From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Lambda Coder <sjlambda@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: org.texi edits, patch attached
Date: Sat, 26 Nov 2016 23:42:45 +0100 [thread overview]
Message-ID: <87bmx1euca.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <CAM5gNT1DEJfLm4H873801_qXf89i=WJ3v7_PfCx-SCC7e4Lz9g@mail.gmail.com> (Lambda Coder's message of "Wed, 23 Nov 2016 17:46:25 -0800")
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
next prev parent reply other threads:[~2016-11-26 22:42 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-07 23:30 org.texi edits, patch attached Lambda Coder
2016-11-11 10:18 ` Nicolas Goaziou
2016-11-11 13:38 ` Bastien Guerry
2016-11-14 12:02 ` Lambda Coder
2016-11-15 7:47 ` Nicolas Goaziou
2016-11-15 20:10 ` Lambda Coder
2016-11-15 20:44 ` Nicolas Goaziou
2016-11-16 23:30 ` Lambda Coder
2016-11-17 22:56 ` Nicolas Goaziou
2016-11-18 0:51 ` Lambda Coder
2016-11-18 8:21 ` Nicolas Goaziou
2016-11-19 4:09 ` Lambda Coder
2016-11-24 1:46 ` Lambda Coder
2016-11-26 22:42 ` Nicolas Goaziou [this message]
2016-12-02 20:33 ` Lambda Coder
2016-12-03 23:46 ` Nicolas Goaziou
2016-12-15 6:45 ` Lambda Coder
2016-12-18 23:39 ` Nicolas Goaziou
2016-12-20 3:31 ` Lambda Coder
2016-12-20 16:58 ` Nicolas Goaziou
2017-02-23 13:24 ` Nicolas Goaziou
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87bmx1euca.fsf@nicolasgoaziou.fr \
--to=mail@nicolasgoaziou.fr \
--cc=emacs-orgmode@gnu.org \
--cc=sjlambda@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).