Re: Minor suggestion to improve groff_ms documentation

[G. Branden Robinson]

Hi Oliver,

At 2024-11-08T16:41:18+0100, Oliver Corff via GNU roff typesetting system 
discussion wrote:
> Dear All,
> 
> I was in search of the macros for writing indented and bulleted lists.
> While groff_mm contains the macro BL which is explained as "Begin
> bulleted list" and groff_me has "(l begin list" and ")l end list", I
> was a bit baffled how groff_ms successfully hides its list feature
> from the user: Under ".IP" it only says "Set a pagraph with a left
> indentation."
> 
> My suggestion: Can we make a small insertion to the effect: "Set a
> paragraph with a left indentation; used for typesetting bulleted
> lists." or similar? It would be nice if searches for the same purpose
> could be done by the same key words across the major macro packages.

There's a limitation to that principle; some packages seem to have
divergent terminological traditions.  Of the non-man-page full-service
package, all have a feature we know as "keeps", but only some call them
that.

That said, I do sometimes add stuff like this:

     Hook macros are undefined by default; mm calls them to enable
     customization of its behavior.  (DWB mm termed these “exits”.)

More recently I learned that the term "exits" was, apparently, a lift
from IBM assembly language programming jargon.

Regarding ms, it has a whole separate manual.  Part of it reads:

(This is wide in nroff mode, 87n, because I haven't slimmed down some
tables yet.)

5.6.  Lists

The  marker argument to the IP macro can be employed to present a variety of 
lists; for
instance, you can use a bullet glyph (\[bu]) for unordered lists, a number (or 
auto‐in‐
crementing register) for numbered lists, or a word or phrase for glossary‐style 
or def‐
inition lists.  If you set the paragraph indentation register PI before calling 
IP, you
can later reorder the items in the list without having to ensure that a width  
argument
remains affixed to the first call.

      ┌────────────────────────────────────────────────────────────────────────┐
      │           Input                               Result                   │
      └────────────────────────────────────────────────────────────────────────┘
      │ .nr PI 2n                   A bulleted list:                           │
      │ A bulleted list:                                                       │
      │ .IP \[bu]                   •   lawyers                                │
      │ lawyers                                                                │
      │ .IP \[bu]                   •   guns                                   │
      │ guns                                                                   │
      │ .IP \[bu]                   •   money                                  │
      │ money                                                                  │
      ├────────────────────────────────────────────────────────────────────────┤
      │ .nr step 0 1                A numbered list:                           │
      │ .nr PI 3n                                                              │
      │ A numbered list:            1.  lawyers                                │
      │ .IP \n+[step].                                                         │
      │ lawyers                     2.  guns                                   │
      │ .IP \n+[step].                                                         │
      │ guns                        3.  money                                  │
      │ .IP \n+[step].                                                         │
      │ money                                                                  │
      └────────────────────────────────────────────────────────────────────────┘

Some sort of brief aside could be added to groff_ms(7), of course.

Regards,
Branden

signature.asc
Description: PGP signature