2. First Steps

Abstract

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.

To configure Borges you need to perform the following steps:

  1. Define a New Working Directory

    A working directory should be created to hold all your project's files. Let's assume you want to put your files under My_Project in your home directory, then you would issue:

          mkdir ~/My_Project
         

    to do so.

    Note

    The following steps assume you are under the working directory (~/My_Project/ in the example).

  2. Copy the Template System to The Working Directory

    Now that the working directory has been created, you need to copy a “template system tree” into it. A template directory tree is supplied under the /usr/share/Borges/template/ directory, so issue

          cp -a /usr/share/Borges/template/* .
         

    to copy the template into your working directory.

  3. Create Your Personal Profile

    Each “author” (writer, translator, proofreader, etc.) needs to define his personal profile. Borges uses the information in the profile for version management and author credits among other things. The profile is stored in conf/author.xml and a sample is provided in the conf/author.xml.in file, so just issue

          cp conf/author.xml.in conf/author.xml
         

    and edit author.xml with your favorite text editor to suite your personal data. Below you have a sample profile:

    
          <?xml version='1.0' encoding='ISO-8859-1'?>
           <author>
            <initials>pp</initials>
            <firstname>Peter</firstname>
            <lastname>Pingus</lastname>
            <mail>peter.pingus@mandrakesoft.com</mail>
            <lang>en</lang>
           </author>
         

    Tip

    Take a look at the comments in author.xml for hints about the meaning of the parameters (In the above sample, the comments are excluded for simplicity reasons).

  4. Initialize the System

    Now, Borges has to be initialized. To do so, just issue

    make

    and directories will be populated with the minimum required files.

  5. Generate the Modules Templates

    Now you have the system configured, it is time to test if it works properly. A sample document (called Sample) is provided, so we will use that one for testing purposes. Issue

          make -C manuals/Sample templates LANG=en
         

    to generate the modules templates for the sample document.

    Tip

    the -C argument of the make command simply means to make the templates target in the manuals/Sample directory. You could have run

          cd manuals/Sample; make templates LANG=en 

    also.

  6. Compile Sample to PDF and Check the Result

    Now you can compile the sample document to PDF to check how it looks. Issue

          make -C manuals/Sample master.pdf LANG=en
         

    to do so, and check the resulting PDF by issuing

          xpdf manuals/Sample/master.pdf
         

    if everything went well, you should see a nice PDF of the sample document. Of course, you can use Acrobat Reader instead of Xpdf to open the PDF if you prefer to.

  7. Compile Sample to HTML and Check the Result

    You can also compile the sample document to HTML. Issue

          make -C manuals/Sample master.flat.html LANG=en
         

    to do so, and check the results by pointing your favorite browser to ~/My_Project/manuals/Sample/master.flat.html.

  8. Generate and View the Report

    The report is a tool of 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

          make -C reports all LANG=en
         

    and view the resulting report by pointing your favorite web browser to ~/My_Project/reports/index.html.

Note

In all the above examples the LANG=en parameter is mandatory if your preferred language is other than English (en). The preferred language was set in the author.xml file, remember?

It was not that hard wasn't it? Now, you can setup Borges to work with your own projects.