From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: org.texi edits, patch attached Date: Tue, 15 Nov 2016 08:47:39 +0100 Message-ID: <87d1hxp4kk.fsf@nicolasgoaziou.fr> References: <874m3efhfw.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:54428) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c6YT1-0002bS-SY for emacs-orgmode@gnu.org; Tue, 15 Nov 2016 02:47:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c6YSx-0003nz-Qj for emacs-orgmode@gnu.org; Tue, 15 Nov 2016 02:47:43 -0500 Received: from relay3-d.mail.gandi.net ([217.70.183.195]:47016) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c6YSx-0003nf-Hy for emacs-orgmode@gnu.org; Tue, 15 Nov 2016 02:47:39 -0500 In-Reply-To: (Lambda Coder's message of "Mon, 14 Nov 2016 04:02:37 -0800") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Lambda Coder Cc: emacs-orgmode@gnu.org Hello, Lambda Coder 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{<>}. This behavior is illustrated in the following example. > +Because the @code{<>} 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