RapazP - ADGen for AsciiDoc (v 2.2.1)

1. Introduction

AsciiDoc is a format text intended for the drafting of documents, articles, handbooks and of UNIX man pages.

The documents respecting the AsciiDoc format can be used same manner as a document normal text. So they can be visualized, published or be printed directly. The files, in conformity with the AsciiDoc format, can also be converted into various formats such as: PDF, HTML, DocBook or LinuxDoc.

Programmed in Python and based on XML configuration files, the application ADGen has the role to simplify the creation and the deployment of web pages written with the format AsciiDoc.

In addition to the file conversion, ADGen makes it possible to internationalize the contents of a web site, to manage the hierarchy of the directories and to set up a side menu in a web page.

Moreover, it makes possible to automatically deploy the files generated by the means of a ftp transfer.

Structure before generation	Structure after generation

1.1. Screenshots

Content tab	Preferences Tab	Add file

2. Downloads

All version are available on sourceforge.net or via links below.

File	Description
ADGen-2.2.1.tar.gz	Independant platform
ADGen\_{revisionhistory}_i386.deb	Linux Debian / Ubuntu package 32 bit
ADGen\_{revisionhistory}_amd64.deb	Linux Debian / Ubuntu package 64 bit
ADGen-win-2.2.1.zip	Windows release (without setup)
ADGen-2.2.1.pdf	Documentation for the version 2.2.1 in PDF format
ADGen-1.2.2.zip	Latest release for ADGen version 1.0

The creation of Debian packages from python source was done using the tutorial "creating a .deb package from a python setup.py"

3. Installation

Just like AsciiDoc, ADGen requires Python 2.4 or more recent to work. If you do not have Python interpreter yet on your system, you can download it on the official site http://www.python.org/.

The current version was tested under Linux (Ubuntu) and Cygwin (in command line) with AsciiDoc 8.2.6.

3.1. GNU/Linux

3.1.1. Manual installation

To perform a manual installation of the application ADGen in a Linux environment, simply extract the archive .tar.gz then run the setup script.

Sample

$ tar xvfz adgen-2.2.1.tar.gz

$ cd adgen-2.2.1

$ sudo python setup.py install

3.1.2. Package Debian / Ubuntu

Since version 2.2.0 and above, you can install ADGen through a Debian package. These are available for a 32 bit (i386) or 64-bit (amd64) architecture.

3.2. Windows

There is currently no installation script for ADGen Windows. The installation procedure is still relatively simple since you just need to extract the zip file in a new directory.

To start ADGen, move in the installation folder and launch the adgen.py or adgengui.py depending on whether you want to work in command line or with the GUI. You can also add the installation folder to your environment variable PATH in order to be able to launch the application on any folder.

The graphical version requires gtk. Normally, it must be running on Windows however no tests have been performed in this configuration.

4. Configuration files

If you are not using the GUI or you have problems with configuration files. You will find in this chapter the organization and contents of all files used by ADGen.

ADGen configuration is carried out by the means of 3 files:

adgen.conf: Contains the general configuration of ADGen. This file is located in the $HOME/.adgen folder.
ftp.conf: Optional, this file makes it possible to configure the ftp access for an automatic transfer of web files. This file is located in the $HOME/.adgen folder.
adgen.adg ou adgen.xml: Contains the data of the web project to be generated. By default, ADGen uses the configuration file located in the folder used to lauch the application, however you can specify it using the option -c.

During the first launch of ADGen, the files adgen.conf and ftp.conf are automatically created as example. To use ADGen, these files must imperatively be configured.

4.1. adgen.conf

This configuration file contains all necessary datas for ADGen.

<?xml version="1.0" encoding="UTF-8"?>
<adgen>
  <editor>
    <linux>gedit</linux>
    <windows>D:\Editra\Editra.exe</windows>
  </editor>
  <asciidoc>
    <command>
      <linux>asciidoc</linux>
      <windows>c:/asciidoc/asciidoc.py</windows>

      <extensions layoutFile=".conf" textFile=".txt" webFile=".html"/>
    </command>
  </asciidoc>
