[...] >> 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.
The XSLT generated HTML is static html, but of course being a separate toolchain it needs setting up. I don't use it much so I can't say how similar its output is to the standard Asciidoc. Someone with more javascript experience than me could comment on the possibility of using node.js to run the javascript outside the browser and generate a static HTML like other toolchains. Also do the non-browser tools "get" the CSS formatting? > > > 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. Again, use the XSLT toolchain if you want static HTML. The differences are even noted in the User Guide :) Or use asciidoctor, but its default theme doesn't match asciidoc's. > > > 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. Well, the asciidoc program is unlikely to ever handle anything that needs access to content it hasn't seen yet. Other implementations such as asciidoctor or post-asciidoc toolchains do that. Re-implementing that functionality seems a waste of effort, but as I said, perhaps the Javascript can be run standalone or an alternative postprocessor provided using Python XML handling, but "somebody"(tm) needs to do it. Such tools either need to be multi-pass (as Latex is, but thats slooow) or fit the entire document into memory, fine for a few pages of help file, but I suspect not for War and Peace. > > 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. Well, I usually say something like "somebody here might be able to help, but you are more likely to get help on <specific toolchain> list". Sadly this seems to be true, its not very often that anybody helps. Maybe the people using Asciidoc are just too busy. > > 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. You could always contribute it back to the community then, so people don't have to re-create it. Nothing will happen in an open source project if nobody answers questions they know the answer to (or become interested and find out) and if they do not contribute the solutions they have found back. At the moment Asciidoc is in the position that its original developer has effectively retired so it is looking for more contributors. In particular we need to move the website off his servers to allow updates to follow the github source. Then I think contributions for the toolchains could be more prominently displayed, perhaps as a wiki so everyone can contribute. At the moment many contributions are spread around and get lost :( > > ## 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. > As above, thats certainly a possibility as a "lightweight" toolchain in addition to the existing ones. > 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. > > As above. > > > >> 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. It should be noted that asciidoctor is not a competitor to asciidoc, it implements the same markup. It simply has a different use-case and implementation. All kudos to Dan and the guys for realising that documents have a long life and backward compatibility is absolutely important to avoid imposing the costs of updating documents on all projects using the markup. If asciidoctor fits your use better then use it. Of course its default styling is also different, more in keeping with its use-case I guess, but I understand it supports themes, so maybe contribute an "Asciidoc Classic" theme to that project. Cheers Lex > [...] -- 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.
