Re: Duck season! Rabbit season! Mallard season!

[esr thyrsus com (Eric S. Raymond)]

Shaun McCance <shaunm gnome org>:
> But it's worth pointing out that Yelp, today, does make
> your legacy documentation accessible and searchable.

Sort of.  It doesn't actually do a very good job rendering manual
pages, at least not compared to doclifter lifting to XML-DocBook
followed by rendering to HTML.  You already know several of the
reasons for this from our one previous email conversation.

> All your man and info pages are there.  What's interesting to
> us isn't so much finding that stuff.  We need to figure
> out where to put new stuff in a way that Gnome and KDE
> and any other interested party can agree on.  This has
> proven to be surprisingly difficult.

Agreed.  Which is why I think the "where to put things" issue needs to
be attacked in an explicitly desktop-independent, distro-independent
way.  I'll take up that theme in my next post.
 
> I have two qualms with using XHTML for this purpose.  First,
> imposing a set of standard CSS classes would be hard.  Not
> impossible by any means.  But hard.  If writers are writing
> by hand, it's more work.  If they're using a graphical editor,
> that editor needs to be trained to do our documents.

Agreed.  
 
> Could we train an editor to our flavor of XHTML?  I'm sure we
> could, in theory.  I'm also sure we could write a really good
> graphical editor for whatever markup we're using.  But since
> we haven't yet, I'd like to make sure hand editing isn't too
> painful.
> 
> Well-designed source formats are easy to write.  There's no
> single best-designed source format.  It depends on the domain.

Agreed again.  On the other hand, if you design a custom XML application 
and bake it into a dedicated editor and processing tools, changing it
once you really understand the problem dmain will be hard -- so hard
that a desire to avoid such changes is very likely to distort your
thinking.
 
> We would be severely abusing XHTML by adding any implicit
> automatic text handling.

Agreed.  So, don't do that, then!

> > Again, I find myself in strong agreement with almost everything in 
> > <http://www.gnome.org/~shaunm/quack/mallard.xml>.  Shaun's dissection 
> > of the state of most on-line help ("Reading the interface back to 
> > me is not helpful") is particularly trenchant.
> 
> Dave Malcolm once wrote a script using Dogtail (a testing
> framework built off of our accessibility framework).  It
> would look at a window and automatically create DocBook
> that read the interface back.  The results were eerily
> similar to much of our documentation. 

Heh.  Yes, I believe this.
 
> I think I haven't done a very good job of keeping people
> informed of what I'm doing.  As a result, people aren't
> really grokking what I'm trying to do, or why XHTML or
> DocBook won't cut it.

You have not convinced me yet.  But I'm open to argument.
 
> My early, early ideas on this subject actually did involve
> subsetting DocBook.  But then to get everything we want,
> we'd need to subset and extend.  And we'd still be left
> with things we don't like.

I agree that if we discover a domain requirement to *extend* it,
XML-DocBook is a non-starter.
 
> DocBook, even a subset thereof, is hard to write.  No
> amount of subsetting is going to make mediaobject less
> obtuse.  And if it looks like DocBook, people will think
> it is DocBook.  So they'll try to use all their favorite
> elements.  If we don't include them, we screw with the
> heads of people who know DocBook. 

You're saying subsetting can't be made to work.  I don't buy it, not
on the basis of mere assertion that it will confuse people, because
I'm certain it wouldn't confuse *me*.

> DocBook is also incredibly hard to process correctly.
> One problem is that it's intentionally under-specified,
> allowing implementations to make decisions.  When you
> know your target processor (say, when you're writing
> a book for a specific publisher), that's fine.  But
> writing a document that can be deployed in different
> desktop environments and such is another thing.

This problem is hard but solvable.  I've used the solutions.
 
> Take, for example, xref.  The exact text of the xref
> element is not specified.  Combine this with supporting
> over 60 languages with dozens of rules for different
> grammatical roles, and you've got a recipe for trouble.

That means xref can't be in your subset.  I don't have a
problem with that.

> We could specify and solve each of these issues, but
> then we'd be left with something that kind of looks
> like DocBook, but isn't really DocBook anymore.  And
> I truly believe that would do more harm than good.

Not convinced yet.  Still listening.
-- 
		<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>