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

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

Hi,

see comments inline.


> >     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.
> I think that requirements need to be defined that will
> address portability.
Yes, you are absolutely right. However I can't see the only one
right solution and approach. Software projects have been developing
on so many platforms and environments that I am afraid there is
no only one solution. 
I think that we end up with at least a few scripts for the most important
systems and environments, like windows, unix, ant, maven, 
cgi script - suggested by Cameron and maybe some more.

The most general is cgi script, but it has limitations too.

> > 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?
> ENTITY Management can be part automated. See my
> explanation at this link
> http://www.oxygenxml.com/forum/viewtopic.php?t=156
I was talking about our style of entities use. They are placed in
documents in special kind of comments. And these comments are
removed during processing XML files. It is easy to accomplish this
on Linux, but difficult on windows due to lack of sed, grep
and very poor scripting language.

We use entities for project customization. For example when document
describes CVS repository location we use entitiy &cvs_url; and
in configuration file we can set proper url for particular project without
modifying XML file. So we have fully reusable documentation modules.

However entities cause some problems with editing tools like xxe.
To work around this we have temporally put them in comments.

The proper solution is to change XML editing tools or replace entities
with something different.
There is no good and free replacement for xxe, but we have found a
way to efficiently work with <xinclude> elements. 
As you have writen there is no good parser and processor for
<xinclude> yet. But Cameron found xinclude.xsl which works very
well for most basic <xinclude> cases. And it require only any good
XSL processor to use such as xalan, saxon, or even xslproc (which 
has <xicnlude> support builtin indeed).

> <xi:include> is still a problem. Most tools like xalan
> only have an experimental implementation. For parsing
> the same applies, see this link
> http://xml.apache.org/xerces2-j/faq-xinclude.html
> 
> ENTITY reference and xinclude need to be supported.
> First because of the above and second to provide
> backward compatibility to all the legacy out there.
See my above, comments.

> The problem is deciding on what level of granularity
> to apply to the modular concept. I will put together
> an article on this subject. It may serve as food for
> debate that may result in some recommendations. I say
Great!, maybe we will decide to make an IRC meeting for 
this purpose.

> Application examples include:
> 1. User Manuals for Software
> 2. User Manuals for Hardware
> 3. Product Descriptions
> 4. Reference Guides
> 5. Training Materials
> 6. Application Notes
> 7. White Papers
> 8. Tenders
> 9. Management Documents (ISO, PRINCE2, RUP etc)
> 10. 
> 11. the list is long ..
Yes, that's good idea.

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