Re: [generguide-devel] Changes...

[Cameron S. <ca...@sh...>]

On Monday 01 Sep 2003 6:36 am, Artur Hefczyc wrote:
> 1. Added support for CATALOGS to generpublish.sh script
>    (it works if you start it with option '-k')
Should we include CATALOG files into the generguide repository, then 
generguide.sh can use CATALOGs without needing a user to set them up 
themselves?
Ie, the "generguide -k" option could set the CATALOG variables itself.

> 2. Documentation for using xinclude.xsl with java tools has been written.

Cool.  It is good to get all this information down.  I think that it currently 
contains too much detail and that we need to revisit this and simplify it, 
possibly by writing wrapper scripts which hide most of the options from the 
user.

> 4. Well, the last one, but not the less important. I have changed XML
> prolog in all our guides to following form:
>   <!ENTITY % xinclude
>     PUBLIC "-//GenerGuide//ELEMENTS XInclude for SDocBook V1.0//EN"
>     "http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
>
>     The one, most important consequence is, when you will be processing
>     documentation xinclude.mod have to be loaded by processing tool.
>     Because it is located on the web site you should note significant
> increase of time necessary for processing.
>     But benefit is that you don't need to worry about having this file on
> your disk in proper location when you are editing XML documentation.
>
>     But before you start to hate me for wasting your time with waiting
>     forever until processing will finish I give you tip how to avoid
>     downloading xinclude.mod (and sdocbook DTD) each time file is
>     processed.
>
> 1. Set environment variable similar to main below:
> export
> SGML_CATALOG_FILES="/sgml/catalog:/sgml/dtds/sdocbook-1.0/sdocbook.cat" 2.
> Put attached catalog file in place pointed by above variable and
> sdocbook.cat in directory where you have simplified docbook dtd.
> (If you have)
> 3. Look in catalog file and ensure that it points to correct xinclude.mod
> location on your HDD.
> 4. Always start generpublish.sh with '-k' parameter.

As mentioned above, maybe we should wrap above processing into the 
generguide.sh script.

> There is document in our guide/ directory describing this matter a little
> bit - - basicxml.xml - which is not included in developersguide.

This is good stuff.  It would be good to incorporate it into the developers 
guide.
I invisage that we will eventually have one huge repository for all sorts of 
business processes.  From this repository we will build guides that are 
relevant for the project we are working on.
Eg: Java Developers Guide
XSL Developers Guide
Tips on Buying Property
How to write a newspaper

and so on.

>
> On the other side I saw (and worked according this rule) that you have
> added xinclude declaration to all XML files. However it is necessary only
> where it is used, so it could be removed in many files what can speed
> processing up. (Not too much if you use xinclude.mod from your disk).

OK, good idea.

>
> It seems to me that I have even sent you description how to set/use
> catalogs under xxe.

Yes, however I still have not been bothered setting it up.  I'm yet to be 
bothered by not having it.  I know you keep trying to convert me.  :)


-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com