==============================================================================
#              README.source for debian-reference (Version 2 series)         #
#                     Sun, 24 Nov 2013 12:39:43 +0000                        #
#                    Osamu Aoki, osamu at debian dot org                     #
==============================================================================

The web pages generated for the DDP are build directly from the released
package.  You can find them linked from:
  http://www.debian.org/doc/user-manuals#quick-reference

= Quick start =

The latest source is viewable via HTTP:
 http://anonscm.debian.org/gitweb/?p=ddp/debian-reference.git

When you commit a translation file, please only commit the updated
po/<language>.po to the master branch.  (No po/templates.pot, *.xml, *.ent, nor
*.txt files)

If you are not familiar with git, it may be a good idea to submit
po/<language>.po to the BTS.  Then the package maintainer can update the
source.

This source is maintained in the alioth ddp debian-reference git repository as
indicated in the Vcs-Git control fields.  You can get the source as:
 $ git clone git://anonscm.debian.org/ddp/debian-reference.git
 $ cd debian-reference
or if you already have local copy:
 $ cd path/to/debian-reference
 $ git checkout master
 $ git pull

It is good idea to create a local branch local-1 and work on it as:
 $ git checkout -b local-1
  ... edit and test   <----------------\<------------------------------------\
 $ git commit -a -m "Describe ..."     ^                                     ^
 $ make wrap;make po                   | (check fuzzy.log)                   |
  ... go back to edit ---------------->/                                     |
                                                                             |
