Re: [generguide-devel] Re: I've created Generic Guide project

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

I can see that in CVS repository project directory tree is repeated.
I mean there is directory structure:
generguide
	|
	-- bin
	-- docbook-xsl
	-- docs
	-- dtd
	-- guide
	-- generguide
		|
		-- bin
		-- docbook-xsl
		-- docs
		-- dtd
		-- guide
		-- generguide

I work on files located in first level of this structure.

> If we define a new generguide DTD, could we still use Dookbook WYSIWYG
> editors?
I think so. This is the same problem as with use of xinclude.mod.
We create extension for existing DTD (docbook and sdocbook).
So let me explain this issue with xinclude.mod as example.
Such editors works on 2 levels. 

1-st level is for validating and helping in document structure modification.
It includes also such activities as displaying list of valid tags in current 
context, valid attributes for current tag and so on. 
To perform these actions program loads DTD and all entities (extensions) 
such as xinclude and all other. So it shouldn't be a problem if we create
proper DTD extension and declare the use of that extension in XML
file prolog.
i. e.:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE section
  PUBLIC "-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN"
  "http://www.oasis-open.org/docbook/xml/simple/4.1.2.5/sdocbook.dtd"
[<!ENTITY % xinclude
  PUBLIC "-//NONAME//ELEMENTS DocBook XInclude extension//EN" "xinclude.mod">
%xinclude;
]>

Above declaration tells that we are going to create XML file with structure 
defined in 
"http://www.oasis-open.org/docbook/xml/simple/4.1.2.5/sdocbook.dtd"
file and in "xinclude.mod" file. We can also include additional entity for
further extensions to our base sdocbook DTD.
Problems are only if we will start to use tags which are not defined in any
of files declared in file prolog. (So that is reason that I proposed to use 
fake-tag based on comments string.)

2-nd level of WYSIWYG (WYSIWYM) editors activity is displaying file
content. Please note, XML file contains no information how should
text be displayed. It contains only structural information.
To add visual sense to XML content they use two ways: CSS or XSLT.
CSS is used to directly define visual sense for XML tags
but
XSLT is used to transform XML to another format which can be easily
displayed.
Both CSS and XSLT are strictly DTD dependent. As you see, There can be
problem with displaying tags defined in extensions. Indeed xxe doesn't
display them in normal mode. They are only visible in document tree view
and there they can be added or removed. Different editor can behave 
differently for example they can display external tags in red color.
It is not good, I know. The more there is no standard for displaying XML tags,
each editor can define own CSS in their own way. 
However I expect that some standard will be created in short term.

To tell the true there are no good and free XML editors yet. All advanced
applications were born at SGML time and they were customized to XML use.
But they all are expensive. But things are changing very quickly nowadays.

> I like this idea.
> From reading
> http://www.sagehill.net/xml/docbookxsl/ModularDoc.html#UsingXinclude and
> xpointer, I'm guessing the master developersguide.xml should be able to
> reference items within the config file.  (I did try doing this with
> xsltproc a while back without success.  You might be able to work out how
> to do it.) So I should be able to write:
> <para>In the
>  <xi:include  href="config.xml#xpointer(/project/project-name[1]/*)"
> xmlns:xi="http://www.w3.org/2001/XInclude"/>
>  project, we do things this way: ... </para>
OK, I will take care about it. Maybe different tools can do it better.
I will check it.

> project name, I think we can avoid the issue by changing all references to
> "this project".  This keeps things generic and simple.  It means that
> documentation between projects will look the same and I think that we
> should try to keep things the same.
I am afraid it is not that simple. I started to work on it. Geotools appears
in many contexts, for example:
1. "Geotools Project Management Committee"
2. www.geotools.org
3. org.geotools.map.BoundingBox
4. #geotools irc channel
5. cvs.geotools.sourceforge.net
6. geotools2/geotools-src/<module>
...

I don't think simple change geotools -> this project is what you
expect. I am preparing something like dictionary map.
I mean maping for translating 'geotools' in different context to
different target 'string' or meaning.
With this mapping I will provide also 'sed' script for automatic 
translation.

> It would be good to grep two developers guides to see the differences and
> hopefully you should only see some sections added, others removed, and
> config files changed.
Don't fully understand this.
Let me show some example use:
I assume we have perfect guides set. GeoTools project want to generate
it's own documentation based on our guides set.
So GeoTools editor should create project custom config file.
Than he starts one script and generates GeoTools documentation in
HTML and PDF format.
All differences should be in "projectguide.xml" config file.
To be more flexible for different projects needs, configuration file
should allow to define also what sections should be included in 
target documentation and the more should also allow to define
inclusion of external sections created in i. e. GeoTools project.

> I was using .sgml to denote Docbook files.
> I guess that using <xi:include> means the files are not docbook any more. 
> Is this what you have a problem with?
> Should all files end in .xml, or only files with <xi:include> in them?
I wonder if it is worth to change files extension. I will explain why
and that you can make a decision to left existing extensions or
change them to XML.
1. xinclude is valid extension for both SGML and XML files.
2. You can declare your file as XML or SGML in document prolog:
<!DOCTYPE section
  PUBLIC "-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN"
  "http://www.oasis-open.org/docbook/xml/simple/4.1.2.5/sdocbook.dtd">
Above is XML declaration, to create SGML files all 'XML' occurrences
should be changed to SGML.
3. Please note we use sdocbook DTD for XML files, there is different 
sdocbook DTD for SGML files.
4. Although XML is some kind of SGML subset our files are not valid
SGML files.

Although it may look like all above points are good reasons to
change file extension there is one truth:
SGML is almost not used now. In particular in Internet world there is only
XML used. The more, all available editing and processing tools don't
know anything about SGML. They can't see differences. They threat
all such files as XML.
Only serious, expensive and with long tradition tools can process
properly SGML files.
I use emacs which is free but with long tradition program ;). It can 
understand both SGML and XML standards.
However I don't edit any real SGML files indeed. So I can configure
my emacs to threat all such files as XML too.

I have found some URLs explaining a little differences between SGML and XML:
http://navycals.dt.navy.mil/28001/sgmlxml.html
http://matwww.ee.tut.fi/hmopetus/prj/xmlsem2000/ht/leppanen.htm
http://www.w3.org/TR/NOTE-sgml-xml-971215

> > I have seen all files lack of prolog (DTD declaration). I will add it to
> > them. But I am not sure if I can also add xinclude entity declaration
> > where it is necessary.
> I'll have to take your lead here, as I'm not familiar with the problem.
I did it. So you need to configure xxe for use it.

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