DOCS/xml/README.maintainers

   1 The documentation and its translations reside in subdirectories.
   2 When building the documentation, the toplevel Makefile goes into
   3 the subdirectories listed in the SUBDIRS variable and executes make
   4 in each of those directories to create the HTML documentation
   5 in subdirectories of the 'HTML' and 'HTML-single' directories.
   6
   7 IMPORTANT: Do NOT place sensitive files under 'HTML' or 'HTML-single'!
   8            It is for generated documentation only.
   9            The whole directory tree is wiped out by the Makefile
  10            when running 'make distclean' or 'make clean'.
  11            Also, subdirectories are wiped out one by one before
  12            creating the HTML files.
  13
  14 Each subdirectory must have a Makefile.  Its purpose is to include
  15 the toplevel Makefile.inc file (with the rules to build the docs)
  16 and add dependency information to the main target, $(HTMLDIR)/index.html.
  17 The main target usually depends on all the XML and XSL files in the
  18 subdirectory.  (Note that the toplevel *.xsl files are added automatically
  19 by Makefile.inc, so you do not have to list them.)
  20
  21
  22 Adding new translations
  23 ~~~~~~~~~~~~~~~~~~~~~~~
  24
  25 1) Create a new subdirectory and copy the XML files there. main.xml must not be
  26    copied, it is autogenerated.
  27
  28 2) Make sure to create a 'Makefile' for the translation -- you can
  29    use 'en/Makefile' as an example.
  30
  31 3) If you want to use a customized XSL stylesheet, create one and name it
  32    'html-common.xsl'. Also create two additional XSL stylesheets
  33    ('html-single.xsl' and 'html-chunk.xsl'), with content such as this:
  34
  35    html-single.xsl:
  36
  37    <?xml version="1.0" encoding="ISO-8859-1"?>
  38    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  39                 version="1.0">
  40
  41   <xsl:import href="../html-single.xsl"/>
  42   <xsl:include href="html-common.xsl"/>
  43
  44   </xsl:stylesheet>
  45
  46   html-chunk.xsl:
  47
  48   <?xml version="1.0" encoding="ISO-8859-1"?>
  49   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  50                 version="1.0">
  51
  52   <xsl:import href="../html-chunk.xsl"/>
  53   <xsl:include href="html-common.xsl"/>
  54
  55   </xsl:stylesheet>
  56
  57
  58    Note: You mustn't xsl:include or xsl:import chunk.xsl directly!
  59    Including it can (and will) break building of documentation if chunk.xsl
  60    is installed at a nonstandard location.
  61
  62 4) If you wish to change the output encoding of generated files, create
  63    html-common.xsl as suggested in step 4) and add strings such as these
  64    somewhere between the <xsl:stylesheet ...> and </xsl:stylesheet> tags
  65    (please, pay attention to quotes):
  66
  67       <xsl:param name="chunker.output.encoding" select="'your_encoding'"/>
  68       <xsl:output encoding="your_encoding"/>
  69
  70 5) If you are using your own HTML stylesheet, edit your Makefile and set
  71    the HTML_STYLESHEET variable to its name. Please, don't call your HTML
  72    stylesheet 'default.css'.
  73
  74 6) In each translated file after the <?xml ... ?> tag you must put a note
  75    like <!-- synced with r2 -->, where 2 is the revision of corresponding
  76    English file (see comment at the top of file).
  77
  78 7) While your translation isn't finished, you can change USE_SYMLINKS
  79    to "yes" in your Makefile. This will help you testing your translation:
  80    English files will be used instead of untranslated ones, when generating
  81    HTML docs.
  82
  83 That's all, in theory.