Re: Future of groff Texinfo manual (was: documentation of hyphenation)

[G. Branden Robinson]

At 2020-06-30T04:18:00+1000, John Gardner wrote:
> Groff *can* generate high-quality manuals, it *can* generate HTML
> output, and it *can* generate indexes — AFAIK, the only thing it
> *can't* do that Texinfo can is compile binary `.info` files. But even
> that could be achieved by adding a new postprocessor for Info output.

That is a fascinating idea I had never considered before.

> It just feels weird for a document formatting system to have its own
> documentation generated by a completely different document formatting
> system…

Yes, but while I'm passionate about many things (ask Dave Kemper to
characterize my views on inter-sentence spacing :P ), burying Texinfo is
not one of them.

At 2020-06-29T20:36:31+0200, Ingo Schwarze wrote:
> > Chapter 5 (gtroff [sic] Reference): Retain. [2]
> 
> Yes.  Basically, i think this *is* the groff manual.  I find the
> internal organization of this chapter extremely weird and confusing.
> It is one big mish-mash of requests, escape sequences, registers
> and other syntax elements, nothing appears to be sorted in any way
> that makes sense to me.

What it is attempting to do is organize things conceptually, not by
syntactical category.  So the big commit I pushed the other day was all
in a single Texinfo node (or chapter section in the printed manual,
which is where I do my proofreading).

Where I think our Texinfo manual needs development is in conceptual
introductions and linking material between nodes, possibly with some
tweaks to the order in which topics are presented (I have nothing
concrete in mind at this point--such a thing would arise from
undertaking a revision and finding it difficult to discuss a subject
without excessive forward references).

> But the weird ordering is very easy to ignore thanks to the excellent
> appendices.  In 95% of the cases that i'm using the groff manual, i
> start from one of the appendices which directs me to the appropriate
> place in chapter 5.

Yes.  The wealth of indices in our Texinfo manual is a big plus.  Ted
and/or Werner were militant about getting topics into the conceptual
index and thereby made it immensely valuable.

> The *content* of chapter 5 is of outstanding quality.  I'm using
> it very frequently and i don't remember finding a single error in
> it (i think i would remeber because it would have forced me to
> prepare a patch to an info file, which would have been an extremely
> unusual task for me...  then again, sometimes i do forget things).

I found one or two small ones this year; you and I even discussed one of
them (.ps 0). ;-)

But, yes, I agree.

[the ms node in our Texinfo manual]
>  * Merge it into groff_ms(7).
>    That's the natural place for this material.
>    (If someone is willing to do the work.)

ms is a more capable language than man; two huge benefits to documenting
a system in itself are dogfooding and presentation of examples.  That's
why I've been hammering on our man pages for years; I want people to
write good man pages everywhere and I found it is distressing that the
quality of groff's was so variable.

>    Do not frame it as an example.  I think telling people to document
>    future macro packages in TeXinfo format would be really bad
>    advice.

I was referring more to the content rather than the input format, but
the point is well-taken.

I'll skip a few points where I don't feel I can add to others' replies.

> I never saw the point of groff_diff(7).

Well, CSTR #54 is a great document but it isn't Free Software.  It
couldn't be distributed with groff.  However, it was widely available
gratis (and probably more so today), so one could reasonably expect
users to be able to lay their hands on it.

Another observation I have is that the Unix Manual Volume 2 documents
(the whitepapers, not the man pages) are much easier to learn from GNU
manuals.

Sometimes this is only because the quality of writing is higher in the
Unix manuals (but not always), but I think the main factor is that the
underlying systems are smaller, simpler, and easier to get into the
head.

I've had this experience repeatedly--make and m4 spring immediately to
mind.  My experiences with the GNU manuals for those was that they
rapidly went into comprehensive encyclopedia mode, which is great for
someone already conversant with the system but bewildering to someone
who needs to see the broad strokes first.

GNU manuals could solve this problem through progressive refinement of
the system, and our Texinfo manual goes some way down this road.

