Boost logo

Boost :

Subject: Re: [boost] [graph] quickbook reference docs and formatting
From: John Maddock (john_at_[hidden])
Date: 2009-09-03 12:09:12


> First, I need a second opinion on some formatting alternatives for the
> quickbook docs w.r.t the documentation of member/non-member functions of
> the
> graph classes.
>
> These should be mostly buildable - there are some errors about missing
> links, but they aren't fatal. Let me know if there are issues building
> them.
> I got the doc toolchain working a while ago and I'm afraid to mess with
> it.
> I may not have the same set up as everybody else. Hopefully I do.

It builds OK for me.

> The HTML docs give a flat listing with each function separated by a HR
> element, which is effective (although not especially navigable). Other
> lib**raries
> (e.g., Boost.Filesystem) present a similar listing although without the
> HR's
> to divide the content. I've tried putting these in a table to improve
> readability, and it works a little but, but I don't have enough control
> over
> the table to prevent auto-wrapping, which can break a function declaration
> line in weird places.
>
> So what's better: a flat listing or a table? Is there a third option?

I prefer a flat listing as you currently have for the member functions in
adjacency_list.html. IMO the tables get too wide and ungainly for HTML and
for PDF output will very likely look awful (not enough page width - let me
know if you want me to generate a PDF anytime). But I agree that a third
option might be nice... something to delineate the different member
functions without having to make each one a separate section or something.
But I can't think of anything in Docbook that would work for that at
present... let me think about this.

Otherwise after a brief skim through it looks fine. Let me know if you need
any help with xsltproc options etc to customize output to the Graph libs
needs.

HTH, John.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk