Re: [groff] groff as the basis for comprehensive documentation?

[Ingo Schwarze]

Hi John,

John Gardner wrote on Sat, Apr 21, 2018 at 04:19:06AM +1000:

> My Troff previewer will be doing just that for
> man://mandoc/1/. =)
> Will probably add support for subsection-linking with fragment
> identifiers too:
> man://mandoc/1/#exit-status

Unless you have strong reasons for the different syntax, please
consider using the syntax established in the new man.cgi(8) a few
years ago:

  protocol://[manpath/][arch/]name[.sec][#fragment]

with all components case-sensitive and blanks in fragment names
replaced by underscores rather than hyphens, for example:

  man://mandoc.1#EXIT_STATUS
  man://sparc64/lom.4

I'm not saying either syntax is better - as a matter of fact, the
differences are minimal, but avoiding gratuitious variations may
benefit the overall ecosystem in the long term.

The [manpath/] component can be used to identify operating systems
and operating system releases; you may not need it in your context,
to access local manual pages only.

Note that i didn't invent a new syntax lightly, but there was no
precedent to follow that i could find.  The old syntax of the
classical man.cgi was a horrible thing involving
  ?query=...&foo=...&bar=...
and so on, so reusing it was not an acceptable option (though
the new man.cgi still supports it for backward compatibility).

Note that Debian mostly follows that syntax, too:

  https://manpages.debian.org/stretch/mandoc/mandoc.1.en.html#HTML_Output

Except for the .lang.html insertion.
They are using [manpath/] for "release/package/",
so that component is somewhat flexible depending on the context.

Yours,
  Ingo