On 6/13/07, Rene Rivera <[EMAIL PROTECTED]> wrote:
> 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.
Nice points, but I still think that boostbook can handle all of this.
> > 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.
I know, but I think it is very feasible to accomplished it in finite
time. I will continue translating docs when I have some time, and I
hope others will jump in.
> > 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.
You do not seem to like it ;)
> >> 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.
I do not see that a mutable changing style in old boost releases being a plus.
What is more, one thing that bothers me in the beta pages is that it
is cluttered with this old stuff. I find it useful to put a link to
old release docs but IMO the main page must jump directly to the last
version documentation.
> >> 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.
But it is in the header were it belongs.
> > 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.
Ok, you hate xslt :)
In that case, and if we show that your processor is much better (I
have only used xslt for a week so I am not attached to it) both in the
xhtml generated and in the way to specify how this conversion must be
done, why do we need docbook?
Why are you crawling the docbook htmls to find the useful information
if you have xml specifications in your hand?
For that htmls that are generated with docbook, is it really hard for
your tool to crawl and transform them to xml instead of xhtml? If this
is the case you have done a great tool that allows us to have all
boost docs in xml...
> > 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.
My idea of simplicity is:
Boost authors write the docs using quickbook. Each library must have:
boost/libs/some_lib/doc
boost/libs/some_lib/doc/some_lib.qbk
boost/libs/some_lib/doc/Jamfile.v2
There exist a glue quicbook libs docs in
boost/doc/libs/libs.qbk
boost/doc/libs/Jamfile.2
To generate the documentation there is an script that:
for each library:
{
generate the docs using the Jamfile of each library
bjam --v2 (maybe with --website, that tells boostbook to ignore
some options)
copy the result to [web]/libs/library_name
}
generate the glue docs and copy it to [web]/libs/
I fail to see why we can not do this. Is there a docs manager? He can
have this responsibility in each release.
> > 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.
I do not think that it is irrelevant. For one thing, we may now have
features in boostbook that allows us to transverse our docs better and
this stuff will going to be striped out by a new processor in the docs
chain. We are not talking about style here.
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
