[bug #60061] Narrow scope of groff Texinfo manual

[G. Branden Robinson]

URL:
  <https://savannah.gnu.org/bugs/?60061>

                 Summary: Narrow scope of groff Texinfo manual
                 Project: GNU troff
            Submitted by: gbranden
            Submitted on: Mon 15 Feb 2021 03:49:12 AM UTC
                Category: Core
                Severity: 1 - Wish
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: gbranden
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

Background: https://lists.gnu.org/archive/html/groff/2020-06/msg00044.html and
follow-ups

There was a broad consensus around an idea of mine to narrow the scope of our
Texinfo manual.


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





    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?60061>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/