[PATCH] org-file-apps docstring: document using regexp group matches as command line parameters, add examples

[PATCH] org-file-apps docstring: document using regexp group matches as command line parameters, add examples

[Jan Böcker]

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

This is also available via
git pull git://github.com/jboecker/org-mode.git for-carsten

I tried to document the new behaviour as concise and clear as possible.

(If anyone reads this and finds it too confusing in any way, please say
so . I introduced the changes, so I know what they do and why, but the
docstring has to explain this to people who do not.)

While I could not make it any shorter than my first draft, I hope that
the clear separation of the three possible interpretations of a string
as the file identifier and the short example for each one will allow the
reader to quickly find what they need without having to understanding
all of the complexity first.

Regards,
  Jan

[-- Attachment #2: 0001-org-file-apps-docstring-document-using-regexp-group-.patch --]
[-- Type: text/x-patch, Size: 3031 bytes --]

From 98fa677bc979ac9e89826d2b520233a7724a87ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20B=C3=B6cker?= <jan.boecker@jboecker.de>
Date: Wed, 12 May 2010 23:15:56 +0200
Subject: [PATCH] org-file-apps docstring: document using regexp group matches as command line parameters, add examples

The functionality which this patch documents was originally introduced
in commit 75563bf71e6df356a5ae77a93152fcf913378107, then re-written in
commit dfda58d720484124f9432a09d831a9d6292908af and the 5 commits before
that.
---
 lisp/org.el |   34 +++++++++++++++++++++++++++++++---
 1 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 8dc806d..89879c2 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1477,9 +1477,37 @@ you can use this variable to set the application for a given file
 extension.  The entries in this list are cons cells where the car identifies
 files and the cdr the corresponding command.  Possible values for the
 file identifier are
- \"regex\"     Regular expression matched against the file name.  For backward
-               compatibility, this can also be a string with only alphanumeric
-               characters, which is then interpreted as an extension.
+ \"string\"    A string as a file identifier can be interpreted in different 
+               ways, depending on its contents:
+               
+               - Alphanumeric characters only:
+                 Match links with this file extension.
+                 Example: (\"pdf\" . \"evince %s\")
+                          to open PDFs with evince.
+
+               - Regular expression: Match links where the
+                 filename matches the regexp.  If you want to
+                 use groups here, use shy groups.
+
+                 Example: (\"\\.x?html\\'\" . \"firefox %s\")
+                          (\"\\(?:xhtml\\|html\\)\" . \"firefox %s\")
+                          to open *.html and *.xhtml with firefox.
+
+               - Regular expression which contains (non-shy) groups:
+                 Match links where the whole link,
+                 including \"::\" and anything after that, matches the regexp.
+                 In a custom command string, %1, %2, etc. are replaced with the
+                 parts of the link that were matched by the groups.
+                 For backwards compatibility, if a command string is given that
+                 does not use any of the group matches, this case is handled
+                 identically to the second one (i.e. match against file name only).
+
+                 In a custom lisp form, you can access the group matches with
+                 (match-string n link).
+
+                 Example: (\"\\.pdf::\\(\\d+\\)\\'\" . \"evince -p %1 %s\")
+                          to open [[file:document.pdf::5]] with evince at page 5.
+
  `directory'   Matches a directory
  `remote'      Matches a remote file, accessible through tramp or efs.
                Remote files most likely should be visited through Emacs
-- 
1.7.0.4


[-- Attachment #3: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: [PATCH] org-file-apps docstring: document using regexp group matches as command line parameters, add examples

[Carsten Dominik]

Hi Jan, this looks good, I have applied it.  Thanks!

- Carsten

On May 12, 2010, at 11:44 PM, Jan Böcker wrote:

> This is also available via
> git pull git://github.com/jboecker/org-mode.git for-carsten
>
> I tried to document the new behaviour as concise and clear as  
> possible.
>
> (If anyone reads this and finds it too confusing in any way, please  
> say
> so . I introduced the changes, so I know what they do and why, but the
> docstring has to explain this to people who do not.)
>
> While I could not make it any shorter than my first draft, I hope that
> the clear separation of the three possible interpretations of a string
> as the file identifier and the short example for each one will allow  
> the
> reader to quickly find what they need without having to understanding
> all of the complexity first.
>
> Regards,
>  Jan
> <0001-org-file-apps-docstring-document-using-regexp- 
> group-.patch>_______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten