generguide-devel — Discussion for developers of generguide

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/

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

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/

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

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

> > 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.
> Agreed.  Are you working on this?
I created very simple windows script for geotools project and I think I can
generalize it for generguide needs a little bit after first release of maven plugin.

> Another option is to put the generpublish.sh script inside a CGI wrapper and 
> make it accessable via the web.
> Ie: Allow user to upload a generconfig.xml file, user can then edit the config 
> file, user can then download the config file, or a zipped Developer's Guide.
Yes, I think it is very good idea. It would be the most portable solution.
But maybe it is not mandatory for release no. 1.0

> I'm wondering whether we should announce the existance of our project before 
> we consider it ready to use so that someone else doesn't start a similar 
> project.  Also, by announcing our project early, we may attract developers 
> and users (like Sean) who can help define what needs to be done, and help us 
> get there.
Yes, I think it can be good move. Users or even quests feedback is the most 
valuable for our work.

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

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

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

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

Hi,

I try to introduce now generguides in my company. At the time of doing this
I came across a few problems. They are not difficult to solve, the more
I am member of generguide team, but they are a little bit annoying.
They can be more annoying for someone completely new to this idea.
So I think they should be solved in some way, before alpha release.

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.
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?
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.
4. No documentation how to use it. I mean how to use configuration files and how
    to set them up.

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

> This leads me onto our developement path.
> Here is what I see needs doing:
> 1. Develop a generconfig web editing tool.  (Done by me for filtering 
> sections).
Yes, it is very important in my opinion.

> 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 contantly 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 suuport almost useless.

I can see now, it is not good that I try to implement all features at once. I should
release first version first, which have some limited support but works for basic cases
and than try to extend it with next features.

So I will try to prepare first basic maven plugin for sdocbook, which support
simple modular documentation in next few days.

> 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 <xinclude> elements?

> 4. Incororate variable editing in the generconfig web editing tool.
> <Release 0.3alpha>
Could you say what you mean when you are talking about 'variables'
please at last a few words to ensure me that we are thinking about the same.

> 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 localy.
They can be kept localy 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?
> At what point should we annonce 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.

I try to introduce this in my company, however we are going to implement 
extreme programming idea and documentation issue is not that important.
So it will not be used extensivelly.

But generguide project should use itself tools which it provide. So at least
we, in generguide project, should be first users. And I think we will be ready
to release any version if whole project documentation will be generated
with use of our tools.

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

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

[Cameron S. <ca...@sh...>]

Hi,
Sean has made me think about the scope and direction of the generguide project 
a bit.
In particular, are we limiting ourselves by focusing generguide on "Business 
Processes"?
Are there other forms of documentation that would benefit from this modular 
approach?  Sean, do you have one or two examples?

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.

In future, other purely documentation projects can spring up independantly of 
generguide (except that it uses the generguide tools).  For want of a better 
word, these projects could be called GenerRepositories.  GenerRepositories 
can reference each other in a similar manner to web pages referencing each 
other.

This leads me onto our developement path.
Here is what I see needs doing:

1. Develop a generconfig web editing tool.  (Done by me for filtering 
sections).

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?

3. Define variables (like  entities) within generconfig so that they can be 
used within XXE editor.  I plan to work on this next.

4. Incororate variable editing in the generconfig web editing tool.

<Release 0.3alpha>

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.

6. Incorporate into generconfig web editing tool.

<Release 1.0beta> ???

-------

Have I missed anything?  Sean, I assume you will have ideas I have not thought 
of.

Am I on the right track?
At what point should we annonce this project to related email lists in order 
to attract attention?

-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

[generguide-devel] Just SF mail system test...

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

Due to some problems with mails on SF
I am sending this letter to test if it works for me.

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

[generguide-devel] filters from config file now being processed by generpublish.sh

[Cameron S. <ca...@sh...>]

On Monday 08 Sep 2003 8:51 pm, Cameron Shorter wrote:
> After a large amout of time wrestling with XSL, I've finally got
> xinclude.xsl to selectively merge sections based on the @filter attribute
> in the configuration file.
> The filter attribute can be:
> * BLACK : include this node and all child nodes (unless specifically
> excluded).
> * WHITE : include this node, but not the child nodes (unless the child node
> is BLACK or WHITE)
> * EXCLUDE : don't include this node
> * DEFAULT or <undefined>: Inherit filter value from parent.
>
> I will eventually write this up in the user guide and design.
> I now plan to finish the generconfigform.html which provides a html form
> for editing the configuration file.

