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

[Sean W. <se...@ya...>]

--- Artur Hefczyc <ko...@pl...> wrote:
> > >     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.

Other than standardizing on JAVA and programming the
functionality of any scripting into the app, I don't
think that there is a standard solution. If the route
is to dev an app that performs the operations, then it
will be easy for most users to start using generguide.
In addition, it could serve as a plug-in to a number
of other Java based editors jedit, oxygen, XXE,
Morphon etc. This would obviate the need for people to
have to learn another editor. The learning curve will
be limited to the Java App.

> > > 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 entity
> &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 written 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).

In my opinion, tools like XXE are broken. The best way
to author XML Documents is directly into the source
view. The WYSIWYG and Single-Source concepts are on
opposite ends of the same boom stick. If you try to
bring the end together, the stick will break.

CSS views work fine in the document is not modular.

Regarding entities. Your application of entities is
not standard. Therein is a problem. It is safer to
apply standards. In addition, entities have many
applications. You may use them for project
customization, but others use them to build modular
documents. I don't think it wise that generguide's
application of entities be limited. As I said before,
the scope needs to widen and the recommendation should
be more generic. If this is not done then the
flexibility of generguide will be limited.

> 
> > <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.

DITTO

> 
> > 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.

I am glad you like the idea. I hope that you also
realize the implications. If generguides requirements
fail to be generic, each of these applications will
test their integrity. If any of them break the
recommendation, them we will be faced with making
changes, rethinking whole concepts. As the number of
applications increase, the overhead will also
increase. Changes to the recommendation may also
violate the integrity of legacy applications,
requiring them to be modified to be inlinin-line the
new geneguide recommendation.

In my vision I see that an application must conform
100% to the recommendation, but that it may have
extensions to cater for application specific
senscenariosf all applications have a common
extension, then it should not be an extension. Rather
a part of the core recommendation.

This approach will make it much easier for new members
to start projects. It will also reduce the learning
curve for people wanting to use generguide. Once they
understand the core recommendation, they only have to
learn the extension for the application(s) they want
to use.

This is why I stress, standardized approaches and
stabilization of the generguide recommendation before
work begins on application specific projects.

Hope I am not going to far at a tangent.

Sean Wheller

__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com