Re: (off topic?) Docbook? Re: manlint?

[Larry Kollar]

James K. Lowden <jklowden@schemamania.org> wrote:

>> Complain about Markdown all you will, and use weird-arse corner cases
>> to show it?s Bad, but GFM can handle a lot of everyday text.
> 
> If you limit the feature set to what markdown does, -ms macros are
> readable too.  It's a little tricky to set up an auto-incrementing
> register -- I always have to look it up -- and it's a nuisance to
> separate paragraphs with PP, but SH, IP, I, B, and PP get a lot done.  
> 
> Obviously -ms lacks hyperlinks.  The things markdown lacks are too
> numerous to mention.  

Fortunately, Markdown doesn’t have to stand on its own. If you accept
that typing something like “*italic text*” (two keystrokes overhead) is a
lot faster than typing “\fIitalic text\fP" (six keystrokes) or '\n.I “italic 
text”\n’
(seven), and that stuff adds up over a few thousand words, then you can
see the value of drafting something in Markdown and converting it. (Or,
in a system like Lightweight DITA, convert only the pieces that need more
complex markup).

Using a utility like lowdown (thanks Kristaps), you can convert to -ms as well.

>> Most of the -ms macros that come before the first .LP or .NH are
>> considered book metadata in DITA, so metadata is covered. What
>> *roff doesn?t do is produce usable HTML output. Yet.
> 
> There can be no question that troff boasts a very rich input language.
> Every time I point that out in the context of advocating its use,
> someone says, "but HTML".

I used groff at work for about 6-7 years to produce documentation. “But
HTML” became very important at the end, and was a contributing factor
that pried me off groff and onto a system that (except for HTML) was far
inferior. Try as I might, I just couldn’t get what came out of grohtml to
produce acceptable results without a huge amount of by-hand work.

> … A different -- and, I would argue, more
> realistic -- approach would be a macro-to-HTML converter that worked
> only for documents expressly written with HTML in mind, using only
> macros and eschewing troff requests.  Such a document is, I assert,
> easily converted to HTML and produces perfectly acceptable PDF.

So you would use *roff to produce PDF, and some kind of conversion
script to produce HTML? That’s probably going to be more workable
than something like grohtml in the long run. Modifying things means
changing both the macro file and the script, but you have to do much
the same if you’re working with something like DITA. There are concepts
one could steal from DITA to ease maintenance and extensions. So maybe
add to “using only macros and eschewing troff requests” things like:

*  One *roff file = one HTML page.
*  Use a “book” file to order and structure things. You would also define
   variables here.
*  Distinguish between internal links (within the document) and external.
   This gives you the ability to warn of (or quit on) missing files.

(I’ve probably only scratched the surface… for example, would you also
want to eliminate escapes, or try to process inline markup like italics or
superscripts?)

Some extensions would be dead-easy; for example, using alias to add
semantic sugar:

        .als CITE I
        .als CMD CW

The conversion script would have to provide a similar mechanism, but
if it’s there from the beginning I think it would be easier than trying to
retrofit it.

> … If there was a simple way to add a "class" and "id" to macros
> (that would be ignored except for HTML) then a very
> simple HTML tagged with classes and IDs could leave most presentation
> choices to CSS.  
> 
> Any suggestions on how -ms macros could be compatibly extended to
> include classes and IDs?  I've always found that aspect of my
> "proposal" daunting.

Why not leave that to the conversion script? If it’s needed only for
HTML, then don’t worry about backporting it. You could autogenerate
IDs by slugifying the title text or manually by creating an .ID macro,
and use a table to define classes for each supported macro. 

— Larry