Thank you Lex for this informative reply. Perhaps part of it should
included in the documentation itself.
Using the browser as a toolchain reminds me a few years ago when it was
discussed if XSL-FO should be included in browsers (to allow more
semantic content) and the discussion concluded "WONTFIX? -- bad for the
web" because it would no doubt me misused and irreversibly engage in a
web without semantics at all.
For details see https://bugzilla.mozilla.org/show_bug.cgi?id=95959 .
Le 24/03/2014 21:36, Lex Trotman a écrit :
What may not be clear is that this applies to HTML too. The browser
is the toolchain and the processing is defined by CSS and Javascript.
The Javascript generates the table of contents and footers, they are
not generated by the Asciidoc translator since it is single pass and
does not have the information to generate them (especially as the toc
is usually output *before* any of the contents it refers to). This
limitation on available information to the translator also applies to
xref links (especially forward ones).
Thank you! Generating the TOC in Javascript appeared to me like a hacky
workaround. I understand better how it actually fits the pattern exactly.
The advantage of the single pass implementation is however that it
does not have any limits on the size of the document it processes.
What this long winded intro is coming to is that therefore you should
look at modifying the HTML **toolchain** to perform the link
processing, ie the Javascript.
Once one gets the pattern, your answer fits very well.
My suggestion in initial message then is starting to look like the start
of reinventing the docbook backend *and* process it inside asciidoc, so
forget it.
The Javascript for the TOC provides an example of such post
processing, a similar Javascript could modify the link text to the
text labelled by the link if the xref was captionless (ie the text was
the link in []).
Let's assume such Javascript for link text is done and look at the way
forward.
## Remaining trouble: two problems
The trouble with this one-pass approach toward a "toolchain" browser is
that it requires a smart enough toolchain and since that "toolchain"
browser is client-side we cannot guarantee anything. Yes I know it's
still graceful degradation and see the intellectual point, but in
practice people do complain and many programs able to read HTML don't
get it.
I see the point, somehow the HTML produced by asciidoc is "elegant",
"doesn't repeat itself".
Yet who expects a HTML document to come up without TOC and/or with
crippled link texts when opened in a different HTML-reading program ?
People will see that as a bug and curse asciidoc.
I understand better the "split" nature of asciidoc now, which brings
forward a related problem.
Problem 1 (as per initial message) : users (I can't be the only one) are
attracted by asciidoc and its nice HTML style but they need to provide a
HTML that can be read by "dumb" readers, or are pushed away by the
missing link text handling we discussed.
Problem 2: regularly (see list archive) people are attracted by asciidoc
and its nice HTML style but they need PDF too and are pushed away when
realizing that the docbook path starts with next to no style, rough
edges and some differences with HTML. And the list often (politely)
says: hey it's a docbook problem, we can't provide full support.
Let's take a metric for problem 2: the easiest way to make a
nice-looking PDF (not the default FOP or LaTeX appearance) from an
asciidoc source, in a scripted way.
Try 1: open in firefox and print to PDF. Result: big images are cropped
on the right. Headers/footers have to be set again and again. Plus it's
not scripted.
Try 2: ask OpenOffice to read that HTML and produce PDF. Can be
scripted. Result: lost table of content, lost link text.
Try 3: use https://github.com/dagwieers/asciidoc-odf, curse OpenOffice
and give up (I don't remember what was bad enough).
Try 4: use a2x. Dull style. Steep learning curve, either FOP or dblatex
side. I was fortunate to know LaTeX, made my style from scratch and am
happy with it. Not everyone will do.
## Suggestions
Suggestion: include in asciidoc distribution a docbook toolchain setup
that produces HTML referring to the same CSS as the html backend. It
will have all the benefits of docbook backend (TOC, link text, images
fit, scripted). It will solve problem 1.
Consider the resemblance with ghostscript's feature to parse a PDF and
produce a "flattened" PDF.
Suggestion: include in asciidoc distribution a FOP and/or a dblatex
setup that produces PDF with an *appearance* close to that of the
default one-pass HTML output. (Don't just tell style foo and bar were
mentioned already on the list, I know that and it's not salient enough
for users.) It will have all the benefits of docbook toolchain (TOC,
link text, images fit, scripted) with a good-looking style. It will
solve problem 2 and double as a starting point for users to hack their
style, big win for everyone.
PPS There is also a Ruby implementation (asciidoctor) that accumulates
the whole document in memory and does static toc and footer
generation, this allows it to be used in places like Github README
markup where it can't serve Javascript. But this is of course
blurring the lines of presentation and content further.
This is interesting, too. It allows to consider asciidoctor in a
toolchain perspective and wonder if it's better or not.
Using the browser as a toolchain reminds me a few years ago when it was
discussed if XSL-FO should be included in browsers (to allow more
semantic content) and the discussion concluded "WONTFIX? -- bad for the
web" because it would no doubt me misused and irreversibly engage in a
web without semantics at all.
For details see https://bugzilla.mozilla.org/show_bug.cgi?id=95959 .
--
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.
