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

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

Hi,

Sean, it seems to me that there is some misunderstanding
because you don't know full story of some of our solutions
or just we are talking about different issues.
Please, let me explain some general matters and than we can
start discuss details again.

And one another thing. English is not my native language
so please be patient and don't feel offended I have no intention
to do so, it can be just my poor English.

1. Documentation processing:
    I hope we target java and non-java projects, so we should have
    at least ready to use java tools and non-java tools. I take part
    in both kind of projects and from my experience I know that
    these are two separate worlds:
    Java developers prefer to use java-only tools and environment, however
    non-java developers hate to use any java applications. They want
    to have nothing to do with CLASSPATH, installing JDK and
    all related matters.
    So I can see at least 2 concurrent lines of documentation processing tools:
    - Java
    - non-java
    I am thinking only about XML processing tools, not editors. When I speak
    about XML processing I mean, transformation all source XML files into
    chosen target format (one HTML file, multiple HTML files, PDF, and so on...)
    
    These tasks are not too complicated indeed so implementation and
    maintenance of two separate lines should not be too difficult.

    # So problem is: XML processing tools...

2. Editors: 
    Personally I count myself as a man who has big XML knowledge and
    I use emacs in my whole development work, both programming and
    XML documentation. Probably you are much better than me in XML
    matter. 
    However I hope we target also developers with much fewer (if any)
    XML knowledge. They need to use WYSIWYG or WYSIWYM
    editors, at least at starting point. So our environment should be
    prepared to use it with both kind of editors. It even seems to me
    that visual editors are even more important because users like we 
    have enough knowledge to solve most problems with XML issues, on
    the contrary to beginners who just give it up.

    So we should also be aware of limitation visual editors have.

    Xxe is the only free editor I know but as you said it is broken and does not
    allow to work well with entities for example.

    # So problem is: XML editing applications proposition (free is essential)...

3. We want to provide framework for modular documentation. So you
    can build guide for your project from existing blocks and add some
    more bocks, specific for your project.

    As you said entities were mostly used for parting documents. However it
    seems to me they were used for this task in the past because of lack of 
    better option. They have, however, a few important limitations and it is worth
    to look for better approach.  First of all system entities can not have DOCTYPE
    declaration so therefore they are not valid XML documents and working with
    single entity file is more difficult - no validation, no context prompt.

    <xinclude> was invented just for modular XML documents. It has poor 
    support yet but we can expect that it will be better in short future. I think it 
    is promising solution. And we have working tools for our simple needs for now.

    Maybe you have just another idea how to manage modular documents...

    # So the problem is: XML modular documents...

4. We want to have reusable documents from one project to another. I mean 
    we have a couple of XML files which can be used to build instruction for 
    developers. But some elements in these documents should be changed regarding 
    to project: project name, site address, manager name and so on.

    Than we need some customization for documents. Our solution was entities 
    and we can define values of entities specific to particular project to 
    generate documentation for this project.
    Because of problems with entities and xxe we started to consider to
    use <xincude> for this task too. Moreover <xinclude> offers us a few
    nice features which add more flexibility to documentation customization.
    For example keeping project customization in one XML file instead of
    in a few entities files (some entity values have to be kept in separate files 
    i. e. longer license note, structural list of developers).

    Maybe there is some better option for this about you know...

    # So the problem is: XML documents customization...

Final note: it is good to know that my solution is not good, have some
limitations or it is not standard, however I can switch to another approach
if only there is any better one. Many things we are doing here are not 
standard just because this is partially new area and probably we have
to set a few new standards.

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