[GRASS5] GRASS tutorial

mlennert · October 26, 2002, 3:22pm

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi all,

After our discussion about the problems some had with docbook, I have
decided that the GRASS Wiki might be a better place for the tutorial
as I had it in mind (mainly composed of links to relevant web
pages). I therefore started to transpose it to the Wiki. The beginning
of my efforts can be found on
http://grass.itc.it/wiki/index.php/Tutorial. Please everyone feel free
to correct or complement any of the pages, there's still lots of work.

Once we've fleshed out this tutorial we might reimport it into docbook
to make something more "book-like" out of it (less links, more text)
which could then be distributed in PDF or other formats.

If no one objects, I will announce the wiki tutorial project on the
users list next week in the hope to motivate some people to
participate.

Moritz

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.0 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>

iD8DBQE9urNMyrpWRtQydA0RAjpbAKCynnd2Be+HFWs99zJBqbu2t64MWwCfTnti
h+ZkM+Q6pzac6yRJ3jUepbQ=
=9Qqr
-----END PGP SIGNATURE-----

Sergiusz_Pawlowicz1 · October 27, 2002, 12:19am

--->[Quoting Moritz Lennert <mlennert@club.worldonline.be>:]

If no one objects, I will announce the wiki tutorial project
on the users list next week in the hope to motivate some
people to participate.

No objections, but also no support to this idea. Do not tell
me that technical reasons interfere with your mind to improve
documentation... Our expirience in Linux Documentation Project
(we require docbook or linuxdoc sgml files) is that lazy
people are not producing good documentation, how easy the tool
they use is.

Currently docbook files with grass tutorial are rendered each
five minutes from cvs, you can see output under:

http://tutorial.grass.it-zone.org/

and everyone with simple text editor such a notepad.exe
could improve it.

And please notice, that keeping eg. translation up do date of
wiki documentation is _very_ hard.

Wiki web page is only helper to improve or get user feedback,
not to write something.

cheers - Sergiusz
--
private: http://ibiblio.org/ser/ company: http://it-zone.org/
______________________________________________________________
on wallpaper: tldp.org, gnu.org, pld-linux.org, hyperreal.info

mlennert · October 27, 2002, 10:00am

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sun, 27 Oct 2002 02:19:31 +0200, Sergiusz Pawlowicz <ser@it-zone.org> wrote:

--->[Quoting Moritz Lennert <mlennert@club.worldonline.be>:]

> If no one objects, I will announce the wiki tutorial project
> on the users list next week in the hope to motivate some
> people to participate.

No objections, but also no support to this idea. Do not tell
me that technical reasons interfere with your mind to improve
documentation... Our expirience in Linux Documentation Project
(we require docbook or linuxdoc sgml files) is that lazy
people are not producing good documentation, how easy the tool
they use is.

Currently docbook files with grass tutorial are rendered each
five minutes from cvs, you can see output under:

http://tutorial.grass.it-zone.org/

Great ! Thanks a lot.

and everyone with simple text editor such a notepad.exe
could improve it.

The problem was with the installation of the docbook tools. Apparently
it was not easy for those without root access to deal with it. Also
see
http://lists.it-zone.org/index.cgi?3:sss:33:200209:dbkecbpifcdhdhnedhif
for a discussion of the docbook question. But, as you say, if
rendering is so immediate, maybe people don't need to worry about
docbook tools anymore.

And please notice, that keeping eg. translation up do date of
wiki documentation is _very_ hard.

Why is it harder than docbook (unless we use gettext-like tools for
docbook) ?

Wiki web page is only helper to improve or get user feedback,
not to write something.

I'm no expert, but I thought that wiki was just that, a tool for
cooperative writing ?

I'm open to discussion. I started the wiki version in order to have a
concrete comparaison and not just a theoretical discussion. So, I'm
not absoulutely fixed to that solution.

Up to now there is half of the people who seem to be confortable in
docbook and the other half who would prefer to use "simpler"
tools. The immediate rendering of the tutorial seems to take some of
the wind out of the argument against docbook. But it still
necessitates cvs write access. The wiki allows any user to add a
comment whenever they want without much hassle.

Moritz
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.0 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>

iD8DBQE9u7lPyrpWRtQydA0RAloAAJ9iTlCwceyv9651Ukw51NKjEZor4ACeJvOv
aDOzod97TWOgcDjkS2M2H68=
=h0Mh
-----END PGP SIGNATURE-----

Sergiusz_Pawlowicz1 · October 27, 2002, 10:20am

--->[Quoting Moritz Lennert <mlennert@club.worldonline.be>:]

> And please notice, that keeping eg. translation up do date
> of wiki documentation is _very_ hard.

Why is it harder than docbook (unless we use gettext-like
tools for docbook) ?

Writing something from continuosly changing web page is a
horror, is not it?

> Wiki web page is only helper to improve or get user
> feedback, not to write something.

I'm no expert, but I thought that wiki was just that, a tool
for cooperative writing ?

I do not think that cooperative writing is the thing we need.
CVS is much better, we could eg. devide the whole tutorial for
people using chapter, but I cannot imagine how many people
could write one (currently empty) chapter from scratch.

The things will change if we finish tutorial, then wiki will
be helpful to allow comments from users.

the wind out of the argument against docbook. But it still
necessitates cvs write access. The wiki allows any user to
add a comment whenever they want without much hassle.

CVS access should be granted to anyone, because it is very
safe and people cannot abuse it. But of course it is a
required step to use my rendering machine.

PS. Please move this topic only to grass-doc list

cheers - Sergiusz
--
private: http://ibiblio.org/ser/ company: http://it-zone.org/
______________________________________________________________
on wallpaper: tldp.org, gnu.org, pld-linux.org, hyperreal.info

Markus_Neteler1 · October 28, 2002, 8:11am

On Sat, Oct 26, 2002 at 05:22:53PM +0200, Moritz Lennert wrote:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi all,

After our discussion about the problems some had with docbook, I have
decided that the GRASS Wiki might be a better place for the tutorial
as I had it in mind (mainly composed of links to relevant web
pages). I therefore started to transpose it to the Wiki. The beginning
of my efforts can be found on
http://grass.itc.it/wiki/index.php/Tutorial. Please everyone feel free
to correct or complement any of the pages, there's still lots of work.

Once we've fleshed out this tutorial we might reimport it into docbook
to make something more "book-like" out of it (less links, more text)
which could then be distributed in PDF or other formats.

If no one objects, I will announce the wiki tutorial project on the
users list next week in the hope to motivate some people to
participate.

Moritz

Hi Moritz,

just a small warning: The PHPWIKI is quite unstable in my
opinion (clicking on "RecentChanges" can block the web server).
Also the PHPWIKI seems to be abandoned.

Markus

Radim_Blazek · October 28, 2002, 10:58am

On Sunday 27 October 2002 11:00 am, Moritz Lennert wrote:

The problem was with the installation of the docbook tools. Apparently
it was not easy for those without root access to deal with it.

I have docbook installed now! It was easy, I asked our administrator and he
has done it. But if I run 'make', it ends with:

docbook2html -o HTML Grass_tutorial.xml
Using catalogs: /etc/sgml/xml-docbook-4.1.cat
Using stylesheet: /usr/share/sgml/docbook/utils-0.6/docbook-utils.dsl#html
Working on:
/ssi0/ssi/blazek/GRASS/grass_doc/src/en/tutorial/Grass_tutorial.xml
jade:/ssi0/ssi/blazek/GRASS/grass_doc/src/en/tutorial/Grass_tutorial.xml:104:0:E:
URL not supported by this version
jade:E: cannot open "/usr/local/share/builtins.dsl" (No such file or
directory)
jade:/usr/share/sgml/docbook/dsssl-stylesheets-1.64/html/../common/dbtable.dsl:224:13:E:
2nd argument
for primitive "ancestor" of wrong type: "#<unknown object 136089888>" not a
singleton node list
make: *** [all] Error 8

Could anybody help me? (Some html pages were created.)

Radim

mlennert · October 28, 2002, 11:25am

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Mon, 28 Oct 2002 11:58:43 +0100, Radim Blazek <blazek@itc.it> wrote:

On Sunday 27 October 2002 11:00 am, Moritz Lennert wrote:
> The problem was with the installation of the docbook tools. Apparently
> it was not easy for those without root access to deal with it.

I have docbook installed now! It was easy, I asked our administrator and he
has done it. But if I run 'make', it ends with:

docbook2html -o HTML Grass_tutorial.xml
Using catalogs: /etc/sgml/xml-docbook-4.1.cat
Using stylesheet: /usr/share/sgml/docbook/utils-0.6/docbook-utils.dsl#html
Working on:
/ssi0/ssi/blazek/GRASS/grass_doc/src/en/tutorial/Grass_tutorial.xml
jade:/ssi0/ssi/blazek/GRASS/grass_doc/src/en/tutorial/Grass_tutorial.xml:104:0:E:
URL not supported by this version

I have

Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.11/docbook-utils.dsl#html

and I do not get the

URL not supported by this version

error message.

I use jade, not openjade.

Moritz

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.0 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>

iD8DBQE9vR6cyrpWRtQydA0RAueSAKC4R3g7f63tC9o+8odS2SN6vI29qgCcC9iL
ktD4x5UuuIztpxnjXIRPSas=
=hX5o
-----END PGP SIGNATURE-----