[boost-docs] [boostbook] Documenting and revising params

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[boost-docs] [boostbook] Documenting and revising params

Matias Capeletto
Hi!
I want to document BoostBook params. In the way I want to see if
there are no param bloating. Please read this list and
comment on the proposed changes. Thanks!


html params
=================================


General
-------------------------------------------------------------------

boost.root ( '../..' )

# These two are used in the all libraries mode
boost.header.root       ( $boost.root )
boost.include.libraries ( ''          )


Page style
-------------------------------------------------------------------
Boostbook support several kinds of pagestyle. We must ask our self
if all this options must be included. There are some very old
styles that no one uses now. IMO we have to leave only the few
ones people will use.

[[[[ current ]]]]

page.style ( 'website' ) [oo: 'textlinks']

(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' )


(b) __ textlinks params __
    The old style, many options here. We have to decided if we will continue to
    support it. (I do not know if it is generating valid XHTML, I have
    to try it)

    nav.layout ( 'horizontal' ) [oo: 'none' , 'vertical']
    nav.border ( 'none'       ) [oo: 'Boost'            ]
    nav.flow   ( Spirit'      ) [oo: 'none' , 'DocBook' ]

    boost.libraries ( 'libraries.html'                  )
    boost.image.src ( concat($boost.root, '/boost.png') )
    boost.image.alt ( 'Boost C++ Libraries'             )
    boost.image.w   ( 277 )
    boost.image.h   (  86 )


[[[[ 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') )

  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

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  )




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     )

# 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  )



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 )



King 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
[hidden email]
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
Reply | Threaded
Open this post in threaded view
|

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

John Maddock
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.


-------------------------------------------------------------------------
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
[hidden email]
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
Reply | Threaded
Open this post in threaded view
|

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

Matias Capeletto
On 6/19/07, John Maddock <[hidden email]> wrote:

> Matias Capeletto wrote:
>
> > (a) __ website params __
> >    The new style, based on beta.boost.org including GroupedLinks and
> >    Google search box.
> >
> >    grouped.links.chapters.show   ( 'false'          )
> >    grouped.links.sections.show   ( 'false'          )
> >    search.box.show               ( 'false'          )
>
> I might be inclined to turn these on by default.

Ok, me too. The only one that makes me uncomfortable is the sections
GroupedLinks, because users must provide a version of his own now. If
I can manage to automate the creation of the xml definition when
boostbook runs, then this worry will vanished.

>
> > [[[[ 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' )
> > + Lots of parameters

> > [[[[[ proposed ]]]]]
> >
> > Only html.stylesheet          ( concat($boost.root,
> > '/doc/style/boostbook.css') )
>
> Yep.

Great.

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

No, they are the same as before

> > fo params
> > ===========================
> > John? These are fine?
> >
> > # Needed for FOP 0.2, set to zero for FOP-0.9!
> > fop.extensions           ( 0     )
> > 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.

Ok.

> > # 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.

Good.

> > Unused params
> > ============================
> > These params will be removed
> >
> > doc.standalone          ( false )
>
> What does/did that do anyway?  I know some folks are using it?

I have no clue. It is not used anywhere! :)

> 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.

Agree. I have using both links a lot.

> Thanks for persevering with this, John.

The docs deserve it :)

King regards
Matias

PS: How we can check that my test of Strict XHTML validation are fine?
PS: Thanks to Daniel James, ie6 now support box-wrappers!

-------------------------------------------------------------------------
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
[hidden email]
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs