= Debmake documentation source

All files included in this source tree are under the MIT license with its text
in the LICENSE file except for the files which explicitly claim differently in
them.

== Git repository

All updates should be committed to "devel" branch of the Git repository at

  https://salsa.debian.org/debian/debmake-doc

The "devel" branch is meant to build the non-native Debian binary package
using the “debmake -t -i debuild” command with quasi-native Debian package
scheme as described in 6.2.

Playing with git purely from command line isn't easy.  Please consider using
GUI tool such as gitk.

== Build

The build process involves several files for make:

* Makefile -- "package" target does “debmake -t -i debuild”
* Makefile.common -- Common build parameters
* Makefile.pkg -- "pkg" target to generate the packaging example logs
* Makefile.dbk -- build documentation from the asciidoc source and the
  packaging example logs

== Normal build

The packaging of debmake-doc is:

* package build by "make package" from the git "devel" branch.
* upload package with "dput"
* Import to git with "gbp import-dsc" with "pristine-tar" (master, upstream,
  pristine-tar branches).
* Merge "master" into "devel" branch for readable history.

The execution of "make package" regenerates the packaging example logs and
runs full document package build in chroot.

This takes long time and isn't friendly for debug.

== Debug build

Since regenerating the packaging example logs takes time, we provide a way to
avoid this step for people updating the text not involving the packaging
example logs.

First, you set up source with:

 $ export DEBUG=1 # more verbose reporting
 $ sudo apt-get update
 $ sudo apt-get install git gitk debmake devscripts
 $ sudo apt-get build-dep debmake-doc
 $ git clone [email protected]:debian/debmake-doc.git
 $ cd debmake-doc
 $ gitk --all     # check the source (you are on "master" now.)
 $ git checkout --track origin/upstream
 $ git checkout --track origin/pristine-tar
 $ git checkout --track origin/devel
 $ git checkout devel
 $ make pkg       # building packaging log example

or

 ...
 $ git clone --branch devel [email protected]:debian/debmake-doc.git
 $ cd debmake-doc
 $ gitk --all     # check the source (you are on "devel" now.)
 $ make pkg       # building packaging log example

(Checking out branch may be easier if you use GUI of gitk.  That is what I
actually do here.)

Then refresh files under po/ directory with:

 $ make base-xml  # building base xml from asciidoc
 $ make all-xml   # building all xml source while updating PO from base-xml

or simply as:

 $ make build     # building all xml source while updating PO from asciidoc

Now you are ready to translate this source by hacking PO files under po/
directory using tools such as poedit.  The result of your translation can be
previewed with the browser by generating html files.

 $ make LANGPO=<lang> css html  # preview html

Results are found under tmp/html/ .

If you get error free html file, you may wish to check PDF file.

 $ make LANGPO=<lang> pdf  # preview PDF

Results are found under tmp/ .

If satisfied, make sure to commit only your modified PO files to git "devel"
branch.  Assuming you are editing po/<lang>.po:

 $ git add po/<lang>.po
 $ git commit po/<lang>.po

Update English original content by hacking ASCIIDOC text files under asciidoc/
directory.  The result can be previewed with the browser by generating html
files. 

 $ make base-xml  # building base xml from asciidoc
 $ make LANGPO= all-xml   # building all xml source while updating PO from base-xml
 $ make LANGPO= css html  # preview html

Please note that LANGPO is set to empty string in the above.

Results are found under tmp/html/ .

If you get error free html file, you may wish to check PDF file.

 $ make LANGPO= pdf  # preview PDF

Results are found under tmp/ .

If you are checking ASCIIDOC markup issue and wish to test build without going
through XML, there is an alternative html build method:

 $ make pkg       # building packaging log example
 $ cd asciidoc
 $ make

The result is asciidoc/debameke-doc.html

== po

This directory contain po files for translator.

In order to keep the translation in sync with the English, po/pot files are
generated in the way not to contain <screen> contents and url attribute of
<ulink>.

This is done directly by the itstool from gettext (without using po4a) as
described in the above "Debug build".

If you updated a PO file while others committing the same file before you
commit it, merging of the PO file isn't trivial.  Don't try to merge just by
git.  Here is the way to do it.

* Copy your latest po/<lang>.po to outside of the source tree as
  /path/to/<lang>.po.my .
* Use gitk to checkout local "devel" branch.
* Use gitk to reset your local "devel" to "remotes/origin/devel" (hard reset).
* Use "git pull origin devel"
* Move po/<lang>.po to po/<lang>.po.their .
* Move back /path/to/<lang>.po.my to po/<lang>.po.my .
* msgcat --use-first po/<lang>.po.my po/<lang>.po.their >po/<lang>.po
* Update po with the latest source "make build"

Now you have merged PO to po/<lang>.po .

You may un-fuzzy and commit po/<lang>.po .

== debian-template/

This directory contains a set of template files used to be copied to debian/*
files of many examples of the packaged source tree.

The changelog file is for the latest version of the package example which is
split up properly for each version and copied accordingly.

== debhello-<version>/

Each of these contains an entire set of an example source tree with properly
packaged debian/* files.

The upstream tarball used in the packaging example are generated by the tar
command while excluding the debian/ directory.

== debhello-<version>-pkg<revision>/

These are used to generate the packaging process example.

These contain step<number>.cmd files which are executed sequentially and the
results are logged to the step<number>.log files with the script program.

Since the step<number>.log files are terminated by <CR><LF>, may contain
<TAB>, and may be too long, the filtered step<number>.slog files are generated.

The <revision> is usually 1 and it matches the Debian revision of the binary
packages generated.

If you wish to run script-by-script, you can do the following
 $ make step<number>.raw

Some cmd files running program which waits user input uses the expect command
to automate it to move forward.

== .stamp

The existence of .stamp file in each directory indicates all the files in the
directory has been generated via Makefile and up-to-date.  This is not
committed to the VCS.

== asciidoc/

This contain the source text files written in the asciidoc markup. Their
extension is usually .txt .

// vim:se tw=78 sts=4 ts=4 et ai: