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

[G. Branden Robinson]

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

signature.asc
Description: PGP signature