[GRASS5] [bug #2820] (grass) v.build: discuss mysterious "support files"

[Markus Neteler]

On Thu, Dec 09, 2004 at 12:15:56AM +0100, Request Tracker wrote:
> this bug's URL: http://intevation.de/rt/webrt?serial_num=2820
> -------------------------------------------------------------------------
> 
> In the v.build documentation, discuss these mysterious "support
> files". Perhaps they are the files that live in .../dbf/... .  Perhaps
> they are the files called cidx coor dbln head hist sidx topo ... no it
> couldn't be them.
> 
> Say just when one would need to use v.build. I mean who would want to
> go thru life without "support". And the more support, and the more
> often, the better.

Question: Why not reading more than the first line?

Citation:
http://grass.itc.it/grass57/manuals/html57_user/v.build.html

"DESCRIPTION
 These support files supply topology and category information
 that are needed by other GRASS programs
"

> Show how one can determine if one doesn't have support, but should,
> and if one has support, but it isn't needed, etc.

I have added now:
"GRASS is generating these support files automatically,
 only in rare cases the user has to (re)build them.
"

No, I won't explain "rare cases" in the documentation.
A rare case occurs if e.g. Radim asks the user to run v.build to
rebuild the topology for existing 5.7 maps in case of a format
change. Happened a very few times in the past.

> Also,
> Parameters:
>    error   Name of vector where errors are written
> Say what will happen if we don't give this. Do our errors go up in
> smoke...etc? Will we still be informed of them? Say so.

Yes, Sir.

Changed the message to:
-    err_opt->description  = "Name of vector where errors are written";
+    err_opt->description  = "Name of vector map where erroneous vectors are written to";

and added 
+In case of errors, the user can optionally generate an error
+vector map containing the erroneous vectors for later inspection.

to the documentation.
 
> don't say "write topology to stdout"
> say "build topology, but only write it to stdout, not the files"

Why? This is not the case.

> or "don't build topology, instead only write any topology already
> found to stdout..."

Even not the case.

Markus