====== Configuration of Epeios-related software components ======

<note>
This are general configuration instructions common to all //Epeios// software. Configuration instructions specific to each software may be available in the //Configuration// section of each software's main page.
</note>

<note>Some parts of this page will only apply to software with command-line interface (CLI). Also some other parts will only apply to frontend related components.</note>

===== Language =====

The default language is English. You can switch to French by changing the ''<Language>...<Language>'' entry in the ''Parameters'' section of the configuration file (''//<component name>//.xcfg'') from ''en'' to ''fr''. This two are currently the only available languages, but, by completing the locale file (''//<component name>//.xlcl''), and modifying the configuration file accordingly, you can switch to whatever language you want.

It's also possible to change punctually the language, without having to modify the configuration file, as described below.

===== Frontends =====

==== Parameters ====


<note>This section concerns //[[:XDHTML:]]// frontends, that is, components with a name ending with ''xdh'' (before the extension).</note>

<code xml>
<Parameters>
 <Preset Type="PRESET_TYPE" Handling="HANDLING">PRESET_VALUE</Preset>
 <Backend Type="BACKEND_TYPE">PARAMETERS</Backend>
</Parameters>
</code>

  * //''PRESET_TYPE''// : one of :
    * ''None'' : no preset; ''PRESET_VALUE'' is not used,
    * ''Setup'' : use the setup which id is given by ''PRESET_VALUE'',
    * ''Project'' : use the project which file name is given by ''PRESET_VALUE'',
  * //''HANDLING''// : one of :
    * ''Display'' or missing: the //prolog// page is displayed, with the given project selected,
    * ''Load'' : load the given project (//prolog// page is skipped),
    * ''Run'' : run the given project (both //prolog// and //login// pages are skipped),
    * ''Login'' : load the given preset (//prolog// page is skipped), and displays only the login form on the //login// page.
   * //''BACKEND_TYPE''// : one of :
     * ''None'' : for no backend ; //''PARAMETERS''// is ignored,
     * ''Predefined'' : for a predefined //backend//, as defined in the ''Definitions/Backends'' section ; //''PARAMETERS''// is the id of the chosen backend,
     * the plugins defined in the ''FrontendPlugins'' section, to which //''PARAMETERS''// is given as parameters.

<note>The ''Preset'' entry applies only to the frontends with desktop GUI, but the ''Backend'' entry is also used for the Web (multi-user) and CLI frontends. </note>

==== Setups ====

<code xml>
<Setups>
 <Setup … Handling="HANDLING">…</Setup>
</Setups>
</code>

''HANDLING'': one of:
 //In progress…//

<note>The ''Setups/Setup'' entries are for all type of software, but the ''Setup''%%'%%s ''Handling'' attribute is dedicated to the frontends used with desktop GUIs.</note>


===== Command-line arguments =====

All command-line components from the //Epeios// project can have their command-line arguments be configured.

All this components read their parameters from an internal registry. This registry is filled with the content of the configuration file (and potential project file ; see below), but also with values depending from the command-line arguments. To set a value for a parameter, you can use this special option :

''%%--%%#//<path>//=//<value>//''

where ''//<path>//'', which is automatically prefixed with ''Parameters/'', is the path of the entry in the registry, and ''//<value>//'' its value.

For example, there is a ''Parameters/Language'' entry in the registry for the language to use, and which value is generally set in the configuration file. To switch temporarily to another language without having to modify the configuration file, simply add ''%%--%%#Language=//<language>//'' option, where ''//<Language>//'' is the language you want to switch to (given that the translations for this language exist in the locale file ; see above), when calling the component.

In the configuration file, you will find an ''Arguments'' section. Each ''Argument'' entry specifies a shortcut for either the command argument, an option, a flag or an argument which is neither of previous type of argument. The ''Layouts'' section contains a ''Layout'' entry for each command to make the link between an argument and the parameter it represents following its position.

The ''Locale'' section contains the translations of the label and descriptions of the arguments, and is used for the generation of the help page of the component.

===== Project files =====

Some command-line components handle project files; in such a case, this is indicated in the help page (displayed with the ''%%--%%help'' command) of the component. Such a project file has, by convention, a ''.xprj'' extension, and following structure :

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<Projects>
 <Project target="<component name>">
  ...
 </Project>
</Projects>
</code>

In fact, all Epeios-related software components can handle project files, even when not mentioned in the help page. You only have to add a ''%%--%%#Project=<project file name>'' option when launching the component, or set the ''Parameters/Project'' entry in the configuration file to the project filename.

You can also define some projects in the ''Definitions'' section of the configuration file, and then use one of them by adding a ''%%--%%#Project[Type="Predefined"]=<project id>'' option when launching the component, or set the ''Parameters/Project[Type="Predefined"]'' entry in the configuration file to the project id.

You can put in a project file the same entries as in the configuration file (although some entries don't make sense, for example the ''Parameters/Project'' entry mentioned above). A project file can be seen as a remote configuration file. For example, there is mentioned above that you can change the language of a component by changing the ''Parameters/Language'' entry in the configuration file. But you can also put this entry in a project file, without modifying the configuration file, so that the language of the component only changes when launched with this project file.

Entries in a project file supersede same entries in configuration file.

===== Setups =====

''Setups'' (with final ''s'') is a section containing one or more ''Setup'' (__without__ final ''s'') sections, each with its own ''id'' attribute value. Each ''Setup'' contains a set of parameters, which, when owned by the selected setup, are entries that are considered as child of the ''Parameters'' section of the configuration file.

To specify which setup to use, put its id as the value of the ''Setup'' attribute of the ''Parameters'' tag. This can be done directly in the configuration file, or through an option to type as command-line argument if defined in the ''Arguments'' section (this should be indicated in the help page -- command ''%%--%%help'' -- of the tool), or, as explained above, with the ''%%--%%#@Setup=<//id//>'' option as a command-line argument, where ''//<id>//'' is the setup's id.

Alternatively, you can add a ''Default'' attribute to the ''Setups'' tag with the value of the id of the default setup. This value is superseded by the value of the above  described ''Setup'' attribute of the ''Parameters'' tag. 

A project file can contain its own ''Setups'' section.

Entries of a selected setup supersede same entries in a project file and in the configuration file.

===== 'Debug' section =====

This is a section defined under the ''Parameters'' section which deals with various debug features

==== 'DumpRegistries' entry ====

This entry is usually given as a command-line argument (''%%--%%#Debug/DumpRegistries=//<value>//'').

If ''//<value>//'' is empty, the content of all the registries is displayed.

You can also specify which registry content to display by giving as ''//<value>//'' one or several of the following characters:
  * ''m'' for the main registry; filled with the content of the configuration file,
  * ''l'' for the lasting registry; filled with application data, and set by application,
  * ''p'' for the project registry; filled by project file,
  * ''s'' for the setup registry; filled with setup content, when one is specified,
  * ''a'' for the arguments registry; filled with the content of the command-line arguments,
  * ''r'' for the runtime registry; set by the application, but lost once the application is terminated.

For example ''%%--%%#Debug/DumpRegistries=am'' displays the content of the argument registry and the main registry.

==== 'DumpLocales' entry ====

This entry is usually given as a command-line argument (''%%--%%#Debug/DumpLocales=//<value>//'').

If ''//<value>//'' is empty, the content of all the locales is displayed.

You can also specify which locale content to display by giving as ''//<value>//'' one or several of the following characters :
  * ''m'' for the main locale.
  * ''c'' for the configuration locale,
  * ''p'' for the project locale,

For example ''%%--%%#Debug/DumpLocales=mp'' displays the content of the main locale and the project locale.


===== The XML preprocessor =====

Configuration/locale/project files go through the Epeios XML preprocessor, which is described on the //[[:tools:XPPq:]]// dedicated page, before handled by the component. So, all the //Epeios// XML preprocessor directives can be used in this files. This allows in particular to split each of them in several sub-files.