Browse Source

Consistent capitalisation of option and environment keywords.

Also explain this convention.

Two exceptions: #+results, as it is dynamically inserted and
has always been lowercase, and #+BEGIN_LaTeX, with mixed case
to respect Lamport's will.  But all these keywords can be
written with lower/upper/mixed case.

Thanks to François Pinard for raising this issue.
Bastien Guerry 13 years ago
parent
commit
d2b3db915a
1 changed files with 36 additions and 29 deletions
  1. 36 29
      doc/org.texi

+ 36 - 29
doc/org.texi

@@ -1078,7 +1078,7 @@ attach it to your bug report.
 @node Conventions,  , Feedback, Introduction
 @section Typesetting conventions used in this manual
 
-Org uses three types of keywords: TODO keywords, tags, and property
+Org uses three types of keywords: TODO keywords, tags and property 
 names.  In this manual we use the following conventions:
 
 @table @code
@@ -1096,7 +1096,14 @@ User-defined properties are capitalized; built-in properties with
 special meaning are written with all capitals.
 @end table
 
-The manual lists both the keys and the corresponding commands for accessing
+Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
+and @i{environment keywords} (like @code{#+BEGIN_LaTeX} to start a @LaTeX{}
+environment).  Both are written in uppercase@footnote{@code{#+results} is the
+only exception, as it is dynamically inserted with lowercase characters.} for
+a better readability of the manual, but you can safely use lowercase
+(e.g. @code{#+title} and @code{#+begin_latex}) in your Org files.
+
+The manual lists both the keys and the corresponding commands for accessing a
 functionality.  Org mode often uses the same key for different functions,
 depending on context.  The command that is bound to such keys has a generic
 name, like @code{org-metaright}.  In the manual we will, wherever possible,
@@ -9641,7 +9648,7 @@ Insert template with export options, see example below.
 @cindex #+EXPORT_SELECT_TAGS
 @cindex #+EXPORT_EXCLUDE_TAGS
 @cindex #+XSLT
-@cindex #+LATEX_HEADER
+@cindex #+LaTeX_HEADER
 @vindex user-full-name
 @vindex user-mail-address
 @vindex org-export-default-language
@@ -9661,7 +9668,7 @@ Insert template with export options, see example below.
                @r{You need to confirm using these, or configure @code{org-export-allow-BIND}}
 #+LINK_UP:     the ``up'' link of an exported page
 #+LINK_HOME:   the ``home'' link of an exported page
-#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@}
+#+LaTeX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@}
 #+EXPORT_SELECT_TAGS:   Tags that select a tree for export
 #+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export
 #+XSLT:        the XSLT stylesheet used by DocBook exporter to generate FO file
@@ -10333,11 +10340,11 @@ By default, the @LaTeX{} output uses the class @code{article}.
 @vindex org-export-latex-classes
 @vindex org-export-latex-default-packages-alist
 @vindex org-export-latex-packages-alist
-@cindex #+LATEX_HEADER
-@cindex #+LATEX_CLASS
-@cindex #+LATEX_CLASS_OPTIONS
-@cindex property, LATEX_CLASS
-@cindex property, LATEX_CLASS_OPTIONS
+@cindex #+LaTeX_HEADER
+@cindex #+LaTeX_CLASS
+@cindex #+LaTeX_CLASS_OPTIONS
+@cindex property, LaTeX_CLASS
+@cindex property, LaTeX_CLASS_OPTIONS
 You can change this globally by setting a different value for
 @code{org-export-latex-default-class} or locally by adding an option like
 @code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
@@ -10349,7 +10356,7 @@ defines a header template for each class@footnote{Into which the values of
 define the sectioning structure for each class.  You can also define your own
 classes there.  @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS}
 property can specify the options for the @code{\documentclass} macro.  You
-can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the
+can also use @code{#+LaTeX_HEADER: \usepackage@{xyz@}} to add lines to the
 header.  See the docstring of @code{org-export-latex-classes} for more
 information.
 
@@ -10524,7 +10531,7 @@ transitions.
 Frames will automatically receive a @code{fragile} option if they contain
 source code that uses the verbatim environment.  Special @file{beamer}
 specific code can be inserted using @code{#+BEAMER:} and
-@code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other export
+@code{#+BEGIN_BEAMER...#+END_BEAMER} constructs, similar to other export
 backends, but with the difference that @code{#+LaTeX:} stuff will be included
 in the presentation as well.
 
@@ -12245,7 +12252,7 @@ publish it as @file{theindex.html}.
 @end multitable
 
 The file will be created when first publishing a project with the
-@code{:makeindex} set.  The file only contains a statement @code{#+include:
+@code{:makeindex} set.  The file only contains a statement @code{#+INCLUDE:
 "theindex.inc"}.  You can then build around this include statement by adding
 a title, style information, etc.
 
@@ -13023,7 +13030,7 @@ case, variables require a default value when they are declared.
 The values passed to arguments can either be literal values, references, or
 Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References
 include anything in the Org mode file that takes a @code{#+NAME:},
-@code{#+TBLNAME:}, or @code{#+RESULTS:} line.  This includes tables, lists,
+@code{#+TBLNAME:}, or @code{#+results:} line.  This includes tables, lists,
 @code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other
 code blocks.
 
@@ -13338,10 +13345,10 @@ The results are interpreted as raw Org mode code and are inserted directly
 into the buffer.  If the results look like a table they will be aligned as
 such by Org mode.  E.g., @code{:results value raw}.
 @item @code{html}
-Results are assumed to be HTML and will be enclosed in a @code{begin_html}
+Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML}
 block.  E.g., @code{:results value html}.
 @item @code{latex}
-Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block.
+Results assumed to be @LaTeX{} and are enclosed in a @code{BEGIN_LaTeX} block.
 E.g., @code{:results value latex}.
 @item @code{code}
 Result are assumed to be parsable code and are enclosed in a code block.
@@ -14217,19 +14224,19 @@ keystrokes are typed on a line by itself.
 The following template selectors are currently supported.
 
 @multitable @columnfractions 0.1 0.9
-@item @kbd{s} @tab @code{#+begin_src     ... #+end_src}
-@item @kbd{e} @tab @code{#+begin_example ... #+end_example}
-@item @kbd{q} @tab @code{#+begin_quote   ... #+end_quote}
-@item @kbd{v} @tab @code{#+begin_verse   ... #+end_verse}
-@item @kbd{c} @tab @code{#+begin_center  ... #+end_center}
-@item @kbd{l} @tab @code{#+begin_latex   ... #+end_latex}
-@item @kbd{L} @tab @code{#+latex:}
-@item @kbd{h} @tab @code{#+begin_html    ... #+end_html}
-@item @kbd{H} @tab @code{#+html:}
-@item @kbd{a} @tab @code{#+begin_ascii   ... #+end_ascii}
-@item @kbd{A} @tab @code{#+ascii:}
-@item @kbd{i} @tab @code{#+index:} line
-@item @kbd{I} @tab @code{#+include:} line
+@item @kbd{s} @tab @code{#+BEGIN_SRC     ... #+END_SRC}
+@item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
+@item @kbd{q} @tab @code{#+BEGIN_QUOTE   ... #+END_QUOTE}
+@item @kbd{v} @tab @code{#+BEGIN_VERSE   ... #+END_VERSE}
+@item @kbd{c} @tab @code{#+BEGIN_CENTER  ... #+END_CENTER}
+@item @kbd{l} @tab @code{#+BEGIN_LaTeX   ... #+END_LaTeX}
+@item @kbd{L} @tab @code{#+LaTeX:}
+@item @kbd{h} @tab @code{#+BEGIN_HTML    ... #+END_HTML}
+@item @kbd{H} @tab @code{#+HTML:}
+@item @kbd{a} @tab @code{#+BEGIN_ASCII   ... #+END_ASCII}
+@item @kbd{A} @tab @code{#+ASCII:}
+@item @kbd{i} @tab @code{#+INDEX:} line
+@item @kbd{I} @tab @code{#+INCLUDE:} line
 @end multitable
 
 For example, on an empty line, typing "<e" and then pressing TAB, will expand
@@ -14586,7 +14593,7 @@ This line contains the formulas for the table directly above the line.
 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,
 @itemx #+OPTIONS:, #+BIND:, #+XSLT:,
 @itemx #+DESCRIPTION:, #+KEYWORDS:,
-@itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
+@itemx #+LaTeX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
 @itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:
 These lines provide settings for exporting files.  For more details see
 @ref{Export options}.