[groff] 06/14: refer(1): Revise for intelligibility.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a4b08b972ec101c78f57de596350d7234e460791
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Aug 31 18:36:39 2023 -0500

    refer(1): Revise for intelligibility.
    
    Content:
    * Move discussion of `lf` handling to the first description paragraph,
      which is concerned with the nuts and bolts of general input
      transformation.  This gets it out of the way so we can discuss the
      particulars of _refer_ concepts with less interruption later.
    * Properly introduce and consistently use terminology (in the 2/9ths of
      the document thus far revised): "citation", "bibliographic record",
      "mark", "label", "bracket", "accumulate".
    * Supply examples of marks to concretize the discussion.
    * Motivate the presence of bibliographic records.
    * Discuss database usage and purpose of indxbib(1), lookbib(1), and
      lkbib(1) commands.  Observe that their use is wholly optional.
    * Add cross references between title-related field names, since there
      are three, for varying purposes.
    * Update description of bibliographic record fields based on
      observations of real-world examples and Tuthill 1983.
    * Cite Tuthill 1983 in "See also" section.  Guess I'm not the first
      person to notice that CSTR #69 is a difficult resource from which to
      acquire refer(1) competence.  I wonder if this is an example of
      journal referees being more receptive to discussions of performance
      than substantial advances in the ergonomics of producing bibliographic
      citations.  Perhaps the referees had mastered the production of
      such things by hand and resented the impeding obsolescence of their
      skill.  Whatever the reason, whoever decided that the speed advantages
      of indexed databases[1] over full-text searches should dominate the
      paper served future generations poorly.
    
    Style:
    * Use active voice more.
    * Tighten wording.
    * Use stem form for tagged paragraphs describing record fields.
    * Prefer present tense to future tense when describing command behavior.
    
    Markup:
    * Migrate from `LP` macro to `P`.
    * Employ poor man's keep to make pagination more attractive.
    
    [1] This cannot possibly have been a novel insight in 1978.[2]
    [2] Perhaps I should read more C. J. Date before shooting my mouth off.
---
 src/preproc/refer/refer.1.man | 436 ++++++++++++++++++++++++------------------
 1 file changed, 246 insertions(+), 190 deletions(-)

diff --git a/src/preproc/refer/refer.1.man b/src/preproc/refer/refer.1.man
index 49b12c1dc..1a522babe 100644
--- a/src/preproc/refer/refer.1.man
+++ b/src/preproc/refer/refer.1.man
@@ -8,7 +8,7 @@
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -118,7 +118,9 @@ except that it interprets lines between
 .B .[
 and
 .B .]\&
-as citations to be translated into
+as
+.I citations
+to be translated into
 .I groff
 input,
 and lines between
@@ -127,6 +129,13 @@ and
 .B .R2
 as instructions regarding how citations are to be processed.
 .
+.I @g@refer
+interprets and generates
+.I roff
+.B lf
+requests so that file names and line numbers in messages produced by
+commands that read its output correctly describe the source document.
+.
 Normally,
 .I @g@refer
 is not executed directly by the user,
@@ -142,67 +151,78 @@ or if
 .I file
 is
 .RB \[lq] \- \[rq],
-the standard input stream is read.
+.I @g@refer
+reads the standard input stream.
 .
 .
 .LP
-Each citation specifies a reference.
+A citation identifies a work by reference to a
+.I "bibliographic record"
+detailing it.
 .
-The citation can specify a reference that is contained in a
-bibliographic database by giving a set of keywords that only that
-reference contains.
+Select a work from a database of records by listing keywords that
+uniquely identify it.
 .
-Alternatively it can specify a reference by supplying a database record
-in the citation.
+Alternatively,
+a document can specify a record for the work at the point its citation
+occurs.
 .
-A combination of these alternatives is also possible.
+A document can use either or both strategies as desired.
 .
 .
-.LP
+.P
 For each citation,
 .I @g@refer
-can produce a mark in the text.
+produces a
+.I mark
+in the text,
+like a superscripted footnote number or \[lq][Lesk1978a]\[rq].
 .
-This mark consists of some label which can be separated from the text
-and from other labels in various ways.
+A mark consists of a
+.I label
+between
+.I brackets.
 .
-For each reference it also outputs
-.MR groff @MAN7EXT@
-language commands that can be used by a macro package to produce a
-formatted reference for each citation.
+The mark can be separated from surrounding text
+and from other labels in various ways.
 .
-The output of
 .I @g@refer
