History for BestPractices
changed:
-
Best practices for CNXML
- Indent your markup (emacs with PSGML does a nice job)
- Make sure the module tag's id attribute matches its actual ID
- Make sure the author id matches the actual author id
- Make sure the authors' names are spelled correctly
- Always include at least one keyword
- Always include an abstract. Abstracts should be in complete
sentences.
- Never, ever, **EVER** use <emphasis> for a vocabulary term
- Don't hard code figure/equation numbers into names or references.
For example, do not give a figure the name Figure 1; instead do not use the name tag
if there is not a more descriptive name for the figure.
Figures are numbered within the module automatically.
When referring to a figure within the same module, it is best to use an empty cnxn tag.
Example::
<cnxn target='fig1'/>
This will automatically reference the figure that has the id of 'fig1' with Figure N
where N is the number the figure was given automatically in the document.
- When linking a picture to a larger version of itself, instead of the caption linking to the large image, use <para name='' value=''/> inside the media tag::
<media type='image/gif' src='g_moonwash.gif'>
<param name='thumbnail' value='g_moonwash-t.gif'/>
</media>
- When comparing to sections of text, as with translation, use a table.
- Tables now support the 'colspec' tag as a child of 'tgroup', use it when you need to define the widths of certain columns (in pixels). If you want to have auto width for the columns simply define them to 'colwidth="*"'
Example::
<table frame="all" id="table">
<name>Example Table</name>
<tgroup cols="2">
<colspec colname="col1" colnum="1" colwidth="75"/>
<colspec colname="col2" colnum="2" colwidth="75"/>
<tbody>
<row>
<entry>entry</entry>
<entry>entry</entry>
</row>
<row>
<entry>entry</entry>
<entry>entry</entry>
</row>
<row>
<entry>entry</entry>
<entry/>
</row>
</tbody>
</tgroup>
</table>
BestPractices
