emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [Patch] For the Manual: using org-crypt
@ 2011-03-18  8:58 Ian Barton
  2011-03-23 10:00 ` Julien Danjou
  0 siblings, 1 reply; 9+ messages in thread
From: Ian Barton @ 2011-03-18  8:58 UTC (permalink / raw)
  To: emacs-orgmode

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.

Ian.


* org-crypt.el
org-crypt will encrypt the text of an entry, but not the
headline, or properties. Org-crypt uses the Emacs EasyPG library to
ecnrypt 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 .emacs:

#+BEGIN_SRC emacs-lisp
(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_SRC

If you want to use Public Key Encryption, you will need to generate a
suitable pubic/private key pair using gnupg.

Now any text below a headline that has a :crypt: tag will be
automatically be encrypted when the file is saved. If you want to use
a different tag just customize the "org-crypt-tag-matcher" setting.

Preventing tag inheritance stops you having encrypted text inside
encrypted text.

To decrypt the text just call "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
"M-x org-decrypt-entry" to a key.

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-03-18  8:58 [Patch] For the Manual: using org-crypt Ian Barton
@ 2011-03-23 10:00 ` Julien Danjou
  2011-03-23 15:33   ` Christian Egli
  0 siblings, 1 reply; 9+ messages in thread
From: Julien Danjou @ 2011-03-23 10:00 UTC (permalink / raw)
  To: lists; +Cc: emacs-orgmode

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

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?

-- 
Julien Danjou
❱ http://julien.danjou.info

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-03-23 10:00 ` Julien Danjou
@ 2011-03-23 15:33   ` Christian Egli
  2011-03-23 16:03     ` Jambunathan K
  0 siblings, 1 reply; 9+ messages in thread
From: Christian Egli @ 2011-03-23 15:33 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-03-23 15:33   ` Christian Egli
@ 2011-03-23 16:03     ` Jambunathan K
  2011-05-24 13:15       ` Carsten Dominik
  0 siblings, 1 reply; 9+ messages in thread
From: Jambunathan K @ 2011-03-23 16:03 UTC (permalink / raw)
  To: Christian Egli; +Cc: emacs-orgmode


Thanks Christian. Some minor improvements. The intention is not to
nitpick but to build on top of what you have provided and help the
reviewer.

> +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. 

--8<---------------cut here---------------start------------->8---
> 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.
--8<---------------cut here---------------end--------------->8---

This information could be captured elsewhere and be left out of the
manual. (This parts reads like a tutorial entry)

> +
> +To use org-crypt you will need to have something like the following in your
> +@file{.emacs}:

`Recommendation', `suggestion' would be a better word. Word `something'
is ambiguous.

--8<---------------cut here---------------start------------->8---
> +If you want to use Public Key Encryption, you will need to generate a
> +suitable pubic/private key pair using @command{gnupg}.
--8<---------------cut here---------------end--------------->8---

This portion better be left out of the Org manual.

--8<---------------cut here---------------start------------->8---
> +Now any text below a headline that has a @samp{:crypt:} tag will be
> +automatically be encrypted when the file is saved. 
--8<---------------cut here---------------end--------------->8---

Above portion qualifies to be part of introductory text.


--8<---------------cut here---------------start------------->8---
> +Preventing tag inheritance stops you having encrypted text inside encrypted
> +text.
--8<---------------cut here---------------end--------------->8---

Above segment seems a bit out of context ... May be some supplementary
information has to go with it or is it just an implementation artefact
that the user need not bother about. Or is this part of the user
configuration?

> +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. 

The first part is complete in itself. The latter can be removed.

--8<---------------cut here---------------start------------->8---
> If you use this +feature a lot, you will probably want to bind
> @kbd{M-x org-decrypt-entry} to +a key.
--8<---------------cut here---------------end--------------->8---

Shouldn't part of the manual?

Jambunathan K.


-- 

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-03-23 16:03     ` Jambunathan K
@ 2011-05-24 13:15       ` Carsten Dominik
  2011-05-27  9:15         ` Christian Egli
  0 siblings, 1 reply; 9+ messages in thread
