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

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

--- Artur Hefczyc <ko...@pl...> wrote:
[snip] Implementation Problems
> 
> 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.

I think that requirements need to be defined that will
address portability.

> 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

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

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

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
recommendations, because I think that granularity is
not 100% under our control.

> 4. No documentation how to use it. I mean how to use
> configuration files and how
>     to set them up.

Yes, a Generguide User Manual would be good. I will
start working on this, but I am also just beginning to
find out how all the parts hang together.
 
> > 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.

It is very wise to create a high-level
guideline/recommendation (the technique) and then have
application specific projects. The guideline should be
as generic possible to ensure scalability across
applications (projects).

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 ..
 
[snip] generconfig web editing tool.

> > 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 constantly 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 support almost useless.

Scripts or utils provided must be portable.

> I can see now, it is not good that I try to
> implement all features at once. [snip]
> 
> > 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
> <xi:include> elements?

Again, xi:include is experimental. So it should be in
generguide.

[snip]

 
> > 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
> locally.
> They can be kept locally 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?

The track sounds right. But I think that the
requirements etc need to be stable before investing so
much time is developing tools. Once stable, then the
wish list can be attacked.

> > At what point should we announce 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.

The more help the better. On the downside, without a
stable recommendation, it will be chaos.




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