summaryrefslogtreecommitdiffstats
path: root/README.txt
blob: 180b944c9919238c276d739c9dde570dc48cae71 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
RTEMS Project Documentation
===========================

The documents are written in ReST and built using Sphinx. The build system will
check the version of Sphinx and ensure you have a suitable version
available. If your host does not provide a packaged version use PIP to fetch a
recent version. The Sphinx website provides details on doing this.

ReST is the Re-Structed-Text format. It is a simple markup language that allows
us to create quality documentaion. It is flexible and powerful however do not
attempt to train it to create a specific format. You need to test any new way
of presenting something on all output formats. What may look great in one
format may not translate with the same clarity to another output format.

The RTEMS Documentation output formats are:

 HTML        - Multi-page HTML with files in a single directory per manual.
 PDF         - Single PDF per manual.
 SIngle HTML - Single HTML, one file per manual.

The PDF format is cerated using Latex and that uses texlive packages. This
exposes us to the complex world of Latex however the quality of the documents
created is worth it.

Production Quality Hosts
------------------------

We allow the building of PDF documentation on hosts that do not have a fully
suitable texlive environment and this results in quality that is not at the
production level.

The hosts which produce production quality is:

 FreeBSD
 CentOS 6 and 7 (if using texlive, not RPMs of texlive)

Host Setup
----------

HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install,
and building a Single HTML page requires the 'inliner' tool.

Please add your host as you set it up.

Sphinx Per User Install
~~~~~~~~~~~~~~~~~~~~~~~

You can use this method to install a personal version of Sphinx if your host
does not provide a suitable package:

 $ pip install -U sphinx

On some hosts, this may complain that a newer version of pip is available.
If so, then upgrade pip into your personal area.

 $ pip install --upgrade --user pip

The personal area for these tools is ${HOME}/.local/bin. It should
be PREPENDED to your path. On a 32-bit install of CentOS 6, these
were the PATH modifications to use the local install of Texlive
and sphinx:

  export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
  export PATH=${HOME}/.local/bin:${PATH}

FreeBSD
~~~~~~~

PDF Quality: production

Sphinx:

  # pkg install py27-sphinx

PDF:

  # pkg install texlive-full

Single HTML:

  # pkg install npm
  # npm install -g inliner

CentOS 6 and 7
~~~~~~~~~~~~~~

PDF Quality: production

Sphinx:

  $ pip install -U sphinx

PDF:

  WARNING: Do NOT use the RPMs for texlive. They are incomplete and, in
           the best case, result in ugly PDFs.

  As root, install texlive per the instructions at
  http://tug.org/texlive/acquire-netinstall.html

  # wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
  # tar xf install-tl-unx.tar.gz
  # cd install-tl-20161106
    NOTE: The date in the name of the directory will change.
  # ./install-tl
    - Use the command line system. Select "O" for options if you want to
      change from A4 to US letter paper size by default.
    - Select "I" to install
    - The tools will be installed into a directory like the following:
      /usr/local/texlive/2016/bin/i386-linux/

     NOTE: The year (2016) and host OS (i386-linux) will change to
           reflect 32 or 64 bit and OS name.

Single HTML:

  # yum install npm
  # npm install -g inliner

PATH:

  Ensure the appropriate directories are PREPENDED to your PATH before
  building the documentation. Examples are shown below:

  export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
  export PATH=${HOME}/.local/bin:${PATH}


Arch Linux
~~~~~~~~~~

Sphinx:

  # pacman -S python-sphinx

PDF:

  # pacman -S texlive-bin texlive-core texlive-latexextra texlive-fontsextra \

openSUSE
~~~~~~~~

Packages:

  # zypper in python-pip 'texlive*'

Sphinx:

  # pip install -U Sphinx

Using pip to install Sphinx destroys the python-Sphinx package if installed via
RPM.

Latex Setup
~~~~~~~~~~~

Latex is used to create the PDF document.  The setup of Latex varies from host
to host operating system due to the way each host packages the texlive
packages. There is no common naming and no real way to figure what texlive
package is present in a host's packaging. It seems not all of texlive is
available.

The RTEMS Documentation waf configure phase check for each texlive package used
in the generated output and the styles. If you complete configure with the
--pdf option you should be able to build PDF documentation.

The texlive package requirments come from the Latex styles we are using and
Sphinx.

