groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: John Gardner
Subject: Re: [groff] groff as the basis for comprehensive documentation?
Date: Sat, 21 Apr 2018 16:48:33 +1000

Apologies for the out-of-sync response: Ingo's e-mail was binned as spam by
Gmail. Apologies if it sounded like I was ignoring you. =) (I was wondering
where Ralph drew this from:


> *The name of that standard section in man(7) and mdoc(7) is "EXIT**STATUS",
> not "Exit Status" nor "Exit status" nor "exit status".*


Now then. This is gonna be great.


> *Oops, you are rolling your own CSS from scratch.*


Ingo, I've spent the last 13 years in front-end web development, and I've
been writing standards-compliant websites for almost a decade. You are in
absolutely *no* position to be lecturing me on CSS, especially not when
your own is a pigsty.

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


... yes, that's the entire reason CSS exists: to separate presentation from
content (the latter being tantamount with "semantics" as understood by web
authors and those of us who actively follow modern web standards). Whatever
your interpretation of "semantic" is, it's firmly-entrenched in some
mdoc-centric little realm far removed from the web platform.

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


The stylesheet is atrocious, and only "semantic" insofar as direct
likenesses to mdoc markup is concerned. Probably looks adequate to systems
programmers, but to a web developer, it more resembles the auto-generated
slop Microsoft Office generated in the old days when saving Word documents
as HTML.

*With HTML code containing the correct attributes*


Correct? You've managed to get *everything* wrong. HTML and CSS is *NOT* mdoc,
yet you write it as such and then brag frequently about mandoc's "superior
HTML output". I've had enough.

*Shortlist of what mandoc fucks up with HTML:*

   1.
*Redundant title attributes on everything. *Actually, worse than redundant:
   it screws with assistive technologies like screen-readers, which might read
   the contents of a tag to the user using the title attribute if one is
   present. If you want to attach page or application-specific metadata to
   elements, use data-*
   <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*>
   instead.


   -
*Presentational tags used instead of those conveying text-level
semantics: *You're
   literally doing what mdoc(7) tells you not to do, except in HTML form:
      - -b, -S, -o:
      Flags/options should be represented using kbd tags, as they describe user
      input <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd>.
      - =*option*:
      Parameters should use var tags to indicate a placeholder name for an
      expectant value
      - Use dfn to markup the defining subject's name. For mdoc, this means
      *Nm*
   - *Inconsistent or incorrect use of sectioning elements*
   You linked to https://man.openbsd.org/gcc.1 as an example. CTRL+F and
   search for "Options Controlling the Kind of Output".
   I'd hotlink the section directly, but you neglected to use an ID
   attribute or even an anchor element with a name attribute. Did you mean to
   use all those separate <dl> tags as an indication of quality output, or was
   that an oversight?
   - *Pointless empty elements everywhere*
   - *Class attributes assigned to elements which should be styled using
   SIMPLE stylesheet declarations*

Also, half of your "semantic stylesheet <https://man.openbsd.org/mandoc.1>"
is redundant and repeating default properties. Many values aren't actually
doing anything, and several rulesets are empty altogether.

I can't go on. I'm feeling queasy with fremdschämen. Seriously.


On 21 April 2018 at 07:19, Ingo Schwarze <address@hidden> wrote:

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]