Fix API entry heading vertical alignment

Styling changes necessary to make the API entry headings (such as
'Prototype' etc) to align vertically when browser window is wide.
Getting the alignment to work requires awkward margin hacks.

Also reimplement CSS styling for stacks to be more simple.

website/buildsite.py

@@ -221,32 +221,41 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 	# the 'hidechar' span is to allow browser search without showing the char
 	res.append('<h1 id="%s"><a href="#%s"><span class="hidechar">.</span>%s()</a></h1>' % (funcname, funcname, funcname))
 
+	res.append('<div class="api-call">')
+
 	if parts.has_key('proto'):
 		p = parts['proto']
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-proto">Prototype</h2>')
 		res.append('<pre class="c-code">')
 		for i in p:
 			res.append(htmlEscape(i))
 		res.append('</pre>')
+		res.append('</div>')  # api-part
 		res.append('')
 	else:
 		pass
 
 	if parts.has_key('stack'):
 		p = parts['stack']
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-stack">Stack</h2>')
 		for line in p:
 			res.append('<pre class="stack">' + \
 			           '%s' % htmlEscape(line) + \
 			           '</pre>')
+		res.append('</div>')
 		res.append('')
 	else:
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-stack">Stack</h2>')
 		res.append('<p>(No effect on value stack.)</p>')
+		res.append('</div>')  # api-part
 		res.append('')
 
 	if parts.has_key('summary'):
 		p = parts['summary']
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-summary">Summary</h2>')
 
 		# If text contains a '<p>', assume it is raw HTML; otherwise
@@ -266,26 +275,33 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 			for i in p:
 				res.append(htmlEscape(i))
 			res.append('</p>')
+		res.append('</div>')  # api-part
 		res.append('')
 
 	if parts.has_key('example'):
 		p = parts['example']
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-example">Example</h2>')
 		res.append('<pre class="c-code">')
 		for i in p:
 			res.append(htmlEscape(i))
 		res.append('</pre>')
+		res.append('</div>')  # api-part
 		res.append('')
 
 	if parts.has_key('seealso'):
 		p = parts['seealso']
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-seealso">See also</h2>')
 		res.append('<ul>')
 		for i in p:
 			res.append('<li><a href="#%s">%s</a></li>' % (htmlEscape(i), htmlEscape(i)))
 		res.append('</ul>')
+		res.append('</div>')  # api-part
+		res.append('')
 
 	if testcase_refs:
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-testcases">Related test cases</h2>')
 		if testrefs.has_key(funcname):
 			res.append('<ul>')
@@ -294,12 +310,15 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 			res.append('</ul>')
 		else:
 			res.append('<p>None.</p>')
+		res.append('</div>')  # api-part
+		res.append('')
 
 	if not testrefs.has_key(funcname):
 		res.append('<div class="fixme">This API call has no test cases.</div>')
 		
 	if list_tags and parts.has_key('tags'):
 		# FIXME: placeholder
+		res.append('<div class="api-part">')
 		res.append('<h2 class="api-tags">Tags</h2>')
 		res.append('<p>')
 		p = parts['tags']
@@ -308,6 +327,7 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 				res.append(' ')
 			res.append(htmlEscape(val))
 		res.append('</p>')
+		res.append('</div>')  # api-part
 		res.append('')
 
 	if parts.has_key('fixme'):
@@ -318,6 +338,7 @@ def processApiDoc(parts, funcname, testrefs, used_tags):
 		res.append('</div>')
 		res.append('')
 
+	res.append('</div>')  # api-call div
 	return res
 
 def processRawDoc(filename):

website/style-api.css

@@ -7,17 +7,24 @@
 	 * to make the entries more compact.
 	 *
 	 * Specificity must override normal section heading rules.
+	 *
+	 * The challenge here is to keep the section heading vertically
+	 * aligned with the content on the right.  To do this, we need
+	 * to avoid top margins in the elements on the right (paragraphs,
+	 * stacks, <pre>-blocks) which is a bit hackish.  The api-part
+	 * div margins are then used to provide spacing between the API
+	 * documentation parts.
 	 */