-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

Re: [generguide-devel] Proposal to add Sean as a developer

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

> We have not developed procedures for the management of members in the 
> generguide project.  I suggest we use the same process as we use in Geotools 
> (and is documentated in 
> http://generguide.sourceforge.net/developersguide/developersguide.html#teamorg 
> ).
of course +1


> I suggest that Artur and I are part of the Project Managment Committee, if 
> that is ok with you Artur.
of course +1

> Sean sounds enthusiastic and suitably over qualified.  I propose we ask him to 
> join us a a developer.
> Artur, is that ok with you.
of course +1

> Sean, would you like to join us?
I would like to ask you to say something about your skills. I have idea about 
team working to share knowledge between team members to not force all
to learn everything. And would be helpful to know in what areas I can look
for help with you.

Here is my resume to give you overview about my competence:
http://wttools.sourceforge.net/cv_only.html

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

Re: [generguide-devel] Requirements: Documentation Format

[Cameron S. <ca...@sh...>]

FYI Artur, Sean is now subscribed to generguide-devel using his yahoo email 
address.  Hopefully we can move forward with our discussions now.

On Monday 08 Sep 2003 12:47 am, Sean Wheller wrote:

> rdocformat1 > Documentation shall be stored in
> standards based format.
>
> The format specified is limited to Simplified Docbook.
>
> 1. I am not sure that Simplified Docbook can be
> referred to as a format. Rather it is a Document Type.

ok.

>
> 2. Simplified Docbook is a Subset of the DocBook XML
> Document Type. It is designed to accommodate documents
> such as articles, white papers, release notes etc.
> This means that generguide is inappropriately
> specifying the use of a Document Type. The generguide
> framework enables the development of books.

ok.

>
> 3. Simplified Docbook is only one of the standards
> based Document Types available. Perhaps the high-level
> principles of the generguide framework should be more
> generic to ensure wider application.


OK.  I accept all these suggestions.  The reason for specifying a 
Documentation Type is so that we can select appropriate tools.  Currently we 
provide Norman Walsh's docbook stylesheets which are used for Docbook XML and 
Simple Docbook XML.  So I'm happy to expand the scope to include Docbook XML.

If we add more document types than this, we need to consider how our tools can 
process them.

Specific guides may want to limit the document type used on their project to 
Simple docbook.  (Eg for a Developer's guide Full docbook is not required and 
hence using simple docbook makes it easier for new tech writers).

So our configuration file should have a field which specifies what document 
type to use.

>
> rdocformat2 > Documentation should be stored in a
> format which can be transformed into other common
> formats. In particular: text, html, pdf.
>
> 1. The format is XML, conforming to standards based
> Document Types, like Simplified Docbook or Docbook
> XML, as specified by the project.

Ok, but there needs to be a Stylesheets written for the XML before it can work 
within the generguide framework.

>
> rdocformat3.1 > Documentation shall be editable with
> an easy to use, no cost, WYSIWYM editor.
>
> 1. If rdocformat2 is specified as per the description
> I have provided, then the need for rdocformat3.1 is
> obviated to the extent that an author can use any
> editor of their choice.

Yes, that is true, however I still think this is an end user requirement.
In the requirements I try to list all a user's needs, independant of the 
technical solution we provide.
If at a later stage we decide our approach is not working, and we need to 
change our design, then we need to make sure this requirement is met.

Unfortunately most tech writers I've met don't like writing documentation in 
emacs or vi, which is probably why there are so many WORD documents around.

> 2. What is important is that the content conforms to
> the Document Type specified by the project and that it
> is Valid and Well-formed XML.
>
> rdocformat3.2 > Documentation shall be editable with
> an easy to use, open source, WYSIWYM editor.
>
> 1. Is there a reason why this rec is the same as
> rdocformat3.1?

It is not quite the same.  One refers to a free (as in free beer), the other 
refers to open source.
For many open source developers, this is an important difference and for this 
reason, XXE which is a great free docbook editor is not mentioned in the 
Linux Documentation Project HOWTOs.

