Re: [Boost-docs] [boost-docs] [boostbook] Documenting and revisingparams

From: John Maddock (john_at_[hidden])
Date: 2007-06-19 05:52:09

Matias Capeletto wrote:

> (a) __ website params __
>    The new style, based on beta.boost.org including GroupedLinks and
>    Google search box.
>
>    grouped.links.js ( 'grouped_links.js' )
>
>    grouped.links.chapters.show   ( 'false'          )
>    grouped.links.chapters.xml    ( 'boost_libs.xml' )
>    grouped.links.chapters.url    ( ''               )
>
>    grouped.links.sections.show   ( 'false'          )
>    grouped.links.sections.xml    ( 'sections.xml'   )
>    grouped.links.sections.url    ( ''               )
>
>    search.box.show               ( 'false'          )
>    search.box.cse.definition.src (
> 'http://www.boost.org/cse.definition.xml' )

I might be inclined to turn these on by default.

> [[[[ proposed ]]]]]
>
> # only the new style is supported
> page.style ( 'standard' )
>
> # other small js libs may appear, we support this from the beginning
> javascript.lib.root ( concat($boost.root, '/doc/javascript/') )
>
> grouped.links.chapters.*   [ same as before,
>                             but point to
> boost.root/doc/boost_libs.xml ]
> grouped.links.sections.*   [ same as before ]
> search.box.*               [ same as before ]
>
>
> Style sheet and graphics
> -------------------------------------------------------------------
> There are a lot of parameters here. IMO they can be reduced with
> out loosing flexibility
>
> [[[[[ current ]]]]]
>
> html.stylesheet          ( 'boostbook.css' )
>
> admon.graphics           ( 1    )
> admon.graphics.extension ( .png )
> admon.graphics.path      ( concat($boost.root, '/doc/html/images/') )
>
> navig.graphics           ( 1    )
> navig.graphics.extension ( .png )
> navig.graphics.path      ( concat($boost.root, '/doc/html/images/') )
>
> [[[[[ proposed ]]]]]
>
> html.stylesheet          ( concat($boost.root,
> '/doc/style/boostbook.css') )

Yep.

>  admon.graphics           [ deprecated ] a <div
> class="admonition_type"/> is used
>  admon.graphics.extension [ deprecated ] the css decide if graphics
>  are used admon.graphics.path      [ deprecated ] and their path and
>  extension navig.graphics           [ deprecated ] <div
>  class="navig_graphic_type"/> navig.graphics.extension [ deprecated ]
>  the css decide if graphics are used navig.graphics.path      [
> deprecated ] and their path and extension

OK.

> Chunker params
> ---------------------------------------------------------------
>
> # How far down we go with TOC's
> generate.section.toc.level       ( 3  )
>
> # Max depth in each TOC
> toc.max.depth                    ( 2  )
>
> # How far down we chunk nested sections, basically all of them:
> chunk.section.depth              ( 1  )
>
> # Don't put the first section on the same page as the TOC:
> chunk.first.sections             ( 1  )
>
> # How far down sections get TOC's
> toc.section.depth                ( 10 )
>
> # Max depth in each TOC:
> toc.max.depth                    ( 4  )

If these are different from existing defaults, then we'll have to test the 
existing libraries, and make adjustments as required.

> fo params
> ===========================
> John? These are fine?
>
> # Needed for FOP 0.2, set to zero for FOP-0.9!
> fop.extensions           ( 0     )
>
> # Internal?
> xep.extensions           ( 1     )

I think it may be possible to turn on both FOP-1 and XEP extensions, which 
should keep most folks happy.  FOP-0.2 is pretty awful!  I'll check this.

> # No indent on body text
> body.start.indent        ( 0pt   )
>
> # Margin size
> page.margin.inner        ( 0.5in )
> page.margin.outer        ( 0.5in )
>
> # Yes, we want graphics for admonishments
> admon.graphics           ( 1     )
>
> # pngs and pdf do not get along
> admon.graphics.extension ( .svg  )
> navig.graphics.extension ( .svg  )

OK. The user can override these in his Jamfile anyway, so I think they 
should probably be moved to fo.xsl.

> Internal
> ==============================
> This parameters will not be documented in boostbook docs. The
> rationale is to avoid param bloating that will surely confuse
> the user. If the user want to change this parameters, he will
> have to read DocBook docs.
>
>
> Internal html params
> --------------------------------------------------------------
> chapter.autolabel             ( 1   )
> css.decoration               ( 0   )
> use.id.as.filename            ( 1   )
> refentry.generate.name        ( 0   )
> refentry.generate.title       ( 1   )
> make.year.ranges              ( 1   )
> generate.manifest             ( 1   )
> chunker.output.indent         ( yes )
> callout.graphics.number.limit ( 15  )
>
>
> Internal fo params
> ------------------------------------------------------------------
>
> chapter.autolabel       ( 0      )
> refentry.generate.name  ( 0      )
> refentry.generate.title ( 1      )
> make.year.ranges        ( 1      )
> ulink.show              ( 0      )
>
>
>
> Unused params
> ============================
> These params will be removed
>
> doc.standalone          ( false )

What does/did that do anyway?  I know some folks are using it?

BTW, when/if you add docs for all this, don't forget to add a link to 
http://docbook.sourceforge.net/release/xsl/current/doc/ which is an 
invaluable reference for tweaking Docbook output.  The online book 
http://www.sagehill.net/docbookxsl/ is pretty useful too.

Thanks for persevering with this, John.