Documentation source repository tightly coupled to tools folders

[GoogleCodeExporter]

The current structure of the docs portion of the repository currently has 
placeholders for the tools required to build the doc (xsltproc, fop, docbook 
dtd and style sheets, ...). The various style sheets used in the documentation 
bundle expect to find the basic style sheets used by the tools in this 
directory structure, and the build script expects to find tools executables in 
this structure also..

This complicates working on multiple sandboxes at the same time, because the 
tools have to be copied in each sandbox. Moreover, when trying to build the doc 
on linux (where docbook and other tools are supported more naturally), you 
don't have control over where the tools are installed, they install in standard 
places (tools in usr/bin, stylesheets in usr/share/xml, ...).

I can appreciate the value of the current approach to control the dependencies 
between our documentation bundle and the tools, but I'm betting there is a way 
to code a flexible build script that can accommodate the various scenarios 
(e.g., tools and style sheets inside or outside the documentation bundle folder 
structure).

I will start working on such a script, and perhaps this will require extra 
style sheets in the various styles folders, because the paths to the style 
sheets are currently hard coded in the files in the styles folders. Perhaps 
there is a way to define the root of the various style sheet folders in the 
build script and pass these values to the tools and style sheets that use them, 
I don't know for now.

Original issue reported on code.google.com by rcham...@gmail.com on 25 Oct 2010 at 7:00

[GoogleCodeExporter]

I found an interesting compromise: deploy the tools (xsltproc, fop) outside the 
project's documentation folder structure, but still deploy the docbook-xsl-ns 
stylesheets in the docs/docbook folder. Otherwise, we currently need to change 
six stylesheets (two each in docs/dataAccessGuide/styles, 
docs/dataMapperGuide/styles and docs/tutorial/styles) to reflect changes in the 
path that holds the stylesheets.

One way to reduce the coupling between "our" six stylesheets and the ones 
imported from docbook would be to do something similar to what we do with the 
XSD files in the appendix of the doc: put a placeholder in the XML file and 
substitute its value during the build process. This way, we could define the 
path to the stylesheets in the build script, and the stylesheets would 
automatically be adjusted during the build. If this works, mybatisnet doc 
source and location of tools and stylesheets are only coupled through the build 
script, which I find much better than the current situation.

Feedback is welcome.

Original comment by rcham...@gmail.com on 26 Oct 2010 at 12:05

[GoogleCodeExporter]

[deleted comment]

[GoogleCodeExporter]

While we're at it, the "modern" way of validating XML seems to be through 
schemata, rather than DTDs. Two issues here:

1) should we use a docbook schema instead of DTD (I am unable to decide in a 
meaningful way, as I don't know what this implies in terms of parsing speed, 
"robustness" of the validation, ...) ?

2) Currently, the path to the docbook DTD in our source files points to a local 
file in the repository structure. Would it make sense to use the DTD (or 
eventually schema) over the network (e.g., URL pointing to OASIS web site)? 
Once again, I don't know what the trade-offs are. This would further reduce 
coupling between mybatisnet doc source and the required dependencies, IMHO, 
assuming the OASIS site is probably reliable.

Feedback please! Thanks in advance!

Original comment by rcham...@gmail.com on 26 Oct 2010 at 1:18

[GoogleCodeExporter]

Following e-mail exchanges we had this morning, my "compromise" solution seems 
to have potential. I will work on implementing this in the ibatis-1-maintenance 
line with the same version of docbook we currently use (4.1.2), as I tend to 
make changes incrementally, and the docbook version issue is all but clear 
right now. I will also update the READMEs regarding the installation of the 
tools (windows for now, linux will come eventually if deemed useful). I will 
keep the placeholder folders, which will only contain these READMEs.

Original comment by rcham...@gmail.com on 26 Oct 2010 at 3:19

[GoogleCodeExporter]

I've committed incremental changes throughout the day. I added styles and dtd 
folders in the docbook placeholder (will ease eventual migration to docbook 5 
and ressem,bles a typical setup on linux), and actually added the DTD and its 
dependencies in docbook/dtd.

For the stylesheets bundle however, this yields a large set of files (almost 30 
Mb), so I created the styles placeholder folder and adjusted the REAMDE.html in 
docs/docbook.

Instructions for FOP and xsltproc were also updated.

I think we could get rid of the xsltproc and fop placeholder folders, and 
include the instructions to get them directly in docs/README.html. I also 
suggest we "can" the remaining readme.txt files, if everyone is comfortable 
with the README.html files (currently they are redundant, I prefer the HTML 
versions myself).

Feedback on this proposal would be appreciated.

Original comment by rcham...@gmail.com on 26 Oct 2010 at 8:19