From: Carsten Dominik @ 2011-05-24 13:15 UTC (permalink / raw)
  To: Jambunathan K; +Cc: emacs-orgmode, Christian Egli

Hi,

Is anyone working on making this a complete patch?

Thanks

- Carsten

On Mar 23, 2011, at 5:03 PM, Jambunathan K wrote:

> 
> Thanks Christian. Some minor improvements. The intention is not to
> nitpick but to build on top of what you have provided and help the
> reviewer.
> 
>> +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. 
> 
> --8<---------------cut here---------------start------------->8---
>> 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.
> --8<---------------cut here---------------end--------------->8---
> 
> This information could be captured elsewhere and be left out of the
> manual. (This parts reads like a tutorial entry)
> 
>> +
>> +To use org-crypt you will need to have something like the following in your
>> +@file{.emacs}:
> 
> `Recommendation', `suggestion' would be a better word. Word `something'
> is ambiguous.
> 
> --8<---------------cut here---------------start------------->8---
>> +If you want to use Public Key Encryption, you will need to generate a
>> +suitable pubic/private key pair using @command{gnupg}.
> --8<---------------cut here---------------end--------------->8---
> 
> This portion better be left out of the Org manual.
> 
> --8<---------------cut here---------------start------------->8---
>> +Now any text below a headline that has a @samp{:crypt:} tag will be
>> +automatically be encrypted when the file is saved. 
> --8<---------------cut here---------------end--------------->8---
> 
> Above portion qualifies to be part of introductory text.
> 
> 
> --8<---------------cut here---------------start------------->8---
>> +Preventing tag inheritance stops you having encrypted text inside encrypted
>> +text.
> --8<---------------cut here---------------end--------------->8---
> 
> Above segment seems a bit out of context ... May be some supplementary
> information has to go with it or is it just an implementation artefact
> that the user need not bother about. Or is this part of the user
> configuration?
> 
>> +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. 
> 
> The first part is complete in itself. The latter can be removed.
> 
> --8<---------------cut here---------------start------------->8---
>> If you use this +feature a lot, you will probably want to bind
>> @kbd{M-x org-decrypt-entry} to +a key.
> --8<---------------cut here---------------end--------------->8---
> 
> Shouldn't part of the manual?
> 
> Jambunathan K.
> 
> 
> -- 
> 

- Carsten

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-05-24 13:15       ` Carsten Dominik
@ 2011-05-27  9:15         ` Christian Egli
  2011-05-27 10:38           ` Ian Barton
  0 siblings, 1 reply; 9+ messages in thread
From: Christian Egli @ 2011-05-27  9:15 UTC (permalink / raw)
  To: emacs-orgmode

Carsten Dominik <carsten.dominik@gmail.com> writes:

> Is anyone working on making this a complete patch?

Sorry, no.

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-05-27  9:15         ` Christian Egli
@ 2011-05-27 10:38           ` Ian Barton
       [not found]             ` <EC782DA7-22B0-4B54-950D-CA00F00DAF8C@gmail.com>
  0 siblings, 1 reply; 9+ messages in thread
From: Ian Barton @ 2011-05-27 10:38 UTC (permalink / raw)
  To: emacs-orgmode

On 27/05/11 10:15, Christian Egli wrote:
> Carsten Dominik<carsten.dominik@gmail.com>  writes:
>
>> Is anyone working on making this a complete patch?
>
> Sorry, no.
>
I'll have a go and try to make a proper patch against the current 
manual. Don't blame me if the manual breaks:)

