Re: man-intro

[Oliver Corff]

Hi All,

in a follow-up to my last message I just want to give one real-world
example of a very terse manpage, "for the initiated reader only."

Take refer(1).

It starts with

NAME
       refer - preprocess bibliographic references for groff

DESCRIPTION
       This  file  documents  the  GNU  version of refer, which is part
of the
       groff document formatting system.  refer copies the contents 
of  file‐
       name... to the standard output, except that lines between .[ and
.] are
       interpreted as citations, and lines between .R1 and .R2 are
interpreted
       as commands about how citations are to be processed.

This is a bit too terse for the novice user. My suggestion (.\" comments
do not appear in output, as usual):

       This  file  documents  the  GNU  version of refer, which is part
of the
       groff document formatting system. \" introductory positioning of
refer probably mandatory. ok.

       .\" Purpose and usage *concept*, not usage *details*, which are
explained much later in fine granularity
       .\" All in one or two phrases sufficient to present the idea.
       refer picks items from a bibliographic database (see below, USAGE)
       as requested by citations between .[ and .] in the input file,
Processing of these citations is controlled by
       commands enclosed in .R1 and .R2 in the same input file. All
other input lines are
       copied to the standard output.

Terseness is nice, but in the case presented here the first paragraph of
DESCRIPTION in the refer(1) manpage is logically true, though not truly
helpful.

Sometimes a minimal degree of verbosity makes everything clearer.

My background: I have been using computers for a variety of linguistic,
computational linguistic and lexicographical research sind the
mid-1980s, have been familiar with UN*X-like systems since the early
1990s (with fairly limited exposure to other OS families); so I consider
myself not exactly a novice. Yet, it took me quite a number of
experiments and ruminating the contents of the refer manpage until I had
successfully formatted my first article with refer. As an interesting
byline, I have been using the refer database format for many years
before that, but I always preferred to write my own little processor due
to two fundamental difficulties: a) Asian character sets, and b) URLs,
The second issue was solved by Peter Schaffter's mom. Thank you, Peter!
Despite using biblatex for much of my current work, that has its
limitations, as well. I cannot process more than 4,000 to 5,000
references in one bibliography before I encounter "out of memory" errors
with biblatex (sorting the entries is the problem), but refer continues
to work flawlessly, even with huge files. So, I humbly ask you to read
my comment as one made by a practitioner rather than a CS engineer.

Best regards,

Oliver.


On 23/05/2021 10:11, Oliver Corff wrote:
> Well, isn't this a good reason to emphasize the difference between man
> and help?
>
> Not finding "cd" in a man page means that it is a shell internal; this
> could be stated as an explicite reason why it doesn't come with its own
> manpage.
>
> Perhaps a note of caution to the novice reader could be added in
> man-intro by mentioning that a small number of utilities do not come
> with their associated manpage, but require --help for an overview of
> invocation, arguments and parameters, while other "subsystems" (I think
> of TeX and friends) come with their own, extensive documentation.
>
> The last thought that comes into my mind is that, from a novice user's
> point of view, a huge number of man pages are written from the insider's
> perspective. You don't know how to use utility x? The manpage doesn't
> make sense. You *do* know that utility? Manpage gives you all the
> information you ever dreamt of. An introductory statement to the whys
> and hows of a given utility (in ideally one phrase) can be helpful. But
> this is not a *roff topic; just my comment.
>
> Have a nice Sunday and Pentecost,
>
> Oliver.
>
>
> On 5/22/21 11:42 PM, Ulrich Lauther wrote:
> > On Sat, May 22, 2021 at 08:18:41PM +0200, Oliver Corff wrote:
> > > "man cd", on the other hand, opens the bash built-in command *man
> > > page*,
> > > which, at least on my system is a plethora of text to read (and
> > > digest).
> > on my sytem (ubunto mate) "man cd" results in "No manual entry for cd".
> >
> > > Just my 2cents,
> >          ulrich
> --
> Dr. Oliver Corff
> -- China Consultant --
> Wittelsbacherstr. 5A
> D-10707 Berlin
> Tel.: +49-30-8572726-0
> Fax : +49-30-8572726-2
> mailto:oliver.corff@email.de