</adgen>

4.1.1. Tags

asciidoc

editor

linux	Text editor used in the Linux environment (it must be in the environment variable `PATH` or `/usr/bin`)
windows	Text editor used in Windows environment

command

linux	Linux Asciidoc command. (AsciiDoc must be in the environment variable `PATH` or in your `/usr/bin` folder)
windows	Path who is located AsciiDoc under Windows.
extensions	Extensions list used by AsciiDoc. (by default: `textFile=".txt" webFile=".html" layoutFile=".conf"`)

4.2. ftp.conf

This file is optional. It allow to define all parameters needed to connect and transfer files to the web server via ftp.

The ftp transfer reproduce exactly the same tree structure as that of your local hard disk. For this reason, the web folder, defined in the the project configuration file adgen.xml, will be the start point to deploy all files.

<?xml version="1.0" encoding="UTF-8"?>
<adgen>
  <ftpConfig>
    <host>[host_name]</host>
    <user>[user_name]</user>
    <password>[user_password]</password>

    <deploy>all</deploy>
  </ftpConfig>
</adgen>

4.2.1. Tags

ftpConfig

host

Ftp host address

user

Connexion user (can’t be anonymous).

password

Connexion password.
If you don’t want to put your password in the configuration file, you can give it in the command line with the -p option. However the password is not optional if you want to transfer files with ftp.

deploy

Indicate the elements to be transferred on the ftp server. This key can be overrided during launch with the option -d.

`all`	Transfer all files (web and text)
`text`	Transfer only text files
`web`	Transfer only web files (default option)

4.3. adgen.adg (ou adgen.xml)

This file makes it possible to configure your project.

It is divided into two sections; project which contains the general data of the project and webContent which contains the list of the files to be converted.

In order to simplify the creation of this file, the option -N in the command line create for a new empty configuration file in the current directory.

<?xml version="1.0" encoding="UTF-8" ?>
<adgen>
  <project>
    <version>2.0.0</version>

    <folder>
      <work>
        <linux>/home/spytux/web/infra</linux>
        <windows>c:/web/infra</windows>

        <web>/web/infra</web>

        <rootText>text</rootText>
        <rootHtml>..</rootHtml>
      </work>

      <icons>images/icons</icons>
    </folder>

    <layout>
      <tableBased>layout1</tableBased>
      <simulFrame>layout2</simulFrame>
    </layout>

    <tocTitle>
      <title lang="en">Table of content</title>
      <title lang="fr">Table des mati&amp;egrave;res</title>
    </tocTitle>
  </project>

  <webContent backend="xhtml11" defaultLanguage="fr">
    ...

    <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
    <!--                     SAMPLE PROJECT SECTION                      -->
    <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
    <section webFolder=".." textFolder="opensource" treeNode="opensource">
      <fileName isNumbered="true" isSimulFrame="true">opensource</fileName>
      <fileName isNumbered="true" isSimulFrame="true">internet</fileName>
      <fileName isNumbered="true" isSimulFrame="true">tools</fileName>
    </section>

    <section webFolder="../.." textFolder="opensource/tools" treeNode="opensource">
      <fileName isNumbered="toc" isSimulFrame="true" lang="fr">AsciiDoc</fileName>
       <fileName isNumbered="toc" isSimulFrame="true" lang="en">AsciiDoc</fileName>
    </section>

    <section webFolder="../.." textFolder="opensource/internet" treeNode="opensource">
      <fileName isNumbered="false" isSimulFrame="true">firefox</fileName>
    </section>

    ...
  </webContent>

  ...
</adgen>

4.3.1. Tags

project

This tag contains general information of the project.

version

Allows to specify the version of the generated files.

folder

Allows to configure the sources and destinations folders used by the generator.

work

linux	Absolute directory used as root folder when generating under linux.
windows	Idem above but for Windows.
web	Absolute folder used as root for the web deployment via ftp. This folder must exist on the server ftp.
rootText	This folder is used as root to find the `.txt` to be converted. It must be given relatively to the directory defined above.
rootHtml	This folder is used as root to write the files generated by AsciiDoc. It must be given relatively to the directory defined above.