> 2. Again I think that rdocformat3.1 and rdocformat3.2
> are not required.

If it is ok with you, I'd prefer to keep them.

>
> rdocformat4 > The learning curve required to write
> documentation should be kept as short as possible in
> order to attract authors.
>
> 1. This is not a requirement that fits under the
> category of Documentation Format.

Fair enough, we can move it under a different heading.

>
> rdocformat5 > The documentation format shall allow
> sections of a Generic Guide to be edited and stored
> separately to the Project Guide.
>
> 1. The format is XML. Better refer to architecture or
> structure.

ok.

> 2. This is also not a requirement that fits under the
> category of Documentation Format.

Sure, put it somewhere else.

>
> That is it for today. As I said, I will limit myself
> to the Documentation Format. In due course I will take
> a the same approach with the remainder of the
> requirements.

This is a good start.  I look forward to the next installments.
I suggest you use the latest version of this document from CVS instead of from 
the web page.  The website is not the latest version.
You can find it in:
generguide/docs/sdocbook/generguide.xml

Would you like to become editor of the requirements documentation?
I suggest that you propose changes to the requirements on the email list here 
(as you have done).  Anything that we agree to you can then update in the 
requirements section.



-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

[generguide-devel] Proposal to add Sean as a developer

[Cameron S. <ca...@sh...>]

Artur,
We have not developed procedures for the management of members in the 
generguide project.  I suggest we use the same process as we use in Geotools 
(and is documentated in 
http://generguide.sourceforge.net/developersguide/developersguide.html#teamorg 
).

I suggest that Artur and I are part of the Project Managment Committee, if 
that is ok with you Artur.

Sean sounds enthusiastic and suitably over qualified.  I propose we ask him to 
join us a a developer.
Artur, is that ok with you.
Sean, would you like to join us?


-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

[generguide-devel] Requirements: Documentation Format

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

I am new to the project. So I hope you will be able to
clarify some of the concerns I will raise in this
message.

I would like to start by addressing The Requirements.
As this subject is large I will limit myself to the
Documentation Format.

I hope that your responses will identify some
potential areas where I may start working without the
risk of changing the definition or focus of the
project.

rdocformat1 > Documentation shall be stored in
standards based format.

The format specified is limited to Simplified Docbook.

1. I am not sure that Simplified Docbook can be
referred to as a format. Rather it is a Document Type.
 
2. Simplified Docbook is a Subset of the DocBook XML
Document Type. It is designed to accommodate documents
such as articles, white papers, release notes etc.
This means that generguide is inappropriately
specifying the use of a Document Type. The generguide
framework enables the development of books.
 
3. Simplified Docbook is only one of the standards
based Document Types available. Perhaps the high-level
principles of the generguide framework should be more
generic to ensure wider application.

rdocformat2 > Documentation should be stored in a
format which can be transformed into other common
formats. In particular: text, html, pdf.

1. The format is XML, conforming to standards based
Document Types, like Simplified Docbook or Docbook
XML, as specified by the project.

rdocformat3.1 > Documentation shall be editable with
an easy to use, no cost, WYSIWYM editor.

1. If rdocformat2 is specified as per the description
I have provided, then the need for rdocformat3.1 is
obviated to the extent that an author can use any
editor of their choice.
2. What is important is that the content conforms to
the Document Type specified by the project and that it
is Valid and Well-formed XML.

rdocformat3.2 > Documentation shall be editable with
an easy to use, open source, WYSIWYM editor.

1. Is there a reason why this rec is the same as
rdocformat3.1?
2. Again I think that rdocformat3.1 and rdocformat3.2
are not required.

rdocformat4 > The learning curve required to write
documentation should be kept as short as possible in
order to attract authors.

1. This is not a requirement that fits under the
category of Documentation Format.

rdocformat5 > The documentation format shall allow
sections of a Generic Guide to be edited and stored
separately to the Project Guide.

1. The format is XML. Better refer to architecture or
structure. 
2. This is also not a requirement that fits under the
category of Documentation Format.

That is it for today. As I said, I will limit myself
to the Documentation Format. In due course I will take
a the same approach with the remainder of the
requirements.

Sean Wheller
se...@ya...

 


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

Re: [generguide-devel] Changes...

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

