Re: [spam] Re: New BoostBook user manual

From: Christopher Currie (Christopher_at_[hidden])
Date: 2004-02-05 16:16:47

Rene Rivera wrote:
> When you are more confident in the format of the XML could do me the 
> favor of doing a sample conversion of the HTML produced by the --help 
> facility (one small module would be more than sufficient). Having that 
> would make it very easy for me to add code to then generate the inline 
> help in BoostBook XML format.

I've attached the original output of 'bjam --help-output html --help 
stage', and a sample BoostBook conversion. There's lots of potential for 
interpretation though; Docbook supports a lot of markup that I didn't 
use for the sake of an easier conversion.

Christopher
 --------------070903090803020800060505 Content-Type: text/html;
name="help.html"
Content-Transfer-Encoding: base64
Content-Disposition: inline;
filename="help.html"

PCFET0NUWVBFIGh0bWwgUFVCTElDICItLy9XM0MvL0RURCBIVE1MIDQuMDEgVHJhbnNpdGlv
bmFsLy9FTiI+CjxodG1sPgo8aGVhZD4KPC9oZWFkPgo8Ym9keSBsaW5rPSIjMDAwMGZmIiB2
bGluaz0iIzgwMDA4MCI+CjxoMz5Nb2R1bGUgJ3N0YWdlJzwvaDM+CjxwPgo8L3A+CjxwPgog
VGhpcyBtb2R1bGUgZGVmaW5lcyB0aGUgJ3N0YWdlJyBydWxlLCB1c2VkIHRvIGNvcHkgYSBz
ZXQgb2YgdGFyZ2V0cyB0bwogYSBzaW5nbGUgbG9jYXRpb24KPC9wPgo8cD4KIFR5cGljYWwg
dXNhZ2U6CjwvcD4KPHA+CiBzdGFnZSBkaXN0IDogaGVsbG9fd29ybGQgOiAmbHQ7bG9jYXRp
b24mZ3Q7L3Vzci9iaW4gOwo8L3A+CjxwPgogVGhlIHNvdXJjZSB0YXJnZXQgd2lsbCBiZSBj
b3BpZWQgdG8gdGhlIHNwZWNpZmllZCBsb2NhdGlvbi4gU29tZSB0YXJnZXRzIHdpbGwKIHdl
IHNwZWNpYWxseSBwcm9jZXNzZWQuIEluIHBhcnRpY3VsYXIsIGJpbmFyaWVzIHdpbGwgYmUg
cmVsaW5rZWQuIEZyZWUgcHJvcGVydGllcwogZnJvbSBzdGFnZSBkaXN0IHdpbGwgYmUgaW5j
bHVkZWQgdG8gcHJvcGVydGllcyB1c2VkIGZvciByZWxpbmtpbmcuIEZvciBleGFtcGxlCjwv
cD4KPHA+CiBzdGFnZSBkaXN0IDogaGVsbG9fd29ybGQgOiAmbHQ7bG9jYXRpb24mZ3Q7L3Vz
ci9iaW4gJmx0O2RsbC1wYXRoJmd0Oy9vcHQvbGliIDsKPC9wPgo8cD4KIHdpbGwgY2F1c2Ug
J2hlbGxvX3dvcmxkJyB0byBiZSByZWxpbmtlZCB0byB0aGUgbmV3IGxvY2F0aW9uLCBhbmQg
Jmx0O2RsbC1wYXRoJmd0OwogcHJvcGVydHkgd2lsbCBiZSBhZGRlZCB3aGVuIHJlbGlua2lu
Zy4KPC9wPgo8cD4KIFR3byBwcm9wZXJ0aWVzIHNwZWNpZmljYWxseSBjb250cm9sICdzdGFn
ZScgcnVsZS4KPC9wPgo8cD4KIC0gJmx0O2xvY2F0aW9uJmd0OyB0ZWxscyB3aGVyZSB0byBw
dXQgdGFyZ2V0cy4gSWYgbm90IHNwZWNpZmllZCwgZGlyZWN0b3J5CiAgIHdpdGggdGhlIHNh
bWUgbmFtZSBhcyBzdGFnZSBuYW1lIHdpbGwgYmUgdXNlZC4KPC9wPgo8cD4KIC0gJmx0O25h
bWUmZ3Q7IHRlbGxzIHRoZSBuZXcgbmFtZSBvZiB0aGUgc3RhZ2VkIHRhcmdldC4gSW4gdGhp
cyBjYXNlLCBvbmx5CiAgIG9uZSB0YXJnZXQgY2FuIGJlIHNwZWNpZmllZCBpbiBzb3VyY2Vz
Lgo8L3A+CjxwPgogVGhlIHN0YWdlIHJ1bGUgY2FuIGFsc28gdHJhdmVyc2UgZGVwZW5kZW5j
aWVzLCBmb3IgZXhhbXBsZSB0byBpbnN0YWxsIGEKIHByb2dyYW0gYW4gYWxsIHJlcXVpcmVk
IGxpYnJhcmllcy4gVHdvIHByb3BlcnRpZXMgYWZmZWN0IHRoaXMuCjwvcD4KPHA+CiAtICZs
dDt0cmF2ZXJzZS1kZXBlbmRlbmNpZXMmZ3Q7b24gdGVsbHMgdGhhdCBkZXBlbmRlbmNpZXMg
c2hvdWxkIGJlIHRyYXZlcnNlZC4KICAgRm9yIGVhY2ggdGFyZ2V0IGluICdzdGFnZScgc291
cmNlcywgYWxsIHNvdXJjZXMgdG8gdGhhdCB0YXJnZXQgYW5kIGFsbAogICBkZXBlbmRlbmN5
IHByb3BlcnRpZXMgYXJlIHRyYXZlcnNlZC4gU291cmNlcyBhbmQgZGVwZW5kZWN5IHByb3Bl
cnRpZXMgb2YKICAgdGhvc2UgdGFyZ2V0IGFyZSB0cmF2ZXJzZWQgcmVjdXJzaXZlbHkuCjwv
cD4KPHA+CiAtICZsdDtpbmNsdWRlLXR5cGUmZ3Q7U09NRV9UWVBFIHRlbGxzIHRoYXQgdGFy
Z2V0cyBvZiBTT01FX1RZUEUgb3IgYSB0eXBlIGRlcml2ZWQKICAgZnJvbSBTT01FX1RZUEUs
IHNob3VsZCBiZSBpbmNsdWRlZC4KICAgSWYgbm8gc3VjaCBwcm9wZXJ0eSBpcyBzcGVjaWZp
ZWQsIHRoZW4gYWxsIGZvdW5kIHRhcmdldHMgd2lsbCBiZSBzdGFnZWQuCiAgIE90aGVyd2lz
ZSwgb25seSB0YXJnZXRzIHdpdGggdHlwZXMgbWVudGlvbmVkIGluICZsdDtpbmNsdWRlLXR5
cGUmZ3Q7IHByb3BlcnR5CiAgIHdpbGwgYmUgaW5jbHVkZWQuCjwvcD4KPHA+CiAgIEV4YW1w
bGUgdXNhZ2U6CjxibG9ja3F1b3RlPgombmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDtz
dGFnZSZuYnNwO2Rpc3QmbmJzcDs6Jm5ic3A7aGVsbG9fd29ybGQmbmJzcDs6Jm5ic3A7PGJy
PgombmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbmJzcDsmbHQ7dHJhdmVy
c2UtZGVwZW5kZW5jaWVzJmd0O29uJm5ic3A7Jmx0O2luY2x1ZGUtdHlwZSZndDtFWEUmbmJz
cDsmbHQ7aW5jbHVkZS10eXBlJmd0O1NIQVJFRF9MSUImbmJzcDs7PGJyPgo8L2Jsb2NrcXVv
dGU+CjwvcD4KPGgzPk1vZHVsZSAnc3RhZ2UnIGNsYXNzZXM8L2gzPgo8cD4KPC9wPgo8cD4K
VXNlCi0taGVscApzdGFnZS4mbHQ7Y2xhc3MtbmFtZSZndDsKdG8KZ2V0Cm1vcmUKaW5mb3Jt
YXRpb24uCjwvcD4KPHVsPgo8bGk+CnN0YWdlLWV4ZS1nZW5lcmF0b3I6CjwvbGk+CjxsaT4K
c3RhZ2UtdGFyZ2V0LWNsYXNzOgo8L2xpPgo8L3VsPgo8aDM+TW9kdWxlICdzdGFnZScgcnVs
ZXM8L2gzPgo8cD4KPC9wPgo8cD4KVXNlCi0taGVscApzdGFnZS4mbHQ7cnVsZS1uYW1lJmd0
Owp0bwpnZXQKbW9yZQppbmZvcm1hdGlvbi4KPC9wPgo8dWw+CjxsaT4KY2hlY2stZm9yLXVu
dXNlZC1zb3VyY2VzOgpEb24ndCBkbyBub3RoaW5nLgo8L2xpPgo8bGk+CmNvbnN0cnVjdC1y
ZWd1bGFyLXRhcmdldHM6CkNvbnN0cnVjdHMgdGhlIHRhcmdldHMgb2YgdHlwZXMgZm9yIHdo
aWNoIHRoZXJlIGlzIG5vIFNUQUdFRF8qIHR5cGUuCjwvbGk+CjxsaT4KY29uc3RydWN0LXNw
ZWNpYWwtdGFyZ2V0czoKQ29uc3RydWN0cyB0aGUgdGFyZ2V0cyBvZiB0eXBlcyBmb3Igd2hp
Y2ggYSB0eXBlIGV4aXN0cyB3aXRoIHRoZSBmb3JtIFNUQUdFRF8qLgo8L2xpPgo8bGk+CnN0
YWdlOgpEZWNsYXJlcyBhIHN0YWdlIHRhcmdldC4KPC9saT4KPGxpPgp1cGRhdGUtbG9jYXRp
b246CklmICZsdDtsb2NhdGlvbiZndDsgaXMgbm90IHNldCwgc2V0cyBpdCBiYXNlZCBvbiB0
aGUgcHJvamVjdCBkYXRhLgo8L2xpPgo8L3VsPgo8L2JvZHk+CjwvaHRtbD4K
 --------------070903090803020800060505 Content-Type: text/xml;
name="help.xml"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="help.xml"

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">

<article>
<!-- your html had no title, but it's required in Docbook -->
<title/>

<section>
<title>Module 'stage'</title>

<para>This module defines the 'stage' rule, used to copy a set of
targets to a single location</para>

<para>Typical usage:</para>

<para>stage dist : hello_world : &lt;location&gt;/usr/bin ;</para>

<para>The source target will be copied to the specified location.
Some targets will we specially processed. In particular, binaries
will be relinked. Free properties from stage dist will be
included to properties used for relinking. For example</para>

<para>stage dist : hello_world : &lt;location&gt;/usr/bin
&lt;dll-path&gt;/opt/lib ;</para>

<para>will cause 'hello_world' to be relinked to the new location,
and &lt;dll-path&gt; property will be added when relinking.</para>

<para>Two properties specifically control 'stage' rule.</para>

<para>- &lt;location&gt; tells where to put targets. If not
specified, directory with the same name as stage name will be
used.</para>

<para>- &lt;name&gt; tells the new name of the staged target. In
this case, only one target can be specified in sources.</para>

<para>The stage rule can also traverse dependencies, for example to
install a program an all required libraries. Two properties
affect this.</para>

<para>- &lt;traverse-dependencies&gt;on tells that dependencies
should be traversed. For each target in 'stage' sources, all
sources to that target and all dependency properties are
traversed. Sources and dependecy properties of those target are
traversed recursively.</para>

