source: rtems-docs/README.txt @ 7ba0479

5
Last change on this file since 7ba0479 was 7ba0479, checked in by Sebastian Huber <sebastian.huber@…>, on 02/20/17 at 06:23:55

Render math via JavaScript? in HTML output

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