Re: Wiki user guide

[Shaun McCance <shaunm gnome org>]

On Fri, 2006-07-07 at 15:16 -0400, Peter Williams wrote:
> On Fri, 2006-07-07 at 13:45 -0500, Shaun McCance wrote:
> > NAME MY XML FORMAT!
> 
> How about the ... Help Text Markup Language. Shouldn't cause any
> confusion there!
> 
> Seriously, I'm really interested in helping Mallard get off the
> ground.
> Are things concrete enough for people other than you to start pitching
> in yet? I'd specifically be interested in reading a DTD / schema /
> whatever of the format if such a thing exists. (I've always been
> vaguely
> interested in writing a doc editor, since I think such a tool would
> vastly lower the barrier to the doc writing process.)

I've recently started putting together a RELAX NG schema.
Rather than trying to embed documentation into the RNG,
I've opted to embed the RNG into the documentation.  That
is, I've been writing a document (in Mallard itself, no
less) which has embedded <code> elements which provide
the schema in RNG's compact syntax.

It's just on my local machine right now.  I should commit
this all to gnome-doc-utils, and other people could get
involved.  Here's a sample:

<section id="figure">
<title>Media Objects and Figures</title>

<p>The <code>media</code> element is used to place multimedia objects
in the document.  Since Help does not mix block and inline content,
the <code>media</code> element can be used in either context without
ambiguity.</p>

<remark><p>Role is free-form, but we should list best practice uses
such as "photo" and "screenshot".  Medias chain, similar to XHTML 2.
Figures wrap one or more medias with an optional title (top) and
optional caption (bottom).</p></remark>

<code>help.block.media = element media {
  help.attr.href,
  help.attr.mime,
  help.attr.media.role ?,
  ( help.block.media | help.inline.mixed )
}</code>

<code>help.attr.media.role = attribute role { help.FIXME }</code>

<code>help.block.figure = element figure {
  help.block.title ?,
  help.block.media +,
  help.block.caption ?
}</code>
</section>