<para>- &lt;include-type&gt;SOME_TYPE tells that targets of
SOME_TYPE or a type derived from SOME_TYPE, should be included.
If no such property is specified, then all found targets will be
staged. Otherwise, only targets with types mentioned in
&lt;include-type&gt; property will be included.</para>

<para>Example usage:</para>

<!-- Most HTML entities (like &nsbp;) are not supported. Luckily,
<programlisting> has <pre>-like semantics, so &nbsp; is not
necessary -->
<programlisting>
stage dist : hello_world :
&lt;traverse-dependencies&gt;on &lt;include-type&gt;EXE &lt;include-type&gt;SHARED_LIB ;
</programlisting>

</section>

<section>
<title>Module 'stage' classes</title>

<para>Use --help stage.&lt;class-name&gt; to get more
information.</para>

<!-- listitem doesn't accept #CDATA, must be wrapped in a block
element (such as para or simpara) -->
<itemizedlist>
<listitem><simpara>stage-exe-generator:</simpara></listitem>

<listitem><simpara>stage-target-class:</simpara></listitem>
</itemizedlist>

</section>
<section>
<title>Module 'stage' rules</title>

<para>Use --help stage.&lt;rule-name&gt; to get more
information.</para>

<itemizedlist>
<listitem><simpara>check-for-unused-sources: Don't do nothing.</simpara></listitem>

<listitem><simpara>construct-regular-targets: Constructs the targets of types
for which there is no STAGED_* type.</simpara></listitem>

<listitem><simpara>construct-special-targets: Constructs the targets of types
for which a type exists with the form STAGED_*.</simpara></listitem>

<listitem><simpara>stage: Declares a stage target.</simpara></listitem>

<listitem><simpara>update-location: If &lt;location&gt; is not set, sets it
based on the project data.</simpara></listitem>
</itemizedlist>

</section>
</article>
 --------------070903090803020800060505--