Documentation standards

The documentation of Lutece is written in an XML format, then PDF and HTML files can be generated with the help Maven.

A limited number of tags are used, to reach a uniform page-setting in both formats.

Create a documentation : Base rules

The encoding used is UTF-8, and the chapters are in section and subsection.

The HTML code included in the chapters should not use the tags <br>, misinterpreted during PDF generation. The <p> tag is then used to place a line break.

The tables must contain at least a title in first row( <th> )

The images must measure 780px large ( Centered image with a white background), and be in .gif format.

Examples of implementation

Global structure of file : 

<?xml version="1.0" encoding="UTF-8"?>
  <document>
   <properties>
    <title>
      Lutece : title of document
    </title>
   </properties>
   <body>
   
   <section name="Section Title 1">
               ...................
   </section>

  </body>
  </document>


A document may contain many sections.

A section can contain formatted text by a paragraph(<p>), but also one or more sections

Example : 

   <section name="Section Title 1">
        <p>
           Introduction of Section 1
        </p>

        <subsection name="SubSection 1">
           <p>
              text ...
           </p>
        </subsection>           
        
        <subsection name="SubSection 2">
           <p>
              text ...
           </p>
        </subsection>           

   </section>

The result is as follows :

Section Title 1

Introduction to Section 1

SubSection 1

texte ...

SubSection 2

texte ...


It is possible to include a list in a paragraph : 

       <p>
          <ul>
              <li>example of list 1</li>
              <li>example of list 2</li>
           </ul>
       </p>
       
       <p>
          <ol>
              <li>example of numbered list 1</li>
              <li>example of numbered list 2</li>
           </ol>
       </p>

Result :

  • example of list 1
  • example of list 2

  1. example of numbered list 1
  2. example of numbered list 2


The text can be formatted with tags of type <strong>, <em>, <code> 

   <p>
       <code>code format text</code>
   </p>
   <p>
       <strong>strong text format</strong>
   </p>
   <p>
       <em>em text format</em>
   </p>

Result :

  • code text format
  • string text format
  • em text format


Examples of source code can be placed by using <pre> : 

   <p>                       
       <div class="source">
<pre>
   <application>
     <application-class>fr.paris.lutece.plugins.securedtest.SecuredTestApp</application-class>
     <application-security-model>1</application-security-model>
   </application>
</pre>
       </div>
   </p>

Notice : For proper rendering, the <pre> tag should be stuck to the left and ignore indentation of the xml file.

The result is : 

<application>
     <application-class>fr.paris.lutece.plugins.securedtest.SecuredTestApp</application-class>
     <application-security-model>1</application-security-model>
</application>


To insert a table, the syntax is as follows : 

     <p>
         <table>
             <tr>
                 <th>Title 1</th>
                 <th>Title 2</th>
             </tr>
             <tr>
                 <td>Column 1</td>
                  <td>Column 2</td>
             </tr>
         </table>
     </p>

Which gives the following table :

Title 1 Title 2
Column 1 Column 2


To view a screen capture : 

   <p>
       <center>
              <img src="images/logo_lutece.gif" />
       </center>
   </p>

The tag <center> is intepreted while the HTML generation phase only.

To prevent image deformations of in the PDF version, create a 780px width image( for an A4 output), the screen capture will be centered at this width.

The result is :