Re: (ITS#7614) Markup error in slapd.conf.5

[esr@thyrsus.com]

Howard Chu <hyc@symas.com>:
> OK, I ran Docbook 4.5 on the output from doclifter and I see it's
> complaining on one line of slapd.conf.5.xml. It appears doclifter is
> misinterpreting the .br request. Instead of inserting a line break
> it is either ignoring it completely or doing a paragraph break.
> 
> I'm going to reject your submitted patch because it is not the
> minimal patch needed to fix the error, nor is the error actually in
> our manpage source, it is in the doclifter tool.

You have drastically misunderstood what you saw.  This isn't an error
in doclifter, it's a result of a basic ontological mismatch between
the source and target markups that doclifter tries to bridge across.

There are no line breaks in DocBook's XML, structure-oriented world.
The closest thing to one ia special-purpose <sbr/> tag that is only valid
inside command synoposes.  Thus there is no "line break" equivalent
that .br can be mapped to.  Nor should there be; that is fundamentally
a presentation-level concept.

Thus, one of either ignoring the .br or interpreting it as a paragraph
boundary is exactly what doclifter *should* be doing.  This is not a
bug, it is correct behavior because those are the only alternatives
XML-DocBook supports.

doclifter has to deduce which interpretation is correct by applying
certain parsing and pattern-matching rules.  Usually it succeeds, but
there are rare (single-digit-percentage) cases in which it fails.
Yours is one.

I repeat: the error is *not in the tool*.  It's a result of attempting
to deduce structure out of the troff tag soup that the tag soup does
not intrinsically possess.  After 11 years of development doclifter
does a pretty heroic job of this, but a perfect one is not possible -
there's too much chaos ot there.

My patch adds the structural information required for doclifter to
get traction. The requirement for this is rare, and getting more so
as man page maintainers clean up their sources.  Please be part of
that solution rather than part of the problem.
-- 
		<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>