Re: [gobo-eiffel-develop] geant documentation

[Eric B. <er...@go...>]

Sven Ehrke wrote:
>
> >I didn't look at what you did in your geant2*.xsl files, but
> >the idea I had in mind in order to have consistent documentation
> >is that all XML doc files in Gobo follow the same DTD. That
> >way the gobo2*.xsl files would work uniformally on all the doc
> >files in Gobo. Then of course other XSL files could be written
> >if one does not like the gobo2*.xsl formatting, but it would
> >be better if at least gobo2*.xsl would always work. So this
> >means that whenever the author of a doc needs a construct which
> >is not yet in the Gobo DTD, we should extend the DTD and update
> >the gobo2*.xsl files.
> 
> Ok. I can agree to that. In the documentation for geant I need tables
> to describe the tasks.

Hmmm, tables are part of the formatting, no? I thought that one
advantage of writing docs in XML was that we could write docs
without worrying about formatting (which was handled later on).
So, what I was talking about was DTD. Should tables be in the
DTD, or should they only appear in some .xsl files? In other
words do you consider tables to be part of the doc material or
the formatting? If it's the formatting then we could have some
.xsl which generate tables for some XML elements, but some other
.xsl files could generate some sort of lists:

  Paramters:
     * file
         description: file to copy
         domain: valid filename
         default: -
     * to_file
         description: file to copy to
         domain: valid filename
         default: -

> I understand this. But I have a question then. For the
> geant xml documentation files I would like to use geant
> specific xml tags to make documentation as easy and consistent
> as possible. Here is an example from 'geant_copy.xml' which
> describes the possible attributes of the <copy> task:
> _____________________________________________________
>     <parameters>
>         <parameter name="file" description="file to copy" domain="valid filename" default="-"/>
>         <parameter name="to_file" description="file to copy to" domain="valid filename" default="-"/>
>         <parameter name="to_directory" description="directory to which files should be copied to" domain="valid directory name" default="-"/>
>     </parameters>
> _____________________________________________________

If the element tags do not conflict with element tags already in
the Gobo DTD, why not add them to the DTD? If there are conflicts
we can possibly have <geant:parameters> (I'm sure how namespace
works in the DTD though). But what is important in my opinion
is that when one writes a doc, one should rely on the DTD to 
write the information to be put in the doc. Formatting comes
later when we write and apply .xsl files to these XML files.
But at that time the XML files are already written. I don't
think that writing the XML and XSL files at the same time (while
ignoring DTD specification) is the way these tools are supposed
to be used. At least that's how I understood it.

-- 
Eric Bezault
mailto:er...@go...
http://www.gobosoft.com