reference updates, including diagrams

[org.ibex.core.git] / doc / ibex-doc.xml

diff --git a/doc/ibex-doc.xml b/doc/ibex-doc.xml
new file mode 100644 (file)
index 0000000..05e49d9
--- /dev/null
+++ b/doc/ibex-doc.xml
@@ -0,0 +1,204 @@
+<ibex-doc title="The Ibex Documentation Format" author="Adam Megacz" email="adam@ibex.org">
+
+<section title="Introduction">
+
+  <section title="Another Document Format?">
+
+  Foo.    
+
+  </section>
+
+  <section title="Goals">
+
+    <heading title="Applications"/>
+
+    IbexDoc targets four primary documentation tasks:
+
+    <list>
+
+        Books, Manuals and references
+
+        Articles
+
+        Literate Programming (documentation embedded in source code)
+
+        Presentation Slides
+
+        Web pages, including WikiWebs
+
+    </list>
+
+    <heading title="Separating Semantics from Aesthetics"/>
+
+    The goal of separating <i>markup</i> from <i>content</i> has been
+    around for a long time in the document world.  For some reason it
+    never succeeded.  The problem is that:
+
+    <list>
+        The purpose of content is to convey semantic meaning.
+
+        Some markup and formatting carries semantic meaning.
+    </list>
+
+    For example, consider italicization.  Adding or removing
+    italicization can actually affect the meaning of a piece of text.
+    Therefor italicization (or rather "emphasis") is part of the
+    <i>content</i> of a document.
+
+    IbexDoc recognizes this and does not attempt to use XML for
+    anything that might carry semantic meaning.  Effectively, you can
+    remove all XML tags from an IbexDoc file without altering the
+    meaning of the text (although it might be rather hard to discern
+    the meaning with all the text jumbled together!)
+
+  </section>
+</section>
+  <section title="Tags">
+
+      <definition term="doc">
+          (title subtitle logo license options(toc,index) logo)
+          </definition>
+
+      <definition term="author">
+          (email, name)
+          </definition>
+
+      <definition term="abstract">
+               changes
+          </definition>
+
+      <definition term="appendix">
+          (contains sections, must appear once at EOF)
+          </definition>
+
+      <definition term="section">
+          (title)
+          </definition>
+
+      <definition term="heading">
+          ..
+          </definition>
+
+      <definition term="definition">
+          ..
+          </definition>
+
+      <definition term="property">
+          (a different kind of list?)
+          </definition>
+
+      <definition term="remark">
+          ..
+          </definition>
+
+      <definition term="image">
+          ..
+          </definition>
+
+      <definition term="figure">
+          ..
+          </definition>
+
+      <definition term="code">
+          ..
+          </definition>
+
+      <definition term="pre">
+          ..
+          </definition>
+
+      <definition term="link">
+          ..
+          </definition>
+
+      <definition term="math">
+          ..
+          </definition>
+
+      <definition term="define">
+          ..
+          </definition>
+
+      <definition term="footnote">
+          ..
+          </definition>
+
+  </section>
+
+  <section title="Text Formatting">
+
+  <pre>
+
+     **italics**
+     __boldface__
+     ||typewriter||
+
+     blank lines become paragraph breaks
+
+     # 1
+        # 1.1
+           # 1.1.1
+
+     - 
+        -
+           -
+
+     \\     -   backslash
+     \0x??  -   unicode
+     \amp
+     \lt
+     \gt
+     \quot
+     \apos
+
+  </pre>
+
+  </section>
+
+  <section title="To Do">
+      <list>
+          tables
+
+          plugins (charts, graphs, diagrams)
+
+          wiki-style links
+
+          slides
+          <list>
+              slide breaks
+
+              overlays
+
+              2-column
+
+              different diagram layouts
+
+              color
+
+              persistent outline
+
+              watermark/logo
+          </list>
+      </list>
+
+      <heading title="JavaDoc Features We Like"/>
+      <pre>
+
+          /** */
+          ///      
+          ///&lt;
+          @param
+          @throws
+          @see
+          @link, autolinking (wiki-style?) of other classes/modules
+          @return
+          @deprecated
+          @since
+          @author?
+          package-level overview (but it's lame to put it in a separate file)
+          inheritance
+
+      </pre>
+  </section>
+    
+</ibex-doc>
\ No newline at end of file