Re: [groff] Problems with -Thtml

[Ingo Schwarze]

Hi Blake,

Blake McBride wrote on Sun, Apr 14, 2019 at 04:38:55PM -0500:

> The place where I work uses AsciiDocs.

Yikes.

I didn't inspect AsciiDocs for documentation in particular,
but i did look at Markdown in general:

https://undeadly.org/cgi?action=article&sid=20170304230520

> I started to push them towards groff

That's actually an excellent idea, as long as you push for roff-based
macro languages that have been widely used for documentation during
this millenium - that is, mdoc(7) or man(7).

If you want high quality typeset output, absolutely do use groff(1)
for that.  However, to produce HTML output from the same input files,
use the mandoc(1) program from mandoc.bsd.lv rather than the groff(1)
program.

> but it is important to get HTML output since, these days,
> people more often view documents than print them.

No argument about that.  For computer documentation, my priorities are:

 1. console UTF-8 output for interactive use with man(1)
    [with mandoc(1) or groff(1), output is almost byte-by-byte identical;
     the main difference is that mandoc is about twice to five times
     as fast as groff, depending on the input file.  Also, mandoc(1)
     is slightly more robust with low-quality input.]
 2. HTML 5 output for the web
    [with mandoc(1), *not* with groff(1)]
 3. console ASCII output in case you can't use LC_CTYPE=*.UTF-8
    [with mandoc(1) or groff(1), output is almost byte-by-byte identical]
 4. PDF and PostScript output for printing
    [with groff(1), mandoc is *much* lower quality for this output mode]

> Sounds like it is a good thing I didn't push too hard.

Sure, but only because you should first understand the problem space
and the solution space well enough before lobbying people.  Once
you pick the the proper macro language for the job and the the right
formatter for each output mode, there is nothing wrong with educating
others, too.

> Being someone with a fair degree of troff usage, it is a shame
> I can't use it in many of the docs I write.

You absolutely can.  You absolutely *should* use roff-based languages
for formatting documentation nowadays.  It is so much better than
anything that involves XML.

Yours,
  Ingo