[generguide-devel] Re: What should be in the first mapbuilder release?

[Artur H. <ko...@pl...>]

Hi,

I try to introduce now generguides in my company. At the time of doing this
I came across a few problems. They are not difficult to solve, the more
I am member of generguide team, but they are a little bit annoying.
They can be more annoying for someone completely new to this idea.
So I think they should be solved in some way, before alpha release.

1. Working with documents on windows. I am talking about generpublish
    script. For many windows users it is not easy to accept they need to 
    install something like cygwin to generate target formats of documentation.
    So providing any, even simple and basic, tools for windows+java is
    essential. However due to windows command line limitation I think
    that can be simpler to create good maven support than writing some kind
    of generpublish.bat script.
2. Commented entities are difficult to work with, but it is closely associated
    with above windows limitation. However as I remember we were talking about
    change them to <xinclude> elements. Are we ready to do it?
3. I had to create separate document about development tools and another
    about development conventions. But this two issues are not well separated
    in our guides set. It is not essential for alpha or even no. 1 release, but it would
    be good to think about writing sections targeting only one issue. So we have
    much more flexibility during building final document.
4. No documentation how to use it. I mean how to use configuration files and how
    to set them up.

> If so, then it may be appropriate to split the generguide into 2 projects:
> 1. Just the tools to process modular documentation, along with any standards 
> or convensions we need to enforce.
> 2. The text of the Software Developers Guide.
Yes, that is good idea for splitting project into parts, however details are not
clear for me yet.

> This leads me onto our developement path.
> Here is what I see needs doing:
> 1. Develop a generconfig web editing tool.  (Done by me for filtering 
> sections).
Yes, it is very important in my opinion.

> 2. Get publishing working within maven.  Not essential since we have the unix 
> scripts which work (generpublish.sh), but it would be nice to have.  Artur, 
> have you been working on this?  If so, how is it going?
It seems to that it is also very important to target wider developers community.
I still work on this, however I contantly come across problems with implementation
details which block me from finishing it, like xalan+JDK1.4, xpointer implementation
in xalan and saxon, and many small things which seems not very important but they
make maven suuport almost useless.

I can see now, it is not good that I try to implement all features at once. I should
release first version first, which have some limited support but works for basic cases
and than try to extend it with next features.

So I will try to prepare first basic maven plugin for sdocbook, which support
simple modular documentation in next few days.

> 3. Define variables (like  entities) within generconfig so that they can be 
> used within XXE editor.  I plan to work on this next.
Does it mean you want to replace entities with <xinclude> elements?

> 4. Incororate variable editing in the generconfig web editing tool.
> <Release 0.3alpha>
Could you say what you mean when you are talking about 'variables'
please at last a few words to ensure me that we are thinking about the same.

> 5.  Introduce concept of GenerRepository.  Allow generconfig to reference 
> sections from other GenerRepositories.  Need to address versions, copying 
> images, sections from different repositories having the same id.
Well, I was thinking about building document from sections with following
<xinclude> use:
<xi:include href="http://generguide.sf.net/guide/versionnumbers.xml"/>
I mean to reference parts from source, web location and not from local
file system, to not force user to keep all files localy.
They can be kept localy to speed processing up, but main reference should
be to source location.

> Have I missed anything?  Sean, I assume you will have ideas I have not thought 
> of. Am I on the right track?
> At what point should we annonce this project to related email lists in order 
> to attract attention?
I think we definitely need users to see if we are going in right direction.
At least we should be first users to ensure that it is useful what we are providing.

I try to introduce this in my company, however we are going to implement 
extreme programming idea and documentation issue is not that important.
So it will not be used extensivelly.

But generguide project should use itself tools which it provide. So at least
we, in generguide project, should be first users. And I think we will be ready
to release any version if whole project documentation will be generated
with use of our tools.

Artur
-- 
Artur Hefczyc
Open Source Developer
http://generguide.sourceforge.net/
http://www.geotools.org/
http://wttools.sourceforge.net/
http://maven-plugins.sourceforge.net/