On 2005.06.26 17:41:21 +0000, der Mouse wrote:
> >> If you *must* use XML, please make sure it's readable with plain
> >> text tools too!
> > If you use XML you can convert it to a number of formats (an example
> > is the pkgsrc guide which is available in HTML and plan text format).
> 
> How?  Which tool is appropriate to convert XML to plain text?  Which
> corner I never noticed is the converter buried off in?  Or is it a sed
> script hiding somewhere, or what?

See pkgsrc/doc:
/usr/bin/sed -e 's/&#822[01];/"/g' pkgsrc.html > pkgsrc.tmp.html
/usr/pkg/bin/w3m -dump -O iso-8859-1 -no-graph  pkgsrc.tmp.html | /usr/bin/sed -e 's/[^[:print:]]/ /g' > pkgsrc.txt

It's basically w3m with a small sed magic.

> > Writing stuff in XML is as readable as writing in mdoc format, IMHO.
> 
> Well...I'd agree: either one can be an unreadable blizzard of code, and
> either one can be lucid, clear, and readable even with plain text
> tools.

Exactly.

> I didn't say "please don't write XML"; I said "please make sure it's
> readable with plain text tools".  I've seen HTML that was eminently
> readable with nothing but less(1), and I've seen HTML that I had
> trouble even telling whether there *was* any content to it amid the
> blizzard of tags.  I've seen nroff input that was thoroughly readable
> as text, and I've seen nroff input that makes me scratch my head and go
> "there's probably some text here, but where?".  Similar remarks apply
> to every plain-text markup format I've seen any significant amount of.

Oh, I missunderstood you then. I thought you're complains were about
DocBook/XML. Anyway, IMO, writting documentation in 
XML/HTML/mdoc/<insert you prefered tool/markup language here> is almost
the same as writting code that should be legible.

		-- Rui Paulo