-must therefore be processed using a suitable macro package,
+produces
+.I roff
+language requests usable by a document or a macro package
 such as
 .\" .IR man ,
 .IR me ,
 .IR mm ,
 .IR mom ,
 or
-.IR ms .
+.I ms
+to produce a formatted reference for each citation.
 .
-The commands to format a citation's reference can be output immediately
-after the citation,
-or the references may be accumulated,
-and the commands output at some later point.
+A citation's reference can be output immediately after it occurs
+(as with footnotes),
+or references may
+.IR accumulate ,
+with corresponding output appearing later in the document
+(as with endnotes).
 .
-If the references are accumulated,
-then multiple citations of the same reference will produce a single
-formatted reference.
+When references accumulate,
+multiple citations of the same reference produce a single formatted
+entry.
 .
 .
 .LP
-The interpretation of lines between
+Interpretation of lines between
 .B .R1
 and
 .B .R2
-as prepreocessor commands is a feature of GNU
-.IR \%refer . \" GNU
+tokens as prepreocessor commands is a GNU
+.I \%refer \" GNU
+extension.
 .
-Documents making use of this feature can still be processed by AT&T
+Documents employing this feature can still be processed by AT&T
 .I \%refer \" AT&T
-just by adding the lines
+by adding the lines
 .
 .RS
 .EX
@@ -214,76 +234,96 @@ just by adding the lines
 .
 to the beginning of the document.
 .
-This will cause
-.MR @g@troff @MAN1EXT@
+The foregoing input causes
+.I troff \" generic
 to ignore everything between
 .B .R1
 and
 .BR .R2 .
 .
-The effect of some commands can also be achieved by options.
-.
-These options are supported mainly for compatibility with AT&T
+The effects of some
+.I \%refer \" generic
+commands can be achieved by command-line options;
+these are supported for compatibility with AT&T
 .IR \%refer . \" AT&T
 .
 It is usually more convenient to use commands.
 .
 .
-.LP
-.I @g@refer
-generates
-.B .lf
-requests so that file names and line numbers in messages produced by
-commands that read
-.I @g@refer
-output will be correct;
-it also interprets lines beginning with
-.B .lf
-so that file names and line numbers in the messages and
-.B .lf
-lines that it produces will be accurate even if the input has been
-preprocessed by a command such as
-.MR @g@soelim @MAN1EXT@ .
-.
-.
 .\" ====================================================================
-.SS "Bibliographic databases"
+.SS "Bibliographic records"
 .\" ====================================================================
 .
-The bibliographic database is a text file consisting of records
-separated by one or more blank lines.
+A bibliographic record describes a referenced work in sufficient detail
+that it may be cited to accepted standards of scholarly and professional
+clarity.
 .
-Within each record fields start with a
-.B %
-at the beginning of a line.
+The record format permits annotation and extension that a document may
+use or ignore.
 .
-Each field has a one character name that immediately follows the
-.BR % .
-It is best to use only upper and lower case letters for the names
-of fields.
+A record is a plain text sequence of
+.I fields,
+one per line,
+each consisting of a percent sign
+.BR % ,
+an alphanumeric character classifying it,
+one space,
+and its contents.
 .
-The name of the field should be followed by exactly one space,
-and then by the contents of the field.
+If a field's contents are empty,
+the field is ignored.
 .
-Empty fields are ignored.
 .
-The conventional meaning of each field is as follows:
+.P
+Frequently,
+such records are organized into a
+.I "bibliographic database,"
+with each entry separated by blank lines or file boundaries.
 .
+This practice relieves documents of the need to maintain bibliographic
+data themselves.
 .
-.TP
+The programs
+.MR @g@lookbib @MAN1EXT@
+and
+.MR lkbib @MAN1EXT@
+consult a bibliographic database,
+and
+.MR @g@indxbib @MAN1EXT@
+indexes one to speed retrieval from it,
+reducing document processing time.
+.
+Use of these tools is optional.
+.
+.
+.br
+.ne 4v
+.P
+The conventional uses of the bibliographic field entries are as
+follows.
+.
+Within a record,
+fields other than
 .B %A
-The name of an author.
+and
+.B %E
+replace previous occurrences thereof.
 .
-If the name contains a suffix such as \[lq]Jr.\&\[rq],
-it should be separated from the last name by a comma.
 .
-There can be multiple occurrences of the
+.TP
 .B %A
-field.
+names an author.
+.
+If the name contains a suffix such as \[lq]Jr.\&\[rq]
+or \[lq]III\[rq],
+it should be separated from the surname by a comma.
 .
