* patch to add new link type "infoi" that leverages Info-index command @ 2014-11-01 18:23 Richard Kim 2014-11-06 18:41 ` Nicolas Goaziou 0 siblings, 1 reply; 6+ messages in thread From: Richard Kim @ 2014-11-01 18:23 UTC (permalink / raw) To: Emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 2721 bytes --] A patch is provided below which implements a new link type called "infoi" as a complement to "info" type that exist already. Why new link type? Because info index is almost always finer grain than info nodes. For example [[infoi:libc#close]] brings up not only "(libc)Opening and Closing Files" info node, but also place the cursor on the line that documents "open" function within the node. Hence it is more useful to link function, variable and other names that are in the index. Most info documents have very rich indexes. I am not familiar with org coding style, so I share this patch to present the idea rather than as a finished patch that can be checked in. I assume that name changes and other changes will be needed prior to being acceptable for check in assuming that the idea is ok. ChangeLog entry is followed by the git diff of my change. -------------------------------------------------------------------------------- org-info.el: Add new link type "infoi" that looks up info file index. * lisp/org-info.el (org-info-index-open): New function to implement new link type named "infoi". -------------------------------------------------------------------------------- diff --git a/doc/org.texi b/doc/org.texi index 3fcf4b2..3aedefe 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -3576,6 +3576,7 @@ gnus:group#id @r{Gnus article link} bbdb:R.*Stallman @r{BBDB link (with regexp)} irc:/irc.com/#emacs/bob @r{IRC link} info:org#External links @r{Info node link} +infoi:org#topic @r{Info index link} shell:ls *.org @r{A shell command} elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} diff --git a/lisp/org-info.el b/lisp/org-info.el index 8a2d717..bb65347 100644 --- a/lisp/org-info.el +++ b/lisp/org-info.el @@ -74,6 +74,23 @@ (Info-find-node (match-string 1 name) "Top"))) (message "Could not open: %s" name))) +;;; info-index + +(org-add-link-type "infoi" 'org-info-index-open) + +(declare-function Info-index "info" (topic)) + +(defun org-info-index-open (name) + "Follow an Info file and look up index item specified by NAME." + (if (or (string-match "\\(.*\\)[#:]:?\\(.*\\)" name) + (string-match "\\(.*\\)" name)) + (let ((nodename (match-string 2 name))) + (require 'info) + (Info-find-node (match-string 1 name) "Top") + (if nodename ; If there isn't a node, choose "Top" + (Info-index nodename))) + (message "Could not open: %s" name))) + (provide 'org-info) ;;; org-info.el ends here [-- Attachment #2: Type: text/html, Size: 3413 bytes --] ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: patch to add new link type "infoi" that leverages Info-index command 2014-11-01 18:23 patch to add new link type "infoi" that leverages Info-index command Richard Kim @ 2014-11-06 18:41 ` Nicolas Goaziou 2014-11-10 3:58 ` Richard Kim 0 siblings, 1 reply; 6+ messages in thread From: Nicolas Goaziou @ 2014-11-06 18:41 UTC (permalink / raw) To: Richard Kim; +Cc: Emacs-orgmode Hello, Richard Kim <emacs18@gmail.com> writes: > A patch is provided below which implements a new link type called "infoi" > as a complement to "info" type that exist already. Thanks for your patch. > Why new link type? Because info index is almost always finer grain > than info nodes. For example [[infoi:libc#close]] brings up not only > "(libc)Opening and Closing Files" info node, but also place the cursor > on the line that documents "open" function within the node. Hence it > is more useful to link function, variable and other names that are in > the index. Most info documents have very rich indexes. OK. I would have preferred to merge both features into the same link type, but I see no elegant syntax to distinguish between a node and an index search. > I am not familiar with org coding style, so I share this patch to > present the idea rather than as a finished patch that can be checked > in. I assume that name changes and other changes will be needed prior > to being acceptable for check in assuming that the idea is ok. The idea is OK. Some comments follow. > org-info.el: Add new link type "infoi" that looks up info file index. No full stop at the end of the summary. > * lisp/org-info.el (org-info-index-open): New function to implement > new link type named "infoi". "New function" is enough here. You can describe the motivation behind the patch farther in the commit message, after another blank line. > +;;; info-index > + > +(org-add-link-type "infoi" 'org-info-index-open) > + > +(declare-function Info-index "info" (topic)) > + > +(defun org-info-index-open (name) > + "Follow an Info file and look up index item specified by NAME." > + (if (or (string-match "\\(.*\\)[#:]:?\\(.*\\)" name) > + (string-match "\\(.*\\)" name)) > + (let ((nodename (match-string 2 name))) > + (require 'info) > + (Info-find-node (match-string 1 name) "Top") > + (if nodename ; If there isn't a node, choose "Top" > + (Info-index nodename))) Prefer `when' over one-armed `if'. > + (message "Could not open: %s" name))) This introduce some code duplication in "org-info.el". Could you factor it out? Regards, -- Nicolas Goaziou ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: patch to add new link type "infoi" that leverages Info-index command 2014-11-06 18:41 ` Nicolas Goaziou @ 2014-11-10 3:58 ` Richard Kim 2014-11-10 9:17 ` Nicolas Goaziou 0 siblings, 1 reply; 6+ messages in thread From: Richard Kim @ 2014-11-10 3:58 UTC (permalink / raw) To: Richard Kim, Emacs-orgmode [-- Attachment #1.1: Type: text/plain, Size: 3476 bytes --] Nicolas, Thanks for your feedback. I agree that using the same link type is better. Hence I took an alternate approach as detailed in the attached patch. Enhanced org-info-follow-link to attempt index lookup if node lookup fails. Following is my check in message found in the attached patch: Enhanced org-info-follow-link to attempt index lookup if node lookup fails. Info index is almost always finer grain than info nodes. For example with this change, [[info:libc#close]] brings up not only "(libc)Opening and Closing Files" info node, but also place the cursor on the line that documents "close" function within the node. This is done by looking up "close"in the index upon failing to find a node named "close". Hence one can now link function, variable and other names that are in the index rather than being limited to info node names. Typically there are far more index items than there are node names. For example libc manual has about 700 nodes, but over 4000 concept, type, function, and variables index items. On 6 November 2014 10:41, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote: > Hello, > > Richard Kim <emacs18@gmail.com> writes: > > > A patch is provided below which implements a new link type called "infoi" > > as a complement to "info" type that exist already. > > Thanks for your patch. > > > Why new link type? Because info index is almost always finer grain > > than info nodes. For example [[infoi:libc#close]] brings up not only > > "(libc)Opening and Closing Files" info node, but also place the cursor > > on the line that documents "open" function within the node. Hence it > > is more useful to link function, variable and other names that are in > > the index. Most info documents have very rich indexes. > > OK. I would have preferred to merge both features into the same link > type, but I see no elegant syntax to distinguish between a node and an > index search. > > > I am not familiar with org coding style, so I share this patch to > > present the idea rather than as a finished patch that can be checked > > in. I assume that name changes and other changes will be needed prior > > to being acceptable for check in assuming that the idea is ok. > > The idea is OK. Some comments follow. > > > org-info.el: Add new link type "infoi" that looks up info file index. > > No full stop at the end of the summary. > > > * lisp/org-info.el (org-info-index-open): New function to implement > > new link type named "infoi". > > "New function" is enough here. > > You can describe the motivation behind the patch farther in the commit > message, after another blank line. > > > +;;; info-index > > + > > +(org-add-link-type "infoi" 'org-info-index-open) > > + > > +(declare-function Info-index "info" (topic)) > > + > > +(defun org-info-index-open (name) > > + "Follow an Info file and look up index item specified by NAME." > > + (if (or (string-match "\\(.*\\)[#:]:?\\(.*\\)" name) > > + (string-match "\\(.*\\)" name)) > > + (let ((nodename (match-string 2 name))) > > + (require 'info) > > + (Info-find-node (match-string 1 name) "Top") > > + (if nodename ; If there isn't a node, choose "Top" > > + (Info-index nodename))) > > Prefer `when' over one-armed `if'. > > > + (message "Could not open: %s" name))) > > This introduce some code duplication in "org-info.el". Could you factor > it out? > > > Regards, > > -- > Nicolas Goaziou > [-- Attachment #1.2: Type: text/html, Size: 4740 bytes --] [-- Attachment #2: 0001-Enhanced-org-info-follow-link-to-attempt-index-looku.patch --] [-- Type: text/x-patch, Size: 2831 bytes --] From c850804267f343d020f91499e18cbde84a3fb897 Mon Sep 17 00:00:00 2001 From: Kim <emacs18@gmail.com> Date: Sun, 9 Nov 2014 19:43:18 -0800 Subject: [PATCH] Enhanced org-info-follow-link to attempt index lookup if node lookup fails. Info index is almost always finer grain than info nodes. For example with this change, [[info:libc#close]] brings up not only "(libc)Opening and Closing Files" info node, but also place the cursor on the line that documents "close" function within the node. This is done by looking up "close"in the index upon failing to find a node named "close". Hence one can now link function, variable and other names that are in the index rather than being limited to info node names. Typically there are far more index items than there are node names. For example libc manual has about 700 nodes, but over 4000 concept, type, function, and variables index items. --- doc/org.texi | 2 +- lisp/org-info.el | 15 +++++++++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index db1490a..08e071d 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -3575,7 +3575,7 @@ gnus:group @r{Gnus group link} gnus:group#id @r{Gnus article link} bbdb:R.*Stallman @r{BBDB link (with regexp)} irc:/irc.com/#emacs/bob @r{IRC link} -info:org#External links @r{Info node link} +info:org#External links @r{Info node or index link} shell:ls *.org @r{A shell command} elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} diff --git a/lisp/org-info.el b/lisp/org-info.el index 8a2d717..7deaa33 100644 --- a/lisp/org-info.el +++ b/lisp/org-info.el @@ -67,11 +67,18 @@ "Follow an Info file and node link specified by NAME." (if (or (string-match "\\(.*\\)[#:]:?\\(.*\\)" name) (string-match "\\(.*\\)" name)) - (progn + (let ((filename (match-string 1 name)) + (nodename-or-index (or (match-string 2 name) "Top"))) (require 'info) - (if (match-string 2 name) ; If there isn't a node, choose "Top" - (Info-find-node (match-string 1 name) (match-string 2 name)) - (Info-find-node (match-string 1 name) "Top"))) + ;; If nodename-or-index is invalid node name, then look it + ;; up in the index. + (condition-case nil + (Info-find-node filename nodename-or-index) + (user-error (Info-find-node filename "Top") + (condition-case nil + (Info-index nodename-or-index) + (user-error (message "Could not find '%s' node or index entry." + nodename-or-index)))))) (message "Could not open: %s" name))) (provide 'org-info) -- 1.9.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: patch to add new link type "infoi" that leverages Info-index command 2014-11-10 3:58 ` Richard Kim @ 2014-11-10 9:17 ` Nicolas Goaziou 2014-11-15 18:46 ` Richard Y. Kim 0 siblings, 1 reply; 6+ messages in thread From: Nicolas Goaziou @ 2014-11-10 9:17 UTC (permalink / raw) To: Richard Kim; +Cc: Emacs-orgmode Richard Kim <emacs18@gmail.com> writes: > Thanks for your feedback. I agree that using the same link type is better. > Hence I took an alternate approach as detailed in the attached patch. > Enhanced org-info-follow-link to attempt index lookup if node lookup fails. > Following is my check in message found in the attached patch: Thanks. I think it is better, indeed. Some minor comments follow. > Subject: [PATCH] Enhanced org-info-follow-link to attempt index lookup if node > lookup fails. > > Info index is almost always finer grain than info nodes. For example > with this change, [[info:libc#close]] brings up not only > "(libc)Opening and Closing Files" info node, but also place the cursor > on the line that documents "close" function within the node. This is > done by looking up "close"in the index upon failing to find a node > named "close". Hence one can now link function, variable and other > names that are in the index rather than being limited to info node > names. Typically there are far more index items than there are node > names. For example libc manual has about 700 nodes, but over > 4000 concept, type, function, and variables index items. You need to reformat a bit the commit message, according to Org mode rules (see <http://orgmode.org/worg/org-contribute.html#unnumbered-10>). E.g., --8<---------------cut here---------------start------------->8--- [PATCH] org-info: info links may attempt index lookup * lisp/org-info.el (org-info-follow-link): Attempt index lookup if node lookup fails. * doc/org.texi (External links): Update info links. Info index is almost always... TINYCHANGE --8<---------------cut here---------------end--------------->8--- You may also want to update "orgguide.texi". > + ;; If nodename-or-index is invalid node name, then look it > + ;; up in the index. > + (condition-case nil > + (Info-find-node filename nodename-or-index) > + (user-error (Info-find-node filename "Top") > + (condition-case nil > + (Info-index nodename-or-index) > + (user-error (message "Could not find '%s' node or index entry." > + nodename-or-index)))))) `message' is not needed. Also, error message shouldn't end on a full stop: (user-error "Could not find '%s' node or index entry" nodename-or-index) > (message "Could not open: %s" name))) Not directly related to your patch, but shouldn't it be (user-error "Could not open: %s" name) Regards, ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: patch to add new link type "infoi" that leverages Info-index command 2014-11-10 9:17 ` Nicolas Goaziou @ 2014-11-15 18:46 ` Richard Y. Kim 2014-11-15 23:21 ` Nicolas Goaziou 0 siblings, 1 reply; 6+ messages in thread From: Richard Y. Kim @ 2014-11-15 18:46 UTC (permalink / raw) To: Emacs-orgmode [-- Attachment #1: Type: text/plain, Size: 701 bytes --] Hi Nicolas, Thanks for your feedback. Attached is new patch which incorporates all your suggestions except the following: > Not directly related to your patch, but shouldn't it be > > (user-error "Could not open: %s" name) I'm not sure what you mean by this. Do you mean that the verb "open" is more approrpriate than "find" in the error message, i.e., "Could not open" rather than "Could not find"? If so, then it seems like "find" is more appropriate since "open" seems like there was a problem with opening a file when the problem is that a particular node was not found after successfully opening a file. Please let me know if I misunderstood. Thanks again for your valuable feedbacks. [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-org-info-try-info-index-if-info-node-is-not-found.patch --] [-- Type: text/x-diff, Size: 3239 bytes --] From 16c25b88043f6f84c6d3df14ca3018040a09fe25 Mon Sep 17 00:00:00 2001 From: Kim <emacs18@gmail.com> Date: Sat, 15 Nov 2014 10:37:39 -0800 Subject: [PATCH] org-info: try info index if info node is not found * lisp/org-info.el (org-info-follow-link): Attempt index lookup if node lookup fails. * doc/org.texi (External links): Update info links. Info index is almost always finer grain than info nodes. For example with this change, [[info:libc#close]] brings up not only "(libc)Opening and Closing Files" info node, but also place the cursor on the line that documents "close" function within the node. This is done by looking up "close"in the index upon failing to find a node named "close". Hence one can now link function, variable and other names that are in the index rather than being limited to info node names. Typically there are far more index items than there are node names. For example libc manual has about 700 nodes, but over 4000 concept, type, function, and variables index items. More examples of new ways to create links are shown using org.info as example - [[info:org#org-clock-idle-time]] uses "Variable Index" - [[info:org#org-capture]] uses "Command and Function Index". - [[info:org#timestamp]] uses "Main Index" - [[info:org#C-c C-c]] uses "Key Index" TINYCHANGE --- doc/org.texi | 2 +- lisp/org-info.el | 15 +++++++++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index b01db2c..fcaee0c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -3575,7 +3575,7 @@ gnus:group @r{Gnus group link} gnus:group#id @r{Gnus article link} bbdb:R.*Stallman @r{BBDB link (with regexp)} irc:/irc.com/#emacs/bob @r{IRC link} -info:org#External links @r{Info node link} +info:org#External links @r{Info node or index link} shell:ls *.org @r{A shell command} elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} diff --git a/lisp/org-info.el b/lisp/org-info.el index 8a2d717..7c828a6 100644 --- a/lisp/org-info.el +++ b/lisp/org-info.el @@ -67,11 +67,18 @@ "Follow an Info file and node link specified by NAME." (if (or (string-match "\\(.*\\)[#:]:?\\(.*\\)" name) (string-match "\\(.*\\)" name)) - (progn + (let ((filename (match-string 1 name)) + (nodename-or-index (or (match-string 2 name) "Top"))) (require 'info) - (if (match-string 2 name) ; If there isn't a node, choose "Top" - (Info-find-node (match-string 1 name) (match-string 2 name)) - (Info-find-node (match-string 1 name) "Top"))) + ;; If nodename-or-index is invalid node name, then look it + ;; up in the index. + (condition-case nil + (Info-find-node filename nodename-or-index) + (user-error (Info-find-node filename "Top") + (condition-case nil + (Info-index nodename-or-index) + (user-error (format "Could not find '%s' node or index entry" + nodename-or-index)))))) (message "Could not open: %s" name))) (provide 'org-info) -- 1.9.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: patch to add new link type "infoi" that leverages Info-index command 2014-11-15 18:46 ` Richard Y. Kim @ 2014-11-15 23:21 ` Nicolas Goaziou 0 siblings, 0 replies; 6+ messages in thread From: Nicolas Goaziou @ 2014-11-15 23:21 UTC (permalink / raw) To: Richard Y. Kim; +Cc: Emacs-orgmode emacs18@gmail.com (Richard Y. Kim) writes: > Thanks for your feedback. Attached is new patch which incorporates all > your suggestions Applied. Thank you. > except the following: > >> Not directly related to your patch, but shouldn't it be >> >> (user-error "Could not open: %s" name) > > I'm not sure what you mean by this. Do you mean that the verb "open" is > more approrpriate than "find" in the error message, i.e., "Could not > open" rather than "Could not find"? If so, then it seems like "find" is > more appropriate since "open" seems like there was a problem with > opening a file when the problem is that a particular node was not found > after successfully opening a file. Please let me know if I > misunderstood. Thanks again for your valuable feedbacks. This is simpler than that. I was just saying that (user-error ...) was probably more appropriate than (message ...) in the last line of the function. I changed that in another patch. > Subject: [PATCH] org-info: try info index if info node is not found Nitpick: Missing capitals after the colons. I fixed it in the patch. > + (user-error (format "Could not find '%s' node or index entry" > + nodename-or-index)))))) I changed this to (user-error "Could not ..." nodename-or-index) since `format' is not necessary. Regards, ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-11-15 23:21 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2014-11-01 18:23 patch to add new link type "infoi" that leverages Info-index command Richard Kim 2014-11-06 18:41 ` Nicolas Goaziou 2014-11-10 3:58 ` Richard Kim 2014-11-10 9:17 ` Nicolas Goaziou 2014-11-15 18:46 ` Richard Y. Kim 2014-11-15 23:21 ` Nicolas Goaziou
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).