generguide-devel

[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/

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