From owner-freebsd-doc  Thu Feb 22 18: 1:25 2001
Delivered-To: freebsd-doc@freebsd.org
Received: from meow.osd.bsdi.com (meow.osd.bsdi.com [204.216.28.88])
	by hub.freebsd.org (Postfix) with ESMTP id 384CB37B491
	for <freebsd-doc@freebsd.org>; Thu, 22 Feb 2001 18:01:22 -0800 (PST)
	(envelope-from murray@osd.bsdi.com)
Received: from localhost (murray@localhost)
	by meow.osd.bsdi.com (8.11.2/8.11.2) with ESMTP id f1N1x4812570
	for <freebsd-doc@freebsd.org>; Thu, 22 Feb 2001 17:59:04 -0800 (PST)
	(envelope-from murray@osd.bsdi.com)
Date: Thu, 22 Feb 2001 17:59:04 -0800 (PST)
From: Murray Stokely <murray@osd.bsdi.com>
To: <freebsd-doc@freebsd.org>
Subject: Indexing the Handbook
Message-ID: <Pine.BSF.4.31.0102221744050.7245-100000@meow.osd.bsdi.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

  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.

  The marked up chapter that I worked on is available at
http://www.freebsd.org/~murray/chapter.sgml.  To build this you
should also apply http://www.freebsd.org/~murray/book.patch to you
developers-handbook/book.sgml so that the created index will show up.
You should then build with "GEN_INDEX=yes".

  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>

  Does this look acceptable or should I change the placement of
indexterms a bit?

	- Murray



To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message