Re: New scope checking patch

Jim Blandy
2008-01-30T18:06:47Z

On Jan 30, 2008 4:05 AM, Rob Quill <rob.quill@gmail.com> wrote:
> I have attached the docs patch below. I wasn't sure how much to put in
> the docs, so I just put a small paragraph in the place which seemed
> most appropriate. Any feedback is much appreciated.

I think you can be more expansive than that --- don't be shy! :)
There are two points of view to consider when you write documentation:

1) Think of someone who is writing scripts and needs your feature.
Where would they look for it in the manual? What terms would they
look up in the index?

2) Think of someone who is aware of the feature, but wants full
details on how it works. The GDB manual is also the reference manual
--- how should a reference manual describe this feature? What does a
script author need to know to decide whether the feature does what
they want, and whether they've used it correctly?

If the feature should be mentioned in more than one place, then there
should be one complete description, and the others should reference
it.