Quickbook questions

[Cromwell Enage]

I'm currently using CVS HEAD for learning how to use
Quickbook.

1. The only job of the Quickbook executable is to
convert *.qbk files to BoostBook XML, right?  Is there
no other output format for the moment?

2. Let's say that the root file for all my MPL.Math
documentation is BOOST_ROOT/libs/mpl/doc/src/math.qbk
and that my Jamfile, which is located in
BOOST_ROOT/libs/mpl/doc/, looks like this:

## start of file ##

project boost/libs/mpl/doc ;
import boostbook : boostbook ;
using quickbook ;

boostbook quickbook
    : src/math.qbk
    : <xsl:param>...
    ;

## end of file ##

Other than the <xsl:param> stuff, is this Jamfile
correct?  Where should I look to figure out what can
go with <xsl:param> besides existing Jamfiles?

                              Cromwell D. Enage



       
____________________________________________________________________________________
Be a better Heartthrob. Get better relationship answers from someone who knows. Yahoo! Answers - Check it out.
http://answers.yahoo.com/dir/?link=list&sid=396545433

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/3/07, Cromwell Enage <sponage@...> wrote:

Hi Cromwell.

> I'm currently using CVS HEAD for learning how to use
> Quickbook.

Great! Welcome to quickbook then.

> 1. The only job of the Quickbook executable is to
> convert *.qbk files to BoostBook XML, right?  Is there
> no other output format for the moment?

That is right. But there is an ongoing effort to support other backends.

> 2. Let's say that the root file for all my MPL.Math
> documentation is BOOST_ROOT/libs/mpl/doc/src/math.qbk
> and that my Jamfile, which is located in
> BOOST_ROOT/libs/mpl/doc/, looks like this:
>
> ## start of file ##
>
> project boost/libs/mpl/doc ;
> import boostbook : boostbook ;
> using quickbook ;
>
> boostbook quickbook
>     : src/math.qbk
>     : <xsl:param>...
>     ;
>
> ## end of file ##
>
> Other than the <xsl:param> stuff, is this Jamfile
> correct?  Where should I look to figure out what can
> go with <xsl:param> besides existing Jamfiles?

I recommend you read this guide, it is very fresh stuff (four days I
think) so we can really use your feedback.

http://svn.boost.org/trac/boost/wiki/DocsOrganization

There examples there so you can quick start with quickbook.

You can download the first release of the IBD project:

http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs#Downloads

And look how the doc_test is organized. ( doc/doc_test )
You will see that now all the style resides in ( doc/style ) making
your life easier and avoiding resource duplication.

Best regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[John Maddock]

Cromwell Enage wrote:
> 1. The only job of the Quickbook executable is to
> convert *.qbk files to BoostBook XML, right?  Is there
> no other output format for the moment?

Not at present.  From Docbook XML you can generate PDF, PS, HTML, XHTML, man
pages, and HTMLHelp.

> 2. Let's say that the root file for all my MPL.Math
> documentation is BOOST_ROOT/libs/mpl/doc/src/math.qbk
> and that my Jamfile, which is located in
> BOOST_ROOT/libs/mpl/doc/, looks like this:
>
> ## start of file ##
>
> project boost/libs/mpl/doc ;
> import boostbook : boostbook ;
> using quickbook ;
>
> boostbook quickbook
>    : src/math.qbk
>    : <xsl:param>...
>    ;
>
> ## end of file ##
>
> Other than the <xsl:param> stuff, is this Jamfile
> correct?

Yep.

> Where should I look to figure out what can
> go with <xsl:param> besides existing Jamfiles?

The ultimate reference is
http://docbook.sourceforge.net/release/xsl/current/doc/.

Here's one of my Jamfiles with comments: it includes most of the options
you're likely to want to tweek:

using quickbook ;

xml regex : regex.qbk ;
boostbook standalone
    :
        regex
    :
        # HTML options first:
        # Use graphics not text for navigation:
        <xsl:param>navig.graphics=1
        # How far down we chunk nested sections, basically all of them:
        <xsl:param>chunk.section.depth=10
        # Don't put the first section on the same page as the TOC:
        <xsl:param>chunk.first.sections=1
        # How far down sections get TOC's
        <xsl:param>toc.section.depth=10
        # Max depth in each TOC:
        <xsl:param>toc.max.depth=4
        # How far down we go with TOC's
        <xsl:param>generate.section.toc.level=10
        # Path for links to Boost:
        <xsl:param>boost.root=../../../..
        # Path for libraries index:
        <xsl:param>boost.libraries=../../../../libs/libraries.htm
        # Use the main Boost stylesheet:
        <xsl:param>html.stylesheet=../../../../doc/html/boostbook.css

        # PDF Options:
        # TOC Generation: this is needed for FOP-0.9 and later:
        #<xsl:param>fop1.extensions=1
        # Or enable this if you're using XEP:
        <xsl:param>xep.extensions=1
        # TOC generation: this is needed for FOP 0.2, but must not be set to
zero for FOP-0.9!
        <xsl:param>fop.extensions=0
        # No indent on body text:
        <xsl:param>body.start.indent=0pt
        # Margin size:
        <xsl:param>page.margin.inner=0.5in
        # Margin size:
        <xsl:param>page.margin.outer=0.5in
        # Yes, we want graphics for admonishments:
        <xsl:param>admon.graphics=1
        # Set this one for PDF generation *only*:
        # default pnd graphics are awful in PDF form,
        # better use SVG's instead:
        #<xsl:param>admon.graphics.extension=".svg"
    ;

