new documentation format for std.algorithm

[Adam Ruppe]

Andrei Alexandrescu:
> Hmmm, this wrong jumping is a problem. I'll look into it. Offhand I
> don't know how to distinguish in the generated doc between an enum value
> and a function, but Adam did it. Adam?

My method is to track the level of nesting. The more <dl> tags above
you in the tag tree, the further down you are.

The generated html puts everything in a <dl> html tag. It goes:

<dl>
   <dt>Function <u>name</u> and prototype</dt>
   <dd>Information about it</dd>
</dl>

For enums (and probably structs/class methods too, but I haven't
confirmed yet), the sub-members are in that dd, like so:

<dl>
    <dt>Enum Name</dt>
    <dd>Enum description
       <dl>
           <dt>Member #1 name</dt>
           <dd>Member #1 description</dd>
       </dl>
     </dd>
</dl>



So, if you keep track of how many <dl>'s are above you in the
tree, you know what your parent is - are you a top level function
or a member of another object?

If you're a member of another object, you go up the tree a couple
levels (get past your <dl>, then past the enclosing <dd>) and
find the <dt> that is the last sibling to your grandparent.

That holds the name of the enum.

Here's my javascript implementation:

function getParentTerm(e) {
	while(e) {
		if(e.tagName == "DD")
			return e;
		e = e.parentNode;
	}

	// we have the definition, gotta get the term right above it

	if(e == null)
		return null; // has no parent

	var r;
	var arr = e.parentNode.childNodes;
	for(var p = 0; p < arr.length; p++) {
		var a = arr[p];
		if(a.tagName == "DT")
			r = a; // store the last term we saw...
		if(a == e) // if we're back to ourselves...
			return r; // ... the last term is the answer
	}
	//assert(0);
}



Since the actual function names are underlined, you can get
a full name by searching the returned term for a <u> tag and
pulling it out. While parent !is null, name = parent.name ~ "." ~
name, done.

If you found the child a[name] elements and replaced the name
attribute with the result from above, the links would all work too.


I have an almost working D implementation too, but the HTML isn't
well formed xml so my library butchers it a bit on output. That needs
to be fixed before ditching the javascript. Then, I figure, we can
add the helper program in between dmd itself and the live site.


Anyway, I know what's wrong and how to fix it, but haven't written
the last pieces of code to actually do it yet... after that, we
just have some presentation issues to finalize and we're set.