Asciidoctor brings back the fun into academic writing!

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Asciidoctor brings back the fun into academic writing!

getreu
This post was updated on .
Having used LaTex for academic writing many years I recently became an avid supporter of asciidoctor.

What are the special requirements for academic writing?

1. footnotes
2. bibliographic references (e.g. IEEE style for computer sciences)
3. mathematical formulas


Use case: adoc -> pdf

Asciidoctor-pdf supports footnotes not well enough yet, but the docbook toolchain with asciidoctor-fopub provides everything we need.  When you need maths asciidoctor-latex is a good alternative option.

Use case: adoc -> html

Almost perfect, but there is an important show-stopper: the compliance issue #1562 "xreflabel for bibliography anchor is ignored".
(cf: https://github.com/asciidoctor/asciidoctor/issues/1562)

Dan has analysed the issue:
a)   The bibliography anchor needs to support the xreflabel.
b)    A reference to a bibliography anchor needs to honor the xreflabel value.
It is scheduled for asciidoctor 1.6

In the discussion other good ideas to enhance bibliography support came up, but the above a) and b) of #1562 are the blocker for academic use at the moment as the only existing workaround is to write a post-processor or a script that manually corrects the missing xreflabel support. This is even for my computer scientist colleagues not acceptable!

Workaround: adoc -> docbook (xml) -> html (footnotes not tested, formulas?)


Use case: adoc -> odt, xdoc

This is the less advanced at the moment, but it works surprisingly well. The import preserves paragraph styles. The best workflow with free tools I found so far is:
1. adoc -> html   with asciidoctor/asciidoctor
2. import the html with lowriter and save odt or xdoc

Here again in 1.  we have the show-stopper #1562 above.


Conclusion

It is fun to write articles with Asciidoctor even though I can not recommend it yet because of issue #1562 a) and b).


Is there progress on this?


---

Edit: Workaround for `adoc -> html` added.



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of Asciidoctor and academic writing

willwade
I realise this doesn't answer your questions.. However after searching for a way of citing correctly in a asciidoc file I stumbled on this post and thought it would be worth noting asciidoc-bib (https://github.com/petercrlane/asciidoc-bib) which may be useful to others..
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of Asciidoctor and academic writing

getreu
Thank you. Have you tried to export from Zotero via bibtex?
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of Asciidoctor and academic writing

willwade
Can't say I have - I work pretty much exclusively with CiteULike (http://citeulike.org) which deals with bibtex nicely
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of Asciidoctor and academic writing

gour
In reply to this post by getreu
getreu wrote

Use case: adoc -> odt, xdoc

This is the less advanced at the moment, but it works surprisingly well. The import preserves paragraph styles. The best workflow with free tools I found so far is:
1. adoc -> html   with asciidoctor/asciidoctor
2. import the html with lowriter and save odt or xdoc
Have you tried something like:

1. AsciiDoctor --> DocBook

asciidoctor -b docbook5 -o output.xml inout.adoc

2. DocBook --> ODT

pandoc -f docbook -t odt -o output.odt input.xml


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of Asciidoctor and academic writing

getreu
`pandoc` does not support all the features I need (see first post in this thread). And I need to produce identical html and pdf.

I just posted my workaround for issue #1562  here (at the end).

I do not recommend it, but is works.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of Asciidoctor and academic writing

getreu
Good news: asciidoctor-bibtex takes away the hassle of referencing and simplifies the work-flow of academic writing.

Asciidoctor brings back the fun into academic writing!

The following works well for me:

1. Organize bibliography with zotero

2. Export the used references

    IMPORTANT: the default reference-key-generation-scheme  is not compatible with asciidocto-bibtex!
    Use a customized scheme:
    a) install plugin zotero-better-bibtex
    b) In -> Preferences -> Citation keys -> Citation key format: enter

          [auth:lower][year]


3. Compile


A2pdf


  asciidoctor -b docbook  -r asciidoctor-bibtex -r asciidoctor-diagram -a data-uri! "$@"
  /usr/local/share/asciidoctor-fopub/fopub "$XmlFileName"


A2pdf2


  asciidoctor-pdf -r asciidoctor-bibtex -r asciidoctor-diagram "$@"


A2html


  asciidoctor     -r asciidoctor-bibtex -r asciidoctor-diagram -b xhtml "$@"


A2slides


  asciidoctor -T ./asciidoctor-reveal.js/templates/slim -r asciidoctor-bibtex -r asciidoctor-diagram "$@"



NOTE:: Do not (yet) use the build in bibliography feature because of the compliance issue #1562
 
Loading...