> On Monday 01 Sep 2003 6:36 am, Artur Hefczyc wrote:
> > 1. Added support for CATALOGS to generpublish.sh script
> >    (it works if you start it with option '-k')
> Should we include CATALOG files into the generguide repository, then 
> generguide.sh can use CATALOGs without needing a user to set them up 
> themselves?
> Ie, the "generguide -k" option could set the CATALOG variables itself.
Yes, it is good idea, however while I can know the place where xinclude.mod
file is located (in our generguide project directory tree), I can't guess location
of sdocbook.dtd (and other used DTDs) on user machine unless we add them
to project directory tree (but I don't like this).
So I will try to add today CATALOGS support for xinclude.mod only.

> > 2. Documentation for using xinclude.xsl with java tools has been written.
> Cool.  It is good to get all this information down.  I think that it currently 
> contains too much detail and that we need to revisit this and simplify it, 
> possibly by writing wrapper scripts which hide most of the options from the 
> user.
Yes, you are right. It was my concern too. However some details are hard
to find and it is good to have them documented somewhere.
That was reason I was thinking where to put this info. documentation.xml
seems to describe problems on higher level.
So I think I can rewrite this section and omit technical details and move them
to separate file. There is similar problem with entities, however they are described
in separate file which don't have to be included in documents which don't
require such technical info.
Is this ok for you?

> This is good stuff.  It would be good to incorporate it into the developers 
> guide.
> I invisage that we will eventually have one huge repository for all sorts of 
> business processes.  From this repository we will build guides that are 
> relevant for the project we are working on.
> Eg: Java Developers Guide
> XSL Developers Guide
> Tips on Buying Property
> How to write a newspaper
Yes, this is one of my expectations with this project. So I try to collect
whole knowledge I have or can find, describe it as detaily as possible
for further use.

> > On the other side I saw (and worked according this rule) that you have
> > added xinclude declaration to all XML files. However it is necessary only
> > where it is used, so it could be removed in many files what can speed
> > processing up. (Not too much if you use xinclude.mod from your disk).
> OK, good idea.
Is that mean I can remove <xinclude> declarations from files where it is not
used? Or you want it to have common header in all files? 

> > It seems to me that I have even sent you description how to set/use
> > catalogs under xxe.
> Yes, however I still have not been bothered setting it up.  I'm yet to be 
> bothered by not having it.  I know you keep trying to convert me.  :)
Oh, no! :) I don't, however I was afraid because of changes I made 
you start to wait for processing XML files more time than you work on them.

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

Re: [generguide-devel] Just an idea

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

> > Now we want to include in master document everything apart from
> > <sectioninfo/> element with it's content.
> > We can include content of above document apart from <sectioninfo/>
> > with following command:
> > <xi:include
> > href="samplefile.xml#xpointer(/section/*[name()!='sectioninfo']/descendant-
> >or-self::*)" xmlns:xi="http://www.w3.org/2001/XInclude" />
> Thinking again about how to remove <sectioninfo> from all the guides, it might 
> be easier to run all the guides through a XSL filter which strips 
> <sectioninfo> before calling the docbook parsing.  This way, we don't need to 
> edit the source guides. The stripping XSL could be called from generguide.sh.

Below text is to ensure that we are talking about the same thing.
Please don't feel offended that I am repeating it again but I want to be sure
we understand each other.

Well, I didn't mean to remove <sectioninfo> from our guides.
Just the opposite, I was thinking about adding it to all guides to
have author, copyright, and so on... info included in all files.
Because sometimes I would like to generate HTML page from only
basicxml.xml document and sometimes I want basicxml.xml to be included
as section in another large document.

My concern was, how to include such files in master document without
having <sectioninfo> content repeated at the beginning of each
section in target XML file.
Of course, the obvious solution is to omit <sectioninfo> during inclusion
part content. But I didn't know if this is possible with <xinclude> element.
The above sample shows how to accomplish this and include file content
without unnecessary part.

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

Re: [generguide-devel] Just an idea

[Cameron S. <ca...@sh...>]

On Saturday 30 Aug 2003 11:36 pm, Artur Hefczyc wrote:

> Now we want to include in master document everything apart from
> <sectioninfo/> element with it's content.
> We can include content of above document apart from <sectioninfo/>
> with following command:
> <xi:include
> href="samplefile.xml#xpointer(/section/*[name()!='sectioninfo']/descendant-
>or-self::*)" xmlns:xi="http://www.w3.org/2001/XInclude" />

