Re: [docbook] Re: [docbook-apps] Tools to make DocBook easier

[Warren Block <wblock@wonkity.com>]

On Mon, 14 Sep 2015, Warren Young wrote:

> On Sep 14, 2015, at 4:04 PM, Warren Block <wblock@wonkity.com> wrote:
> > What tools are there to make working with DocBook easier?  I wrote a lint-like proofreading tool
>
> There’s already xmllint, which if given a DocBook DTD, will validate 
> the well-formedness of your document, not just in the XML sense, but 
> also in that, for example, <para> cannot appear within <city>.

Sure.  But xmllint only validates the XML, and that misses many, many 
common mistakes that mystify authors.

> Some of the DocBook-aware text editors will do this on the fly, such as oXygen.
>
> > called “igor"
>
> Its -n option is bogus for DocBook.  Two spaces after a period is a 
> relic of fixed-width typography, from the days of typewriters.  I’m 
> doing it here because I expect you’re reading it in a fixed-width 
> font.  If your DocBook files are writing out to fixed-width forms, 
> then *maybe* it has a use, but I’d bet most DocBook input ends up as 
> HTML or PDF output, which typically use proportional fonts.

The rules are based on the FreeBSD standards from the Writing Style 
chapter here:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html

Some of those are arbitrary or path-dependent.  For our purposes, it's 
not so much whether we as individuals agree with the standard as whether 
our source is all formatted the same way.  That's important to us 
because we have so many contributors working on shared documents.

> Its -o and -t options are reinventing the xmllint wheel, probably 
> poorly.  I’m not trying to be mean, but your tests probably aren’t as 
> rigorous as a DTD, which is already installed on the system, as is 
> xmllint, in all likelihood.  Maybe it should just call out to xmllint 
> for you?

It is easy to get a proper XML document that uses tags incorrectly. 
"Incorrectly" according to our standards, anyway.  For example, we are 
precise about the content of programlisting elements.  Whitespace before 
or after the content is significant, and so the <programlisting> tags go 
on the same lines as content.  That is a surprise to many people, and so 
this program checks for it.  The DTD says nothing about that.  (And I'm 
the first to admit that igor does not really understand XML or DocBook 
at all, it's just some ugly Perl tricks to detect common problems. 
Improvements or rewrites are welcome.)

It's a tool to help the writer, because at the time, there were no 
others.  That is still a pretty sparse space, and I'd be interested in 
hearing about other tools with similar goals.

Note that we also use Schematron rules for a 'make lint' validation. 
igor is not meant to be a replacement for that or xmllint.

> Other than that, it looks like a nice addition to the toolkit.
>
> Any chance of at least preformatting the man page as index.html for 
> the project page?  It’s a bit annoying that I had to know “nroff -man 
> < igor.1 | less” in order to RTFM without installing your software.

Just 'man igor.1' should be enough, but I've added igor.1.html now.