org.texi edits, patch attached

org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 390 bytes --]

Attached is a patch submission for org.texi file. Sorry for the large size
of the attachment. I am posting to this list on Bastien's suggestion.

The edits mainly pertain to org-babel, which is where most of my time is
spent these days. This patch is an attempt to make the documentation more
consistent with the rest of gnu manuals. Comments and suggestions welcome.

--sjLambda@gmail.com

[-- Attachment #1.2: Type: text/html, Size: 507 bytes --]

[-- Attachment #2: 0001-Documentation-edits.patch.gz --]
[-- Type: application/x-gzip, Size: 16984 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> Attached is a patch submission for org.texi file. Sorry for the large size
> of the attachment. I am posting to this list on Bastien's suggestion.
>
> The edits mainly pertain to org-babel, which is where most of my time is
> spent these days. This patch is an attempt to make the documentation more
> consistent with the rest of gnu manuals. Comments and suggestions
> welcome.

Thank you for the patch!

I didn't read through the whole set of changes but I'll make some
initial comments.

Have you signed FSF papers already? You need to so that we can apply
your non-trivial changes to documentation.

Also, Texinfo document requires two spaces after a full stop. There are
a couple of places in your changes that do not follow this.

You also need to provide a proper commit message, listing sections
modified in the manual. See commit message in the repo for examples.

If your FSF papers are in order, could you send an updated patch?


Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Bastien Guerry]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Have you signed FSF papers already? You need to so that we can apply
> your non-trivial changes to documentation.

Yes, Lambda Coder has signed the FSF papers for both Emacs and Tramp.

> You also need to provide a proper commit message, listing sections
> modified in the manual. See commit message in the repo for examples.

Yes, see http://orgmode.org/worg/org-contribute.html#org4682cef for
details on how to write commit messages.

Thanks for the patches!

-- 
 Bastien

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 261 bytes --]

On Fri, Nov 11, 2016 at 2:18 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> If your FSF papers are in order, could you send an updated patch?
>
>
> Regards,
>
> --
> Nicolas Goaziou
>

I've attached an updated patch file to this msg.

--Lambda Coder.

[-- Attachment #1.2: Type: text/html, Size: 736 bytes --]

[-- Attachment #2: 0001-doc-org.texi-Editorial-revisions-to-the-manual.patch.gz --]
[-- Type: application/x-gzip, Size: 22002 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

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

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 185 bytes --]

On Mon, Nov 14, 2016 at 11:47 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Could you send an updated patch?
>
> Nicolas Goaziou
>

Yes, see attached patch 2.

--Lambda Coder.

[-- Attachment #1.2: Type: text/html, Size: 640 bytes --]

[-- Attachment #2: 0002-doc-org.texi-Editorial-revisions-to-the-manual.patch.gz --]
[-- Type: application/x-gzip, Size: 8634 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> Yes, see attached patch 2.

Thank you.

I have one last suggestion below.

Also, I cannot apply it to maint branch. Could you try rebasing maint
and format patch from there?

> +directory} is not expanded---due to portability issues.

I suggest instead:

  is not expanded, due to portability issues.


Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 495 bytes --]

On Tue, Nov 15, 2016 at 12:44 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Also, I cannot apply it to maint branch. Could you try rebasing maint
> and format patch from there?
>
>
See if this patch file works. It was generated against maint branch instead
of master with this command:

git format-patch origin/maint

If it still does not work for you, use the attached the org.texi file
instead. Just copy the entire Working With Source Code chapter.

Best wishes,

sjLambda@gmail.com

[-- Attachment #1.2: Type: text/html, Size: 959 bytes --]

[-- Attachment #2: org.texi.gz --]
[-- Type: application/x-gzip, Size: 234879 bytes --]

[-- Attachment #3: maint.patch.gz --]
[-- Type: application/x-gzip, Size: 30930 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> See if this patch file works. It was generated against maint branch instead
> of master with this command:
>
> git format-patch origin/maint
>
> If it still does not work for you, use the attached the org.texi file
> instead. Just copy the entire Working With Source Code chapter.

It didn't so I used the latter and applied your changes. I also added
a changelog.

Thank you.

Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1: Type: text/plain, Size: 308 bytes --]

On Thu, Nov 17, 2016 at 2:56 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> It didn't so I used the latter and applied your changes. I also added
> a changelog.
>

Thanks.

Do you prefer future edits against master or maint branch? It was not clear
when I asked the very first time.

--Lambda Coder.

[-- Attachment #2: Type: text/html, Size: 685 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> Do you prefer future edits against master or maint branch? It was not clear
> when I asked the very first time.

Documentation fixes usually go to maint, unless they refer to
a master-only feature, obviously.

Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 646 bytes --]

Thanks Nicolas for pushing the 1st set of edits.

Attached I have a 2nd set of edits for the same chapter. Cleaned up
references mainly.

This patch is based off maint branch. Hope it's easier for you this time.

Best wishes,

--Lambda Coder


On Fri, Nov 18, 2016 at 12:21 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Lambda Coder <sjlambda@gmail.com> writes:
>
> > Do you prefer future edits against master or maint branch? It was not
> clear
> > when I asked the very first time.
>
> Documentation fixes usually go to maint, unless they refer to
> a master-only feature, obviously.
>
> Regards,
>
> --
> Nicolas Goaziou
>

[-- Attachment #1.2: Type: text/html, Size: 1255 bytes --]

[-- Attachment #2: 0001-Working-with-source-code-2nd-revision.patch.gz --]
[-- Type: application/x-gzip, Size: 16389 bytes --]

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 965 bytes --]

Nicolas, attached is the revised edits for:

* Working with source code (2nd review)
* Miscellaneous
* Hacking
* MobileOrg

The patch is against maint branch from today.

Best wishes,

--Lambda Coder

On Fri, Nov 18, 2016 at 8:09 PM, Lambda Coder <sjlambda@gmail.com> wrote:

> Thanks Nicolas for pushing the 1st set of edits.
>
> Attached I have a 2nd set of edits for the same chapter. Cleaned up
> references mainly.
>
> This patch is based off maint branch. Hope it's easier for you this time.
>
> Best wishes,
>
> --Lambda Coder
>
>
> On Fri, Nov 18, 2016 at 12:21 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
>> Hello,
>>
>> Lambda Coder <sjlambda@gmail.com> writes:
>>
>> > Do you prefer future edits against master or maint branch? It was not
>> clear
>> > when I asked the very first time.
>>
>> Documentation fixes usually go to maint, unless they refer to
>> a master-only feature, obviously.
>>
>> Regards,
>>
>> --
>> Nicolas Goaziou
>>
>
>

[-- Attachment #1.2: Type: text/html, Size: 2033 bytes --]

[-- Attachment #2: 0001.patch.gz --]
[-- Type: application/x-gzip, Size: 45805 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> Nicolas, attached is the revised edits for:
>
> * Working with source code (2nd review)
> * Miscellaneous
> * Hacking
> * MobileOrg
>
> The patch is against maint branch from today.

Thank you. Some comments and suggestions follow.

Before starting however, I have one question: isn't replacing "code
block" with "src code block" everywhere a bit obnoxious? Couldn't define
once and for all that a "src block" is a code block and simply use "code
block" everywhere?

Also, your patch inserts trailing white spaces throughout the document.
Could you double-check that?

> +Org can flexibly export just the @emph{code} from the @samp{src} code blocks,
> +just the @emph{results} of evaluation of the @samp{src} code block,
> +@emph{both} the code and the results of @samp{src} code block evaluation, or
> +@emph{none}.  Org defaults to exporting @emph{code} for most languages.  For
> +some languages, such as @code{ditaa}, Org defaults to @emph{results}.  Each
> +of these options is described below.  For details about exporting just the
> +body of @samp{src} code blocks, see @ref{Literal examples}.  For details
> +about exporting portions (sub-trees) of an Org document, see
> @ref{Exporting}

  code blocks, @pxref{Literal examples}.

and,

  Org document, @pxref{Exporting}.

also,

  about exporting parts of an Org document 

i.e., drop "sub-trees", "portions" and the parenthesis.

> -The @code{:exports} header arguments control the export of code blocks (and
> -not inline code):
> +The @code{:exports} header arguments control the export of @samp{src} code
> +blocks (and not inline code):

  code blocks---and not inline code:

> -After each evaluation, results are inserted after the end of code block in
> -the Org buffer.  Previous results are either replaced (default) or appended
> -to.  On export, Org includes only the results and not the code block.
> +After each evaluation, Org inserts the results at the end of @samp{src} code
> +block in the Org buffer.  Previous results are either replaced (default) or
> +appended to.  On export, Org includes only the results and not the @samp{src}
> +code block.

  replaced---which is the default---or appended to...

>  @vindex org-export-use-babel
> -To stop Org from evaluating code blocks during export, set
> -@code{org-export-use-babel} variable to @code{nil}.  Turning off evaluation
> -comes in handy when batch processing.  For example, markup languages for
> -wikis, which have a high risk of untrusted code.  In this case, Org doesn't
> -process header arguments either.  For this reason it is often better to set
> -@code{:eval never-export} (@pxref{eval}) to prevent code evaluation but still
> -allow headers to be honored.  To evaluate just the inline code blocks, set to
> -@code{inline-only}.  Isolating inline evaluations is not for security but for
> -avoiding any delays due to recalculations during exports, such as calls to
> -a remote database.
> -
> -Org never evaluates code blocks in commented sub-trees when exporting
> -(@pxref{Comment lines}).  On the other hand, Org does evaluate code blocks in
> -sub-trees excluded from export (@pxref{Export settings}).
> +
> +To stop Org from evaluating @samp{src} code blocks during export, set
> +@code{org-export-babel-evaluate} variable to @code{nil}.  Stopping evaluation
> +comes in handy when batch processing in environments with high risk of
> +untrusted code, such as markup languages for wikis.  To evaluate only the
> +inline @samp{src} code blocks, set the variable to @code{inline-only}.  This
> +isolates evaluation not for any security reasons but for avoiding delays due
> +to recalculations during exports, such as calls to a remote database.
> +
> +Org never evaluates @samp{src} code blocks in commented sub-trees when
> +exporting (@pxref{Comment lines}).  On the other hand, Org does evaluate
> +@samp{src} code blocks in sub-trees excluded from export (@pxref{Export
> +settings}).

There is a gotcha here. This part was modified in master. It would be
better to preserve as much as possible the parts of the original text,
in particular the reference to ":eval no-export".

I suggest to find a common paragraph, simply replacing
`org-export-use-babel' with `org-export-babel-evaluate' for maint branch.

> -them in the Org file, right after the @samp{src} code block.  The insertion
> -point is after a newline and the @code{#+RESULTS} label.  Org creates the
> -@code{#+RESULTS} label if one is not already there.
> +them in the Org file, immediately following the @samp{src} code block.  The
> +insertion point is after a newline and the @code{#+RESULTS} label.  Org
> +creates the @code{#+RESULTS} label if one is not already there.
>  
> -By default, Org enables only @code{emacs-lisp} source code blocks for
> -execution.  See @ref{Languages} for identifiers to enable other languages.
> +By default, Org enables execution for only @code{emacs-lisp} @samp{src} code
> +blocks.  To add or remove other languages, see @ref{Languages}.

  languages, @pxref{Languages}.

> -code blocks}).
> +code blocks}). 

Mind the spurious space above.

> -Org passes arguments to the code block using standard function call
> -syntax ---instead of the header argument syntax.  For example,
> -a @code{#+CALL:} line that passes 4 to a code block named @code{double},
> -which declares the header argument @code{:var n=2}, would be written as
> -@code{#+CALL: double(n=4)}.
> +Org passes arguments to the @samp{src} code block using standard function
> +call syntax, and not the header argument syntax.  For example, @code{#+CALL:
> +double(n=4)}, passes 4 to a @samp{src} code block named @code{double}. 

  passes @samp{4} to a ...

Mind the trailing space at the end.

> -The ``Library of Babel'' is a collection of code blocks available for calling
> -from other Org files.  This collection is in a repository file in Org mode
> -format in the @samp{doc} directory of Org mode installation.  For remote code
> -block evaluation syntax, see @ref{Evaluating code blocks}.
> +The ``Library of Babel'' is a collection of @samp{src} code blocks available
> +for calling from other Org files.  This collection is in a repository file in
> +Org mode format in the @samp{doc} directory of Org mode installation.  For
> +remote code block evaluation syntax, see @ref{Evaluating code blocks}.

  syntax, @pxref{Evaluating code blocks}.

> -Header arguments in function calls are the most specific and override all
> -other settings in case of an overlap.  They get the highest priority.  Two
> -@code{#+CALL:} examples are shown below.  For the complete syntax of
> -@code{#+CALL:} lines, see @ref{Evaluating code blocks}.
> +Header arguments in function calls are the most specific and, in case of an
> +overlap, override settings at any other level.  They get the highest
> +priority.  Two @code{#+CALL:} examples are shown below.  For the complete
> +syntax of @code{#+CALL:} lines, see @ref{Evaluating code blocks}.

  lines, @pxref{Evaluating code blocks}.

> -data between @samp{src} code blocks.
> +data between @samp{src} code blocks.

Trailing whitespace.

> -of the code block for execution.  See also @ref{prologue}.
> +of the code block for execution.  See also @ref{prologue}. 

Trailing whitespace.

> -references in the @samp{src} code block before evaluation.
> +references in the @samp{src} code block before evaluation. 

Trailing whitespace.

> -@samp{src} code block, using ``noweb'' style references.
> +@samp{src} code block, using ``noweb'' style references.

Ditto.

> -Org mode supports insertion of empty structural elements (like
> -@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
> -strokes.  This is achieved through a native template expansion mechanism.
> -Note that Emacs has several other template mechanisms which could be used in
> -a similar way, for example @file{yasnippet}.
> +With easy templates, Org inserts empty structural elements (such as
> +@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just three key strokes.
> +Org does this using a template expansion mechanism, which is native to Org.
> +Such expansions operate similar to other generic Emacs template expansion
> +packages.

  structural elements---such as @code{#+BEGIN_SRC} and @code{#+END_SRC}
  pairs---with just three key strokes

> -To insert a structural element, type a @samp{<}, followed by a template
> -selector and @kbd{@key{TAB}}.  Completion takes effect only when the above
> -keystrokes are typed on a line by itself.
> +In Org, on a line by itself, type a @kbd{<} and a template letter (valid ones
> +are listed below).  Then @kbd{@key{TAB}} complete the expansion.  For example:

  letter---valid ones are listed below.

> -Single keys can be made to execute commands when the cursor is at the
> -beginning of a headline, i.e., before the first star.  Configure the variable
> -@code{org-use-speed-commands} to activate this feature.  There is a
> -pre-defined list of commands, and you can add more such commands using the
> -variable @code{org-speed-commands-user}.  Speed keys not only speed up
> -navigation and other commands, but they also provide an alternative way to
> -execute commands bound to keys that are not or not easily available on a TTY,
> -or on a small mobile device with a limited keyboard.
> +Single keystrokes (without meta or modifier keys) can execute custom commands
> +in an Org file.  They become active when the cursor is at the very beginning
> +of a headline (even before any bullet points or stars).

What is a "bullet point"? Isn't stars (or asterisks) clear enough? Also,

  keystrokes---without meta or modifier keys---can execute

and

  of a headline---even before any bullet point or star.

> -Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated
> -either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.
> +Org executes formulas in tables (@pxref{The spreadsheet}) either through the
> +@i{calc} or the @i{Emacs Lisp} interpreters.

  @emph{calc} or the @emph{Emacs Lisp}

?

> -These lines (several are allowed) specify link abbreviations.

  lines ---several are allowed---specify

> -Here are the options for hiding leading stars in outline headings, and for
> -indenting outlines.  The corresponding variables are
> -@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a
> -default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
> +These options hide leading stars in outline headings, and indent outlines.
> +The corresponding variables are @code{org-hide-leading-stars} and
> +@code{org-odd-levels-only}, both with a default setting of @code{nil}
> +(meaning @code{showstars} and @code{oddeven}).

  @code{nil}---meaning @code{showstars} and @code{oddeven}.

> -This line contains the formulas for the table directly above the line.
> -
> -Table can have multiple lines containing @samp{#+TBLFM:}.  Note
> -that only the first line of @samp{#+TBLFM:} will be applied when
> -you recalculate the table.  For more details see @ref{Using
> -multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
> +This line is for formulas for the table directly above.  A table can have
> +multiple @samp{#+TBLFM:} lines.  On table recalculation, Org applies only the
> +first @samp{#+TBLFM:} line.  For details see @ref{Using multiple #+TBLFM
> +lines} in @ref{Editing and debugging formulas}.

  For details @pxref{Using multiple #+TBLFM lines}.

The reference already contains the section it belongs to, doesn't it?

> -Things become cleaner still if you skip all the even levels and use only odd
> -levels 1, 3, 5..., effectively adding two stars to go from one outline level
> -to the next@footnote{When you need to specify a level for a property search
> -or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}.  In this
> -way we get the outline view shown at the beginning of this section.  In order
> -to make the structure editing and export commands handle this convention
> -correctly, configure the variable @code{org-odd-levels-only}, or set this on
> -a per-file basis with one of the following lines:
> +Using stars for only odd levels, 1, 3, 5, ..., can also clean up the clutter.
> +This removes two stars from each level@footnote{When you need to specify a
> +level for a property search or refile targets, @samp{LEVEL=2} will correspond
> +to 3 stars, etc.}.  But for correct handling of structure editing and export
> +commands, configure the variable @code{org-odd-levels-only}.  To set this
> +per-file, use one of these lines:

  Using stars for odd levels, 1, 3, 5, @dots{}, can also

> -Org lives in the world of GNU Emacs and interacts in various ways
> -with other code out there.
> +Org's interaction (or lack there of) with other Emacs packages are documented
> +here.

  Org's interaction---or lack there of---with other Emacs packages

> -For the same reason, key bindings in Org also conflict with the
> -@kbd{S-<cursor>} keys used by CUA mode.  If you prefer to leave these keys to
> -a different package while working in Org mode, configure the variable
> -@code{org-replace-disputed-keys}.  When set, Org will move the following key
> +Org key bindings conflict with @kbd{S-<cursor>} keys used by CUA mode.  For
> +Org to relinquish these bindigns to CUA mode, configure the variable
> +@code{org-replace-disputed-keys}.  When set, Org moves the following key
>  bindings in Org files, and in the agenda buffer (but not during date
>  selection).

  and in the agenda buffer---but not during date selection.

>  @lisp
> -(defun yas/org-very-safe-expand ()
> -  (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
> +(defun yas/org-very-safe-expand () (let ((yas/fallback-behavior 'return-nil))
> +  (yas/expand)))
>  @end lisp

The former is more idiomatic. Please remove this chunk.

> -Org-crypt will encrypt the text of an entry, but not the headline, or
> -properties.  Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
> -files.
> +Org-crypt encrypts the text of an entry, but not the headline, or properties.
> +Org-crypt uses the Emacs EasyPG library to encrypt and to decrypt.

  Org Crypt encrypts the text

and

  Org Crypt uses

or perhaps "Org crypt" instead of "Org Crypt"...

> -To use org-crypt it is suggested that you have the following in your Emacs
> -init file:
> +Suggested org-crypt settings in Emacs init file:

See above.

> -You would activate this new link type in Emacs init file with
> +To activate org-man link type in Emacs, enter this in the init file:

"Org man" or "Org Man", per above.

> -Org 8.0 comes with a completely rewritten export engine which makes it easy
> -to write new export back-ends, either from scratch, or by deriving them
> -from existing ones.
> +Org 8.0 has a new export engine that makes it easy for writing new
> +back-ends.  This engine can also derive new back-ends from existing
> ones.

I don't think retaining reference to Org 8 is relevant in an Org 9 manual. I suggest:

  Org has an export framework that makes...

> -When creating a new back-end from scratch, the basic idea is to set the name
> -of the back-end (as a symbol) and an alist of elements and export functions.
> -On top of this, you will need to set additional keywords like
> -@code{:menu-entry} (to display the back-end in the export dispatcher), and
> -@code{:options-alist} (to let the user set export options that are specific
> -to this back-end.)
> +For a new back-end from scratch, set its name (as a symbol) in an alist of
> +elements and export functions.  For making the back-end visible to the export
> +dispatcher, set @code{:menu-entry} keyword.  For export options specific to
> +this back-end, set the @code{:options-alist}.

  set its name---as a symbol---in a alist of

> -Add-ons can tap into this functionality by providing a function that detects
> -special context for that add-on and executes functionality appropriate for
> -the context.  Here is an example from Dan Davison's @file{org-R.el} which
> -allows you to evaluate commands based on the @file{R} programming language
> -@footnote{@file{org-R.el} has been replaced by the Org mode functionality
> -described in @ref{Working with source code} and is now obsolete.}.  For this
> -package, special contexts are lines that start with @code{#+R:} or
> -@code{#+RR:}.
> +These commands work by providing a function that detects special context for
> +that add-on and executes functionality appropriate for that context.
> +
> +Here is an example from Dan Davison's @file{org-R.el} which evaluates
> +commands based on the @file{R} programming language @footnote{@file{org-R.el}
> +has been replaced by the expanded Org mode functionality described in
> +@ref{Working with source code}.}.  For this package, special contexts are
> +lines that start with @code{#+R:} or @code{#+RR:}.
>  
>  @lisp
>  (defun org-R-apply-maybe ()
> -  "Detect if this is context for org-R and execute R commands."
> +  "Detect if context is org-R and execute R commands."
>    (if (save-excursion
>          (beginning-of-line 1)
>          (looking-at "#\\+RR?:"))

I think we can remove this whole part of the manual. Neither "org-R.el"
nor "#+RR:" or "#+R:" exist anymore in Org.

> +Because of Org's success in handling tables with Orgtbl, one frequently asked
> +feature is to expand the usability functions to other table formats native to
> +other mdoes, such as @LaTeX{}.  This would be hard to do in a general way
> +without complicated customization nightmares.  Moreover, that would take Org
> +away from its simplicity roots as evidenced by Orgtbl.  However, there is an
> +alternate approach to accomplishing the same.
> +
> +This approach involves implementing a custom @i{translate} function
> that

  @emph{translate}


> +operates on a native Org @i{source table} to produce a table in another

  @emph(source table)

> -List of columns that should be skipped.  If the table has a column with
> -calculation marks, that column is automatically discarded as well.
> -Please note that the translator function sees the table @emph{after} the
> -removal of these columns, the function never knows that there have been
> -additional columns.
> +List of columns to be skipped.  Org first discards columns with calculation
> +marks automatically and then sends the table to the translator function,
> +which then uses skipcols to determine what to skip.

  @samp{skipcols}

> -Sometimes it is possible to put the table after some kind of @i{END}
> -statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}
> -in @LaTeX{}.
> +Put the table after an @i{END} statement.  For example @samp{\bye} in @TeX{}
> +and @samp{\end@{document@}} in @LaTeX{}.

  @samp{END}

> -Now let's assume you want to make the table header by hand, because you
> -want to control how columns are aligned, etc.  In this case we make sure
> -that the table translator skips the first 2 lines of the source
> -table, and tell the command to work as a @i{splice}, i.e., to not produce
> -header and footer commands of the target table:
> +For hand-made custom tables, note that the translator needs to skip the first
> +two lines of the source table.  Also the command has to @i{splice}, i.e., not
> +produce header and footer commands of the target table:

  @emph{splice}

> -Orgtbl mode.  By default, it uses a @code{tabular} environment to typeset the
> -table and marks horizontal lines with @code{\hline}.  You can control the
> -output through several parameters (see also @pxref{Translator functions}),
> -including the following ones :
> +Orgtbl mode.  By default, it uses @code{tabular} environment to typeset the
> +table and mark the horizontal lines with @code{\hline}.  Output customization
> +parameters include (see also @pxref{Translator functions}):

  include (@pxref{Translator functions}):

> -In particular, properties passed into the function (i.e., the ones set by the
> -@samp{ORGTBL SEND} line) take precedence over translations defined in the
> -function.  So if you would like to use the @LaTeX{} translator, but wanted
> -the line endings to be @samp{\\[2mm]} instead of the default @samp{\\}, you
> -could just overrule the default with
> +Properties passed to the function (i.e., set by the @samp{ORGTBL SEND} line)
> +take precedence over properties defined in the function.  For example, this
> +overrides the default @LaTeX{} line endings, @samp{\\}, with @samp{\\[2mm]}:

  to the function---i.e., set by the @samp{ORGTBL SEND} line---take

> -Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted
> -@LaTeX{} list between the two marker lines.
> +@kbd{C-c C-c} on @code{a new house} inserts the translated @LaTeX{}
> list

  @samp{a new house}

> -If you want to make sure that all dynamic blocks are always up-to-date,
> -you could add the function @code{org-update-all-dblocks} to a hook, for
> -example @code{before-save-hook}.  @code{org-update-all-dblocks} is
> -written in a way such that it does nothing in buffers that are not in
> +To keep dynamic blocks up-to-date in an Org file, use the function,
> +@code{org-update-all-dblocks} in hook, such as @code{before-save-hook}.  The
> +@code{org-update-all-dblocks} function does not run if the file is not in
>  @code{org-mode}.

  is not in Org mode.

> +Org provides a special hook to further limit items in agenda views:
> +@code{agenda}, @code{agenda*}@footnote{The @code{agenda*} view is the same as
> +@code{agenda} except that it only considers @emph{appointments}, i.e.,
> +scheduled and deadline items that have a time specification @code{[h]h:mm} in
> +their time-stamps.}, @code{todo}, @code{alltodo}, @code{tags},
> +@code{tags-todo}, @code{tags-tree}.  Specify a custom function that tests
> +inclusion of every matched item in the view.  This function can also
> +skip as much as is needed.

  @samp{[h]h:mm}

> -Therefore we could also have written the search for WAITING projects
> -like this, even without defining a special function:
> +The following is an example of a search for WAITING without the special
> +function:

  @samp{WAITING}

> -Reduce the number of DONE and archived headlines: this way the agenda does
> -not need to skip them.
> +Reduce the number of DONE and archived headlines: so agenda operations that
> +skip over theseT can speed up.

Typo. Also,

  @samp{DONE}

> -Org provides commands to access agenda information for the command
> -line in Emacs batch mode.  This extracted information can be sent
> -directly to a printer, or it can be read by a program that does further
> -processing of the data.  The first of these commands is the function
> -@code{org-batch-agenda}, that produces an agenda view and sends it as
> -ASCII text to STDOUT@.  The command takes a single string as parameter.
> -If the string has length 1, it is used as a key to one of the commands
> -you have configured in @code{org-agenda-custom-commands}, basically any
> -key you can use after @kbd{C-c a}.  For example, to directly print the
> -current TODO list, you could use
> +Org provides commands to access agendas through Emacs batch mode.  Through
> +this command-line interface, agendas can be automated for further processing
> +or printing.
> +
> +@code{org-batch-agenda} outputs to an agenda view in ASCII to STDOUT@.  This

Why the "@."? Shouldn't we use:

  in ASCII to STDOUT.  This

> +command takes one string parameter.  When string length=1, Org uses it as a

Typo.

> +key to @code{org-agenda-custom-commands}.  These are the same ones availabe
> +through @kbd{C-c a}.
> +
> +This example command line diretly prints the current TOTO list to the
> +printer:

Typo.

> -If the parameter is a string with 2 or more characters, it is used as a
> -tags/TODO match string.  For example, to print your local shopping list
> -(all items with the tag @samp{shop}, but excluding the tag
> -@samp{NewYork}), you could use
> +When the string parameter length is 2 or more characters, Org matches it with

 two or more characters,

> +tags/TODO strings.  For example, to print a shopping list (items tagged with
> + @samp{shop}, but exclude items tagged with @samp{NewYork}):

  For example, to print a list of items tagged with @samp{show}, but
  exclude items tagged with @samp{NewYork}:

> -which will produce a 30-day agenda, fully restricted to the Org file
> -@file{~/org/projects.org}, not even including the diary.
> +which will produce an agenda for the next 30 days from just the
> +@file{~/org/projects.org} file, (and even ignores the diary).

I think (and even ignores the diary) is redundant here, as there is
"just the file" before. I suggest to drop the last part of the sentence.

> -Time and date will only be given if a timestamp (or deadline/scheduled)
> -led to the selection of the item.
> +If the selection of the agenda item was based on a timestamp (or
> +deadline/scheduled), then Org includes date and time in the output.

on a timestamp---including deadline and scheduled---then Org includes

> -# run it and capture the output
> +aaaa# run it and capture the output

Typo.

> +@code{FUNC} is a function or a Lisp form.  With the cursor positioned at the

  @samp{FUNC}

> +beginning of the headline, call the function without arguments.  Org returns
> +an alist of return values of calls to the function.
> +
> +To avoid preserving point, the call to @code{FUNC} is wrapped in

  @samp{FUNC}
  
> +save-excursion form.  After evaluation, the cursor is moved to the end of the
> +line (presumably of the headline of the processed entry).  Search continues

  line---presumably of the headline of the processed entry.  Search continues

> +from there.  This may not produce the expected results under some conditions,
> +such as removing the current (sub)tree (for archiving).  Org skips the next

  such as removing the current sub-tree for archiving.  Org skips the next

> +entry entirely.  To avoid such skips, make @code{FUNC} set the variable

  @samp{FUNC}

> +@code{org-map-continue-from} to a specific buffer position.
> +
> +@code{MATCH} is a tags/property/todo match.  Org iterates only those

  @samp{MATCH} is a tags/property/TODO match.

>  @code{SCOPE} determines the scope of this command.  It can be any of:

  @samp{SCOPE}

> -@i{MobileOrg} is the name of the mobile companion app for Org mode, currently

  @emph{MobileOrg}

> -available for iOS and for Android.  @i{MobileOrg} offers offline viewing and

Ditto.

> -capture support for an Org mode system rooted on a ``real'' computer.  It
> -also allows you to record changes to existing entries.  The
> -@uref{https://github.com/MobileOrg/, iOS implementation} for the
> +@i{MobileOrg} is a companion mobile app that runs on iOS and Android devices.

Ditto.

> +@i{MobileOrg} enables offline-views and capture support for an Org mode

Ditto.

> +system that is rooted on a ``real'' computer.  @i{MobileOrg} can record
> +changes to existing entries.

Ditto.

> +by Matt Jones.  Though the two implementations are not identical, they offer
> +similar features.
> +
> +This appendix describes Org's support for agenda view formats compatible with
> +@i{MobileOrg}.  It also describes integrating changes (such as notes) between
> +@i{MobileOrg} and the computer.

See above. Also,

  integrating changes---such as notes---between

> +To change tags and TODO states in MobileOrg, first customize the variables
> +@code{org-todo-keywords} and @code{org-tag-alist}.  These should cover all
> +the important tags and TODO keywords, even if Org files use only some of
> +them.  Though MobileOrg has in-buffer settings, it understands TODO states
>  @i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags

  @emph{sets}

and

  @emph{mutually exclusive} tags

> +MobileOrg needs access to a file directory on a server to interact with
> +Emacs.  With a public server, consider encrypting the files.  Org mode 7.02
> +(and later) and with @i{MobileOrg 1.5} (iPhone version) support encryption.

For the reason explained earlier, I think we can drop the "Org mode
7.02" part, so

  MobileOrg 1.5 (iPhone version) supports encryption.

Also, note that MobileOrg is not consistently emphasized in the manual.
We need to either use "MobileOrg" or "@emph{MobileOrg}" everywhere.
I prefer the former.

> +Org also requires @file{openssl} installed on the local computer.  To turn on
> +encryption, set the same password in @i{MobileOrg} and Emacs.  Set the

See above.

> +password in the variable @code{org-mobile-use-encryption}@footnote{If you can
> +safely store the password in your Emacs setup, you might also want to
> +configure @code{org-mobile-encryption-password}.  Please read the docstring
> +of that variable.  With encryption, file names will remain visible even if the
> +file contents are encrypted.
> +
> +For a server to host files, consider options like
> +@uref{http://dropbox.com,Dropbox.com} account@footnote{An alternative is to

I'd rather not suggest using Dropbox in a GNU manual.

> +use webdav server.  For more information, see MbileOrg documentation.

Typo.

> +On first connection, MobileOrg creates a directory @i{MobileOrg} on

See above: "MobileOrg".

> +Dropbox.  Emacs needs to know its location (through init file):
>  
>  @lisp
>  (setq org-mobile-directory "~/Dropbox/MobileOrg")
>  @end lisp

See above about Dropbox.

> +Org mode puts files for @i{MobileOrg} in that directory, and also reads

  MobileOrg

> +captured notes from @i{MobileOrg} from that directory.

  MobileOrg

> +Org pushes files listed in @code{org-mobile-files} to
> +@code{org-mobile-directory}.  Files include agenda files (as listed in
> +@code{org-agenda-files}).  Customize @code{org-mobile-files} to add other
> +files.  File names will be staged with paths relative to
> +@code{org-directory}, so all files should be inside this
> +directory@footnote{Symbolic links in @code{org-directory} should have the
> +same name as their targets.}.
> +
> +Push creates a special Org file @file{agendas.org} with custom agenda views
> +defined by the user@footnote{While creating the agendas, Org mode will force
> +ID properties on all referenced entries, so that these entries can be
> +uniquely identified if @i{MobileOrg} flags them for further action.  To avoid

  MobileOrg

> +Org writes the file @file{index.org}, containing links to other files.
> +@i{MobileOrg} reads this file first from the server to determine what other

  MobileOrg

> +files to download for agendas.  For faster downloads, MobileOrg will read
> +only those files whose checksums@footnote{Checksums are stored automatically
> +in the file @file{checksums.dat}} have changed.

Missing period:

  in the file @file{checksums.dat}.} have changed.

> +When @i{MobileOrg} synchronizes with the server, it pulls the Org files for

  MobileOrg

> +After moving the entries, Org attempts changes to @i{MobileOrg}.  Some

  MobileOrg

> +Org generates an agenda view for flagged entries for user intervention to
> +clean up.  For notes stored in flagged entries, @i{MobileOrg} displays them

  MobileOrg

> +Pressing @kbd{?} displays the entire flagged note in another window.  Org
> +also pushes it to the kill ring.  To store flagged note as a normal note, use
> +@kbd{?  z C-y C-c C-c}.  Pressing @kbd{?} twice removes the @code{:FLAGGED:}
> +tag along with the recorded flagging note (which is stored in a property).

  recorded flagging note---which is stored in a property.


Could you send an updated patch?

Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 336 bytes --]

On Sat, Nov 26, 2016 at 2:42 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

>
> Could you send an updated patch?
>
> Regards,
>
> --
> Nicolas Goaziou
>


See the attached patch file diff'd against maint. I've also attached a
separate file that has your comments and my responses. Hope they are
self-explanatory.

--Lambda Coder.

[-- Attachment #1.2: Type: text/html, Size: 869 bytes --]

[-- Attachment #2: 0001-doc-org-texi.patch.gz --]
[-- Type: application/x-gzip, Size: 48701 bytes --]

[-- Attachment #3: 20161123CommentsFromNicolas.txt.gz --]
[-- Type: application/x-gzip, Size: 11613 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> See the attached patch file diff'd against maint.

Applied. Thank you for all that work.

Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 428 bytes --]

Thanks.

I have more. I've just finished the Exporting chapter. See the attached
patch file against current maint branch.

Best wishes,

--Lambda Coder.

On Sat, Dec 3, 2016 at 3:46 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Lambda Coder <sjlambda@gmail.com> writes:
>
> > See the attached patch file diff'd against maint.
>
> Applied. Thank you for all that work.
>
> Regards,
>
> --
> Nicolas Goaziou
>

[-- Attachment #1.2: Type: text/html, Size: 996 bytes --]

[-- Attachment #2: 0001-Editorial-revisions-to-the-manual.patch.gz --]
[-- Type: application/x-gzip, Size: 56410 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> I have more. I've just finished the Exporting chapter. See the attached
> patch file against current maint branch.

Thank you!

Usual comments and questions follow.

> +Org has export facilities for printing, format conversions, and general
> +sharing of Org documents with the outside world.  Org export supports
> +pretty-printing, web publishing, slide shows, and quick exports of lists and
> +tables to many foreign formats while retaining as much structure
> +(@pxref{Document structure}) and markup (@pxref{Markup}) as possible.  The
> +many features of Org exports are constantly being improved and expanded and
> +they are all explained in this chapter.

I would remove "are constantly being improved and expanded and they"

> +@noindent Org also uses additional libraries located in @code{contrib/}
> +directory (@pxref{Installation}).  Users can install even more specialized
> +libraries from the Emacs packaging system.  

Nitpick: libraries from the Emacs packaging system may not be "more
specialized", but just different.

What about dropping "specialized"?

> +Invokes the export dispatcher interface.  The options show default settings.
> +The @kbd{C-u} prefix argument preserves options from the previous export,
> +including any sub-tree selections as long as buffer contents have not changed
> +since the last export.

The last part of the sentence above is incorrect. Buffer contents may
have changed between two exports. Otherwise, there is not much interest
in exporting the same thing twice, even with a shortcut.

> -Toggle subtree export.  The top heading becomes the document title.
> +Toggle sub-tree export.  When turned on, Org exports only the sub-tree starting
> +from the cursor position at the time the export dispatcher was invoked.  Org
> +uses the top heading of this sub-tree as the document's title.  If the cursor
> +is not on a heading, Org uses the nearest enclosing header.  If the cursor is
> +in the document preamble, Org signals an error and aborts export.

I wonder if the last sentence isn't too technical for a manual.
Shouldn't we leave that for a docstring?

> +Options set through properties
> +(@pxref{Properties and columns}) apply to that specific heading and its
> +subheadings.  Properties are inherited in the hierarchy, and, in case of
> +overlap, options set at the specific level override those set at the more
> +general and global levels.

This is not correct. Options set through properties apply only when
doing a sub-tree export. Besides, even in this case, properties are not
necessarily inherited. It depens on `org-use-property-inheritance'.

> -A date or a time-stamp@footnote{The variable
> -@code{org-export-date-timestamp-format} defines how this time-stamp will be
> -exported.}.
> +A date or a time-stamp@footnote{The export format is specified in 
> +@code{org-export-date-timestamp-format}.}.

`org-export-date-timestamp-format' has an effect only when DATE is
a time-stamp. It isn't obvious by reading the above.

>  @item EMAIL
>  @cindex #+EMAIL
> @@ -10436,46 +10465,47 @@ The email address (@code{user-mail-address}).
>  @item LANGUAGE
>  @cindex #+LANGUAGE
>  @vindex org-export-default-language
> -The language used for translating some strings
> -(@code{org-export-default-language}).  E.g., @samp{#+LANGUAGE: fr} will tell
> -Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
> -clocktable.
> +Language to use for translating certain strings
> +(@code{org-export-default-language}).  With @samp{#+LANGUAGE: fr}, for
> +example for the clocktable, Org translates the English @emph{File} to the
> +French @emph{Fichier}.

The example needs to be changed (so did the old one).
`org-export-default-language' has no effect on the Clock Table.
I suggest to replace it with a real example, e.g.

  With @samp{#+LANGUAGE: fr}, for example, Org translates @emph{Table of
  contents} to the French @emph{Table des matières}.

> +The default value is @code{:export:}.  When a tree is tagged with
> +@code{:export:} (@code{org-export-select-tags}), Org selects that tree and
> +its sub-trees for export.  Org excludes trees with @code{:noexport:} tags (see
> +below).  

Usual nitpick:

  tags---see below.

> -Toggle inclusion of drawers, or list drawers to include
> +Toggle inclusion of drawers, or list-drawers to include

Is this a typo? `org-export-with-drawers' can contain a list of drawers
to include (or not).

> +``Planning information'' comes from lines containing any combination of these
> +cookies: @code{SCHEDULED:}, @code{DEADLINE:}, or @code{CLOSED:}.

and located right after the headline.

> +Org converts the first three outline levels into headlines for ASCII export.
> +The remaining levels are turned into lists.  To change this cut-off point
> +where levels become lists, (@pxref{Export settings}).

You should remove the parenthesis above.

>  @subheading Quoting ASCII text
>  
> -You can insert text that will only appear when using @code{ASCII} back-end
> -with the following constructs:
> +To insert text within the Org file by the @code{ASCII} back-end, use one the
> +following constructs, inline, keyword, or export block:

For consistency (with, e.g., HTML or some others "ASCII" in the manual),

  @code{ASCII} -> ASCII

>  #+BEGIN_EXPORT ascii
> -All lines in this block will appear only when using this back-end.
> +Org exports text in this block only when using @code{ASCII} back-end.

Ditto.

> +@code{ASCII} back-end recognizes only one attribute, @code{:width},
> which

Ditto.

> +Besides @code{#+BEGIN_CENTER} blocks (@pxref{Paragraphs}),
> @code{ASCII}

Ditto.

> +Org uses @emph{Beamer} export to convert an Org file tree structure into a
> +high-quality interactive slides for presentations.  @emph{Beamer} is a
> +@LaTeX{} document class for creating presentations in PDF, HTML, qand other
> +popular display formats.

Typo: qand > and

> +Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
> +it recognizes other @LaTeX{} specific syntax (for example, @samp{#+LATEX:} or
> +@samp{#+ATTR_LATEX:}).  See @ref{@LaTeX{} export} for details.

Last sentence should be

  @xref{@LaTeX{} export}, for details.

The comma is mandatory.

> +@example
> +#+ATTR_BEAMER: :options [Lagrange]
> +Let $G$ be a finite group, and let $H$ be
> +a subgroup of $G$.  Then the order of $H$ divides the order of $G$.
> +@end example

The example above does nothing useful, does it? :options do not apply to
paragraphs AFAIK.

> +Org mode contains an HTML exporter with extensive HTML formatting (XHTML 1.0
> +strict), in ways similar to John Gruber's @emph{markdown} language, but with
> +additional support for tables.

  HTML formatting---XHTML 1.0 strict.

I'm not sure comparing HTML back-end to markdown is realistic nowadays.
Both are very different. We may drop the last part of the sentence.

> +@c Org's HTML export converts the first three outline levels into headlines
> +@c for HTML export.  The remaining levels are turned into itemized lists.  To
> +@c change this globally for the cut-off point where levels become lists,
> +@c (@pxref{Export settings}).  To change just for this document for now,
> +@c specify a numeric prefix argument, such as:
>  
>  @c @example
>  @c @kbd{C-2 C-c C-e b}
>  @c @end example
>  
>  @c @noindent
> -@c creates two levels of headings and does the rest as items.
> +@c creates the first two levels as headings and the rest as itemized lists.

What about removing the comments? (@c)

> +Specify the document type, for example: HTML5, (@code{org-html-doctype}).

I would remove the last comma:

  for example: HTML5 (@code{org-html-doctype}).

> +Options for MathJax (@code{org-html-mathjax-options}).  MathJax is used to
> +typeset @LaTeX{} math in HTML documents.  @ref{Math formatting in HTML
> +export} has an example.

  @xref{Math formatting in HTML export}, for an example.

> -Arbitrary lines appended to the end of the header of the document
> -(@code{org-html-head-extra}).
> +More arbitrary lines for appending to the HTML document's head.
> +(@code{org-html-head-extraq}).

Typo: extraq -> extra

Also, I would remove the penultimate period:

  ... HTML document's head (@code{org-html-head-extra}).
> +When special blocks do not have a corresponding HTML5 element (see
> +@code{org-html-html5-elements}), the HTML exporter reverts to standard
> +translation.  For example, @code{#+BEGIN_lederhosen} exports to @samp{<div
> +class="lederhosen">}.

  HTML5 element---see @code{org-html-html5-elements}---the HTML exporter...

> +The HTML export back-end transforms Org's internal links (@pxref{Internal
> +links}) to equivalent HTML links in the output.  The back-end similarly
> +handles Org's automatic links created by radio targets (@pxref{Radio
> +targets}) similarly.  For Org links to external files, the back-end
> +transforms the links to @i{relative} paths.

@i{relative} -> @emph{relative}

> +For Org links to other @file{.org} files, the back-end automatically changes
> +the file extension to @file{.html} and makes file paths relative.  If the
> +@file{.org} files have an equivalent @file{.html} version at the same
> +location, then the converted links should work without any further manual
> +intervention.  However, to disable this automatic path translation, set
> +@code{org-html-link-org-files-as-html} to @code{nil}.  When disabled, the
> +HTML export back-end substitutes the @samp{id:}-based links in the HTML
> +output.  For more about linking files when publishing to a directory, see
> +@ref{Publishing links}.

  ... to a directory, @pxref{Publishing links}.

> -You could use @code{http} addresses just as well.
> +The HTTP export back-end copies the @code{http} links from the Org file as
> +is.

There is no such thing as a "HTTP" export back-end? What do you mean here?

>  @c FIXME: More about header and footer styles
> -@c FIXME: Talk about links and targets.
> +@c FIXME: Talk about lfinks and targets.

Typo: lfinks -> links

>  #+BEGIN_SRC emacs-lisp
> -  (defun Fib (n)                          ; Count rabbits.
> +  (defun Fib (n)
>      (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
>  #+END_SRC

You ruined the joke :)

> +The ODT export back-end can produce documents in other formats besides ODT
> +using a specialized ODT converter process.  Its common interface works with
> +popular converters to produce formats such as @samp{doc}, or convert a
> +document from one format (say @samp{csv}) to another format (say @samp{ods}
> +or @samp{xls}).

  from one format, say @samp{csv}, to another format, say @samp{ods}.

I would drop the "xls" part.

> +The ODT export back-end starts with the size dimensions (in centimeters) of

  size dimensions---in centimeters--of

> +To modify the category component of the caption, customize the option
> +@code{org-odt-category-map-alist}.  For example, to tag all embedded images
> +with the string @samp{Illustration} (instead of the default @samp{Figure})
> +use the following setting:

  ... the string @samp{Illustration}---instead of the default
  @samp{Figure}---use the following setting :

>  @lisp
>  (setq org-odt-category-map-alist
>        (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))

There is a quote missing at the beginning of the second line.

> +The ODT export back-end can read one-liner options on line with @code{#+ODT:}
> +in the Org file.

I cannot parse this sentence. Would it need clarifications?

>  @example
> -#+attr_texinfo: :options org-org-export-to-org ...
> +#+attr_texinfo: :options opt1 opt2 opt3 ...
>  #+begin_defun
>  A somewhat obsessive function.
>  #+end_defun
>  @end example

You also ruined the joke :) You need to replace the contents of the
defun, which do not make sense anymore.

Also, #+begin_defun expects a function name, not arguments.

>  @noindent
> -becomes
> +exports to
>  
>  @example
> -@@defun org-org-export-to-org ...
> +@@defun opt1 opt2 opt3 ...
>  A somewhat obsessive function.
>  @@end defun
>  @end example

Ditto.

> +The iCalendar export back-end can also incorporate TODO entries based on the
> +configuration of the @code{org-icalendar-include-todo} variable.  The
> +back-end exports plain timestamps as VEVENT, TODO items as VTODO@, and also

  VTODO@, -> VTODO,

> -language in the block.  @xref{Languages}, for identifiers of supported
> +language in the block.  @xref{Languages} for identifiers of supported

Please revert this chunck, a comma (or full stop) is necessary after
"@xref".


Could you send an updated patch?


Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Lambda Coder]

[-- Attachment #1.1: Type: text/plain, Size: 266 bytes --]

On Sun, Dec 18, 2016 at 3:39 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Could you send an updated patch?
>
>
> Regards,
>
> --
> Nicolas Goaziou
>


See attached patch for Exporting chapter against maint. Also my notes to
your comments.

--Lambda Coder.

[-- Attachment #1.2: Type: text/html, Size: 760 bytes --]

[-- Attachment #2: 0002-Editorial-revisions-to-the-manual.patch.gz --]
[-- Type: application/x-gzip, Size: 56825 bytes --]

[-- Attachment #3: 20161219CommentsFromNicolas.txt.gz --]
[-- Type: application/x-gzip, Size: 5895 bytes --]

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Hello,

Lambda Coder <sjlambda@gmail.com> writes:

> See attached patch for Exporting chapter against maint. 

Thank you. 

Unfortunately, I cannot apply it. Could you send create it with
format-patch against maint's tip, without gzipping it?

> Also my notes to your comments.

Answers follow.

>> +Org has export facilities for printing, format conversions, and general
>> +sharing of Org documents with the outside world.  Org export supports
>> +pretty-printing, web publishing, slide shows, and quick exports of lists and
>> +tables to many foreign formats while retaining as much structure
>> +(@pxref{Document structure}) and markup (@pxref{Markup}) as possible.  The
>> +many features of Org exports are constantly being improved and expanded and
>> +they are all explained in this chapter.
> 
> I would remove "are constantly being improved and expanded and they"
> 
> [why?]

It sounds like a commercial ad.

> Shouldn't we leave that for a docstring?
> 
> [Perhaps, but all three conditions have to be together.]

Fair enough.

>> +@example
>> +#+ATTR_BEAMER: :options [Lagrange]
>> +Let $G$ be a finite group, and let $H$ be
>> +a subgroup of $G$.  Then the order of $H$ divides the order of $G$.
>> +@end example
> 
> The example above does nothing useful, does it? :options do not apply to
> paragraphs AFAIK.
> 
> [I did not put it there, edit it as you see fit.]

OK, will do, if I remember about it.

>> +Options for MathJax (@code{org-html-mathjax-options}).  MathJax is used to
>> +typeset @LaTeX{} math in HTML documents.  @ref{Math formatting in HTML
>> +export} has an example.
> 
>   @xref{Math formatting in HTML export}, for an example.
> 
> [commas don't make grammatical sense here after xref]

It is not about English grammar, but about Texinfo syntax.

  @xref{whatever}, for example.

produces

  See Section 3.1 [whatever], page 24, for example.

whereas

  @xref{whatever} for example.

produces

  See Section 3.1 [whatever], page 24 for example.

which is awkward.

>>  #+BEGIN_SRC emacs-lisp
>> -  (defun Fib (n)                          ; Count rabbits.
>> +  (defun Fib (n)
>>      (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
>>  #+END_SRC
> 
> You ruined the joke :)
> 
> ["count rabbit pairs" makes it more accurate but still nothing funny]

Too bad. I found it hilarious (!). Let's remove it then.

>>  @example
>> -#+attr_texinfo: :options org-org-export-to-org ...
>> +#+attr_texinfo: :options opt1 opt2 opt3 ...
>>  #+begin_defun
>>  A somewhat obsessive function.
>>  #+end_defun
>>  @end example
> 
> You also ruined the joke :) You need to replace the contents of the
> defun, which do not make sense anymore.
> 
> [I did not know that was a joke.]

Ah well. I find names following specific schemes funny, at times.

> Also, #+begin_defun expects a function name, not arguments.
> 
> [That's what I thought but see the original block was like that without options]

The original is correct since it provides a name for the function being
defined.

>>  @noindent
>> -becomes
>> +exports to
>>=20=20
>>  @example
>> -@@defun org-org-export-to-org ...
>> +@@defun opt1 opt2 opt3 ...
>>  A somewhat obsessive function.
>>  @@end defun
>>  @end example
> 
> Ditto.
> 
> [Restored the previous example. Strongly suggest re-editing this
> example or removing it entirely. It's neither informative nor funny.]

You may not find it funny, but it's definitely informative, since it
illustrates the :options attribute.


Regards,

-- 
Nicolas Goaziou

Re: org.texi edits, patch attached

[Nicolas Goaziou]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Lambda Coder <sjlambda@gmail.com> writes:
>
>> See attached patch for Exporting chapter against maint. 
>
> Thank you. 
>
> Unfortunately, I cannot apply it. Could you send create it with
> format-patch against maint's tip, without gzipping it?

Out of curiosity, did you make any progress on it? 

I still cannot merge your work and I wouldn't want it to be lost.

Thank you.