<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||
     ==nonstructural heading==

     blank lines become paragraph breaks

     # 1
        # 1.1
           # 1.1.1

     - 
        -
           -

     \\     -   backslash
     \0x??  -   unicode
     \amp
     \lt
     \gt
     \quot
     \apos

     wiki plugins: page topology (who points here, orphaned pages, statistics, document upload, etc)
                   http://en.wikipedia.org/wiki/Special:Specialpages

     structured ebnf content?
     http://www.docbook.org/tdg/en/html/docbook.html

  </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>
