Menu
▾
▴
generguide-devel — Discussion for developers of generguide
You can subscribe to this list here.
| 2003 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
(33) |
Jul
(21) |
Aug
(20) |
Sep
(80) |
Oct
(62) |
Nov
(8) |
Dec
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2004 |
Jan
|
Feb
|
Mar
|
Apr
|
May
(1) |
Jun
(4) |
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
(2) |
| 2006 |
Jan
|
Feb
|
Mar
(1) |
Apr
|
May
|
Jun
|
Jul
(3) |
Aug
(6) |
Sep
(1) |
Oct
(6) |
Nov
(7) |
Dec
(12) |
| 2007 |
Jan
(9) |
Feb
(12) |
Mar
(1) |
Apr
(4) |
May
(6) |
Jun
(11) |
Jul
(16) |
Aug
(19) |
Sep
|
Oct
|
Nov
|
Dec
|
|
From: Artur H. <ko...@pl...> - 2003-06-23 09:11:00
|
> 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/
|
|
From: Cameron S. <ca...@sh...> - 2003-06-22 11:23:46
|
Artur, 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 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. -- Cameron Shorter http://shorter.net/cameron Open Source Developer http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com/ |
|
From: Cameron S. <ca...@sh...> - 2003-06-22 05:10:20
|
Artur, I'm slowly thinking through your ideas. You have convinced me that renaming the sections as .xml is the right thing to do. I've updated the todo.txt to say this. -- Cameron Shorter http://shorter.net/cameron Open Source Developer http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com/ |
|
From: Cameron S. <ca...@sh...> - 2003-06-21 23:05:13
|
Artur, Yes you are right, I imported generguide into CVS twice. I've got the sourceforge team to remove the extra directory. If you do a fresh cvs checkout you will find the directory has been removed. -- Cameron Shorter http://shorter.net/cameron Open Source Developer http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com/ |
|
From: Artur H. <ko...@pl...> - 2003-06-21 22:20:22
|
I added new file to repository: generguide/todo.txt It contains all todos I have found in our mails up to now. Some of them are todos for far future, however I think it is useful to have all of them collected. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ |
|
From: Artur H. <ko...@pl...> - 2003-06-21 22:01:06
|
Thanks, I think I understand now. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ |
|
From: Artur H. <ko...@pl...> - 2003-06-21 21:40:34
|
> 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> I was thinking about this, and I am sure it is possible to do it. However this kind of processing has some limitations of use. We can't accomplish more complex inclusions this way. i. e. for developers list: <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> we can access only one developer element. I can't see any way to do inclusions with use of loops. The only solution to this I see XSLT which is almost full featured language with loops, conditionals and so on. Please don't think I try to force XSLT use. I try only warn about traps and suggest possible solutions. XSLT is the only technology I know for this kind of XML processing. Maybe there also good alternatives. Another problem I found is that current xinclude.mod doesn't allow to use <xi:include .../> tag after </section> closing tag. After some investigation I see that it is because of 'section' definition on SDocBook DTD. Probably I can modify xinclude.mod to allow this kind of use. I can add at least one file to CVS repository - basicxml.xml. However it seems to me it is not good to have most files with 'sgml' extension and one or a few of them with 'xml' extension. If you make a decision what extension to use I will add new file to CVS repository. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ |
|
From: Artur H. <ko...@pl...> - 2003-06-21 21:23:32
|
I have walked through file sources and tried to analyse different kind of 'geotools' occurrence. I attached file with samples and my proposition for translating from existing text to tagret, project independent format. I am able also to write 'sed' script which can do translation automaticaly, however I found only 139 occurrences. This amount can be done in 1 day manual, but more important is not what tool to use but how to translate. So therefore I have spent some time on creating mapping proposition. Please look in attachment and do some corrections. Than I can change sources according to your orders. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ |
|
From: Artur H. <ko...@pl...> - 2003-06-21 16:21:53
|
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/ |
|
From: Cameron S. <ca...@sh...> - 2003-06-21 12:15:27
|
On Thursday 19 Jun 2003 4:35 pm, Artur Hefczyc wrote: > > 3. For sections that are geotools specific: > > 3.1 make a copy of the section in the geotools repository, say > > geotools-src/docs/localdevelopersguide/ > > 3.2 Either remove section from generguide or replace with CAPITALISED > > GENERIC WORDS which will need to be edited later by specific projects. > > Not fully understand this yet, so I will leave it for later. I've created an example with irc*.sgml, in particular irclog.sgml which shows the generic guide not storing logs, and geotools storing logs at http://geotools.org Try running: generguide/bin/build.sh Then look at target/developersguide.html#irclogs Then, cvs update geotools2 Notice new files geotools2/geotools-src/developersguide/irc*.sgml generguide/bin/build.sh -l work/geotools2/geotools-src/developersguide/ Notice a difference in target/developersguide.html#irclogs -- Cameron Shorter http://shorter.net/cameron Open Source Developer http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com/ |
|
From: Cameron S. <ca...@sh...> - 2003-06-21 12:09:05
|
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/ |
|
From: Artur H. <ko...@pl...> - 2003-06-20 23:08:45
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 I am working on sgml files and I would like to share some thoughts about it: 1. It would be good to have some tool for automatic formating xml code (something like jalopy for Java). I have such functionality in emacs but it is not perfect, particulary, it tries to format 'programlisting' content. 2. We can use short version of xinclude tag: <xi:include href="file.sgml" xmlns:xi="http://www.w3.org/2001/XInclude"/> instead of: <xi:include href="file.sgml" xmlns:xi="http://www.w3.org/2001/XInclude"> </xi:include> 3. I also added something like comment string at the end of each sgml file. Please don't remove it. I need it to properly operate on this files under emacs. I realize that it is my own tool dependend and it shouldn't be there, however I will remove it later after I finish all manual processing on them. 4. There are something like this: <programlisting>cd $GEOTOOLS_HOME/geotools2 maven build</programlisting> in maven.sgml file. $GEOTOOLS_HOME variable is undefined in document, and so more it looks like it's use in not valid. It seems to me $GEOTOOLS_HOME should be replaced with something like $PROJECTS_HOME 5. In many examples where paths to files are used sometimes '\' is used as file separator and sometimes '/'. I suggest to use only one variant: '/' - this char is properly understood by almost all systems: unix like, java and event recent Windows systems. I am working on removing GeoTools and GT2 from documents. It is not that easy as I have thought before. They exist in many different contexts and I want to make smart replacement. More details I will send probably in about 10-12 hours. I need a little sleep ;) I have added DTD prolog to each file and made some reformating of XML code. 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+85Pz0/6x1bjSKPkRAvHQAJ4/IBCIkZOIb2T8Clb9wEIwyTk2gACeKaS2 OVwoUC6hJ8BJ6KnbpiMqdpc= =Ui/L -----END PGP SIGNATURE----- |
|
From: Artur H. <ko...@pl...> - 2003-06-20 10:57:41
|
-----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----- |
|
From: Cameron S. <ca...@sh...> - 2003-06-20 02:27:22
|
On Thursday 19 Jun 2003 4:35 pm, Artur Hefczyc wrote: > > This avoids the need for XSLT. However I'm possibly avoiding XSLT > > because I don't know enough about it and am going with what I know > > instead. > So as I can see the use of XSLT in our project can not be that easy > and comfortable. > > For example lets assume we want to be able put, somewhere in > generic guide, information about license type used (i. e. in geotools > project). > > To be able to do it with XSLT we should have (choose) some tag which > could be replaced with license information for existing project. > The one option is to use tag existing in sdocbook (or even full DocBook) > which probably can be in a conflict with other uses of this tag. > But it is easy to use, our editors will work with it without any problems. I'm not comfortable overloading any of the docbook tags. The tags are there for documentation rules and is likely to confuse users in the future. > > Or another option is to define our own tags set (something like > xinclude.mod) which could be used as sdocbook extension. So these special > set of tags can be used for many necessary things in genericguide project > docs. And than these set of tags can be processed in first stage to replace > them with necessary text with standard XML tags and then such files would > be directed to common XSLT processing to transform them to output format. > However it will be something like creating new standard what is not bad in > general but can generate some difficulties at beginning. 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. > > In my documents I used third approach, the easiest to use but without > future. I put special comment strings in XML code and they are replaced, > by shell scripts, with XML tags and text before they are directed to > further processing. > It is similar approach to second option. And can be used before full > implementation of second option. Comments can't hurt our XML text > and in future they can be changed to XML 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 put it here to ensure the build.sh script works. The users computer > > might not have xslt installed. I was trying to ensure that there is > > minimal configuration required to get generguide working. > > I understand now. I try to use the latest version to see if there are > really worth differences to replace existing version. OK. > 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. For instance, when talking about JUnit within the Unit Test section, "junit" is quite unique and probably doesn't need "unittestjunit" as an id. > > Tasks: > > If you are looking for something to do, I'd suggest going through each > > section and doing the following: > > 1. Restructure to above format. > > It could be useful to have files list and have checked files already > cleaned. Also it could be useful to avoid in some way to work together > on the same file. Yes, ok. Would you like to create that file? Maybe "generguide/guide/todo.txt" It probably won't be too much of an issue if you check all your code in at the end of the day and I do the same since we are working in different time zones. > > 3. For sections that are geotools specific: > > 3.1 make a copy of the section in the geotools repository, say > > geotools-src/docs/localdevelopersguide/ > > 3.2 Either remove section from generguide or replace with CAPITALISED > > GENERIC WORDS which will need to be edited later by specific projects. > > Not fully understand this yet, so I will leave it for later. OK, I'll see if I can set up an example in the next few days. > I have a couple of new sections about emacs and XML. I can add them (if I > can) to CVS repository. I think it would be useful to finish XML section as > soon as possible, because it could be helpful for our XML work. > I mean - document about joining separate XML files, efficient DTD use > from local directories instead of from location given in XML prolog, > validating and other XML processing and so on. > If I find enough power it is possible to have it ready for tomorrow. Sounds good. -- Cameron Shorter http://shorter.net/cameron Open Source Developer http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com/ |
|
From: Artur H. <ko...@pl...> - 2003-06-19 15:35:54
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 > I was thinking that geotools would import generguide into it's docs (or > developersguide) directory, then create a new directory for geotools > specific sections. > Eg: > geotools/geotools-src/developersguide/generguide/... > geotools/geotools-src/developersguide/localdocs/*.sgml I agree, however I worry a little about making all things up to date. When we change someting in generic project or in geotools project. So obviously scripts should be smart enough to make is easy updating all together. However all troubles shouldn't be very difficult to solve I think. > This avoids the need for XSLT. However I'm possibly avoiding XSLT because > I don't know enough about it and am going with what I know instead. I know something about it. I have used in my job in one project XSLT and have created some XSLT scripts for our needs. In simplest words XSLT translates one set of XML tags to another set. As we currently use them for translation from XML sdocbook to HTML. So as I can see the use of XSLT in our project can not be that easy and comfortable. For example lets assume we want to be able put, somewhere in generic guide, information about license type used (i. e. in geotools project). To be able to do it with XSLT we should have (choose) some tag which could be replaced with license information for existing project. The one option is to use tag existing in sdocbook (or even full DocBook) which probably can be in a conflict with other uses of this tag. But it is easy to use, our editors will work with it without any problems. Or another option is to define our own tags set (something like xinclude.mod) which could be used as sdocbook extension. So these special set of tags can be used for many necessary things in genericguide project docs. And than these set of tags can be processed in first stage to replace them with necessary text with standard XML tags and then such files would be directed to common XSLT processing to transform them to output format. However it will be something like creating new standard what is not bad in general but can generate some difficulties at beginning. In my documents I used third approach, the easiest to use but without future. I put special comment strings in XML code and they are replaced, by shell scripts, with XML tags and text before they are directed to further processing. It is similar approach to second option. And can be used before full implementation of second option. Comments can't hurt our XML text and in future they can be changed to XML tags. > That is very generous of you. However your family is much more important > than a computer project, so I hope you don't make decisions based on this > work. I try to spend all my time with family when they are with me and don't waste time if they are away. So I hope there is no reason to worry. But I am very glad that you also see family as primary concern. > I put it here to ensure the build.sh script works. The users computer > might not have xslt installed. I was trying to ensure that there is > minimal configuration required to get generguide working. I understand now. I try to use the latest version to see if there are really worth differences to replace existing version. > Doc format: > ... > The rules are not hard and fast because not all documentation will fall > into this pattern. I have met one problem during creating my part of documentation. It is related to 'id' attributes values. It is very easy to use the same value in different documents (sections) and than, after joining them, have difficult to understand problems. 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. But I am OK with use another approach. > Tasks: > If you are looking for something to do, I'd suggest going through each > section and doing the following: > 1. Restructure to above format. It could be useful to have files list and have checked files already cleaned. Also it could be useful to avoid in some way to work together on the same file. > 2. Remove all references to geotools and GT2. A lot of the time, you can > replace "geotools" with "this project". Easy to do for me, I can use grep+sed or emacs with interactive mode to avoid stupid-automates mistakes, so leave it for me. Hm, I can see the first place for own XML tag use: <this-project/> for example. However since it is too early to make this decision and it would generate DTD problems immediately I can suggest something like fake tag: <!-- this-project --> this project <!-- /this-project --> So this will not hurt at the moment but will allow easy changes in the future. > 3. For sections that are geotools specific: > 3.1 make a copy of the section in the geotools repository, say > geotools-src/docs/localdevelopersguide/ > 3.2 Either remove section from generguide or replace with CAPITALISED > GENERIC WORDS which will need to be edited later by specific projects. Not fully understand this yet, so I will leave it for later. > 4. Make sure all sections have unique id tags associated with them. Yes, see my comments above about 'id' attribute values. I think it would be helpful to standardize naming them in some way. > I'd suggest that you start with your emacs sections. I have a couple of new sections about emacs and XML. I can add them (if I can) to CVS repository. I think it would be useful to finish XML section as soon as possible, because it could be helpful for our XML work. I mean - document about joining separate XML files, efficient DTD use from local directories instead of from location given in XML prolog, validating and other XML processing and so on. If I find enough power it is possible to have it ready for tomorrow. 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+8dhR0/6x1bjSKPkRAmX/AJ9vqro1tyWwklhTXIhsB9uAp6E4DgCgy11v spVqa/UVVdTNzG/cYSJ7DK0= =klXF -----END PGP SIGNATURE----- |
|
From: Cameron S. <ca...@sh...> - 2003-06-18 21:04:24
|
On Wednesday 18 Jun 2003 2:00 pm, you wrote: > > Hope you are not feeling as sick as you were on the IRC meeting. > > Yes, I am much better now. Monday (in Europe) was the worst day. Glad to hear that. > > My plan is to: > > * Work out a process for importing the generguide into the geotools > > project. Any ideas? > > It depends what you exactly mean when you talk about importing. I am not > sure yet how do you expect generic documentation should be used. > For example generic guides can be used as templates. And projects can > create own documentation based on these templates. Than with some set of > XSLT or scripts in some language they generate own documentation inserting > project logo, addresses of mailing lists, developer list and so on... in > proper place in documentation. > > Another approach is to use generic guides as references or patterns. So on > project page they can say "In our project development we follow standards > presented on "genericguide" project site." And maybe than there is no need > to physicaly importing documentation. > > In real use I can see both approaches. Some parts of guide can be used as > templates and some of them as references or patterns. Yes, I can see both those working. The way the current generguide/bin/build.sh script works is: cp generguide/docs $tmp cp project/docs $tmp #overwriting generguide/docs style $tmp > $target/developersguide.html I was thinking that geotools would import generguide into it's docs (or developersguide) directory, then create a new directory for geotools specific sections. Eg: geotools/geotools-src/developersguide/generguide/... geotools/geotools-src/developersguide/localdocs/*.sgml This avoids the need for XSLT. However I'm possibly avoiding XSLT because I don't know enough about it and am going with what I know instead. > > > What directory should it sit in? > > I think existing geotools "docs" directory is good. ok. > > > * Remove references in the generguide to geotools. > > * At the same time, create local geotools specific sections in geotools > > cvs. * Announce the project to the world. (Probably via email lists like > > maven-user). Any suggestions on where the project should be announced? > > When I started my own project I was announcing it on many developers > specific places like java.sun.com in developers section, IBM alphaworks, > on some related discusion news list. > This project is very special. I think there are many people who could be > very interested in such info. > I will think about some more appropriate places. ok. > > > If you are interested in helping out with any of this then I'd be > > delighted to have you on board. However if you are sick, or have > > something better to do then that is fine too. > > I would be happy to take care about some task. The more there will 4 free > days from tomorrow in Poland. However I am not sure if I will go to Gdansk > to my family for this time. If I stay at home I can spend all the time on > it (few hours I need for GeoTools VPF). The decision will be known tommorow > in the morning ;). And than I don't know what will be next week. Again if > my family will come back to me to Warsaw I will be having less time for OS > projects. If not, you can use all my evenings time. That is very generous of you. However your family is much more important than a computer project, so I hope you don't make decisions based on this work. > > And from 15.07 to 30.07 I have holydays and probably will be away from > computer. However from the beginning of August I expect again to have more > time. ok. > > I have looked in CVS repository and wondered why did you put docbook xslt > there? From time to time it is new version released and I expect each next > version will be better than former. Maybe it should be used as external > library? I put it here to ensure the build.sh script works. The users computer might not have xslt installed. I was trying to ensure that there is minimal configuration required to get generguide working. Doc format: I've been thinking about setting the structure of the developersguide in the following format: http://generguide.sourceforge.net/developersguide/developersguide.html#writingguidelines Process sentence or 2 explaining process Tool1 sentence or 2 explaining tool Section 1 about tool possible sentence explaining section. rest of section Section 2 about tool Tool2 ... Reference The rules are not hard and fast because not all documentation will fall into this pattern. Tasks: If you are looking for something to do, I'd suggest going through each section and doing the following: 1. Restructure to above format. 2. Remove all references to geotools and GT2. A lot of the time, you can replace "geotools" with "this project". 3. For sections that are geotools specific: 3.1 make a copy of the section in the geotools repository, say geotools-src/docs/localdevelopersguide/ 3.2 Either remove section from generguide or replace with CAPITALISED GENERIC WORDS which will need to be edited later by specific projects. 4. Make sure all sections have unique id tags associated with them. I'd suggest that you start with your emacs sections. -- Cameron Shorter http://shorter.net/cameron Open Source Developer http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com/ |
54 messages has been excluded from this view by a project administrator.
