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