Fwd: Re: How to use refer macros-agnostic way?

[p . piatrou]

address@hidden wrote ..
> Hi, Peter
> 
> I am glad there is someone who shares my concern about the refer
> documentation because otherwise I would wonder if I really that lasy
> and stupid ... On the other hand, what else should be assumed by a
> documentation creator about the end user? </ sarcasm off >
> 
> By the way, with the user-defined refer macros examples provided
> by Tadziu I could figure out how to use refer without invoking the
> standard macro sets. It turned out to be much simpler than I thought. 
> Thank you, Tadziu!
> 
> What I learned doing this exercise is that
> 1) refer is NOT macros-agnostic as I humbly expected,
> 2) but this is all right,
> 3) my difficulties boil down to the question of refer documentation
> in-adequasy.
> If 3) was not right I would simply not have a pleasure discussing
> the issue with you, guys, because I am just too lasy and ... see above.
> 
> Actually, it is my second attempt to use refer. First time, when it was
> just out of curiosity, I gave up because found it impossible to
> understand how to use refer from the existing super-scarse documentation.
> My second attempt is about an idea to use groff as a documentation
> platform for scientific projects in our Academy of Science. And here, as
> you can imagine, refer becomes indispensible, so I had to break
> through it and did successfully with your help. Thanks again! But!
> This is not a normal way of learning how to work with a software.
> 
> I am not asking for too much (you, Peter, ask for more). Take, for instance, 
> groff_mm(1), which can indeed be called ADEQUATE man page because, with all 
> its conciseness, it gave me enough information to start using the mm macros.
> What was crucial to me, the descriptions of internal strings and registers,
> and also the interaction with mm of the user-defined macros. This is exacly
> what a user needs but does not find in refer(1). Namely, what could be added
> to refer(1):
> 
> 1) descriptions of internal strings like [A, [B, ... and registers 
> generated by refer,
> 2) mention of the citations formatting being taken care of by refer-ms.tmac,
> etc., if one uses the standard macro sets,
> 3) if one does not use the standard macro sets, there should be a brief
> description of how a user is to arrange the .[-, ... macros.
> 
> Maybe a couple of paragraphs, it does not break anything, and should be
> enough as a newbuy's staring point.
> I agree that all this information is already scattered among refer(1),
> refer.tmac and the Lesk's paper. I even agree that the information is kind
> of ample. I am complaining about the way of its presentation, which DOES NOT
> work for an average user. "Formally it is all correct, but in fact it is 
> a derision" ((C) V.I. Lenin).
> 
> Regards,
> Piotr
> 
> Peter Schaffter <address@hidden> wrote ..
> > On Wed, Jan 08, 2020, Tadziu Hoffmann wrote:
> > > In my opinion, the manual page [refer(1)] is perfectly adequate,
> > > if you accept that it is not a tutorial but rather a reference
> > > manual that you refer to for particular details of implementation
> > > or invocation.
> > 
> > The caveat is significant: you must accept that manpages aren't
> > instruction manuals, which term I prefer to "tutorial," which has
> > a whiff of condescension.  They're more like abstracts with cheat
> > sheets.
> > 
> > > In fact, all of the manual pages for troff-related utilities
> > > assume that you're already familiar (at least in very broad
> > > terms) with the basic ideas of how the utilities are meant to be
> > > used.
> > 
> > A classic manpage Catch-22: useful only after you already know what
> > you turned to the manpage to learn.
> > 
> > I disagree that refer(1) is perfectly adequate:
> > 
> >   * there's no mention that the mom macros, which have been part of
> >     groff for close to twenty years, are suitable for use with refer;
> > 
> >   * the wording of the preamble to the list of field identifiers
> >     creates the impression that they are the only ones available;
> > 
> >   * there is no mention that the number of reference types can be
> >     extended beyond the four that are listed;
> > 
> >   * sections dealing with accent strings in bibliographic databases
> >     need to be updated to state first that accented characters
> >     should be entered as named glyphs, reflecting contemporary
> >     usage, and only secondarily that accent strings, if preferred,
> >     should come after the affected character.
> > 
> > I thoroughly sympathise with the OP's frustration with the refer
> > manpage, even if there's nothing to be done about it.  It's complete
> > and accurate, but communicates its substance poorly to all but the
> > initiated.  It would be of enormous help if, at the very least, the
> > SEE ALSO section pointed readers to Lesk's paper so they don't have
> > to plough through the whole manpage only to discover that they're as
> > befuddled and befogged as before, with no clue where to find the
> > kind of helpful information they were seeking.
> > 
> > -- 
> > Peter Schaffter
> > http://www.schaffter.ca