From owner-freebsd-doc Fri Feb 23 2: 5:29 2001 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id DBDF337B491 for ; Fri, 23 Feb 2001 02:05:21 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.11.1/8.11.1) id f1NEehC47026; Fri, 23 Feb 2001 14:40:43 GMT (envelope-from nik) Date: Fri, 23 Feb 2001 14:40:43 +0000 From: Nik Clayton To: Murray Stokely Cc: freebsd-doc@freebsd.org Subject: Re: Indexing the Handbook Message-ID: <20010223144043.A46865@canyon.nothing-going-on.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: ; from murray@osd.bsdi.com on Thu, Feb 22, 2001 at 05:59:04PM -0800 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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 > , , and 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. > > 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. > > LIFO > > process image > stack pointer > > > When a program invokes a function a new "stack frame" is > created. > > stack frame > stack pointer > > 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. > > frame pointer > > process image > frame pointer > > return address > > 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. > > 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. > > bounds checking > > 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. 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 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? stack frame"> 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