Last chance clean-up of org.texi
This commit is contained in:
Tom Dye
Eric Schulte
parent
4482058c0c
commit
b5efd50fb5
211
doc/org.texi
211
doc/org.texi
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
\input texinfo
|
||||
@c %**start of header
|
||||
@setfilename ../../info/org
|
||||
@setfilename info/org
|
||||
@settitle The Org Manual
|
||||
|
||||
@set VERSION 6.36trans
|
||||
|
|
@ -108,7 +108,7 @@ license to the document, as described in section 6 of the license.
|
|||
* Markup:: Prepare text for rich export
|
||||
* Exporting:: Sharing and publishing of notes
|
||||
* Publishing:: Create a web site of linked Org files
|
||||
* Working With Source Code:: Code evaluation inside Org-mode
|
||||
* Working With Source Code:: Export, evaluate, and tangle code blocks
|
||||
* Miscellaneous:: All the rest which did not fit elsewhere
|
||||
* Hacking:: How to hack your way around
|
||||
* MobileOrg:: Viewing and capture on a mobile device
|
||||
|
|
@ -380,6 +380,13 @@ Publishing
|
|||
* Uploading files:: How to get files up on the server
|
||||
* Sample configuration:: Example projects
|
||||
* Triggering publication:: Publication commands
|
||||
* Library of Babel::
|
||||
* Languages::
|
||||
* Header arguments::
|
||||
* Results::
|
||||
* Noweb reference syntax::
|
||||
* Key bindings & useful functions::
|
||||
* Batch execution::
|
||||
|
||||
Configuration
|
||||
|
||||
|
|
@ -397,6 +404,50 @@ Sample configuration
|
|||
* Simple example:: One-component publishing
|
||||
* Complex example:: A multi-component publishing example
|
||||
|
||||
Working With Source Code
|
||||
|
||||
* Structure of code blocks::
|
||||
* Editing source code::
|
||||
* Exporting code blocks::
|
||||
* Extracting source code::
|
||||
* Evaluating code blocks::
|
||||
* Library of Babel::
|
||||
* Languages::
|
||||
* Header arguments::
|
||||
* Results::
|
||||
* Noweb reference syntax::
|
||||
* Key bindings & useful functions::
|
||||
* Batch execution::
|
||||
|
||||
Header arguments
|
||||
|
||||
* Using header arguments::
|
||||
* Specific header arguments::
|
||||
|
||||
Using header arguments
|
||||
|
||||
* System-wide header arguments::
|
||||
* Language-specific header arguments::
|
||||
* Buffer-wide header arguments::
|
||||
* Header arguments in Org-mode properties::
|
||||
* Code block specific header arguments::
|
||||
|
||||
Specific header arguments
|
||||
|
||||
* var argument::
|
||||
* results argument::
|
||||
* file argument::
|
||||
* dir and remote execution::
|
||||
* exports argument::
|
||||
* tangle argument::
|
||||
* no-expand argument::
|
||||
* session argument::
|
||||
* noweb argument::
|
||||
* cache argument::
|
||||
* hlines argument::
|
||||
* colnames argument::
|
||||
* rownames argument::
|
||||
|
||||
Miscellaneous
|
||||
|
||||
* Completion:: M-TAB knows what you need
|
||||
|
|
@ -10353,6 +10404,13 @@ Publishing has been contributed to Org by David O'Toole.
|
|||
* Uploading files:: How to get files up on the server
|
||||
* Sample configuration:: Example projects
|
||||
* Triggering publication:: Publication commands
|
||||
* Library of Babel::
|
||||
* Languages::
|
||||
* Header arguments::
|
||||
* Results::
|
||||
* Noweb reference syntax::
|
||||
* Key bindings & useful functions::
|
||||
* Batch execution::
|
||||
@end menu
|
||||
|
||||
@node Configuration, Uploading files, Publishing, Publishing
|
||||
|
|
@ -10844,10 +10902,14 @@ above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
|
|||
This may be necessary in particular if files include other files via
|
||||
@code{#+SETUPFILE:} or @code{#+INCLUDE:}.
|
||||
|
||||
@node Working With Source Code, Miscellaneous, Publishing, Top
|
||||
@comment node-name, next, previous, up
|
||||
@comment Working With Source Code, Miscellaneous, Publishing, Top
|
||||
|
||||
@node Working With Source Code, Miscellaneous, Publishing, Top
|
||||
@chapter Working With Source Code
|
||||
@cindex Schulte, Eric
|
||||
@cindex Davison, Dan
|
||||
@cindex source code, working with
|
||||
|
||||
Source code can be included in Org-mode documents using a @samp{src} block,
|
||||
e.g.
|
||||
|
|
@ -10860,11 +10922,11 @@ e.g.
|
|||
#+END_SRC
|
||||
@end example
|
||||
|
||||
Org provides a number of features for working with live source code,
|
||||
Org-mode provides a number of features for working with live source code,
|
||||
including editing of code blocks in their native major-mode, evaluation of
|
||||
code blocks, tangling of code blocks, and exportation of code blocks and
|
||||
their results to a number of formats. The following sections provide a
|
||||
thorough tour of Org-mode's sophisticated code block handling facilities.
|
||||
their results to a number of formats. The following sections describe
|
||||
Org-mode's code block handling facilities.
|
||||
|
||||
@menu
|
||||
* Structure of code blocks::
|
||||
|
|
@ -10898,9 +10960,9 @@ The structure of code blocks is as follows:
|
|||
|
||||
@table @code
|
||||
@item <name>
|
||||
This name is associated with the source code block. This is similar to the
|
||||
This name is associated with the code block. This is similar to the
|
||||
@samp{#+tblname} lines that can be used to name tables in Org-mode files.
|
||||
Referencing the name of a source code block makes it possible to evaluate the
|
||||
Referencing the name of a code block makes it possible to evaluate the
|
||||
block from other places in the file, other files, or from Org-mode table
|
||||
formulas (see @ref{The spreadsheet}).
|
||||
@item <language>
|
||||
|
|
@ -10914,7 +10976,7 @@ tangling of source code blocks. See the @ref{Header arguments}
|
|||
section. Header arguments can also be set on a per-buffer or per-subtree
|
||||
basis using properties.
|
||||
@item <body>
|
||||
The code
|
||||
The source code.
|
||||
@end table
|
||||
|
||||
@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
|
||||
|
|
@ -10960,7 +11022,7 @@ some languages (e.g. @code{ditaa}) the default exports the results of code
|
|||
block evaluation. For information on exporting code block bodies, see
|
||||
@ref{Literal examples}.
|
||||
|
||||
The @code{:exports} header argument can be used to specify non-default export
|
||||
The @code{:exports} header argument can be used to specify export
|
||||
behavior:
|
||||
|
||||
@subsubheading Header arguments:
|
||||
|
|
@ -10980,9 +11042,9 @@ Both the code block and its results will be exported.
|
|||
Neither the code block nor its results will be exported.
|
||||
@end table
|
||||
|
||||
@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
|
||||
@comment node-name, next, previous, up
|
||||
@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
|
||||
@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
|
||||
@section Extracting source code
|
||||
|
||||
Creating pure source code files by extracting code from source blocks is
|
||||
|
|
@ -11011,13 +11073,14 @@ Tangle the current file.
|
|||
Choose a file to tangle.
|
||||
@end table
|
||||
|
||||
@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
|
||||
@comment node-name, next, previous, up
|
||||
@comment Evaluating code blocks, , Extracting source code, Working With Source Code
|
||||
|
||||
@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
|
||||
@section Evaluating code blocks
|
||||
|
||||
Code blocks can be evaluated and the results placed in the Org-mode buffer.
|
||||
Check the value of the @code{org-babel-interpreters} for a list of languages
|
||||
Check the value of the variable @code{org-babel-interpreters} for a list of languages
|
||||
that can be evaluated on your system. See also @ref{Languages} for a list of
|
||||
supported languages. See @ref{Structure of code blocks} for information on
|
||||
the syntax used to define a code block.
|
||||
|
|
@ -11035,6 +11098,8 @@ blocks located in the current Org-mode buffer or in the ``Library of Babel''
|
|||
|
||||
@example
|
||||
#+call: <name>(<arguments>) <header arguments>
|
||||
#+function: <name>(<arguments>) <header arguments>
|
||||
#+lob: <name>(<arguments>) <header arguments>
|
||||
@end example
|
||||
|
||||
@table @code
|
||||
|
|
@ -11171,29 +11236,29 @@ of the language names from the above table).
|
|||
@node Header arguments, Results, Languages, Working With Source Code
|
||||
@section Header arguments
|
||||
|
||||
Most code block functionality is configurable using header arguments. This
|
||||
Code block functionality can be configured with header arguments. This
|
||||
section provides an overview of the use of header arguments, and then
|
||||
exhaustively covers all header arguments.
|
||||
describes each header argument in detail.
|
||||
|
||||
@menu
|
||||
* Using Header arguments::
|
||||
* Specific Header arguments::
|
||||
* Using header arguments::
|
||||
* Specific header arguments::
|
||||
@end menu
|
||||
|
||||
@node Using Header arguments, Specific Header arguments, , Header arguments
|
||||
@subsection Using Header arguments
|
||||
@node Using header arguments, Specific header arguments, Header arguments, Header arguments
|
||||
@subsection Using header arguments
|
||||
|
||||
The values of header arguments can be set in five different ways, each more
|
||||
specific (and having higher priority) than the last.
|
||||
@menu
|
||||
* System-wide header arguments::
|
||||
* Language Specific header arguments::
|
||||
* Language-specific header arguments::
|
||||
* Buffer-wide header arguments::
|
||||
* Header arguments in Org-mode Properties::
|
||||
* Code Block specific header arguments::
|
||||
* Header arguments in Org-mode properties::
|
||||
* Code block specific header arguments::
|
||||
@end menu
|
||||
|
||||
@node System-wide header arguments, Language Specific header arguments, , Using Header arguments
|
||||
@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
|
||||
@subsubheading System-wide header arguments
|
||||
System-wide values of header arguments can be specified by customizing the
|
||||
@code{org-babel-default-header-args} variable:
|
||||
|
|
@ -11223,21 +11288,21 @@ blocks.
|
|||
(assq-delete-all :noweb org-babel-default-header-args)))
|
||||
@end example
|
||||
|
||||
@node Language Specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using Header arguments
|
||||
@subsubheading Language Specific header arguments
|
||||
@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
|
||||
@subsubheading Language-specific header arguments
|
||||
Each language can define its own set of default header arguments. See the
|
||||
language-specific documentation available at
|
||||
@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}.
|
||||
@uref{http://orgmode.org/worg/org-contrib/babel/reference.php#languages}
|
||||
for information on language-specific header arguments.
|
||||
|
||||
@node Buffer-wide header arguments, Header arguments in Org-mode Properties, Language Specific header arguments, Using Header arguments
|
||||
@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments
|
||||
@subsubheading Buffer-wide header arguments
|
||||
FIXME
|
||||
|
||||
@node Header arguments in Org-mode Properties, Code Block specific header arguments, Buffer-wide header arguments, Using Header arguments
|
||||
@subsubheading header arguments in Org-mode Properties
|
||||
@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments
|
||||
@subsubheading Header arguments in Org-mode properties
|
||||
|
||||
Header arguments are also read from Org-mode Properties (see @ref{Property
|
||||
Header arguments are also read from Org-mode properties (see @ref{Property
|
||||
syntax}), which can be set on a buffer-wide or per-heading basis. An example
|
||||
of setting a header argument for all code blocks in a buffer is
|
||||
|
||||
|
|
@ -11262,8 +11327,8 @@ Properties defined in this way override the properties set in
|
|||
@code{org-set-property} function bound to @key{C-c C-x p} to set properties
|
||||
in Org-mode documents.
|
||||
|
||||
@node Code Block specific header arguments, , Header arguments in Org-mode Properties, Using Header arguments
|
||||
@subsubheading Code Block specific header arguments
|
||||
@node Code block specific header arguments, , Header arguments in Org-mode properties, Using header arguments
|
||||
@subsubheading Code block specific header arguments
|
||||
|
||||
The most common way to assign values to header arguments is at the
|
||||
code block level. This can be done by listing a sequence of header
|
||||
|
|
@ -11296,28 +11361,28 @@ Header arguments for ``Library of Babel'' or function call lines can be set as s
|
|||
#+call: factorial(n=5) :exports results
|
||||
@end example
|
||||
|
||||
@node Specific Header arguments, , Using Header arguments, Header arguments
|
||||
@subsection Specific Header arguments
|
||||
@node Specific header arguments, , Using header arguments, Header arguments
|
||||
@subsection Specific header arguments
|
||||
The following header arguments are defined:
|
||||
|
||||
@menu
|
||||
* var::
|
||||
* results::
|
||||
* file::
|
||||
* var argument::
|
||||
* results argument::
|
||||
* file argument::
|
||||
* dir and remote execution::
|
||||
* exports::
|
||||
* tangle::
|
||||
* no-expand::
|
||||
* session::
|
||||
* noweb::
|
||||
* cache::
|
||||
* hlines::
|
||||
* colnames::
|
||||
* rownames::
|
||||
* exports argument::
|
||||
* tangle argument::
|
||||
* no-expand argument::
|
||||
* session argument::
|
||||
* noweb argument::
|
||||
* cache argument::
|
||||
* hlines argument::
|
||||
* colnames argument::
|
||||
* rownames argument::
|
||||
@end menu
|
||||
|
||||
@node var, results, , Specific Header arguments
|
||||
@subsubsection var
|
||||
@node var argument, results argument, Specific header arguments, Specific header arguments
|
||||
@subsubsection var argument
|
||||
The @code{:var} header argument is used to pass arguments to
|
||||
code blocks. The specifics of how arguments are included
|
||||
in a code block vary by language; these are
|
||||
|
|
@ -11412,7 +11477,7 @@ following the source name.
|
|||
#+end_src
|
||||
@end example
|
||||
|
||||
@subsubheading indexable variable values
|
||||
@subsubheading Indexable variable values
|
||||
It is possible to assign a portion of a value to a variable in a source
|
||||
block. The following example assigns the second and third rows of the table
|
||||
@code{example-table} to the variable @code{data}:
|
||||
|
|
@ -11451,8 +11516,8 @@ For more information on indexing behavior see the documentation for the
|
|||
which case the entire range is returned.
|
||||
@end example
|
||||
|
||||
@node results, file, var, Specific Header arguments
|
||||
@subsubsection results
|
||||
@node results argument, file argument, var argument, Specific header arguments
|
||||
@subsubsection results argument
|
||||
|
||||
There are three types of results header argument. Only one option of each
|
||||
type may be supplied per code block.
|
||||
|
|
@ -11546,8 +11611,8 @@ be prepended to the existing results. Otherwise the new results will be
|
|||
inserted as with @code{replace}.
|
||||
@end itemize
|
||||
|
||||
@node file, dir and remote execution, results, Specific Header arguments
|
||||
@subsubsection file
|
||||
@node file argument, dir and remote execution, results argument, Specific header arguments
|
||||
@subsubsection file argument
|
||||
@code{:file} is used to specify a path for file output in which case an
|
||||
Org-mode style link (see @ref{Link format}) @code{file:} link is inserted
|
||||
into the buffer as the result. Common examples are graphical output from R,
|
||||
|
|
@ -11561,7 +11626,7 @@ as python and ruby require that the code explicitly create output
|
|||
corresponding to the path indicated by @code{:file}.
|
||||
|
||||
|
||||
@node dir and remote execution, exports, file, Specific Header arguments
|
||||
@node dir and remote execution, exports argument, file argument, Specific header arguments
|
||||
@subsubsection dir and remote execution
|
||||
While the @code{:file} header argument can be used to specify the path to the
|
||||
output file, @code{:dir} specifies the default directory during code block
|
||||
|
|
@ -11628,8 +11693,8 @@ directory}. Therefore, if @code{default-directory} is altered using
|
|||
which the link does not point.
|
||||
@end itemize
|
||||
|
||||
@node exports, tangle, dir and remote execution, Specific Header arguments
|
||||
@subsubsection exports
|
||||
@node exports argument, tangle argument, dir and remote execution, Specific header arguments
|
||||
@subsubsection exports argument
|
||||
Specify what should be included in HTML or LaTeX exports of the Org-mode
|
||||
file.
|
||||
|
||||
|
|
@ -11647,8 +11712,8 @@ both the code and results are included in the exported file. E.g.,
|
|||
nothing is included in the exported file. E.g., @code{:exports none}.
|
||||
@end itemize
|
||||
|
||||
@node tangle, no-expand, exports, Specific Header arguments
|
||||
@subsubsection tangle
|
||||
@node tangle argument, no-expand argument, exports argument, Specific header arguments
|
||||
@subsubsection tangle argument
|
||||
Specify whether or not the source code block should be included in tangled
|
||||
extraction of source code files.
|
||||
|
||||
|
|
@ -11666,16 +11731,16 @@ as a file basename to which the block will be exported. E.g., @code{:tangle
|
|||
basename}.
|
||||
@end itemize
|
||||
|
||||
@node no-expand, session, tangle, Specific Header arguments
|
||||
@subsubsection no-expand
|
||||
@node no-expand argument, session argument, tangle argument, Specific header arguments
|
||||
@subsubsection no-expand argument
|
||||
By default, code blocks are expanded with @code{org-babel-expand-src-block}
|
||||
during tangling. This has the effect of assigning values to variables
|
||||
specified with @code{:var} (see @ref{var}), and of replacing ``noweb''
|
||||
specified with @code{:var} (see @ref{var argument}), and of replacing ``noweb''
|
||||
references (see @ref{Noweb reference syntax}) with their targets. The
|
||||
@code{:no-expand} header argument can be used to turn off this behavior.
|
||||
|
||||
@node session, noweb, no-expand, Specific Header arguments
|
||||
@subsubsection session
|
||||
@node session argument, noweb argument, no-expand argument, Specific header arguments
|
||||
@subsubsection session argument
|
||||
Start a session for an interpreted language where state is preserved. This
|
||||
applies particularly to the supported languages python, R and ruby.
|
||||
|
||||
|
|
@ -11685,8 +11750,8 @@ A string passed to the @code{:session} header argument will give the session
|
|||
a name. This makes it possible to run concurrent sessions for each
|
||||
interpreted language.
|
||||
|
||||
@node noweb, cache, session, Specific Header arguments
|
||||
@subsubsection noweb
|
||||
@node noweb argument, cache argument, session argument, Specific header arguments
|
||||
@subsubsection noweb argument
|
||||
Controls the expansion of ``noweb'' style (see @ref{Noweb reference syntax})
|
||||
references in a source code block. This header argument can have one of two
|
||||
values: @code{yes} or @code{no}.
|
||||
|
|
@ -11726,8 +11791,8 @@ Note that noweb replacement text that does not contain any newlines will not
|
|||
be affected by this change, so it is still possible to use inline noweb
|
||||
references.
|
||||
|
||||
@node cache, hlines, noweb, Specific Header arguments
|
||||
@subsubsection cache
|
||||
@node cache argument, hlines argument, noweb argument, Specific header arguments
|
||||
@subsubsection cache argument
|
||||
Controls the use of in-buffer caching of source code block results to avoid
|
||||
re-running unchanged source code blocks. This header argument can have one
|
||||
of two values: @code{yes} or @code{no}.
|
||||
|
|
@ -11744,8 +11809,8 @@ executions of the source code block. If the source code block has not
|
|||
changed since the last time it was evaluated, it will not be re-evaluated.
|
||||
@end itemize
|
||||
|
||||
@node hlines, colnames, cache, Specific Header arguments
|
||||
@subsubsection hlines
|
||||
@node hlines argument, colnames argument, cache argument, Specific header arguments
|
||||
@subsubsection hlines argument
|
||||
Tables are frequently represented with one or more horizontal lines, or
|
||||
hlines. The @code{:hlines} argument to a code block accepts the
|
||||
values @code{yes} or @code{no}, with a default value of @code{no}.
|
||||
|
|
@ -11801,8 +11866,8 @@ Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
|
|||
@end example
|
||||
@end itemize
|
||||
|
||||
@node colnames, rownames, hlines, Specific Header arguments
|
||||
@subsubsection colnames
|
||||
@node colnames argument, rownames argument, hlines argument, Specific header arguments
|
||||
@subsubsection colnames argument
|
||||
The @code{:colnames} header argument accepts the values @code{yes},
|
||||
@code{no}, or @code{nil} for unassigned. The default value is @code{nil}.
|
||||
|
||||
|
|
@ -11841,8 +11906,8 @@ does not ``look like'' it has column names (i.e. the second row is not an
|
|||
hline)
|
||||
@end itemize
|
||||
|
||||
@node rownames, , colnames, Specific Header arguments
|
||||
@subsubsection rownames
|
||||
@node rownames argument, , colnames argument, Specific header arguments
|
||||
@subsubsection rownames argument
|
||||
The @code{:rownames} header argument can take on the values @code{yes}
|
||||
or @code{no}, with a default value of @code{no}.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue