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.