[generguide-devel] Re: discussion about ENTITIES

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Sean,
comments inline regarding your suggestions about ENTITIES.

Of note, we have 2 requirements for including text:
1. Include a docbook node (eg section).  So far we have addressed this by 
using <xinclude> to other files, and I think we are in agreement that this is 
a reasonable solution.
2. Include a variable name.  Eg, replace &project_name; with "Generguide".  
This is still not solved to our satisfaction and is the topic of this email.

On Thursday 02 Oct 2003 7:41 am, Sean Wheller wrote:
> ----- Original Message -----
> From: "Cameron Shorter" <ca...@sh...>
> To: <gen...@li...>
> Sent: Wednesday, October 01, 2003 12:22 PM
> Subject: [generguide-devel] Re: Sample files
>
> > I was not actually looking for problems with XXE, I was hoping we could
>
> find
>
> > solutions.  :)
>
> I know:-) Not trying to be difficult.
>
> > You have given a example of using ENTITIES to include files.  What we
> > have been doing with generguide is only including a variable string.  Eg:
>
> "Project
>
> > Name".  Only problem is XXE doesn't process these ENTITIES.  Attached is
>
> one
>
> > of the files, and the entities.ent
>
> In Gener you have used Internal General Entities.
> I used External General Entities.
> For the parser, they are the same, just that one is internal and the other
> external.
>
> XXE will open the document and the Entity will be shown in both cases. But
> in both cases you cannot edit directly. No way to fix that without fixing
> the XXE entity problem mentioned in my previous post.
>
> Actually I don't think that all the comments are required in Gener. The
> documents will open with the new version of XXE. So why add comments. All
> we must avoid is nesting.

Agreed.  Currently we are using  to get around 
deficiencies with XXE.  I agree we should use something else ASAP.

>
> So that is my first solution.
>
> Second solution, that will not suite every situation, is to use the
> entityref
> attribute when possible and suitable.
> This will reduce the number of comments required in a document. But it is
> not available on all elements. In DB you can now do the following:
> <textobject>
>     <textdata entityref="filename"/>
> </textobject>
>
> To make such a solution possible, would require modification of the DTD and
> then it's not Docbook anymore.

As I understand it, the example requires a new filename for each variable.  
I'd hope that all variables could be kept in one file.

I've mentioned to Artur before that I'd prefer to only use standards where 
possible.
However, I'm warming to the idea of extending docbook.

>
> Third solution is to use ulink when possible. Also consider variations
> based on olink) but most people find olink to complicated and never get it
> working. I don't know why.
> Here is cvs.xml using ulink. BTW Artur did hint to this in the last IRC
> meeting.
> --SOF--
> <section id="cvs">
>   <title>CVS</title>
>
>   <para>Concurrent Versions System (CVS) is a version control system that
>   allows multiple developers to work on the same files at the same
> time.</para>
>
>   <para>Information on how to download and edit this project&#39;s source
> code
>       are provided at: <ulink url="&cvs_url;"/>.</para>
>
>   <para>Note, before you can edit files, you will need to be granted write
>   access from the &src_license_owner;.</para>
>
>   <para>An excellent CVS manual can be found at <ulink
>
> url="http://cvsbook.red-bean.com/">http://cvsbook.red-bean.com/</ulink>.</p
>a ra>
> </section>
> --EOF--
> Yes. If you use the solution for cvs_url you will not see any text in XXE,
> but I think you get the idea. IMO it beats the comments handsdown. Beside
> it could always be ... <para> ... are provided at: <ulink
> url="&cvs_url;">SourceForge</ulink>.</para>

Yes, I like this.

>
>
> Fourth solution is to rethink how Gener uses enities and for what.
>
> Stay with me on this ....
>
> I think it better to develop an XSL customization layer that accepts
> parameter input
> than to use entities. That way we can pass the parameters to the XSL,
> either by direct input, or by feeding the customization layer with an xml
> file. In some environments it may also enable the use of method calls.
> Where a var of the method could pass xml as string. syntax:
> class.method(var1, var2, var3, xmlparameters) where xml parameters is a
> pointer to a valid and well formed xml string. In code, abstraction of
> Gener would then be possible and hence loading to application for editing
> under GUI.
>
> Going off at a tangent again... SO the generguide customization layer would
> have:
>
> <!-- Title of the Document -->
>     <xsl:param name="title"></xsl:param>
>
> <!-- Name of Project -->
>     <xsl:param name="projectname"></xsl:param>
>
> <!-- Version of Project -->
>     <xsl:param name="version"></xsl:param>
>
> ... continue to add and then customize and then /overide DB xsl's. Maybe
> even set some common DB parameters.
>
> This has the nice side effect of making Gener more dynamic (less hard
> coded). It also enables option setting Y, N, O, P
>
> A parameter file could conform to a DTD/XSD.
>
> parameter.xml
> --SOF--
> <?xml version="1.0" encoding="UTF-8"?>
> <parameters>
>      <title>The Definitive Guide</title>
>      <product>GenerGuide</product>
>      <version>1.0</version>
> </parameters>
> --EOF--
>
> parmeter.dtd
> --SOF--
> <!ELEMENT product (#PCDATA)>
> <!ELEMENT parameters (#PCDATA | title | product | version)*>
> <!ELEMENT title (#PCDATA)>
> <!ELEMENT version (#PCDATA)>
> --EOF--
>
> parameter.xsd
> --SOF--
> <?xml version="1.0" encoding="UTF-8"?>
> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
> elementFormDefault="qualified">
>   <xs:element name="product" type="xs:string"/>
>   <xs:element name="parameters">
>     <xs:complexType mixed="true">
>       <xs:choice minOccurs="0" maxOccurs="unbounded">
>         <xs:element ref="title"/>
>         <xs:element ref="product"/>
>         <xs:element ref="version"/>
>       </xs:choice>
>     </xs:complexType>
>   </xs:element>
>   <xs:element name="title" type="xs:string"/>
>   <xs:element name="version" type="xs:string"/>
> </xs:schema>
>
> --EOF--

Sean, I see the potial of this suggestion.
Of note, I'd imagine parameter.xml should be incorporated in the 
generconfig.xml.

Another variation of this idea I had is to have a param_to_entity.xsl style 
sheet.  Users can edit the param.xml seperately, then convert to ENTITIES 
before editing/publishing.  However, I think your idea of extending docbook 
is better.

If we are going to extend docbook, I'd be keen to discuss the idea with key 
people working on the docbook standard, and writing docbook editors.
Hopefully we will be able to get support from editors, and possibly even get 
an addition to the docbook standards.

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