Introduction

Publican is a tool for publishing material authored in DocBook XML. This guide explains how to create and build books and articles using Publican. It is not a general DocBook XML tutorial; refer to DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner, available at http://www.docbook.org/tdg/en/html/docbook.html for more general help with DocBook XML.

Publican 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.

Design. Publican is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, Publican works to ensure your XML is up to publishable standard.

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.

Entities, for example, can be validly defined in any XML file. However, to ensure the DTD declaration is present, valid and standardized, Publican rewrites the declaration in every XML file before it builds a book or article. Consequently, all entities declared in all XML files are lost. Publican, therefore, requires you define entities in the Doc_Name.ent file (refer to Section 1.6, “Doc_Name.ent”).

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.

Entities also present an essentially insurmountable obstacle to quality translation (refer to Section 1.6.1, “Entities and translation”). Consequently, while we are not reducing the Doc_Name.ent file's functionality, we are no longer considering requests to add functionality or features associated with entity use.

1. This section is for testing the output and doesn't ship in the production docs

1.1. Testing BZ #1092351 Code Switcher

PerlC++
#!/usr/bin/perl
use strict;
use warnings;

print "Hello, World!\n";
#include <iostream>

int main()
{
  std::cout << "Hello World!"; &lies;
}

1.2. Testing BZ #1088051 Code Popper

[Show All][Hide]$ apt-get search libxslt
gambas3-gb-xml-xslt - Gambas XSLT component
libidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)
libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)
libical-parser-html-perl - generates HTML calendars from iCalendars
libxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Java
libxml-filter-xslt-perl - Perl module for XSLT as a SAX Filter
libxml-libxslt-perl - Perl interface to the GNOME libxslt library
libxslt1-dbg - XSLT 1.0 processing library - debugging symbols
libxslt1-dev - XSLT 1.0 processing library - development kit
libxslt1.1 - XSLT 1.0 processing library - runtime library
python-libxslt1 - Python bindings for libxslt1
python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)
python-lxml - pythonic binding for the libxml2 and libxslt libraries
python-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)
python3-lxml - pythonic binding for the libxml2 and libxslt libraries
python3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)
php5-xsl - XSL module for php5
libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxslt
libsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxslt
swfmill - xml2swf and swf2xml processor
libxslthl-java - XSLT syntax highlighting

 

1.3. Testing BZ #1112899 Callouts and BZ #1101050 Entities in CDATA

Test a programlisting with a calloutlist

Example 1. "Hello world!" in C++

#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();  1
        Session session = connection.createSession(); 2

        Receiver receiver = session.createReceiver(address); 3
        Sender sender = session.createSender(address); 4

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

        Message message = receiver.fetch(Duration::SECOND * 1); 5
        std::cout << message.getContent() << std::endl;
        session.acknowledge(); 6

        connection.close(); 7
        return 0;
    } catch(const std::exception& error) {
        std::cerr << error.what() << std::endl;
        connection.close();
        return 1;   
    }
  }
1

Establishes the connection with the messaging broker.

2

Creates a session object, which maintains the state of all interactions with the messaging broker, and manages senders and receivers.

3

Creates a receiver that reads from the given address.

4

Creates a sender that sends to the given address.

5

Reads the next message. The duration is optional, if omitted, will wait indefinitely for the next message.

6

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—this allows acknowledgements to be batched, which is more efficient than acknowledging messages individually.

7

Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.

And now we test a programlistingco with an areaspec

  <list-index 
        column="column_name"                                    1 
        base="0|1|..."/>               2 
1

column_name (required): the name of the column holding the collection index values.

2

base (optional - defaults to 0): the value of the index column that corresponds to the first element of the list or array.

1.4. Testing BZ #752021 Cross-Browser embed external video

1.5. Testing BZ #1110611 A line break is automatically inserted after cdata in code.

Is there a newline inserted after this CDATA?

1.6. Testing BZ #1117561 CDATA tags

=, >, >=, <, <=, <>

!=

<>