Slight problems with links

[Emmanuel Charpentier <emm.charpentier@free.fr>]

[-- Attachment #1: Type: text/plain, Size: 1936 bytes --]

Dear list,

one of my uses od org-mode is to prepare documents wrapping R (and
sometimes Sagemath) call results in interpretation text. My reference
output is .pdf documents, but I *have* to prepare a .docx version (for
use in managerial spheres, where computer literacy is *very* low.
Cross-references and citations are a sine qua non, maths are useful.

I have been annoyed by a couple of deficiencies and inconsistencies
between exporters, so I prepared a test document testing various cases.
This documents and some exports are attached (NE = Native exporter, PE
= ox-pandoc exporter).

TL;DR :

  * I tested the built-in latex/pdf exporter as well as ox-pandoc, the
latter both for .pdf and .docx export. The built-in ODT exporter
doesn't export citations ; therefore, I didn't test it further.


  * org-ref's :labels and :refs do not export to anything but the
built-in latex exporter. The native system of #+NAME:s and #+CAPTION:s,
a bit on the heavy side, seems not to fail (except that they do not
expand in a caption...).

  * Maths, tables, figures are unproblematic.

  * The requirements of org-reftex, the built-in latex exporter and ox-
pandoc being mutually incompatible, and some ingenuity is required. see
the attached org source. Org-ref's requirements do not simplify the
situation...

  * Code snippets (i. e. source blocks exporting code) have a
captioning/numbering problem :

    - With the built-in latex exporter, they are numbered and labeled
as figures.

    - The pandoc latex exporter numbers them separately (as seen by
referencing them), but do not output this number (nor the category)
before the caption.

    - The pandoc .docx exporter works as advertised.

So I have a couple of questions:

  * What can be done to reconcile org-ref's, latex-exporter's and ox-
pandoc's requirements for bibliographies ?

  * How to fix the pdf exporters' quirks with code snippets ?

HTH,

--
Emmanuel Charpentier

[-- Attachment #2: Links.docx --]
[-- Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document, Size: 22700 bytes --]

[-- Attachment #3: Links.org --]
[-- Type: text/plain, Size: 6560 bytes --]

# An archi-minimal test of bibliography export.
# Goals : export to LaTeX(PDF) and DOCX as transparently as possible

#+options: tex:t title:nil author:nil date:nil toc:nil
#+property: header-args:sage :session
#+PANDOC_OPTIONS: number-sections:t

#+begin_src emacs-lisp :exports none :results none
  (require 'org-ref)
  ;; This is much needed to manage changes in bibliography exports...
  (setq org-latex-pdf-process
	(list "latexmk -pdf -pdflatex='%latex -interaction=nonstopmode -shell-escape' -bibtex -f %f")
	org-latex-to-mathml-convert-command
	"latexmlmath \"%i\" --presentationmathml=%o")
#+end_src

Export by **src_emacs-lisp[:results raw]{org-export-current-backend}**.

* Test of maths <<sec:Maths>>

** Hand-typed

Everyone knows[fn::or should know...] that \(e^{i\theta}=\cos\theta+i\sin\theta\)[fn::This is de Moivre's formula]. It results that:
#+name: eq:Euler
\begin{equation}
e^{i\pi}+1=0
\end{equation}

This equation [[eq:Euler]], known as Euler's formula, is one of the best known formulas of elementary maths.

** Sage-generated

#+name: FA
#+begin_src sage :exports results :results table
  def matable():
      a,b=SR.var("a, b")
      LF=[sin, cos, tan]
      T=[f(v)==f(v).trig_expand() for f in LF for v in[a+b, a-b]]
      return [[r"\(\displaystyle {}\)".format(latex(f))] for f in T]
  matable()
#+end_src

#+name: tab:FA
#+caption:Addition formulas, générated by the  Sage snippet [[lst:FA]].
#+RESULTS: FA
| \(\displaystyle \sin\left(a + b\right) = \cos\left(b\right) \sin\left(a\right) + \cos\left(a\right) \sin\left(b\right)\)              |
| \(\displaystyle \sin\left(a - b\right) = \cos\left(b\right) \sin\left(a\right) - \cos\left(a\right) \sin\left(b\right)\)              |
| \(\displaystyle \cos\left(a + b\right) = \cos\left(a\right) \cos\left(b\right) - \sin\left(a\right) \sin\left(b\right)\)              |
| \(\displaystyle \cos\left(a - b\right) = \cos\left(a\right) \cos\left(b\right) + \sin\left(a\right) \sin\left(b\right)\)              |
| \(\displaystyle \tan\left(a + b\right) = -\frac{\tan\left(a\right) + \tan\left(b\right)}{\tan\left(a\right) \tan\left(b\right) - 1}\) |
| \(\displaystyle \tan\left(a - b\right) = \frac{\tan\left(a\right) - \tan\left(b\right)}{\tan\left(a\right) \tan\left(b\right) + 1}\)  |

The results in table [[tab:FA]]  (generated by the Sage snippet in listing [[lst:FA]]) should be known perfectly by any college candidate (yes, even in humanities...).

* Figures <<sec:Figures>>

#+name: SageFig
#+begin_src sage :results file :exports results
  plot(sin, -pi,pi, figsize=4, aspect_ratio=1)
#+end_src

#+name: fig:SageFig
#+caption: A well-known figure, generated by the Sage snippet ||lst:SageFig]].
#+RESULTS: SageFig
[[file:/home/charpent/.sage/temp/zen-book-flip/1793/tmp_ptu96N.png]]

The figure [[fig:SageFig]] (generated by the code snippet of listing [[lst:SageFig]]) whil be placed by \LaTeX at some ``convenient'' place.

* Citations <<sec:Citations>>

# This has been created with ~org-ref-help-insert-cite-link~,
# at a time where the ~[[bibliography...~ link was uncommented.
Citation attempt with a ~cite:~ link : cite:chenouardPhoneTriagePaediatric2016,bergouniouxCalpainActivationShigella2012

# This has been created with ~org-ref-tex-citation :
Another attempt, using a ~\cite{}~ \LaTeX{} macro : \cite{loganadaneCurrentRoleWhole2017}

* Conclusions

** What works

  * Maths (inline, displayed or math environments) are correctly displayed. There is some support for referencing (isolated) equations. See §[[sec:Maths]].
  * Tables are correctly displayed and referenced. (Ditto).
  * Figures are correctly displayed and referenced. See §[[sec:Figures]]
  * Citations can be correctly retrieved and bibliographies can be correctly generated, as shown in §[[sec:Citations]].

The latter requires some ingenuity: My source contains the following snippet at the place where the references are needed:
#+begin_src emacs-lisp :eval no :exports code :noweb yes
<<BiblioTrick>>
#+end_src

The resulting trick leaves enough information in the source file to be able to use ~org-reftex-citation~ function (~C-c C-x [~)  but not enough for the ~org-ref-helm-insert-cite-link~ (~C-c ]~).

One also notes that the ~:results~ type **has** to be ~raw~ ; using ~org~ prepends a comma to the intended result...

** What doesn't (in any exporter)

  * Links are not expanded in captions, and print litteraly.

    A test show that ~org-ref~ ~ref:~  links do expand in captions when exported by the native \LaTeX{} exporter. They are, however, unusable for my purpose, since they do not export (i.e. print litteraly) to anything else...

** Support depending on the exporter

*** Built-in \LaTeX{} exporter

  * Listings (code snippets) are numbered and labeled as figures.

*** All ~pandoc~ exporters

  * References appear necessarily at the end of the document.

    I understand that this a long-known deficiency of ~pandoc~; some workaround exist for ~HTML~ output, but do not seem to apply to ~.docx~ nor ~.pdf~ outputs.

*** ~Pandoc~ \LaTeX{} exporter (~ox-pandoc~)

  * Code snippets are correcly numbered, but neither their captions nor the numbers appear in the resulting PDF.

  * (A pecadillo) In text, the string =\LaTeX{}= exports literally as ~LaTeX{}~, not the expected symbol...

*** ~Pandoc~ ~.docx~ exporter

  * I have been unable to get numbered sections.

    I understand that this might be a limitatin of ~pandoc~ itself, and can be fixed by substituting another ~.docx~ template.

  * I have been unable to master the position of some elements: both table and figures appear at the left of the page.

\appendix

* Some listings

** Maths
#+name: lst:FA
#+caption: Generation of table [[tab:FA]]
#+begin_src sage :eval no :exports code :noweb yes
<<FA>>
#+end_src

** Figures

#+name: lst:SageFig
#+caption: Generation of the figure [[fig:SageFig]].
#+begin_src sage :eval no :exports code :noweb yes
<<SageFig>>
#+end_src

#+name: BiblioTrick
#+begin_src emacs-lisp :exports results :results raw
  (cond ( ;; This allows export to DOCX/ODT :
	 (eq org-export-current-backend 'pandoc)
	 "* References\n\#+bibliography: CRCInnovation2019.bib\n\#+PANDOC_OPTIONS: csl:vancouver-brackets.csl")
	;;This allows export to LaTeX/PDF with the builtin exporter :
	((eq org-export-current-backend 'latex)
	 "[[bibliographystyle:vancouver]]\n[[bibliography:CRCInnovation2019.bib]]")
	;; This leaves enough information to allow org-reftex to find its file :
	(t "\#+bibliography: CRCInnovation2019"))

#+end_src

#+RESULTS:
#+bibliography: CRCInnovation2019

[-- Attachment #4: Links-NE.pdf --]
[-- Type: application/pdf, Size: 201541 bytes --]

[-- Attachment #5: Links-PE.pdf --]
[-- Type: application/pdf, Size: 243498 bytes --]