15. How to write Documentation

Wed, 10/13/2010 - 10:41 — frisonim

15.1: Setup

Check out the ch.ethz.jopera.help documentation plugin. The source XML file is called jop.xml - the bitmap pictures (in .PNG format) are kept in html/figs and they are converted to Postscript automatically by the Ant scripts/build.xml file that you should use
to compile the text. Since this is done with some Python/Imagemagik you should configure some properties of this build.xml file to find them.

Note:
You do not have to close the Eclipse Help window to see your changes, just refresh the embedded browser after the Ant script is done

15.2: XML Reference

The list of xml-tags provided for logical (semantical) structuring of this documentation

Note:
Usually the description/content of an element is specified as the content of the provided tag

<doc>
The root-tag enclosing the entire help-document

<part>
Main part of the documentation

name
Name/Title of that part

<chap>
Chapter, sectioning parts

name
Title of that chapter

desc
Optional description of that chapter

<sec>
Section, for sectioning chapters

name
Title of that section

break
Optional, if value is "yes", a page-break is set before that section (where the output-document has pages at all - i.e. the pdf-version)

<subsec>
Subsection, for sectioning sections

name
Title of that subsection

<subsubsec>
Subsubsection, for sectioning subsections

name
Title of that subsubsection

<list>
List, its items will show a (bulleted list) - see item below

<item>
List-item, one point (bullet) of the list - see list above

<steps>
Encloses a nubered list for step-by-step descriptions

<step>
One numbered step - see steps above

type
Optional attribute for specifying the kind of the step , its value is put in boldface with an appended colon in front of the step-description

<menu>
An entry of the mainmenu, produces a table for its menuitems - see menuitem below

name
Caption of the menu entry

<menuitem>
An entry in a menu - see above

name
Caption of the menu entry

<menucomment>
A comment subsectioning the table of menuitems

type
(optional)

option - Sets introductory phrase on optionality of the following menuitems

<code>
For code segments, is verbatim (all signs allowed, no escaping necessary)
(For rapid highlighting of some word/term just enclose with apostrophes)

<fig>
For figures/pictures

file
The source file of the figure

text
The figure description

label
If specified, this is the label for references from other positions in the document. If not specified, a label with name fig_ plus the file-name of the figure is generated.

width
Optional width of the figure - can be specified relatively to the page-width (number and percentage-sign - recommended) or absolutely in points (just a number) - The html-translation ignores this while simply putting the figure in original size

<note>
Annotation

<ref>
Reference to some label defined elsewhere as attribute of a fig , sec , subsec or subsusec -tag

label
The label referred to

type
Can be specified for section-references: see - produces a see-phrase for that ref

<url>
Hyper-link, just as single-tag like

<url></url>

href
The URL

<footnote>
Footnote

<faq>
Construct for the usual question-answer pattern. Expects a sequence of question and answer -pairs as child-tags

<question>
FAQ-question (simple text), a question-mark is appended

<answer>
FAQ-answer, in contrary to the question -tag other elements (tags) are allowed