Difference between revisions of "Documentation/Structure"
Annegentle (talk | contribs) (→Source file names) |
StackScribe (talk | contribs) (→Source file names) |
||
Line 8: | Line 8: | ||
== Source file names == | == 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. | + | 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. |
== Directory structure == | == Directory structure == |
Revision as of 17:54, 15 May 2015
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.
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_*. |