This is the mail archive of the gdb@sources.redhat.com mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: memory region documentation


> From: jtc@redback.com (J.T. Conklin)
> Date: 16 Nov 2000 11:05:29 -0800
> 
> However, this exercise has reminded me why I'm a programmer and not a
> tech writer.

Actually, what you wrote was very good; the comments I had were pretty
much minor.

> >> @subsection Memory Access Mode 
> >> [...]
> >> @subsection Memory Access Size
> >> [...]
> >> @subsection Data Cache
> 
> Eli> Here, too, I'd suggest @cindex entries.
> 
> This seems a bit odd to me.  These are pretty generic concepts.  If I
> was browsing the index I'm not sure I'd expect that they'd be related
> to memory regions.

Indices are for quickly finding something that you know or suspect
to be somewhere in the manual.  That is, you don't look in the index
to find what's in the book---that's what the TOC or the top-level menu
is for---but when you use the manual as a reference.

When that happens, it is perfectly okay to have an index entry which,
under other circumstances, would sound as a generic concept, provided
that the index entry points to the place where those concepts are
discussed in depth in the manual.

> On the other hand, if I wanted to set the memory access width, it
> would take me to the right page.

That is exactly the purpose of an index.  Imagine someone looking for
this specific piece of information, and ask yourself whether it would
be reasonable for that person to try to type "memory access mode".

I usually find the info-search command (bound to the `i' key) to be
the most efficient means of finding specific information in a manual.
When you use index-search, the situation when someone browses the
index is not the most important one.

> Can you tell me where you'd like me to put this chapter?  I assume
> it's a chapter, since it doesn't seem to be a good fit into any of
> the existing chapters --- especially if we start adding more varied
> attributes.

It looks like making this a chapter is the right thing.

As to its place, it is not very important.  You need to add an entry
to the top-level menu (in the @top node) that leads to this new node
you've written, and you need to insert the text somewhere in the
file.  It is customary to put the node between the same nodes as the
menu entry in the top-level menu (but IIRC this is not required,
strictly speaking).

It looks like between "Native Debugging" and "Support Libraries" would
be a good place.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]