Document content specification

It is possible to configure the structure of the wiki output by specifying the chaptersContent property. This XML file specifies:

• The chapters which will be included in the PDF, DOCX, or Epub file, and their order
• The categories which will be included in each chapter
• Optionally, the articles which will be included in each chapter (appart from those specified in the chapter categories defined above)

Note that if the output format is PDF, PDF, or DOCX, the chapters structure will be used to generate the output document. If the output format is based on HTML, only the computed list of included articles will be used.

Grammar

See The document content schema.

File structure

The content XML file contains:

• A list of categories, which will help to define which category to consider if one article belong to more than one category. This list specifies the order in which several categories of the same article should be considered
• A list of chapter names, and for each chapter:
  • An optional list of:
    • Categories for which the articles will be added in this chapter
    • Categories to exclude for this chapter
    • packages for which the articles must not belong for this chapter
    • Packages for which the articles must belong to be included for this chapter
  • An optional head element, specifying a list of specific articles to add at the beginning of this chapter
  • An optional list of:
    • Specific articles to add for this chapter
    • Specific list of articles to add for this chapter, but must follow each other
    • An optional list of articles to exclude for this chapter
  • An optional list of sub-chapters to add for this chapter

Note that by default articles which are in no chapter will be added at the end in a "Miscellanous" chapter. However, the defaultExclude attribute at the top-level element allows to specify that articles which are in no chapter will not be present in the document.

Excluded packages

An excluded package is specified by the excludePackage element. The element has the following attribute:

• "name": the name of the category

Included and excluded categories

An included category is specified by the category element. The element has the following attribute:

• "name": the name of the category

It is possible to use a list of categories for the attribute rather than only one. In this case, it means that only articles belonging to all the listed categories will be added to the chapter.

For example, in the following content definition, articles which are in both the "general" and "general2" category will be added in the chapter.

      <chapter name="chapter1">
         <category name="category1 category2" />   
      </chapter>

An excluded category is specified by the excludeCategory element. The element has the following attributes:

• "name": the name of the category
• "strict": optional. If true, an article beloging to this cateogy will be excluded even if it belongs to another included category

For example:

      <chapter name="chapter1">
         <category name="category1" />
         <excludedCategory name="category2" />
      </chapter>

In this case, if an article belongs to "category1" and "category2", it will be included in the list of articles for the chapter.

      <chapter name="chapter1">
         <category name="category1" />
         <excludedCategory name="category2" strict="true" />
      </chapter>

In this case, if an article belongs to "category1" and "category2", it will not be included in the list of articles for the chapter.

Definition of an article

An article can be defined by:

   <article name="article name" />

or for an article which belongs to a package:

   <article name="article name" package="the package name" />

For excluded articles:

   <excludedArticle name="article name" />

or for an excluded article which belongs to a package:

   <excludedArticle name="article name" package="the package name" />

Generation algorithm

By default the generator will generate:

• One introduction chapter with only the content of the index file
• One chapter for each chapter defined in the XML file
• For each chapter, one Word sub-chapter for each article belonging in one of the categories defined in this chapter

Generation order

• Any article will only be present once
• The articles which are explicitly specified in a chapter will appear before those implicitly specified by the categories in which they appear

For example, if we have the following content for a chapter:

   <documentContent>
      <chapter name="chapter1">
         <category name="category1" />
         <article name="article 5" />
      </chapter>
   <documentContent>

In this case, if we have several articles of the category category1, they will appear after the article article_5.

Keeping the articles order

The keepOrder attribute for the root documentContent element allows to keep the order of articles which are specifically specified for each chapter. For example:

   <documentContent keepOrder="true">
      <chapter name="first chapter">
          <article name="article d" /> 
          <article name="article b" /> 
          <category name="general" />
      </chapter>
      <chapter name="second chapter">
          <category name="general2" />
      </chapter> 
   </documentContent>

In that case "article d" will be the first article in the first chapter, and "article b" the second article in the chapter.

ArticlesList

It is possible to ensure that several articles will follow each other even if the keepOrder attribute is not set to true. For example here the "article 3" and "article 6" aeticlew will follow each other:

   <documentContent>
      <chapter name="chapter1">
         <category name="category1" />
         <articlesList>
             <article name="article 3" />
             <article name="article 6" />
         </articlesList>
      </chapter>
   </documentContent>

Note that this is not necessary to use articlesList elements if the keepOrder attribute is set to true, because in that case the order of articles which are specifically specified for each chapter will be kept.

Conditions of inclusion of an article

• The article must belong to the list of categories specified for this chapter, or be in the list of articles
• The article must not belong to an excluded category
• The article must not belong to an excluded package
• The article must not belong to the list of excluded articles
• If the chapter has a package list, the article must belong to one of these packages

For example, if we have the following content for a chapter:

   <documentContent>
      <chapter name="chapter1">
         <package name="pack" />
         <category name="category1" />
         <excludedCategory name="category2" />
         <article name="article 5" />
         <excludedArticle name="article 2" />
      </chapter>
   <documentContent>

Then to add an article to this chapter:

• It must belong to the category category1, or it must be the article article_5
• It must not belong to the category category2
• It must belong to the package pack
• It must not be the article_2

Examples

Simple example

   <documentContent>
      <category name="category3" />
      <category name="category1" />
      <category name="category4" />
      <category name="category2" />
      <chapter name="chapter1">
         <category name="category1" />
         <category name="category2" />
         <article name="article 5" />
      </chapter>
      <chapter name="chapter2">
         <category name="category3" />
      </chapter>
   <documentContent>

Example with sub-chapters and articles which follow each other

   <documentContent>
      <category name="category3" />
      <category name="category1" />
      <category name="category4" />
      <category name="category2" />
      <chapter name="chapter1">
         <category name="category1" />
         <chapter name="chapter3">
            <category name="category2" />
            <articlesList>
               <article name="article 3" />
               <article name="article 6" />
            </articlesList>
         </chapter>
      </chapter>
      <chapter name="chapter2">
         <category name="category3" />
      </chapter>
   </documentContent>

Example with articles at the beginning of a chapter

   <documentContent>
      <category name="category3" />
      <category name="category1" />
      <category name="category4" />
      <category name="category2" />
      <chapter name="chapter1">
         <category name="category1" />
         <chapter name="chapter3">
            <category name="category2" />
            <head>
               <article name="article 3" />
               <article name="article 6" />
            </head>
         </chapter>
      </chapter>
      <chapter name="chapter2">
         <category name="category3" />
      </chapter>
   </documentContent>

Example with excluded articles and categories

   <documentContent defaultExclude="true">
      <category name="category3" />
      <category name="category1" />
      <category name="category4" />
      <category name="category2" />
      <chapter name="chapter1">
         <category name="category1" />
         <excludeCategory name="category2" />
         <article name="article 5" />
         <article name="article 5" />
         <excludeArticle name="article 6" />
      </chapter>
      <chapter name="chapter2">
         <category name="category3" />
      </chapter>
   <documentContent>