<!--
   Plain Old Documentation XML ("PXML") version 0.01 DTD
   POD is the documentation format invented for documenting Perl modules.
   ====EXPERIMENTAL====
   Sean M. Burke, 2001-04-22, sburke@cpan.org
   Namespace = http://www.perl.com/CPAN/authors/id/S/SB/SBURKE/pxml_0.01.dtd
   This DTD module is denoted by these identifiers:
    PUBLIC "-//Sean Michael Burke//DTD PXML 0.01//EN"
    SYSTEM "http://www.perl.com/CPAN/authors/id/S/SB/SBURKE/pxml_0.01.dtd"
   Cf. the Perl module Pod::PXML, available in CPAN, http://search.cpan.org
-->

<!-- It so happens that all the content-models came out
  as either (#PCDATA), (#PCDATA | foo | bar)*, or
  (foo | bar)*.  That makes validation simple.
-->

<!ELEMENT pod (head1|head2|head3|head4|p|pre|list|for)*>
<!-- POD is short for "Plain Old Documentantion" -->
<!ATTLIST pod
  xmlns CDATA #FIXED 'http://www.perl.com/CPAN/authors/id/S/SB/SBURKE/pxml_0.01.dtd'
>

<!ENTITY % Style " b | i | c | x | f | s | link ">

<!-- ==== BLOCK-LEVEL ELEMENTS ==== -->

<!ELEMENT head1 (#PCDATA | %Style; )* >
<!ELEMENT head2 (#PCDATA | %Style; )* >
<!ELEMENT head3 (#PCDATA | %Style; )* >
<!ELEMENT head4 (#PCDATA | %Style; )* >
<!ELEMENT p     (#PCDATA | %Style; )* > <!-- a normal paragraph -->

<!ELEMENT pre (#PCDATA) >  <!-- a verbatim/preformatted paragraph -->
<!ATTLIST pre xml:space (preserve) #FIXED 'preserve' >
<!-- example:
  <pre><![CDATA[
    $tree->load_file      ( $file, %options)
    $tree->load_fh        ( $fh  , %options);
  ]]></pre>
-->

<!ELEMENT list (item|p|pre|list|for)* > <!-- "=over ...stuff... =back" -->
<!ATTLIST list indent CDATA #IMPLIED> <!-- where you put the 8 in "over 8" -->
<!-- Good advice: Have at least one p, pre, or item per list -->
<!-- Sane advice: If the first thing in the list in a p, don't have items -->

<!ELEMENT item (#PCDATA | %Style;)*  > <!-- "=item ...label..." -->

<!ELEMENT for (#PCDATA) > <!-- I guess? -->
<!-- TODO: change that to be a block-level container, and use
  PIs for unprocessed content -->

<!ATTLIST for target CDATA #IMPLIED>
<!-- Example:
  <for target="html"><![CDATA[
    <img alt="stuff" src="foo.png" height=123 width=456">
  ]]></for>
-->

<!-- ==== STYLE ELEMENTS ==== -->

<!ELEMENT link (#PCDATA | %Style;)* >
<!ATTLIST link
 page       CDATA #IMPLIED
 section    CDATA #IMPLIED
>
<!-- Sanity constraint: Don't have an empty link element. -->
<!-- Sanity constraint: Don't nest your link elements -->
<!-- Sanity constraint: Every link element must have a page attribute,
       or a section attribute, or both. -->
<!--
The correspondences explained:
   L<...|Foo>       == <link page="Foo">...</link>
   L<...|Foo/"bar"> == <link page="Foo" section="bar">...</link>
   L<...|Foo/bar>   ==   (ditto)
   L<...|/"bar">    == <link section="bar">...</link>

And, incidentally,
   L<Foo>           becomes <link page="Foo">Foo</link>
Current formatters are inconsistent in how L<Foo> is to be rendered;
The current Pod::Text says "the Foo man page",
-->

<!-- And now the other style elements... -->
<!ELEMENT b (#PCDATA | %Style;)* > <!-- bold -->
<!ELEMENT i (#PCDATA | %Style;)* > <!-- italic -->
<!ELEMENT c (#PCDATA | %Style;)* > <!-- code (monospace) -->
<!ELEMENT f (#PCDATA | %Style;)* > <!-- filename (monospace?) -->
<!ELEMENT x (#PCDATA | %Style;)* > <!-- index-point -->
<!ELEMENT s (#PCDATA | %Style;)* > <!-- spaces are nonbreaking -->
<!-- Sanity constraint: don't nest your x elements -->

<!-- Note: no, there's nothing in PXML corresponding to Z<> -->

<!-- THE END -->

