|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Correcting Poor Formatting</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>LaTeX does not invariably produce good looking output. To
|
|
Packit Service |
76cb02 |
remedy this it can sometimes be useful to guide LaTeX in the
|
|
Packit Service |
76cb02 |
formatting of individual characters, words, sentences, and pages.
|
|
Packit Service |
76cb02 |
It is best to adjust with caution, making adjustments only to fix
|
|
Packit Service |
76cb02 |
specific problems and limiting adjustments to the affected
|
|
Packit Service |
76cb02 |
area.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<tip>
|
|
Packit Service |
76cb02 |
<para>Adjustments to formatting are best done late in the
|
|
Packit Service |
76cb02 |
production process so that subsequent changes to content do not
|
|
Packit Service |
76cb02 |
produce new problems.</para>
|
|
Packit Service |
76cb02 |
</tip>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>This section provides an overview of common problems and
|
|
Packit Service |
76cb02 |
summarizes methods which may be used to resolve issues related to
|
|
Packit Service |
76cb02 |
formatting. Much more detail can be found in the
|
|
Packit Service |
76cb02 |
linkend="sec-custom"/> chapter and the <xref linkend="sec-params"/>
|
|
Packit Service |
76cb02 |
and <xref linkend="sec-pis"/> appendixes. Be sure to look through
|
|
Packit Service |
76cb02 |
these, especially the appendixes, to see whether there is an
|
|
Packit Service |
76cb02 |
adjustment which will solve your particular problem. Of course the
|
|
Packit Service |
76cb02 |
DocBook documentation should also be consulted to see if a DocBook
|
|
Packit Service |
76cb02 |
attribute can be used to adjust document presentation.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Floats</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Floats are figures, tables, examples, images, and so forth
|
|
Packit Service |
76cb02 |
which do not necessarily appear in the output document in the
|
|
Packit Service |
76cb02 |
location in which they appear in the DocBook source. The
|
|
Packit Service |
76cb02 |
placement of floats can result in visually poor or otherwise
|
|
Packit Service |
76cb02 |
undesirable output.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>One direct approach is to use the <quote>informal</quote>
|
|
Packit Service |
76cb02 |
versions of the affected DocBook elements. E.g. use
|
|
Packit Service |
76cb02 |
<sgmltag>informaltable</sgmltag> instead of
|
|
Packit Service |
76cb02 |
<sgmltag>table</sgmltag>. The <quote>informal</quote> elements do
|
|
Packit Service |
76cb02 |
not float. Bear in mind though that <quote>informal</quote>
|
|
Packit Service |
76cb02 |
elements do not appear in the table of contents.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The alternative to eliminating the float entirely is
|
|
Packit Service |
76cb02 |
to make an adjustment by parameter, attributes, or processing
|
|
Packit Service |
76cb02 |
instruction. For figure, example, and equation, you can play
|
|
Packit Service |
76cb02 |
with these methods:</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<itemizedlist>
|
|
Packit Service |
76cb02 |
<listitem><para>In a specific element, use the
|
|
Packit Service |
76cb02 |
<sgmltag>floatstyle</sgmltag> attribute to
|
|
Packit Service |
76cb02 |
specify the latex float placement policy. For example
|
|
Packit Service |
76cb02 |
<literal>'[H]'</literal> tries to place the element where it is
|
|
Packit Service |
76cb02 |
declared.</para></listitem>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<listitem><para>Use the parameter
|
|
Packit Service |
76cb02 |
<literal><replaceable>element</replaceable>.defaut.position</literal>
|
|
Packit Service |
76cb02 |
to specify globaly the placement policy for this element.</para>
|
|
Packit Service |
76cb02 |
</listitem>
|
|
Packit Service |
76cb02 |
</itemizedlist>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Look at page
|
|
Packit Service |
76cb02 |
linkend="float-placement-choices"/> for more details
|
|
Packit Service |
76cb02 |
about the meaning of the placement choice letters.</para>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Tables</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Placement problems with tables relate to their
|
|
Packit Service |
76cb02 |
classification as a float. For resolution regarding these issues
|
|
Packit Service |
76cb02 |
see the section on floats above.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Tables exceeding the length of a page, or tables that
|
|
Packit Service |
76cb02 |
otherwise need to cross page boundaries, have special
|
|
Packit Service |
76cb02 |
requirements. They must not be floats and must be rendered using
|
|
Packit Service |
76cb02 |
the LaTeX <package>longtable</package> environment. Among the
|
|
Packit Service |
76cb02 |
available controls are: use of a <sgmltag>informaltable</sgmltag>
|
|
Packit Service |
76cb02 |
element in place of a <sgmltag>table</sgmltag> element, the
|
|
Packit Service |
76cb02 |
<sgmltag>table</sgmltag> element's <sgmltag>tabstyle</sgmltag>
|
|
Packit Service |
76cb02 |
attribute, the <parameter>table.default.tabstyle</parameter> parameter,
|
|
Packit Service |
76cb02 |
the <parameter>table.in.float</parameter> parameter
|
|
Packit Service |
76cb02 |
linkend="dblatex_table-in-float"/> PI-->.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>It is worth mentioning that good typesetting design practice
|
|
Packit Service |
76cb02 |
for tables generally calls for eliminating all vertical rules (the
|
|
Packit Service |
76cb02 |
lines between columns) and most horizontal rules.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Better vertical placement of
|
|
Packit Service |
76cb02 |
table horizontal rules can be obtained by providing values for
|
|
Packit Service |
76cb02 |
the <parameter>newtbl.format.thead</parameter> and
|
|
Packit Service |
76cb02 |
<parameter>newtbl.format.tbody</parameter> parameters. Depending on the
|
|
Packit Service |
76cb02 |
font in use, a value like
|
|
Packit Service |
76cb02 |
<literal>\rule{0pt}{2.6ex}\rule[-0.9ex]{0pt}{0pt}</literal> can be
|
|
Packit Service |
76cb02 |
used for both parameters. This inserts a
|
|
Packit Service |
76cb02 |
<wordasword>strut</wordasword>, a 0 width character, in each row
|
|
Packit Service |
76cb02 |
of the table which <quote>pushes</quote> the horizontal rules
|
|
Packit Service |
76cb02 |
upwards and downwards to provide adequate vertical spacing.</para>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Examples</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Placement of examples has the same issue than tables, that is, it
|
|
Packit Service |
76cb02 |
is an element that can contain many materials and need to split over
|
|
Packit Service |
76cb02 |
several pages. In this case it cannot be considered as a float.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>To avoid an example floating and to allow it cover several
|
|
Packit Service |
76cb02 |
pages, set the parameter <parameter>example.float.type</parameter>
|
|
Packit Service |
76cb02 |
to <literal>none</literal>.</para>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Hyphenation and over-long lines</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>LaTeX is generally very good at hyphenation, but this
|
|
Packit Service |
76cb02 |
applies only to actual words. Technical writing may include long
|
|
Packit Service |
76cb02 |
character sequences that are not actual words. Hyphenation
|
|
Packit Service |
76cb02 |
failure will typically result in lines of text that flow past the
|
|
Packit Service |
76cb02 |
expected right-hand edge of a line. In LaTeX terminology this is
|
|
Packit Service |
76cb02 |
known as a <quote>overfull hbox</quote>.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The <parameter>hyphenation.format</parameter> parameter can
|
|
Packit Service |
76cb02 |
be helpful to flag some formats for more agressive
|
|
Packit Service |
76cb02 |
hyphenation.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Various adjustments can be made with the
|
|
Packit Service |
76cb02 |
<sgmltag class="xmlpi">latex</sgmltag> processing instruction to
|
|
Packit Service |
76cb02 |
add raw latex directives and eliminate
|
|
Packit Service |
76cb02 |
overfull hboxes but it often makes sense to address hyphenation
|
|
Packit Service |
76cb02 |
problems directly. This can be done either on an ad-hoc basis,
|
|
Packit Service |
76cb02 |
telling LaTeX how to hyphenate specific occurrences of words where
|
|
Packit Service |
76cb02 |
a problem exists, or by telling LaTeX how to hyphenate words it
|
|
Packit Service |
76cb02 |
does not know. The first method is accomplished by inserting
|
|
Packit Service |
76cb02 |
<quote>soft hyphens</quote> into words in your DocBook source
|
|
Packit Service |
76cb02 |
using the <xref linkend="pi-latex"/> processing instruction. This is
|
|
Packit Service |
76cb02 |
described in the <xref linkend="sec-safe-latex"/> section.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>To educate LaTeX as to how to hyphenate your special
|
|
Packit Service |
76cb02 |
vocabulary a custom LaTeX style is required. Setting this up is
|
|
Packit Service |
76cb02 |
described in the <xref linkend="sec-custom-latex"/> section. The
|
|
Packit Service |
76cb02 |
LaTeX command to use is \hyphenation . For example
|
|
Packit Service |
76cb02 |
\hyphenation{PostgreSQL trans-mog-re-fi-ca-tion}
|
|
Packit Service |
76cb02 |
tells LaTeX that <wordasword>PostgreSQL</wordasword> should not be
|
|
Packit Service |
76cb02 |
hyphenated and where to hyphenate
|
|
Packit Service |
76cb02 |
<wordasword>transmogrification</wordasword>.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Finally, long URLs can cause over-long lines. Especially in
|
|
Packit Service |
76cb02 |
footnotes. Using the LaTeX <package>breakurl</package> package is
|
|
Packit Service |
76cb02 |
one way to solve this. This can be done with a custom latex
|
|
Packit Service |
76cb02 |
stylesheet. See <xref linkend="sec-custom-latex"/>.</para>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Paragraphs, Lines, and Sentences</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Widows and orphans, single (or too few) lines at the top and
|
|
Packit Service |
76cb02 |
bottom of pages, can be controlled with the
|
|
Packit Service |
76cb02 |
linkend="latex-block"/> processing instruction.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>Lines can grow longer than their normal right-hand boundary.
|
|
Packit Service |
76cb02 |
This is generally due to problems with hyphenation. Hyphenation
|
|
Packit Service |
76cb02 |
problems can arise in various ways, e.g. the introduction of
|
|
Packit Service |
76cb02 |
hyperlinks which do not hyphenate. Sometimes hyphenation cannot
|
|
Packit Service |
76cb02 |
or should not be changed. In these situations the
|
|
Packit Service |
76cb02 |
linkend="latex-block"/> processing instruction can be used to
|
|
Packit Service |
76cb02 |
prevent poorly formatted lines. It provides controls which
|
|
Packit Service |
76cb02 |
affect, among other things, the placement of line breaks.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The <xref linkend="latex.frenchspacing"/> parameter controls
|
|
Packit Service |
76cb02 |
spacing between sentences. A <quote>safe</quote>
|
|
Packit Service |
76cb02 |
linkend="latex"/> processing instruction
|
|
Packit Service |
76cb02 |
<parameter>content</parameter> value can, in some cases, provide
|
|
Packit Service |
76cb02 |
control over individual instances of this.</para>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
-->
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<section>
|
|
Packit Service |
76cb02 |
<title>Characters and Manual Spacing</title>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The <sgmltag class="xmlpi">latex</sgmltag> processing instruction
|
|
Packit Service |
76cb02 |
may be used to limit character kerning, the joining of pairs of
|
|
Packit Service |
76cb02 |
characters.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<para>The following DocBook entity declarations can be useful to
|
|
Packit Service |
76cb02 |
control spacing. These may be declared in your DocBook
|
|
Packit Service |
76cb02 |
DTD within the trailing pair of square braces
|
|
Packit Service |
76cb02 |
(<literal>[]</literal>) or elsewhere. Once declared the entities
|
|
Packit Service |
76cb02 |
may be used in your document text. E.g.
|
|
Packit Service |
76cb02 |
<literal>Von Trapp</literal> puts a non-breaking space
|
|
Packit Service |
76cb02 |
between <literal>Von</literal> and <literal>Trapp</literal>,
|
|
Packit Service |
76cb02 |
ensuring that these two words will not appear on separate
|
|
Packit Service |
76cb02 |
lines.</para>
|
|
Packit Service |
76cb02 |
|
|
Packit Service |
76cb02 |
<programlisting>
|
|
Packit Service |
76cb02 |
<!ENTITY nbsp " " >
|
|
Packit Service |
76cb02 |
<!ENTITY ensp " " >
|
|
Packit Service |
76cb02 |
<!ENTITY emsp " " >
|
|
Packit Service |
76cb02 |
</programlisting>
|
|
Packit Service |
76cb02 |
</section>
|
|
Packit Service |
76cb02 |
</section>
|