Re: [Groff] Refer and Journals

[Joerg van den Hoff]

On Wed, Mar 14, 2007 at 02:28:15PM -0700, Frank Jahnke wrote:
> I am trying to cast references from refer into the format requested by a
> particular journal.  My old Bell Labs documentation on refer does not
> have much information on the topic, and sadly the man page is nearly
> incomprehensible to me.  Is there a place where better documentation can
yes it is not easy reading, but still...
> be found?
none that I know of.
> 
> What I have to do is largely minor, such as changing the volume from
> bold to italic, eliminating periodical titles, and moving the location
> of the date in the citation string.  The most challenging one is to
> change references with more than four authors to the names of the first
> four, and then et. al.
> 
> This publication does not have many citations, so I could certainly type
> them in manually, but this is a recurring issue.  I would appreciate
> learning how to do it "right."  Your suggestions would be welcomed.

I have not satisfactory solution, but can try to give a few hints
(DISCLAIMER: the nonsense/correct ratio probably is greater than zero):

I presume you use the `ms' macros.

1. 
part of the adjustments have to be done at the preprocessor (`refer') level
this is explained (sort of) in the manpage. it boils usually down to to include
a block

.R1
stuff
.R2

in your document (or better in some header file which is sourced by each of
your documents). here you can enforce sorting (by date, by author, ...) and a
lot more. e.g. I use

.R1
search-truncate 255
accumulate
bracket-label " [" "]" ", "
abbreviate-label-ranges
reverse A
sort A
sort-adjacent-labels
move-punctuation
join-authors " and " ", " ", and "
join-authors " and " ", " ", "
.R2

the explanation for these settings are in the `refer' manpage.


2.
fine tuning requires adjustements to the macros in the `ref'-module of `ms'.
to this end you should copy this module into a separate file (or the file where
the .R1/.R2 block resides), modify it and source it from your document. I never
get around to spending really once and for all sufficient time to understand it
fully, but I enclose a copy of the `ref'-module which includes my comment
blocks, where I have put down my current state of understanding, what's going
on.

and here it comes:

.\"============================================start==============================
.\" ****************************
.\" ******** module ref ********
.\" ****************************
.ig
   this copy is derived from the groff 1.19.3. version of the module.
   it is intended as a template from which to derive customized versions
   which would actually respresent 'style files' to be included in the
   different documents, depending on what kind of reference formatting is
   desired.
   for a start, some comments are inserted to explain the purpose of string
   registers and macros where this has become clear.
   #
   remember, that these macros serve to process the preprocessor (i.e. refer)
   output. part of the 'style' has therefore to be specified at the
   preprocessor level (e.g. sorting, reversal of first and second author name
   etc.). this means, that in general a new 'style' requires fiddling with
   the refer settings as well as with these macros.
   #
   some things seem not possible, e.g. emphasizing (boldify, underline)
   a single author. to achieve this one has to fiddle with the prepocessor 
   output first (inserting formatting directives at this stage).
..
.\" Refer support.
.ig
   refer output of a single reference looks for example like this:
   .\"^A2005L
   .ds [F 37                  \"enumeration
   .]-                       \"initialiasation
   .ds [A van\~den\~Hoff, J
   .ds [D 2005 Dec
   .ds [J Amino Acids
   .ds [K PAPER
   .ds [L Hoff2005a
   .ds [N 29(4)
   .ds [P 341-53
   .nr [P 1
   .ds [T Principles of quantitative positron emission tomography
   .nr [T 0
   .nr [A 0
   .][ 1 journal-article
   .]>
   the purpose of the `ref' macros is to give definitions for
   the `.]-' and `][' marcros and to format the reference from the
   given string register content
..
.de ]-
.rm [A [B [C [D [E [G [I [J [N [O [P [Q [R [S [T [V
.rm ref*string
..
.ig
   the following string registers (ref*spec!0-4) specify the order of 
appearance of the
   different fields contributing to the final reference. therefore, _this_
   is the place to define a new style in terms of arrangement of the different 
   fields.
..
.\" Other
.ds ref*spec!0 Q A T1 S V N P I C D O
.\" Journal article
.ds ref*spec!1 Q A T2 J S V N P I C D O
.\" Book
.ds ref*spec!2 Q A T1 S V P I C D O
.\" Article within book
.ds ref*spec!3 Q A T2 B E S V P I C D O
.\" Tech report
.ds ref*spec!4 Q A T2 R G P I C D O
.\"
.\" ][ type
.ig
   this macro constructs the
   formatted reference by calling `ref*build'
   and initiates print-out of the reference
   by calling `ref*print'. actually while in a
   block of accumulated references, `ref*end-print'
   is called (aliased).
   the refer preprocessor generates a call of the kind
   .][ 1 journal-article
   apparently only the number code of the
   reference type (1 in the example) is used in the 
   definition below
..
.de ][
.if r [T \{\
.       als [T1 [T
.       als [T2 [T
.\}
.ie d ref*spec!\\$1 .ref*build \\*[ref*spec!\\$1]
.el \{\
.       @error unknown reference type `\\$1'
.       ref*build \\*[ref*spec!0]  \" ... and therefore formatted as 'other'
.\}
.ref*print
.rm ref*string
.rm [F [T1 [T2
..
.\" start of reference number
.ds [. address@hidden
.\" end of reference number
.ds .] address@hidden
.\" period before reference
.ds <. .
.\" period after reference
.ds >. \" empty
.\" comma before reference
.ds <, ,
.\" comma after reference
.ds >, \" empty
.\" start collected references
.de ]<
.als ref*print ref*end-print
.SH
\&\\*[REFERENCES]
address@hidden
..
.\" end collected references
.de ]>
address@hidden
.als ref*print ref*normal-print
..
.de ref*normal-print
.ie d [F .FS "\\*([.\\*([F\\*(.]"
.el .FS \&
\\*[ref*string]
.FE
..
.ig
   the 'real' printing is done here, by emitting
   `ref\*string' in a new `XP' paragraph:
..
.de ref*end-print
.ie d [F .IP "\\*([F."
.el .XP
\\*[ref*string]
..
.als ref*print ref*normal-print
.ig 
   here, the formatted reference is constructed and resides, finally in the
   string `ref*string'.
   `ref*build' is called with the field arguments defined by one of
   the `ref*string!0-4' string registers. the while loop cycles over these
   fields and concatenates the fields including the formatting information
   in the `ref*add-[A-Z]' macros.
..
.de ref*build
.rm ref*string ref*post-punct
.nr ref*suppress-period 1
.while \\n[.$] \{\
.       if d [\\$1 \{\
.               ie d ref*add-\\$1 .ref*add-\\$1
.               el .ref*add-dflt \\$1
.       \}
.       shift
.\}
.\" now add a final period
.ie d ref*string \{\
.       if !\\n[ref*suppress-period] .as ref*string .
.       if d ref*post-punct \{\
.               as ref*string "\\*[ref*post-punct]
.               rm ref*post-punct
.       \}
.\}
.el .ds ref*string
..
.ig
   below are the definitions of how to handle the individual fields in the 
reference.
   especially, the wrapping by commas, periods, paranthesis etc. is defined 
here.
   see the trailing comment below for the meaning of each argument to these 
macros.
   this, therefore, is the place to adjust the details of interpunctation, 
paranthesis
   and(!) emphasis (bold, italic, underling). remember that capitalisation, on 
the 
   other hand is handled by `refer'.
   most things are handled by the single macro `ref*field' defined after the
   `ref*add' macros.
..
.de ref*add-T1
.ref*field T , "\fI" "" "\fP"
.if r [T .nr ref*suppress-period \\n([T
..
.de ref*add-T2
.ref*field T , "\\*Q" "" "\\*U"
.if r [T .nr ref*suppress-period \\n([T
..
.de ref*add-P
.ie \\n([P>0 .ref*field P , "pp. "
.el .ref*field P , "p. "
..
.de ref*add-J
.ref*field J , \fI "" \fP
..
.de ref*add-D
.ref*field D "" ( )
..
.de ref*add-E
.ref*field E , "ed. "
..
.de ref*add-G
.ref*field G "" ( )
..
.de ref*add-B
.ref*field B "" "in \fI" "" \fP
..
.de ref*add-O
.ref*field O .
.ie r [O .nr ref*suppress-period \\n([O
.el .nr ref*suppress-period 1
..
.de ref*add-A
.ref*field A ,
.if r [A .nr ref*suppress-period \\n([A
..
.de ref*add-V
.ref*field V "" \fB \fR
..
.de ref*add-N
.ref*field N \z( "" ")"
..
.de ref*add-dflt
.ref*field \\$1 ,
..
.\" First argument is the field letter.
.\" Second argument is the punctuation character to use to separate this field
.\" from the previous field.
.\" Third argument is a string with which to prefix this field.
.\" Fourth argument is a string with which to postfix this field.
.\" Fifth argument is a string to add after the punctuation character supplied
.\" by the next field.
.de ref*field
.if d ref*string \{\
.       ie d ref*post-punct \{\
.               as ref*string "\\$2\\*[ref*post-punct] \"
.               rm ref*post-punct
.       \}
.       el .as ref*string "\\$2 \"
.\}
.as ref*string "\\$3\\*([\\$1\\$4
.if \\n[.$]>4 .ds ref*post-punct "\\$5
.nr ref*suppress-period 0
..
.\"============================================end==============================

for instance the above includes the line

.ref*field N \z( "" ")"

which tadziu was refering to in one of the last mails to the list.

probably the best way is to play around with the definitions in this file and
than look at the output you get.
as you can see, the `ref' module defines macros which process the `refer' output
which, e.g. looks like

   .ds [F 37                  \"enumeration
   .]-                       \"initialiasation
   .ds [A van\~den\~Hoff, J
   .ds [D 2005 Dec
   .ds [J Amino Acids
   .ds [K PAPER
   .ds [L Hoff2005a
   .ds [N 29(4)
   .ds [P 341-53
   .nr [P 1
   .ds [T Principles of quantitative positron emission tomography
   .nr [T 0
   .nr [A 0
   .][ 1 journal-article
   .]>

some things (such as setting the principal author in bold, the others in normal
type) seem not to be adjustable at all (neither via `refer' nor via the `ref'
module). the only resort I see here is to adjust the refer output manually or
with a script (e.g. at one point I included the above blocks via a script in
.KS/.KE blocks to prevent splitting of references across pages).

to summarize:

1. adjust the refer settings
2. adjust the `ref' module definitions
3. if  necessary, fiddle with the refer output prior to formatting

if someone knows of better ways, I'd like to learn of them, of course.

hth

joerg