Re: [generguide-devel] Re: I've created Generic Guide project

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

On Thursday 19 Jun 2003 4:35 pm, Artur Hefczyc wrote:

> > This avoids the need for XSLT.  However I'm possibly avoiding XSLT
> > because I don't know enough about it and am going with what I know
> > instead.

> So as I can see the use of XSLT in our project can not be that easy
> and comfortable.
>
> For example lets assume we want to be able put, somewhere in
> generic guide, information about license type used (i. e. in geotools
> project).
>
> To be able to do it with XSLT we should have (choose) some tag which
> could be replaced with license information for existing project.
> The one option is to use tag existing in sdocbook (or even full DocBook)
> which probably can be in a conflict with other uses of this tag.
> But it is easy to use, our editors will work with it without any problems.

I'm not comfortable overloading any of the docbook tags.  The tags are there 
for documentation rules and is likely to confuse users in the future.

>
> Or another option is to define our own tags set (something like
> xinclude.mod) which could be used as sdocbook extension. So these special
> set of tags can be used for many necessary things in genericguide project
> docs. And than these set of tags can be processed in first stage to replace
> them with necessary text with standard XML tags and then such files would
> be directed to common XSLT processing to transform them to output format.
> However it will be something like creating new standard what is not bad in
> general but can generate some difficulties at beginning.

Again, if we can avoid this then that would be good.  I don't want to maintain 
a new XML standard and continually have to update to incorporate the latest 
docbook format.

>
> In my documents I used third approach, the easiest to use but without
> future. I put special comment strings in XML code and they are replaced,
> by shell scripts, with XML tags and text before they are directed to
> further processing.
> It is similar approach to second option. And can be used before full
> implementation of second option. Comments can't hurt our XML text
> and in future they can be changed to XML tags.

This is getting closer.
I think the solution that is being used at the moment is even simpler.  I'm 
not sure if you have understood what I've proposed.  You might want to look 
at:
http://generguide.sourceforge.net/usersguide.html
and the build.sh script.

What I'm proposing is that the user creates their own .sgml files which will 
overwrite the generguide.sgml files.

For instance, if we want the generic guide to reference "project name", then 
in all generguide documentation we use:

For the <xi:include href="projectname.sgml"
  xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> project, we ...

Do you think this is a reasonable solution or does it have some problems?

> > I put it here to ensure the build.sh script works.  The users computer
> > might not have xslt installed.  I was trying to ensure that there is
> > minimal configuration required to get generguide working.
>
> I understand now. I try to use the latest version to see if there are
> really worth differences to replace existing version.

OK.



> For now I started to use convention that 'id' value starts with file base
> name (what is usually close to section title) and the rest is some
> identification string.

That sounds good to me.  Although I suggest we just make this advice rather 
than a hard rule.
For instance, when talking about JUnit within the Unit Test section, "junit" 
is quite unique and probably doesn't need "unittestjunit" as an id.

> > Tasks:
> > If you are looking for something to do, I'd suggest going through each
> > section and doing the following:
> > 1. Restructure to above format.
>
> It could be useful to have files list and have checked files already
> cleaned. Also it could be useful to avoid in some way to work together
> on the same file.

Yes, ok.  Would you like to create that file?  Maybe 
"generguide/guide/todo.txt"

It probably won't be too much of an issue if you check all your code in at the 
end of the day and I do the same since we are working in different time 
zones.


> > 3. For sections that are geotools specific:
> > 3.1 make a copy of the section in the geotools repository, say
> > geotools-src/docs/localdevelopersguide/
> > 3.2 Either remove section from generguide or replace with CAPITALISED
> > GENERIC WORDS which will need to be edited later by specific projects.
>
> Not fully understand this yet, so I will leave it for later.

OK, I'll see if I can set up an example in the next few days.

> I have a couple of new sections about emacs and XML. I can add them (if I
> can) to CVS repository. I think it would be useful to finish XML section as
> soon as possible, because it could be helpful for our XML work.
> I mean - document about joining separate XML files, efficient DTD use
> from local directories instead of from location given in XML prolog,
> validating and other XML processing and  so on.
> If I find enough power it is possible to have it ready for tomorrow.

Sounds good.

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