Duck season! Rabbit season! Mallard season!

[esr thyrsus com (Eric S. Raymond)]

(Please forgive the cheesy Warner Brothers reference in the subject.)

INTRODUCTION

This is a critique of the Mallard proposal found at an absurdly long
URL for which one might as well google.  I'm uttering it because I
have been thinking hard about a different, GNOME-independent
architecture for handling documentation that would solve a
slightly different set of problems.

My ideas (about which more later) aren't flatly incompatible with
Mallard, but they do suggest that some of its ambitions could use a
bit of trimming and refocusing.  What I'd like to do, ultimately,
is keep the good ideas from Mallard and mate them to some I'm not
going to specify just yet.

ISSUES WE CAN...ER...DUCK

I'm going to start by trying to factor out a couple of issues.  

One: choice of documentation license.  This is a political brouhaha we
don't have to get into before writing and deploying better software.

Two: a new documentation editor. While I applaud the goal, I think this
simply is not worth solving as a one-off with the markup structure
wired in.  What we need is a schema-driven XML editor; the schema might be
DocBook, or it might be SMNL (Shaun's Mystical New Language), but baking
either schema into the editor code would be, IMHO, nuts.  If for no other
reason than that it would hugely raise the costs of modifying and
extending the language once we actually understand the problem domain.

Three: Content issues -- the fresh look at the tone and style, etc.
If the new tools seriously constrain what we do with "style", or
vice-versa, something is badly wrong.  Better to treat these as
orthogonal issues and not get mugged later by our own assumptions.

EASY STUFF

This leaves the following bullet items (quoted) from before we get 
into Shaun's detailed notes:

* A markup language

* A standard place and way to keep docs

* The docs themselves: topic-based rather than monolithic documents. 
  And cross-linked up the wazoo of course.

Let me start with the last first.  The single novel idea in this
proposal I agree with most strongly is Shaun's vision of topic-based
documentation, "cross-linked up the wazoo".  However (and this is an
important caveat) this has value mainly as an organizing principle for
*new* documentation.  There are other, major problem -- like making
legacy documentation (100,000 man pages) accessible and searchable --
that it doesn't touch.  (My own ideas are more focused on that.)

A standard place and way to keep docs.  Agreed, this is a significant
issue.  Also agreed that ScrollKeeper needs to be taken out behind the
barn and shot.  I haven't looked at Spoon in detail yet, but I'm quite
willing to believe that it could be the basis of something better.  In
fact a working son-of-Scrollkeeper would also be a huge boost towards
my somewhat different goals, so I'd love to see Spoon succeed.

A MARKUP LANGUAGE

A markup language.  This is where I start to differ.  I understand
the attraction of designing such things -- I'm prone to it myself --
but I also know that unless one is *very* careful such projects tend to
wander deep into the weeds and get lost in over-elaboration.

So my first real challenge to the Mallard plan is this:  Why couldn't
SMNL be a well-defined subset of XHTML+CSS?  Each node would be a page.
If you need more inlines than XHTML gives you, declare a CSS class with 
a standardized interpretation.  You'd get (non-CALS) tables for free.

This approach would have huge advantages in terms of the amount of code
(browsers, editors, validators, translators) that nobody would have to
write.  Transclusion could be handled by fairly lightweight interpreters
for PIs, something like the way DHTML worked.

I see no requirement in "A Markup Language" that would block this approach.

RETHINKING HELP

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.

And again, I begin to differ only on the language-design issues.  I think
this proposal is rushing into playing with novel XML way too soon.  
Taking the first one of his examples, I don't see what

<topic id="fe">
  <info>
    <!-- Metadata here -->
  </info>
  <title>Fe</title>
  <!-- Block-level content here -->
  <!-- Sectioning content here -->
</topic>

would gain us over this bog-standard XHTML:

<html id="fe">
  <head>
    <!-- Metadata here -->
  </head>
  <body>
    <title>Fe</title>
    <!-- Block-level content here -->
    <!-- Sectioning content here -->
  </body>
</html>

I also think that use of XML-DocBook is dismissed too quickly.
While it's certainly the case that the whole of DocBook is too big for
this application, I'd like to see a serious swing taken at
*subsetting* it for this purpose before any new schema gets defined.

Further down, I bridle a bit at the criticism that XML-DocBook is 
"too semantic".  That's not a bug, it's a feature that we're going to
want back rather badly some day when our search algorithms start 
relying on a richer ontology than HTML's.

I actually have a path forward to suggest rather than just criticizing.

REFENTRY IS YOUR FRIEND

In the bullet point "Structural markup doesn't fit our needs.", it seems
to me that Shaun is missing what could be done with the RefEntry
document type.

I'm intimately familiar with it, because I wrote a program called 
doclifter that lifts manual page sources to RefEntry documents
with over a 90% success rate (actually over 99% with trivial fixes
for broken man markup).  

One possibility is that the Mallard markup should be a subset of DocBook
that uses a subset of RefEntry as the main topic-node type.  Again this
would be a huge benefit in terms of code nobody has to write.

I'll lay out my own ideas, and how they dovetail with the Mallard
proposal, in a separate post.
-- 
		<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>