[boostbook][PATCH] member classes in synopsis

The attached patch attempts to make member classes look a little better in the 
parent class synopsis.  If noone objects, I'll apply it to trunk sometime 
next week.

_______________________________________________
Boost-docs mailing list
Boost-docs <at> lists.boost.org
http://lists.boost.org/mailman/listinfo.cgi/boost-docs

Re: [quickbook] Template argument evaluation.

2009/5/29 Eric Niebler <eric <at> boostpro.com>:
>
> Frankly, I'm ok with breaking docs that rely on the weird dynamic scoping of
> quickbook templates. There are probably exactly 0 docs in this category. I
> say, just rip it out and replace it with something sensible.

There are also a few other things I'd like to change which will be
more disruptive so they'll definitely need a version switch. In this
case it's actually pretty easy to implement the switch so I thought I
might as well use one for everything. It gives an incentive to
upgrade. But the current lookup behaviour could be seen as just broken
and worth fixing for all versions.

I've started making notes on possible changes:

https://svn.boost.org/trac/boost/wiki/BoostDocs/Quickbook-1.5

Daniel

[quickbook] Template argument evaluation.

Hi,

I've been going through some of the old template tickets, and having a
look at the implementation and there's a few things which could be
improved. I think that these changes should be activated by a version
switch, so perhaps it's worth starting on a version 1.5.

First, quickbook currently uses dynamic scoping which is generally
accepted to be a bad idea. So I'd like to change it to use static
scoping. This example:

    [template x static scoping]
    [template foo1[] [x]]
    [template foo2[x] foo1]
    [foo2[dynamic scoping]]

Will currently return 'dynamic scoping', I'd like it to change it to
return 'static scoping' for 1.5 or whatever.

When template arguments are expanded they are evaluated with the
current scope rather than the scope they were called with which can be
surprising. So I'd like to change it so that they are bound to the
correct scope. So:

   [template x new]
   [template foo1[a x] [a]]
   [foo1 [x] old]

Will return 'old' at the moment, I'd prefer it to return 'new'.
Another way to achieve this would be to evaluate template arguments

[Quickbook] Feature request

Including files with [include filename] should work with templates. e.g:

[template mypath[file] some/path/[file]]
[include [mypath get/file]]

So far I see two workarounds:
Either (a) explicitely set the full path in the include block. But this has
the problem that you need to know the path, which is not always possible;
for example if quickbook gets called from a build directory the path to the
source directory is not known when writing the quickbook documentation.
Or (b) use -I /some/path which is my current workaround. However if there
are more files with the same name in different directories, things will get
ugly.

Please implement or rewrite quickbook for Spirit 2.1 and use it as a well
documented sample application, in which case I might try to implement it;
whichever is more convenient 

Thomas

Document build problem - I/O error : Failed to load external entity

Hello,

I'm new in boost.book and quickbook. Follwing an instruction I've
installed iconv, zlib, libxml2, libxslt, boostbook xml, docbook xsl,
generated quickbook.exe and updad my user-config.jam:

using xsltproc : "c:/pj/qbook/bin/xsltproc.exe" ;

using boostbook
    : "c:/pj/qbook/docbook-xsl"
    : "c:/pj/qbook/docbook-xml"
    ;

 using quickbook
    : "c:/pj/qbook/bin/quickbook.exe"
    ;

Attempt to compile simple quickbook fails because lots of "failed to
load external entity" errors:

C:\pj\tmp\qbook>bjam --v2 --toolset=msvc html
...found 13 targets...
...updating 4 targets...
common.mkdir bin\msvc-9.0express\debug\threading-multi
quickbook.quickbook-to-boostbook
bin\msvc-9.0express\debug\threading-multi\test.xml
Generating Output File: bin\msvc-9.0express\debug\threading-multi\test.xml
xslt-xsltproc bin\msvc-9.0express\debug\threading-multi\test.docbook
xslt-xsltproc-dir html\standalone_HTML.manifest
warning: failed to load external entity

building docs for one library

I've patched in the coroutine library into my boost 1.37 tree and want to 
build the documenation
for it.  When I invoke bjam either from within the directory containing the 
files for from the
boost root I get a series of messages back that i don't understand - see 
below.

What is the proper way to invoke the documentation build for one library?

Robert Ramey

$ pwd
C:/boost_1_37_0/libs/coroutine/doc
$ ls
Jamfile.v2     coroutine.qbk  index.html     index_files

