Re: (ITS#7614) Markup error in slapd.conf.5
Eric S. Raymond wrote:
Howard Chu <hyc(a)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.
A line-break may well be only a presentation-level concept, but it is also
something that a document author explicitly chooses to insert. A tool (or
markup language) that ignores an author's explicit wishes is a broken tool.
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.
Your solution is broken or unfit for the purpose if it cannot process simple
and correct manpage source.
--
-- Howard Chu
CTO, Symas Corp. http://www.symas.com
Director, Highland Sun http://highlandsun.com/hyc/
Chief Architect, OpenLDAP http://www.openldap.org/project/