Since po/*.po files are not easy to be merged with git, I suggest to commit  |
only updated po/*.po files to the master branch.                             |
                                                                             |
After everything is fine in the local branch, update master tree not by      |
using "git merge" but by "git checkout <branch> <file>" to the master        |
branch as:                                                                   |
 $ git checkout master                                                       |
 $ git checkout local-1 po/<language>.po                                     |
 $ make wrap;make po                     (check fuzzy.log)                   |
 $ git add po/<language>.po                                                  |
 $ git commit -m "Describe commit ..."                                       | 
 $ git checkout -b local-2 (repeat for local-2 in place for local-1) ------->/

Before start making commits to the alioth repo directly, please make sure to
coordinate with the maintainer.

The Alioth write access can be gained by joining the ddp group as described
in:
  https://wiki.debian.org/Teams/DDP

Alioth write access is normally done via SSH (password-less login).

== Test building after translation ==

If you just translated a PO file, e.g. "it.po", please
reformat and test it first by:
 $ make wrap
 $ make test "LANGPO=it"

You have HTML files under the html/ directory.

Specifying "LANGPO" variable as above saves build time by skipping other
languages.

== Minor English updates ==

For minor English updates in ASCIIDOC files with neither new URL references nor
new packages, please test them first by:
 $ make test "LANGPO="

If this test causes no error, clean the source tree and commit it with:
 $ make clean
 $ git add asciidoc/*
 $ git commit -m "Updated ...."
 $ make wrap; make po; make clean
 $ git commit -a -m "make po"

== Major English updates ==

For major English updates in ASCIIDOC files with new URL references or new
packages, please distclean first by:
 $ make distclean

The rest are the same "Minor English updates".

==============================================================================
= Build environment =

Required packages for the local test building:
 * Packages listed in Build-Depends and Build-Depends-Indep stanza found 
   in debian/control.
 * dctrl-tools
 * wget
 * devscripts and its recommended packages
 * PO file editor such as poedit
 * git and gitk

For the package building, it is good idea to use tools such as
 * pbuilder
 * cowbuilder
 * git-buildpackage

==============================================================================
= Flow chart for the building of this documentation =

The English source is kept as ASCIIDOC(*) files under asciidoc/.
The translation source is kept as PO files under po/.

  >>> all the asciidoc/*.txt files 
                   :(make rawxml)                  
                   v
  >>> debian-reference.raw.xml ------>  (make entity) <=> remotely fetched
        |          |   |                              :    data files (+)
        |          |   +---------------------+        :
        |          |                         |        :              
        |          v                         v        v              
        |   debian-reference.en.xml   common.ent   url.ent and *.ent files
        |          : (**)        |           |        |      
        v          v             |           |        |
      debian-reference.en.xmlt   |           |        |
        |                        |           |        |
        v                        |           |        |
      templates.pot              |           |        |
        |                        |           |        |
        v (make po)              |           |        |
  >>> ja.po                      |           |        |
        |    fuzzy.log (++)      |           |        |
        v                        |           |        |
      debian-reference.ja.xml    |           |        |
        |                        |           |        |
        v                        v           v        v
        +----------+-------------+-----------+--------+
                   |(make all), (make test),
                   |(make html), (make txt), (make pdf), ...  (#)
                   v
      all documents (*.*.html *.*.txt *.*.pdf)

(*)  ASCIIDOC used in this package is bin/asdciidoc which is a customized
     script based on the older version.
(+)  When the English source changes URL link location or packages mentioned 
     in the package list table, you need to update *.ent files in the source 
     by running "make entity" with remote file access.
(**) debian-reference.en.xmlt effectively replaces untranslatable contents in
     debian-reference.en.xml with "DUMMY" to reduce clutter in PO files.
(++) fuzzy.log file contain # of fuzzy translation.  If not zero, please update
     PO file.
(#)  PDF files are not buildable due to tool chain issues.

==============================================================================
= Tips for working with PO files =

Sanity check of a PO file:
 $ msgcat some.po >/dev/null

 -> Look for unquoted " and accidental folding of lines.

Remove duplicate entries in a PO file:
 $ mv some.po some.old.po
 $ msguniq some.old.po >some.po

Merge PO files:

When 2 person update a PO file, you need to merge them using gettext tools.

You can check if 2 PO files are different using:
 $ msgcat --less-than=2 filename.po.mine filename.po.their

If you have no order of preference:
 $ msgmerge --no-wrap filename.po.mine filename.po.their >filename.po

Look for "#-#-#-#-#" where manual resolution is needed and resolve it
via editor.

Add a new PO:

You can create a new template PO file for a new language and edit it as:

 $ cd po
 $ cp templates.pot ??.po
 $ poedit ??.po

Wikipedia URLs:

bin/interwiki script can be used to check translated URLs.

==============================================================================
= Tricks for ASCIIDOC and PO files =

There are some non-conventional tricks used in ASCIIDOC to work around special
characters.

@@@ in ASCIIDOC:

You see quite a bit of @@@ in asciidoc source.  That is placed there
when idiosyncrasies of asciidoc hit me.  The result of Asciidoc to raw.xml 
conversion is filtered with the sed script bin/replace to get right 
characters into the resulting XML file (debian-reference.en.raw) without 
worrying about asciidoc converting them into something funny.

For example: @@@sq@@@ is converted to ' 

These conversions occur right after asciidoc conversion but before
storing to raw.xml files.  So this is used as purely the workaround for 
the asciidoc idiosyncrasies.

@-@ in ASCIIDOC and RAWXML:

You see quite a bit of @-@ in asciidoc and generated XML source.  That
is placed there when auto-generated data replaces them as entity in the
final form (*.xml, *.po, *.html, ...).

For example:
 @-@foo@-@     is converted to the entity definition &foo;
 @-@popcon1@-@ is converted to popcon value and URL link of package in
               column 1.
 @-@psize1@-@  is converted to size value and URL link of package in
               column 1.
 @-@popcon2@-@ is converted to popcon value and URL link of package in
               column 2.
 @-@psize2@-@  is converted to size value and URL link of package in
               column 2.

These survive asciidoc conversion but are transformed into XML when conversion
from raw.xml to en.xml happens.

==============================================================================
= URL in the English ASCIIDOC source and PO files =

When selecting URL in the English ASCIIDOC source, please make sure to pick an
internationalized URL which understands the browser language preferences.

The top entries of PO files contain URLs.  If URL is internationalized, such
URLs can be kept as in in the PO files. I.e., (msgid == msgstr):

  msgid "http://www.debian.org/"
  msgstr "http://www.debian.org/"

For Wikipedia, you should find and set the translated URL in the PO files.
I.e., (msgid == msgstr):

  msgid "http://en.wikipedia.org/wiki/Application_binary_interface"
  msgstr "http://ja.wikipedia.org/wiki/Application_Programming_Interface"

If URL uses UTF-8 characters, use original ones instead of ones with "%" for
readability.  Please note most wikipedia pages have link to the translated text
at the left of web page.

Do not change "&foo;" in the msgstr of a PO file for translating URL
references.  Look for the top part of the PO file defining the "foo" entity.

==============================================================================
= List of make targets =

 $ make all       # build all
 $ make test      # build html for testing (for Translator)
 $ make package   # build html and text from RAWXML/PO for DDP
 $ make publish   # build html text pdf from RAWXML/PO for DDP
 $ make clean     # clean files ready for tar 
 $ make distclean # clean files to reset RAWXML/ENT/POT
 $ make rawxml    # update RAWXML from ASCIIDOC
 $ make entity    # update ENT and local cache data from RAWXML/REMOTE
 $ make po        # update all PO from RAWXML
 $ make wrap      # wrap all PO
 $ make xml       # update all *.XML from RAWXML/ENT/PO/ADD
 $ make css       # update CSS and IMAGES in $(PUBLISHDIR)
 $ make html      # update all HTML in $(PUBLISHDIR)
 $ make txt       # update all Plain TEXT in $(PUBLISHDIR)
 $ make pdf       # update all PDF in $(PUBLISHDIR)
 $ make tex       # update all TeX source in $(PUBLISHDIR)
 $ make url       # check duplicate URL references

Osamu

