The top level document
of the document
is in documentname.in
(copied to documentname.xml
by the build script).
Each chapter (or
preface, glossary, appendix etc) is a separate file, defined as a
system entity and included from this top level
file.
There are some useful entities defined for common terms in the beginning of this top level document.
E.g. 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.in
file
into what.ever
in
the documentname.xml
file.
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 separate by underscore. 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 CVS.
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
what sentences has been changed and what has not in the diff
reports from CVS.
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