<?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>?&gt;</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>
