Add AsciiDoc Reader / AsciiDoc input support #1456
Comments
|
I have started working on this, it might not be ready for a few months. |
|
Have you tried going AsciiDoc -> DocBook -> Pandoc? Can you describe the shortcomings of doing this if you have? |
|
Thanks for your positive comment! I personally have not tried the conversion chain as you mentioned. The current choices are bulky with regards to its dependencies, while not being and not aspiring to be universal markup translators, like pandoc. Going through intermediate formats instead of one pandoc invocation seems hacky to me. Recently, I read about two publishing houses switching away from LaTeX and moving to AsciiDoc as their source format, so I gather that it fulfills the needs of technical writing well, also regarding referencing and I find it useful to have another capable plain-text format for documents, if software support is good and can easily convert between different formats and offers multiple output choices. Which is where this feature would come in ;-) I personally would also like to write articles and possibly a book rather in AsciiDoc than LaTeX, which is - at least my personal - motivation for this feature. |
|
|
|
I can testify that this would be a very useful addition to pandoc, thanks in advance mr. mpickering! |
|
PR #2100 contributes a basic AsciiDoc reader (with many features not yet implemented). |
|
I commented on the #2100 |
|
I agree to that asciidoc is getting popular. I've just tried to convert the book Pro Git 2 into epub using pandoc and soon noticed that the book was coded in asciidoc, and pandoc was unable to read it. |
|
I’ve tried an asciidoc > html (via https://github.com/asciidoctor/asciidoctor) > epub (via pandoc) conversion chain and it works extremely well except for the following issue. Asciidoctor wraps all HTML elements in divs with additional classes. This stops pandoc from splitting the epub automatically at headings, because it will never see a 'naked' h1 etc. Also mentioned this issue here: asciidoctor/asciidoctor#184 The ePub file I created using this method did not pass epubcheck 3.0.1 because it contained one duplicate ID (something I could have avoided). More seriously, the way footnotes are handled is not compliant, and raised several errors like this: (paths truncated with ellipsis at start) At the risk of stating the obvious, it's important that pandoc-generated epubs from any source format avoid epubcheck validation errors, as authors and publishers may need to submit these epubs to storefronts that will require epubcheck compliance (i.e. Smashwords, iBooks). Many of the Github-hosted CLI epub generators I've tried (e.g. https://github.com/avdgaag/rpub) omit consideration of epubcheck compliance, so this may not be an obvious point after all. The most common point of failure seems to be the manifest, which pandoc does correctly, which is great. But it could be yet more robust, as the above errors indicate. |
|
+++ Ben Hourigan [Jul 05 15 08:56 ]:
You could handle this easily with a filter that strips out the
When I convert pandoc's README to epub3, I see no errors My guess is that the HTML footnotes produced by asciidoctor If you attach a short sample file (of HTML produced by Unfortunately, there's no standard way of doing footnotes |
|
Hope this is a sufficient sample: <div class="paragraph">
<p>… the kind of politics that the liberal economist F. A. Hayek called “socialist.” <span class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnote_1" title="View footnote.">1</a>]</span></p>
</div> |
|
Could you attach or link to the generated (noncompliant) epub itself? |
|
By the way, here's a simple filter ( import Text.Pandoc.JSON
main = toJSONFilter undiv
where undiv (Div (ident, ["content"], kvs) bs) = bs
undiv b = [b] |
|
Depending on how asciidoc formats the notes, you may be able to get the HTML reader to parse them as notes. If you use |
Sorry, this is a bit misleading. Since a filter is applied only after the HTML reader, this wouldn't work unless you first filtered, then piped the resulting HTML into another invocation of pandoc. Anyway, there are numerous tools you could use to insert the type attribute where it's needed in the HTML, before passing to pandoc. |
|
Or maybe asciidoctor could be persuaded to insert the needed |
|
Actually, rather than the epub itself, it would be most useful for me to have the HTML from which it was generated. |
|
Thanks for the filter. Will try this out. You can get the HTML file from https://www.dropbox.com/s/c2ror63pz16hc3w/2015-07-06-BH-STG-adoc-test.html?dl=0 |
|
I tried: So I edited adoc-test.html and changed one of the duplicate |
|
PS. You might have more success using asciidoc to produce DocBook, then converting that with pandoc. Have you tried that route? |
|
Ah, damn---I didn't think to do a version check. Sorry for being such a novice. I'd been using 1.13.2, which is the latest version on homebrew. Will install 1.15 and try again. Your results sound promising. |
|
BTW, as of pandoc 1.13.2, when I tried the asciidoctor docbook > pandoc epub route the output from docbook was inferior to the output from HTML. One particular thing that I noticed was that admonition blocks came in to the epub as blockquotes without an additional class, and so couldn't be styled specifically with CSS. |
|
Currently DocBook elements like and convert that to +++ Ben Hourigan [Jul 06 15 10:34 ]:
|
|
With the duplicate ID sorted in the .adoc file, from the pandoc 1.15 produces from the asciidoctor.html an epub that passes ePubcheck! :) Inability to split the file at chapter headings remains an issue. Now trying the undiv filter. At first I got this error: Then after installing ghc (7.8.4) and cabal-install (1.22.0.0) (not sure if latter was necessary) from homebrew, I got this error. Oddly, if I run All files used during generation here: https://www.dropbox.com/s/40uv3f4ad2fwuco/bh-undiv.hs-test.zip?dl=0 I'm running a script called generate.sh, which is just the following command: |
|
Is undiv.hs in your working directory? What OS are you on? +++ Ben Hourigan [Jul 06 15 18:13 ]:
|
|
Thanks for the feedback @jgm. It's emitting JSON now. |
|
when you are now emitting pandoc JSON, then why not integrate the huskydoc with pandoc itself? |
|
There are three reasons:
I am planning to address these issues over the next months. I'd like to polish the library some more before I start to address compatibility issues. Being able to experiment is part of the reason this project exists. The result of using the huskydoc executable is identical to what would be produced if pandoc was calling the library directly, so the method described above is hopefully be acceptable for now. |
|
+1 |
|
This thread is very interesting. I'd also love to see pandoc support Asciidoc reader. As for the issue of AsciiDoctor wrapping paragraphs in
This can be easily achieved using HAML and asciidoctor-backends, and it allows to change how elements are rendered into HTML by targeting single elements. For example, to change how paragraphs are formatted in Asciidoctor's final output, you only need to add a modified version of this single file: https://github.com/asciidoctor/asciidoctor-backends/blob/master/haml/html5/block_paragraph.html.haml Look inside it: %div{:id=>@id, :class=>['paragraph', role]}>
- if title?
.title=title
%p<=contentYou only need to remove the Another bad thing about this divs is that they make CSS styling really annoying. The cool thing about using custom templates and backends is that only the needed files that you actually put in your custom template folder will be used, for the missing files it will fallback on the default. So there is no need to re-implement the whole template system. I wish I could share more info on how to do it, but I researched this quite a long time ago and my memory is not fresh on the issue. It is sad though that the AsciiDoctor project has been stuck for so long on developement of Chunked (multi-page) HTML output feature --- looks like is on stall right now. Asciidoc FXThose interested in a quick way to convert Asciidoc to html without having to install dependencies )not even AsciiDoc/AsciiDoctor) should look into Asciidoc FX: it's a cross platform AsciiDoc editor (also available as standalone app) that can convert Asciidoc documents to standalone (and templated) html5 docs (includin syntax highlighting with Highlight.js): It's a Java app that bundles with AsciiDoctor and DocBook (no HTML output support though!), plus other tools --- thus sparing you to have to install anything. And it doesn't conflict with any locally installed version of AsciiDoctor, Asciidoc, etc. I use pandoc to convert to AsciiDoc and then with Asciidoc FX I just open and save as HTML5 --- and I get a fully standalone document, with a nice template. Hope this might help.... |
|
+++ Tristano Ajmone [Mar 06 17 14:12 ]:
The cool thing about using custom templates and backends is that only
the needed files that you actually put in your custom template folder
will be used, for the missing files it will fallback on the default. So
there is no need to re-implement the whole template system.
I implemented a very similar system in jgm/gitit using HStringTemplate. The ability to have reusable template parts in a common request in pandoc.
|
|
An AsciiDoc Reader would be quite useful to many, especially in humanities, who need to be able to handle As far as I know, only Unfortunately, AsciiDoc's LaTeX support is not good enough. Pandoc would be ideal. |
|
Why not use pandoc's markdown with line blocks for verse?
This is a quote
block.
And
| This is
| some verse
Since these are represented differently in the AST, you should have lots
of possibilities for styling them differently in HTML and LaTeX.
Priyadarshan <notifications@github.com> writes:
… An AsciiDoc Reader would be quite useful to many, especially in humanities, who need to be able to handle `quote` block and `verse` block as separate cases, to HTML and LaTeX targets.
As far as I know, only `org` and `asciidoc` support that natively, with [AsciiDoc having perhaps a more complete syntax](http://asciidoc.org/userguide.html#X94).
Unfortunately, AsciiDoc's LaTeX support is not good enough. Pandoc would be ideal.
--
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub:
#1456 (comment)
|
|
Thank you for the prompt comment. The non-profit organisation I work for is maintaining several thousand books (poetry, prose, plays), currently in org-mode, that are converted to LaTeX to make books. We would like to switch to Pandoc for its speed, simplicity and elegance. I though already of doing what you suggested, i.e. using pandoc markdown, That solution is not too elegant, since verse and quote have two different ways to mark their semantic space:
There is a "mismatch" between the two, which works fine, ultimately, but it would not make sense to the editors of the files. Of course we can tell them to "just do it", but that will detract for the final solution quite a bit. Looking at lua filters gave me some ideas. Certainly adopting pandoc-markdown has its advantages. Thank you for the advice. |
|
I wonder, would it be feasible to extend the That would have additional benefit to allow any of the countless custom environments available in LaTeX (like cverse, drama, etc), a veritable boon to people in humanities. For example, or |
|
@priyadarshan I think jgm meant to use blockquotes (prepend About rewriting divs in latex: you can already do that with filters. There is also #2106 |
|
@mb21 Thank you, I understood that. As I said, using line blocks syntax for verse would not be compatible with our guideline of keeping original text as clean and intact as possible. That is even more so for poetry. Thank you for pointer to rewriting divs in LaTeX. That is exactly what we need. I hope that ticket will be completed too, it seems nice to have same possibility in LaTeX as in HTML writers. Apology for creating noise in this ticket. After all, that is about asciidoc. Thank you so much to John MacFarlane and developers for the wonderful Pandoc! |
|
Note that content in fenced divs will be parsed as Markdown before it gets to your filter. So, to get line breaks between lines of verse, you'd have to insert them manually (two space or backslash at end of line) or enable the If you have further discussion on this topic, though, please move it to pandoc-discuss. |
|
Thank you so much for the valuable advice.
Thank you, I will. |
|
An asciidoc reader would also be very useful to me (to convert from asciidoc to rst) |
|
Regarding the DIVs problem mentioned above, I wanted to add that there's a new third party semantic HTML backend for Asciidoctor now (if I remember correctly, it was added after this thread began): https://github.com/jirutka/asciidoctor-html5s So this might be a viable workaround for the problems mentioned above concerning ePubs creation. |
2014 ... months? ;-) |
|
@gmarpons just posted asciidoc-hs on pandoc-discuss:
|
|
@ciampix Open Source Months are a fairly flexible unit of measure, each month being roughly equivalent to one promise on the more commercial 6-8 weeks scale. |
|
What feature branch is this issue in the github code please? I can't see any branch related to 1456 or asciidoc. |
|
There's this library being developed independently: |
|
I'm confused. https://pandoc.org/demos.html 28.
Why it supports only Also if as output I set |
|
Pandoc assumes that files with I'm not sure what you are asking in the second paragraph. Please raise this on the pandoc-discuss mailing list. We want to reserve this tracker for bug reports and feature requests, questions should go to the mailing list. |
and others
Greetings,
I would like to hereby suggest the addition of AsciiDoc input resp. an AsciiDoc Reader.
Besides Markdown, this format is growing in popularity, also in use inside a publishing toolchain (asciidoc -> docbook -> pdf/epub/html). Currently the only other viable implementation is asciidoctor, which uses Ruby or JRuby, but it is AsciiDoc-only in its input format and not a universal markup converter, like pandoc.
I am aware of only one relevant discussion thread regarding this, which showed positive echo for this feature. Someone actually had some basic code there, but I am not sure if kuznero resp. Roman Kuznetsov still has his code from back then to start from, but anyway, it would certainly make sense to have AsciiDoc input in the feature set.
The text was updated successfully, but these errors were encountered: