Bug 748198

The CSBuilder delivers a zip file to the client via a REST interface.
The zip file contains a publican book ready to build, composed of the
topics in the structure specified by the supplied Content Spec.


CREATE THE BOOK SKELETON

1. Create a folder with the name contentSpec.Title, where all spaces are
replaced by underscores.
   eg:
   contentSpec.Title = Zanata Quickstart
   folder name: Zanata_Quickstart

   From here on, this folder name is referred to as the
contentSpec.escapedTitle.

2. In that folder, create a file called "publican.cfg", with the
following contents:

-- begin publican.cfg --

  # CSBuilder: <csBuilder.version>
  # Day Mon DD HH:MM:SS YYYY

  xml_lang: "en-US"
  type: Book
  brand: <contentSpec.brand>

-- end publican.cfg --

 Set the brand to "common" (no quotes) if none is specified by the
contentSpec.

3. In that folder, create a directory called "en-US"

4. In the en-US folder, create a file Book_Info.xml, with the following
contents:

Note that double << >> are used here to denote a replaceable element.
The replaceable element should be programatically inserted and both <<
>> removed.
-- begin Book_Info.xml --

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "<<contentSpec.escapedTitle>>.ent">
%BOOK_ENTITIES;
]>
<bookinfo
id="book-<<contentSpec.escapedTitle>>-<<contentSpec.escapedTitle>>">
        <title><<contentSpec.Title>></title>
        <subtitle>Subtitle goes here</subtitle>
        <productname><<contentSpec.product>></productname>
        <productnumber><<contentSpec.version>></productnumber>
        <edition>0</edition>
        <pubsnumber>0</pubsnumber>
        <abstract>
                <para>
                      	A brief paragraph describing this book. This will
be used as the description for the rpm package.
                </para>
        </abstract>
        <corpauthor>
                <inlinemediaobject>
                        <imageobject>
                                <imagedata
fileref="Common_Content/images/title_logo.svg" format="SVG" />
                        </imageobject>
                </inlinemediaobject>
        </corpauthor>
        <xi:include href="Common_Content/Legal_Notice.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="Author_Group.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

-- end Book_Info.xml --

5. In the en-US folder, create a file Author_Group.xml, with the
following contents:

-- begin Author_Group.xml --

?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "<<contentSpec.escapedTitle>>.ent">
%BOOK_ENTITIES;
]>
<authorgroup>
	<author>
                <firstname>Staff</firstname>
                <surname>Writer</surname>
                <affiliation>
                        <orgname>Red Hat</orgname>
                        <orgdiv>Engineering Content Services</orgdiv>
                </affiliation>
                <!-- <email></email> -->
        </author>
</authorgroup>

-- end Author_Group.xml

6. In the en-US folder, create a file Preface.xml, with the following
contents:

-- begin Preface.xml --

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "<<contentSpec.escapedTitle>>.ent">
%BOOK_ENTITIES;
]>
<preface id="pref-<<contentSpec.escapedTitle>>-Preface">
        <title>Preface</title>
        <xi:include href="Common_Content/Conventions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="Feedback.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback
xmlns:xi="http://www.w3.org/2001/XInclude">
                <xi:include href="Common_Content/Feedback.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
        </xi:fallback>
        </xi:include>
</preface>

-- end Preface.xml --

7. In the en-US folder, create a file Revision_History.xml, with the
following contents:

-- begin Revision_History.xml --

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "<<contentSpec.escapedTitle>>.ent">
%BOOK_ENTITIES;
]>
<appendix id="appe-<<contentSpec.escapedTitle>>-Revision_History">
        <title>Revision History</title>
        <simpara>
                <revhistory>
                        <revision>
                                <revnumber>0-0</revnumber>
                                <date>DAY MON DD YYYY</date>
                                <author>
                                        <firstname>CSBuilder</firstname>
                                        <surname>Robot</surname>
                                        <!-- <email></email> -->
                                </author>
                                <revdescription>
                                        <simplelist>
                                                <member>Initial creation
of book by CSBuilder</member>
                                        </simplelist>
                                </revdescription>
                        </revision>
                </revhistory>
        </simpara>
</appendix>

-- end Revision_History.xml --

8. In the en-US folder, create a file <contentSpec.escapedName>.ent,
with the following content:

-- begin <contentSpec.escapedName>.ent --

<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "<<contentSpec.escapedName>>">
<!ENTITY YEAR "YYYY">
<!ENTITY HOLDER "| You need to change the HOLDER entity in the
en-US/<<contentSpec.escapedName>>.ent file |">

-- end <contentSpec.escapedName>.ent --

9. In the en-US folder, create a file <contentSpec.escapedName>.xml,
with the following content:

-- begin <contentSpec.escapedName>.xml --

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "<<contentSpec.escapedName>>.ent">
%BOOK_ENTITIES;
]>
<book>
      	<xi:include href="Book_Info.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="Preface.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />

</book>

-- end <contentSpec.escapedName>.xml

10. In the en-US folder create a folder "images"

11. Copy the file "icon.svg" to the images folder.


CHAPTERS AND SECTIONS


12. Process the Content spec contents (either from the content spec
itself, or using the levels in the database)

For each Chapter write a separate file called
Chapter-<contentSpec.Chapter(current).title>.xml

Each Chapter has the following form:

-- begin Chapter skeleton --

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "<<contentSpec.escapedTitle>>.ent">
%BOOK_ENTITIES;
]>
<chapter>
	<title><<contentSpec.Chapter(current).title>></title>


</chapter>

-- end Chapter skeleton --

When you create a new chapter, you need to add a line to
<contentSpec.escapedTitle>.xml, like this:

<xi:include href="Chapter-<contentSpec.Chapter(current).title>.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />



Sections appear inside the chapter.

-- begin Section Skeleton --

<section>
  <title><<contentSpec.Section(current).title>></title>

</section>

-- end Section Skeleton --

Topics should appear like this:

<!-- <<topic.Title>> -->
<xi:include href="topics/<<topicID>>.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />


TOPIC PROCESSING

0. In the en-US directory, create a directory "topics"

1. Set title

  A topic is a single xml root node of type <section>.

  Find the <title/> child element of the root node.

  If one does not exist, create it.

  Set the value of the element to the topic.title, overwriting any
existing value.

2. Set id
  Locate the id attribute of the <section> element, if it exists.

If the topic is included more than once in the content spec, then the id
attribute must be removed if it exists. Move on to step 3.

If the topic is included only once in the content spec, and an id
attribute does not exist, create it.

  Set the id attribute value to <topic.id>, overwriting any existing id
attribute value.


3. Write the reference into the appropriate chapter (in the appropriate
section):

<!-- <<topic.Title>> -->
<xi:include href="topics/<<topicID>>.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />

4. If topic.xml is null, write the following to topics/<<topicID>>.xml:

-- begin <topic.ID>.xml --

<section>
  <title>No XML content</title>
  <warning>
    <title>Topic <<topic.ID>> has no XML content</title>
    <para>Topic <<topic.ID>> has no XML content and is not included in
this build.</para>
  </warning>
</section>

-- end <topic.ID>.xml --

Go to step 1 with the next topic.

4. If topic.xml is not null, run a validation check

Validate the topic, and add an entry to the csbuilder.log file with an
error if it fails validation:

"ERROR: Topic <topic.ID> failed validation"

5. Write topic file
If the topic passed validation, write the topic.xml into the file
topics/<topic.ID>.xml

If the topic failed validation write the following content to
topics/<topic.ID>.xml:

-- begin <topic.ID>.xml --

<section>
  <title>Validation Error</title>
  <warning>
    <title>Topic <<topic.ID>> failed validation</title>
    <para>Topic <<topic.ID>> failed validation and is not included in
this build.</para>
  </warning>
</section>

-- end <topic.ID>.xml --


Once all the topics are processed, bundle the whole thing up in a zip
file, and return it.