One of the benefits of using docbook to maintain the help handbooks is the ability to
export to different viewing formats.
Trinity inherits a handful of KDE3 xsl stylesheets that should help us dynamically create
online copies of any help handbook.
Ideally, we generate the output nightly of any document in GIT we want at the web site.
Of immediate interest we want to provide a copy of our FAQ in html format for the web
site. I'm updating that document but an old copy may be used to help learn how this
process should work.
I fiddled with the xsl stylesheets, but I'm missing the big picture how all of this is
supposed to flow.
Although there are several stylesheets, there are only four fundamental stylesheets.
On an installed system they will be installed at:
$PREFIX/share/apps/ksgmltools2/customization/.
The primary stylesheets:
/opt/trinity/share/apps/ksgmltools2/customization/kde-chunk-online.xsl
/opt/trinity/share/apps/ksgmltools2/customization/kde-chunk.xsl
/opt/trinity/share/apps/ksgmltools2/customization/kde-nochunk.xsl
/opt/trinity/share/apps/ksgmltools2/customization/kde-web.xsl
kde-chunk.xsl is the default stylesheet and the one used to generate the handbooks when
compiling the packages.
Read about the stylesheets here:
$PREFIX/share/apps/ksgmltools2/customization/README
The next trick in the process is the meinproc command. This command validates the
integrity of the docbook files as well as use a stylesheet to generate an html page.
The basic command looks like this:
meinproc --check ./index.docbook -o /var/adhoc/faq.html \
--stylesheet /opt/trinity/share/apps/ksgmltools2/customization/kde-nochunk.xsl
For purposes of the web site, the only stylesheet that I have had success is the
kde-nochunk.xsl stylesheet, yet even that is not 100% successful. Many of the links in the
resulting html are broken because related docbook files are not being converted to html. I
need to figure out how to tell the process where to find all of the common images are
located as well. I suspect to generate a functional FAQ for the web site we'll need a
script to generate all of the necessary pieces in the correct order.
To avoid contaminating your Trinity installation or GIT sources, copy the tdebase source
tree to a working directory. Then, for example, cd to tdebase/doc/faq and run the
following command:
meinproc --check ./index.docbook -o $WORKING_DIR/faq.html \
--stylesheet $PREFIX/share/apps/ksgmltools2/customization/kde-nochunk.xsl
where $WORKING_DIR is the location where you copied the tdebase sources and $PREFIX is
where Trinity is installed (commonly /opt/trinity).
When experimenting with meinproc, know that when the -o switch is not used that all html
files will be generated in the current directory.
I have not figured out how to use the -o switch to automatically generate all required
html files to another location. When I use the -o switch only the parent html file is
generated in that location. I have to omit the -o switch to generate all of the html files
and then mv them elsewhere.
Once we get this all figured out we can document the process in etherpad and then write a
script to automate this process.
I appreciate any help. :-)
Darrell
Show replies by date