Thinking again about how to remove <sectioninfo> from all the guides, it might 
be easier to run all the guides through a XSL filter which strips 
<sectioninfo> before calling the docbook parsing.  This way, we don't need to 
edit the source guides.  The stripping XSL could be called from 
generguide.sh.

-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

Re: [generguide-devel] Changes...

[Cameron S. <ca...@sh...>]

On Monday 01 Sep 2003 6:36 am, Artur Hefczyc wrote:
> 1. Added support for CATALOGS to generpublish.sh script
>    (it works if you start it with option '-k')
Should we include CATALOG files into the generguide repository, then 
generguide.sh can use CATALOGs without needing a user to set them up 
themselves?
Ie, the "generguide -k" option could set the CATALOG variables itself.

> 2. Documentation for using xinclude.xsl with java tools has been written.

Cool.  It is good to get all this information down.  I think that it currently 
contains too much detail and that we need to revisit this and simplify it, 
possibly by writing wrapper scripts which hide most of the options from the 
user.

> 4. Well, the last one, but not the less important. I have changed XML
> prolog in all our guides to following form:
>   <!ENTITY % xinclude
>     PUBLIC "-//GenerGuide//ELEMENTS XInclude for SDocBook V1.0//EN"
>     "http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
>
>     The one, most important consequence is, when you will be processing
>     documentation xinclude.mod have to be loaded by processing tool.
>     Because it is located on the web site you should note significant
> increase of time necessary for processing.
>     But benefit is that you don't need to worry about having this file on
> your disk in proper location when you are editing XML documentation.
>
>     But before you start to hate me for wasting your time with waiting
>     forever until processing will finish I give you tip how to avoid
>     downloading xinclude.mod (and sdocbook DTD) each time file is
>     processed.
>
> 1. Set environment variable similar to main below:
> export
> SGML_CATALOG_FILES="/sgml/catalog:/sgml/dtds/sdocbook-1.0/sdocbook.cat" 2.
> Put attached catalog file in place pointed by above variable and
> sdocbook.cat in directory where you have simplified docbook dtd.
> (If you have)
> 3. Look in catalog file and ensure that it points to correct xinclude.mod
> location on your HDD.
> 4. Always start generpublish.sh with '-k' parameter.

As mentioned above, maybe we should wrap above processing into the 
generguide.sh script.

> There is document in our guide/ directory describing this matter a little
> bit - - basicxml.xml - which is not included in developersguide.

This is good stuff.  It would be good to incorporate it into the developers 
guide.
I invisage that we will eventually have one huge repository for all sorts of 
business processes.  From this repository we will build guides that are 
relevant for the project we are working on.
Eg: Java Developers Guide
XSL Developers Guide
Tips on Buying Property
How to write a newspaper

and so on.

>
> On the other side I saw (and worked according this rule) that you have
> added xinclude declaration to all XML files. However it is necessary only
> where it is used, so it could be removed in many files what can speed
> processing up. (Not too much if you use xinclude.mod from your disk).

OK, good idea.

>
> It seems to me that I have even sent you description how to set/use
> catalogs under xxe.

Yes, however I still have not been bothered setting it up.  I'm yet to be 
bothered by not having it.  I know you keep trying to convert me.  :)


-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

[generguide-devel] Changes...

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

I am working (discovering how things work), documenting it and 
working again.
I have made some changes, I hope it will not affect you badly.
1. Added support for CATALOGS to generpublish.sh script
   (it works if you start it with option '-k')
   Internet and especially SF are very weak recently so to process
   XML files effectively I need maping DTDs and MODs to my local
   file system.
2. Documentation for using xinclude.xsl with java tools has been written.
    Description for generating HTML, PDF and other formats has to be 
    added yet.
3. I have updated xinclude.mod and put it to our web site at address:
    http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod
4. Well, the last one, but not the less important. I have changed XML prolog
    in all our guides to following form:
  <!ENTITY % xinclude
    PUBLIC "-//GenerGuide//ELEMENTS XInclude for SDocBook V1.0//EN"
    "http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">

    The one, most important consequence is, when you will be processing
    documentation xinclude.mod have to be loaded by processing tool.
    Because it is located on the web site you should note significant increase
    of time necessary for processing.
    But benefit is that you don't need to worry about having this file on your
    disk in proper location when you are editing XML documentation.

    But before you start to hate me for wasting your time with waiting
    forever until processing will finish I give you tip how to avoid 
    downloading xinclude.mod (and sdocbook DTD) each time file is 
    processed.

1. Set environment variable similar to main below:
export SGML_CATALOG_FILES="/sgml/catalog:/sgml/dtds/sdocbook-1.0/sdocbook.cat"
2. Put attached catalog file in place pointed by above variable and 
sdocbook.cat in directory where you have simplified docbook dtd.
(If you have)
3. Look in catalog file and ensure that it points to correct xinclude.mod 
location on your HDD.
4. Always start generpublish.sh with '-k' parameter.

Because you usually call xmltools with '--novalid' sdocbook DTD is
not downloaded so, you don't need sdocbook.cat indeed. But in a case
if you would like to validate XML document with them this catalog may help.

For Java tools once more file is needed. The CatalogManager.properties
file works as above environment variable and it has to be somewhere in
directory given as classpath. If you want to use it, look inside and ensure
that 'catalog' property has correct value.

There is document in our guide/ directory describing this matter a little bit
- - basicxml.xml - which is not included in developersguide.

On the other side I saw (and worked according this rule) that you have
added xinclude declaration to all XML files. However it is necessary only
where it is used, so it could be removed in many files what can speed
processing up. (Not too much if you use xinclude.mod from your disk).

It seems to me that I have even sent you description how to set/use 
catalogs under xxe.

I hope I didn't forget about anything. If you find something wrong
send me message I will correct it ASAP.

uff....
and still working on this.....

Artur
- -- 
Artur Hefczyc             "Don't change people, just live with them."
Open Source Developer:
http://www.geotools.org/
http://generguide.sourceforge.net/
http://wttools.sourceforge.net/
http://maven-plugins.sourceforge.net/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQE/Ulw10/6x1bjSKPkRAtXRAKDEkMjjQnFoevENMYDrNf6t5STPfQCgqvPF
KVoUURFtXSBeavu8EYR1p7I=
=Asiu
-----END PGP SIGNATURE-----

Re: [generguide-devel] Just an idea

[Cameron S. <ca...@sh...>]

On Sunday 31 Aug 2003 4:34 pm, Artur Hefczyc wrote:
> I don't know if you know XPath, to effectively use above idea, XPath
> at least basic XPath knowledge is necessary and above sample
> looks complicated even for somebody familiar with it.

Yes, I've been playing with Xpath and XSL recently.
-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

Re: [generguide-devel] Just an idea

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sunday 31 of August 2003 05:16, Cameron Shorter wrote:
> On Saturday 30 Aug 2003 11:36 pm, Artur Hefczyc wrote:
> > Now we want to include in master document everything apart from
> > <sectioninfo/> element with it's content.
> > We can include content of above document apart from <sectioninfo/>
> > with following command:
> > <xi:include
> > href="samplefile.xml#xpointer(/section/*[name()!='sectioninfo']/descendan
> >t- or-self::*)" xmlns:xi="http://www.w3.org/2001/XInclude" />
>
> Good idea, I like it.

I don't know if you know XPath, to effectively use above idea, XPath
at least basic XPath knowledge is necessary and above sample
looks complicated even for somebody familiar with it. 
(Probably there is simpler version of above expression.)
I have found excellent site:
http://www.zvon.org/xxl/XPathTutorial/General/examples.html
and there is also self-training tool where you can experiment
with XPath expressions:
http://www.zvon.org:9001/saxon/cgi-bin/XLab/XML/xlabIndex.html?stylesheetFile=XSLT/xlabIndex.xslt

Artur
- -- 
Artur Hefczyc             "Don't change people, just live with them."
Open Source Developer:
http://www.geotools.org/
http://generguide.sourceforge.net/
http://wttools.sourceforge.net/
http://maven-plugins.sourceforge.net/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQE/UZb80/6x1bjSKPkRAkEEAJ9GtzWDAGsI2Z6/uRBUdGYsVBy3zACfdtoY
1lDYisitUMRA5Kc8hlk9aM8=
=/pXQ
-----END PGP SIGNATURE-----