> At first, i assumed it was written because the groff team had no time
> to write their own, complete manual and instead chose to only document
> what they changed.  (I'm not sure that actually was the reason, it's
> merely what i thought when i first saw it.)  Whatever the reason, it's
> quite bad for usablity.  If you want to look up anything, you typically
> need two documents in different formats: groff_diff(7) and an older
> Unix Roff manual.  You first need to look into groff_diff(7), find
> something there that assumes previous understanding of the feature
> in Unix Roff, so you have to go to the other manual, then come back.
> 
> I think groff_diff(7) has long become obsolete by chapter 5 of the
> info manual.  It could probably just be deleted, after checking that
> everything groff_diff(7) says is covered in chapter 5 of the info
> manual.
> 
> One reason for getting rid of groff_diff(7) is that it does seem
> to cause significant maintenance effort.  If regularly see commits
> changing it.

I think those commits come from me.  :)

It wasn't too long ago that I noticed that the language in our Texinfo
manual and groff_diff(7) is often exactly parallel.  This wasn't my
doing; the pattern was already established.

Killing off groff_diff(7) is too radical for me to personally endorse at
this point.  I don't mind keeping it in sync with our Texinfo manual
when I change one or the other.  The effort of translating the markup
syntax is minor compared to wordsmithing, experimenting, and
source-diving I often have to do to alter the text in the first place.

groff(7) is an approximation of CSTR #54.  It's table-driven and
comprehensive but terse (ideally).

groff_diff(7) is comprehensive with respect to groff innovations and
includes examples, but presumes a strong knowledge of traditional roff.

Our Texinfo manual is comprehensive, period, and ideally, will take
someone from a rube existence at the Unix command line with no knowledge
of typesetting and have them writing their own personal macro packages
by the time they're done with it.  But it is not short.

> > I think if we altered the groff Texinfo manual as above, a worthwhile
> > book could be prepared in the classic "tutorial and reference" pattern.
> > The first part would be the groff texinfo manual, and the second part
> > would be a dump of the man pages.
> 
> That doesn't quite fit because chapter 5 of the info manual is an
> excellent reference manual (i'm quite willing to call it excellent
> even with the weird ordering).

It is.  I just think it could be more (maybe in chapter 5, maybe in an
earlier chapter).  For instance, see the conversation I had with Tadziu
last month about diversions.  Our Texinfo manual is an ideal place to
teach someone how to mentally model the way groff operates so that they
know where a partial output line is collected, what environment it is
associated with and what sorts of input it to one diversion or another
(since, as I poorly understand it, technically there is a "default
diversion" that is where your output goes if when you're not using a
diversion).

Chapter 5 could still benefit from what I called bridging material
above, I think.  I'd appreciate knowing if you think the fairly sweeping
changes I made to the "Manipulating Hyphenation" node/section constitute
a worsening of the manual's quality for your purposes.

In hindsight I suppose I undertook that experiment on a section you were
unlikely to care much about--if I recall correctly, mandoc does not
concern itself with hyphenation at all.  :D

> Let's just admit the real reasons:  We have substantial amounts of
> text in both formats and don't see sufficient value in changing the
> format in either direction, don't have the time, and besides the
> FSF vetoes one of the directions.

The first several factors may be more important than the last.

> Overall, your plan sounds very reasonable to me.

Thanks!

At 2020-06-29T16:04:15-0400, T. Kurt Bond wrote:
> As for the ms info node, I agree it would be good to integrate the
> information from that into the groff_ms(7) man page.  (I don't see
> something like the info section "General structure of an `ms'
> document" in groff_ms(7), for instance; this was in "Using groff with
> the -ms Macro Package" by Larry Kollar, but that document may have
> been superseded; I can only find a PDF version of it on the net at
> https://www.mail-archive.com/ion-general@lists.berlios.de/msg01838/ms.pdf ).
> If that happens and the ms info node is removed, it should be at least
> replaced with a pointer to the man pages like most of the macro
> packages mentioned.

Hmm!  It seems the ms stuff in our Texinfo manual may have started life
as an ms document after all.

IIRC, Larry Kollar is sometimes seen on this list.  Maybe he'd be
willing to share a copy of the ms sources so we don't have to backport
it from Texinfo format...?

Regards,
Branden

signature.asc
Description: PGP signature