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

[John Gardner]

> There is a place for a book-like work, I think.

I agree, but using a different typesetting system to prepare it is a wasted
opportunity, IMHO. 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.

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


On Tue, 30 Jun 2020 at 03:08, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

> At 2020-06-14T14:40:44+1000, John Gardner wrote:
> > Why are we using Info, again? Was it because of GNU policy?
>
> Yes.  https://www.gnu.org/prep/standards/standards.html#GNU-Manuals
>
> Aside from the mandate of the source document format, I find the advice
> there fairly sound, as far as it goes.  I do wryly observe the exception
> RMS carved out for himself to justify the retention of the 1980s-era
> abortion joke in the GNU libc manual.  (It was taken out, over his
> objections, last year.)
>
> > Or is there a more compelling reason as to why we're maintaining two
> > different versions of the same documentation?
>
> There is a place for a book-like work, I think.  Our manual has helped
> me learn the system better.
>
> There is indeed much duplication but that doesn't bother me nearly as
> much as the places where duplication of other groff documentation was
> intended but nobody ever got around to it.  For example, ms is the only
> macro package documented there (man was too, but it had fallen out of
> sync with groff_man(7) even before I got to it).
>
> Much worse, Chapter 6 (Preprocessors) is just a bunch of embarrassing
> stubs.
>
> Chapter 9 (Installation) has a title.  That's it.
>
> Many of the utility programs that ship with groff are not even
> mentioned, let alone documented in the groff Texinfo manual.
>
> However, what _is_ written is often written well.  It would be a shame
> to throw it away.
>
> I therefore propose to pare down the groff Texinfo manual to the parts
> it does best, which is comprises conceptual and tutorial introductions
> (chapters 1 and 3) plus a modernization of CTRS #54 (Chapter 5) and CSTR
> #97 (Chapter 8).
>
> == 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 5 (gtroff [sic] Reference): Retain. [2]
> Chapter 6 (Preprocessors): Drop.
> Chapter 7 (Output Devices): Drop.
> Chapter 8 (File Formats): Retain. [3]
> Chapter 9 (Installation): Drop.
>
> [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.
>
> [2] Keep in sync with groff_diff(7) for groff innovations and groff(7)
> for quick references and topical summaries.
>
> [3] Keep in sync with groff_out(5) and groff_font(5).
>
> Yes, there would still be some redundancy with respect to those last two
> points.  The good news is that the work is already done and not hard to
> maintain (I've been doing it).
>
> Moreover, much mischief could be avoided if we'd simply _document_ the
> forms of the documentation that need to be maintained in parallel.  It
> seems everyone has to stumble across this knowledge for themselves.
>
> == THE VISION THING ==
>
> I'm putting this part at the end as part of my perverse opposition to
> the practices of corporate executives.
>
> 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.  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].
>
> What do you think?
>
> Regards,
> Branden
>