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

[John Gardner]

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

It's an excellent summary of how groff differs to classical troff,
highlights potential portability issues (a.k.a., "groff-isms"), and also
documents known incompatibilities with legacy syntax.

If maintaining groff_diff(7) alongside another document with similar
content becomes a maintenance hassle, well… at least make it an appendix of
differences, rather than going into detail about every new feature.

On Tue, 30 Jun 2020 at 04:39, Ingo Schwarze <schwarze@usta.de> wrote:

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