[GRASS5] documentation

[Markus Neteler]

On Wed, Apr 24, 2002 at 10:28:52AM +0200, Moritz Lennert wrote:
> On Tue, Apr 23, 2002 at 09:12:56PM -0500, Helena wrote:
> > > start a general review of everything that is available, merge usable
> > > stuff and write whatever is needed.
[...] 
> > So I really believe that instead of trying to fix the old book (which
> > would be a monumental work, as it requires much more than polishing), it
> > would be actually faster and better to write new on-line tutorial based
> > on the latest GRASS5 release, rather than rely on GRASS4* materials. We
> > have already set it up, I think that Markus has a link to it.
> 
> There already is a new tutorial ? 

You can find an outlined version here:
http://grass.itc.it/gdp/grass5tutor/

This must be filled with contents now.
Eventually we should use "docbook" or something
similar (http://www.docbook.org/)

> I have been thinking along the same lines and I would propose somethin
> like this:
> 
> 1) A man page of a manual should contain links to parts of the
> manual/examples where it is used. A while ago I sent a message to the
> list, asking whether it would be possible to include a keywords
> section the man pages which would then be used to link to tutorials
> (i.e. on the d.rast page have a link to "displaying maps", "using
> raster data", etc..).

... and at least I agreed :-) In fact I already contacted colleagues
here to generated keywords semiautomated (as it is a huge task for
nearly 400 pages). But up to now I do not have a good suggestion
for software to use.

> 2) If we use the keywords carefully, we can automatically create a
> page that lists all the keywords with links to the relevant man pages
> and more detailed tutorials if the latter exist. This could be the
> beginning of a tutorial and people could add and maintain small
> tutorials on one of these aspects. If there is no tutorial, at least
> the user has all the relevant modules listed.

Such an index would be very welcome.

> 3) I think that seen the limited amount of people, this formula allows
>    incremental growth of documentation, while being usable almost
>    immediately.

But I don't think that a tutorial can grow from an index. I stick
more with Helena's idea of writing task oriented. However, the
tutorial should not miss such an index.

> So, if someone could confirm that 1)+2) are possible and maybe point
> me into the right directions on how to do it, I am willing to begin
> with that. Once the keyword page (i.e. the table of contents of a
> task-oriented tutorial) is ready, I (and others) can weed through the
> existing jungle and select those documents that should be linked to
> from that page. In a third phase we then have to write whatever is missing.
> 
> 
> Moritz

Markus