source: rtems-docs/README.txt @ 30b5468

5
Last change on this file since 30b5468 was 30b5468, checked in by Joel Sherrill <joel@…>, on 02/13/19 at 21:42:51

README.txt: Fix typos

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