LUTECE Site Support - Wiki - Documentation conventions

Oct 6, 2021 6:47:16 PM Thomas Dumont

Documentation conventions

Lutece's documentation is written in XML format, and is generated using Maven in HTML and PDF formats.

A limited number of tags is used, to allow a layout homogeneous in both formats.

Create a documentation: the basic rules

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

The HTML code included in these chapters must not use the   tag, misinterpreted during of the PDF generation. The  tag is used to make line breaks.

Tables must have at least one title in first line ( <th> )

The images should be 780px wide (center the image on a white background), and be created in .gif format.

Examples of implementation

Overall structure of the file:

<? xml version = 1.0 encoding = UTF-8?>
    <Document>
        <Properties>
            <title> Lutèce: title of the document </title>
        </Properties>
        <Body>

            <section name = Chapter title 1>
                ...................
            </Section>

        </Body>
    </Title>

A document can contain several sections.

A section may contain paragraph-formatted text (  ), as well as one or more subsection (s)

Example:

<section name = Chapter title 1>
        <P>
            Introduction of Chapter 1
        </P>

        <subsection name = Subchapter 1>
            <P>
                    text ...
            </P>
        </Subsection>

        <subsection name = Subchapter 2>
            <P>
                text ...
            </P>
        </Subsection>

    </Section>

The result is as follows:

Chapter title 1

Introduction of Chapter 1

Subchapter 1

text ...

Subchapter 2

text ...

It is possible to include a list in a paragraph:

<P>
      <Ul>
         <li> sample list 1 </li>
         <li> sample list 2 </li>
      </Ul>
   </P>

   <P>
      <Ol>
         <li> sample list numbered 1 </li>
         <li> sample list numbered 2 </li>
   </Ol>
</P>

Result:

example of list 1
example of list 2

example numbered list 1
example of list numbered 2

Text can be formatted with tags of type  ,  , <code>

<P>
      <code> text in code format </code>
   </P>
   <P>
      <strong> strong text </strong>
   </P>
   <P>
      <em> text in em format </em>
   </P>

Result:

text in code format
strong text
text in em format

Examples of code can be introduced using the <pre> tag:

<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>

Warning: for the rendering to be correct when using the <pre> tag, you have to paste the text on the left, without taking into account the general indentation of the xml code of the 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 display a screenshot:

<P>
        <Center>
            <img src = images / logo_lutece.gif />
        </Center>
    </P>

The <center> tag is only taken into account for HTML generation.