On Mon, Nov 07, 2005 at 09:25:52AM +0800, Joel de Guzman wrote:
>
> Oh, BTW, here's the relevant link:
> http://www.xml.com/pub/a/2004/07/14/dbndx.html
>
Just to flesh out the use-case, I played with this a bit, here's what
I came up with... Because of the way links in the index (which point
to locations of <indexterm>) and instances of [link T /T/] (pointing
to [#T]) behave differently, it looks like total automation might not
be all that straightforward.
The best I've come up with is to create a file "indexterms.dat"
containing on each line
<term> <format-char>
e.g.:
sort =
back_inserter =
Where generally each line
T ?
in indexterms.dat gets expanded by a script to (indexterms.qbk):
[def *T [link T ?T?]]
[def ~T [link T ?T?]'''<indexterm><primary>T</primary></indexterm>''']
[def !T '''<indexterm
significance="preferred"><primary>T</primary></indexterm>''']
Let all the .qbk files include macros.qbk, which contains the
ubiquitous smiley macro and in turn includes this indexterms.qbk.
Then at the central point of documentation for T "cpod(T)", you put
(longwinded):
[#T] (drops HTML anchor)
[section explanation of T]
!T (drops docbook index anchor)
(docs)
[endsect]
and elsewhere, where T is referenced, you use:
*T for a link to [#T] that does *not* appear in the index, and
~T for a link to !T that also appears in the index.
The good things are:
- the syntax is wicked terse.
- You can sprinkle your docs with links back to the cpod(T) without
cluttering the index.
- You (should be able to) get a decent index in printed form with
boldface pagenumbers for the pages where !T
(significance="preferred") appears.
The ugly bits are:
- You need both *T and ~T, because your html index can quickly get
cluttered, since it contains a list of links, the text of which is
the titles of the sections that contain the <indexterm> tags. You
use ~T only where something useful about ~T is said. If you dropped
the requirement to be able to link almost every occurance of T to
[#T] in the html, you could probably get around this, but it's nice.
When reading the docs you're almost never more than a click away
from cpod(T).
- You can't put [#T] inside the macro. quickbook would need to delay
evaluation (dropping?) of the anchor until after the macros are
expanded. e.g. [def !T [#T] '''<indexterm significance... (etc) ]
doesn't currently work. The [#T]'s appear where the macro is
defined, not where it is expanded.
- apache FOP coughs the xml back up with the enlightening error
message:
[ERROR] null
and [#T] and !T don't look like they'd be combinable in one macro
anyway, because:
- if T's central point of documentation is typically a [section ...],
then putting [#T] inside the section causes the links to act funny.
When you click on the link generated by *T, you get sent to [#T],
which is just south of the section title. So the title
"Documentation for T", which you'd like to see at the top of your
page, is "chopped off" (it is just north of the top of the browser
page, not visible. Your first impression is that the link was bad.)
- On the other hand, if !T is outside the section definition, the link
generated by docbook and placed in the index will take you to the
top of the page, not right to the definition, also giving you the
impression that the link was bad. Also, the text of the link in the
index will be the title of the outer section, not the (desired)
innermost one.
Anyhow. Sorry that got a little longwinded.
-t
-------------------------------------------------------
SF.Net email is sponsored by:
Tame your development challenges with Apache's Geronimo App Server. Download
it for free - -and be entered to win a 42" plasma tv or your very own
Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
