Re: [boost] Boost documentation

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-06-24 16:11:30

On 6/24/07, David Abrahams <dave_at_[hidden]> wrote:
> on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
> > Hi,
> >
> > 5. This is new *nonstandard* format any new developer will have to
> > learn. I don't believe we can afford yet another barrier for new
> > submitters.
>
> Unless they already know DocBook, DocBook represents a much higher
> barrier for most people getting started.

Totally agree.

> > 6. Source code highlighting
> >
> >       My understanding is that quickbook presents some source code
> > highlighting automation. IMO this can be either implemented as standalone
> > C++ based tool that docs writers can use when required or even better it can
> > be implemented in JavaScript. I believe I've seen it done.
>
> I'm not sure I want to do that job on the browser, but I understand
> the appeal, especially if end-users can tune the colors.

Have you seen this: (firefox, safari, camino and knoqueror only for now)
http://tinyurl.com/27ubvp
Move the mouse to the upper-right corner of a code-block and select
your preferred IDE.

> > II. BoostBook
> > 4. Documentation
> > I found documentation to be largely unacceptable (funny thing for the
> > project dedicated to writing documentation)
> >
> >     c) most critical: no description whatsoever of all the modification done
> > in comparison with DocBook. All the updated parameter need to be listed, all
> > the updated templates need to be explained. General approach should be what
> > the person familiar with DocBook (standard) need to know/expect to use
> > BoostBook
>
> That's a problem.

Almost solved in my local copy, will upload it soon.

> > As I mentioned before we should try to limit our extensions to the most
> > necessary only and strive to stick with standard DocBook. Also all
> > extensions should be made optional.
>
> Aren't they, currently?

Yep.

> > III. What should we do?
> >
> > IMO the standardization efforts need to target DocBook/BoostBook. On the
> > other hand each developer should be allowed to extend/twick standard L&F.
> > Usually differences should be only cosmetic.
>
> Major cosmetic differences will keep Boost looking fractured.

100% agree.

> > Following are general
> > observations about common L&F
> >
> > 1. JS Menu support.
> >    I believe it should be implemented but made optional.
>
> Why not just let the user show/hide it?

I am working to provide this functionality. You have spoiled the
surprise effect now ;)

> >   4. Portability
> >   This is major requirement for all the features we implement. They should
> > work on at least set of predefined "major" browsers.
>
> Yep.

We are currently working on this.

Best regards
Matias Capeletto