Re: [boost] [1.34] Feature Freeze

From: David Abrahams (dave_at_[hidden])
Date: 2006-02-12 20:01:12

Rene Rivera <grafik.list_at_[hidden]> writes:

> Because some of the existing docs may not make much sense in the new 
> structure. For example the getting started would need to get chopped up 
> as there's a download page (or they will be). 

Having recently prepared a "Getting Started with Boost" talk, I have
been planning on rewriting the Getting Started docs anyway.  Not sure
what *you* have in mind Re: chopping up, but one conclusion I came to
is that we need some way to give people a continuous thread of
information they can read for their own platform/compiler, without
being distracted by the others.  That means either dividing it into
separate documents that can be assembled via some kind of include
directive, or, if there are few enough of these threads (say, 2-3),
maybe a multicolumn layout with one column per procedure, and
full-width boxes where the procedure can be shared.  I realize
it's unorthodox, but one thing I like about the latter approach is
that you can see how the different platforms relate to one another
without being interrupted by them when you don't care.

> There's probably more things like that, but I guess rewrite is too
> strong of a word. Perhaps "editing" is more accurate.

Not in case of the Getting Started stuff.  With all due respect to
your excellent efforts (which got many new users over the hump), it
needs a major overhaul.

>>> I've done that for some of the documents.  But I just don't have the
>>> free time to do it for all of them in the next few weeks, or even
>>> months, to get the new site ready for the release.
>> 
>> I'd be happy to volunteer if I can really understand what it means.
>
> I think you got the basic idea with your first questions. The details 
> technical details are...
>
> 1. Checkout the sources: cvs co user_at_[hidden]:/cvsroot/boost website. 
> The directory structure under that is fairly obvious.
>
> 2. Download and install tidy from <http://tidy.sourceforge.net/>. The 
> latest version is always best.
>
> 3. Pick some old page that isn't translated and find a place for it.
>
> 4. Copy the website/workplace/template.html file to where you want the 
> page, with a reasonable new name of course.
>
> 5. Edit the various SSI (server side includes) references, i.e. the 
> "#include" to match the section you are in for the sidebars. It should 
> be changing the single "/common/sidebar-boost.html" reference to one of:
>
>      /common/sidebar-boost.html
>      /common/sidebar-community.html
>      /common/sidebar-development.html
>      /common/sidebar-doc.html
>      /common/sidebar-support.html
>
> 6. Edit the reference to the section specific CSS in the head to match. 
> Similar to #5, this section specific CSS controls the tab that shows up 
> as active.
>
> 7. Copy over from the old HTML into the "section-body" div. Where the 
> "<p>{stuff}</p>" placeholder is.
>
> 8. Run tidy as such:
>
>    tidy --tidy-mark no -i -wrap 78 -m -asxhtml --doctype strict /fname/
>
> This forces the document into XHTML regardless of the content so it 
> cleans up most of the content.
>
> 9. Open the file in your browser and adjust the source as needed, fix 
> links, etc. WARNING: The header, sidebars, and parts of the footer will 
> not show up as they require running within Apache to get inserted by 
> SSI. That's OK, the style of the content should be accurate.

If I run a Cygwin apache here, can I get a look at it?

> 10. Commit into CVS, and some time later my test server will resync with 
> CVS (it does so on 10 minute intervals) and you'll see the page in the 
> full context.
>
> 11. To add links to the sidebars, edit the appropriate menu file in 
> "/common/menu-yyy.html" and add an item.
>
> ** I'll the above to the website for reference, much later tomight. **

You read my mind!  And BTW, I enthusiastically volunteer.

>> BTW, the new website design suffers a bit from a lack of structure.
>> Lines or colored panels used to separate the main text columns might
>> be helpful.
>
> Yea, I think it's just an effect of the main page since it has less 
> content than the rest. I'll see what I can do, most likely shaded boxes 
> for the news and downloads sections. Thanks for the suggestion :-)

Yer welcome.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com