Re: <OK> Re: [Groff] Re: Simplifying groff documentation

[M Bianchi]

On Sat, Dec 23, 2006 at 10:26:43PM -0500, Larry Kollar wrote:
>       :
> The problem with using XML for documentation is that it was
> designed specifically for machine processing -- and *people*
> write documents for *other* people.

I agree and think this is _very_ important.  groff -mm and -ms attempt to do
this, but mixing macros that associate _meaning_ with text with macros that
associate _presentation_ with text quickly gets confusing.  LaTeX has the same
problem to my eye.

> The human element has been
> tripping up XML doctypes, one after another, for quite a while
> now. One can mandate DocBook here, or DITA there, but if you
> have to *mandate* you've already failed. Success means an
> *embrace* -- and HTML is about the only doctype that has ever
> been widely embraced rather than endured.

HTML may have been "embraced" but I don't think because it helped people
communicate with people.  The lack of implimented standards across browsers
emphasizes how desparate people were to get their words on the web.

>       :
> Another possibility is that groff itself can do the conversion.
> The HTML "driver" has a ways to go yet before being able to
> produce beautiful HTML, but what comes out now is close enough
> to clean up using some awk scripts and HTML Tidy. So it might
> be easier, short- and long-term, to encourage people to add the
> -mwww macros to their man pages.

I think this is unlikely to work because _meaning_ and _presentation_ markups
look alike.

I want to write documents with only _meaning_ markup (and as little of that as
possible) and have the appearance come from a standardized assignment of
_presentation_ to _meaning_.  I want to avoid "tweeking" appearance altogether
since I firmly believe "our way is better than my way (for all `our ways' I
agree with)".  I'm working hard on at accumulating lots of `our ways' I agree
with by learning to agree more readily.

-- 
 Mike Bianchi