Menu
▾
▴
[Babeldoc-devel] babeldoc/readme/userguide chapter1.xml,1.2,1.3
|
From: <tr...@us...> - 2003-08-06 12:48:51
|
Update of /cvsroot/babeldoc/babeldoc/readme/userguide In directory sc8-pr-cvs1:/tmp/cvs-serv12974 Modified Files: chapter1.xml Log Message: updated some documentation - added section on configuration. Index: chapter1.xml =================================================================== RCS file: /cvsroot/babeldoc/babeldoc/readme/userguide/chapter1.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -C2 -d -r1.2 -r1.3 *** chapter1.xml 30 Jul 2003 23:24:06 -0000 1.2 --- chapter1.xml 6 Aug 2003 12:48:48 -0000 1.3 *************** *** 18,22 **** <para>Additionally the issue with document processing sometimes fails and then the issue is how do you react? <productname>Babeldoc</productname> has a very sophisticated journaling function that can allow administrators to reintroduce documents into any place in the pipeline.</para> </section> ! <section> <title>Fundamental terms and expressions</title> --- 18,22 ---- <para>Additionally the issue with document processing sometimes fails and then the issue is how do you react? <productname>Babeldoc</productname> has a very sophisticated journaling function that can allow administrators to reintroduce documents into any place in the pipeline.</para> </section> ! <section> <title>Fundamental terms and expressions</title> *************** *** 80,84 **** <para>(WINDOWS) c:> bin\babeldoc pipeline</para> </userinput> ! <para>The options for the pipeline tool will be printed to the screen. Please experiment with this tool. For interrogating the configurations on, say the , stage, issue the command:</para> <userinput> <para>(UNIX) $ bin/babeldoc pipeline -C test.extract</para> --- 80,84 ---- <para>(WINDOWS) c:> bin\babeldoc pipeline</para> </userinput> ! <para>The options for the pipeline tool will be printed to the screen. Please experiment with this tool. For interrogating the configurations on, say the <userinput>extract</userinput>, stage, issue the command:</para> <userinput> <para>(UNIX) $ bin/babeldoc pipeline -C test.extract</para> *************** *** 120,133 **** <para>For this step to correctly work, please create two directories:</para> <itemizedlist> ! <listitem>(UNIX) <userinput>/tmp/in</userinput> and <userinput>/tmp/done</userinput> ! </listitem> <listitem>(WINDOWS) <userinput>\tmp\in</userinput> and <userinput>\tmp\done</userinput> on the same partition as your <productname>Babeldoc</productname> installlation</listitem> </itemizedlist> <para>Start the scanner as follows:</para> <itemizedlist> ! <listitem>(UNIX) <userinput>$ bin/babeldoc scanner</userinput> ! </listitem> ! <listitem>(WINDOWS) <userinput>c:> bin\babeldoc scanner</userinput> ! </listitem> </itemizedlist> <para>The scanner will print a few informational lines to the screen and then wait for files to be placed in the in directory. Copy the file to the <userinput>/tmp/in</userinput> directory and within 1 second, the scanner will recognize the new file. The scanner will read in the file, move the file to the done directory and then submit the document to the </para> --- 120,130 ---- <para>For this step to correctly work, please create two directories:</para> <itemizedlist> ! <listitem>(UNIX) <userinput>/tmp/in</userinput> and <userinput>/tmp/done</userinput></listitem> <listitem>(WINDOWS) <userinput>\tmp\in</userinput> and <userinput>\tmp\done</userinput> on the same partition as your <productname>Babeldoc</productname> installlation</listitem> </itemizedlist> <para>Start the scanner as follows:</para> <itemizedlist> ! <listitem>(UNIX) <userinput>$ bin/babeldoc scanner</userinput></listitem> ! <listitem>(WINDOWS) <userinput>c:> bin\babeldoc scanner</userinput></listitem> </itemizedlist> <para>The scanner will print a few informational lines to the screen and then wait for files to be placed in the in directory. Copy the file to the <userinput>/tmp/in</userinput> directory and within 1 second, the scanner will recognize the new file. The scanner will read in the file, move the file to the done directory and then submit the document to the </para> *************** *** 135,137 **** --- 132,199 ---- </section> </section> + + <section> + <title>Modules</title> + <para><productname>Babeldoc</productname> is a modular piece of software. Each of the modules in babeldoc successively add and refine its operation. Although a module participates both in the runtime and build of <productname>Babeldoc</productname>, this document is concerned with the runtime aspects of modules.</para> + </section> + + <section> + <title>Configuration</title> + <para>All configuration data within <productname>Babeldoc</productname> is handled in a structured fashion. Every configuration key must be contained in a configuration file. The configuration file is hierarchically arranged very similar to a regular filesystem file in directories and subdirectories. The "directory" part of the configuration file name is specified as UNIX style forward slashes separating directory names. The configuration key is a string which must be unique in a configuration file. An example of this is the configuration key: <userinput>Journal.simple</userinput> which is defined in the configuration file: <userinput>service/config</userinput>.</para> + <section> + <title>LightConfig</title> + <para>The configuration implementation of <productname>Babeldoc</productname> is configurable but the default configuration implementation is the <userinput>LightConfig</userinput>. This stores the configuration data in properties files which are then hierarchically arranged into directories. The files may be stored on the local filesystem or in archive (JAR) files</para> + <para>The lightconfiguration implementation also has the very interesting and sometimes perplexing ability to merge configuration files with the same name into a single configuration file. This means that configuration file data does not overwrite data except where the configuration key is identical. In this case, the configuration file that is specified at the end of the configuration search path is dominant. This is logical and is consistent with how the PATH (or CLASSPATH) environment variable is used by the command processor to search for executables except that instead of the first match overriding all else, all of the matches are merged into a single "file".</para> + <para>The configuration searchpath is very important and is used by <productname>Babeldoc</productname> to determine where to find the configuration data and how to load it. The parts of the search path are given below:</para> + <itemizedlist> + <listitem>module dependency: The module dependencies determine the builtin searchpath. This cannot be changed by the user except by excluding modules from <productname>Babeldoc</productname> runtime. The module search path moves from the core module to the most dependant module. In other words, a configuration key in a configuration file in the most dependant module will override the same key in the same file in the core module. This is important to how dependant modules "specialize" <productname>Babeldoc</productname> behavior.</listitem> + <listitem>BABELDOC_HOME: This environment variable is set by the user to indicate those directories which contain configuration information. This environment variable is structured just as the CLASSPATH variable is. The earlier path elements indicate less dominant paths. It is very important for projects to set this variable to either a directory or a JAR file which contains your configuration settings.</listitem> + <listitem>current directory: The current directory is automatically added to the configuration search path for convenience reasons.</listitem> + </itemizedlist> + <para>There are times when the configuration is not working as expected. There is a small commandline tool which makes it easier to inspect the configuration files and how each configuration key is modified in the configuration file. The tool, <userinput>lightconfig</userinput> is illustrated below: </para> + <example> + <title>Listing configuration data</title> + <userinput> + <para>(UNIX) $ bin/babeldoc lightconfig -l pipeline/config</para> + <para>(WINDOWS) c:> bin\babeldoc lightconfig -l pipeline/config</para> + </userinput> + <para>The location of the configuration file <userinput>pipeline/config.properties</userinput> in each of the parts in the configuration search is then listed. A typical output would be:</para> + <computeroutput> + <para>Listing urls for the configuration: pipeline/config.properties</para> + <para>1: jar:file:/c:/download/babeldoc/build/lib/babeldoc_core.jar!/core/pipeline/config.properties</para> + <para>0: file:/C:/work/vap_rpt/./pipeline/config.properties</para> + </computeroutput> + <para>This output indicates that the file pipeline/config.properties exists in the babeldoc_core.jar file and is then overriden in the directory: C:/work/vap_rpt</para> + </example> + <example> + <title>Tracing a configuration key</title> + <userinput> + <para>(UNIX) $ bin/babeldoc lightconfig -l pipeline/config -t documentation.type</para> + <para>(WINDOWS) c:> bin\babeldoc lightconfig -l pipeline/config -t documentation.type</para> + </userinput> + <para>This traces how a particular configuration key (<userinput>documentation.type</userinput>) found in the configuration file: <userinput>pipeline/config.properties</userinput> is modified in all the possible configuration files. A typical output would be:</para> + <computeroutput> + <para>Listing urls for the configuration: pipeline/config.properties</para> + <para>1: jar:file:/c:/download/babeldoc/build/lib/babeldoc_core.jar!/core/pipeline/config.properties</para> + <para> documentation.type = simple</para> + <para>0: file:/C:/work/vap_rpt/./pipeline/config.properties</para> + <para> documentation.type: not defined</para> + </computeroutput> + <para>This output indicates that the configuration key is defined once in the babeldoc_core.jar file and is not subsequently overriden.</para> + </example> + + <section> + <title>Setting up a new project</title> + <para>This section briefly describes the steps necessary to setup a new babeldoc project. It is assumed that <productname>Babeldoc</productname> is installed in c:\babeldoc.</para> + <itemizedlist> + <listitem>Create a project directory: c:\project (for instance)</listitem> + <listitem>Add the following variables to you environment</listitem> + <listitem>BABELDOC_HOME - This variable must point to the root of your babeldoc binary installation, <userinput>c:\babeldoc</userinput>. At minimum it must contain the bin and lib directories. The bin directory must contain the babeldoc run scripts and the lib directory must contain all the babeldoc Java archive (JAR)files</listitem> + <listitem>BABELDOC_USER - This variable must point to your project directory, <userinput>c:\project</userinput>, in this case</listitem> + <listitem>PATH - Add the <userinput>c:\babeldoc\bin</userinput> directory to your path. This is not absolutely required, but will make running babeldoc easier by cutting down the commandline length</listitem> + <listitem>Add the configuration directories the the <userinput>c:\project</userinput> directory. These could include <userinput>pipeline</userinput>, <userinput>journal</userinput>, etc </listitem> + </itemizedlist> + </section> + </section> + </section> </chapter> |
