1 <ibex-doc title="The Ibex Documentation Format" author="Adam Megacz" email="adam@ibex.org">
3 <section title="Introduction">
5 <section title="Another Document Format?">
11 <section title="Goals">
13 <heading title="Applications"/>
15 IbexDoc targets four primary documentation tasks:
19 Books, Manuals and references
23 Literate Programming (documentation embedded in source code)
27 Web pages, including WikiWebs
31 <heading title="Separating Semantics from Aesthetics"/>
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:
38 The purpose of content is to convey semantic meaning.
40 Some markup and formatting carries semantic meaning.
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.
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!)
56 <section title="Tags">
58 <definition term="doc">
59 (title subtitle logo license options(toc,index) logo)
62 <definition term="author">
66 <definition term="abstract">
70 <definition term="appendix">
71 (contains sections, must appear once at EOF)
74 <definition term="section">
78 <definition term="heading">
82 <definition term="definition">
86 <definition term="property">
87 (a different kind of list?)
90 <definition term="remark">
94 <definition term="image">
98 <definition term="figure">
102 <definition term="code">
106 <definition term="pre">
110 <definition term="link">
114 <definition term="math">
118 <definition term="define">
122 <definition term="footnote">
128 <section title="Text Formatting">
135 ==nonstructural heading==
137 blank lines become paragraph breaks
155 wiki plugins: page topology (who points here, orphaned pages, statistics, document upload, etc)
156 http://en.wikipedia.org/wiki/Special:Specialpages
158 structured ebnf content?
159 http://www.docbook.org/tdg/en/html/docbook.html
165 <section title="To Do">
169 plugins (charts, graphs, diagrams)
181 different diagram layouts
191 <heading title="JavaDoc Features We Like"/>
200 @link, autolinking (wiki-style?) of other classes/modules
205 package-level overview (but it's lame to put it in a separate file)