= 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 git@salsa.debian.org: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 git@salsa.debian.org: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: