Product SiteDocumentation Site

Chapter 5. Using sets

5.1. Stand-alone sets
5.2. Distributed sets
A set is a collection of books, published as a single output. The Services Plan for example is a set comprised of many books such as the Developer Guide, Engineering Content Services Guide and the Engineering Operations Guide to name just a few. The create_book command creates a template for a set by setting the type parameter to Set. There are two types of sets, stand-alone sets and distributed sets.

5.1. Stand-alone sets

A stand-alone set contains the XML files for each book, all of which are located inside the directory of the set.
The procedure that follows will guide you through the process of creating a stand-alone set named My Set located in a directory called books/My_Set/. The set will contain Book A and Book B both of which will be manually created inside the books/My_Set/en-US directory.
Procedure 5.1. Creating a stand-alone set
  1. Run the following command in a shell in the books/ directory to create a set named My_Set branded in the Red Hat style and in which the XML will be written in American English.
    publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
    
    
  2. cd into the My_Set/en-US directory and create two directories called Book_A and Book_B.
    cd My_Set/en-US
    mkdir Book_A Book_B
    
    
  3. cd into the books/My_Set/en-US/Book_A directory. Create and edit the Book_A.xml, Book_Info.xml, and any other xml files required for your book such as those required for individual chapters. Ensure that Book_A.xml contains the correct xi:include references to all of your xml files in the directory. For example, if Book A contained Book_Info.xml and Chapter_1.xml, the Book_A.xml file would look like this:
    <?xml version='1.0'?>
    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    ]>
    	  
    <book>
    	  <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
    	  <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
    </book>
    
    
  4. Use the same process for Book_B, located in the books/My_Set/en-US/Book_B directory, as per the step above.
  5. Open the books/My_Set/en-US/My_Set.xml file in an editor. For each book in the set, add an xi:include reference to the primary xml file from the book. The primary xml file for Book A will be Book_A.xml and for Book B, Book_B.xml. The My_Set.xml file should now look like this:
    <?xml version="1.0"?>
    <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    ]>
    
    <set>
    	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    </set>
    
    				
    
    
  6. Test your set by running the publican build --formats=test langs=en-US command.

5.2. Distributed sets

A distributed set contains books that are located in a version-controlled repository. Although several version control systems exist, this version of Publican supports only one: Subversion (SVN). By setting the repository location and titles of the included books in the publican.cfg file, each book can be exported to build the entire set. The procedure that follows will guide you through the process of creating a set named My Set containing Book A and Book B.

Important

The following procedure assumes that Book A and Book B already exist and are available in your SVN repository. Currently Publican only supports SVN.
Procedure 5.2. Creating a set
  1. Run the following command in a shell to create a set named My_Set branded in the Red Hat style and in which the XML will be written in American English.
    $ publican create --type=Set --name=My_Set --brand=RedHat  --lang=en-US
    
    
  2. Add the following lines to the publican.cfg file:
    books 		= Book_A Book_B
    repo	= http://PATH-TO-YOUR-SVN-REPOSITORY
    scm	= SVN
    
    
  3. Open the My_Set.xml file in an editor. For each book in the set, add an xi:include reference to the primary XML file from the book. The primary XML file for Book A will be Book_A.xml and for Book B, Book_B.xml. The My_Set.xml file should now look like this:
    <?xml version="1.0"?>
    <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    ]>
    
    <set>
    	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    </set>
    
    				
    
    
  4. Test your set by running the publican build --formats=test --langs=en-US command.

    Important

    When building a set, the publican clean_ids command will be run over each book because of the constraint that IDs must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.