OLD | NEW |
1 | 1 |
2 XZ Utils | 2 XZ Utils |
3 ======== | 3 ======== |
4 | 4 |
5 0. Overview | 5 0. Overview |
6 1. Documentation | 6 1. Documentation |
7 1.1. Overall documentation | 7 1.1. Overall documentation |
8 1.2. Documentation for command line tools | 8 1.2. Documentation for command line tools |
9 1.3. Documentation for liblzma | 9 1.3. Documentation for liblzma |
10 2. Version numbering | 10 2. Version numbering |
11 3. Reporting bugs | 11 3. Reporting bugs |
12 4. Other implementations of the .xz format | 12 4. Translating the xz tool |
13 5. Contact information | 13 5. Other implementations of the .xz format |
| 14 6. Contact information |
14 | 15 |
15 | 16 |
16 0. Overview | 17 0. Overview |
17 ----------- | 18 ----------- |
18 | 19 |
19 XZ Utils provide a general-purpose data compression library and | 20 XZ Utils provide a general-purpose data compression library and |
20 command line tools. The native file format is the .xz format, but | 21 command line tools. The native file format is the .xz format, but |
21 also the legacy .lzma format is supported. The .xz format supports | 22 also the legacy .lzma format is supported. The .xz format supports |
22 multiple compression algorithms, which are called "filters" in | 23 multiple compression algorithms, which are called "filters" in |
23 context of XZ Utils. The primary filter is currently LZMA2. With | 24 context of XZ Utils. The primary filter is currently LZMA2. With |
(...skipping 156 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
180 Always include the exact version number of XZ Utils in the bug report. | 181 Always include the exact version number of XZ Utils in the bug report. |
181 If you are using a snapshot from the git repository, use "git describe" | 182 If you are using a snapshot from the git repository, use "git describe" |
182 to get the exact snapshot version. If you are using XZ Utils shipped | 183 to get the exact snapshot version. If you are using XZ Utils shipped |
183 in an operating system distribution, mention the distribution name, | 184 in an operating system distribution, mention the distribution name, |
184 distribution version, and exact xz package version; if you cannot | 185 distribution version, and exact xz package version; if you cannot |
185 repeat the bug with the code compiled from unpatched source code, | 186 repeat the bug with the code compiled from unpatched source code, |
186 you probably need to report a bug to your distribution's bug tracking | 187 you probably need to report a bug to your distribution's bug tracking |
187 system. | 188 system. |
188 | 189 |
189 | 190 |
190 4. Other implementations of the .xz format | 191 4. Translating the xz tool |
| 192 -------------------------- |
| 193 |
| 194 The messages from the xz tool have been translated into a few |
| 195 languages. Before starting to translate into a new language, ask |
| 196 the author that someone else hasn't already started working on it. |
| 197 |
| 198 Test your translation. Testing includes comparing the translated |
| 199 output to the original English version by running the same commands |
| 200 in both your target locale and with LC_ALL=C. Ask someone to |
| 201 proof-read and test the translation. |
| 202 |
| 203 Testing can be done e.g. by installing xz into a temporary directory: |
| 204 |
| 205 ./configure --disable-shared --prefix=/tmp/xz-test |
| 206 # <Edit the .po file in the po directory.> |
| 207 make -C po update-po |
| 208 make install |
| 209 bash debug/translations.bash | less |
| 210 bash debug/translations.bash | less -S # For --list outputs |
| 211 |
| 212 Repeat the above as needed (no need to re-run configure though). |
| 213 |
| 214 Note especially the following: |
| 215 |
| 216 - The output of --help and --long-help must look nice on |
| 217 a 80-column terminal. It's OK to add extra lines if needed. |
| 218 |
| 219 - In contrast, don't add extra lines to error messages and such. |
| 220 They are often preceded with e.g. a filename on the same line, |
| 221 so you have no way to predict where to put a \n. Let the terminal |
| 222 do the wrapping even if it looks ugly. Adding new lines will be |
| 223 even uglier in the generic case even if it looks nice in a few |
| 224 limited examples. |
| 225 |
| 226 - Be careful with column alignment in tables and table-like output |
| 227 (--list, --list --verbose --verbose, --info-memory, --help, and |
| 228 --long-help): |
| 229 |
| 230 * All descriptions of options in --help should start in the |
| 231 same column (but it doesn't need to be the same column as |
| 232 in the English messages; just be consistent if you change it). |
| 233 Check that both --help and --long-help look OK, since they |
| 234 share several strings. |
| 235 |
| 236 * --list --verbose and --info-memory print lines that have |
| 237 the format "Description: %s". If you need a longer |
| 238 description, you can put extra space between the colon |
| 239 and %s. Then you may need to add extra space to other |
| 240 strings too so that the result as a whole looks good (all |
| 241 values start at the same column). |
| 242 |
| 243 * The columns of the actual tables in --list --verbose --verbose |
| 244 should be aligned properly. Abbreviate if necessary. It might |
| 245 be good to keep at least 2 or 3 spaces between column headings |
| 246 and avoid spaces in the headings so that the columns stand out |
| 247 better, but this is a matter of opinion. Do what you think |
| 248 looks best. |
| 249 |
| 250 - Be careful to put a period at the end of a sentence when the |
| 251 original version has it, and don't put it when the original |
| 252 doesn't have it. Similarly, be careful with \n characters |
| 253 at the beginning and end of the strings. |
| 254 |
| 255 - Read the TRANSLATORS comments that have been extracted from the |
| 256 source code and included in xz.pot. If they suggest testing the |
| 257 translation with some type of command, do it. If testing needs |
| 258 input files, use e.g. tests/files/good-*.xz. |
| 259 |
| 260 - When updating the translation, read the fuzzy (modified) strings |
| 261 carefully, and don't mark them as updated before you actually |
| 262 have updated them. Reading through the unchanged messages can be |
| 263 good too; sometimes you may find a better wording for them. |
| 264 |
| 265 - If you find language problems in the original English strings, |
| 266 feel free to suggest improvements. Ask if something is unclear. |
| 267 |
| 268 - The translated messages should be understandable (sometimes this |
| 269 may be a problem with the original English messages too). Don't |
| 270 make a direct word-by-word translation from English especially if |
| 271 the result doesn't sound good in your language. |
| 272 |
| 273 In short, take your time and pay attention to the details. Making |
| 274 a good translation is not a quick and trivial thing to do. The |
| 275 translated xz should look as polished as the English version. |
| 276 |
| 277 |
| 278 5. Other implementations of the .xz format |
191 ------------------------------------------ | 279 ------------------------------------------ |
192 | 280 |
193 7-Zip and the p7zip port of 7-Zip support the .xz format starting | 281 7-Zip and the p7zip port of 7-Zip support the .xz format starting |
194 from the version 9.00alpha. | 282 from the version 9.00alpha. |
195 | 283 |
196 http://7-zip.org/ | 284 http://7-zip.org/ |
197 http://p7zip.sourceforge.net/ | 285 http://p7zip.sourceforge.net/ |
198 | 286 |
199 XZ Embedded is a limited implementation written for use in the Linux | 287 XZ Embedded is a limited implementation written for use in the Linux |
200 kernel, but it is also suitable for other embedded use. | 288 kernel, but it is also suitable for other embedded use. |
201 | 289 |
202 http://tukaani.org/xz/embedded.html | 290 http://tukaani.org/xz/embedded.html |
203 | 291 |
204 | 292 |
205 5. Contact information | 293 6. Contact information |
206 ---------------------- | 294 ---------------------- |
207 | 295 |
208 If you have questions, bug reports, patches etc. related to XZ Utils, | 296 If you have questions, bug reports, patches etc. related to XZ Utils, |
209 contact Lasse Collin <lasse.collin@tukaani.org> (in Finnish or English). | 297 contact Lasse Collin <lasse.collin@tukaani.org> (in Finnish or English). |
210 tukaani.org uses greylisting to reduce spam, thus when you send your | |
211 first email, it may get delayed by a few hours. In addition to that, | |
212 I'm sometimes slow at replying. If you haven't got a reply within two | 298 I'm sometimes slow at replying. If you haven't got a reply within two |
213 weeks, assume that your email has got lost and resend it or use IRC. | 299 weeks, assume that your email has got lost and resend it or use IRC. |
214 | 300 |
215 You can find me also from #tukaani on Freenode; my nick is Larhzu. | 301 You can find me also from #tukaani on Freenode; my nick is Larhzu. |
216 The channel tends to be pretty quiet, so just ask your question and | 302 The channel tends to be pretty quiet, so just ask your question and |
217 someone may wake up. | 303 someone may wake up. |
218 | 304 |
OLD | NEW |