Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify rules for forming and using anchors and ids #666

Open
rockyallen opened this issue May 4, 2017 · 0 comments
Open

Clarify rules for forming and using anchors and ids #666

rockyallen opened this issue May 4, 2017 · 0 comments

Comments

@rockyallen
Copy link
Contributor

rockyallen commented May 4, 2017

Section http://asciidoctor.org/docs/user-manual/#anchordef conflates "Anchors" and "IDs", but they are not the same.
I think the difference is that [[x]] on a line by itself (ie a "block") is an ID for the subsequent block element,
whereas [[x]] with any other text on the line (ie "inline") is an anchor within that block.

  1. You can have multiple anchors in the same block, even if they are adjacent:
 [[a1]]Some [[a2]][[a3]]text

but a block can have only 1 ID, so this is wrong:

[[a1]]
[[a2]]
== Title
See <<a1>>
  1. IDs can have an xreflabel, but anchors can't (is this a bug?)
[[mypet,my last pet]]
== Tiger
See <<mypet>>.

renders as See my last pet.

but

[[mypet,my last pet]]Tiger
See <<mypet>>.

renders as See [mypet].

So for anchors you have to put the xreflabel on the xref instead

See <<mypet,my last pet>>
  1. Names must start with a letter or underscore, and can only contain upper or lower case letters, digits, underscores, hyphens, and periods.
  2. To be portable, names must be unique within the complete document, and must not rely on case to distinguish them. (HTML may work OK if this restriction is violated (tested with Firefox), but DocBook will fail validation.)
  3. Recommend that names are lower case to make it easier not to violate rule 4.
  4. Cross references should use the correct case. (Browsers should not care, but DocBook/FOP will fail).

Google:
An xml:ID value must be an NCName. This means that it must start with a letter or underscore, and can only contain letters, digits, underscores, hyphens, and periods.
An HTML5 id must contain at least one character, must not contain any space characters, all values are case-insensitive.
In HTML 4 additionally may not begin with a number.

From testing:
Asciidoctor only accepts valid HTML 4 names.
Uniqueness is not enforced.
Inline anchors become anchors in docbook, html4 and html5.
Block ids and id= become ids.
Anchors in Firefox are case sensitive. Haven't tested other browsers.
From #840 this apparently generates an ID not an anchor (check it)

== Title [[titleid]]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant