[Po4a-commits] "po4a/share/doc po4a-build.xml, NONE, 1.1 po4a.config, NONE, 1.1"

[Neil Williams]

Update of /cvsroot/po4a/po4a/share/doc
In directory alioth:/tmp/cvs-serv28295/doc

Added Files:
	po4a-build.xml po4a.config 
Log Message:
	* README: trying to describe what I'm seeking here.
	* doc/po4a-build.xml: Prototype manpage for po4a-build
	* doc/po4a.config: po4a-build config file for it's own
	manpage translation, in due course.
	* po/.cvsignore: Ignore the POT
	* po4a-build: Switch to po4a-build as the script name and
	po4a-build.conf as the config file name. Comment out
	"debianism" of looking for debian/changelog.
	* po4a-build.conf: Internal conf file for eventual manpage
	generation and translation.
	* po4a-build.conf.example: SCRIPTS= unsupported - better done
	using the Makefile snippets, see README.



--- NEW FILE: po4a.config ---

[po4a_paths] doc/po/po4a-build.pot
[type:docbook] doc/po4a-build.xml

--- NEW FILE: po4a-build.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="po4a-build">
  <refentryinfo>
    <productname>po4a-build</productname>
    <productnumber/>
  </refentryinfo>
  <refmeta>
    <refentrytitle>po4a-build</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">PO4A</refmiscinfo>
    <refmiscinfo class="manual">PO4A</refmiscinfo>
  </refmeta>
  <refnamediv id="name">
    <refname>po4a-build</refname>
    <refpurpose>build translated documentation</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>po4a-build</command>
      <group>
        <arg>-f</arg>
        <arg>--file </arg>
        <replaceable> FILE</replaceable>
      </group>
      <group>
        <arg>--pot-only</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>po4a-build</command>
      <group>
        <arg>-?</arg>
        <arg>-h</arg>
        <arg>--help</arg>
        <arg>--version</arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para><command>po4a-build</command> is intended to make it as easy to
    produce translated documentation as it can be to produce the current
    untranslated content.
    </para>
    <para>Documentation in a format supported by <command>po4a</command>
    can be built using <command>po4a-build</command>. Both the untranslated
    and translated content is built as a single process, updating the POT
    files at the same time.
    </para>
    <para>Existing build instructions are replaced by a single call to
    <command>po4a-build</command> and a simple configuration file is used
    to tell <command>po4a-build</command> how to build each element and
    which binary packages will include the translated and untranslated
    content.
    </para>
    <para>Once built, the content will be in package-specific directories
    beneath the <option>BASEDIR</option> specified in the configuration file.
    For a binary package foo, with translations into German and French, this
    would result in:
    </para>
    <programlisting>
BASEDIR/foo/man/man1/foo.1
BASEDIR/foo/man/de/man1/foo.1
BASEDIR/foo/man/fr/man1/foo.1
    </programlisting>
    <para>This makes it easy to include all the generated content into the
    binary package with a single install location:
    </para>
    <programlisting>
doc/foo/man/* ./usr/share/man/
doc/foo/html/* ./usr/share/doc/foo/
    </programlisting>
    <para>This rule will not need to be updated when new translations are
    added and adding a second binary package (bar) allows the content for
    that package to kept separate.
    </para>
  </refsect1>
  <refsect1 id="config">
    <title>CONFIGURATION</title>
    <para><command>po4a-build</command> uses a default configuration file,
    <filename>po4a-build.conf</filename> which should be in the top level
    directory of your package VCS. (Use the <option>-f</option> option to
    specify a different file.)
    </para>
    <example id="config">
    <title>example configuration file</title>
    <para>An example configuration file is available at:
    </para>
    <programlisting>
/usr/share/doc/po4a-build/po4a-build.conf.ex
    </programlisting>
    </example>
    <refsect2 id="layout">
      <title>configuration file layout</title>
      <para>The configuration file consists of several sections, general,
      XML/XSL support, POD support and HTML support.
      </para>
      <para>General includes the name and location of the po4a config
      file (probably best to leave this as <filename>po4a.config</filename>),
      the po directory containing the documentation PO files (often
      <filename>doc/po</filename>), the full name of the POT file used
      to create the translations, the BASEDIR for the generated output,
      whether the package contains manpages in section 3 rather than just
      section 1 and the names of the binary packages which are to contain
      the generated output.
      </para>
      <para>XML/XSL support includes specifying which of the binary packages
      use XSL support in the XMLPACKAGES variable, the top level DocBook
      file to pass to <command>xsltproc</command> and the location of the
      XML or Docbook files. The XSLFILE can be overridden, if necessary.
      </para>
      <para>POD support includes specifying which of the binary packages
      use POD support in the PODPACKAGES variable and the full name
      of the POD file.
      </para>
      <para>HTML support specifies the subdirectory to create below
      BASEDIR for the untranslated and translated HTML content and the
      DocBook file to generate the HTML. The HTMLXSL file can be overridden,
      if necessary.
      </para>
    </refsect2>
  </refsect1>
  <refsect1 id="commands">
    <title>COMMANDS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>--pot-only</option></term>
        <listitem>
          <para>Only updates the POT file(s). <option>--pot-only</option>
          is intended to support packages including all POT files in the
          package source. Packages using autotools can easily add the POT
          file via EXTRA_DIST but packages just using a Makefile or
          certain VCS build helpers can find it awkward to add the POT file
          (which is a generated file) without putting the POT file into
          the VCS. To avoid this ugly and unnecessary work, 
          <command>po4a-build</command> can update the POT file(s) at the
          start of the build, so that <command>dpkg-source</command>
          includes them into the source tarball.
          </para>
          <example id="svn">
            <title>svn-buildpackage example</title>
            <para><command>svn-buildpackage</command> has explicit support
            for this kind of addition, using the <option>useNativeDist</option>
            SVN property and the <option>native-dist</option> Make
            target.
            </para>
            <programlisting>
# adds the POT file to the source tarball
native-dist: Makefile
	po4a-build --pot-only
            </programlisting>
            <programlisting>
$ svn propset useNativeDist 1 debian
            </programlisting>
          </example>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-h</option>|<option>--help</option></term>
        <listitem>
          <para>print the usage message and exit.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>--version</option>
        </term>
        <listitem>
          <para>print the usage message and exit.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="options">
    <title>OPTIONS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-f</option>|<option>--file</option><replaceable> FILE</replaceable></term>
        <listitem>
          <para>Override the <command>po4a-build</command> default
          configuration file (<filename>po4a-build.conf</filename>)
          and supply your own.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para><command>po4a-build</command> was written
      by Neil Williams <email>codehelp at debian.org</email>.
    </para>
    <para>This manual page was written by Neil Williams
      <email>codehelp at debian.org</email>
    </para>
  </refsect1>
</refentry>