Matias Capeletto wrote: > On 6/9/07, Rene Rivera <[EMAIL PROTECTED]> wrote: > >> The big warning about the docs, as they are presented on the beta web >> site: They override, disregard, and literally throw away the style >> information in the source docs. > > I do not understand the rationale of adding another conversion tool to > the docs building chain.
Simple: * It allows the web site to set a consistent style, consistent to the web site that is. * It allows the web site to add interactive elements to the docs. The Google search is one example. Another we've wanted for some time is a fine grained commenting/notes system directly on the docs (like this <http://www.jackslocum.com/blog/2007/04/03/ext-js-launches/>). * It cleans up the docbook html. For example to do things like fix the paths to work within the web site structure. And to generally make it possible to use CSS for styling instead of the HTML+CSS combo docbook uses. > If we get every bit of boost docs into xml (by means of quickbook just > for the sake of simplicity) That's a big if. > why we need another processing step? See above :-) > I have learned xslt last week and I have to say that I am very impress > by the power it has. Ouch. I'll leave that discussion for some other time. >> How that happens is that the ZIP >> archives for all the release are put on the web server. The doc section > > This step is good now because we have docs in html that look differently. > IMO, once we get docs into qbk, this additional step will only add > extra complexity. > > qbk ---[ quicbook ]--> xml --[ boostbook ]--> html --[ new procesor ]--> html That last one is actually XHTML. But it would be ideal if the boostbook output XHTML instead of HTML. Just too many "bugs" in browsers for rendering HTML. > AFIKS every thing we will be doing in the new processor, can be > integrated into boostbook. Possibly... But it would not handle the case of changing the style of the web site at some future point, without having to regenerate all the docs for all the previous Boost releases. Which is not possible, since they are /fixed/ releases. >> The content of the header, i.e. the search box, will not be available on >> the web site. > > :( I should have been more specific. It's not going to be available in the header. It can be present some place else. > This is exactly the point! Boostbook is a great tool... > For me our problem is how to make html based docs look as our > boostbook docs. Your processor may be very, very useful. While we are My processor would be way simpler, if the boostbook docs did not use html for styling. Basically my processor cleans up the terrible html the docbook xslt transforms generate. > 100% agree with you, but I do can not see why we can not modified > boostbook to generate this kind of docs. See comment above about backward compatibility. > We should aim at simplicity, and IMHO adding an extra step is a step backward. Sure. And the point of separating the web site is to remove the responsibility of how the docs get presented on the web site from the library authors. Which simplifies the Boost release procedure. This might be a different simplicity than you have in mind though. > In the end we are all working to make boost a better place, both for > users and for developers. Sure. > The new beta.boost.org is a great step > forward! a really big one (thanks Rene for all the hard work there), Thanks. It's good to know it was worth the pain of accounting for all the feed back. > but I think that the proposed docs building chain is not going to work > well for us. There's no proposal. The only proposal we are really talking about is doc style. How the docs acquire that style is irrelevant. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
