doc/ibex-doc.xml

   1 <ibex-doc title="The Ibex Documentation Format" author="Adam Megacz" email="adam@ibex.org">
   2
   3 <section title="Introduction">
   4
   5   <section title="Another Document Format?">
   6
   7   Foo.
   8
   9   </section>
  10
  11   <section title="Goals">
  12
  13     <heading title="Applications"/>
  14
  15     IbexDoc targets four primary documentation tasks:
  16
  17     <list>
  18
  19         Books, Manuals and references
  20
  21         Articles
  22
  23         Literate Programming (documentation embedded in source code)
  24
  25         Presentation Slides
  26
  27         Web pages, including WikiWebs
  28
  29     </list>
  30
  31     <heading title="Separating Semantics from Aesthetics"/>
  32
  33     The goal of separating <i>markup</i> from <i>content</i> has been
  34     around for a long time in the document world.  For some reason it
  35     never succeeded.  The problem is that:
  36
  37     <list>
  38         The purpose of content is to convey semantic meaning.
  39
  40         Some markup and formatting carries semantic meaning.
  41     </list>
  42
  43     For example, consider italicization.  Adding or removing
  44     italicization can actually affect the meaning of a piece of text.
  45     Therefor italicization (or rather "emphasis") is part of the
  46     <i>content</i> of a document.
  47
  48     IbexDoc recognizes this and does not attempt to use XML for
  49     anything that might carry semantic meaning.  Effectively, you can
  50     remove all XML tags from an IbexDoc file without altering the
  51     meaning of the text (although it might be rather hard to discern
  52     the meaning with all the text jumbled together!)
  53
  54   </section>
  55 </section>
  56   <section title="Tags">
  57
  58       <definition term="doc">
  59           (title subtitle logo license options(toc,index) logo)
  60           </definition>
  61
  62       <definition term="author">
  63           (email, name)
  64           </definition>
  65
  66       <definition term="abstract">
  67                changes
  68           </definition>
  69
  70       <definition term="appendix">
  71           (contains sections, must appear once at EOF)
  72           </definition>
  73
  74       <definition term="section">
  75           (title)
  76           </definition>
  77
  78       <definition term="heading">
  79           ..
  80           </definition>
  81
  82       <definition term="definition">
  83           ..
  84           </definition>
  85
  86       <definition term="property">
  87           (a different kind of list?)
  88           </definition>
  89
  90       <definition term="remark">
  91           ..
  92           </definition>
  93
  94       <definition term="image">
  95           ..
  96           </definition>
  97
  98       <definition term="figure">
  99           ..
 100           </definition>
 101
 102       <definition term="code">
 103           ..
 104           </definition>
 105
 106       <definition term="pre">
 107           ..
 108           </definition>
 109
 110       <definition term="link">
 111           ..
 112           </definition>
 113
 114       <definition term="math">
 115           ..
 116           </definition>
 117
 118       <definition term="define">
 119           ..
 120           </definition>
 121
 122       <definition term="footnote">
 123           ..
 124           </definition>
 125
 126   </section>
 127
 128   <section title="Text Formatting">
 129
 130   <pre>
 131
 132      **italics**
 133      __boldface__
 134      ||typewriter||
 135      ==nonstructural heading==
 136
 137      blank lines become paragraph breaks
 138
 139      # 1
 140         # 1.1
 141            # 1.1.1
 142
 143      -
 144         -
 145            -
 146
 147      \\     -   backslash
 148      \0x??  -   unicode
 149      \amp
 150      \lt
 151      \gt
 152      \quot
 153      \apos
 154
 155      wiki plugins: page topology (who points here, orphaned pages, statistics, document upload, etc)
 156                    http://en.wikipedia.org/wiki/Special:Specialpages
 157
 158      structured ebnf content?
 159      http://www.docbook.org/tdg/en/html/docbook.html
 160
 161   </pre>
 162
 163   </section>
 164
 165   <section title="To Do">
 166       <list>
 167           tables
 168
 169           plugins (charts, graphs, diagrams)
 170
 171           wiki-style links
 172
 173           slides
 174           <list>
 175               slide breaks
 176
 177               overlays
 178
 179               2-column
 180
 181               different diagram layouts
 182
 183               color
 184
 185               persistent outline
 186
 187               watermark/logo
 188           </list>
 189       </list>
 190
 191       <heading title="JavaDoc Features We Like"/>
 192       <pre>
 193
 194           /** */
 195           ///
 196           ///&lt;
 197           @param
 198           @throws
 199           @see
 200           @link, autolinking (wiki-style?) of other classes/modules
 201           @return
 202           @deprecated
 203           @since
 204           @author?
 205           package-level overview (but it's lame to put it in a separate file)
 206           inheritance
 207
 208       </pre>
 209   </section>
 210
 211 </ibex-doc>