- The top level document of the document is in documentname.xml. Each chapter (or preface, glossary, appendix etc) of the cookbook and the quickguide is a separate file, defined as a system entity and included from this top level file. The manual is one big file: manual.xml
- There may be some useful entities defined for common terms in the beginning of this top level document.
E.g. for the cookbook: The use of &argouml; will ensure consistent naming of the product (ArgoUML) and allow us to change it later (to Argo/UML, Argouml or whatever).
- In the build script there is some magic that translates @tagname@ to a real value. E.g. @VERSION@ in the documentname.xml file into 0.16.
- XML comments are used throughout to explain what various sections are trying to achieve.
- Cross-referencing requires use of id. attributes. Many of these used in the manual are of the following format, but the use of this format is not obligatory any more.
- To avoid confusion, use a prefix of ch. for chapter, app. for appendix, s. for sect1 through sect5, fig. for figure, tab. for table and gl for glossentry.
- A second prefix of tut. or ref. is allowed to distinguish tutorial and reference material. The remainder of the tag should be descriptive, but concise with words separated by underscores. Where a graphic is involved this remainder should correspond to the file name. For example fig.ref.navigation_pane for a figure showing the explorer, with the diagram in navigation_pane.gif
- There is one exception to this and that is the description of the critics in the manual. Each paragraph about a critic is instead marked with critics. followed by the classname implementing that critic. The reason for this is that the intention is to have the manual accessable when pressing the Help button on that critic. Generating a link to the correct place in the manual is easier if the classname need not undergo some kind of textual transformation and the implementation doesn't care if a a specific critic is described in a sect1, sect2, sect3, or sect4. Reorganizing the manual would otherwise affect also the java code. The conversion to the correct tagname or really the correct URL is currently implemented in the defaultMoreInfoURL() method in the org.argouml.cognitive.critics.Critic class.
- Only use glossterm (for the term or its abbreviation/acronym), glossdef and glossseealso within glossentry. Other entries are not implemented in the style sheets and so do not appear in the glossary!
- Use spaces rather than tabs. Tabs are generally set so large the text moves over to the right of the page, and are not set the same everywhere (emacs uses 8 spaces, some MS editors use 6 spaces), making documents unreadable between users.
- The indentation size is 2.
- Make a new line after each sentence or before expressions. The Docbook source is source that is handled by subversion. When structuring the text the parts are paragraphs, sentences and words. By having each sentence on a line of its own it is easier to see which sentences have been changed and which have not in the diff reports from subversion. The contributions that Jeremy Bennet did for the 0.10 User Manual are not written like this. Change it while changing the paragraphs.
- All block graphics should be encapsulated within figure, allowing reference from around the text. Set attribute float to 1 to allow the figure to float (makes life easier for printed version).
- All block graphics should be provided through mediaobject and provided with both an imageobject and comprehensive description in a textobject. This gives the potential of meaningful content where a diagram cannot be displayed for any reason. Where appropriate the mediaobject should be wrapped by screenshot.
- Inline graphics can be done through inlinegraphic, rather inlinemediaobject. A textual alternative is of little value in these circumstances. Where appropriate the mediaobject should be wrapped by guiicon