icons

Folder of the Web site containing the icons. This tag is used to inform the option "iconsdir=" of AsciiDoc.

layout

tableBased: Division table based layout
simulFrame: Simulated frames using CSS. (This kind of layout is not supported by Internet Explores 6)

tocTitle

Allow to internationalize the table of content title.

webContent

This tag contains the list of documents to be converted via AsciiDoc.

webContent

Its attributes are as follows:

`backend`	indicate the `backend` used by AsciiDoc for the generation of the files. (optional)
`defaultLanguage`	Allows to specify the default language of the generated pages. This attribute can be overrided for each document.

section

Allows to configure the documents to be converted. It is necessary to define a tag section by folder.

The attributes are as follows:

`webFolder`	Relative path to the tag work (higher defined) in which the generated files will be saved.
`textFolder`	Relative path to the tag work (higher defined) containing the files to be converted.
`treeNode`	Allows to specify the node to be used in the side menu of the web page.

fileName

Name of the file to be converted (without the extension)

The attributes are as follows:

`isNumbered`	true or notoc if sections of the document must be numbered, toc or toc_X (X indicates the level number of the contents (1..4)) to have table of content and numbered sections and false or none in contrary case. If this attribute is not present, the sections are not numbered (idem false or none). (optional)
`isSimulFrame`	true to use the frame simulated layout and false to use the traditional layout.
`lang`	Allows to specify the language of the current document. (optional)

The documents translated in several languages will have to be saved with initial language before the file extension:

Source		Destination
asciidoc.en.txt	→	asciidoc.en.html
asciidoc.fr.txt	→	asciidoc.fr.html
`defaultLanguage`	→	asciidoc.html

4.4. Menus and Attributes

Some attributes as been added to manage new ADGen functionalities. These attributes can be used in the layouts configuration file

{baseFolder}

The variable \{baseFolder} is replaced by the webFolder tag content.

  <link rel="stylesheet"
        href="{stylesdir={baseFolder}stylesheets}/{theme={backend}}.css"
        type="text/css" />

{iconsdir}

The attribute \{iconsdir} is replaced by the tag icons. This attribute can be used to indicate the web site icons folder.

  <link rel="shortcut icon" href="{iconsdir}/mini_logo.png" />
  <link rel="icon" href="{iconsdir}/mini_logo.png" />

{language}

The tag \{language} can be defined to set the variable Content-Language.

  <meta http-equiv="Content-Language" content="{language}" />

{tocTitle}

This tag allow to internationalize the title used during table of content generation.

  ifdef::toc[]
    <script type="text/javascript"
            src="{scriptsdir={baseFolder}scripts}/toc.js">
    </script>
  endif::toc[]

  ...

  ifdef::toc[]
    <div id="toc">
      <div id="toctitle">{tocTitle}</div>
      <noscript>
        <p><b>
          JavaScript must be enabled in your browser to display the table of contents.
        </b></p>
      </noscript>
    </div>
  endif::toc[]

The management of the menus is carried out on the level of the file of parameter setting of the layouts. The state of a menu can either be opened, or closed; this is determined by the tag treeNode in the configuration file (XML).

 <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 <!--                           SAMPLE MENU                           -->
 <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
 ifndef::opensource[]
   <img style="border:none; width:10px; height:10px;"
        alt="left_arrow"
        src="{baseFolder}images/icons/left_arrow.png" />
   <a href="{baseFolder}opensource/opensource.html">OpenSource</a>
 endif::opensource[]
 ifdef::opensource[]
   <img style="border:none; width:10px; height:10px;"
        alt="down_arrow"
        src="{baseFolder}images/icons/down_arrow.png" />
   <a href="{baseFolder}opensource/opensource.html">OpenSource</a>
   <div id="sub-menu">
     <div><a href="{baseFolder}opensource/internet.html">Internet</a></div>
   </div>
   <div id="sub-menu">
     <div><a href="{baseFolder}opensource/tools.html">Outils</a></div>
   </div>
 endif::opensource[]

