Re: [boost] [graph] quickbook reference docs and formatting

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.