Contribution to org-mode, Eldoc support

Contribution to org-mode, Eldoc support

[Łukasz Gruner]

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

Hi

I would like to contribute Eldoc support.
I've already changed license, but dont quite get that pgp part, I have
generated my pgp and now what?

Cheers,
Łukasz Gruner

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-eldoc-support-for-src_blocks-and-headlines.patch --]
[-- Type: text/x-diff; name="0001-Add-eldoc-support-for-src_blocks-and-headlines.patch", Size: 7353 bytes --]

From e96112a92c7c24f16c1274b3e8c6567634e19eb1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Gruner?= <lukasz@gruner.lu>
Date: Sat, 1 Nov 2014 15:57:54 +0100
Subject: [PATCH] Add eldoc support for src_blocks and headlines.

* lisp/org-eldoc.el (org-eldoc-hook-setup) initialize
eldoc with org mode. Org mode will display Breadcrumb path
when on a header line, src block properties when on src block
and while inside of src-block will try to act natively for that
language.
---
 lisp/org-eldoc.el | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 lisp/org-eldoc.el

diff --git a/lisp/org-eldoc.el b/lisp/org-eldoc.el
new file mode 100644
index 0000000..844100d
--- /dev/null
+++ b/lisp/org-eldoc.el
@@ -0,0 +1,172 @@
+;;; org-eldoc.el --- display org header and src block info using eldoc
+
+;; Copyright (c) 2014 Free Software Foundation, Inc.
+
+;; Author: Łukasz Gruner <lukasz@gruner.lu>
+;; Maintainer: Łukasz Gruner <lukasz@gruner.lu>
+;; Version: 6
+;; Package-Requires: ((org "8"))
+;; URL: https://bitbucket.org/ukaszg/org-eldoc
+;; Created: 25/05/2014
+;; Keywords: eldoc, outline, breadcrumb, org, babel, minibuffer
+
+;; This file is not part of Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; To enable, put the following in your .emacs file:
+;;
+;; (org-eldoc-hook-setup) ;; have org-eldoc add itself to `org-mode-hook'
+;; OR run:
+;; (org-eldoc-load)       ;; to setup org-eldoc and enable `eldoc-mode'
+;;
+;;
+;; Report bugs and feature requests at:
+;;
+;; https://bitbucket.org/ukaszg/org-eldoc/issues
+
+;;; Changelog:
+
+;; As of 01/11/14 switching license to GPL3 to allow submission to org-mode.
+
+;;; Code:
+
+(require 'org)
+(require 'ob-core)
+(require 'eldoc)
+
+(defgroup org-eldoc nil "" :group 'org)
+
+(defcustom org-eldoc-breadcrumb-separator "/"
+  "Breadcrumb separator."
+  :group 'org-eldoc
+  :type 'string)
+
+(defcustom org-eldoc-test-buffer-name " *Org-eldoc test buffer*"
+  "Name of the buffer used while testing for mode-local variable values."
+  :group 'org-eldoc
+  :type 'string)
+
+(defun org-eldoc-get-breadcrumb ()
+  "Return breadcrumb if on a headline or nil."
+  (let ((case-fold-search t) cur)
+    (save-excursion
+      (beginning-of-line)
+      (save-match-data
+        (when (looking-at org-complex-heading-regexp)
+          (setq cur (match-string 4))
+          (org-format-outline-path
+           (append (org-get-outline-path) (list cur))
+           (frame-width) "" org-eldoc-breadcrumb-separator))))))
+
+(defun org-eldoc-get-src-header ()
+  "Returns lang and list of header properties if on src definition line and nil otherwise."
+  (let ((case-fold-search t) info lang hdr-args)
+    (save-excursion
+      (beginning-of-line)
+      (save-match-data
+        (when (looking-at "^[ \t]*#\\+\\(begin\\|end\\)_src")
+          (setq info (org-babel-get-src-block-info 'light)
+                lang (propertize (nth 0 info) 'face 'font-lock-string-face)
+                hdr-args (nth 2 info))
+          (concat
+           lang
+           ": "
+           (mapconcat
+            (lambda (elem)
+              (when (and (cdr elem) (not (string= "" (cdr elem))))
+                (concat
+                 (propertize (symbol-name (car elem)) 'face 'org-list-dt)
+                 " "
+                 (propertize (cdr elem) 'face 'org-verbatim)
+                 " ")))
+            hdr-args " ")))))))
+
+(defun org-eldoc-get-src-lang ()
+  "Return value of lang for the current block if in block body and nil otherwise."
+  (let ((case-fold-search t))
+    (save-match-data
+      (when (org-between-regexps-p ".*#\\+begin_src"
+                                   ".*#\\+end_src")
+        (save-excursion
+          (goto-char (org-babel-where-is-src-block-head))
+          (car (org-babel-parse-src-block-match)))))))
+
+(defvar org-eldoc-local-functions-cache (make-hash-table :size 40 :test 'equal)
+  "Cache of major-mode's eldoc-documentation-functions,
+ used by \\[org-eldoc-get-mode-local-documentation-function].")
+
+(defun org-eldoc-get-mode-local-documentation-function (lang)
+  "Check if LANG-mode sets eldoc-documentation-function and return its value."
+  (let ((cached-func (gethash lang org-eldoc-local-functions-cache 'empty))
+        (mode-func (intern-soft (format "%s-mode" lang)))
+        doc-func)
+    (if (eq 'empty cached-func)
+        (when (fboundp mode-func)
+          (with-temp-buffer
+            (funcall mode-func)
+            (setq doc-func (and eldoc-documentation-function
+                                (symbol-value 'eldoc-documentation-function)))
+            (puthash lang doc-func org-eldoc-local-functions-cache))
+          doc-func)
+      cached-func)))
+
+(declare-function c-eldoc-print-current-symbol-info "c-eldoc" ())
+(declare-function css-eldoc-function "css-eldoc" ())
+(declare-function php-eldoc-function "php-eldoc" ())
+(declare-function go-eldoc--documentation-function "go-eldoc" ())
+
+(defun org-eldoc-documentation-function ()
+  "Return breadcrumbs when on a headline, args for src block header-line,
+  calls other documentation functions depending on lang when inside src body."
+  (or
+   (org-eldoc-get-breadcrumb)
+   (org-eldoc-get-src-header)
+   (let ((lang (org-eldoc-get-src-lang)))
+     (cond ((or
+             (string= lang "c") ;; http://github.com/nflath/c-eldoc
+             (string= lang "C")) (when (require 'c-eldoc nil t)
+                                   (c-eldoc-print-current-symbol-info)))
+           ;; https://github.com/zenozeng/css-eldoc
+           ((string= lang "css") (when (require 'css-eldoc nil t)
+                                   (css-eldoc-function)))
+           ;; https://github.com/zenozeng/php-eldoc
+           ((string= lang "php") (when (require 'php-eldoc nil t)
+                                   (php-eldoc-function)))
+           ((or
+             (string= lang "go")
+             (string= lang "golang")) (when (require 'go-eldoc nil t)
+                                        (go-eldoc--documentation-function)))
+           (t (let ((doc-fun (org-eldoc-get-mode-local-documentation-function lang)))
+                (when (fboundp doc-fun) (funcall doc-fun))))))))
+
+;;;###autoload
+(defun org-eldoc-load ()
+  "Set up org-eldoc and enable `eldoc-mode'."
+  (interactive)
+  (setq-local eldoc-documentation-function #'org-eldoc-documentation-function)
+  (eldoc-mode 1))
+
+;;;###autoload
+(defun org-eldoc-hook-setup ()
+  "Add org-eldoc initialization code to `org-mode-hook'."
+  (add-hook 'org-mode-hook #'org-eldoc-load))
+
+(provide 'org-eldoc)
+
+;; -*- coding: utf-8-emacs; -*-
+
+;;; org-eldoc.el ends here
-- 
2.1.1

Re: Contribution to org-mode, Eldoc support

[Aaron Ecay]

Hi Lukasz,

Thanks for your contribution.

2014ko azaroak 1an, Łukasz Gruner-ek idatzi zuen:
> 
> Hi
> 
> I would like to contribute Eldoc support.
> I've already changed license, but dont quite get that pgp part, I have
> generated my pgp and now what?

There’s a couple of issues.

1. Write access to the org repository.  For that you need an SSH (not
   PGP) key.  This tutorial from GitHub
   <https://help.github.com/articles/generating-ssh-keys/> goes over
   what is needed.  When you get to step 3, instead of entering the key
   file in GitHub’s website, you email it to Jason Dunsmore or Bastien
   Guerry.

2. Copyright assignment.  For code in org’s core, you need to have a
   copyright assignment on file with the FSF (because any code in org
   will eventually become part of emacs).  The process is documented
   here: <http://orgmode.org/worg/org-contribute.html#unnumbered-2>.
   The org mode repo has a contrib directory, where it is OK to put code
   without a copyright assignment.  This is bundled into
   org-plus-contrib packages that many people install, but cannot be put
   into emacs releases.

   So org-eldoc can be added to contrib immediately, and then moved to
   the core (i.e. out of contrib) when the copyright assignment is
   complete (if you decide that copyright assignment is something you
   want to do, and also subject to the judgment of the org maintainers).

Does that make sense?

Thanks again,

-- 
Aaron Ecay

Re: Contribution to org-mode, Eldoc support

[Rasmus]

Hi Łukasz,

Thanks for the patch.

I tested your package briefly, but I did not look into the code.

Łukasz Gruner <lukasz@gruner.lu> writes:

> I would like to contribute Eldoc support.

It works nice for source blocks.  However, I don't get any feedback in
header-lines:

 #+header:
 #+begin_src emacs-lisp
 ...
 #+end_src

On headlines, I'm a bit surprised that it shows breadcrumbs.  Normally,
eldoc provides feedback for what arguments are possible I think.  Would
it not make more sense — in terms of what I expect when I turn eldoc on
— if it showed what can be a each location.  E.g. right after "^*" there
is an optional TODO keyword/state. 

Also, I think it should somehow "just work" when I turn on eldoc in Org,
i.e. not the extra steps needed with the hook or the other way to load
it.

> I've already changed license, but dont quite get that pgp part, I have
> generated my pgp and now what?

I'm not sure about this.  Have you signed the FSF paperwork?  I did not
find a Gruner here:

     http://orgmode.org/worg/org-contribute.html

—Rasmus

-- 
What will be next?

Re: Contribution to org-mode, Eldoc support

[Łukasz Gruner]

On Sun, Nov 2, 2014, at 20:28, Rasmus wrote:
> It works nice for source blocks.  However, I don't get any feedback in
> header-lines:
> 
>  #+header:
>  #+begin_src emacs-lisp
This works only on #XXX_SRC header lines (I don't use anything else and
am not very knowledgable about it, thus I only support this)