Eric S. Raymond wrote:
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.
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.