makedoc syntax (was Re: [AD] Screen destruction documentation update)

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-09-10, Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx> wrote:
> On 2005-09-09, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> > Can we get rid of any ` at least for the new makedoc?

I think the textual parts of new makedoc documents should be strict XML,
with no "enhancements".  You'd have to write <code>blah</code> or
<tt>blah</tt> instead of `blah'.  We also would drop non-standard stuff
like "&gt" without the semicolon, the automatic interpretation of "&" as
"&amp;", missing closing tags, etc.

However, section headings and such would retain the @-stuff syntax, so
makedoc format would become XML with @-stuff around to indicate the
document structure.

Ok, that is a slight lie.  Compare the following two examples.  There
are implicit <para>s in the first version compared with the second
version.  We could also NOT have implicit <para>s, in which case you
could really say that makedoc is a simple macro layer on top of XML.


    @sect1 Blah blah
  |
  | Here is some <tt>text</tt>.
  |
    @sect2 Blah blah blah
  |
  | Here is <em>more</em> text.
  |
    @@BITMAP *create_bitmap(int width, int height);
    @shortdesc Creates a memory bitmap.
  |
  | Creates a memory bitmap sized <var>width</var> by <var>height</var>.
  |
  | <codeblock>
  | BITMAP *b = create_bitmap(w, h);
  | </codeblock>
  |
    @retval
  | Returns a pointer to the created bitmap ...


And in XML,

    <sect1 title="Blah blah">
  |
  |   <para>Here is some <tt>text</tt>.</para>
  |
      <sect2 title="Blah blah blah">
  |
  |     <para>Here is <em>more</em> text.</para>
  |
        <function>
          <name>create_bitmap</name>
          <returnvalue>BITMAP *</returnvalue>
          <argumentlist>
            <argument>
              <name>width</name>
              <type>int</type>
            </argument>
            <argument>
              <name>height</name>
              <type>int</type>
            </argument>
          </argumentlist>
          <shortdesc>Creates a memory bitmap.</shortdesc>
          <description>
  |         <para>
  |           Creates a memory bitmap sized <var>width</var> by
  |           <var>height</var>.
  |         </para>
  |         <codeblock>
  |           BITMAP *b = create_bitmap(w, h);
  |         </codeblock>
          </description>
          <retval>
  |         <para>Returns a pointer to the created bitmap ...</para>
          </retval>
        </function>
      </sect2>
    </sect1>

Peter