The most useful ones are:

        # Path for links to Boost:
        <xsl:param>boost.root=../../../..
        # Path for libraries index:
        <xsl:param>boost.libraries=../../../../libs/libraries.htm
        # Use the main Boost stylesheet:
        <xsl:param>html.stylesheet=../../../../doc/html/boostbook.css

As they let you use the existing images and stylesheets in doc/, not sure if
they work with full URL's to the Boost website though.

HTH, John.


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Joel de Guzman-2]

John Maddock wrote:

>         # Set this one for PDF generation *only*:
>         # default pnd graphics are awful in PDF form,
--------------------^^^

You mean png?

Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net


-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[John Maddock]

Joel de Guzman wrote:
> John Maddock wrote:
>
>>         # Set this one for PDF generation *only*:
>>         # default pnd graphics are awful in PDF form,
>> --------------------^^^
>
> You mean png?

Ah, that would be the ones, yes :-)

John.

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Cromwell Enage]

--- Matias Capeletto wrote:
> Hi Cromwell.

Hi, Matias.

> I recommend you read this guide, it is very fresh
> stuff (four days I think) so we can really use your
> feedback.
>
>
http://svn.boost.org/trac/boost/wiki/DocsOrganization

Okay, I'll play with the IBD distro before I give real
solid feedback.  However, I am curious about a couple
of things:

1. The DocsOrganization page recommends that images be
in either *.png or *.svg format.  However, I see no
inherent downside to using *.jpeg images in certain
cases (other than the usual lossy-compression issues).
 For example, StarUML (homepage at
http://staruml.sourceforge.net/ ) can, at present,
export UML diagrams only to the *.jpeg format.  I'm
simply pointing out that being a good netizen with
regard to images is more than just using a recommended
format.

2. Is the example/doc subdirectory the only place
Quickbook will look for code chunks?  In my automata
library, I also pull code from programs in the test
subdirectory, so at the very least I would like to be
able to keep the code there (or move them to a
test/doc subdirectory, if necessary).

Otherwise, this is good stuff!  Keep it up!

                              Cromwell D. Enage



       
____________________________________________________________________________________
Looking for a deal? Find great prices on flights and hotels with Yahoo! FareChase.
http://farechase.yahoo.com/

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/4/07, Cromwell Enage <sponage@...> wrote:

> --- Matias Capeletto wrote:
> > Hi Cromwell.
>
> Hi, Matias.
>
> > I recommend you read this guide, it is very fresh
> > stuff (four days I think) so we can really use your
> > feedback.
> >
> >
> http://svn.boost.org/trac/boost/wiki/DocsOrganization
>
> Okay, I'll play with the IBD distro before I give real
> solid feedback.

That will be great.

> However, I am curious about a couple
> of things:
>
> 1. The DocsOrganization page recommends that images be
> in either *.png or *.svg format.  However, I see no
> inherent downside to using *.jpeg images in certain
> cases (other than the usual lossy-compression issues).
>  For example, StarUML (homepage at
> http://staruml.sourceforge.net/ ) can, at present,
> export UML diagrams only to the *.jpeg format.  I'm
> simply pointing out that being a good netizen with
> regard to images is more than just using a recommended
> format.

I am not against jpeg. The DocsOrganization recommends pngs
to try to have a common image format in Boost. If you can not
use pngs, you can use other format.
We must recommend one. Do you think jpeg is a better
recommendation?

> 2. Is the example/doc subdirectory the only place
> Quickbook will look for code chunks?  In my automata
> library, I also pull code from programs in the test
> subdirectory, so at the very least I would like to be
> able to keep the code there (or move them to a
> test/doc subdirectory, if necessary).

Again, it is just a recommendation. If you have to write
code snippets only for your docs, put them there.
If you want to extract snippets that are in your test suite,
your example folder or your library headers, you just do it.
This is done in qbk with:
[import file_path]

> Otherwise, this is good stuff!  Keep it up!

Thanks for the feedback.
Please keep coming!

Best regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Cromwell Enage]

--- Matias Capeletto wrote:
> I am not against jpeg.  The DocsOrganization
> recommends pngs to try to have a common image
> format in Boost.

I actually agree with this.

> If you can not use pngs, you can use other format.

That's good to hear.

> We must recommend one.  Do you think jpeg is a
> better recommendation?

What I'd say is "use PNGs when you can, but use other
formats (e.g. JPEG) when you have to."  Perhaps it's
just a matter of wording.

> > 2. Is the example/doc subdirectory the only
> > place Quickbook will look for code chunks?  In
> > my automata library, I also pull code from
> > programs in the test subdirectory, so at the
> > very least I would like to be able to keep the
> > code there (or move them to a test/doc
> > subdirectory, if necessary).
>
> Again, it is just a recommendation.  If you have
> to write code snippets only for your docs, put
> them there.  If you want to extract snippets that
> are in your test suite, your example folder or
> your library headers, you just do it.

Okay, thanks for the clarification.

                              Cromwell D. Enage



       
____________________________________________________________________________________
Get the Yahoo! toolbar and be alerted to new email wherever you're surfing.
http://new.toolbar.yahoo.com/toolbar/features/mail/index.php

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs