"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.