README

   1 File      : README          - This file
   2 Directory : docbook         - Contains docbook/XML source for many releases of documentation
   3 Directory : script          - Contains build scripts
   4 Directory : templates       - All the XSL templates and other required files
   5 Directory : templates/doc   - templates for generating HTML from docbook/xml documentation
   6 Directory : templates/web   - Contains all other web content
   7 Directory : templates/i     - required images
   8 Directory : templates/howto - Howto documentation source
   9 File      : templates/wrapper.xsl   - The HTML wrapper. The stuff that's common across all web pages
  10
  11 script/gen does all the magic. Run it with no arguments to get a
  12 list of options. It takes the stylesheets wrapper.xsl, and those
  13 inside the "web" and "doc" directories and creates a website from
  14 them. You also tell it where to find spec.xml and filter.xml and it
  15 will create the documentation pages from that. Here are some
  16 examples:
  17
  18 ## Example 1:
  19
  20   script/gen --latest 4.72 --web --tmpl templates --docroot /var/www/
  21
  22 This copies all of the files from the "templates/web" directory
  23 into "/var/www/". When it comes across .xsl files, it generates
  24 html from them instead. For non .xsl files, if the last-modified
  25 timestamp of the file is the same as the one already in /var/www/
  26 it's ignored.
  27
  28 ## Example 2:
  29
  30   script/gen --latest 4.72 --spec docbook/*/spec.xml \
  31     --tmpl templates --docroot /var/www/
  32
  33 If there are multiple spec.xml files in "specs/*/" for different
  34 versions of the documentation, this command will generate the
  35 appropriate webpages in /var/www-exim-html-$VERSION/. spec.xml
  36 contains the version number it's self, so it uses that in $VERSION
  37
  38 ## Example 3:
  39
  40   script/build /var/www/
  41
  42 Generates everything into output directory /var/www
  43 Look at the script/build for details - it is just a wrapper
  44 around script/gen
  45
  46
  47 All of the above examples make sure the exim-html-current symlink
  48 is kept in place. When a new version of Exim is released, we need
  49 to generate the new spec and filter documentation, and update the
  50 main web pages to reflect the new version number. That would be as
  51 simple as running a command like that in Example 4, with the latest
  52 version number, and just for the latest spec.xml and filter.xml
  53 files.
  54
  55 If you wanted to, for example, add a new link to the navigation bar
  56 on all pages, you would need to re-generate *all* web pages. This
  57 is a drawback of having a static website without frames. You would
  58 only need to edit one file though, specifically wrapper.xsl. Once
  59 that is done, you would run gen with --web, --spec and --filter,
  60 providing the filter.xml and spec.xml files for every piece of
  61 online documentation.
  62
  63 --latest should always specify the current stable version of Exim.
  64 Even if you're generating documentation pages for an older version.
  65 The script needs to know what the current version of Exim is, as it
  66 is mentioned in several places on the website, and is also needed
  67 to create the correct symlink for exim-html-current.