docs/dev/pysource.dtd

   1 <!--
   2 ======================================================================
   3     Docutils Python Source DTD
   4 ======================================================================
   5 :Author: David Goodger
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This DTD has been placed in the public domain.
  10 :Filename: pysource.dtd
  11
  12 This DTD (document type definition) extends the Generic DTD (see
  13 below).
  14
  15 More information about this DTD and the Docutils project can be found
  16 at http://docutils.sourceforge.net/.  The latest version of this DTD
  17 is available from
  18 http://docutils.sourceforge.net/docs/dev/pysource.dtd.
  19
  20 The formal public identifier for this DTD is::
  21
  22     +//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML
  23 -->
  24
  25 <!--
  26 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  27     Parameter Entity Overrides
  28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29 -->
  30
  31 <!ENTITY % additional.section.elements
  32   " | package_section | module_section | class_section
  33     | method_section | function_section
  34     | module_attribute_section | function_attribute_section
  35     | class_attribute_section | instance_attribute_section ">
  36
  37 <!ENTITY % additional.inline.elements
  38   " | package | module | class | method | function
  39     | variable | parameter | type | attribute
  40     | module_attribute | class_attribute | instance_attribute
  41     | exception_class | warning_class ">
  42
  43 <!--
  44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  45     Generic DTD
  46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  47
  48 This DTD extends the Docutils Generic DTD, available from
  49 http://docutils.sourceforge.net/docs/ref/docutils.dtd.
  50 -->
  51
  52 <!ENTITY % docutils PUBLIC
  53     "+//IDN python.org//DTD Docutils Generic//EN//XML"
  54     "docutils.dtd">
  55 %docutils;
  56
  57 <!--
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  59     Additional Section Elements
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61 -->
  62
  63 <!-- package's namespace == __init__.py module's namespace -->
  64 <!ELEMENT package_section
  65     (package, fullname?, import_list?, %structure.model;)>
  66 <!ATTLIST package_section %basic.atts;>
  67
  68 <!ELEMENT module_section
  69     (module, fullname?, import_list?, %structure.model;)>
  70 <!ATTLIST module_section %basic.atts;>
  71
  72 <!ELEMENT class_section
  73     (class, inheritance_list?, fullname?, subclasses?,
  74      %structure.model;)>
  75 <!ATTLIST class_section %basic.atts;>
  76
  77 <!ELEMENT method_section
  78     (method, parameter_list?, fullname?, overrides?,
  79      %structure.model;)>
  80 <!ATTLIST method_section %basic.atts;>
  81
  82 <!ELEMENT function_section
  83     (function, parameter_list?, fullname?, %structure.model;)>
  84 <!ATTLIST function_section %basic.atts;>
  85
  86 <!ELEMENT module_attribute_section
  87     (attribute, initial_value?, fullname?, %structure.model;)>
  88 <!ATTLIST module_attribute_section %basic.atts;>
  89
  90 <!ELEMENT function_attribute_section
  91     (attribute, initial_value?, fullname?, %structure.model;)>
  92 <!ATTLIST function_attribute_section %basic.atts;>
  93
  94 <!ELEMENT class_attribute_section
  95     (attribute, initial_value?, fullname?, overrides?,
  96      %structure.model;)>
  97 <!ATTLIST class_attribute_section %basic.atts;>
  98
  99 <!ELEMENT instance_attribute_section
 100     (attribute, initial_value?, fullname?, overrides?,
 101      %structure.model;)>
 102 <!ATTLIST instance_attribute_section %basic.atts;>
 103
 104 <!--
 105     Section Subelements
 106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 107 -->
 108
 109 <!ELEMENT fullname
 110     (package | module | class | method | function | attribute)+>
 111 <!ATTLIST fullname %basic.atts;>
 112
 113 <!ELEMENT import_list (import_item+)>
 114 <!ATTLIST import_list %basic.atts;>
 115
 116 <!--
 117 Support ``import module``, ``import module as alias``, ``from module
 118 import identifier``, and ``from module import identifier as alias``.
 119 -->
 120 <!ELEMENT import_item (fullname, identifier?, alias?)>
 121 <!ATTLIST import_item %basic.atts;>
 122
 123 <!ELEMENT inheritance_list (class+)>
 124 <!ATTLIST inheritance_list %basic.atts;>
 125
 126 <!ELEMENT subclasses (class+)>
 127 <!ATTLIST subclasses %basic.atts;>
 128
 129 <!ELEMENT parameter_list
 130     ((parameter_item+, optional_parameters*) | optional_parameters+)>
 131 <!ATTLIST parameter_list %basic.atts;>
 132
 133 <!ELEMENT parameter_item
 134     ((parameter | parameter_tuple), parameter_default?)>
 135 <!ATTLIST parameter_item %basic.atts;>
 136
 137 <!ELEMENT optional_parameters (parameter_item+, optional_parameters*)>
 138 <!ATTLIST optional_parameters %basic.atts;>
 139
 140 <!ELEMENT parameter_tuple (parameter | parameter_tuple)+>
 141 <!ATTLIST parameter_tuple %basic.atts;>
 142
 143 <!ELEMENT parameter_default (#PCDATA)>
 144 <!ATTLIST parameter_default %basic.atts;>
 145
 146 <!ELEMENT overrides (fullname+)>
 147 <!ATTLIST overrides %basic.atts;>
 148
 149 <!ELEMENT initial_value (#PCDATA)>
 150 <!ATTLIST initial_value %basic.atts;>
 151
 152 <!--
 153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 154     Additional Inline Elements
 155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 156 -->
 157
 158 <!-- Also used as the `package_section` identifier/title. -->
 159 <!ELEMENT package (#PCDATA)>
 160 <!ATTLIST package
 161     %basic.atts;
 162     %reference.atts;>
 163
 164 <!-- Also used as the `module_section` identifier/title. -->
 165 <!ELEMENT module (#PCDATA)>
 166 <!ATTLIST module
 167     %basic.atts;
 168     %reference.atts;>
 169
 170 <!--
 171 Also used as the `class_section` identifier/title, and in the
 172 `inheritance` element.
 173 -->
 174 <!ELEMENT class (#PCDATA)>
 175 <!ATTLIST class
 176     %basic.atts;
 177     %reference.atts;>
 178
 179 <!-- Also used as the `method_section` identifier/title. -->
 180 <!ELEMENT method (#PCDATA)>
 181 <!ATTLIST method
 182     %basic.atts;
 183     %reference.atts;>
 184
 185 <!-- Also used as the `function_section` identifier/title. -->
 186 <!ELEMENT function (#PCDATA)>
 187 <!ATTLIST function
 188     %basic.atts;
 189     %reference.atts;>
 190
 191 <!--
 192 ??? Use this instead of the ``*_attribute`` elements below?  Add a
 193 "type" attribute to differentiate?
 194
 195 Also used as the identifier/title for `module_attribute_section`,
 196 `class_attribute_section`, and `instance_attribute_section`.
 197 -->
 198 <!ELEMENT attribute (#PCDATA)>
 199 <!ATTLIST attribute
 200     %basic.atts;
 201     %reference.atts;>
 202
 203 <!--
 204 Also used as the `module_attribute_section` identifier/title. A module
 205 attribute is an exported module-level global variable.
 206 -->
 207 <!ELEMENT module_attribute (#PCDATA)>
 208 <!ATTLIST module_attribute
 209     %basic.atts;
 210     %reference.atts;>
 211
 212 <!-- Also used as the `class_attribute_section` identifier/title. -->
 213 <!ELEMENT class_attribute (#PCDATA)>
 214 <!ATTLIST class_attribute
 215     %basic.atts;
 216     %reference.atts;>
 217
 218 <!--
 219 Also used as the `instance_attribute_section` identifier/title.
 220 -->
 221 <!ELEMENT instance_attribute (#PCDATA)>
 222 <!ATTLIST instance_attribute
 223     %basic.atts;
 224     %reference.atts;>
 225
 226 <!ELEMENT variable (#PCDATA)>
 227 <!ATTLIST variable
 228     %basic.atts;
 229     %reference.atts;>
 230
 231 <!-- Also used in `parameter_list`. -->
 232 <!ELEMENT parameter (#PCDATA)>
 233 <!ATTLIST parameter
 234     %basic.atts;
 235     %reference.atts;
 236     excess_positional  %yesorno;  #IMPLIED
 237     excess_keyword     %yesorno;  #IMPLIED>
 238
 239 <!ELEMENT type (#PCDATA)>
 240 <!ATTLIST type
 241     %basic.atts;
 242     %reference.atts;>
 243
 244 <!ELEMENT exception_class (#PCDATA)>
 245 <!ATTLIST exception_class
 246     %basic.atts;
 247     %reference.atts;>
 248
 249 <!ELEMENT warning_class (#PCDATA)>
 250 <!ATTLIST warning_class
 251     %basic.atts;
 252     %reference.atts;>
 253
 254 <!--
 255 Local Variables:
 256 mode: sgml
 257 indent-tabs-mode: nil
 258 fill-column: 70
 259 End:
 260 -->