This page handles the structure of books - how to name and arrange files and directories.
Source file names
For XML file names, we have used prefixes like bk_, ch_, section_, and app_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. However, in migrating to RST/Sphinx we are using the xml:id for the file name and moving towards a page-based, topical approach to file naming. RST files should use a hyphen as the space delimiter and have the .rst extension.
For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic.
Common practice are:
- A figures subdirectory that includes all images (both SVG source and PNG).
- A samples subdirectory that contains source code samples or configuration file samples.
- A subdirectory per chapter where all sections are in the subdirectory, the ch_ file itself is in the top level directory.
Book check list
Use the following check list for books:
|pom.xml file||Your pom.xml file uses the latest (non-SNAPSHOT) cloud-doc plugin version and is configured correctly. To find the version number of the latest plugin, go to Clouddocs Maven Plugin Release Notes.|
|TOC||Your pom.xml file configures a TOC for your book.|
|Glossary||Embed the shared glossary and mark terms with the <glossterm> tag in your document.|
|Preface||Your book has a preface.|
|Doc history||The preface includes the doc history. Also make sure that you have included a revision entry for your latest changes.|
|Title||Title is correct.|
|Code samples||Code samples are in separate files and included in chapter, section, or appendix file.|
|Chunking||Chapters and appendices are in separate files and included in the book file.|
|Source file names||Source file names use file naming conventions. Book files = bk_*; Chapter files = ch_*; Appendix files = app_*; Section files = section_*.|