$ bjam
Jamfile.v2:36: in modules.load
rule doxygen unknown in module Jamfile</C:/boost_1_37_0/libs/coroutine/doc>.
C:/boost_1_37_0/tools/build/v2/build\project.jam:307: in load-jamfile
C:/boost_1_37_0/tools/build/v2/build\project.jam:62: in load
C:/boost_1_37_0/tools/build/v2/build\project.jam:168: in project.find
C:/boost_1_37_0/tools/build/v2\build-system.jam:535: in load
C:\boost_1_37_0\tools\build\v2/kernel\modules.jam:283: in import
C:\boost_1_37_0\tools\build\v2/kernel/bootstrap.jam:128: in boost-build
C:\boost_1_37_0\boost-build.jam:16: in module scope
$ 

quickbook xinclude bug?

I'm trying to generate docs for proto manually.  I'm on the trunk. 
Proto's 'proto.qbk' contains the line

[xinclude reference.xml]

which is in the same directory as proto.qbk itself:

% ls -l /home/troy/Projects/boost/trunk/src/libs/proto/doc/proto.qbk
-rw-r--r-- 1 troy troy 11250 Jan 24 06:54 
/home/troy/Projects/boost/trunk/src/libs/proto/doc/proto.qbk

% ls -l /home/troy/Projects/boost/trunk/src/libs/proto/doc/reference.xml
-rw-r--r-- 1 troy troy 36374 Jan 24 06:54 
/home/troy/Projects/boost/trunk/src/libs/proto/doc/reference.xml

I cd to a build directory parallel to the source tree, and generate the 
xml with quickbook.  I've hacked some couts into the xinclude action:

% cd /home/troy/Projects/boost/trunk/build/libs/proto/doc && 
../../../bin/quickbook --output-file=proto.xml 
/home/troy/Projects/boost/trunk/src/libs/proto/doc/proto.qbk
Generating Output File: proto.xml
infile=/home/troy/Projects/boost/trunk/src/libs/proto/doc/proto.qbk
outdir=/home/troy/Projects/boost/trunk/build/libs/proto/doc/.
returning path=../../../../../src/libs/proto/doc/reference.xml

I doublecheck the path to reference.xml in the generated proto.xml:

% grep reference.xml proto.xml
   <xi:include href="../../../../../src/libs/proto/doc/reference.xml" />

Why do the Doxygen member functions comments not appear in the ?

Do any Doxygen Doctors know why/how to get the \brief member function info
to appear on the Functions lists.

Especially when it comes through using autodoc into Quickbook, Docbook...
but it's a Doxygen issue, not any post processing.

You will see below in the synopsis that the member variables at the bottom
have their comments appended,
But the functions do not (although the line at the bottom from the fully
members list shows that there is a comment).

IMO It would be neater for the  

// In header: <boost/svg_plot/svg.hpp>

class svg {
public:
  // construct/copy/destruct
  svg();
  svg(const svg &);
  // private member functions
  void write_header(std::ostream &) ;
...
  // public member functions
void x_size(unsigned int) ;
void y_size(unsigned int) ;
unsigned int x_size() ;
unsigned int y_size() ;
...
g_element & g(int) ;

Re: Quickbook with Doxygen autodoc -How togetthe function (and enum) descriptions?

> I did notice a minor wrinklette in the pdf - the function number (22 in 
> the
> example above) lies on the border of the box, neither in nor out.

I've fixed that one in the XSL customisation layer.

John.

Re: Quickbook with Doxygen autodoc -How togetthe function (and enum) descriptions?

>> You shouldn't see anything except functions in there (as the primary
> entries
>> that is), assuming this is refering to auto-index?
>>
>> If not do you have a "bad" example that slips through?
>
> Well if I look at the function index and look at author (since it's near 
> the
> top of the alphabet 
>
> What I hoped to find was a link that took me directly to the function info
>
> 22.  void author(const std::string a) ;
>
> Set author for the document (default is copyright_holder).
>
> But what I get is several links to the primary author entry
>
> author
>
>    Description
>
>    Header < boost/svg_plot/svg.hpp >
>
>    Header < boost/svg_plot/svg_fwd.hpp >
>
>    Implementation & Rationale
>
>    svg public member functions
>

Korean Localization of the Boost

_______________________________________________
Boost-docs mailing list
Boost-docs <at> lists.boost.org
http://lists.boost.org/mailman/listinfo.cgi/boost-docs