Changes between Version 1 and Version 2 of Docs/New_Chapter


Ignore:
Timestamp:
Nov 10, 2016, 12:39:11 AM (3 years ago)
Author:
Chris Johns
Comment:

Adding a new chapter.

Legend:

Unmodified
Added
Removed
Modified
  • Docs/New_Chapter

    v1 v2  
    44
    55This page describes how to write a new chapter in the documentation and the rules you should follow.
     6
     7'''NOTE:'''
     8
     91. ReST and Sphinx manage the layout so do not attempt to create a specific
     10   layout with ReST. It may and will change in ways you do not expect.
     11
     122. Check all output formats until you are comfortable with the look and
     13   what is happening.
     14
     15
     16== Headings ==
     17
     18Use the following for headings:
     19
     201. `######` Part
     211. `******` Section
     221. `======` Sub-section
     231. `------` Sub-sub-section
     241. `^^^^^^` Sub-sub-sub-section
     251. `~~~~~~` Sub-sub-sub-sub-section
     26
     27The specific character needs to be the same length as the heading.
     28
     29
     30== Source Files ==
     31
     32Add a new chapter in a new ReST source file. Use the `.rst` file extension. The `waf` build system will build all `.rst` files it finds.
     33
     34== License ==
     35
     36All RTEMS Documentation is under the CC-BY-SA-4.0 license and we require the first line be:
     37
     38{{{
     39.. comment SPDX-License-Identifier: CC-BY-SA-4.0
     40}}}
     41
     42After this you can add a copyright statement. For example:
     43
     44{{{
     45.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
     46.. comment: All rights reserved.
     47}}}
     48
     49== Chapter Title ==
     50
     51Add the Chapter title:
     52
     53{{{
     54RTEMS Is Awesome
     55****************
     56}}}
     57
     58You can optionally follow the Chapter title with some text about the chapter or you can start into a section. No chapter text leaves you with a blank page in the PDF format which can look nice acting as a separator. See the `c-user` manual for an example of this.
     59
     60== Sections and Sub-Sections ==
     61
     62Add sections and sub-sections to your chapter breaking the text into sensible grouping. For example:
     63
     64{{{
     65.. _why_use_rtems:
     66
     67Why I use RTEMS?
     68================
     69.. index: Why use RTEMS?
     70
     71I use RTEMS because is it reliable, stable and *free*.
     72}}}
     73
     74ReST will automatically provide an anchor you can reference based on the section heading. To reference the section simply add:
     75
     76{{{
     77There are many reasons to use RTEMS, see :ref:`Why I use RTEMS?`.
     78}}}
     79
     80In this example another anchor has been provided called `why_use_rtems` and it can also be referenced using:
     81
     82{{{
     83There are many reasons to use RTEMS, see :ref:`why_use_rtems`.
     84}}}
     85
     86If you want to avoid breaking references with changes in section naming then an explicit anchor is best.
     87
     88An index entry has also been added.
     89
     90== Literal Test ==
     91
     92To use literal text, that is text that appears in a constant width font use:
     93
     94{{{
     95``MY_CONSTANT``
     96}}}
     97
     98== Code Blocks ==
     99
     100To add code blocks use:
     101
     102{{{
     103.. code-block:: c
     104
     105   void foo(cons char* bar)
     106   {
     107      printf("Hello from: %s\n", bar);
     108   }
     109}}}
     110
     111NOTE: You need a line between the `..code-block::` and the start of the code.
     112
     113You can select from a number of formats, for example `c` and `shell`.
     114
     115== Directives ==
     116
     117Directives use the ReST `definition` format:
     118
     119{{{
     120DESCRIPTION:
     121    Indent the text for the description and everything in the description is
     122    part of the description until you add a paragraph in column 1. This
     123    includes code blocks:
     124
     125    .. code-block: shell
     126
     127       # cd /
     128       # rm -rf *
     129
     130    And you can lists:
     131
     132       #. Point 1
     133       #. Point 2
     134
     135NOTES:
     136    A new part of the directive.
     137}}}
     138
     139== Figures and Images ==
     140
     141Figures and images are the same thing. Please the image in the `images` directory tree so we can share images where ever possible. Also place the source for the image it the image is built in some way. Where possible avoid using proprietary tools to create images because this creates a burden for the project to maintain the image. Also provide details on how to edit or recreate the image.
     142
     143In the ReST source use:
     144
     145{{{
     146.. figure:: ../images/eclipse/eclipse-help-installation.png
     147   :width: 50%
     148   :align: center
     149   :alt: Help, Installation Details
     150}}}
     151
     152The modifiers help position and layout the image in the output.
     153
     154== PDF Page Breaks ==
     155
     156RTEMS Documentation requires we start a new directory, command or item on a new page. In HTML we have no control over this and it does not make sense. In the PDF it requires we add specific Latex commands:
     157
     158{{{
     159.. raw:: latex
     160
     161   \clearpage
     162}}}
     163
     164For example from the `c-user` manual for the Semaphore Manager:
     165
     166{{{
     167Directives
     168==========
     169
     170This section details the semaphore manager's directives.  A subsection is
     171dedicated to each of this manager's directives and describes the calling
     172sequence, related constants, usage, and status codes.
     173
     174.. raw:: latex
     175
     176   \clearpage
     177
     178.. _rtems_semaphore_create:
     179
     180SEMAPHORE_CREATE - Create a semaphore
     181-------------------------------------
     182.. index:: create a semaphore
     183.. index:: rtems_semaphore_create
     184
     185
     186CALLING SEQUENCE:
     187    .. code-block:: c
     188
     189        rtems_status_code rtems_semaphore_create(
     190            rtems_name           name,
     191            uint32_t             count,
     192            rtems_attribute      attribute_set,
     193            rtems_task_priority  priority_ceiling,
     194            rtems_id            *id
     195        );
     196}}}