Add anchors to reference.md for each piece of syntax
We should be able to write links to reference.md
for each piece of syntax, and get a link to the point where that syntax is defined and discussed.
To do this in markdown, we need explicit HTML, as in:
<a name="anchorname"></a>
But apparently, that makes for crappy results when you link to the anchor in CSS. The only thing that seems to work well with rustdoc is
<span id="anchorname">...</span>
over an appropriate paragraph. The initial <span>
tag has to be on the same line as the start of the paragraph or rustdoc misrenders it all.
Experimentation suggests that div
can perform nicely if it covers a whole section, or if you use html to insert a dummy paragraph at the end, as in:
<div id="foo">
Text here paragraph 1.
Text here paragraph 2.
<span></span>
</div>
I suggest the following schema:
-
x:foo
: Document the expansion for$foo
. Examples:#x:fname
,#x:tdefgens
,#x:when
,#x:if
. -
c:foo
: Document the condition "foo", as in${if foo {...}
). Examples:#c:any
,#c:v_is_named
,#c:false
. -
t:foo
: Document the general topic "foo". (This one I am less sure of.) Examples:#t:repetition
. -
s:foo
: Document some other piece of syntax written as "foo". (This one I am less sure of.) Examples:#s:for_struct
,#s:expect_items
.
Thoughts?
Edited by Nick Mathewson