tmac/refer.tmac

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