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. We now have: (1) html only docs (2) boostbook based docs (3) quickbook based docs The tool chain is: (1) html (2) xml ---[ boostbook ]----> html (3) qbk ----[ quicbook ]----> xml ---[ boostbook ]----> html 2 and 3 passed through boostbook so the look and feel is the same. The only problem are html only docs. IMHO the way to go is to get these docs into quickbook. (I have already translated four boost libraries docs and I plan to continue doing it if authors allows me to do it) Note that for the present discussion about styles and the new banner bar the important thing is boostbook and not quickbook. If we get every bit of boost docs into xml (by means of quickbook just for the sake of simplicity) why we need another processing step? I have learned xslt last week and I have to say that I am very impress by the power it has. > How that happens is that the ZIP > archives for all the release are put on the web server. The doc section > pages, when requested to open one of the version specific doc files, > opens a specific archive and expands+reads the file into memory. It then > post processes that file, on the fly, stripping out all of the header > and footer content. It also does some number of cleanups and fixing in > the content itself. Currently that is done via structured regex > search+replace manipulation, but I'll be changing that at some point to > do DOM manipulations now that the server has PHP5. The doc is then > incorporated back into the web page one sees with the standard header > and footer for the web site. The CSS used is entirely different than the > one in the document at this point, since it comes from the standard web > site style! 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 AFIKS every thing we will be doing in the new processor, can be integrated into boostbook. > The style used for the docs is designed, and inherited, from the style > for the rest of the site (exemplar page > <http://beta.boost.org/development/exemplar.html>). There are additional > styles to handle the variety of elements and changes over time that the > Boost docs have had, and are still having ;-) > > The presentation architecture has some consequences for Matias styles, > and other author's styles... > > They will *only* be visible in the downloaded release, iff they are > generated by the authors themselves. > The content of the header, i.e. the search box, will not be available on > the web site. And hence will *only* be available in the downloaded > release. This also happens to be the one context under which it's likely > not usable as the person might not have network access. :( 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 in the transition all the html docs are processed to look like the others. (1) html ---[ rene processor ]---> html that looks like boostbook docs (2) xml ---[ boostbook ]----> html (3) qbk ----[ quicbook ]----> xml ---[ boostbook ]----> html > Changes to the style of the docs are less likely to make it to the web > site than changes to the release style. This is intentional, as it's > important to keep a consistent look & feel on the web site. Both for > usability and presentation quality of the web site. It means that > changes to the web site style have to arbitrated even more than changes > to the release doc styles. 100% agree with you, but I do can not see why we can not modified boostbook to generate this kind of docs. We should aim at simplicity, and IMHO adding an extra step is a step backward. In the end we are all working to make boost a better place, both for users and for developers. The new beta.boost.org is a great step forward! a really big one (thanks Rene for all the hard work there), but I think that the proposed docs building chain is not going to work well for us. Best regards Matias ------------------------------------------------------------------------- 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
