Readme_Maemo_Documentation_Toolchain_PreFinal.txt

The Maemo Documentation Infrastructure project has reached PreFinal release for 
the Maemo Documenation Toolchain development. This release is done to allow 
Maemo communtiy to review and give feedback for the toolchain.


MAEMO DOCUMENTATION TOOLCHAIN DETAILS

    * Toolchain version: Maemo Documentation Toolchain version 0.2.4 - PreFinal
    * Release date: 08.02.2010
    * Technologies supported: LaTeX, PDF, HTML, MediaWiki, Midgard
    * Download link: http://tablets-dev.nokia.com/maemo-dev-env-downloads.php

    Maemo base releases supported

    * Maemo Fremantle 5.x releases
    * Maemo Diablo 4.1.2 releases

    Linux distributions supported

    * Ubuntu 9.04 Janunty Jackalope (and later)
    * Debian 5.0 Lenny (and later)


FILES INCLUDED TO MAEMO DOCUMENTATION TOOLCHAIN DELIVERY

    Maemo specific packages:
    * README - readme file for the Maemo documentation toolchain
    * maemodoc-toolchain_0.2.4           - Maemo documentation scripts
    * maemodoc-toolchain-wikify_0.2.4    - MediaWiki conversion script  
    * maemodoc-toolchain-mediawiki_0.2.4 - MediaWiki import environment
    * latex2html_2008-2maemo2            - Maemo updated latex2html tool

    Debian Lenny specific packages (newer versions of packages)
    * libboost-regex1.40.0_1.40.0-2
    * libicu42_4.2.1-3_i386.deb
    * source-highlight_3.1-2_i386.deb
    

SHORT DESCRIPTION

    * Maemo Documentation Toolchain includes only wellknown open source tools.
    * Installation of Maemo Documentation Toolchain uses local repository for 
      those packages that Nokia has modified or that do not yet have later 
      enough version available for standard Debian or Ubuntu distribution.
    * Maemo Documentation Toolchain is based on LaTeX and uses latex2html 
      and pdflatex tools to produce high quality PDF and HTML versions of 
      Maemo documents.
    * Easy to use scripts are provided to automate documentation generation 
      from LaTeX with command line and menu interfaces.
    * For HTML version of documents tools are provided to convert them to 
      the MediaWiki import format.
    * For MediaWiki import format documents tools are provided to import 
      them to the MediaWiki service.
    * MediaWiki import only updates wiki pages if same updated document gets 
      imported to the same location in MediaWiki as the previous import.
    * For HTML version of documents tools are provided to import them to 
      the maemo.org Midgard.
    * Maemo Documentation Guidelines LaTeX document provides an example 
      and instructions how to create Maemo documents using Maemo 
      Documentation Toolchain so that high quality PDF, HTML and MediaWiki 
      conversions are possible.


INSTALLATION

- Unpack the toolchain package tarball to some convenient location.

  $ tar -C /path/to/local/repo -xzf maemodoc-toolchain_0.2.4.tar.gz


- Tell apt where to find the packages
 
  Create a file /etc/apt/sources.list.d/maemodoc-toolchain-local.list 
  with the contents.
    
    deb file:///path/to/local/repo/maemodoc-toolchain /

  and tell apt to update its list of available packages

    $ sudo apt-get update     


- Install the toolchain.

    $ sudo apt-get install maemodoc-toolchain


- Optionally install the wiki import tool.

    $ sudo apt-get install maemodoc-toolchain-mediawiki
 
  This is only required if you want to be able to import wikified 
  documentation into MediaWiki and will pull in MediaWiki, Apache and 
  MySQL as dependencies but will /not/ touch their configuration.


TOOLCHAIN USAGE

The executables are installed in /usr/bin.

- `maemodoc-toolchain' consists of the following scripts

    - maemodoc-menu         a simple frontend for maemodoc-html and 
                            maemodoc-pdf ; can be used to generate HTML 
                            and PDF from and to wikify Maemo LaTeX documents

    - maemodoc-html         a LaTeX-HTML conversion tool

    - maemodoc-pdf          a LaTeX-PDF conversion tool

    - maemodoc-scaleimage   a tool for automatically scaling and rotating 
                            images to conform to the Maemo documentation 
                            size constraints


- `maemodoc-toolchain-wikify' pulled in as a dependency, contains

    - maemodoc-wikify       a tool for (media)wikifying HTML generated 
                            by maemodoc-html


- `maemodoc-toolchain-mediawiki' contains just one script

    - maemodoc-importwiki   a tool for importing maemodoc-wikified 
                            documents into MediWiki

The packages install the normal bits, copyright and such, in /usr/share/doc.


Simply unpack the LaTeX files somewhere:

    $ tar xvzf maemodoc-baseline-latex_wXY.tar.gz

Run one of `maemodoc-menu', `maemodoc-html' or `maemodoc-pdf'. 
Use `-H' or `--help' to get a list of tool parameters.