Re: Proposed v2: revised man(7) synopsis macros

[G. Branden Robinson]

[slight correction]

At 2024-04-26T00:59:58-0500, G. Branden Robinson wrote:
> (The \~ escape sequences keep the line from breaking between the
> data type and the formal argument name.  Documents needing to be
> portable to DWB or Solaris 10 troff will need to use the unadjustable
> space escape sequence `\ ` [backslash, space] instead.)

I have stricken "Heirloom Doctools" from the foregoing.  I got so used
to typing the DWB/Heirloom/Solaris trio that I forgot that it doesn't
apply here.

As groff_man_style(7), notes, Heirloom Doctools troff has supported the
`\~` escape sequence for nearly 20 years.

     \~        Adjustable non‐breaking space.  Use this escape sequence
               to prevent a break inside a short phrase or between a
               numerical quantity and its corresponding unit(s).

                      Before starting the motor,
                      set the output speed to\~1.
                      There are 1,024\~bytes in 1\~KiB.
                      CSTR\~#8 documents the B\~language.

               \~ is a GNU extension also supported by Heirloom Doctools
               troff 050915 (September 2005), mandoc 1.9.14
               (2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13),
               and Plan 9 from User Space troff (commit 93f8143600,
               2022‐08‐12), but not by Solaris or Documenter’s Workbench
               troffs.

> * An example document, renderable with groff Git HEAD, 1.23.0, 1.22.4,
>   and 1.22.3 (at least), illustrating use of these macros.  View it
>   with "nroff -man".

Also, for the reader's edification, I'm including an inline rendering of
this example document, using groff 1.23.0.  Font styling is of course
lost in email.

$ nroff -man -Tascii /tmp/branden/synopsis-examples-portable.man
synopsis-examples(7)   Miscellaneous Information Manual   synopsis-examples(7)

Name
       synopsis-examples - examples of SY/YS macro usage

Description
       Here's a command synopsis.

       foo [-ab] -c param [-d param2] ...
           [--option-with-ridiculous-long-name-to-cause-line-break] file ...

       foo --help
       foo -h

       Now here's an example of a C function prototype.  This ncurses function
       takes  many arguments and is otherwise challenging for man page authors
       to typeset.

       int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts, chtype bs,
                   chtype tl, chtype tr, chtype bl, chtype br);

       Now let's test the behavior of synopses under a variety of conditions.

                 Let's first create a ten en (10n) relative inset  with  man's
                 RS  and RE macros so that we are more likely to get breaks in
                 synopses when formatting for typesetters.   Here's  a  simple
                 case of a command that takes no options and no operands.

                 simple

                 Here's a case of multiple prototypes re-using the indentation
                 of the first because the first gives its YS call an argument.

                 int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts,
                             chtype bs, chtype tl, chtype tr, chtype bl,
                             chtype br);
                 int border(chtype ls, chtype rs, chtype ts, chtype bs,
                             chtype tl, chtype tr, chtype bl, chtype br);

                 We  can  still  separate  such  synopses  with a paragraphing
                 macro.  Here's a third function prototype using wborder's in-
                 dentation.

                 int bogusfunc(WINDOW *win, int y, int x, chtype ch, int n,
                             void * lengthy-formal-argument-name);

                 Between synopses, the previous indentation, as  well  as  the
                 adjustment  and and automatic hyphenation modes, configurable
                 in groff man, are all restored.  In the  bogusfunc  synopsis,
                 we  called YS without an argument to discard the computed in-
                 dentation.  Our next synopsis computes its indentation anew.

                 int border(chtype ls, chtype rs, chtype ts, chtype bs,
                            chtype tl, chtype tr, chtype bl, chtype br);

       Let's end the relative inset and present our friend  wborder  one  more
       time.

       int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts, chtype bs,
                   chtype tl, chtype tr, chtype bl, chtype br);

       Let's try a function returning a pointer to void (and taking a function
       pointer as a parameter).

       void *bsearch(const void * key, const void * base, size_t nmemb,
                     int (*compar)(const void *, const void *));

       Finally, if we invalidly call SY without arguments, we do (essentially)
       nothing.  Text between the SY and YS calls is typeset normally.

       This concludes the demonstration.

groff test suite                  2024-04-25              synopsis-examples(7)

Regards,
Branden

signature.asc
Description: PGP signature