Documentation method.

New Message	Reply	About this list	Date view	Thread view	Subject view	Author view

From: Michael Lake (mikel_at_speleonics.com.au)
Date: Sun Jan 21 2001 - 11:58:19 CET

Next message: Michael Lake: "Re: LRUD: 'From' or 'To' ?"
Previous message: Richard Knapp: "All's quiet...."

Message-ID: <3A6AC0CB.6123E8E6@speleonics.com.au>
Date: Sun, 21 Jan 2001 21:58:19 +1100
From: Michael Lake <mikel_at_speleonics.com.au>
To: cavexml_at_cartography.ch
Subject: Documentation method.
References: <Pine.LNX.4.21.0101121612050.6966-100000_at_karto.ethz.ch>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Sender: owner-cavexml_at_karto.baug.ethz.ch
Precedence: bulk

Hi All,

A while ago I asked what we were going to do with regards to
documentation.

Andreas Neumann wrote:
> Concerning the way to document for different media I must confirm that I
> haven't worked with "Docbook" yet, but I am open to learn it, if its not
> too complicated. I frequently use LaTeX, HTML and XML, so I am used to
> structure text and separate formatting from content.
>
> Maybe Michael can send me some links with documentation or tutorial on
> docbook - I think the Linux Distribution I use (SuSE) provides all the
> tools needed ...

I have not used it either. Just thought that its something to think
about at the start. Although I use noweb (which uses LaTeX and embedded
code fragments) I know that more software developers use docbook.
URLs are: http://www.docbook.org/intro.html and faq.htm respectively.

I have downloaded & install all the DocBook tools but still haven't been
able to work it out yet! Its a powerful but complex system. I made some
enquiries about using DocBook at the Australian Open Source Conf which
has just
finished. DocBook is currently at 3.2 or something and is mature. Most
software
developers in the open source community use DocBook as its designed for
technical
documentation of software. There is an XML version of DocBook but its
pretty new.

However there is a catch. I was told it may have probs with DTDs and XML
code embedded in it as it's an SGML language which of course uses all
the
same syntax as XML DTD's.

In the meantime as a trial to see what you think I have updated my own
documentation to include the schema, derived from my DTD, by Martin
Laverty.
This file is actually called CaveSurvey.nw (for noweb) and from it I
generate
the DTD, Schema, HTML and PostScript. Printout the cavesurvey2.ps file
and
have a nice read on the train :-) You will see that each part of the DTD
and
Schema are with the discussion as to why that piece of code is done that
way. DONT COMMENT ON WHETHER THAT WAY IS RIGHT OR NOT. I have put it
there to
show how you can have bit of code placed right next to the bits that
document
why the code is as it is. You can extract the CaveSurvey DTD with "make
dtd",
extract the Schema with "make schema", and extract the documentation
with
"make html" & "make ps". All the contents and at the end the code
defines
and index are generated automatically.

Devin Kouts wrote: "I submit that both DTD and Xschema may be
useful.....
Until that moment,.....I move that we attempt to use both
DTD and Xschema to describe the valid contents of an XML file ..."

With the above we can have the one document define DTD and Schema and
keep them in sync easily.

It's at my website at:
http://www.speleonics.com.au/cavesurvey.zip (132k size)
Note this is not a html link. It's the actual location. The zip file
contains
CaveSurvey.dtd
CaveSurvey.html
CaveSurvey.xsd
CaveSurvey2.ps (23 pages long, 2 pages/A4 page landscape)

As you can prob understand from all the discussion we have been having
recently
when we do settle on a particular way to do something it needs to be
documented.
We can't include it with the DTD or Schema as comments as users need to
download
the DTD/Schema and the browser must read it in. Instead we include the
(if need be -
the long winded) discussion in the documentation right with the part of
the DTD and
Schema and extract the full DTD/Schema from the docs.

PS. To Martin: The schema in that doc is still not fully merged. There
are some bits to still go in. It wont work at present as a schema. Its
just for seeing
how its generated.

Mike

-- 
--------------------------------------------------------------------
Michael Lake
Active caver, Linux enthusiast and interested in anything technical.
Safety Convenor, Australian Speleological Federation
Owner, Speleonics (Australia)
--------------------------------------------------------------------

Next message: Michael Lake: "Re: LRUD: 'From' or 'To' ?"
Previous message: Richard Knapp: "All's quiet...."

New Message	Reply	About this list	Date view	Thread view	Subject view	Author view

This archive was generated by hypermail 2b30 : Wed Feb 14 2001 - 00:03:52 CET