From owner-freebsd-doc Sat Oct 28 14:12:46 2000 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 4407937B4CF for ; Sat, 28 Oct 2000 14:12:40 -0700 (PDT) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.11.0/8.11.0) id e9SKXKm02946; Sat, 28 Oct 2000 21:33:20 +0100 (BST) (envelope-from nik) Date: Sat, 28 Oct 2000 21:33:20 +0100 From: Nik Clayton To: Michael Lucas Cc: doc@freebsd.org Subject: Re: linking to FAQ? Message-ID: <20001028213319.A2503@canyon.nothing-going-on.org> References: <20001027123838.B86573@blackhelicopters.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20001027123838.B86573@blackhelicopters.org>; from mwlucas@blackhelicopters.org on Fri, Oct 27, 2000 at 12:38:38PM -0400 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Michael, On Fri, Oct 27, 2000 at 12:38:38PM -0400, Michael Lucas wrote: > I'm planning a project where I need to link to various portions of the > FAQ. Being new to the innards of the FreeBSD docs, please pardon me > if this is a damnfool question. :) > > Looking through the FAQ, I see that the various questions are marked > as: > > admin.html#AEN2328 > > Are those links constant? For example, if I say "to mount other > foreign filesystems under FreeBSD, see , > will that still work when you add something earlier up in the FAQ? Or > do those numbers change? Yes and no. Numbers like that are automatically generated by the doc build process, and are subject to change at every opportunity. Currently, the stylesheets generate them by taking the string AEN (Automatic Element Number, I guess) and then appending the current element number. The current element number is going to change every time a new element (such as , or even ) is added to the document, so while it's stable over multiple generations of the same document, as soon as a new element is added the numbers all change. Fortunately, we have finer grained control than this. If an 'id' attribute exists on the element then the stylesheets will use that instead. So question 6.1 in the FAQ looks something like this: I'd like to customize my kernel. Is it difficult? ... which means that you can reach this question by going to book.html#MAKE-KERNEL (notice that the attribute values are uppercased, although in reality, the browsers shouldn't care). So, if you want to supply us with sensible id values for the question's you're going to be linking to (or better still, a patch to the book.sgml which does it). That's option 1. Option 2, which is less stable, is something I'm about to commit to the tree. At the moment, questions aren't numbered. Clearly I'd picked up the crack pipe a bit too frequently, and had elected to turn off the numbering. I'm just about to turn that on. I'm also going to commit a little bit of DSSSL code that changes the generation of NAMEs for elements that don't have an ID. Instead of using AEN + the element number, for questions it will now be "Q" plus the question number (e.g., 6.2.) so you might link to http://www.freebsd.org/faq/admin.html#Q7.8. Note the trailing '.', it's required. That's less stable than supplying us with IDs, because if a new question is added before this one in section 7 then a renumbering will happen. But it's better than what we've got at the moment. Hope that helps. 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