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

[Cameron S. <ca...@sh...>]

On Friday 20 Jun 2003 11:57 am, Artur Hefczyc wrote:

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

I like this idea, but have one main reservation which you may have an answe=
r=20
for.
I think that this project will benefit significantly if there are WYSIWYG=20
editors which can be used to edit the generguide docs.  This will mean that=
=20
non-geeks will be able to write/edit/correct/maintain the documentation.

While docbook still has limited editor support, I live in hope that it shou=
ld=20
get support within the next year or so.  For instance, beta versions of Ope=
n=20
Office are reporting support for import/export of dobook formats.

If we define a new generguide DTD, could we still use Dookbook WYSIWYG=20
editors?

If we do decide to define our own tags, I agree that using commented tags i=
n=20
the short term is a good idea.


> > This is getting closer.
> > I think the solution that is being used at the moment is even simpler.=
=20
> > 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=3D"projectname.sgml"
> >   xmlns:xi=3D"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.

Yes, true.
I was wondering whether a directory structure would be better, but I think=
=20
your idea of a config file is even better still.

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

I like this idea.
=46rom reading=20
http://www.sagehill.net/xml/docbookxsl/ModularDoc.html#UsingXinclude and=20
xpointer, I'm guessing the master developersguide.xml should be able to=20
reference items within the config file.  (I did try doing this with xsltpro=
c=20
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=3D"config.xml#xpointer(/project/project-name[1]/*)" =20
xmlns:xi=3D"http://www.w3.org/2001/XInclude"/>
 project, we do things this way: ... </para>


> > > 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 so=
me
> > > identification string.

> 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=3D'junitconfig'" how to configure this IDE for junit patterns generato=
r or
> something like this. And also unittest.sgml can contain also
> id=3D'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.

I'm flexable on this issue, so we probably should go with your advice.  It=
=20
would be worth looking at the suggested id tags for our current sections to=
=20
see what they would look like first and make sure they are ok.

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

I'm still to be convinced, but I am warming to the idea.  With regards to=20
project name, I think we can avoid the issue by changing all references to=
=20
"this project".  This keeps things generic and simple.  It means that=20
documentation between projects will look the same and I think that we shoul=
d=20
try to keep things the same.

It would be good to grep two developers guides to see the differences and=20
hopefully you should only see some sections added, others removed, and conf=
ig=20
files changed.

>
> 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 was using .sgml to denote Docbook files.
I guess that using <xi:include> means the files are not docbook any more.  =
Is=20
this what you have a problem with?
Should all files end in .xml, or only files with <xi:include> in them?

>
> 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 whe=
re
> it is necessary.

I'll have to take your lead here, as I'm not familiar with the problem.

=2D-
Cameron Shorter              http://shorter.net/cameron
Open Source Developer        http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com/