Introduction
The purpose of this document is to define how to write documentation using XDoc format. This
has been chosen as the standard
This format has been chosen because:
- The files versions are managed together with the source code in SCM
- The diff is easily readable
- It will be easy, if another format is chosen, to do a migration
-
The rendered result is easy to ge using the Maven site plugin
- It is easy to edit, using any text editor
- It is an open standard
In order to have a common understanding of the documentation source, and in order to make easy the migration
to another format (DocBook, lets say...), we have to follow common wrting rules such:
- Common basic template
- XDoc basic rules knowledge
- Limited subset of XHTML tags
- Limited subset of style classes
- Formating rules
Basic Template
Hereafter you'll find a basic
template
to copy / paste in a new file to start a new documentation.
XDoc basic rules
XDoc is mainly few elements and XHTML content
XDoc elements
We will only list here the element to use in the body of the document, e.g. the one you can use in the
body element.. Other elements, like
document, head, title, author... are contained in
the
document template.
| Name |
Description |
| section |
Define a section in you documentation. A section can only contains subsections |
| subsection |
Define a sub-section, and must be nested into a section element. It cannor contains subsection
nor section elements. If you need to add a sub-sub-section, consider splitting your documentation
in several files and then raise your sections hierarchy |
| source |
To present source code or preformatted text, program listing, etc...
|
Rules
- Don't nest block level elements, like <ul> element in <p>
- Don't nest <source> element in paragraphs (<p> element)
- Put inline elements inside block level elements, e.g. put <a> in block level element
-
XHTML rule: all tags must be closed. Empty tags must be written using the empty tag notation:
<element/>
- XHTML rule: all elements and attributes must be lowercase.
XHTML tags
Excluding XDoc specific elements, writting XDoc is basically writting XHTML. In order to avoid painful reading
of XDoc source, and painful migration to another format, we must limit or usage of available XHTML tags. All
the tags not list here must not be used. Most of the time, it is because they have a style instead
of structure connotation.
| Element |
Description |
Allowed attributes |
| p |
paragraph |
- |
| ul |
list |
- |
| ol |
ordered list |
- |
| li |
list item |
- |
| table |
table definition |
- |
| tr |
table row |
- |
| th |
table header |
- |
| td |
table cell |
- |
| a |
link |
href, target |
| img |
image |
src |
| em |
Indicates emphasis. |
- |
| strong |
Indicates stronger emphasis. |
- |
| cite |
Contains a citation or a reference to other sources. |
- |
| dfn |
Indicates that this is the defining instance of the enclosed term. |
- |
| var |
Indicates an instance of a variable or program argument. |
- |
| abbr |
Indicates an abbreviated form (e.g., WWW, HTTP, URI, Mass., etc.). |
title |
| accronym |
Indicates an acronym (e.g., WAC, radar, etc.). |
title |
Style classes
No other style classes than the one listed below should be used. The keypoint for those classes is
that thew have a real semantic: the purpose is not really to make things beautiful, but to add a semantic
to proposed XHTML element we saw above. As an example, the
screenshot style class for on
img
element should be a way to identify an image as a screenshot, not a way to display it like this por like that: this
task comes much later on and is not your responsability. It's the responsability of the guy which will try to
make the documentation as clearer as possible (which is nearly impossible if everybody use the
style
attribute or their own home-made style classes
| Class |
Description |
| img.screenshot |
Define a image as a screenshot |
Formating rules
- Lines must not be longer than 120 characters (as java code should...)
- The indentation should be 2 characters