An example of failures are:

  Checking for Tex package 'Bjarne'        : ok
  Checking for Tex package 'alltt'         : ok
  Checking for Tex package 'amsmath'       : ok
  Checking for Tex package 'amssymb'       : ok
  Checking for Tex package 'amstext'       : ok
  Checking for Tex package 'array'         : ok
  Checking for Tex package 'atbegshi'      : ok
  Checking for Tex package 'babel'         : ok
  Checking for Tex package 'calc'          : ok
  Checking for Tex package 'capt-of'       : not found (please install)
  Checking for Tex package 'charter'       : ok
  Checking for Tex package 'cmap'          : ok
  Checking for Tex package 'color'         : ok
  Checking for Tex package 'eqparbox'      : not found (please install)
  Checking for Tex package 'etoolbox'      : ok
  Checking for Tex package 'fancybox'      : ok
  Checking for Tex package 'fancyhdr'      : ok
  Checking for Tex package 'fancyvrb'      : ok
  Checking for Tex package 'float'         : ok
  Checking for Tex package 'fncychap'      : ok
  Checking for Tex package 'fontenc'       : ok
  Checking for Tex package 'footnote'      : ok
  Checking for Tex package 'framed'        : ok
  Checking for Tex package 'graphicx'      : ok
  Checking for Tex package 'hypcap'        : ok
  Checking for Tex package 'hyperref'      : ok
  Checking for Tex package 'ifplatform'    : not found (please install)
  Checking for Tex package 'ifthen'        : ok
  Checking for Tex package 'inconsolata'   : not found (please install)
  Checking for Tex package 'inputenc'      : ok
  Checking for Tex package 'keyval'        : ok
  Checking for Tex package 'kvoptions'     : ok
  Checking for Tex package 'lato'          : not found (please install)
  Checking for Tex package 'lineno'        : ok
  Checking for Tex package 'longtable'     : ok
  Checking for Tex package 'makeidx'       : ok
  Checking for Tex package 'multirow'      : ok
  Checking for Tex package 'parskip'       : ok
  Checking for Tex package 'pdftexcmds'    : ok
  Checking for Tex package 'textcomp'      : ok
  Checking for Tex package 'threeparttable' : ok
  Checking for Tex package 'times'          : ok
  Checking for Tex package 'titlesec'       : ok
  Checking for Tex package 'upquote'        : not found (please install)
  Checking for Tex package 'utf8'           : ok
  Checking for Tex package 'wrapfig'        : ok
  Checking for Tex package 'xcolor'         : ok
  Checking for Tex package 'xstring'        : ok
  There are 6 Tex package failures. Please fix.

If you find there is an issue please post the developers list.

Building
--------

Note: waf-1.9.5 is a little noisy when running tex builds and tests. I hope
      to have this resolved soon.

To build enter in the top directory:

  $ ./waf configure [--pdf] [--singlehtml] [--prefix] [--sphinx-verbose]
  $ ./waf

The '--pdf' and '--singlehtml' options can be added to configure to build those
output formats.

To build and install to a specific location:

  $ ./waf configure --prefix=/foo/my/location
  $ ./waf build install

If you need to debug what is happening use configure with a suitable Sphinx
version level:

  $ ./waf configure --sphinx-verbose=-v
  $ ./waf clean build

You can enter a manual's directory and run the same configure command and build
just that manual.

Documentation Standard
----------------------

This following details the documentation standard. If in doubt first search the
existing documentation for an example and if unsure ask.

1. All text is to be formatted to wrap at 80 columns. Do not manually line feed
   before 80.

2. Pasted text such as console output can exceed 80 columns however it is
   preferred even this text is wrapped at 80 columns. Long lines in code block
   text causes issues with the PDF output.

3. The headings use the following:

      Heading   Description
      1  ###### Part
      2  ****** Section
      3  ====== Sub-ection
      4  ------ Sub-sub-section
      5  ^^^^^^ Sub-sub-sub-section
      6  ~~~~~~ Sub-sub-sub-sub-section

3. For literal output, such as shell commands and code use '::' at the trailing
   edge of the previous paragraph. If the '.. code-block::' with
   'c' for C code and 'shell' for shell code and terminal output. If you need
   line number use:

    .. code-block:: shell
       :linenos:

4. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP',
   'Important' or 'Warning' to the text. Let the mark-up language handle
   this. The supported directives are:

     .. warning::
     .. note::
     .. topic::

   These directives reference specific CSS sytle support.

5. Images are placed in the 'images' directory. Do not place images in the
   source directories. Using a common 'images' tree of images promotes sharing
   of images. To add an image use:

    .. figure:: ../images/my-image.png
       :wdith: 75%
       :align: center
       :alt: This is the alt text for some output types.

6. Callouts can be implement manually using a liternal block which can using
   '::' or a code block and topic block is used for the items. For
   example:

     .. code-block: c

        #include <stdio.h>  <1>
        int main(int argc, char** argv)  <2>
        {
           printf("Hello world\n");  <3>
           return 0;   <4>
        }

     .. topic:: Items:

       1. Include the standard input/output header file.

       2. The program starts here.

       3. Print something to the standard output device.

       4. Exit with an exit code of 0. This is value can be checked by the
          caller of this program.

   Note, the topic items are manually number. This makes is easier to see which
   item matches the text. Use <> for the number and align at a position that
   works and makes the number as visible as possible. Use hanging indents if an
   items extends over a single line.

7. Use the RTEMS domain references for URLs and mailing lists. For example to
   insert the RTEMS developers list use:

     :r:list:`devel`
     :r:url:`git`

   The valid lists are:

     announce     : Announce Mailing List
     bugs         : Bugs Mailing List
     devel        : Developers Mailing List
     build        : Build Logs
     users        : Users Mailing List
     vc           : Version Control Mailing List

  The valif URLs are:

     trac         : https://devel.rtems.org/
     devel        : https://devel.rtems.org/
     www          : https://www.rtems.org/
     buildbot     : https://buildbot.rtems.org/
     builder      : https://builder.rtems.org/
     docs         : https://docs.rtems.org/
     lists        : https://lists.rtems.org/
     git          : https://git.rtems.org/
     ftp          : https://ftp.rtems.org/
     review       : https://review.rtems.org/
     bugs         : https://devel.rtems.org/wiki/Bugs/
     gsoc         : https://devel.rtems.org/wiki/GSoC/
     socis        : https://devel.rtems.org/wiki/SOCIS/