Bernt's document and LaTeX [was: Re: [Orgmode] http://doc.norang.ca/org-mode.html ]

[Nick Dokos]

Carsten Dominik <address@hidden> wrote:

> I would like to encourage you all to take another looks at Bernt's
> nearly completed document over at
> 
>      http://doc.norang.ca/org-mode.html
> 
> If you are serious about using Org-mode to get organized, this
> is simply an awesome resource of ideas, customization snippets,
> tips and tricks.  I am learning looking at that, too.
> 
> Thanks for doing this, Bernt.
> 

Seconded, thirded and fourthed: thanks Bernt!

And while we are on the subject of Bernt's document: I haven't looked at
the most recent incarnation on Bernt's website, but I got his org file
from worg the other day and I tried to export it to LaTeX/PDF and print
a copy to read (I prefer paper for documents that I'd like to read
carefully - in this case, I can also put the printed document under my
pillow: I hear it's the only way for hopeless cases like me to get
organized !-)

But I ran into a problem with the LaTeX exporter.

Bernt uses code emphasis in a bunch of places, e.g. with TODO keywords,
like the following:

,----
| *** Normal Task States
| Normal tasks go through the sequence =TODO= -> =STARTED= -> =DONE=.
| The second sequence is really just a convenient collection of odd-ball
| states for tasks (=WAITING=, =SOMEDAY=, =CANCELLED=).
`----

but also in headings, like this:

,----
| *** Using =STARTED= for clocked tasks
|     Tasks automatically change to =STARTED= whenever they are clocked in.
`----

The LaTeX exporter turns these into the following:

,----
| \subsubsection{Normal Task States}
| \label{sec-3.1.1}
| 
| Normal tasks go through the sequence \verb~TODO~ -> \verb~STARTED~ -> 
\verb~DONE~.
| The second sequence is really just a convenient collection of odd-ball
| states for tasks (\verb~WAITING~, \verb~SOMEDAY~, \verb~CANCELLED~).
`----

and

,----
| \subsubsection{Using \verb~STARTED~ for clocked tasks}
| \label{sec-3.3.1}
| 
|     Tasks automatically change to \verb~STARTED~ whenever they are clocked in.
`----

But \verb is a "fragile" command and cannot be used in a moving argument
(e.g.  a subsubsection heading - it's a "moving" argument because it's
going to be "moved around" on its way to the table of contents and its
expansion has to be timed correctly), so LaTeX complains about the \verb
in the \subsubsection title above. The standard way to deal with this
problem is to \protect the fragile command: use \protect\verb instead of
\verb in the moving argument. I did something simpler: I tweaked the
exporter to \protect every \verb - afaik, this might be inefficient, but
it should not cause a problem. I did that with the following patch:

--- a/lisp/org-latex.el
+++ b/lisp/org-latex.el
@@ -1377,7 +1385,7 @@ The conversion is made depending of STRING-BEFORE and 
STRING-AFTER."
                (if (not (string-match (regexp-quote (substring ll i (1+ i)))
                                       string))
                    (progn
-                     (setq format (concat "\\verb" (substring ll i (1+ i))
+                     (setq format (concat "\\protect\\verb" (substring ll i 
(1+ i))
                                           "%s" (substring ll i (1+ i))))
                      (throw 'exit nil))))))))
   (setq string (org-export-latex-protect-string

The resulting LaTeX document has every \verb properly (NOT!)
\protect'ed. But LaTeX sure does not like the result:

,----
| This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6) (format=pdflatex 
2009.2.9)  8 JUN 2009 18:17
| entering extended mode
|  %&-line parsing enabled.
| **org-mode.tex
| (./org-mode.tex
| LaTeX2e <2005/12/01>
| Babel <v3.8h> and hyphenation patterns for english, usenglishmax, dumylang, 
noh
| yphenation, pinyin, loaded.
| (/usr/share/texmf-texlive/tex/latex/base/article.cls
| Document Class: article 2005/09/16 v1.4f Standard LaTeX document class
| 
| ....lots of stuff elided ....
| 
| [15] [16] [17]
| Runaway argument?
| the \protect \relax \hbox {}#I\catcode `\ \active \<let>-command 
\csname\endcsn
| ame
| ! Paragraph ended before \HyPsd@@ProtectSpaces was complete.
| <to be read again> 
|                    \par 
| l.918 ...ct\verb~STARTED~ task list under control}
|                                                   
| ?
`----

The funny thing is that there are four instances of this construct in
Bernt's document:

,----
| ...
| \subsubsection{Using \protect\verb~STARTED~ for clocked tasks}
| ...
| \subsubsection{Why keep it all on the \protect\verb~STARTED~ list?}
| ...
| \subsection{Keeping the \protect\verb~STARTED~ task list under control}
| ...
| \subsubsection{\textbf{UNFINISHED} Using \protect\verb~f5~}
| ...
`----

and it's only the third one that causes a problem: if I get rid of the
markup on that one, pdfLaTeX finishes normally. Aha! I noted that the problem
is a \subsection argument, whereas the others are \subsubsection
arguments - the former appears in the TOC, whereas the latter do not by
default - but if I change the \tocdepth from the default 2 to 3, then 
subsubsections
get added to the table of contents and then LaTeX barfs on those too: \protect 
is
a bust.

After doing a little research, I found out that \verb is not just "fragile":
it's *special* (see e.g. 
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin
where I find:

      This is why the LaTeX book insists that verbatim commands must not
      appear in the argument of any other command; they aren’t just
      fragile, they’re quite unusable in any command parameter,
      regardless of \protection. (The \verb command tries hard to detect
      if you’re misusing it; unfortunately, it can’t always do so, and
      the error message is therefore not a reliable indication of
      problems.)

The suggested workaround is to actually use \texttt{foo}, instead of
\verb~foo~ where the two would give identical results.  This has
problems of its own: the main one is things like underscores which would
need to be escaped. But I wonder if the LaTeX exporter should go this
way, rather than fighting with \verb all the way (and losing). Or if we
can distinguish between body instances and section heading instances, do
the \texttt{foo} transformation only on the latter.

Comments?

Thanks,
Nick