On 1/15/2012 4:51 PM, Kent A. Reed wrote:
2. The resolution of hyperlinks to sections in the parts.
My mental model of browsing hyperlinked documents includes the notion
that a hyperlink labeled "See the XYZ section" should take me to a page
displayed such that the section title line lies at the top of the
display window. Many, but not all, such hyperlinks in the EMC2
documentation instead take me to a page displayed such that the first
line of the body of the section lies at the top of the display window;
the section title is out of the display window. In some cases, this
leads to "where am I" confusion.
I have not had time to explore this issue. Just today, I found in one of
the parts I reviewed a perfect case of two hyperlinks side-by-side which
displayed the two different behaviors but I forgot to write it down.
When I find it again, I'll use it to figure out how to implement a
consistent style.
Ok, I found again my perfect case in gcode/o-code.html in the O-Return
Example:
"See the Binary Operators & Parameters sections for more information."
Clicking on "Binary Operators" takes one to the header "7. Binary
Operators" in gcode/overview.html. The text follows .
Click on "Parameters" takes one to the paragraph beginning "The
RS274/NGC language supports parameters..." with the header "5.
Parameters (Variables)" out of the window (also in gcode/overview.html).
The hyperlinks are syntactically the same. It is the targets that are
different.
In gcode/overview.html, the relevant portions read
---snip---
<h2 id="sec:Binary-Operators">7. Binary Operators</h2>
---snip---
versus
---snip---
<h2 id="_parameters_variables_a_id_sec_parameters_a">5. Parameters
(Variables)<a id="sec:parameters"></a></h2>
---snip---
The first form was generated by the Asciidoc source lines
---snip---
[[sec:Binary-Operators]]
== Binary Operators
---snip---
The second form was generated by the Asciidoc source line
---snip---
== Parameters (Variables)[[sec:parameters]](((Parameters)))
---snip---
Clearly, I would deprecate the second form. Given its prevalence it may
not be feasible to fix and test all the source files but I hope we
practice continuous improvement.
As an aside, I now understand how we get weird links of the form
"_something_a_id_sec_something_a". Yuck.
Regards,
Kent
------------------------------------------------------------------------------
RSA(R) Conference 2012
Mar 27 - Feb 2
Save $400 by Jan. 27
Register now!
http://p.sf.net/sfu/rsa-sfdev2dev2
_______________________________________________
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers
