Re: [Patch] For the Manual: using org-crypt

[Christian Egli <christian.egli@sbs.ch>]

Julien Danjou <julien@danjou.info> writes:

> On Fri, Mar 18 2011, Ian Barton wrote:
>
>> Apologies in advance this isn't a "real" patch:) This is the entry for the
>> manual describing org-crypt.el. I was going to put it in
>> http://orgmode.org/manual/Miscellaneous.html#Miscellaneous However, since I
>> am not a Tex user, I rapidly came to the conclusion that if I tried to patch
>> org.texi, I would probably do more harm than good.
>>
>> I have also pushed a short Tutorial to Worg about using encryption with org
>> files.
>
> It seems nobody answered you: I think that if you do not try to provide
> this in form of a patch it will be forgotten.
> Or could somebody help integrating this into a patch to org.texi maybe?

The attached patch should get you started. It is just a simple org ->
texi translation, I don't know if the text conforms to the guidelines
put forth in the Documentation_Standards[1]. Please make sure it
conforms to these and then resubmit the patch. If you need any more help
please let me know.

Thanks
Christian

Footnotes: 
[1]  http://orgmode.org/w/?p=org-mode.git;a=blob;f=doc/Documentation_Standards.org;hb=HEAD

diff --git a/doc/org.texi b/doc/org.texi
index 6fc848b..fa0676f 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -675,8 +675,6 @@ Specific header arguments
                                 files during tangling
 * comments::                    Toggle insertion of comments in tangled
                                 code files
-* padline::                     Control insertion of padding lines in tangled
-                                code files
 * no-expand::                   Turn off variable assignment and noweb
                                 expansion during tangling
 * session::                     Preserve the state of code evaluation
@@ -701,6 +699,7 @@ Miscellaneous
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org on a tty
 * Interaction::                 Other Emacs packages
+* org-crypt.el::                
 
 Interaction with other packages
 
@@ -11823,8 +11822,6 @@ The following header arguments are defined:
                                 files during tangling
 * comments::                    Toggle insertion of comments in tangled
                                 code files
-* padline::                     Control insertion of padding lines in tangled
-                                code files
 * no-expand::                   Turn off variable assignment and noweb
                                 expansion during tangling
 * session::                     Preserve the state of code evaluation
@@ -12284,7 +12281,7 @@ The @code{:mkdirp} header argument can be used to create parent directories
 of tangled files when missing.  This can be set to @code{yes} to enable
 directory creation or to @code{no} to inhibit directory creation.
 
-@node comments, padline, mkdirp, Specific header arguments
+@node comments, no-expand, mkdirp, Specific header arguments
 @subsubsection @code{:comments}
 By default code blocks are tangled to source-code files without any insertion
 of comments beyond those which may already exist in the body of the code
@@ -12324,7 +12321,7 @@ Insert newlines before and after each code block body in tangled code files.
 Do not insert any newline padding in tangled output.
 @end itemize
 
-@node no-expand, session, padline, Specific header arguments
+@node no-expand, session, comments, Specific header arguments
 @subsubsection @code{:no-expand}
 
 By default, code blocks are expanded with @code{org-babel-expand-src-block}
@@ -12830,6 +12827,7 @@ emacs -Q --batch -l $ORGINSTALL \
 * Clean view::                  Getting rid of leading stars in the outline
 * TTY keys::                    Using Org on a tty
 * Interaction::                 Other Emacs packages
+* org-crypt.el::                
 @end menu
 
 
@@ -13506,7 +13504,7 @@ tty you would rather use @kbd{C-c .} to re-insert the timestamp.
 @end multitable
 
 
-@node Interaction,  , TTY keys, Miscellaneous
+@node Interaction, org-crypt.el, TTY keys, Miscellaneous
 @section Interaction with other packages
 @cindex packages, interaction with other
 Org lives in the world of GNU Emacs and interacts in various ways
@@ -13715,6 +13713,46 @@ another key for this command, or override the key in
 
 @end table
 
+@node org-crypt.el,  , Interaction, Miscellaneous
+@section org-crypt.el
+@cindex @file{org-crypt.el}
+@cindex @code{org-decrypt-entry}
+@cindex Encryption
+@cindex EasyPG
+
+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. EasyPG is part of recent Emacs releases (at least Emacs 23). It is
+available as a separate package for earlier versions of Emacs. If your
+version of Emacs already has EasyPG do not install the package manager's
+version. Doing so will lead to unpredictable results.
+
+To use org-crypt you will need to have something like the following in your
+@file{.emacs}:
+
+@example
+(require 'org-crypt)
+(org-crypt-use-before-save-magic)
+(setq org-tags-exclude-from-inheritance (quote ("crypt")))
+;; GPG key to use for encryption
+;; Either the Key ID or set to nil to use symmetric encryption.
+(setq org-crypt-key nil)
+@end example
+
+If you want to use Public Key Encryption, you will need to generate a
+suitable pubic/private key pair using @command{gnupg}.
+
+Now any text below a headline that has a @samp{:crypt:} tag will be
+automatically be encrypted when the file is saved. If you want to use a
+different tag just customize the @code{org-crypt-tag-matcher} setting.
+
+Preventing tag inheritance stops you having encrypted text inside encrypted
+text.
+
+To decrypt the text just call @kbd{M-x org-decrypt-entry} and the encrypted
+text where the point is will be replaced with the plain text. If you use this
+feature a lot, you will probably want to bind @kbd{M-x org-decrypt-entry} to
+a key.
 
 @node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking


-- 
Christian Egli
Swiss Library for the Blind, Visually Impaired and Print Disabled
Grubenstrasse 12, CH-8045 Zürich, Switzerland