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
 136      blank lines become paragraph breaks
 137
 138      # 1
 139         # 1.1
 140            # 1.1.1
 141
 142      -
 143         -
 144            -
 145
 146      \\     -   backslash
 147      \0x??  -   unicode
 148      \amp
 149      \lt
 150      \gt
 151      \quot
 152      \apos
 153
 154   </pre>
 155
 156   </section>
 157
 158   <section title="To Do">
 159       <list>
 160           tables
 161
 162           plugins (charts, graphs, diagrams)
 163
 164           wiki-style links
 165
 166           slides
 167           <list>
 168               slide breaks
 169
 170               overlays
 171
 172               2-column
 173
 174               different diagram layouts
 175
 176               color
 177
 178               persistent outline
 179
 180               watermark/logo
 181           </list>
 182       </list>
 183
 184       <heading title="JavaDoc Features We Like"/>
 185       <pre>
 186
 187           /** */
 188           ///
 189           ///&lt;
 190           @param
 191           @throws
 192           @see
 193           @link, autolinking (wiki-style?) of other classes/modules
 194           @return
 195           @deprecated
 196           @since
 197           @author?
 198           package-level overview (but it's lame to put it in a separate file)
 199           inheritance
 200
 201       </pre>
 202   </section>
 203
 204 </ibex-doc>