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