Quickbook questions
Locked
 
|
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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
|
|
On 7/3/07, Cromwell Enage <[hidden email]> 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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
|
|
In reply to this post by Cromwell Enage
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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
|
|
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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
|
|
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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
|
|
In reply to this post by Matias Capeletto
--- 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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
Re: [IBD] Quickbook questions
|
|
On 7/4/07, Cromwell Enage <[hidden email]> 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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
|
|
--- 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 [hidden email] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs |
«
Return to Boost - Doc
|
1 view|%1 views
| Free forum by Nabble | Edit this page |