Hello,
onf wrote on Mon, Jan 20, 2025 at 01:48:19AM +0100:
> On Mon Nov 4, 2024 at 4:03 PM CET, onf wrote:
>> On Mon Nov 4, 2024 at 1:45 AM CET, Alexis wrote:
>>> "onf" <o...@disroot.org> writes:
>>>> While you can absolutely get a list of manpages containing a
>>>> specific term of a specific type with apropos (like the example
>>>> you gave), what I was getting at is that you can't say to your
>>>> pager "jump to the flag -e". [...]
>>> Well, what i was trying (poorly!) to get at is that if you've got
>>> semantic markup rather than presentational markup, one can use
>>> that fact for the sort of functionality you describe: a program
>>> could find the documentation for that flag by searching the source
>>> for '.Op Fl e', which would be more reliable than having to make
>>> guesses / use heuristics.
>> Agreed. I was mostly complaining such a thing hasn't been done yet
>> despite mdoc existing since the 90s (iirc).
> Actually, BSD mandoc does implement this, it's just documented at
> a poorly visible place in the docs. BSD mandoc's man(1):
You have a point here. I noticed myself in the past that the
prominence of this feature in the documentation is significantly
smaller than its usefulness. It's also documented in mandoc(1),
type either of these commands to see for yourself,
$ man -O tag=tag mandoc # works on OpenBSD and perhaps on other BSDs
# maybe even on Alpine, Void, or Chimera Linux
$ lynx https://man.openbsd.org/mandoc#tag /* works everywhere */
Admittedly, that's not particularly discoverable either.
I tried to think of a more discoverable places in the past, but all that
came to mind so far were inacceptable from a systematic perspective.
I'm open to suggestions, though; maybe you have a good idea
for a better place?
> MANPAGER
> Any non-empty value of the environment variable MANPAGER is
> used instead of the standard pagination program, less(1). If
> less(1) is used, the interactive :t command can be used to go
> to the definitions of various terms, for example command line
> options, command modifiers, internal commands, environment
> variables, function names, preprocessor macros, errno(2)
> values, and some other emphasized words. Some terms may have
> defining text at more than one place. In that case, the
> less(1) interactive commands t and T can be used to move to the
> next and to the previous place providing information about the
> term last searched for with :t. The -O tag[=term] option
> documented in the mandoc(1) manual opens a manual page at the
> definition of a specific term rather than at the beginning.
>
> And it works quite nicely, actually.
Glad to hear that. :-)
> The definitions are generated automatically, so all manpages written
> in mdoc benefit from it. I assume groff mdoc + man-db doesn't
> implement this?
Not that i know of. It would actually be much harder to implement
in groff than in mandoc because a full roff(7) implementation, by
the basic design of how roff(7) works, lacks a semantic parse tree.
So by the time you get to the output processors, they have no syntactic
information left that they could work on. It's all presentational
at that point.
Yours,
Ingo
