"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/doc/docbook/README.DB_authors_notes" (29 Jul 2021, 8320 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.

    1 DOCBOOK CHARACTERS AND SYMBOLS
    2 ------------------------------
    3 
    4 Some special characters for DB inline equations:
    5 
    6  LE  ≤   less than or equal to
    7  GE  ≥   greater than or equal to
    8  x   ×   multiply
    9  div ÷   divide
   10  add +   add
   11  pm  ±   plus or minus
   12  ne  ≠   not equal to
   13  dot ∙   dot operator (multiply)
   14  pi  π   small Greek letter pi
   15  Pi  Π   capital Greek letter Pi
   16 
   17 Dashes:
   18 
   19   figure dash     ‒
   20   en dash         –
   21   em dash         —
   22   quotation dash  ―
   23   swung dash      ⁓
   24 
   25 Some unicode characters for spaces (see p. 330 in Bob Stayton's book):
   26 
   27         no-break space
   28         en space, half the width of an em space
   29         em space, usually equal to the type size of the font
   30       1/3 em
   31       1/4 em
   32              1/6 em
   33        width of a digit
   34       width of narrow punctuation
   35       1/5 em
   36       thinner than thin space
   37 
   38 Other symbols:
   39 
   40  ©           copyright
   41  ®           registered sign
   42  °           degree symbol
   43  ℠           service mark
   44  ™           trade mark
   45 
   46 Note that the space character should butt against the adjacent
   47 characters.
   48 
   49 SVG EQUATIONS
   50 -------------
   51 
   52 To include fancier equations, do the following:
   53 
   54 Use LibreOffice Math to write the equation.  Save the file as X.mml
   55 where X is a suitable name.
   56 
   57 Example mml file:
   58 
   59 <?xml version="1.0" encoding="UTF-8"?>
   60 
   61 <math xmlns="http://www.w3.org/1998/Math/MathML">
   62  <semantics>
   63   <mrow>
   64    <mrow>
   65     <msub>
   66      <mi>P</mi>
   67      <mi>k</mi>
   68     </msub>
   69    </mrow>
   70   </mrow>
   71   <annotation encoding="StarMath 5.0">P_{k} = P_{{k}_{MAX}} left lbrace 1 -e^{[-k_{1}(x - x_{0})^{k_{2}}]} right rbrace </annotation>
   72  </semantics>
   73 </math>
   74 
   75 Edit the file to remove the "semantics" element. Ensure you add the
   76 mml file to version control.
   77 
   78 Use SVGMath to convert the file to a graphic:
   79 
   80   math2svg -s -o X.svg X.mml
   81 
   82 Or you can use the bash script "make-svg.sh" (requires editing to suit
   83 user preferences and paths) which creates the svg file in a
   84 user-defined subdirectory and uses xmllint to format it ready for
   85 further editing either with Inkscape or by hand.
   86 
   87 Use Inkscape to view the svg file and edit it if necessary.  Be sure
   88 to add the new file to version control in the text subdirectory.
   89 
   90 Include the svg file in the desired place in DocBook source like this:
   91 
   92 <equation id="X">
   93 <title>General closed-form damage function formula</title>
   94 <informalfigure>
   95 <mediaobject>
   96   <imageobject role='xhtml'>
   97     <!-- centering title taken care of in css -->
   98     <imagedata
   99        width='3in' scalefit='1'
  100        fileref="./X.svg"
  101     />
  102   </imageobject>
  103   <imageobject role='fo'>
  104     <imagedata
  105        align='center'
  106        format="SVG"
  107        fileref="./X.svg"
  108     />
  109   </imageobject>
  110 </mediaobject>
  111 </informalfigure>
  112 </equation>
  113 
  114 
  115 SVG AND PDF FONT PROBLEMS
  116 -------------------------
  117 
  118 Note there can be font problems for pdf with complex equations.  Querying the
  119 fop mailing list sheds light on the situation:
  120 
  121 <quote>
  122 from: Vincent Hennebert vhennebert@gmail.com via xmlgraphics.apache.org
  123 sender-time: Sent at 05:07 (GMT+01:00). Current time there: 2:23 PM.
  124 reply-to: fop-users@xmlgraphics.apache.org
  125 to: fop-users@xmlgraphics.apache.org
  126 date: Tue, Apr 19, 2011 at 05:07
  127 subject: Re: Missing Font for SVG to PDF Output
  128 mailing list: <fop-users.xmlgraphics.apache.org>; mailed by xmlgraphics.apache.org
  129 ...
  130 
  131 Make sure that the family name you declare in fop.xconf matches the
  132 name under which the font is known on the system.
  133 
  134 Let's take the font "Linux Libertine" an example. Java would know this
  135 font under that name. Since Batik uses the Java font system, it will
  136 also use that name and pass it on to FOP. So you must have a
  137 font-triplet in your fop.xconf that matches that name:
  138 
  139    <font embed-url="libertine.ttf">
  140      <font-triplet name="Linux Libertine" style="normal" weight="normal"/>
  141    </font>
  142 
  143 If you use something else, FOP will find no match for "LinuxLibertine"
  144 and will fall back to a default font.
  145 
  146 You can use the
  147 java.awt.GraphicsEnvironment.getAvailableFontFamilyNames method to
  148 know under which names Java registers the fonts on your system. Of
  149 course, be sure to also use those names in the SVG file.
  150 </quote>
  151 
  152 
  153 MARKS FOR ITEMIZED LIST
  154 -----------------------
  155 
  156 Itemized list symbols defined in the docbook/fo stylesheets that work with the
  157 current BRL-CAD environment:
  158 
  159   <xsl:choose>
  160     <xsl:when test="$itemsymbol='none'"></xsl:when>
  161     <xsl:when test="$itemsymbol='disc'">&#x2022;</xsl:when>
  162     <xsl:when test="$itemsymbol='bullet'">&#x2022;</xsl:when>
  163     <xsl:when test="$itemsymbol='endash'">&#x2013;</xsl:when>
  164     <xsl:when test="$itemsymbol='emdash'">&#x2014;</xsl:when>
  165 
  166     <xsl:when test="$itemsymbol='square'">&#x25A0;</xsl:when>
  167     <xsl:when test="$itemsymbol='box'">&#x25A0;</xsl:when>
  168     <xsl:when test="$itemsymbol='smallblacksquare'">&#x25AA;</xsl:when>
  169     <xsl:when test="$itemsymbol='circle'">&#x25CB;</xsl:when>
  170     <xsl:when test="$itemsymbol='opencircle'">&#x25CB;</xsl:when>
  171 
  172     <xsl:when test="$itemsymbol='whitesquare'">&#x25A1;</xsl:when>
  173     <xsl:when test="$itemsymbol='smallwhitesquare'">&#x25AB;</xsl:when>
  174     <xsl:when test="$itemsymbol='round'">&#x25CF;</xsl:when>
  175     <xsl:when test="$itemsymbol='blackcircle'">&#x25CF;</xsl:when>
  176     <xsl:when test="$itemsymbol='whitebullet'">&#x25E6;</xsl:when>
  177 
  178     <xsl:when test="$itemsymbol='triangle'">&#x2023;</xsl:when>
  179     <xsl:when test="$itemsymbol='point'">&#x203A;</xsl:when>
  180     <xsl:otherwise>&#x25CF;</xsl:otherwise><!-- bullet -->
  181   </xsl:choose>
  182 
  183 The default marks for html nested itemized lists are:
  184 
  185   disc
  186     circle
  187       square
  188 
  189 and they appear as small marks in html.  Note that html only
  190 recognizes those mark names so we accept those defaults and they look
  191 okay.
  192 
  193 For pdf, the same mark names appear too large and we have customized
  194 the defaults marks as follows:
  195 
  196 <xsl:template name="next.itemsymbol">
  197   <xsl:param name="itemsymbol" select="'default'"/>
  198   <xsl:choose>
  199     <!-- Change this list if you want to change the order of symbols -->
  200     <xsl:when test="$itemsymbol = 'bullet'">whitebullet</xsl:when>
  201     <xsl:when test="$itemsymbol = 'whitebullet'">smallblacksquare</xsl:when>
  202     <xsl:otherwise>bullet</xsl:otherwise>
  203   </xsl:choose>
  204 </xsl:template>
  205 
  206 
  207 For non-default pdf list markers modify the 'mark' attribute for the
  208 <itemizedlist>, e.g.,
  209 
  210   <itemizedlist mark='bullet'>        <!-- a small black dot    -->
  211   ...
  212   <itemizedlist mark='whitebullet'>   <!-- a small white circle -->
  213 
  214 
  215 EPS AND OTHER GRAPHICS
  216 ----------------------
  217 
  218 eps and pdf are not handled well in fop currently.
  219 
  220 Use png or tiff for html and svg for fop.
  221 
  222 Use scribus (http://www.scribus.net) to convert eps to svg.
  223 
  224 Use gimp (http://www.gimp.org) to scale or edit png images.
  225 
  226 To center an image in html, use css:
  227 
  228   div.mediaobject {
  229     text-align: center;
  230   }
  231 
  232 A TEMPLATE FOR A FORMAL FIGURE AND INCLUDED IMAGES
  233 --------------------------------------------------
  234 
  235 To better control images for html and pdf, use different attributes
  236 according to role in the DB source.  Following is a template that
  237 gives the basic attributes to do that.  Note the filerefs are the
  238 same, but, in this case, the image widths are specified differently.
  239 It sometimes it takes a bit of trial and error to get the right
  240 attributes and values.  See Reference 2, p. 290, for much more detail.
  241 
  242   <!-- ************************************ -->
  243   <figure>
  244     <title>???</title>
  245     <mediaobject>
  246       <imageobject role='html'>
  247 	<imagedata
  248 	   align="center"
  249 	   contwidthwidth='4.5in' scalefit='1'
  250 	   fileref="./images/vbox/"
  251 	 />
  252       </imageobject>
  253       <imageobject role='fo'>
  254 	<imagedata
  255 	   align="center"
  256 	   width='4.5in' scalefit='1'
  257 	   fileref="./images/vbox/"
  258 	 />
  259       </imageobject>
  260       <textobject>
  261 	<phrase>a picture</phrase>
  262       </textobject>
  263     </mediaobject>
  264   </figure>
  265 
  266 
  267 REFERENCES
  268 ----------
  269 
  270 1. Norman Walsh, "DocBook 5: The Definitive Guide," May 2010, O'Reilly
  271    Media, Inc., Sebastopol, CA, ISBN: 978-0-596-80502-9.
  272 
  273 2. Bob Stayton, "DocBook XSL: The Complete Guide," Fourth Edition,
  274    September 2007, Sagehill Enterprises, Santa Cruz, CA, ISBN:
  275    978-0-9741521-3-4.