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

[Steve Izma]

On Sun, Sep 27, 2020 at 12:14:47AM -0400, Larry Kollar wrote:
> Subject: Re: (off topic?) Docbook? Re: manlint?
> 
> I’m not going to pronounce Docbook dead, but open-source
> projects that use it (or Texinfo) have accidentally erected a
> barrier to entry for people who want to contribute to the
> documentation. They would be much better served by adopting
> Lightweight DITA, which can ingest HTML5 and Github-Flavored
> Markdown alongside DITA XML (and convert any type to any other
> type). 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.

I generally agree with the above, but my point about the
longevity of an XML document is that such a document is agnostic
as to its target output. Too much of this discussion thread is
concerned with converting a groff document to other formats like
XML or HTML and ignoring the reverse path.

Groff is for typesetting on paper. XML and its relatives like
modern HTML seem to be used primarily for Web display, but they
were designed as generalized markup languages. Groff's
hyphenation, justification, and font-handling algorithms could be
adopted by other rendering engines (like browsers or epub
readers) but as far as I'm concerned it's currently the best
method around for producing typeset pages on paper. In fact I
think it's wasted on man pages, except for the fact that groff's
entrenchment as the man-page generator assures that people like
us will have groff available for our purposes regardless of what
Linux or BSD machine we find ourselves on.

>From the point of view of a structured document, groff's
paper-driven purpose makes it a post-processor, not a writing or
composing system. In this sense Markdown-type systems are for
writing, and the most successful of such systems minimizes the
keystrokes needed to structure a document because, after all, a
writer's main purpose is to get content down and worry about
presentation later. Markup code (like markdown, mediawiki
language, even terse XML) is just a set of bookmarks to come back
to when you start cleaning up the document's structure, in the
same way as you would clean up the content's logic after
spontaneous bursts of inspired writing.

Peter's comment about Mom's semantic macros is very interesting,
especially since he points out how presentation comes later: you
write or modify what these semantic macros point to once you've
decided what size of page or kind of page design you want for
your document. Or you could convert those macro requests into
other structured markup, as long as you use opening and closing
delimiters (the crucialness of which is a different discussion).
I think that's a far more efficient approach than including troff
primitives as you write. And it's a significant break from all
the traditional troff macro sets.

> ... there are several decent XML parsers
> for awk while TSV/CSV/JSON parsers have severe limitations. I
> had to learn enough Python to deal with a couple of work
> projects that involved CSV and JSON input.

I think Larry's point here is that it's not that hard to write a
script to go from a markup language to groff. I've used python
for that for over twenty years (and awk for at least fifteen
years before that). I've found that even some of my rather obese
python scripts can do the conversion on a modern machine in the
blink of an eye. And this also means that people we'll never meet
will be able to write a conversion script in whatever language is
handy fifty or one hundred years from now.

However, there are tricks to the process, such as whether to use
tree-like parsing or serial parsing; inline code needs to be
handled differently than block code; when do you want to preserve
white space and when do you want it ignored; how flexible can you
make the parsing so that you can place the markup less
obtrusively in the file to improve the readability of the
content; etc. I'd prefer to have these kinds of discussions
rather than complaining about how bad everyone else's systems are.

        -- Steve

-- 
Steve Izma
-
Home: 35 Locust St., Kitchener, Ontario, Canada  N2H 1W6
E-mail: sizma@golden.net  phone: 519-745-1313
cell (text only; not frequently checked): 519-998-2684

==
I have always felt the necessity to verify what to many seemed a
simple multiplication table.
        -- Ilya Ehrenburg (Soviet author and critic; he's not
           talking about mathematics)