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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Tue, Jun 30, 2020 at 03:08:04AM +1000:

> == PROPOSAL ==
> 
> Chapter 1 (Introduction): Retain.
> Chapter 2 (Invoking groff): Drop; direct users to groff(1).
> Chapter 3 (Tutorial for Macro Users): Retain.
> Chapter 4 (Macro Packages): Drop. (See [1] below.)
> Chapter 6 (Preprocessors): Drop.
> Chapter 7 (Output Devices): Drop.
> Chapter 8 (File Formats): Retain. [3]
> Chapter 9 (Installation): Drop.

I don't remember ever looking into any of these parts and i can't think
of a plausible reason why i ever might.  So from my perspective, do with
them whatever you like.

> 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.  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.

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).

> [1] The only painful part of this is losing Larry Kollar's ms node,
> which is the _only_ macro package that has ever documented well in
> Texinfo as far as I can tell.  I think it would be pretty elegant to
> port this material to an ms document, ship it with the groff
> distribution, and point people to it.  Alternatively, the chapter could
> be reframed as an example of how to document a macro package, discarding
> its current pretentions to comprehensiveness.

I don't feel strongly about this either way.  I mean, -ms it not
exactly the most relevant macro package in 2020, or is it?

I would be OK with either of the following solutions:

 * Merge it into groff_ms(7).
   That's the natural place for this material.
   (If someone is willing to do the work.)

 * If you think it has value as duplicate document, just keep it
   as it is.  In a printed book, the editor may rightly complain
   about a chapter that doesn't fully fit the overall concept of
   the book.  In a purely online book, i see nothing wrong with
   just keeping such a chapter, if it has intrinsic value, without
   making up an excuse like "this is an example".  If you feel you
   must present an excuse, say somethin like "Normally, groff macro
   pages are documented in manual pages.  But we already had this
   chapter and it feels useful to us, so enjoy."

   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 like the idea of converting it to -ms somewhat less.  I mean, we
have groff documentation split out into info(1), man(1), and HTML
(for mom) - do we really need a fourth format?  Also, what is the
point?  As far as i understand, you say Larry did a good job with
it.  So why change it to a different format, unless to the format
used for all other macro sets (for unification)?

As far as i understand, -ms is totally static nowadays and neither
the code nor the documentation receives any development or needs any
practically relevant amount of maintenance.  So just leaving it alone
would feel quite natural to me.

> [2] Keep in sync with groff_diff(7) for groff innovations and groff(7)
> for quick references and topical summaries.

I never saw the point of groff_diff(7).

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.

"What is the difference between groff and traditional roff with
respect to this feature?" is not a question users often need to
ask.  For me as an implementer, the question did come up fairly
frequently.  All the same, i found it much easier to compare the
excellent groff manual (section 5) to the fairly good Heirloom
troff manual and almost never looked at groff_diff(7).

> 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).

But it doesn't matter.  You seem to think new users are well served
by starting with the first few chapters of the info document, and
that sounds plausible.  I don't see any practical relevance to the
question where exactly the boundary between the "user manual" and
the "reference manual" part is.  Providing documentation in two
different formats is not ideal, but can't realistically be helped
in this case.  There is no need to make up an artificial justification.
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.  And we have a particularly
important third part in HTML format anyway because the maintainer
of that part is convinced that neither of the main two formats are
well-suited to his part.

> Possibly, a third part could include
> additional documents we maintain ("Using Automake in the Groff Project",
> "Writing Papers with GROFF using -me", "-ME REFERENCE MANUAL", "Making
> Pictures with GNU PIC", and "Portable Document Format Publishing with
> GNU Troff" [though the last needs some work to complete].

Yes, having i list of supplementary documents in the info manual
would be useful, unless it already exists and i merely missed it.

> What do you think?

Overall, your plan sounds very reasonable to me.

Yours,
  Ingo