<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE preface [
<!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;
]>
<preface conformance="190" version="5.0" xml:id="pref-Publican-Users_Guide-Introduction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
	<info>
		<title>Introduction</title>

	</info>
	 <indexterm>
		<primary>Introduction 1</primary>

	</indexterm>
	 <para>
		<indexterm><primary>Introduction 2</primary></indexterm> <application>Publican</application> <indexterm><primary>Introduction 3</primary> <secondary>Introduction 3</secondary></indexterm> \ \n \p is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using <application>Publican</application>. It is not a general DocBook XML tutorial; refer to <citetitle>DocBook: The Definitive Guide</citetitle> by Norman Walsh and Leonard Muellner, available at <uri xlink:href="http://www.docbook.org/tdg/en/html/docbook.html" xmlns:xlink="http://www.w3.org/1999/xlink">http://www.docbook.org/tdg/en/html/docbook.html</uri> for more general help with DocBook XML.
	</para>
	 <para>
		<application>Publican</application> began life as an internal tool used by Red Hat's Documentation Group (now known as Engineering Content Services). On occasion, this legacy is visible.
	</para>
	 <formalpara conformance="191" xml:id="form-Publican-Users_Guide-Introduction-Design">
		<info>
			<title>Design</title>

		</info>
		 <para>
			<application>Publican</application> is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, <application>Publican</application> works to ensure your XML is up to publishable standard.
		</para>

	</formalpara>
	 <para>
		The branding functionality allows you to create your own presentation rules and look, overriding many parts of the default style to meet your publishing needs. Choices executed in code, however, are not changeable.
	</para>
	 <para>
		Entities, for example, can be validly defined in any XML file. However, to ensure the DTD declaration is present, valid and standardized, <application>Publican</application> rewrites the declaration in every XML file before it builds a book or article. Consequently, all entities declared in all XML files are lost. <application>Publican</application>, therefore, requires you define entities in the <filename><replaceable>Doc_Name</replaceable>.ent</filename> file (refer to <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory-Doc_Name.ent" />).
	</para>
	 <para>
		As publishing workflows grow, unrestrained entity definition leads to entity duplication and other practices that cause maintenance difficulties. Consolidating entity definitions in a single, predictable place alleviates these maintenance issues and helps the automation of the build process stay robust.
	</para>
	 <para>
		Entities also present an essentially insurmountable obstacle to quality translation (refer to <xref linkend="sect-Publican-Users_Guide-Entities_and_translation" />). Consequently, while we are not reducing the <filename><replaceable>Doc_Name</replaceable>.ent</filename> file's functionality, we are no longer considering requests to add functionality or features associated with entity use.
	</para>
<section id="Testing_New_Styles" condition="testing">
<title>This section is for testing the output and doesn't ship in the production docs</title>
<section id="BZ1092351">
<title>Testing BZ #1092351 Code Switcher</title>
	 <informalexample conformance="264" id="switch1" role="switchery">
<programlisting language="Perl" linenumbering="numbered">#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World!\n";
</programlisting>
<programlisting language="C++"><![CDATA[#include <iostream>

int main()
{
  std::cout << "Hello World!"; &lies;
}]]></programlisting>
	 </informalexample>
</section>
<section id="BZ1088051">
<title>Testing BZ #1088051 Code Popper</title>
<screen role="popper" linenumbering="numbered"><prompt>$</prompt> <command>apt-get search libxslt</command>
<computeroutput>gambas3-gb-xml-xslt - Gambas XSLT component</computeroutput>
<computeroutput>libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)</computeroutput>
<computeroutput>libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)</computeroutput>
<computeroutput>libical-parser-html-perl - generates HTML calendars from iCalendars</computeroutput>
<computeroutput>libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java</computeroutput>
<computeroutput>libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter</computeroutput>
<computeroutput>libxml-libxslt-perl - Perl interface to the GNOME libxslt library</computeroutput>
<computeroutput>libxslt1-dbg - XSLT 1.0 processing library - debugging symbols</computeroutput>
<computeroutput>libxslt1-dev - XSLT 1.0 processing library - development kit</computeroutput>
<computeroutput>libxslt1.1 - XSLT 1.0 processing library - runtime library</computeroutput>
<computeroutput>python-libxslt1 - Python bindings for libxslt1</computeroutput>
<computeroutput>python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)</computeroutput>
<computeroutput>python-lxml - pythonic binding for the libxml2 and libxslt libraries</computeroutput>
<computeroutput>python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)</computeroutput>
<computeroutput>python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)</computeroutput>
<computeroutput>python3-lxml - pythonic binding for the libxml2 and libxslt libraries</computeroutput>
<computeroutput>python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)</computeroutput>
<computeroutput>php5-xsl - XSL module for php5</computeroutput>
<computeroutput>libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt</computeroutput>
<computeroutput>libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt</computeroutput>
<computeroutput>swfmill - xml2swf and swf2xml processor</computeroutput>
<computeroutput>libxslthl-java - XSLT syntax highlighting</computeroutput></screen>
<para>&nbsp;</para>
</section>
<section id="BZ1112899">
<title>Testing BZ #1112899 Callouts and BZ #1101050 Entities in CDATA</title>
	 
<!--
     https://bugzilla.redhat.com/show_bug.cgi?id=604255
-->
<para>Test a programlisting with a calloutlist</para>
<example> 
  <title>"Hello world!" in C++</title>
  <programlisting><![CDATA[
#include <qpid/messaging/Connection.h>
#include <qpid/messaging/Message.h>
#include <qpid/messaging/Receiver.h>
#include <qpid/messaging/Sender.h>
#include <qpid/messaging/Session.h> &BZ1101050;

#include <iostream>]]>

using namespace qpid::messaging;

int main(int argc, char** argv) {
    std::string broker = argc > 1 ? argv[1] : "localhost:5672";
    std::string address = argc > 2 ? argv[2] : "amq.topic";
    Connection connection(broker); 
    try {
        connection.open();  <co id="hello-cpp-open" linkends="callout-cpp-open"/>
        Session session = connection.createSession(); <co id="hello-cpp-session" linkends="callout-cpp-session"/>

        Receiver receiver = session.createReceiver(address); <co id="hello-cpp-receiver" linkends="callout-cpp-receiver"/>
        Sender sender = session.createSender(address); <co id="hello-cpp-sender" linkends="callout-cpp-sender"/>

        sender.send(Message("Hello world!"));

        Message message = receiver.fetch(Duration::SECOND * 1); <co id="hello-cpp-fetch" linkends="callout-cpp-fetch"/>
        <![CDATA[std::cout << message.getContent() << std::endl;]]>
        session.acknowledge(); <co id="hello-cpp-acknowledge" linkends="callout-cpp-acknowledge"/>

        connection.close(); <co id="hello-cpp-close" linkends="callout-cpp-close"/>
        return 0;
    } catch(const std::exception&amp; error) {
        <![CDATA[std::cerr << error.what() << std::endl;]]>
        connection.close();
        return 1;   
    }
  }</programlisting>

  <calloutlist>
    <callout id="callout-cpp-open" arearefs="hello-cpp-open">
      <para>Establishes the connection with the messaging broker.</para>
    </callout>
    <callout id="callout-cpp-session" arearefs="hello-cpp-session">
      <para>Creates a session object, which maintains the state of all
interactions with the messaging broker, and manages senders and
receivers.</para>
    </callout>
    <callout id="callout-cpp-receiver" arearefs="hello-cpp-receiver">
      <para>Creates a receiver that reads from the given address.</para>
    </callout>
    <callout id="callout-cpp-sender" arearefs="hello-cpp-sender">
      <para>Creates a sender that sends to the given address.</para>
    </callout>
    <callout id="callout-cpp-fetch" arearefs="hello-cpp-fetch">
      <para>Reads the next message. The duration is optional, if omitted, will
wait indefinitely for the next message.</para>
    </callout>
    <callout id="callout-cpp-acknowledge" arearefs="hello-cpp-acknowledge">
      <para>Acknowledges messages that have been read. To guarantee delivery, a
message remains on the messaging broker until it is acknowledged by a client.
session.acknowledge() acknowledges all unacknowledged messages for the given
session&mdash;this allows acknowledgements to be batched, which is  more
efficient than acknowledging messages individually.</para>
    </callout>
    <callout id="callout-cpp-close" arearefs="hello-cpp-close">
      <para>Closes the connection, all sessions managed by the connection, and
all senders and receivers managed by each session.</para>
    </callout>
  </calloutlist>
</example>
<para>And now we test a programlistingco with an areaspec</para>
<programlistingco>
    <areaspec>
 <area id="index1" coords="2 55"/>
 <area id="index2" coords="3 11"/>
    </areaspec>
<programlisting language="XML" linenumbering="numbered">  &lt;list-index 
        column="column_name"
        base="0|1|..."/&gt;
</programlisting>
    <calloutlist>
 <callout arearefs="index1">
     <para>
  <literal>column_name</literal> (required): the name of the column holding the
  collection index values.
     </para>
 </callout>
 <callout arearefs="index2">
     <para>
  <literal>base</literal> (optional - defaults to <literal>0</literal>): the
value
  of the index column that corresponds to the first element of the list or
array.
     </para>
 </callout>
    </calloutlist>
</programlistingco>
</section>
<section id="BZ752021">
<title>Testing BZ #752021 Cross-Browser embed external video</title>
<mediaobject>
  <videoobject>
     <videodata contentdepth="413" contentwidth="660" autoplay="false" controls="" format="video/webm" fileref="https://clips.vorwaerts-gmbh.de/VfE.webm"/>
   </videoobject>
 </mediaobject>
<mediaobject>
  <videoobject>
     <videodata contentdepth="413" contentwidth="660"
 fileref="https://player.vimeo.com/video/30704252?title=0[1844952446]byline=0[1844952446]portrait=0"/>
   </videoobject>
    <caption/>
 </mediaobject>
<mediaobject>
  <videoobject>
     <videodata fileref="https://youtube.com/embed/B-Wd-Q3F8KM"/>
   </videoobject>
 </mediaobject>
</section>

<section id="1110611">
<title>Testing BZ #1110611 A line break is automatically inserted after cdata in code.</title>
<para>Is there a newline inserted after this <code><![CDATA[CDATA]]></code>?</para>
</section>
<section id="1117561">
<title>Testing BZ #1117561 CDATA tags</title>
<para><![CDATA[=, >, >=, <, <=, <>]]></para>
<para><![CDATA[!=]]></para>
<para><![CDATA[<>]]></para>
</section>
<section id="1135827">
<title>Testing BZ #1135827 Single line comment being highlighted in a callout.</title>

				 <programlistingco>
					<areaspec>
						<area coords="18" id="wih.service.ex" />
						 <area coords="22" id="wih.mgr.completion" />

					</areaspec>
					 
<programlisting language="Java">
package com.sample;

import org.kie.api.runtime.process.WorkItem;
import org.kie.api.runtime.process.WorkItemHandler;
import org.kie.api.runtime.process.WorkItemManager;

public class NotificationWorkItemHandler implements WorkItemHandler {

  public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
    String from = (String) workItem.getParameter("From");
    String to = (String) workItem.getParameter("To");
    String message = (String) workItem.getParameter("Message");
    String priority = (String) workItem.getParameter("Priority");

    // send email
    EmailService service = ServiceRegistry.getInstance().getEmailService();
    service.sendEmail(from, to, "Notification", message);

    // notify manager that work item has been completed
    manager.completeWorkItem(workItem.getId(), null);
  }

  public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
  // Do nothing, notifications cannot be aborted
  }

}</programlisting>
					 <calloutlist>
						<callout arearefs="wih.service.ex">
							<para>
								The <code>ServiceRegistry</code> class is an example class implementing the task business logic.
							</para>

						</callout>
						 <callout arearefs="wih.mgr.completion">
							<para>
								The <function>completeWorkItem()</function> call completes the work item execution.
							</para>

						</callout>

					</calloutlist>

				</programlistingco>
</section>

<section id="1168765">
<title>Testing BZ #1168765 programlisting no longer support language attribute.</title>
<programlisting language="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?><test></test>]]></programlisting>

</section>

<!--                                 
<para>
<equation>
<title>My MathML example</title>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML">
  <mml:mrow>
    <mml:mo>&sum;</mml:mo>
    <mml:mn>4</mml:mn>
    <mml:mo>+</mml:mo>
    <mml:mi>x</mml:mi>
  </mml:mrow>
</mml:math>
</equation>
</para>
-->
</section>
</preface>