bugGNU roff - Bugs: bug #60061, narrow the scope of the groff...

 
 

bug #60061: narrow the scope of the groff Texinfo manual

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Mon 15 Feb 2021 03:49:12 AM UTC
   
 
Category:  Core Severity:  1 - Wish
Item Group:  Documentation Status:  In Progress
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sat 07 Oct 2023 09:49:00 PM UTC, comment #14: 

5. Also relocate some of the material about preprocessors' interactions with conditional requests and macro definitions from tbl(1), since it goes for region-rewriting preprocessors in general.

G. Branden Robinson <gbranden>
Group administrator
Fri 06 Oct 2023 10:24:02 PM UTC, comment #13: 

Checkpointing my thoughts:

1.  Ditch the DEC Ultrix man(7) extension stuff.  Move the documentary material into the macro file itself.  (Possibly start shipping that as an example instead of in /tmac/, but that's strictly a separate issue from this ticket.)

2.  Ditch the translation of ms.ms, or justify its presence.

3.  Add material to the end of the "Tutorial for Macro Package Users" chapter discussing basic definition and use of registers, macros, and (maybe) strings.  Much of this can be picked up from groff_mm(7), deposited here, and translated to Texinfo.

And not scope-related, but...

4.  Rewrite the description of GNU troff's output format.  It is insufficiently precise.

See recent mailing list discussion.

G. Branden Robinson <gbranden>
Group administrator
Mon 02 Oct 2023 10:48:53 PM UTC, comment #12: 

comment #10:

> I'll fix that, probably with the latter.


Fixed (though with the former), along with other changes, in last month's commit 468456d4.

Dave <barx>
Group Member
Sun 05 Jun 2022 03:31:50 PM UTC, comment #11: 

comment #10:

> Two places where the link can go stale is enough...


Ah, yes, I hadn't considered that.  The lessons of bug #60305 are too soon forgotten.

Dave <barx>
Group Member
Fri 03 Jun 2022 08:44:25 PM UTC, comment #10: 


comment #9:

> The Texinfo manual elsewhere retains the sentence "A free implementation of 'grap', a preprocessor for drawing graphs, can be obtained as an extra package," which seems needlessly coy: may as well include here either the link to where it can be obtained (which was removed from the info manual in the foregoing commit), or a pointer to the groff(1) man page, which contains the link.


Good point, Dave--I'll fix that, probably with the latter.  Two places where the link can go stale is enough...

G. Branden Robinson <gbranden>
Group administrator
Fri 03 Jun 2022 08:39:48 PM UTC, comment #9: 

The Texinfo manual elsewhere retains the sentence "A free implementation of 'grap', a preprocessor for drawing graphs, can be obtained as an extra package," which seems needlessly coy: may as well include here either the link to where it can be obtained (which was removed from the info manual in the foregoing commit), or a pointer to the groff(1) man page, which contains the link.

Dave <barx>
Group Member
Wed 01 Jun 2022 12:39:02 AM UTC, comment #8: 


commit 2c652e943affb8b665ff225eb56dcbb34162957c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon May 30 11:48:26 2022 -0500

    doc/groff.texi: Drop stub-heavy chapters.

    The "Preprocessors" and "Output Devices" chapters were mostly stubs for
    content to be added later, and have been for years.  What content was
    already present duplicated existing groff man pages (except for a
    reference to Ted Faber's "grap" implementation, which is also documented
    in the "MORE.STUFF" file).

    Drop this material to reduce reader frustration with incomplete
    sections.  Replace internal Texinfo @*ref commands with "@cite"s of man
    pages where necessary.

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


G. Branden Robinson <gbranden>
Group administrator
Sat 06 Mar 2021 11:56:42 PM UTC, comment #7: 

A little more polished, with options (see README) and the default build mimics the version produced by pdftex, although that is not my favourite!

README
======

To build the groff book use make. The default settings will produce a book in
a very similar style to pdftex, using mainly Computer Modern fonts. However,
there are a number of parameters you can change which will change the style.
The parameters are entered in this way:-

make ARGS='parameter value ...'

The major parameter is "--ver" which can be set to either "original" (the
default if the parameter is not present), or "new" which uses the groff fonts
Helvetica and Courier. This parameter sets all the other parameters listed
below to default values but these can be separately overriden.

These are the separate parameters which can appear in ARGS:-

fam : the font family to use for the body text. Defaults to "H" for new and
CMT for the original.

codefam : the font family to use for monospaced text, set to "C" for new and
"CMC" for original.

hdcol : this should be one of the named colours which groff has
pre-configured, "forestgreen" used for new and "black" for original. It
specifies the colour for all text headings.

baseind : this is the amount of indent to use when indenting text. It is set
to 1.5c for both versions. Note that bulletted lists use a fixed indent amount
which can't be changed.

psz : the default point size, 12p for new and 13.25p for original.

vsz : the default vertical space for the font, 14.5p for both versions.

po : is the margin size, set to 2c for new and 3c for original.

ll : this is the line length used for the book. Since the book is designed for
A4 pages, you should use "c" as the units for po and ll (centimeters).
Normally you don't need this parameter since the default for both versions is
21c-(2*po), which gives symetrical margins.

For example:-

make ARGS='--po 2c'

will generate the original style but with 2cm margins. And:-

make ARGS='--ver new --codefam CMC'

Would generate a new style book but using Computer Modern monospaced instead
of Courier for the code snippets.

Please note that these parameters do not affect the section of the book which
documents "Introduction to PIC" since this section has to have specified
values for the "pictures" to render correctly.

After the book has been generated, in order to generate it again, either do
a 'make clean' or call make like this:-

touch groff.texi; make ARGS='...'

Deri James



(file #51016)

Deri James <deri>
Group Member
Wed 24 Feb 2021 06:37:33 PM UTC, comment #6: 

Here's the build environment. Just untar and cd into texi2groff-beta and "make". There are still many rough edges, there is a list of items not handled by the parser along with a count of how often they triggered, which is present after the "Coping This Manual" section, gradually dwindling!

Please let me know what you think, since it is now "good enough" for my own purposes, but if you think it is a goer, I will continue to polish.

(file #50914)

Deri James <deri>
Group Member
Sat 20 Feb 2021 09:57:29 AM UTC, comment #5: 

Hi Deri,

None of your attachments are showing up in the bug.  My guess is that it's due to the "16384 kB" limit.  Though maybe the true limit is lower; my separate PDFs of our Texinfo manual plus a 300+ PDF of all our man pages comes in at under 8 MB.

Can you mail me?  My address is in the groff ChangeLog file. :)

G. Branden Robinson <gbranden>
Group administrator
Thu 18 Feb 2021 06:42:21 PM UTC, comment #4: 

Trying with a tar file containing complete build.

Deri James <deri>
Group Member
Wed 17 Feb 2021 11:30:08 PM UTC, comment #3: 

I'm trying to attach the pdf. If it fails please let me know if I can send it direct by email.

Deri James <deri>
Group Member
Wed 17 Feb 2021 11:20:15 PM UTC, comment #2: 

I am not sure if you are aware of some work I did awhile ago around making groff produce the "groff book" rather than Tex

This was a program which converted the texinfo file into a roff file which could be run through groff with the ms macro to produce the pdf, it also converts man pages to ms as well. This means that you can embed individual man pages within the book, rather than maintaining separate texts.

You can see examples of this in the "Preprocessors" section of the book, where the appropriate man pages have been inserted. I have been using this book for quite a while since I like all the relevent information in one searchable tome. The sections which you are considering droppin, to avoid maintaining multiple versions of similar information, could be populated from their man pages. Ideally, we could add .ix entries to the man pages so that they get indexed in the Concepts index as well.

Since this was only ever a personal project, and the results were "good enough" for my own purposes, you are likely to find little "nits" which can probably be corrected. Let me know what you think.

Deri James <deri>
Group Member
Mon 15 Feb 2021 04:00:45 AM UTC, comment #1: 

Regarding Chapter 4, Larry Kollar's ms.ms has been resurrected since I made that proposal, and I'm working on updating it.  While of narrower scope, I suppose it's worth explaining my tactical plan somewhere.

I'm trying to get doc/ms.ms up to date with both doc/groff.texi and tmac/groff_ms.7.man.  The latter two are more up to date, and have usually seen added documentation of new features added to GNU ms (the latter was rewritten many years ago to mostly be a translation of ms.ms into man(7).

In a nutshell what I'm doing is porting topical additions to doc/ms.ms and groff_ms(7) to doc/ms.ms, synchronizing language as far as is possible across the three documents, and dropping examples from groff_ms(7), which already has a cross reference to doc/ms.ms, which ships as part of the distribution.

Eventually, ms coverage will drop out of doc/groff.texi, leaving doc/ms.ms as a user manual and groff_ms(7) as a reference.

G. Branden Robinson <gbranden>
Group administrator
Mon 15 Feb 2021 03:49:12 AM UTC, original submission:  

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.


G. Branden Robinson <gbranden>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #51016:  texi2groff-beta2.tgz added by deri (735KiB - application/x-compressed-tar)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by barx
  • -email is unavailable- added by deri (Posted a comment)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-10-06 gbranden SummaryNarrow scope of groff Texinfo manual narrow the scope of the groff Texinfo manual
    2022-05-31 gbranden StatusNone In Progress
    2021-03-06 deri Attached File#50914 Removed
    2021-03-06 deri Attached File- Added texi2groff-beta2.tgz, #51016
    2021-03-01 barx Carbon-Copy- Added barx
    2021-02-24 deri Attached File- Added texi2groff-20210224.tgz, #50914

    Back to the top

    Powered by Savane 3.14-5139.
    Corresponding source code