Date: Fri, 23 Feb 2001 14:40:43 +0000 From: Nik Clayton <nik@freebsd.org> To: Murray Stokely <murray@osd.bsdi.com> Cc: freebsd-doc@freebsd.org Subject: Re: Indexing the Handbook Message-ID: <20010223144043.A46865@canyon.nothing-going-on.org> In-Reply-To: <Pine.BSF.4.31.0102221744050.7245-100000@meow.osd.bsdi.com>; from murray@osd.bsdi.com on Thu, Feb 22, 2001 at 05:59:04PM -0800 References: <Pine.BSF.4.31.0102221744050.7245-100000@meow.osd.bsdi.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Feb 22, 2001 at 05:59:04PM -0800, Murray Stokely wrote:
> After looking through Nik's changes to make indexing available I
> went ahead and marked up a chapter from the Developer's Handbook with
> <indexterm>, <primary>, and <secondary> tags. I added 42 index
> entries to the chapter all together. Adding index entries into the
> middle of the paragraph really breaks up the flow so I wanted to see
> what everyone thought about style practices for adding index entries.
OK. This isn't something I've got a huge amount of experience with.
> Here is an example from that chapter that shows the style I used to
> mark index entries. If there are no objections with this code then I
> would like to commit it shortly.
>
> <para>Most modern computer systems use a stack to pass arguments to
> procedures and to store local variables. A stack is a LIFO
> (last in first out) buffer in the high memory area of a process
> image.
>
> <indexterm><primary>LIFO</primary></indexterm>
> <indexterm>
> <primary>process image</primary>
> <secondary>stack pointer</secondary>
> </indexterm>
>
> When a program invokes a function a new "stack frame" is
> created.
>
> <indexterm><primary>stack frame</primary></indexterm>
> <indexterm><primary>stack pointer</primary></indexterm>
>
> This stack frame consists of the arguments passed to the
> function as well as a dynamic amount of local variable space.
> The "stack-pointer" is a register that holds the current
> location of the top of the stack. Since this value is
> constantly changing as new values are pushed onto the top of the
> stack, many implementations also provide a "frame pointer" that
> is located near the beginning of a stack frame so that local
> variables can more easily be addressed relative to this
> value. <xref linkend="COD">
>
> <indexterm><primary>frame pointer</primary></indexterm>
> <indexterm>
> <primary>process image</primary>
> <secondary>frame pointer</secondary>
> </indexterm>
> <indexterm><primary>return address</primary></indexterm>
>
> The return address for function calls is also stored on the
> stack, and this is the cause of stack-overflow exploits since
> overflowing a local variable in a function can overwrite the
> return address of that function, potentially allowing a
> malicious user to execute any code he or she wants.</para>
>
> <para>Although stack-based attacks are by far the most common,
> it would also be possible to overrun the stack with a heap-based
> (malloc/free) attack.</para>
>
> <indexterm><primary>bounds checking</primary></indexterm>
>
> <para>The C programming language does not perform automatic
> bounds-checking on arrays or pointers as many other languages
> do. In addition, the standard C library is filled with a
> handful of very dangerous functions.</para>
Right.
My main concern is that in talking with a few people at various
conventions it seems that getting a good index involves more than just
sprinkling <indexterm> liberally around the document.
I've got no idea how we select good terms to index, and again, the
feedback I've had suggests that it's much more an art than a science.
Which probably means we can't write rules and procedures for it :-)
Do we also run the risk of having lots of different index terms, all
subtly different? I don't know.
What are the {Linux,Gnome,KDE} Documentation Projects doing about this,
if anything?
Is this something we could use entities for?
<!ENTITY index.p.stack_frame
"<indexterm><primary>stack frame</primary></indexterm>">
and then write
&index.p.stack_frame;
in the documentation?
As I say, I don't know.
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010223144043.A46865>