On Mon, 14 Sep 2015, Warren Young wrote:
On Sep 14, 2015, at 4:04 PM, Warren Block <[email protected]> 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
