<?xml version="1.0" encoding="ISO-8859-1"?>
<sect1 id="first-steps-borges" lang="&lang;">
 <sect1info>
  
  <!-- Please, do NOT edit the following revision history by hand. Use the
  "make <module_name>.revision" target instead.  -->
  
  <revhistory><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>write</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>translate</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>tproof</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>pproof</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>ispell</revremark> </revision><revision><revnumber>0.8</revnumber><date>YYYY-MM-DD</date><authorinitials>tbn</authorinitials><revremark>lproof</revremark> </revision>
      <revision>
        <revnumber>1.en.lproof</revnumber>
        <date>YYYY-MM-DD</date>
        <authorinitials>tbn</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.ispell</revnumber>
        <date>YYYY-MM-DD</date>
        <authorinitials>tbn</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.pproof</revnumber>
        <date>2002-07-22</date>
        <authorinitials>jp</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.tproof</revnumber>
        <date>2002-07-03</date>
        <authorinitials>cb</authorinitials>
      </revision>
      <revision>
        <revnumber>1.en.write</revnumber>
        <date>2002-06-03</date>
        <authorinitials>fm</authorinitials>
      </revision>
    </revhistory>
 </sect1info>
 
  <title id="first-steps-borges-ti1">First Steps</title>

 <abstract>
  <para id="first-steps-borges-pa1">&prog-borges; needs a minimal configuration to work. We will
   detail the configuration steps necessary to create a project
   template. Afterwards, the sample document provided with the project
   template will be compiled into both &pdf; and &html; and the
   progress report will be generated.</para>
 </abstract>

 <para id="first-steps-borges-pa2">To configure &prog-borges; you need to perform the following
  steps:
 </para>
 
 <procedure>
  <step>
   <title id="first-steps-borges-ti2">Define a New Working Directory</title>
    
    <para id="first-steps-borges-pa3">A working directory should be created to hold all your
     project's files. Let's assume you want to put your files under
     <literal>My_Project</literal> in your home directory, then
     you would issue:
     <screen id="first-steps-borges-sc1">
      mkdir ~/My_Project
     </screen>
     to do so.</para>
    <note>
     <para id="first-steps-borges-pa4">The following steps assume you are under the working
      directory (<filename>~/My_Project/</filename> in the
      example).</para>
    </note>
   
  </step>
  <step>
   <title id="first-steps-borges-ti3">Copy the Template System to The Working Directory</title>
   
    <para id="first-steps-borges-pa5">Now that the working directory has been created, you need to
     copy a <quote>template system tree</quote> into it. A template
     directory tree is supplied under the
     <filename>/usr/share/Borges/template/</filename> directory, so issue
     <screen id="first-steps-borges-sc2">
      cp -a /usr/share/Borges/template/* .
     </screen>
     to copy the template into your working directory.</para>
   
  </step>
  <step>
    <title id="first-steps-borges-ti4">Create Your Personal Profile</title>
   
    <para id="first-steps-borges-pa6">Each <quote>author</quote> (writer, translator, proofreader,
     etc.) needs to define his personal profile. &prog-borges; uses
     the information in the profile for version management and author
     credits among other things. The profile is stored in
     <filename>conf/author.xml</filename> and a sample is provided in
     the <filename>conf/author.xml.in</filename> file, so just issue
     <screen id="first-steps-borges-sc3">
      cp conf/author.xml.in conf/author.xml
     </screen>
     and edit <filename>author.xml</filename> with your favorite
     text editor to suite your personal data. Below you have a sample
     profile:

     <programlisting id="first-steps-borges-pl1">
<!-- This should be inside CDATA, but indentation is not respected -->
      &lt;?xml version='1.0' encoding='ISO-8859-1'?&gt;
       &lt;author&gt;
        &lt;initials&gt;pp&lt;/initials&gt;
        &lt;firstname&gt;Peter&lt;/firstname&gt;
        &lt;lastname&gt;Pingus&lt;/lastname&gt;
        &lt;mail&gt;peter.pingus@mandrakesoft.com&lt;/mail&gt;
        &lt;lang&gt;en&lt;/lang&gt;
       &lt;/author&gt;
     </programlisting>
     </para>
    <tip>
     <para id="first-steps-borges-pa7">Take a look at the comments in
      <filename>author.xml</filename> for hints about the meaning of
      the parameters (In the above sample, the comments are excluded
      for simplicity reasons).</para>
    </tip>
   
  </step>
  <step>
   <title id="first-steps-borges-ti5">Initialize the System</title>
   
    <para id="first-steps-borges-pa8">Now, &prog-borges; has to be initialized. To do so, just
     issue
     <screen id="first-steps-borges-sc4">make</screen>
     and directories will be populated with the minimum required
     files.</para>
   
  </step>
  <step>
   <title id="first-steps-borges-ti6">Generate the Modules Templates</title>
   
    <para id="first-steps-borges-pa9">Now you have the system configured, it is time to test if it
     works properly. A sample document (called
     <literal>Sample</literal>) is provided, so we will use that one
     for testing purposes. Issue
     <screen id="first-steps-borges-sc5">
      make -C manuals/Sample templates LANG=en
     </screen>
     to generate the modules templates for the sample document.</para>
      <tip>
	<para id="first-steps-borges-pa10">the <option>-C</option> argument of the
	<command>make</command> command simply means to make the
	<literal>templates</literal> target in the
	<filename>manuals/Sample</filename> directory. You could have run
     <screen id="first-steps-borges-sc6">
      cd manuals/Sample; make templates LANG=en </screen> also.</para>
      </tip>
  </step>
  <step>
   <title id="first-steps-borges-ti7">Compile Sample to &pdf; and Check the Result</title>
   
    <para id="first-steps-borges-pa11">Now you can compile the sample document to &pdf; to check
     how it looks. Issue
     <screen id="first-steps-borges-sc7">
      make -C manuals/Sample master.pdf LANG=en
     </screen>
     to do so, and check the resulting &pdf; by issuing
     <screen id="first-steps-borges-sc8">
      xpdf manuals/Sample/master.pdf
     </screen>
     if everything went well, you should see a nice &pdf; of the
     sample document. Of course, you can use &prog-acroread; instead
     of &prog-xpdf; to open the &pdf; if you prefer to.
    </para>
   
  </step>
  <step>
   <title id="first-steps-borges-ti8">Compile Sample to &html; and Check the Result</title>
   
    <para id="first-steps-borges-pa12">You can also compile the sample document to &html;. Issue
     <screen id="first-steps-borges-sc9">
      make -C manuals/Sample master.flat.html LANG=en
     </screen>
     to do so, and check the results by pointing your favorite
     browser to
     <literal>~/My_Project/manuals/Sample/master.flat.html</literal>.
    </para>
   
  </step>
  <step>
   <title id="first-steps-borges-ti9">Generate and View the Report</title>
   
    <para id="first-steps-borges-pa13">The report is a tool of &prog-borges; which informs you
     about the progress of the work being done in your project for all
     supported languages. To generate the report for the sample
     document, issue
     <screen id="first-steps-borges-sc10">
      make -C reports all LANG=en
     </screen>
     and view the resulting report by pointing your favorite web
     browser to <literal>~/My_Project/reports/index.html</literal>.
    </para>
   
    </step>
  </procedure>

 <note>
  <para id="first-steps-borges-pa14">In all the above examples the <literal>LANG=en</literal>
   parameter is <emphasis>mandatory</emphasis> if your preferred
   language is other than English (<literal>en</literal>). The
   preferred language was set in the <filename>author.xml</filename>
   file, remember?</para>
 </note>

 <para id="first-steps-borges-pa15">It was not that hard wasn't it? Now, you can setup
  &prog-borges; to work with your own projects.</para>

</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-parent-document: ("../../manuals/Borges-doc/master.top.xml" "sect1")
End:
-->