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

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

> Again, if we can avoid this then that would be good.  I don't want to
> maintain a new XML standard and continually have to update to incorporate
> the latest docbook format.
Well, I always prefer to use existing standards, however I also believe we
can create new standards too. We are also smart and experienced ;)
The good example for me of such activity is JUnit package.
However I also realize that it is not easy.
Anyway, I think it can be independent of docbook format in the same way
that xinclude.mod is.
But again, I think I am not ready yet to start working on this yet.
I know how to do it, however it require significant amount of time,
specially for XSLT definition.

Now I suggest to do as following:
1. Define (on demand, when we find it necessary) fake tags like this:
<!-- project-name --> this project <!-- /project-name -->
2. Create simple script in any language which could do what you have 
suggested: replace fake tag with xinclude tag pointing to proper external 
file.

It will allow as to:
1. Have some results in short time
2. Avoid DTD confusing
3. Gather set of external tags we find necessary
4. In future, switch to another approach in very easy way, because we 
have our documents already market, so we can creat simple script to
replace fake-tags with real tags.

> This is getting closer.
> I think the solution that is being used at the moment is even simpler.  I'm
> not sure if you have understood what I've proposed.  You might want to look
> at:
> http://generguide.sourceforge.net/usersguide.html
> and the build.sh script.
> What I'm proposing is that the user creates their own .sgml files which
> will overwrite the generguide.sgml files.
> For instance, if we want the generic guide to reference "project name",
> then in all generguide documentation we use:
> For the <xi:include href="projectname.sgml"
>   xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include> project, we ...
> Do you think this is a reasonable solution or does it have some problems?
I like this approach, the only problem I can see, we can end up with set of
many small files for custom project definition. I am sure it will happen
but obviously not now but after some time, maybe a year.

And than, it will be a time to switch to something different. I think about 
XSLT because this is the only solution I know for such purpose. I am also Ok
with something different.

Anyway, I can see instead of set of following files: projectname.sgml,
projectlicense.sgml, projectdeveloperslist.sgml and so on...
have one file, something like ANT build.xml for custom project description:
<project>
	<name>GenericGuides</project-name>
	<home-site>http://generguide.sourceforge.net/</home-site>
	<project-site>http://sourceforge.net/projects/generguide</project-site>
	<licenses>
		<license>
			<short>GPL</short>
			<full>GNU General Public License (GPL)</full>
		<license>
	</licenses>
	<developers>
		<developer>
			<first-name>Cameron</first-name>
			<surr-name>Shorter</surr-name>
			<email>ca...@us...</email>
			<role>Manager</role>
		</developer>
		<developer>
			<first-name>Artur</first-name>
			<surr-name>Hefczyc</surr-name>
			<email>ko...@us...</email>
			<role>Developer</role>
		</developer>
	</developers>
</project>

So at the end we can replace our fake tags with tags from our custom project 
definition i. e.: <project:name/>, <project:licenses expand="short"/>, 
<project:home-site/> and so on.
So XSLT for such needs would be almost trivial: replace each occurrence of
<project:TAG/> with text found in custom project definition.

> > For now I started to use convention that 'id' value starts with file base
> > name (what is usually close to section title) and the rest is some
> > identification string.
> That sounds good to me.  Although I suggest we just make this advice rather
> than a hard rule.
OK, 

> For instance, when talking about JUnit within the Unit Test section,
> "junit" is quite unique and probably doesn't need "unittestjunit" as an id.
I don't fully agree with this case. Lets assume we are talking about junit use
in presented IDE. Each IDE description can contain "example id='junitconfig'"
how to configure this IDE for junit patterns generator or something like this.
And also unittest.sgml can contain also id='junitconfig'.
I undestand it can look like not real problem, however if we use less
exceptions from this rule there will be less chance for conflicts.

> Yes, ok.  Would you like to create that file?  Maybe
> "generguide/guide/todo.txt"
Ok, done.

You didn't tell me if I have to use my idea of fake-tags:
<!-- project name --> this project <!-- /project-name -->
But I started to use them, because they are very easy to remove and they
don't affect any process. So if you don't like them, let me know
I will remove it.

New issues. 

You are using 'sgml' extension for files that are 'xml' indeed. 
It is not good. They are a tittle different standard and can confuse
some tools (moslty editing tools).

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.

Artur
- -- 
Artur Hefczyc                                art...@pl...
Open Source Developer
http://www.geotools.org/
http://wttools.sourceforge.net/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQE+8uig0/6x1bjSKPkRAsjAAJ9MJix3bC0jh1pPaS7XOCwXXg/p7wCcD6S8
ebPEsg4u5q/RpK2D8opjXg4=
=+SQz
-----END PGP SIGNATURE-----