Re: [O] org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <address@hidden> 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
> address@hidden 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
> address@hidden 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
> address@hidden  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

> address@hidden, 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
> address@hidden, and any specified as properties.  In
> +the following example, the @code{:results} header argument is set to
> address@hidden, which means execution results are not inserted.  The
> address@hidden: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
> address@hidden:} 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
> address@hidden 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
> address@hidden 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 address@hidden: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
> address@hidden: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
> address@hidden: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
> address@hidden @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
> address@hidden<<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