Re: [generguide-devel] Just an idea

[Cameron S. <ca...@sh...>]

On Saturday 30 Aug 2003 11:36 pm, Artur Hefczyc wrote:
> Now we want to include in master document everything apart from
> <sectioninfo/> element with it's content.
> We can include content of above document apart from <sectioninfo/>
> with following command:
> <xi:include  
> href="samplefile.xml#xpointer(/section/*[name()!='sectioninfo']/descendant-
>or-self::*)" xmlns:xi="http://www.w3.org/2001/XInclude" />

Good idea, I like it.

-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

[generguide-devel] Just an idea

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Well,

I started to work on documentation, read what we have done
and again search information about XML.

Some time ago I had concern how to have one common 
document info included in each file such as:
author, copyright and some other info but don't have this
info repeated in master document at the beginning
of each section in target format.

The more I would like to be able to publish also
each part as separate document and then, of course,
I want this document info to be displayed.

Now, I think I found a solution with use of xinclude and xpath.
Let's assume we have or parts of our documentation in 
following form:

(samplefile.xml)
<section>
	<sectioninfo>
		<authorgroup>
		</authorgroup>
		<date>
		</date>
		<copyrigth>
		</copyright>
	</sectioninfo>
	<title></title>
	<abstract></abstract>
	<para></para>
	<para></para>
	<para></para>
	<'all other elements'/>
	<sectio></section>
	<sectio></section>
	<sectio></section>
</section>

Now we want to include in master document everything apart from
<sectioninfo/> element with it's content.
We can include content of above document apart from <sectioninfo/>
with following command:
<xi:include  
href="samplefile.xml#xpointer(/section/*[name()!='sectioninfo']/descendant-or-self::*)"
 xmlns:xi="http://www.w3.org/2001/XInclude" /> 

But above command includes only content of section - root element.
If you want to have it as separate section in master document you have to
embrace above command with <section> element.

Artur
- -- 
Artur Hefczyc             "Don't change people, just live with them."
Open Source Developer:
http://www.geotools.org/
http://generguide.sourceforge.net/
http://wttools.sourceforge.net/
http://maven-plugins.sourceforge.net/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQE/UKh+0/6x1bjSKPkRAp+mAJ9jOGa3qzlt9t8zGXPLuWx3ZEjFWwCgpYMH
0KM4I6ZRyoykLZ5Q8b0tISs=
=NyXw
-----END PGP SIGNATURE-----

[generguide-devel] More suggestions, was - some concerns

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


I think you know about it but, here is excellent guide:
http://www.sagehill.net/docbookxsl/index.html

Especially this part can be interesting for you:
http://www.sagehill.net/docbookxsl/ModularDoc.html#XIncludeFallback
I am thinking about to use plain xinclude.xsl without your modifications.
Because we need this XSL for other inclusions (modular docs) so
it would be better to have and manage only one version.

Above url points to description how to manage inclusions which
can be not reachable at the time of processing.

Another one:
http://www.sagehill.net/docbookxsl/ModularDoc.html#UsingXinclude
shows also how to include whole context of given element without
element itself. Look at the end of this section, just before bold text:
"Including plain text".

> I suggest it should go into the Documentation section, under "Publishing
> docbook files".  You will already see a section here which would be
> outdated with your new work.
> http://generguide.sourceforge.net/developersguide/developersguide.html#publ
>ishingdocbook
Ok, I will.

> > I propose to change it to something like:
> > <!ENTITY % xinclude
> > PUBLIC "-//GenerGuide//ELEMENTS SDocBook XInclude extension V1.0//EN"
> > "http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
> Yes, this sounds reasonable.  (I don't understand what these references
> mean, but your suggestions sound like they would work and I trust your
> judgement enough that I'm happy not to find out.)
One of the biggest benefit to work in team is that nobody needs to know
everything. Knowledge can be spreaded for all team members.
So whole team has always greater knowledge than one developer
could have.
However here is the very short description about this matter if you want
to know:
http://xmlwriter.net/xml_guide/doctype_declaration.shtml#PublicDTD

PS. Somebody told: Knowledge of language grammar can hurt. I think it is
true. The better I know English grammar the more difficult is for me to 
express my thougths. ;-)

Artur
- -- 
Artur Hefczyc             "Don't change people, just live with them."
Open Source Developer:
http://www.geotools.org/
http://generguide.sourceforge.net/
http://wttools.sourceforge.net/
http://maven-plugins.sourceforge.net/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQE/UFxk0/6x1bjSKPkRAmURAKCDFeb6PriYx/GCtA8Ga+9bYIhESQCfUr82
ru/qx65o6c+GJ/i+t8fy9lY=
=w/PX
-----END PGP SIGNATURE-----

Re: [generguide-devel] Processing modular documentation - some concerns

[Cameron S. <ca...@sh...>]

On Friday 29 Aug 2003 6:07 pm, Artur Hefczyc wrote:
> Hi,
>
> I just finished my fights with joining parts of modular documentation
> to one XML document with use of
> Java tools (both xalan and saxon) and xinclude.xsl.

Excellent!!

> It works very well and I would like to describe it somewhere
> but I am not sure where.
> Of course it make sense to describe in this document not
> only how to process modular documentation with java+
> xicnlude.xsl but also how to use other tools xslproc, xmltools,
> xincluder and so on...
>
> There are some possibilities:
> 1. basic.xml (But is this basic xml processing?)
> 2. documentation.xml (But this document describes rather concept
>     but technical information.)
> 3. new document (Similar as entitiesuse.xml)
> 4. Or some other place I couldn't find.
> Have you any idea and suggestions?

I suggest it should go into the Documentation section, under "Publishing 
docbook files".  You will already see a section here which would be outdated 
with your new work.
http://generguide.sourceforge.net/developersguide/developersguide.html#publishingdocbook

>
> Another concern is about our definition of xinclude.mod.
> Our current declaration looks as follows:
> <!ENTITY % xinclude
> PUBLIC "-//NONAME//ELEMENTS DocBook XInclude extension//EN"
> "xinclude.mod">
>
> I propose to change it to something like:
> <!ENTITY % xinclude
> PUBLIC "-//GenerGuide//ELEMENTS SDocBook XInclude extension V1.0//EN"
> "http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
> The most important change is to make it available by HTTP url rather that
> as a file on local file system.
> 1. xinclude.mod will be officially available on the net
> 2. All tools parsing xml files containing xinclude element can download
>     this definition at any time, so user don't need to take care about it
>     unless he wants to speed processing up and store all DTDs locally.
> 3. Generic Guide will become some kind of owner of this definition what
>     make it easier to contact in a case when someone find bug or has a
> question related to this definition.

Yes, this sounds reasonable.  (I don't understand what these references mean, 
but your suggestions sound like they would work and I trust your judgement 
enough that I'm happy not to find out.)


-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com

[generguide-devel] Processing modular documentation - some concerns

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

Hi,

I just finished my fights with joining parts of modular documentation 
to one XML document with use of
Java tools (both xalan and saxon) and xinclude.xsl.
It works very well and I would like to describe it somewhere 
but I am not sure where.
Of course it make sense to describe in this document not
only how to process modular documentation with java+
xicnlude.xsl but also how to use other tools xslproc, xmltools,
xincluder and so on...

There are some possibilities:
1. basic.xml (But is this basic xml processing?)
2. documentation.xml (But this document describes rather concept
    but technical information.)
3. new document (Similar as entitiesuse.xml)
4. Or some other place I couldn't find.
Have you any idea and suggestions?

Another concern is about our definition of xinclude.mod.
Our current declaration looks as follows:
<!ENTITY % xinclude 
PUBLIC "-//NONAME//ELEMENTS DocBook XInclude extension//EN" 
"xinclude.mod">

I propose to change it to something like:
<!ENTITY % xinclude 
PUBLIC "-//GenerGuide//ELEMENTS SDocBook XInclude extension V1.0//EN" 
"http://generguide.sourceforge.net/xinclude/1.0/xinclude.mod">
The most important change is to make it available by HTTP url rather that
as a file on local file system.
1. xinclude.mod will be officially available on the net
2. All tools parsing xml files containing xinclude element can download
    this definition at any time, so user don't need to take care about it
    unless he wants to speed processing up and store all DTDs locally.
3. Generic Guide will become some kind of owner of this definition what 
    make it easier to contact in a case when someone find bug or has a question
    related to this definition.

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