[generguide-devel] Re: Commented entities and standards

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

----- Original Message ----- 
From: "Cameron Shorter" <ca...@sh...>
Sent: Saturday, September 13, 2003 6:16 AM
> On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote:
> > > 2. Commented entities are difficult to work
with,
> > > but it is closely associated
>
> It seems Sean misunderstands our attitude to
commented entities.
> The reason we are using commented entities is a hack
to get around the
> difficienties of XXE and something we plan to remove
as soon as we stop
> talking and get back to coding.
> Currently we use:  <!--&project_name;--> in our
souce text.
Pre-processing
> from the generpublishing script converts this to
&project_name; .
> "project_name" is defined as an entity in
guide/resouces/entities.ent

Yes I have seen this in the source and naturally I was
a bit confused at
first about how to process. I had to make the
connection between the script
and what it did to the commented entities. If I was
not able to read or
understand the script I would have dropped generguide
then and there.
Considering that most authors will not have the
patience for trial and
discovery. I thought that the solution was one barrier
to entry that was not
required.

I managed my entities in a very simple way. I have a
jscript and a perl
script which I found on bayes.co.uk. Its called
dir2xml. I run the script to
get a recurvise listing of a directory in XML. Then I
wrote an XSL to
convert the XML  to a file called global.ent. It is
inlcuded in the prolog
as an external entity. I see you use this standard
technique in generguide
already.

global.ent contains the entity list in standard syntax
format
<!ENTITY entity_name SYSTEM "/path/to/filename.xml">

Example:
<!ENTITY file SYSTEM "/path/to/file.xml">


Every file in the directory has an entry. So I can
insert an entity
reference when ever I wish. Naturally the content of
the XML Instance must
be Well-formed and Valid. It must also be acceptable
within the context of
the element to which it is inserted.

<para>The file <filename>file.xsd</filename> is used
to validate XML
Instances passed to the Business Object</para>

Would be:
<para>The file &file; is used to validate XML
Instances passed to the
Business Object</para>

I have not further need for any pre-processing. All I
must remember is that
when I add a new file to the document, it must be
added to global.ent. This
is easy as I just run the script > xsl > global.ent

If I don't then the validator will complain.

The problem I have with the current <!-- --> method is
that it is
non-standard solution introduced because of XXE. Yet
when I use the method
described above, I can still use XXE. The previous
version had the nasty
side effect of importing the value contained in
file.xml into the master
document. The current version no longer does this, but
you cannot edit the
external XML Instance directly. This is fine as I can
always open file.xml
seperately. Hence I was pressing to get the <!-- -->
method removed as soom
possible.

>
> What we plan to do is replace the above with xlinks
which reference the
> generconfig.xml file.  (I haven't worked out how to
do this yet and am not
> sure if XXE supports it, but I plan to look at it
soon).

As I see it generconfig.xml is just a filter that
enables you to decide what
is in and what is inlcuded and what is excluded from
output. While this is
certainly a method that works. I wonder why it is
required? In my system I
create an entry for all XML Instances within the
folder. The root document
includes several files by way of external entity
reference and those files
can include further files. If I don't want to have a
file, then I and
exclude as required using <!-- --> or delete the
entity reference.

Ok, I must conform to some rules, like each IDREF must
be unique in the root
document and DOCTYPE cannot be in any of the documents
referenced by the
root document. But this is not a major problem as I
<!-- --> out any DOCTYPE
below the root. The problem is that each XML Instances
is then not a valid
document in itself. XInlcude provides a solution to
this, but as we know it
needs a helper until such time that more tools support
it.

Still, without the aid of XInlcude. I have a highly
granualar and flexible
pool of information resources. The granularity of my
system can be as fine
or as general as I want. XML Instances can be the
source of a value or could
be comprised of the values contained in two or more
external XML Instances
(It does not make much sense to do this with just one
value).

>
> Sean, you are rightly concerned that we are not
using standards, and I
agree
> that we need to move back to using standards.  (I
think this is the only
> place where we have deviated from standards.)

Cool

>
> --
>
> With regards to normal Entities from legacy
documentation.  They can still
be
> used within the current generguide framework.  We
are not planning to
remove
> this functionality.

Good to hear.

>
> ---
> On Saturday 13 Sep 2003 3:28 am, Sean Wheller wrote:
> > 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.
>
> I agree.
> I believe the job of generguide is:
> 1. Define the interface.  Ie Docbook XML using
modular docs.
> 2. Ensure at least one free editor supports this
interface and your
average
> tech writer is happy using it.  Ie, WYSIWYM, edits
docbook xml, supports
> modular documents.
> 3. Provide publishing tools.

Cool.


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