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>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.4.31.0102221744050.7245-100000>