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