-The order is significant.
+An entry may contain multiple
+.B %A
+fields;
+order is significant.
 .
-It is a good idea always to supply an
+We recommend always supplying an
 .B %A
 field or a
 .B %Q
@@ -292,174 +332,183 @@ field.
 .
 .TP
 .B %B
-For an article that is part of a book,
-the title of the book.
+records the title of the book within which a cited article
+is collected.
+.
+See
+.B %J
+and
+.BR %T .
 .
 .
 .TP
 .B %C
-The place (city) of publication.
+names the city or other place of publication.
 .
 .
 .TP
 .B %D
-The date of publication.
+indicates the date of publication.
 .
-The year should be specified in full.
+Specify the year in full.
+.\" even if the title of the conference proceedings abbreviates it
 .
 If the month is specified,
-the name rather than the number of the month should be used,
-but only the first three letters are required.
+use its name rather than its number;
+only the first three letters are required.
 .
-It is a good idea always to supply a
+We recommend always supplying a
 .B %D
 field;
 if the date is unknown,
-a value such as
-.B in press
+use
+.RB \[lq] "in press" \[rq]
 or
-.B unknown
-can be used.
+.RB \[lq] unknown \[rq]
+as its contents.
 .
 .
 .TP
 .B %E
-For an article that is part of a book,
-the name of an editor of the book.
+names an editor of the book within which a cited article is collected.
 .
-Where the work has editors and no authors,
-the names of the editors should be given as
+Where a work has editors but no authors,
+name the editors in
 .B %A
-fields and
+fields and append
 .RB \[lq] ,\~(ed.)\& \[rq]
 or
 .RB \[lq] ,\~(eds.)\& \[rq]
-should be appended to the last author.
+to the last of these.
 .
 .
 .TP
 .B %G
-U.S. government ordering number.
+records the U.S.\& government ordering number,
+ISBN,
+DOI,
+or other unique identifier.
 .
 .
 .TP
 .B %I
-The publisher (issuer).
+names the publisher (issuer).
 .
 .
 .TP
 .B %J
-For an article in a journal,
-the name of the journal.
+records the title of the journal within which a cited article is
+collected.
+.
+See
+.B %B
+and
+.BR %T .
 .
 .
 .TP
 .B %K
-Keywords to be used for searching.
+lists keywords intended to aid searches.
 .
 .
 .TP
 .B %L
-Label.
+is a label;
+typically unused in database entries,
+it can override the label format otherwise determined.
 .
 .
 .TP
 .B %N
-Journal issue number.
+records the issue number of the journal within which a cited article
+is collected.
 .
 .
 .TP
 .B %O
-Other information.
-.
-This is usually printed at the end of the reference.
+presents additional (\[lq]other\[rq]) information,
+typically placed at the end of the reference.
 .
 .
 .TP
 .B %P
-Page number.
+lists the page numbers of a cited work that is part of a larger
+collection.
 .
-A range of pages can be specified as
+Specify a range with
 .IB m \- \c
 .IR n .
+.\" XXX: Why not \[en]?  Does that break?
 .
 .
 .TP
 .B %Q
-The name of the author,
-if the author is not a person.
-.
-This will only be used if there are no
+names an institutional author when no
 .B %A
-fields.
+fields are present.
 .
-There can only be one
+Only one
 .B %Q
-field.
+field is permitted.
 .
 .
 .TP
 .B %R
-Technical report number.
+is an identifier for a report,
+thesis,
+memorandum,
+or other unpublished work.
 .
 .
 .TP
 .B %S
-Series name.
+records the title of a series to which the cited work belongs.
 .
 .
 .TP
 .B %T
-Title.
+is the work's title.
 .
-For an article in a book or journal,
-this should be the title of the article.
+See
+.B %B
+and
+.BR %J .
 .
 .
 .TP
 .B %V
-Volume number of the journal or book.
+is the volume number of the journal or book containing the cited work.
 .
 .
 .TP
 .B %X
-Annotation.
-.
+is an annotation.
 .
-.LP
-For all fields except
-.B %A
-and
-.BR %E ,
-if there is more than one occurrence of a particular field in a record,
-only the last such field will be used.
+By convention,
+it is not formatted in the citing document.
 .
 .
 .P
-If accent strings are used,
-they should follow the character to be accented.
-.
-This means that an
+If the obsolescent \[lq]accent strings\[rq] feature of the
+.I ms
+or
+.I me
+macro packages is used,
+such strings should follow the character to be accented;
+an
 .I ms
 document must call the
