Gist (gist.el / Emacs) — Set the `description` at

The default behavior of gist-region is to leave the description blank. To set the description, it is necessary to switch to the gist-list buffer and then use the function gist-edit-current-description to set the description.

I would like to be able to set the description at the same time that the gist is created, without switching to the gist-list buffer. A mini-buffer prompt that defaults to the buffer-name would be the preferred method of handling this. How can this be accomplished programmatically?

Here are the two main functions in gist.el that are responsible for the behavior described above:

(defun gist-region (begin end &optional private callback)
  "Post the current region as a new paste at gist.github.com
Copies the URL into the kill ring.

With a prefix argument, makes a private paste."
  (interactive "r\nP")
  (let* ((file (or (buffer-file-name) (buffer-name)))
         (name (file-name-nondirectory file))
         (ext (or (cdr (assoc major-mode gist-supported-modes-alist))
                  (file-name-extension file)
                  "txt"))
         (fname (concat (file-name-sans-extension name) "." ext))
         (files (list
                 (gh-gist-gist-file "file"
                                    :filename fname
                                    :content (buffer-substring begin end)))))
    (gist-internal-new files private nil callback)))

(defun gist-edit-current-description ()
  (interactive)
  (let* ((id (tabulated-list-get-id))
         (gist (gist-list-db-get-gist id))
         (old-descr (oref gist :description))
         (new-descr (read-from-minibuffer "Description: " old-descr)))
    (let* ((g (clone gist
                     :files nil
                     :description new-descr))
           (api (gist-get-api t))
           (resp (gh-gist-edit api g)))
      (gh-url-add-response-callback resp
                                    (lambda (gist)
                                      (gist-list-reload))))))

Take a look at the function gist-internal-new that gist-region is calling.

(gist-internal-new FILES &optional PRIVATE DESCRIPTION CALLBACK)

The third param is the description but gist-region is setting it to nil. You can modify that last expression in gist-region to read a string from the minibuffer to specify a description

(gist-internal-new files private (read-from-minibuffer "Gist Description: ") callback)

Or better yet, don't modify the function and just write your own! That way, you don't mess with other packages that use the function.

Here is just a slightly a modified version that adds an extra parameter and uses interactive to automatically prompt the user for a description while still allowing prefix args to make private gists.

Unlike the first example when we used `read-from-minibuffer' this one will allow you to use the function in code and specify the description directly without forcing a prompt to be used unless it's called interactively.

;; note that we added the DESCRIPTION argument
(defun gist-region-with-description (begin end &optional description private callback)
  "Post the current region as a new paste at gist.github.com
Copies the URL into the kill ring.

With a prefix argument, makes a private paste."
  (interactive "r\nsGist Description: \nP") ;; we handle the prompt here!
  (let* ((file (or (buffer-file-name) (buffer-name)))
         (name (file-name-nondirectory file))
         (ext (or (cdr (assoc major-mode gist-supported-modes-alist))
                  (file-name-extension file)
                  "txt"))
         (fname (concat (file-name-sans-extension name) "." ext))
         (files (list
                 (gh-gist-gist-file "file"
                                    :filename fname
                                    :content (buffer-substring begin end)))))
    ;; finally we use our new arg to specify the description in the internal call
    (gist-internal-new files private description callback)))