BestPractices
Views
BestPractices
Document Actions
last edited 2 years ago by jenn
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
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
colspectag as a child oftgroup, 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 tocolwidth="*"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>
