[OT] basic emacs tips you will need someday (was: Footnotes and R output when exporting to HTML or Latex)

[Paul R <paul.r.ml@gmail.com>]

Graham,

Graham> Thanks, but I would appreciate a bit more hand holding on this.
Graham> I don't actually know how to "check" org-footnote-re and
Graham> org-footnote-definition-re

I think the best help I can do is to describe the first steps to find
your way in the emacs jungle.

First, take a few minutes to read and try these three commands.

,----[ C-h k C-h k ]
| C-h k runs the command describe-key, which is an interactive compiled
| Lisp function in `help.el'.
| 
| It is bound to C-h k, <f1> k, <help> k, <menu-bar> <help-menu>
| <describe> <describe-key-1>.
| 
| (describe-key &optional key untranslated up-event)
| 
| Display documentation of the function invoked by key.
| key can be any kind of a key sequence; it can include keyboard events,
| mouse events, and/or menu events.  When calling from a program,
| pass key as a string or a vector.
| 
| If non-nil, untranslated is a vector of the corresponding untranslated events.
| It can also be a number, in which case the untranslated events from
| the last key sequence entered are used.
| up-event is the up-event that was discarded by reading key, or nil.
| 
| If key is a menu item or a tool-bar button that is disabled, this command
| temporarily enables it to allow getting help on disabled items and buttons.
| 
| [back]
`----

,----[ C-h k C-h v ]
| C-h v runs the command describe-variable, which is an interactive
| compiled Lisp function in `help-fns.el'.
| 
| It is bound to C-h v, <f1> v, <help> v, <menu-bar> <help-menu>
| <describe> <describe-variable>.
| 
| (describe-variable variable &optional buffer frame)
| 
| Display the full documentation of variable (a symbol).
| Returns the documentation as a string, also.
| If variable has a buffer-local value in buffer or frame
| (default to the current buffer and current frame),
| it is displayed along with the global value.
| 
| [back]
`----

,----[ C-h k C-h f ]
| C-h f runs the command describe-function, which is an interactive
| compiled Lisp function in `help-fns.el'.
| 
| It is bound to C-h f, <f1> f, <help> f, <menu-bar> <help-menu>
| <describe> <describe-function>.
| 
| (describe-function function)
| 
| Display the full documentation of function (a symbol).
| 
| [back]
`----


Now you are ready to discover org-footnote-definition-re and
org-footnote-re. Just press "C-h v org-footnote-re RET" (RET being
enter).

,----[ C-h v org-footnote-re RET ]
| org-footnote-re is a variable defined in `org-footnote.el'.
| Its value is 
| ".\\[\\(?:\\([0-9]+\\)\\|\\(fn:\\([-_[:word:]]+?\\)?\\)\\(?::\\([^]]*?\\)\\)?\\)\\]"
| 
| Documentation:
| Regular expression for matching footnotes.
| 
| [back]
`----

,----[ C-h v org-footnote-definition-re RET ]
| org-footnote-definition-re is a variable defined in `org-footnote.el'.
| Its value is 
| "^\\(\\[\\([0-9]+\\|fn:[-_[:word:]]+\\)\\]\\)"
| 
| Documentation:
| Regular expression matching the definition of a footnote.
| 
| [back]
`----

Right. Now you have a good idea of what those variables are for. 

But wait ! How to guess the names of the variables ?

,----[ C-h f apropos-variable RET ]
| apropos-variable is an interactive compiled Lisp function in
| `apropos.el'.
| 
| It is bound to <menu-bar> <help-menu> <search-documentation>
| <find-options-by-name>.
| 
| (apropos-variable pattern &optional do-all)
| 
| Show user variables that match pattern.
| pattern can be a word, a list of words (separated by spaces),
| or a regexp (using some regexp special characters).  If it is a word,
| search for matches for that word as a substring.  If it is a list of words,
| search for matches for any two (or more) of those words.
| 
| With C-u prefix, or if `apropos-do-all' is non-nil, also show
| normal variables.
| 
| [back]
`----

So calling M-x apropos-variable RET org.*footnote RET will return :

,----[ M-x apropos-variable RET org.*footnote RET ]
| org-export-html-footnotes-section
|   Variable: Format for the footnotes section.
| org-export-with-footnotes
|   Variable: If nil, export [1] as a footnote marker.
| org-footnote-auto-label
|   Variable: Non-nil means, define automatically new labels for footnotes.
| org-footnote-define-inline
|   Variable: Non-nil means, define footnotes inline, at reference location.
| org-footnote-definition-re
|   Variable: Regular expression matching the definition of a footnote.
| org-footnote-fill-after-inline-note-extraction
|   Variable: Non-nil means, fill paragraphs after extracting footnotes.
| org-footnote-label-history
|   Variable: History of footnote labels entered in current buffer.
| org-footnote-re
|   Variable: Regular expression for matching footnotes.
| org-footnote-section
|   Variable: Outline heading containing footnote definitions before export.
| org-footnote-tag-for-non-org-mode-files
|   Variable: Tag marking the beginning of footnote section.
`----

Oh, and org-export-with-footnotes looks interesting also.


How to set all those variables now ? In your emacs session, you probably
have a *scratch* buffer where you can type the emacs lisp language. You
will need the setq function 

,----[ C-h f setq RET ]
| setq is a special form in `C source code'.
| 
| (setq [sym val]...)
| 
| Set each sym to the value of its val.
| The symbols sym are variables; they are literal (not evaluated).
| The values val are expressions; they are evaluated.
| Thus, (setq x (1+ y)) sets `x' to the value of `(1+ y)'.
| The second val is not computed until after the first sym is set, and so on;
| each val can use the new value of variables set earlier in the `setq'.
| The return value of the `setq' form is the value of the last val.
| 
| [back]
`----

so if you want to set org-export-with-footnotes to nil, type

--8<---------------cut here---------------start------------->8---
(setq org-export-with-footnotes nil) 
--8<---------------cut here---------------end--------------->8---

To evaluate a line in the scratch buffer, go to the last closing paren
and do C-j or C-x C-e. You can immediatly try org exports to see if your
settings are ok.

Once you have find the settings you want for org-mode, you will want to
copy those lisp lines in your ~/.emacs file which is read at emacs
startup.


Want to know how I learned that ?

,----[ C-h f info RET ]
| info is an interactive autoloaded Lisp function in `info.el'.
| 
| It is bound to C-h i, <f1> i, <help> i.
| 
| (info &optional file-or-node buffer)
| 
| Enter Info, the documentation browser.
| Optional argument file-or-node specifies the file to examine;
| the default is the top-level directory of Info.
| Called from a program, file-or-node may specify an Info node of the form
| `(FILENAME)NODENAME'.
| Optional argument buffer specifies the Info buffer name;
| the default buffer name is *info*.  If buffer exists,
| just switch to buffer.  Otherwise, create a new buffer
| with the top-level Info directory.
| 
| In interactive use, a non-numeric prefix argument directs
| this command to read a file name from the minibuffer.
| A numeric prefix argument selects an Info buffer with the prefix number
| appended to the Info buffer name.
| 
| The search path for Info files is in the variable `Info-directory-list'.
| The top-level Info directory is made by combining all the files named `dir'
| in all the directories in that path.
| 
| See a list of available Info commands in `Info-mode'.
| 
| [back]
`----


I hope this does not sounds too much like a stupid RTFM. This was
a RTFM, indeed, but a nice one I hope  :)


-- 
  Paul