Article development: using the template

To use the documentation template, save it as the file name you want to create. Do not edit any of the fields in the head section. The build process automatically generates this section and expects the content as it is currently coded there.

The template file is located in the BUILD/zero.docs/templates component.

ID tagging on headings

To reference a section, put the ID on the heading of the section. Do not put it elsewhere.

Correct coding:

<h2 id="Introduction">Introducing ZRM</h2>

Incorrect coding

<div class="introduction">
<h2>Introducing ZRM</h2>
content...
</div>

Note: This example is totally contrived and not based on a real life example so I am not picking on ZRM content here.

Division tags

As you code the information in your file, there are special division tags that must be coded so that the type of information being coded can be formatted correctly and a single change to a css file can change the look and feel or output of that type of information across the entire library of information. Use the sample coding detailed in the following sections of this template:

• Inserting a short description
• Inserting a note
• Inserting notes
• Labeling advanced content
• Inserting code samples
  • Wrappering comments in code samples
  • Wrappering paths in code samples
• Inserting log files
• Nesting ordered lists
• Inserting configuration
• Linking to an external URL
• Linking to a file within the module

Inserting a short description

Use the shortdesc class to add a short description to each file, as shown in the following example:

  
<div class="shortdesc">
<p>Insert a short, 1 or 2 sentence summary of what this 
article is about so that users can decide, at a glance, 
if this is the information they're seeking.
</p>
</div>

Inserting a note

Insert a note using the div class="note" tag as shown in the following example to create a simple note:

<div class="note">
Insert your note here.
</div>

Inserting notes

If you have more than one note in a section, use the div class="notes" tag as shown in the following example to create a list of notes:

<div class="notes">
<ul>
<li>Insert your first note here.</li>
<li>Insert your second note here.</li>
</ul>
</div>

Use the unordered list coding within the notes class unless there is an actual order to the notes you're listing. Then, and only then, you can use the ol coding.

Labeling advanced content

Insert the "Advanced" label on content to signal advanced users that there is a short cut or a different method to use. To insert the advanced lable, use the div class="advanced" tag as shown in the following example to create an advanced note:

<div class="advanced">
Insert advanced content.
</div>

Inserting code samples

Insert a code block using the pre tags wrappered in the div class=codeSample tag as shown in the following example:

<div class="codeSample">
<pre>
Insert your block of code here.
</pre>
</div>

Wrap both input and output in the codeSample tag, as shown in the following example:

<p> The following example shows an entry rendered for a Groovy-based resource 
handler: 
</p>  
<div class="codeSample">
<pre>
 def onRetrieve(){
 entry = [
  // Required
  id : '1',
  title : 'title',
  updated : new Date(0),
  authorname : 'name',
  content : 'content',
  contenttype : 'TEXT',
    
  // Optional
  categorylabel : 'label',
  categoryterm : 'term',
  summary : 'summary',
  summarytype : 'TEXT',
     
  // Extensions
  f1 : 'v1'
 ]
 request.view = 'atom'
 request.atom.output = entry
 render()
 } 
</pre>
</div>
<p> 
The following Atom entry document is the result of the previous example: 
</p> 
<div class="codeSample">
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?> 
&lt;entry xmlns:zero="http://projectzero.com/namespace" xmlns="http://www.w3.org/2005/Atom">
  &lt;id>http://localhost:8081/resources/custom/1&lt;/id>
  &lt;link href="http://localhost:8081/resources/custom/1" rel="edit">&lt;/link>
  &lt;title type="text">title&lt;/title>
  &lt;updated>1970-01-01T00:00:00.000Z&lt;/updated>
  &lt;author>&lt;name>name&lt;/name>&lt;/author>
  &lt;content type="text">content&lt;/content>
  &lt;summary type="text">summary&lt;/summary>
  &lt;category term="term" label="label">&lt;/category>
  &lt;zero:f1 xmlns:zero="http://projectzero.com/namespace">v1&lt;/zero:f1>
&lt;/entry> 
</pre>
</div>  

Wrappering comments in code samples

Use the comments tag within the div="codeSamples" tag to wrapper any comments within your code block, as shown in the following example:

<div class="codeSample">
<pre>
code code code
   <div class="comments"> 
   A comment
   </div>
more code code code
</pre>
</div>

When run with the CSS, the color of the comment text renders green.

Wrappering paths in code samples

Use the path tag within the div="codeSample" tag to wrapper any path statements within your code block, as shown in the following example:

<div class="codeSample">
<pre>
code code code <a name="path" class="path">path/path/morepath</a> 
more code code code
</pre>
</div>

When run with the CSS, the color of the path text renders blue.

Inserting log files

Use this tag to insert a log file fragment, as shown in the following example:

<div class="log">
<pre>
Insert log file fragment.
</pre>
</div>

Nesting ordered lists

Use the div class="olSuba" tag to insert an ordered list within an ordered list as shown in the following example:

<ol>
<li>This is the first step in the process.</li>
<li>This is the second step in the process and it has three substeps:
<div class="olSuba">
<ol>
<li>This is the first sub-step under step two.</li>
<li>This is the second sub-step under step two.</li>
<li>This is the third sub-step under step two.</li>
</ol>
</div>
</li>
<li>This is the third step in the process.</li>
</ol>

Inserting configuration

Use the div class="config" tag to wrapper zero.config extracts.

<div class="config">
<pre>
Insert configuration here.
</pre>
</div>

Linking to an external URL

To create a hyper link to an external site, use the a tag, with the class="externalURL" tag, as shown in the following example:

<a href="http://www.w3.org" class="externalURL">World Wide Web Consortium</a>

Linking to a file within the module

To create a hyperlink to a file within the same module, use the a tag, with the class="fileReference" tag, as shown in the following example:

<a href="nameoffile.htm" class="fileReference">Name of File</a>