Note
The following section is only meant for the maintainers that work on the core layout of the official Phing manual and is not necessary for developers adding documentation for new tasks of improving documentation for existing tasks.
Furthermore, by necessity this assumes a rudimentary knowledge of Docbook5 bubild process and what XSL and CSS stylesheets are. It is not possible in this short space to give a full description of that setup.
XSL Customization layer
All DocBook5 renderings are started from one of the customized XSL stylesheet
under "stylesheets/xsl
" . All commonly adjusted properties should
go into the appropriate stylesheet for that rendering. No properties should be
passed on via the command line. To keep the customization layer as future proof as
possible only in very rare circumstances should any cores XSL templates be copied
and modified. As usual the recommended way is to use the provided hooks.
CSS styelsheets
The CSS stylesheets are used to create the look & feel for the HTML based renderings. These are entirely standard CSS files which by design are kept very simple. It should be noted that a few styling option depends in turn of the modified XSL transformations in the XSL customization layer. This had to be done in order to gain some more detialed control not provided by DocBook5 out-of-the-box.
Webhelp
The webhelp
output rendering is a bit of a special case. This
rendering depends not only on DocBook5 but also on Java as well as Ant build
processor. These dependencies are inherited from the official DocBook5 webhelp
process and will remain. Unfortunately adjusting the look & fell for this
rendering is not as simple as for the other outputs since a fair amount of the
layout (as well as look & feel) are hard-coded in the Webhelp build system.
While it is perfectly possible to adjust the hard coded values and design choises it
is not future proof. Since the Webhelp rendering is the newest and fastest improving
output from DocBook the intention for the Phing documentation is to track these
improvements and not spend time ourself to duplicate this effor with a parallell
development.