Re: Changed behaviours of LaTeX exporter in version 8.0+

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Hello Nicolas,

Great thanks for the detailed instructions with clear explanations for the
problems.

I have addressed all those issues per your suggestions, but put some
comments embedded below.


Again, many thanks for your great help!

Joseph


On Thu, Sep 18, 2014 at 3:01 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

-----> snip <-----

>
> > 2. Accessing the value of "#+KEYWORDS:" and change of cases in
> > "org-special-blocks"
> >
> > For keywords section in IEEE papers, I used to have the following
> settings:
> >
> > #+KEYWORDS: AAA, BBB, CCC
> > ...
> > #+BEGIN_IEEEkeywords
> > {{{KEYWORDS}}}.
> > #+END_IEEEkeywords
>
> [...]
>
> > Version 8.2.7c, however, produces the following from the same settings:
> >
> > \begin{ieeekeywords}
> > .
> > \end{ieeekeywords}
>
> I'm surprised {{{KEYWORDS}}} even worked as, AFAIK, it wasn't
> documented.  Indeed, there is no such macro in Org 8.0.  However, you
> can define your own
>

'{{{KEYWORDS}}}' worked without any issues in previous versions, which in
fact was suggested by someone in the mailing list or stackoverflow
(unfortunately, I couldn't find that via Google any longer).

By the way, in Sec. 12.3 of the Org manual (ver. 8.2.7c), 'KEYWORDS' is
listed together with 'AUTHOR', 'TITLE' and so on as export keywords. Also,
according to Sec. 11.6, those predefined keywords (e.g.,  #+TITLE:,
#+AUTHOR:) can be accessed by {{{title}}} and {{{author}}} like
user-defined macros.

It seems that there is some inconsistency between the actual behavior and
the corresponding manual in export engine of org-mode ver. 8.2.7c.

-----> snip <-----

[-- Attachment #2: Type: text/html, Size: 2492 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Nicolas and All,

One further question regarding your suggestion of the use of filter for
special blocks in export:

I just found out that, if I close Emacs and relaunch it, all variables for
filter (i.e., 'org-export-filter-*') are not defined. As a result, the
following elisp codes for the workaround based on both your suggestion and
the filter example in the manual causes void variable error (i.e.,
"Symbol's value as variable is void:
org-export-filter-special-block-function"):


;; workaround solution (until 8.3.0) for case-sensitve handling of
special-block for IEEE LaTeX class
(defun my-latex-filter-ieeekeywords (text backend info)
  "Upcase 'IEEE' in IEEEkeywords environment in LaTeX export."
  (when (org-export-derived-backend-p backend 'latex)
(replace-regexp-in-string "ieeekeywords" "IEEEkeywords" text)))

(add-to-list 'org-export-filter-special-block-functions
 'my-latex-filter-ieeekeywords)


It turns out that those variables are defined only after exporting org file
into LaTeX.

Again, any advice on propor addition of custom filter functions in the
configuration file would be greatly appreciated; maybe the said example in
the manual needs to be updated as well.

Regards,
Joseph


On Thu, Sep 18, 2014 at 12:50 PM, Kyeong Soo (Joseph) Kim <
kyeongsoo.kim@gmail.com> wrote:

> Hello Nicolas,
>
> Great thanks for the detailed instructions with clear explanations for the
> problems.
>
> I have addressed all those issues per your suggestions, but put some
> comments embedded below.
>
>
> Again, many thanks for your great help!
>
> Joseph
>
>
> On Thu, Sep 18, 2014 at 3:01 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
> -----> snip <-----
>
>>
>> > 2. Accessing the value of "#+KEYWORDS:" and change of cases in
>> > "org-special-blocks"
>> >
>> > For keywords section in IEEE papers, I used to have the following
>> settings:
>> >
>> > #+KEYWORDS: AAA, BBB, CCC
>> > ...
>> > #+BEGIN_IEEEkeywords
>> > {{{KEYWORDS}}}.
>> > #+END_IEEEkeywords
>>
>> [...]
>>
>> > Version 8.2.7c, however, produces the following from the same settings:
>> >
>> > \begin{ieeekeywords}
>> > .
>> > \end{ieeekeywords}
>>
>> I'm surprised {{{KEYWORDS}}} even worked as, AFAIK, it wasn't
>> documented.  Indeed, there is no such macro in Org 8.0.  However, you
>> can define your own
>>
>
> '{{{KEYWORDS}}}' worked without any issues in previous versions, which in
> fact was suggested by someone in the mailing list or stackoverflow
> (unfortunately, I couldn't find that via Google any longer).
>
> By the way, in Sec. 12.3 of the Org manual (ver. 8.2.7c), 'KEYWORDS' is
> listed together with 'AUTHOR', 'TITLE' and so on as export keywords. Also,
> according to Sec. 11.6, those predefined keywords (e.g.,  #+TITLE:,
> #+AUTHOR:) can be accessed by {{{title}}} and {{{author}}} like
> user-defined macros.
>
> It seems that there is some inconsistency between the actual behavior and
> the corresponding manual in export engine of org-mode ver. 8.2.7c.
>
> -----> snip <-----
>

[-- Attachment #2: Type: text/html, Size: 5007 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Sorry for asking another question; this time it is for the
cross-referencing in LaTeX export, which existed before (e.g., Sec. 16 of
manual for <8.0) but is gone now.


Per the suggestion from the older manual for <8.0, I have the following
setting in my configuration file:

(setq org-export-latex-hyperref-format "\\ref{%s}") ; for cross-referencing


Now with 8.2.7c and the following org internal link to a section

... described in Sec. [[*SectionOne][SectionOne]] ...


LaTeX export generates the following code:

... described in Sec. \texttt{SectionOne}, ...


Regards,

Joseph


On Thu, Sep 18, 2014 at 3:07 PM, Kyeong Soo (Joseph) Kim <
kyeongsoo.kim@gmail.com> wrote:

> Nicolas and All,
>
> One further question regarding your suggestion of the use of filter for
> special blocks in export:
>
> I just found out that, if I close Emacs and relaunch it, all variables for
> filter (i.e., 'org-export-filter-*') are not defined. As a result, the
> following elisp codes for the workaround based on both your suggestion and
> the filter example in the manual causes void variable error (i.e.,
> "Symbol's value as variable is void:
> org-export-filter-special-block-function"):
>
>
> ;; workaround solution (until 8.3.0) for case-sensitve handling of
> special-block for IEEE LaTeX class
> (defun my-latex-filter-ieeekeywords (text backend info)
>   "Upcase 'IEEE' in IEEEkeywords environment in LaTeX export."
>   (when (org-export-derived-backend-p backend 'latex)
> (replace-regexp-in-string "ieeekeywords" "IEEEkeywords" text)))
>
> (add-to-list 'org-export-filter-special-block-functions
>  'my-latex-filter-ieeekeywords)
>
>
> It turns out that those variables are defined only after exporting org
> file into LaTeX.
>
> Again, any advice on propor addition of custom filter functions in the
> configuration file would be greatly appreciated; maybe the said example in
> the manual needs to be updated as well.
>
> Regards,
> Joseph
>
>
>
> On Thu, Sep 18, 2014 at 12:50 PM, Kyeong Soo (Joseph) Kim <
> kyeongsoo.kim@gmail.com> wrote:
>
>> Hello Nicolas,
>>
>> Great thanks for the detailed instructions with clear explanations for
>> the problems.
>>
>> I have addressed all those issues per your suggestions, but put some
>> comments embedded below.
>>
>>
>> Again, many thanks for your great help!
>>
>> Joseph
>>
>>
>> On Thu, Sep 18, 2014 at 3:01 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
>> wrote:
>>
>> -----> snip <-----
>>
>>>
>>> > 2. Accessing the value of "#+KEYWORDS:" and change of cases in
>>> > "org-special-blocks"
>>> >
>>> > For keywords section in IEEE papers, I used to have the following
>>> settings:
>>> >
>>> > #+KEYWORDS: AAA, BBB, CCC
>>> > ...
>>> > #+BEGIN_IEEEkeywords
>>> > {{{KEYWORDS}}}.
>>> > #+END_IEEEkeywords
>>>
>>> [...]
>>>
>>> > Version 8.2.7c, however, produces the following from the same settings:
>>> >
>>> > \begin{ieeekeywords}
>>> > .
>>> > \end{ieeekeywords}
>>>
>>> I'm surprised {{{KEYWORDS}}} even worked as, AFAIK, it wasn't
>>> documented.  Indeed, there is no such macro in Org 8.0.  However, you
>>> can define your own
>>>
>>
>> '{{{KEYWORDS}}}' worked without any issues in previous versions, which in
>> fact was suggested by someone in the mailing list or stackoverflow
>> (unfortunately, I couldn't find that via Google any longer).
>>
>> By the way, in Sec. 12.3 of the Org manual (ver. 8.2.7c), 'KEYWORDS' is
>> listed together with 'AUTHOR', 'TITLE' and so on as export keywords. Also,
>> according to Sec. 11.6, those predefined keywords (e.g.,  #+TITLE:,
>> #+AUTHOR:) can be accessed by {{{title}}} and {{{author}}} like
>> user-defined macros.
>>
>> It seems that there is some inconsistency between the actual behavior and
>> the corresponding manual in export engine of org-mode ver. 8.2.7c.
>>
>> -----> snip <-----
>>
>
>

[-- Attachment #2: Type: text/html, Size: 6500 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Richard Lawrence]

Hi Joseph,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> Sorry for asking another question; this time it is for the
> cross-referencing in LaTeX export, which existed before (e.g., Sec. 16 of
> manual for <8.0) but is gone now.
> ...
> Now with 8.2.7c and the following org internal link to a section
>
> ... described in Sec. [[*SectionOne][SectionOne]] ...
>
> LaTeX export generates the following code:
>
> ... described in Sec. \texttt{SectionOne}, ...

I think the problem here is that you don't have a link type, and the new
LaTeX exporter doesn't convert links it doesn't understand into
references.

I use a series of custom link types to make references to document
parts in my dissertation.  Here's the code I use; you will probably want
to adapt it to your use case:

#+BEGIN_SRC elisp
;; use CUSTOM_ID properties to generate labels
(setq org-latex-custom-id-as-label t)

(defun org-find-headline-by-custom-id (prefix path)
  "Find a headline in the current buffer by CUSTOM_ID value PREFIX:PATH."
  (save-excursion
    (goto-char (point-min))
     (and
      ; borrowed from org.el; there doesn't seem to be a function that searches
      ; for a headline with a specific property value
      (re-search-forward
       (concat "^[ \t]*:CUSTOM_ID:[ \t]+" prefix ":" path "[ \t]*$") nil t)
      (setq pos (match-beginning 0))))
   (if pos
       (progn
	 (goto-char pos)
	 (org-back-to-heading t))
     (message (format "Headline with CUSTOM_ID %s:%s not found." prefix path))))

(defun org-export-dissertation-link (prefix path desc format)
  "Export a link to a dissertation section, etc.

In LaTeX, the exported link will look like:
  DESC~\\ref{PREFIX:PATH}
"
    (when (member format '(latex linguistics))
      (format "%s~\\ref{%s:%s}" desc prefix path)))

; Parts:
(org-add-link-type
 "part"
 (lambda (path)
   (org-find-headline-by-custom-id "part" path))
 (lambda (path desc format)
   (org-export-dissertation-link "part" path (or desc "Part") format)))

; Chapters:
(org-add-link-type
 "chap"
 (lambda (path)
   (org-find-headline-by-custom-id "chap" path))
 (lambda (path desc format)
   (org-export-dissertation-link "chap" path (or desc "Chapter") format)))

; Sections:
(org-add-link-type
 "sec"
 (lambda (path)
   (org-find-headline-by-custom-id "sec" path))
 (lambda (path desc format)
   (org-export-dissertation-link "sec" path (or desc "Section") format)))

; Tables:
(org-add-link-type
 "tab"
 (lambda (path) (org-link-search (concat "tab:" path)))
 (lambda (path desc format)
   (org-export-dissertation-link "tab" path (or desc "Table") format)))

#+END_SRC

So a link like "[[sec:foo]]" renders as "Section~\ref{sec:foo}",
"[[chap:foo]]" renders as "Chapter~\ref{chap:foo}", etc. when exported
to LateX, and you can follow links to jump to the appropriate document
headline.

Note that this works by giving my document sections fixed labels by
setting the CUSTOM_ID property.  I give headlines a descriptive name in
this property, using the LaTeX convention of prefixing "sec:", etc. to
keep my labels straight; Org then generates \label commands for document
parts using the CUSTOM_ID property.  This requires setting
org-latex-custom-id-as-label.  For example, a headline like

*** Another interesting section
    :PROPERTIES:
    :CUSTOM_ID: sec:interesting
    :END:

is exported as

\section{Another interesting section}
\label{sec:interesting}

(The prefixes are important, since they function both as link types and
as parts of label/ref keys.  As you'll notice, the
org-export-dissertation-link function adds them back in to the key.)

I find this setup keeps things working well across revisions,
re-ordering and re-naming of sections, etc.

Hope that helps!

Best,
Richard

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Richard Lawrence]

Hi Joseph,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> Great thanks for your answering my two questions, especially sharing your
> experience for cross-referencing in LaTeX export.
>
> Though your suggestion for cross-referencing is an excellent workaround, I
> wonder whether there is any benefit using org-mode in writing papers in
> this case; for instance, manual setting of CUSTOM_ID would be a hassle,
> considering that it can be easily & automatically done in LaTeX with
> AUCTeX/RefTeX's label function.

Don't you need to make sure that your sections have a consistent label
in order to refer to them?

At any rate, one of the reasons I use this solution is that I want to be
able to easily use plain LaTeX at points where I discover that I can't
make Org do everything I want.  One of the cases I was worried about,
for example, is having a section reference inside an embedded LaTeX
block.  If you don't know the label ahead of time, you can't use a raw
\ref command inside #+BEGIN_LATEX...#+END_LATEX.  So I like being able
to set the labels via CUSTOM_ID on an as-needed basis. (I don't do it
for every section.)

You might be able to get away with less; it looks to me like the
[[*Foo][Section Foo]] still produces a link to a headline in LaTeX
output.  Does that not work for you?

> I still don't know why the new export engine has brought so many
> compatibility issues in its behavior.  It seems that I'd better go
> back to the prior version (7.X) in order to focus on my research.

The new export engine was a complete re-write, and came with an attempt
to define and standardize Org syntax.  Some of the incompatibilities are
due to that standardization: the old LaTeX and HTML exporters might
treat some text differently, for example, or not deal with some corner
case, so in writing a new export engine, it was necessary to define the
correct behavior.  Other incompatibilities are just bugs that come with
any new piece of software; the exporter is under heavy development and
those are constantly getting fixed.

The new exporter really is a *lot* better, and in my experience it is
worth the effort to upgrade.  I found myself bumping into the
limitations of the pre-8.0 exporter very frequently.  If you don't, you
can wait, but I think you'll find the new exporter a lot easier to work
with and to get help with.

Best,
Richard

OpenPGP Key ID: CF6FA646
Fingerprint: 9969 43E1 CF6F A646

(See http://www.ocf.berkeley.edu/~rwl/encryption.html for more information.)

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Hi Richard,

I do really appreciate your taking time to further explain the use of
CUSTOM_ID.

Now I can understand why this CUSTOM_ID-based solution is better and, in
some cases as in your example, needed.

With version 7.x, what I did was to reference sections in main texts (not
in embedded LaTeX blocks) using 'C-c l' on a sections header and 'C-c C-l'
in a part referring to it (i.e., no manual setting & typing involved).

Fortunately, for most journal & conference papers in my area (i.e., up to
~15 pages), there is virtually no chance that more than one sections have
the same title at the same level; note that "*Numerical Examples" and
"**Numerical Examples" are different. This may be the case for a thesis as
well, much longer though.

Except for the said case of embedded LaTeX blocks, therefore, the use of
CUSTOM_ID with manual labelling is something I want to avoid if possible.

By the way, as said, [[*Foo][Section Foo]] does not produce the link in
LaTeX export any longer; version 8.x generates just "\texttt{Section Foo}"
unlike version 7.x.

But I do agree that new export engines are more flexible and powerful
(e.g., filters) and will see whether and how all these compatibility issues
will be addressed; otherwise, I would have to update tens of papers based
on version 7.x org-mode, which is my major platform/format for academic
publications and teaching materials.

Again, many thanks for your sharing valuable experience and great insight
on these!
Joseph

On Fri, Sep 19, 2014 at 11:49 PM, Richard Lawrence <
richard.lawrence@berkeley.edu> wrote:

> Hi Joseph,
>
> "Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:
>
> > Great thanks for your answering my two questions, especially sharing your
> > experience for cross-referencing in LaTeX export.
> >
> > Though your suggestion for cross-referencing is an excellent workaround,
> I
> > wonder whether there is any benefit using org-mode in writing papers in
> > this case; for instance, manual setting of CUSTOM_ID would be a hassle,
> > considering that it can be easily & automatically done in LaTeX with
> > AUCTeX/RefTeX's label function.
>
> Don't you need to make sure that your sections have a consistent label
> in order to refer to them?
>
> At any rate, one of the reasons I use this solution is that I want to be
> able to easily use plain LaTeX at points where I discover that I can't
> make Org do everything I want.  One of the cases I was worried about,
> for example, is having a section reference inside an embedded LaTeX
> block.  If you don't know the label ahead of time, you can't use a raw
> \ref command inside #+BEGIN_LATEX...#+END_LATEX.  So I like being able
> to set the labels via CUSTOM_ID on an as-needed basis. (I don't do it
> for every section.)
>
> You might be able to get away with less; it looks to me like the
> [[*Foo][Section Foo]] still produces a link to a headline in LaTeX
> output.  Does that not work for you?
>
> > I still don't know why the new export engine has brought so many
> > compatibility issues in its behavior.  It seems that I'd better go
> > back to the prior version (7.X) in order to focus on my research.
>
> The new export engine was a complete re-write, and came with an attempt
> to define and standardize Org syntax.  Some of the incompatibilities are
> due to that standardization: the old LaTeX and HTML exporters might
> treat some text differently, for example, or not deal with some corner
> case, so in writing a new export engine, it was necessary to define the
> correct behavior.  Other incompatibilities are just bugs that come with
> any new piece of software; the exporter is under heavy development and
> those are constantly getting fixed.
>
> The new exporter really is a *lot* better, and in my experience it is
> worth the effort to upgrade.  I found myself bumping into the
> limitations of the pre-8.0 exporter very frequently.  If you don't, you
> can wait, but I think you'll find the new exporter a lot easier to work
> with and to get help with.
>
> Best,
> Richard
>
> OpenPGP Key ID: CF6FA646
> Fingerprint: 9969 43E1 CF6F A646
>
> (See http://www.ocf.berkeley.edu/~rwl/encryption.html for more
> information.)
>

[-- Attachment #2: Type: text/html, Size: 5594 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Nicolas Goaziou]

Hello,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> By the way, as said, [[*Foo][Section Foo]] does not produce the link in
> LaTeX export any longer; version 8.x generates just "\texttt{Section Foo}"
> unlike version 7.x.

An ECM illustrating the problem would be nice.

"\textt{Section Foo}" means that [[*Foo][Section Foo]] couldn't match
a headline. It can happen if there is no headline named exactly Foo in
the exported part of the buffer.


Regards,

-- 
Nicolas Goaziou

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

On Tue, Sep 23, 2014 at 12:00 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> "Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:
>
> > By the way, as said, [[*Foo][Section Foo]] does not produce the link in
> > LaTeX export any longer; version 8.x generates just "\texttt{Section
> Foo}"
> > unlike version 7.x.
>
> An ECM illustrating the problem would be nice.
>
> "\textt{Section Foo}" means that [[*Foo][Section Foo]] couldn't match
> a headline. It can happen if there is no headline named exactly Foo in
> the exported part of the buffer.
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

Below I provide ECM for LaTeX cross-referencing you requested, which itself
summarizes the issues in the current export engine: We see that there are
mix of results for different cases of heading title (i.e., \texttt{},
\hyperref[]{}, & \ref{}) and that only referring by custom_id results in a
correct cross-reference. Note that, as mentioned in the list several time
before, there is currently no way to customizing hyperref format using
'org-export-latex-hyperref-format' varible, which becomes obsolete now.

============
org-mode source
============

#+TITLE: \LARGE ECM for New Org-Mode \LaTeX Export Engine
#+DATE: Time-stamp: <2014-09-23 10:52:34 Kyeong Soo (Joseph) Kim>
#+AUTHOR: Joseph
#+EMAIL:
#+DESCRIPTION: ECM for testing LaTeX engine compatibility issues
#+LANGUAGE: en
#+OPTIONS: toc:nil email:t
#+STARTUP: overview fnauto fnadjust hideblocks
#+LaTeX_CLASS: article

#+BEGIN_abstract
We test \LaTeX cross-referencing in emacs org-mode version 8.x.
#+END_abstract

* OneWord
  :PROPERTIES:
  :CUSTOM_ID: sec:one_word
  :END:
* Two Words
  :PROPERTIES:
  :CUSTOM_ID: sec:two_words
  :END:
* With & in the Title
  :PROPERTIES:
  :CUSTOM_ID: sec:with_ampersand
  :END:
* Cross-Referenceing
For Section title with one word:
- By custom ID: Sec. [[#sec:one_word]]
- By name (using C-c l & C-c C-l): Sec. [[*OneWord][OneWord]]

For Section title with multiple words:
- By custom ID: Sec. [[#sec:two_words]]
- By name (using C-c l & C-c C-l): Sec. [[*Two%20Words][Two Words]]

For Section title with &:
- By custom ID: Sec. [[#sec:with_ampersand]]
- By name (using C-c l & C-c C-l): Sec.
[[*With%20&%20in%20the%20Title][With & in the Title]]


===============
Exported LaTeX file
===============

% Created 2014-09-23 Tue 10:52
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{fixltx2e}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{float}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{marvosym}
\usepackage{wasysym}
\usepackage{amssymb}
\usepackage{hyperref}
\tolerance=1000
\author{Joseph}
\date{Time-stamp: \textit{<2014-09-23 10:52:34 Kyeong Soo (Joseph) Kim>}}
\title{\LARGE ECM for New Org-Mode \LaTeX Export Engine}
\hypersetup{
  pdfkeywords={},
  pdfsubject={ECM for testing LaTeX engine compatibility issues},
  pdfcreator={Emacs 24.3.1 (Org mode 8.2.7c)}}
\begin{document}

\maketitle
\begin{abstract}
We test \LaTeX cross-referencing in emacs org-mode version 8.x.
\end{abstract}

\section{OneWord}
\label{sec-1}
\section{Two Words}
\label{sec-2}
\section{With \& in the Title}
\label{sec-3}
\section{Cross-Referenceing}
\label{sec-4}
For Section title with one word:
\begin{itemize}
\item By custom ID: Sec. \ref{sec-1}
\item By name (using C-c l \& C-c C-l): Sec. \hyperref[sec-1]{OneWord}
\end{itemize}

For Section title with multiple words:
\begin{itemize}
\item By custom ID: Sec. \ref{sec-2}
\item By name (using C-c l \& C-c C-l): Sec. \texttt{Two Words}
\end{itemize}

For Section title with \&:
\begin{itemize}
\item By custom ID: Sec. \ref{sec-3}
\item By name (using C-c l \& C-c C-l): Sec. \texttt{With \& in the Title}
\end{itemize}
% Emacs 24.3.1 (Org mode 8.2.7c)
\end{document}

[-- Attachment #2: Type: text/html, Size: 5849 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Nicolas Goaziou]

Hello,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> Below I provide ECM for LaTeX cross-referencing you requested, which itself
> summarizes the issues in the current export engine: We see that there are
> mix of results for different cases of heading title (i.e., \texttt{},
> \hyperref[]{}, & \ref{}) and that only referring by custom_id results in a
> correct cross-reference.

See below.

> Note that, as mentioned in the list several time
> before, there is currently no way to customizing hyperref format using
> 'org-export-latex-hyperref-format' varible, which becomes obsolete
> now.

You can use a link filter. Also, `org-export-latex-hyperref-format'
doesn't exist in Org 8.0+.

> - By name (using C-c l & C-c C-l): Sec. [[*Two%20Words][Two Words]]

[...]

> [[*With%20&%20in%20the%20Title][With & in the Title]]

This is the problem. The path isn't expected to be url-encoded. AFAICT,
"C-c l" doesn't encoded headlines. I don't know how yours generates such
a link.


Regards,

-- 
Nicolas Goaziou

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Hi Nicolas,


On Sun, Sep 28, 2014 at 6:01 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:
>
>
> You can use a link filter. Also, `org-export-latex-hyperref-format'
> doesn't exist in Org 8.0+.
>
> > - By name (using C-c l & C-c C-l): Sec. [[*Two%20Words][Two Words]]
>
> [...]
>
> > [[*With%20&%20in%20the%20Title][With & in the Title]]
>
> This is the problem. The path isn't expected to be url-encoded. AFAICT,
> "C-c l" doesn't encoded headlines. I don't know how yours generates such
> a link.
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

The real problem is that, except for using the custom id, the current
export engine cannot refer to the correct label (e.g., "\label{se-1}")
which is automatically generated during the export process.

See the case of section title with only one word in the ECM (e.g., "
\hyperref[sec-1]{OneWord}"), where the export engine still cannot properly
refer to the automatically generated label. This has nothing to do with the
URL-encoding.

Note that the issue of URL-encoding has gone once I cleared up my org-mode
configurations (i.e., commented all out for testing). Still, however, the
issue of wrong cross-referencing is there.

Regards,
Joseph

[-- Attachment #2: Type: text/html, Size: 2057 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Nicolas Goaziou]

Hello,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> The real problem is that, except for using the custom id, the current
> export engine cannot refer to the correct label (e.g., "\label{se-1}")
> which is automatically generated during the export process.
>
> See the case of section title with only one word in the ECM (e.g., "
> \hyperref[sec-1]{OneWord}"), where the export engine still cannot properly
> refer to the automatically generated label. This has nothing to do with the
> URL-encoding.

Could you elaborate about what is wrong with
"\hyperref[sec-1]{OneWord}"?

AFAICT, it is the desired output.


Regards,

-- 
Nicolas Goaziou

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

On Mon, Sep 29, 2014 at 3:07 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> "Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:
>
> > The real problem is that, except for using the custom id, the current
> > export engine cannot refer to the correct label (e.g., "\label{se-1}")
> > which is automatically generated during the export process.
> >
> > See the case of section title with only one word in the ECM (e.g., "
> > \hyperref[sec-1]{OneWord}"), where the export engine still cannot
> properly
> > refer to the automatically generated label. This has nothing to do with
> the
> > URL-encoding.
>
> Could you elaborate about what is wrong with
> "\hyperref[sec-1]{OneWord}"?
>
> AFAICT, it is the desired output.
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

Now I see the point in your suggestion.

It seems that you suggest using filter to change

\hyperref[sec-1]{OneWord}

to

\ref{sec-1}

Am I right?

By the way, this is a bit of step backward, considering near standard use
of '\ref{...}' in most academic papers and theses; the use of hyperlinks
are even strongly discouraged in many conferences and academic journals
during the publication processes.

If we have to choose, I believe going back to version 7.x behavior (i.e.,
"\ref{...}") is a right direction for LaTeX export. Hyperlinks can be done
using filtering in this case.

Regards,
Joseph

[-- Attachment #2: Type: text/html, Size: 2565 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Rasmus]

Hi,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> On Mon, Sep 29, 2014 at 3:07 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> Hello,
>>
>> "Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:
>>
>> > The real problem is that, except for using the custom id, the current
>> > export engine cannot refer to the correct label (e.g., "\label{se-1}")
>> > which is automatically generated during the export process.
>> >
>> > See the case of section title with only one word in the ECM (e.g., "
>> > \hyperref[sec-1]{OneWord}"), where the export engine still cannot
>> properly
>> > refer to the automatically generated label. This has nothing to do with
>> the
>> > URL-encoding.
>>
>> Could you elaborate about what is wrong with
>> "\hyperref[sec-1]{OneWord}"?
>>
>> AFAICT, it is the desired output.
>>
>>
>> Regards,
>>
>> --
>> Nicolas Goaziou
>>
>
> Now I see the point in your suggestion.
>
> It seems that you suggest using filter to change
>
> \hyperref[sec-1]{OneWord}
>
> to
>
> \ref{sec-1}
>
> Am I right?

If you don't want to use hyperref (i) make sure your sections are
numbered (e.g. #+OPTIONS: num:5) and (ii) make sure that you are not
giving links a description.  Here's an example:

* test my heading
:PROPERTIES:
:CUSTOM_ID: t
:END:
[[*test my heading][my funky label]]
[[*test my heading]]
[[#t]]

→ 

\section{test my heading}
\label{sec-1}
\hyperref[sec-1]{my funky label}
\ref{sec-1}
\ref{sec-1}

—Rasmus

-- 
May the Force be with you

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Hello,
On Mon, Sep 29, 2014 at 4:53 PM, Rasmus <rasmus@gmx.us> wrote:
>
>
> If you don't want to use hyperref (i) make sure your sections are
> numbered (e.g. #+OPTIONS: num:5) and (ii) make sure that you are not
> giving links a description.  Here's an example:
>
> * test my heading
> :PROPERTIES:
> :CUSTOM_ID: t
> :END:
> [[*test my heading][my funky label]]
> [[*test my heading]]
> [[#t]]
>
> →
>
> \section{test my heading}
> \label{sec-1}
> \hyperref[sec-1]{my funky label}
> \ref{sec-1}
> \ref{sec-1}
>
> —Rasmus
>
> --
> May the Force be with you
>
>
>
This is exactly what I wanted to do for cross-referencing in LaTeX export.
With this, now I can use my org files as I did with version 7.x (except for
the description in the link).

It would have been much better to have this information in the manual (like
those for cross-referencing in LaTeX in the older version of manual).
Or, is this already described there?

Anyhow, great thanks for this information!

Regards,
Joseph

[-- Attachment #2: Type: text/html, Size: 1838 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Rasmus]

Hi Kyeong,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> Hello,
> On Mon, Sep 29, 2014 at 4:53 PM, Rasmus <rasmus@gmx.us> wrote:
>>
>>
>
>> If you don't want to use hyperref (i) make sure your sections are
>> numbered (e.g. #+OPTIONS: num:5) and (ii) make sure that you are not
>> giving links a description.  Here's an example:
>>
>> * test my heading
>> :PROPERTIES:
>> :CUSTOM_ID: t
>> :END:
>> [[*test my heading][my funky label]]
>> [[*test my heading]]
>> [[#t]]
>>
>> →
>>
>> \section{test my heading}
>> \label{sec-1}
>> \hyperref[sec-1]{my funky label}
>> \ref{sec-1}
>> \ref{sec-1}
>>
>> —Rasmus
>>
>> --
>> May the Force be with you
>>
>>
>>
> This is exactly what I wanted to do for cross-referencing in LaTeX export.
> With this, now I can use my org files as I did with version 7.x (except for
> the description in the link).
>
> It would have been much better to have this information in the manual (like
> those for cross-referencing in LaTeX in the older version of manual).
> Or, is this already described there?

If it's unclear, please consider one of the following:

   1. Writing a documentation patch — especially if you have assigned
      copyright to FSF For Emacs changes.
   2. Explain exactly where you would have expected to find this
      information and/or where the manual is unclear.

Thanks,
Rasmus

-- 
However beautiful the theory, you should occasionally look at the evidence

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

Hi Rasmus,

On Mon, Sep 29, 2014 at 6:09 PM, Rasmus <rasmus@gmx.us> wrote:

> Hi Kyeong,
>
> "Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:
>
> > This is exactly what I wanted to do for cross-referencing in LaTeX
> export.
> > With this, now I can use my org files as I did with version 7.x (except
> for
> > the description in the link).
> >
> > It would have been much better to have this information in the manual
> (like
> > those for cross-referencing in LaTeX in the older version of manual).
> > Or, is this already described there?
>
> If it's unclear, please consider one of the following:
>
>    1. Writing a documentation patch — especially if you have assigned
>       copyright to FSF For Emacs changes.
>    2. Explain exactly where you would have expected to find this
>       information and/or where the manual is unclear.
>
> Thanks,
> Rasmus
>
> --
> However beautiful the theory, you should occasionally look at the evidence
>
>
If possible, please let me know where to find the information you provided
(i.e., without the description filed in the org-mode internal link, its
export to LaTeX becomes "\ref{...}" instead of "\hyperref{...}").

I'm currently using Org Manual version 8.2.7c (PDF version), but cannot
find any relevant information. It's not the matter of whether it's clear or
not, but there is no such information in the current manual.

I do wonder where you got that information (directly from the source code?).

For older version, the following link provides all the details for LaTeX
cross referencing in Sec. 16:
http://orgmode.org/worg/org-tutorials/org-latex-export.html

Writing a documentation patch could be an option, but first of all, I need
detailed information on this but currently have not.

Regards,
Joseph

[-- Attachment #2: Type: text/html, Size: 2724 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Rasmus]

Hi,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> If possible, please let me know where to find the information you provided
> (i.e., without the description filed in the org-mode internal link, its
> export to LaTeX becomes "\ref{...}" instead of "\hyperref{...}").

You can open the info version of the manual with

    (info "org")

> I'm currently using Org Manual version 8.2.7c (PDF version), but cannot
> find any relevant information. It's not the matter of whether it's clear or
> not, but there is no such information in the current manual.
>
> I do wonder where you got that information (directly from the source code?).

It may be documented in chapter 4, entitled Hyperlinks.

   http://orgmode.org/org.html#Hyperlinks

I don't know if this chapter describes export behavior. 

You can skim through org-latex-link if you care.  For headlines this
is the relevant part

;; LINK points to a headline.  If headlines are numbered
;; and the link has no description, display headline's
;; number.  Otherwise, display description or headline's
;; title.
(headline
 (let* ((custom-label
         (and (plist-get info :latex-custom-id-labels)
              (org-element-property :CUSTOM_ID destination)))
        (label
         (or
          custom-label
          (format "sec-%s"
                  (mapconcat
                   #'number-to-string
                   (org-export-get-headline-number destination info)
                   "-")))))
   (if (and (not desc)
            (org-export-numbered-headline-p destination info))
       (format "\\ref{%s}" label)
     (format "\\hyperref[%s]{%s}" label
             (or desc
                 (org-export-data
                  (org-element-property :title destination) info))))))

> Writing a documentation patch could be an option, but first of all, I need
> detailed information on this but currently have not.

Please see

    http://orgmode.org/worg/org-contribute.html

for practical details.

—Rasmus

-- 
To err is human. To screw up 10⁶ times per second, you need a computer

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Rasmus]

Hi,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> If possible, please let me know where to find the information you provided
> (i.e., without the description filed in the org-mode internal link, its
> export to LaTeX becomes "\ref{...}" instead of "\hyperref{...}").

You can open the info version of the manual with

    (info "org")

> I'm currently using Org Manual version 8.2.7c (PDF version), but cannot
> find any relevant information. It's not the matter of whether it's clear or
> not, but there is no such information in the current manual.
>
> I do wonder where you got that information (directly from the source code?).

It may be documented in chapter 4, entitled Hyperlinks.

   http://orgmode.org/org.html#Hyperlinks

I don't know if this chapter describes export behavior. 

You can skim through org-latex-link if you care.  For headlines this
is the relevant part

;; LINK points to a headline.  If headlines are numbered
;; and the link has no description, display headline's
;; number.  Otherwise, display description or headline's
;; title.
(headline
 (let* ((custom-label
         (and (plist-get info :latex-custom-id-labels)
              (org-element-property :CUSTOM_ID destination)))
        (label
         (or
          custom-label
          (format "sec-%s"
                  (mapconcat
                   #'number-to-string
                   (org-export-get-headline-number destination info)
                   "-")))))
   (if (and (not desc)
            (org-export-numbered-headline-p destination info))
       (format "\\ref{%s}" label)
     (format "\\hyperref[%s]{%s}" label
             (or desc
                 (org-export-data
                  (org-element-property :title destination) info))))))

> Writing a documentation patch could be an option, but first of all, I need
> detailed information on this but currently have not.

Please see

    http://orgmode.org/worg/org-contribute.html

for practical details.

—Rasmus

-- 
To err is human. To screw up 10⁶ times per second, you need a computer

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

On Mon, Sep 29, 2014 at 10:18 PM, Rasmus <rasmus@gmx.us> wrote:
<----- snip ---->

>
> It may be documented in chapter 4, entitled Hyperlinks.
>
>    http://orgmode.org/org.html#Hyperlinks
>
> I don't know if this chapter describes export behavior.
>

It does not.


>
> You can skim through org-latex-link if you care.  For headlines this
> is the relevant part
>
> ;; LINK points to a headline.  If headlines are numbered
> ;; and the link has no description, display headline's
> ;; number.  Otherwise, display description or headline's
> ;; title.
> (headline
>  (let* ((custom-label
>          (and (plist-get info :latex-custom-id-labels)
>               (org-element-property :CUSTOM_ID destination)))
>         (label
>          (or
>           custom-label
>           (format "sec-%s"
>                   (mapconcat
>                    #'number-to-string
>                    (org-export-get-headline-number destination info)
>                    "-")))))
>    (if (and (not desc)
>             (org-export-numbered-headline-p destination info))
>        (format "\\ref{%s}" label)
>      (format "\\hyperref[%s]{%s}" label
>              (or desc
>                  (org-export-data
>                   (org-element-property :title destination) info))))))
>

As I guessed, you got this information from the source code itself.

In this regard I do deeply appreciate your providing this information with
all the guidance for contribution to documentation; I will try to
contribute per your advice.

Regards,
Joseph

[-- Attachment #2: Type: text/html, Size: 2544 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Richard Lawrence]

Hi Joseph,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> I just found out that, if I close Emacs and relaunch it, all variables for
> filter (i.e., 'org-export-filter-*') are not defined. As a result, the
> following elisp codes for the workaround based on both your suggestion and
> the filter example in the manual causes void variable error (i.e.,
> "Symbol's value as variable is void:
> org-export-filter-special-block-function"):

Try adding:

(require 'ox)

before your filter definition.

Best,
Richard

Changed behaviours of LaTeX exporter in version 8.0+

[Kyeong Soo (Joseph) Kim]

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

I recently upgraded my org-mode from 7.x to 8.2.7c (bundled with a Windows
Emacs package for ESS) and have been struggling with changed behaviours of
LaTeX exporter since.

Below is the list of those changes:


1. Double backslashes (for line break) embedded in a string for "#+AUTHOR:"

With version 7.x, the following line

#+AUTHOR: Joseph Kim\\Department of Electrical and Electronic
Engineering\\Example University

is exported to

\author{Joseph Kim\\Department of Electrical and Electronic
Engineering\\Example University}


With version 8.2.7c, however, the same line is exported to

\author{Joseph Kim$\backslash$\Department of Electrical and Electronic
Engineering$\backslash$\Example University}

which results in LaTeX compilation error.


2. Accessing the value of "#+KEYWORDS:" and change of cases in
"org-special-blocks"

For keywords section in IEEE papers, I used to have the following settings:

#+KEYWORDS: AAA, BBB, CCC
...
#+BEGIN_IEEEkeywords
{{{KEYWORDS}}}.
#+END_IEEEkeywords

which turns into

\begin{IEEEkeywords}
AAA, BBB, CCC.
\end{IEEEkeywords}


Version 8.2.7c, however, produces the following from the same settings:

\begin{ieeekeywords}
.
\end{ieeekeywords}


Because the keyword environment in IEEE LaTeX class is case-sensitive,
again it results in LaTeX compilation error.


Now I wonder whether I should go back to 7.x or not in spite of many
improvements in the new version.

Any advice or help would be greatly appreciated in this regard.

Regards,
Joseph

[-- Attachment #2: Type: text/html, Size: 2259 bytes --]

Re: Changed behaviours of LaTeX exporter in version 8.0+

[Nicolas Goaziou]

Hello,

"Kyeong Soo (Joseph) Kim" <kyeongsoo.kim@gmail.com> writes:

> 1. Double backslashes (for line break) embedded in a string for "#+AUTHOR:"
>
> With version 7.x, the following line
>
> #+AUTHOR: Joseph Kim\\Department of Electrical and Electronic
> Engineering\\Example University
>

[...]

> With version 8.2.7c, however, the same line is exported to
>
> \author{Joseph Kim$\backslash$\Department of Electrical and Electronic
> Engineering$\backslash$\Example University}
>
> which results in LaTeX compilation error.

AUTHOR, like TITLE, and DATE, now expect Org syntax, not LaTeX code. You
can insert raw LaTeX using an export snippet: @@latex:\\@@. Your author
line would then be


  #+AUTHOR: Joseph Kim@@latex:\\@@Department of Electrical and Electronic Engineering@@latex:\\@@Example University

Note that you can shorten this with a macro.

> 2. Accessing the value of "#+KEYWORDS:" and change of cases in
> "org-special-blocks"
>
> For keywords section in IEEE papers, I used to have the following settings:
>
> #+KEYWORDS: AAA, BBB, CCC
> ...
> #+BEGIN_IEEEkeywords
> {{{KEYWORDS}}}.
> #+END_IEEEkeywords

[...]

> Version 8.2.7c, however, produces the following from the same settings:
>
> \begin{ieeekeywords}
> .
> \end{ieeekeywords}

I'm surprised {{{KEYWORDS}}} even worked as, AFAIK, it wasn't
documented.  Indeed, there is no such macro in Org 8.0.  However, you
can define your own

#+MACRO: keywords AAA, BBB, CCC

and then use

#+BEGIN_IEEEkeywords
{{{keywords}}}.
#+END_IEEEkeywords

> Because the keyword environment in IEEE LaTeX class is case-sensitive,
> again it results in LaTeX compilation error.

I fixed it in master. It will land in Org 8.3. Meanwhile, you can use
a filter to upcase IEEE in your special blocks.


Regards,

-- 
Nicolas Goaziou