Ian.

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
       [not found]             ` <EC782DA7-22B0-4B54-950D-CA00F00DAF8C@gmail.com>
@ 2011-05-30 18:23               ` Ian Barton
  2011-05-31 11:40                 ` Carsten Dominik
  0 siblings, 1 reply; 9+ messages in thread
From: Ian Barton @ 2011-05-30 18:23 UTC (permalink / raw)
  To: emacs-orgmode

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

Here is the patch. Thanks to Christian for his help. I have edited the 
text to take into account Jambunathans comments.

Ian.

On 27/05/11 11:47, Carsten Dominik wrote:
> Actually, please just make the section in texi formatting, I or someone else will link it in into the manual structure.  This is difficult to get right with a patch.  Please take Jambunathans comments int account.
>
> Thanks
>
> - Carsten
>
> On May 27, 2011, at 12:38 PM, Ian Barton wrote:
>
>> On 27/05/11 10:15, Christian Egli wrote:
>>> Carsten Dominik<carsten.dominik@gmail.com>   writes:
>>>
>>>> Is anyone working on making this a complete patch?
>>> Sorry, no.
>>>
>> I'll have a go and try to make a proper patch against the current manual. Don't blame me if the manual breaks:)
>>
>> Ian.
>>
>>
>
>
>


[-- Attachment #2: org-crypt.patch --]
[-- Type: text/x-diff, Size: 2229 bytes --]

From 1861079c6db46c9be36dbbc30ef5d738d5d14193 Mon Sep 17 00:00:00 2001
From: Ian Barton <ian@wilkesley.net>
Date: Mon, 30 May 2011 18:48:33 +0100
Subject: [PATCH] Add section about org-crypt.el.

---
 doc/org.texi |   30 +++++++++++++++++++++++++++++-
 1 files changed, 29 insertions(+), 1 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index e13af4b..91cd199 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -12773,6 +12773,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::                Encrypting Org files
 @end menu
 
 
@@ -13449,7 +13450,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
@@ -13658,6 +13659,33 @@ 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}
+
+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.
+
+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.
+
+To use org-crypt it is suggested that you have 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
+
+Excluding the crypt tag from inheritance prevents already encrypted text
+being encrypted again.
 
 @node Hacking, MobileOrg, Miscellaneous, Top
 @appendix Hacking
-- 
1.7.4.1


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [Patch] For the Manual: using org-crypt
  2011-05-30 18:23               ` Ian Barton
@ 2011-05-31 11:40                 ` Carsten Dominik
  0 siblings, 0 replies; 9+ messages in thread
From: Carsten Dominik @ 2011-05-31 11:40 UTC (permalink / raw)
  To: Ian Barton; +Cc: emacs-orgmode

Applied, thanks.

- Carsten

On May 30, 2011, at 8:23 PM, Ian Barton wrote:

> Here is the patch. Thanks to Christian for his help. I have edited the text to take into account Jambunathans comments.
> 
> Ian.
> 
> On 27/05/11 11:47, Carsten Dominik wrote:
>> Actually, please just make the section in texi formatting, I or someone else will link it in into the manual structure.  This is difficult to get right with a patch.  Please take Jambunathans comments int account.
>> 
>> Thanks
>> 
>> - Carsten
>> 
>> On May 27, 2011, at 12:38 PM, Ian Barton wrote:
>> 
>>> On 27/05/11 10:15, Christian Egli wrote:
>>>> Carsten Dominik<carsten.dominik@gmail.com>   writes:
>>>> 
>>>>> Is anyone working on making this a complete patch?
>>>> Sorry, no.
>>>> 
>>> I'll have a go and try to make a proper patch against the current manual. Don't blame me if the manual breaks:)
>>> 
>>> Ian.
>>> 
>>> 
>> 
>> 
>> 
> 
> <org-crypt.patch>

- Carsten

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2011-05-31 11:40 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-03-18  8:58 [Patch] For the Manual: using org-crypt Ian Barton
2011-03-23 10:00 ` Julien Danjou
2011-03-23 15:33   ` Christian Egli
2011-03-23 16:03     ` Jambunathan K
2011-05-24 13:15       ` Carsten Dominik
2011-05-27  9:15         ` Christian Egli
2011-05-27 10:38           ` Ian Barton
     [not found]             ` <EC782DA7-22B0-4B54-950D-CA00F00DAF8C@gmail.com>
2011-05-30 18:23               ` Ian Barton
2011-05-31 11:40                 ` Carsten Dominik

Code repositories for project(s) associated with this 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).