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

[John Gardner]

>
>
>
> *Unless you have strong reasons for the different syntax, pleaseconsider
> using the syntax established in the new man.cgi(8) a fewyears ago: *


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


Thank you for bringing this to me. =) Yes I most certainly will use this
syntax (didn't consider the possibility of including $MANPATH in the URI).

*and blanks in fragment names replaced by underscores rather than hyphens,
> for example:*

The underscores look really jarring... what's the argument against using
dashes instead? Slugs like "#camel-kebab-case" tend to be formatted that
way, for example...


man://mandoc.1#EXIT_STATUS


Now,  as for the SHOUTY SHOUTY... for HTML output, I'll be using correctly
cased section headings, with the correct application of `text-transform:
uppercase;` being applied by CSS. In fact you can a start I made on a
semantic HTML5  output example:

*https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/example.html#name
<https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/example.html#name>*

This will be generated by one of two projects I intend to start once this
is finished - postprocessors for purely semantic web technologies that
follow WAI-ARIA accessibility practices and uphold contemporary
web-authoring recommendations.

Note the minimalism in the code I've linked you to... So far, this is what
I've written for its stylesheet
<https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/manpage.css>
:

On 21 April 2018 at 05:54, Ingo Schwarze <address@hidden> wrote:

> 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
>