May 13, 2025, 2:21:26 PM

Nicolas Jouanne

Documentation conventions

Lutece’s documentation is written in xDoc (XML) format, and is generated using Maven in HTML and PDF formats.

IMPORTANT: All plugins hosted by GitHub or GitLab must provide a README.md file generated with xdoc2md.

More info about the Maven plugin: xdoc2md.

The documentation must provide 2 Xdoc Files: one in English and one in French.

Example of directory tree:

arborescence-doc

Xdoc mandatory content

The XDOC file should contain those mandatory sections:

Plugin name
Keywords: Keywords should indicate the categories of use of this plugin. Those keywords should be in the Xfile language. Examples: “cms, authentication, cms, workflow, seo, collaborative, …”.
Introduction: This section should indicate the aim and the features of the plugin.
Configuration: List of configuration properties available.
Usage: This section should indicate how to use the feature of this plugin. Examples of code are welcome here.

XDOC model:

<?xml version="1.0" encoding="UTF-8"?>
<document>
    <properties>
        <title>Plugin {PLUGIN NAME}</title>
    </properties>
    <head>
        <meta name="keywords" content="{KEYWORD_A},{KEYWORD_B},{KEYWORD_C}"/>
    </head>
    <body>
        <section name="Plugin {PLUGIN NAME}">
            <subsection name="Introduction">
                <p>...</p>
            </subsection>
            <subsection name="Configuration">
                <p>...</p>
            </subsection>
            <subsection name="Usage">
                <p>...</p>
            </subsection>
        </section>
    </body>
</document>

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 PDF generation. The  tag is used to make line breaks.

Tables must have at least one title in the 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>
</Document>

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:

sample list 1
sample list 2

sample list numbered 1
sample 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.

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. So that the image is not distorted in the PDF version, one trick is to create the image used for the generation of this format at a size of 780px wide (for an A4 output format), the screenshot being centered in this width.

Top of the page