Re: [boost] boost test documentation problems

From: Ronald Garcia (garcia_at_[hidden])
Date: 2002-08-14 14:00:25

Rozental, Gennadiy wrote:

>>For most boost libraries, the web pages are the only documentation 
>>available.  I tend to use non-browser tools to generate quality 
>>(somewhat :) ) printouts and postscript/pdf files of the documentation.  
>>Javascript hinders my ability to do so.
>>    
>>
>
>And what about exteranal style sheets I am using? And I do not think that
>this is a problem in any case. 
>Use postscript printer and print to file. Boost.Test documentation take
>special care about pretty printing.
>So even if you print it just as is it shouuld be good enough. If you have
>any problems with prined version - let me know.
>  
>
Currently when I attempt to print your docs (using html2ps btw), the 
entire index.htm file is rendered onto one page in very small print.  I 
presume it is because the entire document is embedded in a table, but I 
am not an expert on these issues.  Alternatively, when I print from my 
web browser (mozilla), the boost logo comes out warped. Of course this 
is not a large issue, but I think you may overstate the ubiquity of 
proper implementation of extensions to vanilla html.

>>I am all for using tools to generate that HTML where useful and do so
>>    
>>
>myself, but I 
>  
>
>>think the distributed docs should be simple.
>>    
>>
>I do not use documentation generation tools and javascript is the only
>reasonable way to support different pages in sync.
>  
>
With all due respect, I'm not convinced of this.  Out of curiousity, I 
edited my personal copy of your index page, removing the table around 
everything and references to javascript.  The only things that seem to 
be missing are the fancy border, the Boost logo and the fancy menu that 
pops up at the top.  With the exception of the missing boost logo, I 
like the result a lot better than the original. Having written a few 
boost docs myself, I'm pretty sure that the code necessary to display 
the Boost Logo is shorter than your Javascript and stylesheet directives.

Of course Boost.Test is your library and the presentation style in the 
end is for the most part your choice, but it doesn't seem like the 
javascript adds much except for the eye candy, which hardly seems 
necessary.  In what way is it supporting maintainability?

ron