forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "J.Pietschmann" <j3322...@yahoo.de>
Subject Stylebook transition
Date Sun, 23 Jun 2002 18:13:12 GMT
Hi,
I'm currently reorganizing the FOP docs. The actual
version uses stylebook. I thought I replace this by
Ant's style task. This proved a bit more complicated
than expected, because of the transformation pipelines.

General questions:
- How are users building Apache software at home from
  scratch supposed to generate documentation? Using
  Cocoon CLI seems to be a bit large to expect.
- Should projects always provide prebuilt HTML even in
  sourcce distributions?
- Should projects provide XDocs in binary distributions?

Apart fron this, I ended up with the following Ant target:

   <target name="html-fop" depends="prepare-docs">
     <mkdir dir="${build.htmldocs}"/>
     <copy todir="${build.xdocs}">
       <fileset dir="${xdocs}"
         excludes="**/changes*,**/contributors*,**/faq*,**/howto*,**/todo*"/>
     </copy>
     <style basedir="${xdocs}"
       destdir="${build.xdocs}"
       includes="**/changes*.xml"
       extension="xml"
       style="${xdocs}/dtd/changes2document.xsl"/>
     <style basedir="${xdocs}"
       destdir="${build.xdocs}"
       includes="**/contributors*.xml"
       extension="xml"
       style="${xdocs}/dtd/contributors2document.xsl"/>
     <style basedir="${xdocs}"
       destdir="${build.xdocs}"
       includes="**/faq*.xml"
       extension="xml"
       style="${xdocs}/dtd/faq2document.xsl"/>
     <style basedir="${xdocs}"
       destdir="${build.xdocs}"
       includes="**/howto*.xml"
       extension="xml"
       style="${xdocs}/dtd/howto2document.xsl"/>
     <style basedir="${xdocs}"
       destdir="${build.xdocs}"
       includes="**/todo*.xml"
       extension="xml"
       style="${xdocs}/dtd/todo2document.xsl"/>
     <style basedir="${build.xdocs}/fop"
       destdir="${build.htmldocs}"
       includes="*.xml"
       style="${skin}/stylesheets/document2html.xsl"/>
   </target>

This seems to be rather verbose and redundant. At least,
the naming conventions fit.

Question:
- Is it a good idea to tie processing to document name
  conventions?
- Alternative ideas?

I could probably use Ant <echo> to simulate Cocoons directory
generator and do something useful with it.

Further questions:
- What is the canonical directory structure for xdocs?
  changes, todo, contributors, faqs, howtos, specifications
  (what is the intention for this?), other documentation.
  Should subdirectories represent a project structure and
  have their own changes, todos etc? Should subdirectories
  represent document categories?
- What skins are projects supposed to distribute?
- What is the default skin (unless the project decides to
  build its own skin, of course)?

J.Pietschmann



Mime
View raw message