Date: Sat, 28 Oct 2000 21:33:20 +0100 From: Nik Clayton <nik@freebsd.org> To: Michael Lucas <mwlucas@blackhelicopters.org> Cc: doc@freebsd.org Subject: Re: linking to FAQ? Message-ID: <20001028213319.A2503@canyon.nothing-going-on.org> In-Reply-To: <20001027123838.B86573@blackhelicopters.org>; from mwlucas@blackhelicopters.org on Fri, Oct 27, 2000 at 12:38:38PM -0400 References: <20001027123838.B86573@blackhelicopters.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <a href=admin.html#AEN2328>,
> 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 <para>, or even <emphasis>) 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:
<question id="make-kernel">
<para>I'd like to customize my kernel. Is it difficult?</para>
</question>
<answer>
...
</answer>
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20001028213319.A2503>