ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Re: sandbox gendoc
Date Thu, 12 Jan 2006 23:51:30 GMT
>> Yes, DocBook, also a standard, is indeed very verbose and doesn't seem
>> to have the favor among commiters.
> I think think docbook is interesting but something that should be hidden
> from users by a docbook editor, not handwritten. Also its too low-level;
> I want to mark something as a <task>, not as a bit of code.

Agree 100%.  I went through exactly this thought process myself.

I wanted to reuse Docbook as much as possible, but wanted a custom schema to
represent things like Design Patterns, Business Letters, Resumes, etc.

I found the answer: use Docbook 5.0 (currently in beta).  Docbook5 uses
RelaxNG schemas and namespaces rather than DTDs.
I use Jing for validation, though libxml and Sun MSV work fine, too.

Each schema (pattern, letter, resume, ant task...) is implemented using a
small relaxng file that customizes docbook.rng and a small XSLT that
customizes docbook.xsl.  The customizations are usually less than 100 LOC!

Here is a cut-down example, for a letter:

  <include href="docbook.rng">
      <element name="l:letter">
        <a:documentation>A business letter</a:documentation>
        <element name="l:salutation"><text/></element>
        <element name="l:body">
          <a:documentation>The main body of the letter</a:documentation>
          <oneOrMore><ref name="db.all.blocks"/></oneOrMore>

This may be drifting off-topic.  The main point I wanted to make is
that it is possible to have your custom schema but reuse Docbook as well,
via namespaces and relaxng with relatively little effort.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message