[Date Prev][Date Next]
Re: (ITS#7614) Markup error in slapd.conf.5
Eric S. Raymond wrote:
> Howard Chu <email@example.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/