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

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

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

No offense taken and none intended. I think we are
both talking about the same things. It's just that
many topics in one message makes life confusing for
all. May I suggest we tackle issues on a one message
thread per subject basis?

> 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 agree totally. I use both Linux and Windows. I only
refer to Java as it is the only way that I can see
100% portability in a single app. The alternative to
which there is no simple solution, is to have scripts
for Linux and batch files for windows. Or jscript for
Windows and Perl for Linux. etc. etc.

I am glad that you mention the different attitudes of
users, I will get back to this later.

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

Yes. The tool chain that creates a Publishing Model.
http://www.nwalsh.com/docbook/procdiagram/index.html

I am saying that the Publishing Model for GenerGuide
should be as generic possible. Allowing any
implementation of the tool chain to be capable of
producing an output from GenerGuide Sources. 

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

I like to see the processing tools as having
limitations. These prohibit the implementation of a
Publishing Model.

In my opinion we have to do with what is available and
works. Unless we are prepared to actually contribute
to the Xerces project and complete the implementation
of XPointer etc.

True full support will come alone in dues course. But
do you want to fight with it until full support is
provided? I would like to see it work with current
technology. Keep watching the emerging stuff and port
generguide when it becomes stable.

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

I agree with you. However, there are many free XML
Editors on the market
http://www.morphon.com/index.shtml
http://www.conglomerate.org

I can give a long list.

The point is that GenerGuide, as with your Java
scenario, must be able to work with any and all XML
editors, even the commercial ones.

We can certainly point the way to free or open source
tools and they certainly will reduce the barrier to
entry for people that want a solution with cost. Is
this the point of GenerGuide?

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

Yes. A Generic Guide "GenerGuide", that provides a
framework for authors to create documents. The
GenerGuide is like a cookie cutter. It enables you to
get started from a base template. 

Now for the modular documentation part. I ask a
rhetorical question, why do we need modular
documentation?

Is it because we want a higher level of reuse or is it
because we want greater flexibility to include and
exclude ingredients from our cookie. The cutter will
stay the same shape. But the cookies will taste
different.

I think it is both. There are more reasons, but lets
just stick with that.

So, in my mind I see GenerGuide as a cookie cutter. It
does not change shape. I must add ingredients to make
the cookies taste good or have a brown color instead
of straw. Chocolate vs. Vanilla.

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

Yes, I do agree with you. But we are not yet in the
future. All we can do is prepare for it. In the
interim we should be able to have a working version
with todays technology. There is no point fighting it
unless we are prepared to develop the tools in the
chain ourselves. This is not an option. I think we 
need to aggregate the functionality of all the tools
an focus on what is possible with the common. Yet stay
flexible to move rapidly into new territory as it
becomes available. hence the current release will be
stable and the dev release will be new territory -
hold onto your hat!!

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

Yes. I agree. Variables can be provided for. You can
do this in the ENTITY or make an XSL that provides
global parameters or fetch the variables from XML
files during the XSL. The method of implementation
will work which ever way.

All I would like to see is that it is standard.
Currently generguide needs special handling in order
to make the input acceptable to the processor. Without
it, the processor would throw an exception.


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

There is no simple answer. If there was everyone would
be doing it. We are faced with challenges. That's what
I like about the project.

My only concern is that the move to XInclude was
prompted because of an Editor (XXE) that is broken. If
it was made at a time when tools like Xerces, Saxon,
Xalan etc had support for it. I don't think it would
be a problem. The fact today is that only xsltproc
supports XInclude.

My think tells me. If it's not broken, then don't fix
it. ENTITY methods work. XXE does not.

Yes XInclude is the <emphasis>future</emphasis>. But
it is not yet the <emphasis>now</emphasis>. So if you
ask, "What should be in a release?" I say ENTITIES.
Lets give XInclude some time.

> 
> 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.
> 
The problem is not your solution. It works. I just
think that we should be careful how we address things.

Most of the authors I know are not technical. Give
them ANT and they get a blank look in their eyes. Talk
MAVEN and they fall asleep. Tell them they must run a
sh or a bat from the command prompt and they laugh at
you. They have been using commercial tools like Word,
RoboHelp, HDK etc. to do their authoring. They are, as
you said before more comfortable in a WYSIWYG tool.
Many feel that editing in the source is taking a step
backwards in time. All these years they have dreamed
of the perfect WYSIWYG tool, no we want to take it
away from them.

Do we set a standard. In some respects yes. In others
no. When it comes to tools and their technological
functionality. I think NO. When it comes to a
Framework that works with most Publishing Models, I
think YES.

Where I think GenerGuide can help is to provide, not
only the framework, but also tools or an application
that addresses the weaknesses present in the tool
chain and XML Editors. Start with automation of
command line tasks using GUI. Then authors will be
happy to use GenerGuide. Don't ask them to run ANT,
MAVEN and a hold suite of other applications. The tool
chain is mind blowing enough for them.

Look forward to you response.

Sean Wheller

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