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