Documentation/Structure
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. Continue to use underbar as the space delimiter.
Directory structure
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:
| Task | Description | Complete? |
|---|---|---|
| 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_*. |
