URL: <https://savannah.gnu.org/bugs/?66401>
Summary: [man,mdoc] add (sub)section text extraction feature
Group: GNU roff
Submitter: gbranden
Submitted: Sun 03 Nov 2024 06:16:54 AM UTC
Category: Macro package - others/general
Severity: 1 - Wish
Item Group: Feature change
Status: None
Privacy: Public
Assigned to: None
Open/Closed: Open
Discussion Lock: Any
Planned Release: None
_______________________________________________________
Follow-up Comments:
-------------------------------------------------------
Date: Sun 03 Nov 2024 06:16:54 AM UTC By: G. Branden Robinson <gbranden>
Quoting [https://lists.gnu.org/archive/html/groff/2024-11/msg00005.html an
email of mine]:
Why not enhance groff man(7) to support a mode where _it_ will
spit out the "Name"/"NAME" section, and only that, _for_ you?
This would be as easy as checking for an option, say '-d EXTRACT=Name',
and having the package's "TH" and "SH" macro definitions divert
(literally, with the `di` request) everything _except_ the section of
interest to a diversion that is then never called/output. (This is
similar to an m4 feature known as the "black hole diversion".)
...
I also of course have ideas for generalizing the feature, so that you
can request any (sub)section by name, and, with a bit more ambition,[4]
paragraph tags (`TP`) too.
So you could do things like:
nroff -man -d EXTRACT="RETURN VALUE" man3/bsearch.3
and:
nroff -man -d EXTRACT="OPTIONS/-b" man8/zic.8
...
[4] To really land the feature, we need automatic tag generation from
input text (we don't want to make the man page author construct
their own tags). Another reason we want the construction to be
automatic is to make the tags unique when multiple man pages are
formatted in one run, as one might do when making a book of man
pages. Automatic tagging will also enable the slaying of two other
ancient dragons.
1. deep internal links for PDF bookmarks
2. pod2man's `IX`-happy output; the widespread use of this
nonstandard macro confuses way too many novice page authors, and
bloats document size.
Another feature we'll really want to do this right is improved string
processing facilities. That, too, is something that will pay
dividends in several areas. With a proper string iterator in the
formatter (and a couple more conditional operators),[5] it will be
possible to write a string library as a macro file, slimming down the
formatter itself a little and making macro writers' lives easier.
We're only two days into the month and this has already come up on
the groff list.
https://lists.gnu.org/archive/html/groff/2024-11/msg00002.html
[5] https://savannah.gnu.org/bugs/?62264
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?66401>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
signature.asc
Description: PGP signature
