From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Lambda Coder <sjlambda@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: org.texi edits, patch attached
Date: Tue, 15 Nov 2016 08:47:39 +0100 [thread overview]
Message-ID: <87d1hxp4kk.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <CAM5gNT3fO8gbAVpSzJhq6+mFWQbRceFgiiUCoAdAFUVvb1Bo_Q@mail.gmail.com> (Lambda Coder's message of "Mon, 14 Nov 2016 04:02:37 -0800")
Hello,
Lambda Coder <sjlambda@gmail.com> writes:
> I've attached an updated patch file to this msg.
Thank you. Some comments and suggestions follow.
> -Source code can be included in Org mode documents using a @samp{src} block,
> -e.g.:
> +Source code here refers to any code typed in Org mode documents. Org can
> +manage source code in any Org file once such code is tagged with begin and
> +end markers. Working with source code begins with tagging source code
> +blocks. Such source code blocks can be put anywhere in an Org document.
I don't think we should add this last sentence, which may be misleading.
E.g., you cannot put a source block in a comment or a fixed width
area...
> +An important feature of Org's execution of the @samp{src} code blocks is
> +passing variables, functions, and results between @samp{src} blocks. Such
> +interoperability uses a common syntax even if these @samp{src} blocks are in
> +different source code languages. The integration extends to linking the
> +debugger's error messages to the line in the source code block in the Org
> +file. That should partly explain why this functionality by the original
> +contributors, Eric Schulte and Dan Davison, was called
> @samp{Org-babel}.
@samp{Org Babel}.
> +Org mode's @ref{Easy templates} system speeds up creating @samp{src} blocks
> +with just a couple of keystrokes. Don't be put-off by having to type or
> +remember the source block syntax. Emacs already has other completion systems
> +(yasnippet and company, to name two) that can be configured to create these
I don't think we should name them since they are not built-in.
> +Optional. Heading arguments control many aspects of evaluation, export and
> +tangling of code blocks (see @ref{Header arguments}). Using Org's properties
(@pxref{Header arguments})
> +Extracting source code from code blocks is one of the basic tasks in literate
> +programming. Org's features makes it an ideal tool for creating literate
> +programming documents. In literate programming parlance, on creation, such
> +documents are @emph{woven} with code and documentation, and on export, the
> +code is @emph{tangled} for execution by a computer. Org export facilitates
> +weaving and tangling with several customization options.
ITYM "Org babel" not "Org export".
> +When Org tangles the source code blocks, it expands, merges, and transforms
> +source code blocks. Then it recomposes them into one or more separate files
> +(as specified in the options). During this tangling process, Org expands
> +variables in the source code, and also resolve any ``noweb'' style references
> +(see @ref{Noweb reference syntax}).
(@pxref{Noweb reference syntax})
> +Debuggers normally link errors and messages back to the source code. But for
> +tangled files, we want to link back to the Org file, not to the tangled
> +source file. To make this extra jump, Org uses
> +@code{org-babel-tangle-jump-to-org} function with two additional source code
> +block header arguments: One, set @code{padline} (@ref{padline}) to true (the
(@pxref{padline})
> +default setting). Two, set @code{comments} (@ref{comments}) to
> @code{link}
Ditto.
> +After evaluation of the source code block, Org inserts the results after
> +inserting the label @code{#+RESULTS} in the Org file. Edit
> +@code{org-babel-results-keyword} to change the label, @code{#+RESULTS}. The
> +results may optionally have a cache identifier and a block name.
I would remove the sentence starting with "Edit @code{...}". Results
keyword is always "results". The variable above is just a way to change
case. For this reason, I don't think it is worth documenting.
Also, a space is missing before "Edit"
> +By default, (@code{emacs-lisp} is enabled for evaluation. The option to
> +enable additional languages for evaluation is
> +@code{org-babel-load-languages}. Use the Emacs customization interface to
> +change. Or add code to the init file as shown here:
Missing space above.
> +For buffer-wide header arguments, use @code{#+PROPERTY:} lines anywhere in
> +the Org mode file (see @ref{Property syntax}).
(@pxref{Property syntax})
> +The following example sets @code{*R*} (only for R code blocks) to
---only for @samp{R} code blocks---to
> +@code{session}, which means all R code is executed in the same session. It
> +also sets @code{results} from all blocks to @code{silent}, which means
> +results of executions for all blocks (not just R code blocks) are ignored
---not just @samp{R} code blocks---are ignored
> +(therefore, not inserted in the buffer).
and, therefore, not inserted in the buffer.
> +Header arguments set through property drawers (see @ref{Property
> syntax})
(@pxref{Property syntax})
> +apply at the sub-tree level on down. Since these property drawers can appear
> +anywhere in the file hierarchy, Org uses outermost call or source block to
> +resolve the values. Org ignores @code{org-use-property-inheritance} setting.
> +
> @vindex org-use-property-inheritance
This should go above the previous paragraph, shouldn't it?
> +would force separate sessions for clojure blocks in Heading and Subheading,
> +but use the same session for all R blocks. R blocks in Subheading inherit
@samp{R} blocks. In particular, such blocks in Subheading inherit...
> +Header arguments are most commonly set at the code block level. They appear
> +on the @code{#+BEGIN_SRC} line, and override header arguments in
> +@code{org-babel-default-header-args}, and any specified as properties. In
> +the following example, the @code{:results} header argument is set to
> +@code{silent}, which means execution results are not inserted. The
> +@code{:exports} header argument set to @code{code} exports only the body of
> +the code block to HTML or @LaTeX{}.
>
> @example
> +#+BEGIN_SRC emacs-lisp
> #+NAME: factorial
> #+BEGIN_SRC haskell :results silent :exports code :var n=0
Typo?
> +Code block header arguments can span multiple lines using either
> +@code{#+HEADER:} or @code{#+HEADERS:}---notice Org accepts both singular and
> +plural spellings.
Org accepts #+HEADERS only as a backward-compatible convenience. It may
be removed at some point, the correct syntax is #+HEADER. Therefore,
I wouldn't mention it in the manual.
> Headers come between the @code{#+NAME:} and
> +@code{#+BEGIN_SRC} lines.
I didn't check, but this might not be true. There is no order on the
affiliated keywords, at least for the parser. Babel may have its own
interpretation.
> @cindex #+HEADER:
> @cindex #+HEADERS:
Please remove the latter.
>
> -Multi-line header arguments on an un-named code block:
> +Multi-line header arguments on an unnamed code block:
>
> @example
> - #+HEADERS: :var data1=1
> - #+BEGIN_SRC emacs-lisp :var data2=2
> +#+BEGIN_SRC emacs-lisp
> +#+HEADERS: :var data1=1
#+HEADER:
Besides, the #+BEGIN_SRC emacs-lisp line is a typo, isn't it?
> +#+BEGIN_SRC emacs-lisp :var data2=2
> (message "data1:%S, data2:%S" data1 data2)
> - #+END_SRC
> +#+END_SRC
>
> - #+RESULTS:
> - : data1:1, data2:2
> +#+RESULTS:
> +: data1:1, data2:2
> @end example
>
> Multi-line header arguments on a named code block:
>
> @example
> + #+BEGIN_SRC emacs-lisp
> #+NAME: named-block
Typo?
> +Arguments can take values as literals, as references, or even as Emacs Lisp
> +code (see @ref{var, Emacs Lisp evaluation of variables}). References are
> +names from the Org file from the lines @code{#+NAME:} or @code{#+RESULTS:}.
> +References can refer to tables, lists, @code{#+BEGIN_EXAMPLE} blocks, other
> +types of code blocks, or the results of execution of code blocks.
>
> -Note: When a reference is made to another code block, the referenced block
> -will be evaluated unless it has current cached results (see @ref{cache}).
> +For better performance, Org can cache results of evaluations. See
> +@ref{cache} for details.
I would insist on the fact that cache also comes with serious limitations.
> +Argument values are indexed like arrays (see @ref{var, Indexable variable
> +values}).
(@pxref{var, Indexable variable values})
> +The @code{assign} is a literal value, such as a string @samp{"string"} or a
> +number @samp{9}, or a reference to a table, a list, a literal
> example,
@samp{"string"}, a number @samp{9}, a reference to a table, a list,
a literal example,
> +An external @code{:file} that saves the results of execution of the code
> +block. The @code{:file} is either a file name or two strings, where the
> +first is the file name and the second is the description. A link to the file
> +is inserted. It uses an Org mode style @code{[[file:]]} link (see @ref{Link
> +format}).
(@pxref{Link format})
> Some languages, such as R, dot, ditaa, and gnuplot, automatically
@samp{R}, @samp{dot}, @samp{ditaa}, and @samp{gnuplot},
> +A description of the results file. Org uses this description for the link
> +(see @ref{Link format}) it inserts in the Org file.
(@pxref{Link format})
> +File name extension for the output file. Org generates the file's complete
> +path, name,
In GNU parlance, a path is a list of directories, so it doesn't apply
here. "name" is sufficient.
> and extension by combining e@code{:file-ext}, @code{#+NAME:} of
Spurious "e" above.
> +For example, to save the plot file in the home directory's Work folder
@samp{Work} folder
or
``Work'' folder
Not sure which one is better.
> +To evaluate the code block on a remote machine, supply a remote directory name
> +using tramp syntax. For example:
Tramp (or @samp{Tramp})
> +Org captures text results for insertion as usual in the Org file. Org also
Missing space after full stop.
> +inserts a link to the remote file, thanks to Emacs Tramp. Org constructs the
Ditto.
> +path from @code{:dir} and @code{default-directory}, as shown in here:
path -> file name
> +When @code{:dir} is used with @code{:session}, Org sets the starting
> +directory for a new session. But Org will not alter the directory of an
Missing space.
> +Do not use @code{:dir} with @code{:exports results} or @code{:exports both}.
> +The inserted links may not point to the remote location because @code{default
> +directory} is not expanded (due to portability issues).
is not expanded---due to portability issues.
> +The @code{:exports} header argument specifies what portions of the Org file
> +to include in HTML or @LaTeX{} exports. Note that @code{:exports} affect only
Missing space.
affect -> affects
> +source code blocks and do not affect inline code.
do -> does
> +Neither the code nor the results of evaluation is included in the exported
> +file. Whether the code is evaluated at all depends on other
> +options. Example: @code{:exports none}.
Missing space.
> @item @code{tangle}
> -The code block is exported to a source code file named after the full path
> -(including the directory) and file name (w/o extension) of the Org mode file.
> -E.g., @code{:tangle yes}.
> +Export the code block to source file. Source file name is constructed from
> +the Org file's path and name.
See my previous remark about path.
> +Export the code block to source file using whatever string is passed to the
> +@code{:tangle} header argument as a path (directory and file name relative to
> +the directory of the Org mode file) to save as.
See above about path:
header argument as a file name---relative to the directory of the Org
mode file--to save as.
> +The @code{:mkdirp} header argument creates parent directories for tangled
> +files if the directory does not exist. @code{yes} enables directory creation
Missing space.
> +Controls inserting comments into tangled files. These are above and
Missing space.
> +Nearest headline text from Org file is inserted as comment. The exact text
Missing space.
> +By default Org expands code blocks during tangling. The @code{:no-expand}
> +header argument turns off such expansions. Note that one side-effect of
> +expansion by @code{org-babel-expand-src-block} also assigns values to
> +@code{:var} (see @ref{var}) variables. Expansions also replace ``noweb''
(@pxref{var})
> +references with their targets (see @ref{Noweb reference syntax}).
(@pxref{Noweb reference syntax})
> +Some of
> +these expansions may cause premature assignment, hence this option. This
> +option makes a difference only for tangling. It has no effect when exporting
Missing space.
> +Any string besides @code{none} turns that string into a name of the
> +session. Example: @code{:session mysession}.
session, e.g., @code{:session mysession}.
> +If @code{:session} has no
> +argument, then the session name is derived from the source language
> +identifier. Subsequent blocks with the same source code language use the
> +same session. Depending on the language, state variables, code from other
> +blocks, and the overall interpreted environment may be shared. Some
> +interpreted languages support concurrent sessions when subsequent source code
> +language blocks change session names.
> @end itemize
>
> @node noweb
> @@ -16079,41 +16065,36 @@ sessions).
> @cindex @code{:noweb}, src header argument
>
> The @code{:noweb} header argument controls expansion of ``noweb'' syntax
> -references (see @ref{Noweb reference syntax}) when the code block is
> -evaluated, tangled, or exported. The @code{:noweb} header argument can have
> -one of the five values: @code{no}, @code{yes}, @code{tangle}, or
> -@code{no-export} @code{strip-export}.
> +references (see @ref{Noweb reference syntax}). Expansions occur when source
(@pxref{Noweb reference syntax})
> +Noweb insertions now honor prefix characters that appear before
> +@code{<<reference>>}. This behavior is illustrated in the following example.
> +Because the @code{<<example>>} noweb reference appears behind the SQL comment
> +syntax, each line of the expanded noweb reference will be commented.
>
> This code block:
>
> @@ -16128,9 +16109,8 @@ expands to:
> -- multi-line body of example
> @end example
>
> -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.
> +Since this change will not affect noweb replacement text that does not have
> +newlines, it is okay to use inline noweb references.
"it is okay" looks odd in a manual.
Could you send an updated patch?
Regards,
--
Nicolas Goaziou
next prev parent reply other threads:[~2016-11-15 7:47 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-07 23:30 org.texi edits, patch attached Lambda Coder
2016-11-11 10:18 ` Nicolas Goaziou
2016-11-11 13:38 ` Bastien Guerry
2016-11-14 12:02 ` Lambda Coder
2016-11-15 7:47 ` Nicolas Goaziou [this message]
2016-11-15 20:10 ` Lambda Coder
2016-11-15 20:44 ` Nicolas Goaziou
2016-11-16 23:30 ` Lambda Coder
2016-11-17 22:56 ` Nicolas Goaziou
2016-11-18 0:51 ` Lambda Coder
2016-11-18 8:21 ` Nicolas Goaziou
2016-11-19 4:09 ` Lambda Coder
2016-11-24 1:46 ` Lambda Coder
2016-11-26 22:42 ` Nicolas Goaziou
2016-12-02 20:33 ` Lambda Coder
2016-12-03 23:46 ` Nicolas Goaziou
2016-12-15 6:45 ` Lambda Coder
2016-12-18 23:39 ` Nicolas Goaziou
2016-12-20 3:31 ` Lambda Coder
2016-12-20 16:58 ` Nicolas Goaziou
2017-02-23 13:24 ` Nicolas Goaziou
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d1hxp4kk.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
--cc=sjlambda@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).