-.B .AM
-macro when it initializes.
+.B AM
+macro before using them.
 .
-Accent strings should not be quoted:
+Do not quote accent strings:
 use one
 .B \e
 rather than two.
 .
-Accent strings are an obsolescent feature of the
-.I me
-and
-.I ms
-macro packages;
-modern documents should use
-.I groff
-special character escape sequences instead;
-see
-.MR groff_char @MAN7EXT@ .
+See
+.MR groff_char @MAN7EXT@
+for a modern approach to the problem of diacritics.
 .
 .
 .\" ====================================================================
@@ -471,89 +520,87 @@ Citations have a characteristic format.
 .RS
 .EX
 .BI .[ opening-text
-.I flags keywords
-.I fields
+.IR "flags keyword\~" .\|.\|.
+.I field
+\&.\|.\|.
 .BI .] closing-text
 .EE
 .RE
 .
 .
-.LP
-The
+.P
 .IR opening-text ,
 .IR closing-text ,
 and
 .I flags
-components are optional.
+are optional,
+and only one
+.I keyword
+or
+.I field
+need be specified.
 .
-Only one of the
+The set of
 .I keywords
-and
-.I fields
-components need be specified.
+searches the bibliographic database(s) for a reference containing
+all such terms.
 .
-.
-.LP
-The
+If more than one reference matches,
+that is an error;
+specify further
 .I keywords
-component says to search the bibliographic databases for a reference
-that contains all the words in
-.IR keywords .
+to disambiguate the reference.
 .
-It is an error if more than one reference is found.
-.
-.
-.LP
 The
 .I fields
-components specifies additional fields to replace or supplement those
+specify additional bibliographic data to replace or supplement those
 specified in the reference.
 .
-When references are being accumulated and the
+When references are accumulating and
 .I keywords
-component is non-empty,
-then additional fields should be specified only on the first occasion
-that a particular reference is cited,
-and will apply to all citations of that reference.
+are present,
+additional
+.I fields
+should be specified only on the first citation of a particular
+reference;
+they will apply to all citations of that reference.
 .
 .
 .br
 .ne 2v
-.LP
-The
+.P
 .I opening-text
 and
 .I closing-text
-components specify strings to be used to bracket the label instead of
-those in the
+specify strings to be used to bracket the label instead of those in the
 .B \%bracket\-label
 command.
 .
-If either of these components is non-empty,
+Leading and trailing spaces are significant.
+.
+If either of these is non-empty,
 the strings specified in the
 .B \%bracket\-label
 command will not be used;
-this behavior can be altered using the
+alter this behavior with the
 .B [
 and
 .B ]
-flags.
-.
-Leading and trailing spaces are significant for these components.
+.I flags.
 .
 .
-.LP
-The
+.P
 .I flags
-component is a list of non-alphanumeric characters each of which
-modifies the treatment of this particular citation.
+is a list of non-alphanumeric characters each of which modifies the
+treatment of this particular citation.
 .
 AT&T
 .I \%refer \" AT&T
-will treat these flags as part of the keywords and so will ignore them
-since they are non-alphanumeric.
+treats these flags as
+.I keywords,
+but ignores them since they are non-alphanumeric.
 .
-The following flags are currently recognized.
+The following flags are recognized.
 .
 .
 .TP
@@ -1158,8 +1205,8 @@ label expression.
 In the text,
 move any punctuation at the end of line past the label.
 .
-It is usually a good idea to give this command unless you are using
-superscripted numbers as labels.
+We recommend employing this command unless you are using superscripted
+numbers as labels.
 .
 .
 .TP
@@ -1992,13 +2039,22 @@ our non-bibliographic aside.
 .SH "See also"
 .\" ====================================================================
 .
+\[lq]Refer \[em] A Bibliography System\[rq],
+by Bill Tuthill,
+1983, \" 4.2BSD, /usr/doc/refer/refer.bib
+Computing Services,
+University of California,
+Berkeley.
+.
+.
+.P
 \[lq]Some Applications of Inverted Indexes on the Unix System\[rq],
 by M.\& E.\& Lesk,
 1978,
 AT&T Bell Laboratories Computing Science Technical Report No.\& 69.
 .
 .
-.LP
+.P
 .MR @g@indxbib @MAN1EXT@ ,
 .MR @g@lookbib @MAN1EXT@ ,
 .MR lkbib @MAN1EXT@