-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.source
208 lines (139 loc) · 6.63 KB
/
README.source
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
= 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: