http://doc.norang.ca/org-mode.html

http://doc.norang.ca/org-mode.html

[Carsten Dominik]

Hi everyone,

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.

- Carsten

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

[Nick Dokos]

Carsten Dominik <carsten.dominik@gmail.com> 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

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

[Carsten Dominik]

Hi Nick,

that was educational! :-)

I have pushed a tentative fix, please verify.

- Carsten

On Jun 9, 2009, at 2:41 AM, Nick Dokos wrote:

> Carsten Dominik <carsten.dominik@gmail.com> 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
>

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

[Nick Dokos]

Carsten Dominik <carsten.dominik@gmail.com> wrote:


> that was educational! :-)

:-)

> 
> I have pushed a tentative fix, please verify.
> 

I tried it on (the old version of) Bernt's document and it worked fine.
I also tried it on a document with underscores: no problems there either.

Thanks!
Nick

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

[Bernt Hansen]

Nick Dokos <nicholas.dokos@hp.com> writes:

> Carsten Dominik <carsten.dominik@gmail.com> 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!
>

Thanks for the encouragement guys :) I'm hoping to fill out the
unfinished sections of this document soon.  As long as there are
sections marked UNFINISHED I expect this document to be updated at least
once a week.

The last export time for the document is at the bottom of the file so
you can quickly see if there is any new content since the last time you
viewed it.

This document has turned into a bit of a monster with a life of its own
it seems.  It's _way_ longer than I originally intended.

I'm not sure it'll ever be _truly_ finished though ... I'm finding that
when I tweak my workflow I just keep updating this document.  When I try
some new workflow that might improve things for me I schedule a task to
describe this new workflow a month in the future -- this way the new
workflow can mature or die and I'm only documenting things that really
work well for me.  You'll probably see new items about some of the
following in the next 30 days:

  - Why I have special key bindings
  - Combining refile targets into one
  - Limiting time spent on tasks

Regards,
Bernt

Re: http://doc.norang.ca/org-mode.html

[Eraldo Helal]

Great work!