Re: [generguide-devel] Defining a new generguide DTD

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

> I've been wrestling with your idea to have a generguide DTD today.
> I think that you are right and that we should do it (starting with commented 
> tags as you suggest).
> 
> I figure I may as well make use of your greater experience in XML/XSL.
> 
> I still don't feel comfortable moving further away from standard WYSIWYM 
> editors, however I see that there is a good chance that WYSIWYM editors may 
> eventually support generguide type DTDs.

2 new concepts:

1. I was talking to my work mate today in the morning about our project and concerns.
    He has greater SGML experience than main. I think we can use his suggestion in
    our XML development. He suggests to use entities instead of tags for projects 
    customization. I need some research in this area however the general idea is that we 
    can define entities in external file like:
    project-name "this project"
    project-site    "http://generguide.sf.net"
    and so on...
    Than we can use these entities in our documents instead of inserting text in the 
    following way: "&project-name; Management Committee"
    For project customization it is enough to create any kind of file which can be
    used to generate entities file. (Or even project maintainer could create entities 
    file directly, however I don't recommend it because format of this file is not very 
    friendly.)

    Benefits:
    1. Very simple to use, should be supported by all SGML/XML tools.
    2. It doesn't affect any, existing DTD
    3. It is fully DTD independent, so they can be used not only with 
        DocBook and SDocBook DTD, but also with any other.
        (It is not that important however, our documents are sdcobook dependent.)
    4. Entity can by put  in almost any place of XML content without affecting
        document validity.
    5. Unlike with fake-tags in comments we have still some kind of validation
        when we put entities. Validator checks if used entity is really defined somewhere.
    6. All editing tools should not be confused if entity is used. All of them should support
        them, maybe in different way: some of them can display entity name and others
        entity value. xxe however behaves awful. It replaces all entities with their values
        and after document saving all entities are lost!

    Limitations:
    1. Simplify is a feature but also limitation. It allows simple string replacement.
        I will search more in this subject, but at the moment I can't see any way to
        do something more sophisticated like loops processing when we can have 
        many values for one entity, like developers list, set of mailing lists and so on.
    2. I don't know yet how to use them in xxe editor and don't lost entities.

I can't see any way to do in directly on entities, however we can use some kind
of trick.
Entities can point not only to strings, but also to any different resource, file for
example. Such file can contain, text, DTD extension, or even XML content.

All our generic guides will include entities.

We can customize project in project config file. Let me call it now
guideconfig.xml. Yes I suggest to use XML because it is easier to define
complex structures in XML. (However than we can't use simple bash script
for processing it. I think I am able to write java program for config in XML 
processing.)

Than we need a tool which could generate entities file from guideconfig.xml.
Some of entities (simple ones) could be defined as simple strings and others
can be defined as file content. This tool should be able generate files pointed
by entities as well.

At the end we have our generic guides and customized entities so target 
document will be generated exactly in the way as it is currently.

What do you think about it?

2. It seems to me I have found a way to define CSS for our DTD extension.
    So probably displaying our DTD tags will be possible on any
    WYSIWYG editor.
    However with entities concept it is not necessary.

3. References between sections (files). Do we need them or should avoid doing it? 
There is a way to do it. Not directly with SDocBook use, but with something like 
xinclude and additional XML processing tools.

On one hand it can be helpful to reference information places in different
document, however it introduces files dependence and it can be difficult
to use only a few of our sections in one guide.

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