Skip to content

TianoCore Documents Layout

Jump to bottom
Michael Kinney edited this page Jul 8, 2017 · 4 revisions

Documents are stored in GIT repositories in the TianoCore-Docs project on GitHub. Each document is stored in its own repository. Document repositories are named using <project name>-<specification name>. Example: edk2-BuildSpecification

The following shows the layout of files and directories for a document:

├──Document Repository
    ├───.gitignore               Ignore NPM files and local document builds
    ├───CONTRIBUTIONS.TXT        Tiano Contribution Agreement 1.1
    ├───LICENCE.TXT              BSD for Documentation
    ├───book.json                Title, Version, Draft/Release
    ├───cover.jpg                Book cover artwork
    ├───SUMMARY.md               Table of Contents
    ├───TABLES.md                Optional file.  Only used if a document contains many tables
    ├───FIGURES.md               Optional file.  Only used if a document contains many figures
    ├───EXAMPLES.md              Optional file.  Only used if a document contains many examples
    ├───GLOSSARY.md              Optional
    ├───README.md                Acknowledgments, Revision History
    ├───1_<chapter title>        Chapter subdirectory
            ├───README.md        Chapter introduction
            ├───11_<section>     Section
            . . .                Additional sections
    . . .                        Additional chapters
    ├───media                    Tianocore logo and figures (PNG/JPG)
    ├───styles                   Custom Style Sheets (CSS)
    ├───_layouts                 Default Theme Overrides

See the edk2-TemplateSpecification for a complete example. A new document can be started by making a copy of the edk2-TemplateSpecification and performing the following additional steps:

  • Update the title and version in book.json.
  • Update the title in cover.jpg.
  • Update Copyright statements in the Acknowledgements section in README.md.
  • Update the Revision History in README.md.
  • Remove the chapter1.md and chapter2.md
  • Add MarkDown files(.md) for chapters and sections in the new document.
    • If chapters are short, then put a single MarkDown file for the chapter in the root directory.
    • If chapters are long and composed of many sections, then create a directory for the chapter and add MarkDown files for each section in the chapter directory.
  • Update the contents of the media directory with images used in the new document. Do not remove or modify the file media/TianoCoreTitlePageLogo.jpg. This image is referenced by README.md to add a TianoCore logo to the document title page.
  • Update SUMMARY.md with the links to the chapters, sections, tables, figures, and examples.
  • Add optional GLOSSARY.md with definitions of terms used in the new document. GitBook automatically adds hyperlinks to term definitions if this file is present.
  • Do not modify or remove the .gitignore, CONTRIBUTIONS.TXT, or LICENSE.TXT files.
  • Do not modify or remove the contents of the styles or _layouts directories.

book.json File

A book.json file is required for every GitBook document. The default version of this file include the plugin for PlantUML so documents can provide figures using the syntax defined in the PlantUML Language Specification.

In addition, the book.json file declares variables for the document title, the document version, and if this document is a draft or a release. By using these variables throughout the document, the document title and version only need to be maintained in the book.json file. These variables are used in README.md and in the files in the _layouts folder to display the title, revision, and draft status on the title page and in page headers/footers.

The default setting for the draft variable is yes which means the document is a draft release of the document. The only change required to convert a document from a draft release to an official release is to remove the draft variable statement from book.json. This change is only performed in release branches.

The following is a template for the book.json file.

{
  "variables" : {
    "draft"   : "yes",
    "title"   : "<Title>",
    "version" : "<Version>"
  },

  "plugins": ["puml"],
  "pluginsConfig": {}
}

Published Document License and Copyright

The license and copyright for the published document is provided in the Acknowledgements section of the README.md file. Documents in the TianoCore-Docs project must use the TianoCore documentation license that is based on the FreeBSD Documentation License.

The following is a template for the Acknowledgements section in the README.md file.

### Acknowledgements

