From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
To: groff@gnu.org
Cc: linux-man@vger.kernel.org, bug-ncurses@gnu.org, alx@kernel.org
Subject: Re: Proposed v2: revised man(7) synopsis macros
Date: Mon, 29 Apr 2024 03:39:33 -0500 [thread overview]
Message-ID: <20240429083933.avuzyktl4p3xo6yh@illithid> (raw)
In-Reply-To: <20240426055958.3hzal6m4r7mgzhqj@illithid>
[-- Attachment #1: Type: text/plain, Size: 5142 bytes --]
[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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
prev parent reply other threads:[~2024-04-29 8:39 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-26 5:59 Proposed v2: revised man(7) synopsis macros G. Branden Robinson
2024-04-26 9:32 ` Alejandro Colomar
2024-05-03 20:31 ` G. Branden Robinson
2024-05-05 12:41 ` Alejandro Colomar
2024-05-05 12:44 ` Alejandro Colomar
[not found] ` <20240505135453.4rxsqe3so7347mli@illithid>
[not found] ` <ZjeTilIR86sBYrtI@debian>
2024-05-05 14:28 ` Alejandro Colomar
2024-05-05 14:32 ` G. Branden Robinson
2024-05-05 14:45 ` Alejandro Colomar
2024-04-26 21:54 ` Lennart Jablonka
2024-04-26 22:31 ` Undeprecating man(7)'s `HP` macro? (was: Proposed v2: revised man(7) synopsis macros) G. Branden Robinson
2024-04-29 8:39 ` G. Branden Robinson [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240429083933.avuzyktl4p3xo6yh@illithid \
--to=g.branden.robinson@gmail.com \
--cc=alx@kernel.org \
--cc=bug-ncurses@gnu.org \
--cc=groff@gnu.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.