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

[Ingo Schwarze]

Hi John,

John Gardner wrote on Sat, Apr 21, 2018 at 06:21:33AM +1000:
> Ingo Schwarze wrote:

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

   $ man -k Sh,Ss=- | wc -l
        43
   $ man -k Sh,Ss=_ | wc -l 
        11

Dashes are much more common in normal English text (which section
and subsection headings usually consist of).  If you see a hyphen
there, you expect that it represents a hyphen, right?  Besides,
i regard the underscore as the ASCII printable character most
visually similar to the blank as it draws nothing *inside* the
box, but just at the edge.

But really, it's no big deal, i could have gone with the hyphen
back then, but nobody said they would prefer it when the decision
was made.  I'm merely pointing out there is an opportunity here to
consciously choose to be compatible, or to not be compatible...  :)

>> man://mandoc.1#EXIT_STATUS

> Now, as for the SHOUTY SHOUTY...

That's not a matter of SHOUTING, but of case sensitivity.
The name of that standard section in man(7) and mdoc(7)
is "EXIT STATUS", not "Exit Status" nor "Exit status"
nor "exit status".  Case is preserved, consider:

  https://man.openbsd.org/mandoc.1#EXIT_STATUS
  https://man.openbsd.org/mandoc.1#PAGER
  https://man.openbsd.org/mandoc.1#HTML_Output
  https://man.openbsd.org/mandoc.1#Output_Formats
  https://man.openbsd.org/mandoc.1#Syntax_tree_output
  https://man.openbsd.org/mandoc.1#Errors_related_to_tables
  https://man.openbsd.org/mandoc.1#error
  https://man.openbsd.org/mandoc.1#mdoc
  https://man.openbsd.org/mandoc.1#c
  https://man.openbsd.org/mandoc.1#K
  https://man.openbsd.org/ls.1#a
  https://man.openbsd.org/ls.1#A
  https://man.openbsd.org/ksh.1#pwd
  https://man.openbsd.org/ksh.1#PWD
  https://man.openbsd.org/ksh.1#[[
  https://man.openbsd.org/ksh.1##
  https://man.openbsd.org/ksh.1#-
  https://man.openbsd.org/ksh.1#_

> for HTML output, I'll be using correctly cased section headings,
> with the correct application of `text-transform: uppercase;`
> being applied by CSS.

That's a bad idea.  I admit that many authors use unusual and even
inconsistent casing in section headers (even in the very mandoc.1)-:,
which may sometimes seem awkward.  But in technical documentation,
casing is often deliberate, and automatically changing it based on
natural language rules is prone to make information incorrect in
some cases.

> 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

Oops, you are rolling your own CSS from scratch.

I see absolutely nothing semantic in there, it looks like a purely
presentational style sheet to me.

Are you aware of this semantic style sheet for manual pages:

  https://man.openbsd.org/mandoc.css
  http://mandoc.bsd.lv/cgi-bin/cvsweb/mandoc.css

It has matured a lot since Kristaps started it in Dec. 2008.  With
HTML code containing the correct attributes, it can be used with
both man(7) and mdoc(7) documents - of course it is much more
powerful with mdoc(7), though.  Man(7) HTML output can never be
very pretty (nor semantically rich) due to the limitations of the
language, but it more or less kind of works all the same:

  https://man.openbsd.org/gcc.1
  https://man.openbsd.org/perl.1
  https://man.openbsd.org/curses.3

Yours,
  Ingo