Redistribution and use in source (original document form) and 'compiled'
forms (converted to PDF, epub, HTML and other formats) with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code (original document form) must retain the
   above copyright notice, this list of conditions and the following
   disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs, converted to
   PDF, epub, HTML and other formats) must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL TIANOCORE PROJECT  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

<Copyright Statements>

Table Of Contents

The table of contents are provided in the SUMMARY.md file. It is recommended that links to chapters, sections, tables, figures, and examples always include anchors to provide better browsing experience for HTML versions of the documents.

If a document contains a small number of tables, figures, and examples, then links to those items are provided in the SUMMARY.md file. If a document contains many tables, figures, and examples, then links to these items can be provided in separate TABLES.md, FIGURES.md, and EXAMPLES.md files. If these are not broken out, then the Table of Contents in the HTML version in the left side bar of the documentation can be difficult to navigate.

The EDK II DSC Specification is an example of a document with only a few tables and figures. The links to tables and figures are provided at the bottom of the SUMMARY.md file with a --- separators.

# Summary

* [EDK II Platform Description (DSC) File Specification](README.md#edk-ii-platform-description-dsc-file-specification)
* [1 Introduction](1_introduction/README.md#1-introduction)

. . .

* [Appendix D Vpd Data Files](appendix_d_vpd_data_files/README.md#appendix-d-vpd-data-files)
  * [D.1 EDK II Build System Output File Format](appendix_d_vpd_data_files/d1_edk_ii_build_system_output_file_format.md#d1-edk-ii-build-system-output-file-format)
  * [D.2 Vpd Info File Format](appendix_d_vpd_data_files/d2_vpd_info_file_format.md#d2-vpd-info-file-format)
---
* Tables
  * [Table 1 EDK Build Infrastructure Support Matrix](1_introduction/11_overview.md#table-1-edk-build-infrastructure-support-matrix)
  * [Table 2 Well-known Macro Statements](2_dsc_overview/22_build_description_file_format.md#table-2-well-known-macro-statements)
  * [Table 3 Using System Environment Variable](2_dsc_overview/22_build_description_file_format.md#table-3-using-system-environment-variable)
  * [Table 4 Well-known Macro Statements](2_dsc_overview/22_build_description_file_format.md#table-4-well-known-macro-statements)
  * [Table 5 Operator Precedence and Supported Operands](2_dsc_overview/22_build_description_file_format.md#table-5-operator-precedence-and-supported-operands)
  * [Table 6 EDK II [Defines] Section Elements](2_dsc_overview/23_[defines]_section_processing.md#table-6-edk-ii-defines-section-elements)
  * [Table 7 EDK II [BuildOptions] Section Elements: Optional Tags](2_dsc_overview/24_[buildoptions]_section.md#table-7-edk-ii-buildoptions-section-elements-optional-tags)
  * [Table 8 EDK II [BuildOptions] Variable Descriptions](2_dsc_overview/24_[buildoptions]_section.md#table-8-edk-ii-buildoptions-variable-descriptions)
  * [Table 9 HII Attributes](2_dsc_overview/29_pcd_sections.md#table-9-hii-attributes)
  * [Table 10 Standard Variables](appendix_a_variables.md#table-10-standard-variables)
  * [Table 11 EDK II Module Types](appendix_c_module_types.md#table-11-edk-ii-module-types)
---
* Figures
  * [Figure 1 EDK II Parsing Data Flow](2_dsc_overview/21_processing_overview.md#figure-1-edk-ii-parsing-data-flow)

The EDK II Build Specification is an example of a document with many tables and figures. The SUMMARY.md file provides a link to the TABLES.md file and FIGURES.md file right after the link to the README.md file.

# Summary

* [EDK II Build Specification](README.md#edk-ii-build-specification)
* [Tables](TABLES.md#tables)
* [Figures](FIGURES.md#figures)
* [1 Introduction](1_introduction/README.md#1-introduction)

Back to TianoCore Documents Overview

Clone this wiki locally