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
|
=============================
SCons Documentation Toolchain
=============================
Introduction
============
This text tries to give an overview of the current SCons documentation toolchain.
The interested user should be able to better understand where and how the text he writes
is processed.
It is also a reference for core developers and the release team.
.. image:: images/overview.png
The diagram above roughly shows the steps that we currently need for creating all the MAN pages, User manuals and
reference documents. You may think: "Geeez, that looks so complicated. Why can't they
simply convert XML files to PDF with Docbook, or use reST?" Please be patient, and
continue reading. Things will get a little clearer soon.
Our toolchain doesn't only produce HTML and PDF files that are nice to look at, it also performs a lot
of processing under the covers. We try to have our documentation as consistent as possible to the
current behaviour of the source code, but this requires some extra steps.
So let's start right at the top...
Writer's view
=============
The toolchain is set up, such that the User has a very restricted view on this whole "document
processing thingy". All he should be concerned about is to edit existing text or write new sections
and paragraphs.
Sometimes even a completely new chapter has to be added, in general he can fire up his XML editor of choice
and type away.
If he is a really nice user, he cares about validating his XML files against our special
"SCons Docbook DTD/XSD". Either during typing, supported by his XML editor, or by executing a special
script
::
python bin/docs-validate.py
from the top source folder afterwards. Preferably both.
Everything's looking okay, all validation passed? Good, then he simply commits his new work, and
creates a pull request on Bitbucket. That's it!
Additionally, he can create the single documents on his side if he wants to get a feel for how the
final result looks (and who doesn't?). Each of the document folders (``design``, ``developer``, ``man``,
``python10``, ``reference``, and ``user``) contains an ``SConstruct`` file along with the actual
XML files. You can call
::
python ../../src/script/scons.py
from within the directory, and have the MAN pages or HTML created...even PDF, if you have a
renderer installed (``fop``, ``xep`` or ``jw``).
Validation
==========
Just a few more words about the validation step.
We are using our own DTD/XSD as a kind of hook, which only exists to link our own
SCons documentation tags into the normal Docbook XSD. For the output, we always
have an intermediary step (see diagram above), where we rewrite tags like ``cvar``
into a block of Docbook formatting elements representing it.
The toolchain, and all the Python scripts supporting it, are based on the prerequisite that
all documents are valid against the SCons Docbook XSD. This step guarantees that we can
accept the pull request of a user/writer with all his changes, and can create the documentation
for a new release of SCons without any problems at a later time.
Entities
========
We are using entities for special keywords like ``SCons`` that should appear with the same
formatting throughout the text. These are kept in a single file ``doc/scons.mod`` which gets
included by the documents.
Additionally, for each Tool, Builder, Cvar and Function, a bunch of linkends in the form of
entities get defined. They can be used in the MAN page and the User manual.
When you add an XML file in the ``src/engine/Tools`` folder, e.g. for a tool named ``foobar``,
you can use the two entities
*t-foobar*
which prints the name of the Tool, and
*t-link-foobar*
which is a link to the description of the Tool in the Appendix
of the User guide's text.
By calling the script
::
python bin/docs-update-generated.py
you can recreate the lists of entities (``*.mod``) in the ``generated`` folder, if required.
At the same time, this will generate the ``*.gen`` files, which list the full
description of all the Builders, Tools, Functions and CVars for the MAN page
and the guide's appendix.
For more information about how to properly describe these elements, refer to
the start of the Python script ``bin/SConsDoc.py``. It explains the available
tags and the exact syntax in detail.
Examples
========
In the User Guide, we support automatically created examples. This means that the output of the specified
source files and SConstructs, is generated by running them with the current SCons version.
We do this to ensure that the output displayed in the manual, is identical to what you get when you run
the example on the command-line.
A short description about how these examples have to be defined, can be found at the start of the file
``bin/SConsExamples.py``. Call
::
python bin/docs-create-example-outputs.py
from the top level source folder, to run all examples through SCons.
Before this script starts to generate any output, it checks whether the names of all defined examples are
unique. Another important prerequisite is, that for every example all the single ``scons_output`` blocks need to have
a ``suffix`` attribute defined. These suffixes also have to be unique, within each example.
All example output files (``*.xml``) get written to the folder ``doc/generated/examples``, together with all files defined
via the ``scons_example_file`` tag. They are put under version control, too. Like this, it is easier to compare
whether the output got broken for a new version of SCons.
Note, that these output files are not actually needed for editing the documents. When loading the User manual into an XML
editor, you will always see the example's definition. Only when you create some output, the files from
``doc/generated/examples`` get XIncluded and all special ``scons*`` tags are transformed into Docbook elements.
Directories
===========
Documents are in the folders ``design``, ``developer``, ``man``,
``python10``, ``reference``, and ``user``.
*editor_configs*
Prepared configuration sets for the validating WYSIWYG XML editors
XmlMind and Serna. You'll probably want to try the latter, because
the XXE config requires you to have a full version (costing a few
hundred bucks) and is therefore untested. For installing the Serna
config, simply copy the ``scons`` folder into the ``plugins``
directory of your installation. Likewise, the XXE files from the
``xmlmind`` folder have to be copied into ``~/.xxe4/`` under Linux.
*generated*
Entity lists and outputs of the UserGuide examples. They get generated
by the update scripts ``bin/docs-update-generated.py``
and ``bin/docs-create-example-outputs.py``.
*images*
Images for the ``overview.rst`` document.
*xsd*
The SCons Docbook schema (XSD), based on the Docbook v4.5 DTD/XSD.
*xslt*
XSLT transformation scripts for converting the special SCons
tags like ``scons_output`` to valid Docbook during document
processing.
|
