[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
Attachment:
signature.asc
Description: PGP signature
