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.