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 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<refentry id="pi-latex">
<refmeta>
<refentrytitle>latex</refentrytitle>
</refmeta>
<refnamediv>
<refname><sgmltag class="xmlpi">latex</sgmltag>, <sgmltag class="xmlpi">db2latex</sgmltag></refname>
<refpurpose>Insert Arbitrary text into the LaTeX file</refpurpose>
</refnamediv>
<refsynopsisdiv>
<programlisting><![CDATA[<?latex ]]><replaceable>content</replaceable><![CDATA[ ?>]]></programlisting>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>These Processing Instructions are unusual in that they have no
<quote>attribute</quote>. Instead, the
<replaceable>content</replaceable> is put directly into the
generated LaTeX document.</para>
<para>The <sgmltag class="xmlpi">db2latex</sgmltag> PI is deprecated
and should not be used anymore. It was provided for backward
compatibility. Use the <sgmltag class="xmlpi">latex</sgmltag> PI
instead.</para>
<para>This can provide the ultimate in customization, but can be
very dangerous since it breaks the abstractions provided by
dblatex.</para>
<warning>
<para>These Processing Instructions can be used
to inject arbitrary LaTeX into the output stream. Please check if a
safer customization method can be used instead. See the other
<link linkend="sec-custom">customization methods</link>.</para>
<para>While it is pretty clear that insertion of certain sorts
of LaTeX text, at some points within the document, will always
be expected to work, there is no guarantee that
<emphasis>any</emphasis> inserted LaTeX will continue to work in
the future with newer versions of dblatex or its underlying
software stack.</para>
<para>Inserting LaTeX into <code>CDATA</code>, i.e. in places
where document text appears, is likely to be more robust than
inserting LaTeX elsewhere. But again, no guarantees are
made.</para>
</warning>
<para>Care must be taken with whitespace. Leading and trailing
spaces matter within the processing instruction. The
<replaceable>content</replaceable> consists of everything
following the first space and before the closing
<literal>?></literal>. Further care must be taken with any
whitespace which follows the processing instruction -- the TeX
tokenization scan may consume whitespace which follows the
processing instruction. One possible solution when this happens
is to end your <replaceable>content</replaceable> with the
<literal>\</literal> character.</para>
<para>The <sgmltag class="xmlpi">latex</sgmltag> Processing Instruction
takes special steps to work in verbatim blocks,
<sgmltag>screen</sgmltag>, <sgmltag>programlisting</sgmltag>, and
<sgmltag>literallayout</sgmltag> elements, while
<sgmltag class="xmlpi">db2latex</sgmltag> is directly written as is.</para>
</refsection>
<refsection id="sec-safe-latex">
<title>Safe LaTeX Insertions</title>
<para>Although the <package>latex</package> processing instruction
can be dangerous there are a few <package>latex</package>
<parameter>content</parameter> values that are safe to use within
<code>CDATA</code> words, within the words of the actual text of
your document. The following <parameter>content</parameter>
values provide LaTeX with information it can use to improve your
document's formatting:</para>
<variablelist>
<varlistentry id="latex_softhyphen">
<term><literal>\-</literal></term>
<listitem>
<para>Soft hyphen. A backslash followed by a dash indicates
a soft hyphen. LaTeX may or may not break the line and
hyphenate at this point. Useful when over-long variable
names and similar fail to hyphenate and thereby cause lines
to exceed their normal lengths.</para>
<para>Once a soft hyphen is inserted into a word the
insertion point becomes the only place at which hyphenation
is permitted in that occurrence of the word.</para>
</listitem>
</varlistentry>
<varlistentry id="latex_no-kern">
<term><literal>{}</literal></term>
<listitem>
<para>Do not kern (join together) characters. An empty pair
of curly braces placed between two characters indicates that
the characters should not be joined together. Depending on
the font and the characters, some pairs of characters may be
joined together. E.g. a pair of lower-case
<literal>f</literal> characters may be have a their
crossbars joined. This may not be desirable, as when each
of the characters is a component of a separate word within a
larger compound word. Placing this PI between the
characters which are to remain separated prevents the two
characters from kerning.</para>
</listitem>
</varlistentry>
<varlistentry id="latex_no-kern-really">
<term><literal>{\kern0pt}</literal></term>
<listitem>
<para>Really, do not kern (join together) characters. A
stronger version of <literal>{}</literal>.</para>
</listitem>
</varlistentry>
<varlistentry id="latex_end-of-sentence">
<term><literal>\@</literal></term>
<listitem>
<para>A backslash followed by the at sign, when placed after
a capital letter and before a period, indicates that the
period is the end of a sentence. Periods following capital
letters do not otherwise end sentences and sentences may be
used by LaTeX when determining layout.</para>
<!-- <para><literal>\@</literal> has no effect when <xref
linkend="latex.frenchspacing"/> is on.</para> -->
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>Context</title>
<para>Recognized in all elements.</para>
</refsection>
</refentry>
|