tmac/refer.tmac

   1 .\" refer.tmac
   2 .\"
   3 .\" This is an interface to 'refer', originally part of 's.tmac'.
   4 .\"
   5 .\" Copyright (C) 2011-2018 Free Software Foundation, Inc.
   6 .\"   Written by Werner Lemberg (wl@gnu.org)
   7 .\"
   8 .\" This file is part of groff.
   9 .\"
  10 .\" groff is free software; you can redistribute it and/or modify it
  11 .\" under the terms of the GNU General Public License as published by
  12 .\" the Free Software Foundation, either version 3 of the License, or
  13 .\" (at your option) any later version.
  14 .\"
  15 .\" groff is distributed in the hope that it will be useful, but WITHOUT
  16 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  17 .\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
  18 .\" License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public License
  21 .\" along with this program.  If not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\"
  24 .\" Please send comments to groff@gnu.org.
  25 .
  26 .
  27 .\" The following macros must be defined:
  28 .\"
  29 .\"   ref*error                     -- print an error message (in $1)
  30 .\"
  31 .\"   ref*text-label-start          -- start a reference in text
  32 .\"                                    (formatted reference # in $1)
  33 .\"   ref*text-label-end            -- end a reference in text
  34 .\"
  35 .\"   ref*biblio-item-start         -- a reference item with label
  36 .\"                                    (in $1) in the bibliography block
  37 .\"   ref*biblio-item-start-nolabel -- a reference item without label in
  38 .\"                                    the bibliography block
  39 .\"   ref*biblio-item-end           -- end a reference item in the
  40 .\"                                    bibliography block
  41 .\"
  42 .\" The following macros are optional:
  43 .\"
  44 .\"   ref*item-start-hook           -- stuff appended to the ]- macro
  45 .\"   ref*item-end-hook             -- stuff prepended to the ][ macro
  46 .\"   ref*biblio-start-hook         -- stuff appended to the ]< macro
  47 .\"   ref*biblio-end-hook           -- stuff appended to the ]> macro
  48 .\"
  49 .\" The following strings must be defined:
  50 .\"
  51 .\"   ref*refnum-start              -- start reference number formatting
  52 .\"                                    in footnote
  53 .\"   ref*refnum-end                -- end reference number formatting
  54 .\"                                    in footnote
  55 .\"
  56 .\"   [.                            -- start reference number in text
  57 .\"                                    (directly inserted by 'refer')
  58 .\"   .]                            -- end reference number in text
  59 .\"                                    (directly inserted by 'refer')
  60 .\"
  61 .\" Here is the specification of the five possible reference styles
  62 .\" provided by 'refer'.  The example entries are taken from the ms
  63 .\" macro package.
  64 .\"
  65 .\"   ref*spec!0  Q A T S V N P I C D O      -- other
  66 .\"   ref*spec!1  Q A T J S V N P I C D O    -- journal article
  67 .\"   ref*spec!2  Q A T S V P I C D O        -- book
  68 .\"   ref*spec!3  Q A T B E S V P I C D O    -- article within book
  69 .\"   ref*spec!4  Q A T R G P I C D O        -- technical report
  70 .\"
  71 .\" Now the setup for the formatting of reference entries.  The given
  72 .\" example entries for the various strings are taken from the ms macro
  73 .\" package.
  74 .\"
  75 .\" Each string defines five arguments which are passed to a macro, with
  76 .\" the meaning as below.  Please refer to the man page of 'refer' for
  77 .\" more details on the fields.  To allow fine-tuning, two levels are
  78 .\" implemented: For the refer field X and style Y the string
  79 .\" 'ref*spec!X:Y' is looked up.  If it doesn't exist, the string
  80 .\" 'ref*spec!X' is used instead.
  81 .\"
  82 .\"   arg 1  the punctuation character to use to separate this field
  83 .\"          from the previous field
  84 .\"   arg 2  a string to insert after the punctuation character of the
  85 .\"          previous field (normally a space)
  86 .\"   arg 3  a string with which to prefix this field
  87 .\"   arg 4  a string with which to postfix this field
  88 .\"   arg 5  a string to add after the punctuation character supplied
  89 .\"          by the next field
  90 .\"
  91 .\"                  1  2   3        4     5
  92 .\"   ------------------------------------------------------------------
  93 .\"   ref*spec!A     ,  " "                       -- author name
  94 .\"   ref*spec!B     "" " " "in \fI" ""    "\fP"  -- bk title of article
  95 .\"   ref*spec!D     "" " " "("      ")"          -- date of publication
  96 .\"   ref*spec!E     ,  " " "ed. "                -- editor
  97 .\"   ref*spec!G     "" " " "("      ")"          -- US Gov. ordering #
  98 .\"   ref*spec!J     ,  " " "\fI"    ""    "\fP"  -- journal name
  99 .\"   ref*spec!N     "" "(" ""       ")"          -- issue number
 100 .\"   ref*spec!O     .  " "                       -- other information
 101 .\"   ref*spec!P     ,  " " "p.\~"                -- page
 102 .\"   ref*spec!PP    ,  " " "pp.\~"               -- page range
 103 .\"   ref*spec!T     ,  " " "\\*Q"   ""    "\\*U" -- journal title
 104 .\"   ref*spec!T:0   ,  " " "\fI"    ""    "\fP"  -- book title (other)
 105 .\"   ref*spec!T:2   ,  " " "\fI"    ""    "\fP"  -- book title (book)
 106 .\"   ref*spec!V     "" " " "\fB"    "\fR"        -- volume number
 107 .\"
 108 .\"   ref*spec!dflt  ,  " "                       -- all other entries
 109 .
 110 .\" start of reference
 111 .de ]-
 112 .       rm [A [B [C [D [E [G [I [J [N [O [P [Q [R [S [T [V
 113 .       rm ref*string
 114 .       if d ref*item-start-hook \
 115 .               ref*item-start-hook
 116 ..
 117 .
 118 .
 119 .\" end of reference
 120 .de ][
 121 .       if d ref*item-end-hook \
 122 .               ref*item-end-hook
 123 .       ie d ref*spec!\\$1 \
 124 .               ref*build \\$1 \\*[ref*spec!\\$1]
 125 .       el \{\
 126 .               ref*error "unknown reference type '\\$1'"
 127 .               ref*build 0 \\*[ref*spec!0]
 128 .       \}
 129 .       ref*print
 130 .       rm ref*string
 131 .       rm [F
 132 ..
 133 .
 134 .
 135 .\" period before reference
 136 .ds <. .\"
 137 .
 138 .\" period after reference
 139 .ds >. \" empty
 140 .
 141 .\" comma before reference
 142 .ds <, ,\"
 143 .
 144 .\" comma after reference
 145 .ds >, \" empty
 146 .
 147 .
 148 .\" start collected references
 149 .de ]<
 150 .       als ref*print ref*end-print
 151 .       if d ref*biblio-start-hook \
 152 .               ref*biblio-start-hook
 153 ..
 154 .
 155 .
 156 .\" end collected references
 157 .de ]>
 158 .       als ref*print ref*normal-print
 159 .       if d ref*biblio-end-hook \
 160 .               ref*biblio-end-hook
 161 ..
 162 .
 163 .
 164 .de ref*normal-print
 165 .       ie d [F \
 166 .               ref*text-label-start \
 167                   "\\*[ref*refnum-start]\\*([F\\*[ref*refnum-end]"
 168 .       el \
 169 .               ref*text-label-start \&
 170 .       nop \\*[ref*string]
 171 .       ref*text-label-end
 172 ..
 173 .
 174 .
 175 .de ref*end-print
 176 .       ie d [F \
 177 .               ref*biblio-item-start "\\*([F."
 178 .       el \
 179 .               ref*biblio-item-start-nolabel
 180 .       nop \\*[ref*string]
 181 .       ref*biblio-item-end
 182 ..
 183 .
 184 .
 185 .als ref*print ref*normal-print
 186 .
 187 .de ref*build
 188 .       rm ref*string ref*post-punct
 189 .       nr ref*suppress-period 1
 190 .       nr ref*style \\$1
 191 .       shift
 192 .       while \\n[.$] \{\
 193 .               if d [\\$1 \{\
 194 .                       ie d ref*add-\\$1 \
 195 .                               ref*add-\\$1 \\n[ref*style]
 196 .                       el \
 197 .                               ref*add-dflt \\$1 \\n[ref*style]
 198 .               \}
 199 .               shift
 200 .       \}
 201 .       \" now add a final period
 202 .       ie d ref*string \{\
 203 .               if !\\n[ref*suppress-period] \
 204 .                       as ref*string .
 205 .               if d ref*post-punct \{\
 206 .                       as ref*string "\\*[ref*post-punct]
 207 .                       rm ref*post-punct
 208 .               \}
 209 .       \}
 210 .       el \
 211 .               ds ref*string
 212 ..
 213 .
 214 .
 215 .de ref*add-T
 216 .       ie d ref*spec!T:\\$1 \
 217 .               ref*field T \\*[ref*spec!T:\\$1]
 218 .       el \
 219 .               ref*field T \\*[ref*spec!T]
 220 .       if r [T \
 221 .               nr ref*suppress-period \\n([T
 222 ..
 223 .
 224 .de ref*add-P
 225 .       ie \\n([P>0 \{\
 226 .               ie d ref*spec!PP:\\$1 \
 227 .                       ref*field P \\*[ref*spec!PP:\\$1]
 228 .               el \
 229 .                       ref*field P \\*[ref*spec!PP]
 230 .       \}
 231 .       el \{\
 232 .               ie d ref*spec!P:\\$1 \
 233 .                       ref*field P \\*[ref*spec!P:\\$1]
 234 .               el \
 235 .                       ref*field P \\*[ref*spec!P]
 236 .       \}
 237 ..
 238 .
 239 .de ref*add-J
 240 .       ie ref*spec!J:\\$1 \
 241 .               ref*field J \\*[ref*spec!J:\\$1]
 242 .       el \
 243 .               ref*field J \\*[ref*spec!J]
 244 ..
 245 .
 246 .de ref*add-D
 247 .       ie ref*spec!D:\\$1 \
 248 .               ref*field D \\*[ref*spec!D:\\$1]
 249 .       el \
 250 .               ref*field D \\*[ref*spec!D]
 251 ..
 252 .
 253 .de ref*add-E
 254 .       ie ref*spec!E:\\$1 \
 255 .               ref*field E \\*[ref*spec!E:\\$1]
 256 .       el \
 257 .               ref*field E \\*[ref*spec!E]
 258 ..
 259 .
 260 .de ref*add-G
 261 .       ie ref*spec!G:\\$1 \
 262 .               ref*field G \\*[ref*spec!G:\\$1]
 263 .       el \
 264 .               ref*field G \\*[ref*spec!G]
 265 ..
 266 .
 267 .de ref*add-B
 268 .       ie ref*spec!B:\\$1 \
 269 .               ref*field B \\*[ref*spec!B:\\$1]
 270 .       el \
 271 .               ref*field B \\*[ref*spec!B]
 272 ..
 273 .
 274 .de ref*add-O
 275 .       ie ref*spec!O:\\$1 \
 276 .               ref*field O \\*[ref*spec!O:\\$1]
 277 .       el \
 278 .               ref*field O \\*[ref*spec!O]
 279 .       if r [O \
 280 .               nr ref*suppress-period \\n([O
 281 .\" XXX
 282 .\"     el \
 283 .\"             nr ref*suppress-period 1
 284 ..
 285 .
 286 .de ref*add-A
 287 .       ie ref*spec!A:\\$1 \
 288 .               ref*field A \\*[ref*spec!A:\\$1]
 289 .       el \
 290 .               ref*field A \\*[ref*spec!A]
 291 .       if r [A \
 292 .               nr ref*suppress-period \\n([A
 293 ..
 294 .
 295 .de ref*add-V
 296 .       ie ref*spec!V:\\$1 \
 297 .               ref*field V \\*[ref*spec!V:\\$1]
 298 .       el \
 299 .               ref*field V \\*[ref*spec!V]
 300 ..
 301 .
 302 .de ref*add-N
 303 .       ie ref*spec!N:\\$1 \
 304 .               ref*field N \\*[ref*spec!N:\\$1]
 305 .       el \
 306 .               ref*field N \\*[ref*spec!N]
 307 ..
 308 .
 309 .de ref*add-dflt
 310 .       ie ref*spec!dflt:\\$2 \
 311 .               ref*field \\$1 \\*[ref*spec!dflt:\\$2]
 312 .       el \
 313 .               ref*field \\$1 \\*[ref*spec!dflt]
 314 ..
 315 .
 316 .
 317 .\" First argument is the field letter.
 318 .\" Second argument is the punctuation character to use to separate this
 319 .\" field from the previous field.
 320 .\" Third argument is a string to insert after the punctuation character
 321 .\" of the previous field (normally a space).
 322 .\" Fourth argument is a string with which to prefix this field.
 323 .\" Fifth argument is a string with which to postfix this field.
 324 .\" Sixth argument is a string to add after the punctuation character
 325 .\" supplied by the next field.
 326 .de ref*field
 327 .       if d ref*string \{\
 328 .               ie d ref*post-punct \{\
 329 .                       if !\\n[ref*suppress-period] \
 330 .                               as ref*string "\\$2\"
 331 .                       as ref*string "\\*[ref*post-punct]\\$3\"
 332 .                       rm ref*post-punct
 333 .               \}
 334 .               el \
 335 .                       as ref*string "\\$2\\$3\"
 336 .       \}
 337 .       as ref*string "\\$4\\*([\\$1\\$5
 338 .       if \\n[.$]>5 \
 339 .               ds ref*post-punct "\\$6\"
 340 .       nr ref*suppress-period 0
 341 ..
 342 .
 343 .
 344 .\" ====================================================================
 345 .\" Editor settings
 346 .\" ====================================================================
 347 .
 348 .\" Local Variables:
 349 .\" mode: nroff
 350 .\" fill-column: 72
 351 .\" End:
 352 .\" vim: set filetype=groff textwidth=72: