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

[hyc@symas.com]

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.

-- 
   -- Howard Chu
   CTO, Symas Corp.           http://www.symas.com
   Director, Highland Sun     http://highlandsun.com/hyc/
   Chief Architect, OpenLDAP  http://www.openldap.org/project/