4.5. Using command line

By default, the adgen.py application treats the entirety of the file of configuration. It is however possible to personalize the execution using the options described below.

4.6. Options

-h, --help: Show help message and exit
-N, --newproject: Create a new project configuration file adgen.xml in the current directory
-b, --browse: Open the browser to visualize the page. If the option -f is not specified, the index.html page is open.
-c XMLCONFIGFILE, --config=XMLCONFIGFILE: Allows to specify the file of configuration XML to be used (by default: ADGenConf.xml)
-d, --deploymode: Allows to overrid the ftp deployment mode (values: text, web or all)
-f FILE(S), --file=FILE(S): Allows to specify files to be treated (without the extension). Multi-files can be separated with comma.
-o, --output: Allows to overload the rootHtml value during execution
-p, --password: Allows to specify the password used to access to the ftp server if it isn’t specified in the XML configuration file.
-t, --transfer: Transfer generated files on the ftp server.
-v, --verbose: Display all commands and their parameters.
-V, --Version: ADGen Version and copyright

5. Development

5.1. Architecture

This chapter presents the architecture of the application ADGen.

5.1.1. Principle

Architecture diagram for ADGen

5.1.2. Content

/src
  /adgen
    /config
      adgenConfig.py          Management of the file 'adgen.conf'
      adgenConstants.py       Applications constants
      configHelper.py         Basic class for the management of the configuration files xml
      ftpConfig.py            Management of the file 'ftp.conf'
      projectConfig.py        Management of the file 'adgen.adg' or 'adgen.xml'

    /core
      adgenCore.py            Common class used by command line and graphical mode
      helper.py               Helper functions

    /ftp
      ftpManager.py           Class for the management of ftp transfers

    /gui
      /component
        contentTreeView.py    TreeView component used to manage the project file ('.adg' or '.xml')
        logEvents.py          Component used to display all I/O
        tocTreeView.py        Component used to manage translation of toc

      /glade
        adgen.glade           Graphical interface for the application
        adgen.svg             Logo used by glade

      /icons                  All icons used by the application

      /widget
        aboutWidget.py        'About' dialog box
        addContentWidget.py   Dialog box used to manage project file or section
        addTocWidget.py       Dialog box used to add a new language for the toc title
        fileChooserWidget.py  Dialog box used for the 'file open/save'
        messageWidget.py      Dialog box used to display messages
        preferencesWidget.py  Dialog box used to manage 'ADGen' global preferences

      adgen.desktop           Usefull for the creation of the Gnome launcher

    /util
      adgenI18N.py            Manage the internationalization of the application
      logTool.py              Allows you to centralize all I/O messages sent to stdin and stdout

    adgen.py                  Main application
    adgengui.py               Main application for the graphical mode

  /bin
    adgen                     Shell script to launch 'ADGen' in command line
    adgengui                  Shell script to launch 'ADGen' in graphical mode

  /debian                     Contains files needed to create Debian / Ubuntu packages.

  /docs
    adgen.en.txt              English documentation
    adgen.fr.txt              French documentation

  CHANGELOG                   Follow-up of the modifications (English)
  COPYING                     Terms of the GPL license
  INSTALL                     Installation procedure
  MakeFile                    Make file to build Debian / Ubuntu package
  MANIFEST.in                 Manifest used by 'setup.py' during application packaging
  README
  release.sh                  Helper script to create the release
  setup.py                    Helper script for 'ADGen' installation
  uninstall.sh                Helper script useful if you want to uninstall 'ADGen' after using 'setup.py'

5.2. Todo

Below, the list of the various functionalities having to be developed for the deliveries to come:

Simplify the management of the side menu by taking of account information of the project configuration file `adgen.xml `
Direct call of AsciiDoc 8.4.2 new APIs (without using a sub-process)
Support other AsciiDoc options
Allow to transfer ftp files without Asciidoc transformation