Hello,
# Context
An asciidoc document like this :
-----------------------------------------------------
<<someid>>
[[someid,my section name for links]]
== Some section
-----------------------------------------------------
# Expected
Docbook and HTML outputs similar: provide a link with text "my section
name for links" to target "someid".
# Observed
Docbook provides a link with text "my section name in link" to target
"someid" (yes it's documented behavior, please read on).
HTML provides something different: a link with text "someid" to target
"someid".
# Additional information
This inconsistency was already noticed in
https://groups.google.com/forum/#!topic/asciidoc/frDhrH6acvc , and it is
indeed documented.
# Workaround
One workaround: edit the document to always provide a caption like
<<someid,my section name for links>>. This works but basically negates
the documented feature (downward levelling).
Another workaround: ditch the HTML backend and convert to HTML via a
docbook-to-HTML chain. On my system this works and happens to fit my use
case :
asciidoc --backend docbook --out-file mydoc.xml mydoc.txt
xsltproc -o mydoc.html
/usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml-1_1/docbook.xsl
mydoc.xml
But this also means losing features of asciidoc like data-uri for a
self-contained HTML, and all specific style including admonition icons
and the like (you can get them back, see e.g.
http://ds9a.nl/docbook/index.html but you changed -universe- toolchain
anyway).
# At the "macro" level: why it is important to fix that IMHO
Asciidoc (the markup language) may become a weak language with as many
flavor as implementations, like regexps (there's already asciidoctor
providing its own set of extensions, and they take care of HTML/XSLT
e.g.
http://asciidoctor.org/news/2013/09/05/asciidoctor-0-1-4-released/#inter-document-references
).
Asciidoc (the markup language) may become a strong markup language where
all implementations accept the same set of documents and produce same
output (like, say, languages (not platform libraries) like C, java, C#
or XSLT, but don't get misled by these examples).
For asciidoc (the markup language) to be strong there has to be *a
separation between markup documentation and implementation
documentation*. When asciidoc documentation actually documents mostly a
syntax but blesses inconsistent backend-dependent behavior, the very
project that started asciidoc sends the worls a "please create your own
incompatible variant of my syntax".
# At the "micro" level: how to fix ?
It looks like the current asciidoc implementation just parses the
document with one pass, performing substitution, so the information is
not locally available to produce what's needed. Is that a faithful summary ?
After looking at asciidoc source tree, things are not really clear to
me, but if at the asciidoc parsing time, the caption information is not
available, could it be a good approach to:
(1) have the HTML backend just produce some specific markup which
contains enough information.
(2) Then the asciidoc engine would allow backend to provide a
postprocessing pass.
(3) HTML backends would use that pass with some transform like xslt to
produce the HTML we want.
What do you think ?
Thank you for your attention.
--
Stéphane Gourichon
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/asciidoc.
For more options, visit https://groups.google.com/d/optout.
