Create Publican compatible front and back matter in AsciiDoc

Publican expects certain specific front-and-back-matter formations to be present. This page will be my attempt to figure out the Asciidoc to get you there.

Pushing my original work down the page, because I think I’ve been on the wrong path.

There seems to be a file called article-docinfo.xml which is included in the doc/ directory of the Asciidoc install. I haven’t found it yet on my local install, but this seems to contain the entire XML formation of the frontmatter. Here it is on Github: http://code.google.com/p/asciidoc/source/browse/doc/article-docinfo.xml?r=0f14cc38d16230271c4c5c3ce22566b557a9ebf8

It is missing the <bookinfo> bit, and includes the revision histsory at the beginning instead of the end of the book, but it’s a start. It seems like it would need to be hand-crafted per book. This is not ideal, because the current equivalent files are internationalized and this work would need to be done again.

Anyway it appears that you use this file by copying it to the same place where your .asciidoc file is, and calling it the same name as your file, postfixed by _docinfo.xml. So if your file was called mybook.asciidoc, you would copy the docinfo file to mybook_docinfo.xml and Asciidoc would pick it up automatically.

Overall Book Structure

Publican expects the book to be organized in the following manner:

• <book>

  • <bookinfo>

    • Title: The title of the book

    • Subtitle: The subtitle of the book. Used in the RPM manifest.

    • Product Name: The name of the product the book applies to

    • Product Number: The version of the product the book applies to

    • Edition: The edition of the book

    • Pubsnumber: Legacy, nothing breaks if it’s left out.

    • Abstract: A short paragraph about the book. Used as the RPM’s description.

    • Corpauthor: At Red Hat, holds an image of the company logo

    • Legal Notice

    • Author Group: Info about the authors, editors, and other credits

      • <authorgroup>

      • <author>

        • <firstname>, <surname>, <affiliation>, <email>

      • <editor> (and other possible roles) - same contents as author

  • <preface>: This is all templates

    • Document conventions

    • Opportunity to provide feedback

  • Main book contents

    • Typically one file per chapter, though there is no rule about this

  • <appendix> (may be more than one)

    • <revhistory>: Contains one <revision> per publication of the book

      • <revision>: Contains an ID, author, date, and a list of revisions

  • <index>

Publican builds this structure by using <xi:include> statements from a main file to multiple files containing the different bits.

I want to figure out the Asciidoc which will get the right result for each section, when converting from Asciidoc to Docbook using Asciidoctor.

<bookinfo>

TBD

<authorinfo>

TBD

<revhistory>

TBD