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
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="129" version="5.0" xml:id="sect-Publican-Users_Guide-Conditional_tagging" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info xml:id="info-Publican-Users_Guide-Conditional_tagging">
<title>Conditional tagging</title>
</info>
<para>
In some cases you may need to maintain multiple versions of a book; for example, a HOWTO guide for product FOO can have an upstream version and an enterprise version, with very subtle differences between them.
</para>
<para>
<application>Publican</application> makes it easy to manage differences between multiple versions of a book by allowing you to use a single source for all versions. <firstterm>Conditional tagging</firstterm> allows you to make sure that version-specific content only appears in the correct version; that is, you <firstterm>conditionalize</firstterm> the content.
</para>
<para>
To conditionalize content in a book, use the tag attribute <command>condition</command>. For example, let's say the book <citetitle>How To Use Product Foo</citetitle> has an "upstream", "enterprise", and "beta" version:
</para>
<programlisting language="XML"><para condition="upstream">
<application>Foo</application> starts automatically when you boot the system.
</para>
<para condition="enterprise">
<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>.
</para>
<para condition="beta">
<application>Foo</application> does not start automatically when you boot the system.
</para>
<para condition="beta,enterprise">
To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file.
</para></programlisting>
<para>
To build a specific version (and thereby capture all content conditionalized for that version), add the <command>condition: <replaceable>version</replaceable></command> parameter to the <filename>publican.cfg</filename> file and run the <prompt>$</prompt> <command>publican build</command> command as normal. For example, if you add <literal>condition: upstream</literal> to the <filename>publican.cfg</filename> file of <citetitle>How To Use Product Foo</citetitle> and run:
</para>
<screen><prompt>$</prompt> <command>publican build --formats=pdf --langs=en-US</command></screen>
<para>
<application>Publican</application> filters out all tags with condition attributes other than <literal>condition="upstream"</literal> and builds <citetitle>How To Use Product Foo</citetitle> in as a PDF file in American English.
</para>
<xi:include href="Root_nodes_and_conditionals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="xrefs_and_conditionals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<section conformance="130" xml:id="sect-Publican-Users_Guide-Conditional_tagging-Conditional_tagging_and_translation">
<info xml:id="info-Publican-Users_Guide-Conditional_tagging_and_translation">
<title>Conditional tagging and translation</title>
</info>
<warning>
<info xml:id="info-Publican-Users_Guide-Use_conditional_tagging_with_great_caution">
<title>Use conditional tagging with great caution</title>
</info>
<para>
Use conditional tagging only with great caution in books that you expect to be translated, as conditional tagging creates extra difficulties for translators.
</para>
</warning>
<para>
Conditional tagging creates difficulty for translators in two ways: it obscures context in the <firstterm>portable object</firstterm> (PO) files through which translators work, and it makes proofreading more difficult for translators who are not deeply familiar with your book and all the conditions that you have set.
</para>
<para>
The PO files for the document contain the full set of tags from the XML files, regardless of any conditions set. When translators open the PO file for the example from <citetitle>How To Use Product Foo</citetitle> in <xref linkend="sect-Publican-Users_Guide-Conditional_tagging" />, they see:
</para>
<programlisting>#. Tag: para
#, no-c-format
msgid "<application>Foo</application> starts automatically when you boot the system."
msgstr ""
#. Tag: para
#, no-c-format
msgid "<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>."
msgstr ""
#. Tag: para
#, no-c-format
msgid "<application>Foo</application> does not start automatically when you boot the system."
msgstr ""
#. Tag: para
#, no-c-format
msgid "To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file."
msgstr ""</programlisting>
<para>
Because PO files include do not include attributes from tags, there is nothing obvious here to show translators that these paragraphs are alternatives to each other and that the writer does not intend that meaning should flow from one paragraph to the next.
</para>
<para>
In this example, the only paragraphs where the meaning flows logically from one to the next is between paragraphs three and four. Because both of these paragraphs appear in the book for the beta version of the product, they (hopefully) make sense together. Beyond that, the use of conditionals here requires translators to translate individual small chunks of content without the ability to follow the context from one paragraph to the next. When translators must work under these conditions, the quality of the translation will suffer, or the time required — and therefore the cost of translation — will increase.
</para>
<para>
Furthermore, unless the translators who work on your book know how to configure <application>Publican</application>'s <filename>publican.cfg</filename> file and are aware of the valid conditions for your book, they cannot proofread their work. Without that knowledge, when translators proofread a document, they will wonder why they cannot find text that they know they translated and can find easily in the PO file. If you must use conditionals in your book, you must be prepared to provide a greater degree of support to your translators than you would otherwise provide.
</para>
<para>
As an alternative to conditionals, consider maintaining separate versions of your book in separate branches of a version-controlled repository. You can still share XML files and even PO files between the various branches as necessary, and some version control systems allow you to share changes readily among branches.
</para>
<para>
If you maintain two versions of a book in the same repository, we recommend using a separate config file for each version. For example, the <filename>upstream.cfg</filename> file might contain the condition <literal>condition: upstream</literal> and the <filename>enterprise.cfg</filename> file might contain the condition <literal>condition: enterprise</literal>. You could then specify the version of the document to build or package with the <option>--config</option>; for example, <prompt>$</prompt> <command>publican package --lang en-US --config upstream.cfg</command>. Using two separate config files saves you from having to edit the one config file each time you build or package a document.
</para>
</section>
</section>
|
