source: rtems-docs/README.txt @ 87e1929

Last change on this file since 87e1929 was 5ffa072, checked in by Gedare Bloom <gedare@…>, on Jul 26, 2017 at 3:44:44 PM

README: fix typos

  • Property mode set to 100644
File size: 13.0 KB
Line 
1RTEMS Project Documentation
2===========================
3
4The documents are written in ReST and built using Sphinx. The build system will
5check the version of Sphinx and ensure you have a suitable version
6available. If your host does not provide a packaged version use PIP to fetch a
7recent version. The Sphinx website provides details on doing this.
8
9ReST is the Re-Structed-Text format. It is a simple markup language that allows
10us to create quality documentaion. It is flexible and powerful however do not
11attempt to train it to create a specific format. You need to test any new way
12of presenting something on all output formats. What may look great in one
13format may not translate with the same clarity to another output format.
14
15The RTEMS Documentation output formats are:
16
17 HTML        - Multi-page HTML with files in a single directory per manual.
18 PDF         - Single PDF per manual.
19 SIngle HTML - Single HTML, one file per manual.
20
21The PDF format is created using Latex and that uses texlive packages. This
22exposes us to the complex world of Latex however the quality of the documents
23created is worth it.
24
25Production Quality Hosts
26------------------------
27
28We allow the building of PDF documentation on hosts that do not have a fully
29suitable texlive environment and this results in quality that is not at the
30production level.
31
32The hosts which produce production quality is:
33
34 FreeBSD
35 CentOS 6 and 7 (if using texlive, not RPMs of texlive)
36
37NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS.
38
39Host Setup
40----------
41
42HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install,
43and building a Single HTML page requires the 'inliner' tool. The
44sphinxcontrib-bibtex extension is mandatory.
45
46Please add your host as you set it up.
47
48Sphinx Per User Install
49~~~~~~~~~~~~~~~~~~~~~~~
50
51You can use this method to install a personal version of Sphinx if your host
52does not provide a suitable package:
53
54  $ pip install -U --user sphinx
55  $ pip install --user sphinxcontrib-bibtex
56
57On some hosts, this may complain that a newer version of pip is available.
58If so, then upgrade pip into your personal area.
59
60 $ pip install --upgrade --user pip
61
62The personal area for these tools is ${HOME}/.local/bin. It should
63be PREPENDED to your path. On a 32-bit install of CentOS, RHEL, or
64Fedora, these were the PATH modifications to use the local install of
65Texlive and sphinx:
66
67  export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
68  export PATH=${HOME}/.local/bin:${PATH}
69
70If on a 64-bit install of CentOS, RHEL, or Fedora, these will
71be the PATH modifications to use the local install of Texlive
72and sphinx:
73
74  export PATH=/usr/local/texlive/2016/bin/x86_64-linux/:${PATH}
75  export PATH=${HOME}/.local/bin:${PATH}
76
77Windows
78~~~~~~~
79
80To build the documentation on Windows you need to install an offical Python
81build from https://www.python.org/. We suggest you install a recent 2.7 series
8264bit build. The versions 2.7.9 and after include pip.
83
84Note: you cannot use the MSYS2 versions of Python because the pip libraries
85that contain C or C++ code are built with MSVC libraries and cannot integrate
86with the MSYS2 built python.
87
88The following assumes Python is installed to its default path of C:\Python27.
89
90Open an MSYS2 terminal window and add the needed paths to Python and its
91scripts:
92
93 $ export PATH=/c/Python27/Scripts:/c/Python27:$PATH
94
95Install Sphinx and any needed extensions:
96
97 $ pip install sphinx
98 $ pip install sphinxcontrib-bibtex
99
100FreeBSD
101~~~~~~~
102
103PDF Quality: production
104
105Sphinx:
106
107  # pkg install py27-sphinx
108
109PDF:
110
111  # pkg install texlive-full
112
113Single HTML:
114
115  # pkg install npm
116  # npm install -g inliner
117
118CentOS 6 and 7
119~~~~~~~~~~~~~~
120
121PDF Quality: production
122
123Sphinx:
124
125  $ pip install -U sphinx
126
127PDF:
128
129  WARNING: Do NOT use the RPMs for texlive. They are incomplete and, in
130           the best case, result in ugly PDFs.
131
132  As root, install texlive per the instructions at
133  http://tug.org/texlive/acquire-netinstall.html
134
135  # wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
136  # tar xf install-tl-unx.tar.gz
137  # cd install-tl-20161106
138    NOTE: The date in the name of the directory will change.
139  # ./install-tl
140    - Use the command line system. Select "O" for options if you want to
141      change from A4 to US letter paper size by default.
142    - Select "I" to install
143    - The tools will be installed into a directory like the following:
144      /usr/local/texlive/2016/bin/i386-linux/
145
146     NOTE: The year (2016) and host OS (i386-linux) will change to
147           reflect 32 or 64 bit and OS name.
148
149Single HTML:
150
151NOTE: npm appears to be part of the EPEL repository for RHEL and CentOS.
152You may have to add that repository to your configuration.
153
154
155  # yum install npm
156  # npm install -g inliner
157
158Spell check:
159
160  # yum install aspell
161
162PATH:
163
164  Ensure the appropriate directories are PREPENDED to your PATH before
165  building the documentation. Examples are shown below:
166
167  export PATH=/usr/local/texlive/2016/bin/i386-linux/:${PATH}
168  export PATH=${HOME}/.local/bin:${PATH}
169
170
171Arch Linux
172~~~~~~~~~~
173
174Sphinx:
175
176  # pacman -S python-sphinx
177
178PDF:
179
180  # pacman -S texlive-bin texlive-core texlive-latexextra texlive-fontsextra \
181
182openSUSE
183~~~~~~~~
184
185Packages:
186
187  # zypper in python-pip 'texlive*'
188
189Sphinx:
190
191  # pip install -U Sphinx
192
193Using pip to install Sphinx destroys the python-Sphinx package if installed via
194RPM.
195
196Latex Setup
197~~~~~~~~~~~
198
199Latex is used to create the PDF document.  The setup of Latex varies from host
200to host operating system due to the way each host packages the texlive
201packages. There is no common naming and no real way to figure what texlive
202package is present in a host's packaging. It seems not all of texlive is
203available.
204
205The RTEMS Documentation waf configure phase check for each texlive package used
206in the generated output and the styles. If you complete configure with the
207--pdf option you should be able to build PDF documentation.
208
209The texlive package requirments come from the Latex styles we are using and
210Sphinx.
211
212An example of failures are:
213
214  Checking for Tex package 'Bjarne'        : ok
215  Checking for Tex package 'alltt'         : ok
216  Checking for Tex package 'amsmath'       : ok
217  Checking for Tex package 'amssymb'       : ok
218  Checking for Tex package 'amstext'       : ok
219  Checking for Tex package 'array'         : ok
220  Checking for Tex package 'atbegshi'      : ok
221  Checking for Tex package 'babel'         : ok
222  Checking for Tex package 'calc'          : ok
223  Checking for Tex package 'capt-of'       : not found (please install)
224  Checking for Tex package 'charter'       : ok
225  Checking for Tex package 'cmap'          : ok
226  Checking for Tex package 'color'         : ok
227  Checking for Tex package 'eqparbox'      : not found (please install)
228  Checking for Tex package 'etoolbox'      : ok
229  Checking for Tex package 'fancybox'      : ok
230  Checking for Tex package 'fancyhdr'      : ok
231  Checking for Tex package 'fancyvrb'      : ok
232  Checking for Tex package 'float'         : ok
233  Checking for Tex package 'fncychap'      : ok
234  Checking for Tex package 'fontenc'       : ok
235  Checking for Tex package 'footnote'      : ok
236  Checking for Tex package 'framed'        : ok
237  Checking for Tex package 'graphicx'      : ok
238  Checking for Tex package 'hypcap'        : ok
239  Checking for Tex package 'hyperref'      : ok
240  Checking for Tex package 'ifplatform'    : not found (please install)
241  Checking for Tex package 'ifthen'        : ok
242  Checking for Tex package 'inconsolata'   : not found (please install)
243  Checking for Tex package 'inputenc'      : ok
244  Checking for Tex package 'keyval'        : ok
245  Checking for Tex package 'kvoptions'     : ok
246  Checking for Tex package 'lato'          : not found (please install)
247  Checking for Tex package 'lineno'        : ok
248  Checking for Tex package 'longtable'     : ok
249  Checking for Tex package 'makeidx'       : ok
250  Checking for Tex package 'multirow'      : ok
251  Checking for Tex package 'parskip'       : ok
252  Checking for Tex package 'pdftexcmds'    : ok
253  Checking for Tex package 'textcomp'      : ok
254  Checking for Tex package 'threeparttable' : ok
255  Checking for Tex package 'times'          : ok
256  Checking for Tex package 'titlesec'       : ok
257  Checking for Tex package 'upquote'        : not found (please install)
258  Checking for Tex package 'utf8'           : ok
259  Checking for Tex package 'wrapfig'        : ok
260  Checking for Tex package 'xcolor'         : ok
261  Checking for Tex package 'xstring'        : ok
262  There are 6 Tex package failures. Please fix.
263
264If you find there is an issue please post the developers list.
265
266Building
267--------
268
269Note: waf-1.9.5 is a little noisy when running tex builds and tests. I hope
270      to have this resolved soon.
271
272To build enter in the top directory:
273
274  $ ./waf configure [--pdf] [--singlehtml] [--prefix] \
275                    [--sphinx-verbose] [--disable-extra-fonts]
276  $ ./waf
277
278The '--pdf' and '--singlehtml' options can be added to configure to build those
279output formats.
280
281The '--disable-extra-fonts' allows you to build PDF documents with out the
282fonts we use for a better quality document. Use this option to build without
283needing the extra fonts accepting you will get poor quality documents.
284
285To build and install to a specific location:
286
287  $ ./waf configure --prefix=/foo/my/location
288  $ ./waf build install
289
290If you need to debug what is happening use configure with a suitable Sphinx
291version level:
292
293  $ ./waf configure --sphinx-verbose=-v
294  $ ./waf clean build
295
296You can enter a manual's directory and run the same configure command and build
297just that manual.
298
299Documentation Standard
300----------------------
301
302This following details the documentation standard. If in doubt first search the
303existing documentation for an example and if unsure ask.
304
3051. All text is to be formatted to wrap at 80 columns. Do not manually line feed
306   before 80.
307
3082. Do not insert tab characters, use spaces, no trailing white space.
309
3103. Pasted text such as console output can exceed 80 columns however it is
311   preferred even this text is wrapped at 80 columns. Long lines in code block
312   text causes issues with the PDF output.
313
3144. The headings use the following:
315
316      Heading   Description
317      1  ###### Part
318      2  ****** Section
319      3  ====== Sub-section
320      4  ------ Sub-sub-section
321      5  ^^^^^^ Sub-sub-sub-section
322      6  ~~~~~~ Sub-sub-sub-sub-section
323
3245. For literal output, such as shell commands and code use '::' at the trailing
325   edge of the previous paragraph. Use the '.. code-block::' with
326   'c' for C code and 'shell' for shell code and terminal output. If you need
327   line number use:
328
329    .. code-block:: shell
330       :linenos:
331
3326. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP',
333   'Important' or 'Warning' to the text. Let the mark-up language handle
334   this. The supported directives are:
335
336     .. warning::
337     .. note::
338     .. topic::
339
340   These directives reference specific CSS style support.
341
3427. Images are placed in the 'images' directory. Do not place images in the
343   source directories. Using a common 'images' tree of images promotes sharing
344   of images. To add an image use:
345
346    .. figure:: ../images/my-image.png
347       :wdith: 75%
348       :align: center
349       :alt: This is the alt text for some output types.
350
3518. Callouts can be implemented manually using a literal block which can use
352   '::' or a code block and topic block is used for the items. For
353   example:
354
355     .. code-block: c
356
357        #include <stdio.h>  <1>
358        int main(int argc, char** argv)  <2>
359        {
360           printf("Hello world\n");  <3>
361           return 0;   <4>
362        }
363
364     .. topic:: Items:
365
366       1. Include the standard input/output header file.
367
368       2. The program starts here.
369
370       3. Print something to the standard output device.
371
372       4. Exit with an exit code of 0. This value can be checked by the
373          caller of this program.
374
375   Note, the topic items are manually numbered, which makes it easier to see
376   which item matches the text. Use <> for the number and align at a position
377   that works and makes the number as visible as possible. Use hanging indents
378   if an items extends past a single line.
379
3809. Use the RTEMS domain references for URLs and mailing lists. For example to
381   insert the RTEMS developers list use:
382
383     :r:list:`devel`
384     :r:url:`git`
385
386   The valid lists are:
387
388     announce     : Announce Mailing List
389     bugs         : Bugs Mailing List
390     devel        : Developers Mailing List
391     build        : Build Logs
392     users        : Users Mailing List
393     vc           : Version Control Mailing List
394
395  The valid URLs are:
396
397     trac         : https://devel.rtems.org/
398     devel        : https://devel.rtems.org/
399     www          : https://www.rtems.org/
400     buildbot     : https://buildbot.rtems.org/
401     builder      : https://builder.rtems.org/
402     docs         : https://docs.rtems.org/
403     lists        : https://lists.rtems.org/
404     git          : https://git.rtems.org/
405     ftp          : https://ftp.rtems.org/
406     review       : https://review.rtems.org/
407     bugs         : https://devel.rtems.org/wiki/Bugs/
408     gsoc         : https://devel.rtems.org/wiki/GSoC/
409     socis        : https://devel.rtems.org/wiki/SOCIS/
Note: See TracBrowser for help on using the repository browser.