-	/* FIXME: layout is pretty inconsistent now */
+
-	h2.api-proto,
+	.api-call h2.api-proto,
-	h2.api-stack,
+	.api-call h2.api-stack,
-	h2.api-summary,
+	.api-call h2.api-summary,
-	h2.api-example,
+	.api-call h2.api-example,
-	h2.api-seealso {
+	.api-call h2.api-seealso {
 		position: absolute;
 		left: 10px;
 		margin: 0;
-		padding: 5px 0 0 0;
+		padding: 0 0 0 0;
 		width: 200px;
 		text-align: right;
 		height: 0;
@@ -25,4 +32,23 @@
 		color: #ccccdd;
 		font-size: 100%;
 	}
+
+	.api-part {
+		margin: 3ex 0 3ex 0;
+	}
+
+	.content .api-call .stack-wrapper {
+		margin-top: 0;
+		margin-bottom: 2ex;
+	}
+	.content .api-call .stack {
+		margin-top: 0;
+	}
+
+	.content .api-call p {
+		margin-top: 0;
+	}
+	.content .api-call pre {
+		margin-top: 0;
+	}
 }

website/style-content.css

@@ -276,6 +276,8 @@ ul.breakdown li {
 
 .content .stack-wrapper {
 	display: block;
+	margin-top: 1ex;
+	margin-bottom: 2ex;
 }
 
 /* narrow layout: smaller font */
@@ -289,26 +291,16 @@ ul.breakdown li {
  * them aligned
  */
 .content .stack-wrapper .arrow {
-	display: inline-block;  /* for "shrink-to-fit" */
+	display: inline-block;
-	overflow: auto;  /* clear fix */
+	margin: 0 0.1em 0 0.1em;
-	width: auto;
+	padding: 0;
-	background: #ffffff;
-	margin: 1ex 0.1em 1ex 0.1em;
-	border: 2px solid #ffffff;
-	border-radius: 10px;
-	box-shadow: 3px 3px 5px #ffffff;
-	padding: 1ex 0.1em 1ex 0.1em;
 	vertical-align: middle;
 }
 
 .content .stack-wrapper .arrow b {
-	float: left;
+	display: inline-block;
 	min-width: 1.25em;
-	background: #ffffff;
+	margin: 0;
-	margin: 0.1ex 0.1em 0.1ex 0.1em;
-	border: 1px solid #ffffff;
-	border-radius: 5px;
-	box-shadow: 1px 1px 3px #ffffff;
 	padding: 0;
 	vertical-align: middle;
 	text-align: center;
@@ -316,27 +308,25 @@ ul.breakdown li {
 }
 
 .content .stack-wrapper .stack {
-	display: inline-block;  /* for "shrink-to-fit" */
+	display: inline-block;
-	overflow: auto;  /* clear fix */
-	width: auto;
 	background: #eeeeee;
-	margin: 1ex 0px 1ex 0px;
+	margin: 0;
 	border: 2px solid #888888;
 	border-radius: 10px;
 	box-shadow: 3px 3px 5px #bbbbbb;
-	padding: 1ex 1em 1ex 1em;
+	padding: 0.7ex 1ex 0.7ex 1ex;
 	vertical-align: middle;
 }
 
 .content .stack-wrapper .stack .elem {
-	float: left;
+	display: inline-block;
 	min-width: 1.25em;
 	background: #cccccc;
-	margin: 0.1ex 0.1em 0.1ex 0.1em;
+	margin: 0;  /* space chars between spans are enough */
 	border: 1px solid #888888;
 	border-radius: 5px;
 	box-shadow: 1px 1px 3px #bbbbbb;
-	padding: 0.5ex 0.5em 0.5ex 0.5em;
+	padding: 0.5ex 0.35em 0.5ex 0.35em;
 	vertical-align: middle;
 	text-align: center;
 }
@@ -372,10 +362,12 @@ ul.breakdown li {
 }
 
 .content .stack-wrapper .stack-comment {
-	float: right;
+	display: inline-block;
-	margin: 0.1ex 0.3em 0.1ex 2em;
+	margin: 0 0 0 2em;
-	padding-top: 3ex;
+	padding: 0;
-	width: 20em;
+	vertical-align: middle;
+	text-align: center;
+	font-size: 12pt;
 	color: #888888;
 }