15. How to write Documentation

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


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


name Name of that tag


name Name of that attribute