"Fossies" - the Fresh Open Source Software Archive 
Member "brlcad-7.32.4/doc/docbook/README" (29 Jul 2021, 6030 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "README":
7.30.10_vs_7.32.0.
1 This directory holds the DocBook (DB) documentation for BRL-CAD. Over
2 time, this should become the repository for all tutorials, man pages,
3 and other non-autogenerated, formatted documentation for BRL-CAD.
4
5 The xsl stylesheets for docbook are presently in the
6 "resources/other/standard" directory.
7
8 The current structure is as follows:
9
10 articles/
11 Individual articles on specific topics - oed and tire live here,
12 as well as the articles that made up the appendices of Vol III.
13
14 books/
15 Either compilations of smaller documents into large works, or
16 individual self contained works. Most of Volume III is in a
17 single file in this subtree.
18
19 lessons/
20 Individual documents intended to teach some aspect of BRL-CAD
21 to new users/students. At this time it contains the individual
22 lessons that made up Volume II.
23
24 resources/
25 The DocBook xsl files are contained within the "other"
26 subdirectory. Also included there are various directories and
27 files associated with DB validation, fonts, and hyphenation.
28 The "brlcad" subdirectory contains files customized for
29 BRL-CAD products including common files and images.
30
31 system/
32 Documentation similar to traditional Unix "man" pages - focused
33 documentation on specific parts of BRL-CAD. There is a template
34 for authors of mged command man pages at:
35
36 ./system/mann/mged_cmd_template.xml
37
38 presentations/
39 Copies of briefings (slides or slides converted to documents,
40 e.g., "Introduction to Tcl/Tk."
41
42
43 LANGUAGE CONSIDERATIONS
44 -----------------------
45
46 English documents are in 'en' sub-directories. Other languages are
47 found in standard two-character sub-directories. See, for example,
48 the Spanish translations in 'lessons/es'. Currently, the following
49 language codes may be found in various sub-directories:
50
51 * en - English
52 * es - Spanish
53 * hy - Armenian
54 * it - Italian
55 * ru - Russian
56
57 See <http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes> for one
58 listing of ISO language codes.
59
60 English DocBook source files are expected to be ASCII with xhtml
61 unicode markup for non-ASCII symbols. Other language source files
62 should be in UTF-8.
63
64 Notes on equation generation in svg, lists of common symbols and their
65 unicode DB symbols, and other notes on DB authoring tips are found in
66 the file 'README.DB_authors_notes'.
67
68 The text character code requirements may eventually be enforced by a
69 pre-commit hook script.
70
71 CONVERTING MAN FORMAT TO DOCBOOK
72 ---------------------------------
73
74 The doclifter program (available in a Debian or Ubuntu distribution)
75 can give a first-order conversion from the man page format (roff,
76 nroff, troff, or groff) to DocBook xml.
77
78 DOCBOOK PROCESSING
79 ------------------
80
81 Currently there are three products generated from DB source:
82
83 * man pages
84
85 * html documents
86
87 * pdf documents
88
89 There are some external tools required in order to produce those
90 documents:
91
92 For all DB documents (man, html, and pdf):
93
94 * xsltproc
95 a program that comes with libxslt (see http://xmlsoft.org/XSLT/)
96
97 * saxon-he
98 an Open Source java xslt processor (capable of using XSLT 2.0
99 and the new DB XSLT 2.0 stylesheets released on 2011-08-25
100 [not yet used or provided with BRL-CAD]) (see
101 http://saxon.sourceforge.net/)
102
103 For pdf documents:
104
105 * fop
106 a java program provided by the Apache Software Foundation; note
107 that a minimum of version 1.0 is required to use the
108 hyphenation binaries provided in the resources sub-directory
109 (see http://xmlgraphics.apache.org/fop/). Also, version 1.0
110 has some new font support features and we recommend using that
111 version (or later) for DB processing.
112
113 * Java
114 a working Java run-time environment
115
116 * scribus
117 an Open Source page layout program; use to convert eps to svg
118 (see http://www.scribus.net)
119
120 For checking the well-formedness of any xml document:
121
122 * xmllint
123 a program that comes with libxml2 (see http://xmlsoft.org/)
124
125 For creating and editing svg equations:
126
127 * LibreOffice
128 a free office suite whose text editor can be used to create
129 and edit equations and export them to MathML (mml) files (see
130 http://www.libreoffice.org/)
131
132 * Inkscape
133 a powerful and free vector drawing editor (see
134 http://inkscape.org)
135
136 * math2svg
137 a program (from the SVGMath suite) to convert MathML xml
138 format to SVG xml format (see
139 http://http://grigoriev.ru/svgmath/ and
140 http://sourceforge.net/projects/svgmath/)
141
142 Note that the output sometimes needs further editing either
143 manually or by inkscape.
144
145 See this link for help in installing fop 1.0 and saxon-he on Ubuntu:
146
147 http://johnbokma.com/mexit/2011/07/04/
148
149 VALIDATION
150 ----------
151
152 It is possible to add a validation step to DocBook compilation by defining the
153 CMake variable BRLCAD_EXTRADOCS_VALIDATE to ON. This will use xmllint to
154 validate the xml files as they are built.
155
156 By default, this option is enable if the BRL-CAD strict build is enabled.
157
158 OTHER CONSIDERATIONS
159 --------------------
160
161 These documents make extensive use of the XInclude modular
162 documentation specification. Consequently, the contents of any one
163 particular "document" may be scattered over many other documents.
164 This design direction is intended to allow re-use of standard
165 definitions and descriptions in multiple documents serving multiple
166 purposes. When a definition is updated for one document,
167 re-generation of other documents will incorporate the update as well
168 without requiring redundant editing.
169
170 Caution - the BRL-CAD build logic is not aware of the interlinking of
171 various xml files using xinclude. This means that a change on one document
172 may make other output files out of date, and this will not trigger a
173 re-build of those files automatically.
174
175 Notes:
176
177 * When rendered to html output and placed on a server, there may arise
178 a problem where the server supplies the page as ISO-8859-1 encoded
179 despite them actually using UTF-8. To combat this problem in the
180 case of the Apache web server, an .htaccess file in the directory
181 with the line:
182
183 AddDefaultCharset UTF-8
184
185 should let Apache know to use UTF-8 encoding for these pages.