[elpa] externals/dash 733274f 398/426: Merge pull request #120 from holomorph/info-manual

[Phillip Lord]

branch: externals/dash
commit 733274fbb47676f95bd26cf3fdcd87841e4bfc7a
Merge: 0ef7384 4bd6273
Author: Magnar Sveen <address@hidden>
Commit: Magnar Sveen <address@hidden>

    Merge pull request #120 from holomorph/info-manual
    
    Add info manual
---
 create-docs.sh          |    6 +
 dash-template.texi      |  438 +++++++++++++++++++++++++++++++++++++++++++++++
 dev/examples-to-info.el |  175 +++++++++++++++++++
 3 files changed, 619 insertions(+), 0 deletions(-)

diff --git a/create-docs.sh b/create-docs.sh
index dbaae5c..d24082d 100755
--- a/create-docs.sh
+++ b/create-docs.sh
@@ -4,4 +4,10 @@ if [ -z "$EMACS" ] ; then
     EMACS="emacs"
 fi
 
+if [ -z "$MAKEINFO" ] ; then
+    MAKEINFO="makeinfo"
+fi
+
 $EMACS -batch -l dash.el -l dash-functional.el -l dev/examples-to-docs.el -l 
dev/examples.el -f create-docs-file
+$EMACS -batch -l dash.el -l dash-functional.el -l dev/examples-to-info.el -l 
dev/examples.el -f create-info-file
+$MAKEINFO --fill-column=70 dash.texi
diff --git a/dash-template.texi b/dash-template.texi
new file mode 100644
index 0000000..ea0339b
--- /dev/null
+++ b/dash-template.texi
@@ -0,0 +1,438 @@
+\input texinfo    @c -*- texinfo -*-
address@hidden %**start of header
address@hidden dash.info
address@hidden dash
address@hidden UTF-8
address@hidden en
address@hidden fn cp
address@hidden %**end of header
+
address@hidden
+
+This manual is for @code{dash.el} version 2.10.0.
+
+Copyright © 2012-2015 Magnar Sveen
+
address@hidden
+This program 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.
+
+This program 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 this program.  If not, see @uref{http://www.gnu.org/licenses/}.
address@hidden quotation
address@hidden copying
+
address@hidden
address@hidden
address@hidden Dash
address@hidden Magnar Sveen
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
+
address@hidden
address@hidden Top
address@hidden dash
address@hidden
address@hidden ifnottex
+
address@hidden
+* Installation::
+* Functions::
+* Development::
+* Index::
+
address@hidden
+--- The Detailed Node Listing ---
+
+Installation
+
+* Using in a package::
+* Syntax highlighting of dash functions::
+
+Functions
+
address@hidden [[ function-nodes ]]
+
+Development
+
+* Contribute::          How to contribute
+* Changes::             List of significant changes by version
+* Contributors::        List of contributors
address@hidden detailmenu
address@hidden menu
+
+
+
address@hidden Installation
address@hidden Installation
+
+It's available on @uref{http://marmalade-repo.org/,marmalade} and
address@hidden://melpa.milkbox.net/,Melpa}; use @code{M-x
+package-install}:
+
address@hidden @kbd
address@hidden M-x package-install @key{RET} dash
+Install the dash library.
address@hidden table
+
address@hidden @kbd
address@hidden M-x package-install @key{RET} dash-functional
+Optional, if you want the function combinators.
address@hidden table
+
+Alternatively, you can just dump @verb{~dash.el~} or
address@hidden in your load path somewhere.
+
address@hidden
+* Using in a package::
+* Syntax highlighting of dash functions::
address@hidden menu
+
address@hidden Using in a package
address@hidden Using in a package
+
+Add this to the big comment block at the top:
+
address@hidden
+;; Package-Requires: ((dash "2.10.0"))
address@hidden lisp
+
address@hidden To get function combinators:
+
address@hidden
+;; Package-Requires: ((dash "2.10.0") (dash-functional "1.2.0") (emacs "24"))
address@hidden lisp
+
address@hidden Syntax highlighting of dash functions
address@hidden Syntax highlighting of dash functions
+
+Font lock of dash functions in emacs lisp buffers is now optional.
+Include this in your emacs settings to get syntax highlighting:
+
address@hidden
+(eval-after-load "dash" '(dash-enable-font-lock))
address@hidden lisp
+
address@hidden Functions
address@hidden Functions
+
+This chapter contains reference documentation for the dash
address@hidden programming interface,API}.  All functions and
+constructs in the library are prefixed with a dash (-).
+
+There are also anaphoric versions of functions where that makes sense,
+prefixed with two dashes instead of one.
+
+For instance, while @code{-map} takes a function to map over the list,
+one can also use the anaphoric form with double dashes - which will
+then be executed with @code{it} exposed as the list item. Here's an
+example:
+
address@hidden
+(-map (lambda (n) (* n n)) '(1 2 3 4)) ;; normal version
+
+(--map (* it it) '(1 2 3 4)) ;; anaphoric version
address@hidden lisp
+
address@hidden Of course, the original can also be written like
+
address@hidden
+(defun square (n) (* n n))
+
+(-map 'square '(1 2 3 4))
address@hidden lisp
+
address@hidden which demonstrates the usefulness of both versions.
+
address@hidden
address@hidden [[ function-nodes ]]
address@hidden menu
+
address@hidden [[ function-docs ]]
+
address@hidden Development
address@hidden Development
+
+The dash repository is hosted on GitHub:
address@hidden://github.com/magnars/dash.el}
+
address@hidden
+* Contribute::          How to contribute
+* Changes::             List of significant changes by version
+* Contributors::        List of contributors
address@hidden menu
+
address@hidden Contribute
address@hidden Contribute
+
+Yes, please do. Pure functions in the list manipulation realm only,
+please. There's a suite of tests in @verb{~dev/examples.el~}, so remember to 
add
+tests for your function, or it might get broken later.
+
+Run the tests with @code{./run-tests.sh}. Create the docs with
address@hidden/create-docs.sh}. I highly recommend that you install these as a
+pre-commit hook, so that the tests are always running and the docs are
+always in sync:
+
address@hidden
+cp pre-commit.sh .git/hooks/pre-commit
address@hidden verbatim
+
+Oh, and don't edit @file{README.md} directly, it is auto-generated.
+Change @file{readme-template.md} or @file{examples-to-docs.el}
+instead.  The same goes for the info manual.
+
address@hidden Changes
address@hidden Changes
+
address@hidden Changes in 2.10:
+
address@hidden
address@hidden
+Add @code{-let} destructuring to @code{-if-let} and @code{-when-let}
+(Fredrik Bergroth)
address@hidden itemize
+
address@hidden Changes in 2.9:
+
address@hidden
address@hidden
+Add @code{-let}, @code{-let*} and @code{-lambda} with destructuring
address@hidden
+Add @code{-tree-seq} and @code{-tree-map-nodes}
address@hidden
+Add @code{-non-nil}
address@hidden
+Add @code{-fix}
address@hidden
+Add @code{-fixfn} (dash-functional 1.2)
address@hidden
+Add @code{-copy} (Wilfred Hughes)
address@hidden itemize
+
address@hidden Changes in 2.8:
+
address@hidden
address@hidden
+Add @code{-butlast}
address@hidden itemize
+
address@hidden Changes in 2.7:
+
address@hidden
address@hidden
address@hidden now supports more than two lists (Steve Lamb)
address@hidden
+Add @code{-cycle}, @code{-pad}, @code{-annotate}, @code{-zip-fill}
+(Steve Lamb)
address@hidden
+Add @code{-table}, @code{-table-flat} (finite cartesian product)
address@hidden
+Add @code{-flatten-n}
address@hidden
address@hidden now supports "step" argument
address@hidden
+Add functional combinators @code{-iteratefn}, @code{-prodfn}
address@hidden
+Add @code{-replace}, @code{-splice}, @code{-splice-list} which
+generalize @code{-replace-at} and @code{-insert-at}
address@hidden
+Add @code{-compose}, @code{-iteratefn} and @code{-prodfn}
+(dash-functional 1.1)
address@hidden itemize
+
address@hidden Changes in 2.6:
+
address@hidden
address@hidden
+Add @code{-is-prefix-p}, @code{-is-suffix-p}, @code{-is-infix-p}
+(Matus Goljer)
address@hidden
+Add @code{-iterate}, @code{-unfold} (Matus Goljer)
address@hidden
+Add @code{-split-on}, @code{-split-when} (Matus Goljer)
address@hidden
+Add @code{-find-last-index} (Matus Goljer)
address@hidden
+Add @code{-list} (Johan Andersson)
address@hidden itemize
+
address@hidden Changes in 2.5:
+
address@hidden
address@hidden
+Add @code{-same-items?} (Johan Andersson)
address@hidden
+A few bugfixes
address@hidden itemize
+
address@hidden Changes in 2.4:
+
address@hidden
address@hidden
+Add @code{-snoc} (Matus Goljer)
address@hidden
+Add @code{-replace-at}, @code{-update-at}, @code{-remove-at}, and
address@hidden (Matus Goljer)
address@hidden itemize
+
address@hidden Changes in 2.3:
+
address@hidden
address@hidden
+Add tree operations (Matus Goljer)
address@hidden
+Make font-lock optional
address@hidden itemize
+
address@hidden Changes in 2.2:
+
address@hidden
address@hidden
+Add @code{-compose} (Christina Whyte)
address@hidden itemize
+
address@hidden Changes in 2.1:
+
address@hidden
address@hidden
+Add indexing operations (Matus Goljer)
address@hidden itemize
+
address@hidden Changes in 2.0:
+
address@hidden
address@hidden
+Split out @code{dash-functional.el} (Matus Goljer)
address@hidden
+Add @code{-andfn}, @code{-orfn}, @code{-not}, @code{-cut},
address@hidden, @code{-flip} and @code{-on}. (Matus Goljer)
address@hidden
+Fix @code{-min}, @code{-max}, @code{-min-by} and @code{-max-by} (Matus
+Goljer)
address@hidden itemize
+
address@hidden Changes in 1.8:
+
address@hidden
address@hidden
+Add @code{-first-item} and @code{-last-item} (Wilfred Hughes)
address@hidden itemize
+
address@hidden Changes in 1.7:
+
address@hidden
address@hidden
+Add @code{-rotate} (Matus Goljer)
address@hidden itemize
+
address@hidden Changes in 1.6:
+
address@hidden
address@hidden
+Add @code{-min}, @code{-max}, @code{-min-by} and @code{-max-by} (Johan
+Andersson)
address@hidden itemize
+
address@hidden Changes in 1.5:
+
address@hidden
address@hidden
+Add @code{-sum} and @code{-product} (Johan Andersson)
address@hidden itemize
+
address@hidden Changes in 1.4:
+
address@hidden
address@hidden
+Add @code{-sort}
address@hidden
+Add @code{-reduce-r} (Matus Goljer)
address@hidden
+Add @code{-reduce-r-from} (Matus Goljer)
address@hidden itemize
+
address@hidden Changes in 1.3:
+
address@hidden
address@hidden
+Add @code{-partition-in-steps}
address@hidden
+Add @code{-partition-all-in-steps}
address@hidden itemize
+
address@hidden Changes in 1.2:
+
address@hidden
address@hidden
+Add @code{-last} (Matus Goljer)
address@hidden
+Add @code{-insert-at} (Emanuel Evans)
address@hidden
+Add @code{-when-let} and @code{-if-let} (Emanuel Evans)
address@hidden
+Add @code{-when-let*} and @code{-if-let*} (Emanuel Evans)
address@hidden
+Some bugfixes
address@hidden itemize
+
address@hidden Contributors
address@hidden Contributors
+
address@hidden
address@hidden
address@hidden://github.com/Fuco1,Matus Goljer} contributed lots of
+features and functions.
address@hidden
address@hidden://github.com/tkf,Takafumi Arakaki} contributed
address@hidden
address@hidden
address@hidden://github.com/tali713,tali713} is the author of
address@hidden
address@hidden
address@hidden://github.com/vemv,Víctor M. Valenzuela} contributed
address@hidden
address@hidden
address@hidden://github.com/nicferrier,Nic Ferrier} contributed
address@hidden
address@hidden
address@hidden://github.com/Wilfred,Wilfred Hughes} contributed
address@hidden, @code{-first-item} and @code{-last-item}.
address@hidden
address@hidden://github.com/shosti,Emanuel Evans} contributed
address@hidden, @code{-when-let} and @code{-insert-at}.
address@hidden
address@hidden://github.com/rejeep,Johan Andersson} contributed
address@hidden, @code{-product} and @code{-same-items?}
address@hidden
address@hidden://github.com/kurisuwhyte,Christina Whyte} contributed
address@hidden
address@hidden
address@hidden://github.com/steventlamb,Steve Lamb} contributed
address@hidden, @code{-pad}, @code{-annotate}, @code{-zip-fill} and an
+n-ary version of @code{-zip}.
address@hidden
address@hidden://github.com/fbergroth,Fredrik Bergroth} made the
address@hidden family use @code{-let} destructuring and improved
+script for generating documentation.
address@hidden itemize
+
+Thanks!
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
diff --git a/dev/examples-to-info.el b/dev/examples-to-info.el
new file mode 100644
index 0000000..8c67382
--- /dev/null
+++ b/dev/examples-to-info.el
@@ -0,0 +1,175 @@
+(require 'dash)
+(require 'dash-functional)
+(require 'help-fns)
+
+(defvar functions '())
+
+(defun example-to-string (example)
+  (let ((actual (car example))
+        (expected (nth 2 example)))
+    (--> (format "@group\n%S\n    @result{} address@hidden group" actual 
expected)
+      (replace-regexp-in-string "\\\\\\?" "?" it)
+      (replace-regexp-in-string "{\"" "@{\"" it t t)
+      (replace-regexp-in-string "}\"" "@}\"" it t t)
+      (replace-regexp-in-string " {" " @{" it t t)
+      (replace-regexp-in-string "\"{" "\"@{" it t t)
+      (replace-regexp-in-string "}," "@{," it t t)
+      (replace-regexp-in-string "address@hidden" "@address@hidden" it t t))))
+
+(defun docs--signature (function)
+  "Given FUNCTION (a symbol), return its argument list.
+FUNCTION may reference an elisp function, alias, macro or a subr."
+  (let* ((function-value (indirect-function function))
+         (is-alias (not (eq function-value (symbol-function function))))
+         ;; if FUNCTION isn't an alias, function-symbol is simply FUNCTION
+         (function-symbol function))
+
+    (when is-alias
+      ;; find the last symbol in the alias chain
+      (while (symbolp (symbol-function function-symbol))
+        (setq function-symbol (symbol-function function-symbol))))
+
+    (if (subrp function-value)
+        ;; read the docstring to find the signature for subrs
+        (let* ((docstring-args (car (help-split-fundoc
+                                     (documentation function-value)
+                                     function-symbol)))
+               (fun-with-args (read (downcase docstring-args))))
+          (cdr fun-with-args))
+      ;; otherwise get the signature directly
+      (help-function-arglist function-symbol))))
+
+(defmacro defexamples (cmd &rest examples)
+  `(add-to-list 'functions (list
+                            ',cmd
+                            (docs--signature ',cmd)
+                            (documentation ',cmd)
+                            (-map 'example-to-string (-partition 3 
',examples)))))
+
+(defmacro def-example-group (group desc &rest examples)
+  `(progn
+     (add-to-list 'functions ,(concat "### " group))
+     (when ,desc
+       (add-to-list 'functions ,desc))
+     ,@examples))
+
+(defun quote-and-downcase (string)
+  (format "@var{%s}" (downcase string)))
+
+(defun unquote-and-link (string)
+  (format-link (substring string 1 -1)))
+
+(defun format-link (string-name)
+  (-let* ((name (intern string-name))
+          ((_ signature _ _) (assoc name functions)))
+    (if signature
+        (format "@code{%s} (@pxref{%s})" name name)
+      (format "@code{%s}" name))))
+
+(defun format-docstring (docstring)
+  (let (case-fold-search)
+    (--> docstring
+      (replace-regexp-in-string "\\b\\([A-Z][A-Z-]*[0-9]*\\)\\b" 
'quote-and-downcase it t)
+      (replace-regexp-in-string "`\\([^ ]+\\)'" 'unquote-and-link it t)
+      (replace-regexp-in-string "{,@}" "{,@@}" it t)
+      (replace-regexp-in-string "^  " "    " it))))
+
+(defun function-to-node (function)
+  (when (and (stringp function)
+             (string-match "^\\(### [[:upper:]][[:alpha:]- ]+\\)$" function))
+    (concat (s-replace "### " "* " (match-string 1 function)) "::")))
+
+(defun function-to-info (function)
+  (if (stringp function)
+      (concat "\n" (s-replace "### " "@node " function) "\n"
+              (when (string-match "^### " function)
+                (s-replace "### " "@section " function)) "\n")
+    (-let [(command-name signature docstring examples) function]
+      (format (concat "@anchor{%s}\n"
+                      "@defun %s %s\n"
+                      "%s\n\n"
+                      "@address@hidden address@hidden defun\n")
+              command-name
+              command-name
+              signature
+              (format-docstring docstring)
+              (mapconcat 'identity (-take 3 examples) "\n")))))
+
+(defun docs--chop-prefix (prefix s)
+  "Remove PREFIX if it is at the start of S."
+  (let ((pos (length prefix)))
+    (if (and (>= (length s) (length prefix))
+             (string= prefix (substring s 0 pos)))
+        (substring s pos)
+      s)))
+
+(defun docs--chop-suffix (suffix s)
+  "Remove SUFFIX if it is at end of S."
+  (let ((pos (- (length suffix))))
+    (if (and (>= (length s) (length suffix))
+             (string= suffix (substring s pos)))
+        (substring s 0 pos)
+      s)))
+
+(defun github-id (command-name signature)
+  (docs--chop-suffix
+   "-"
+   (replace-regexp-in-string "[^a-zA-Z0-9-]+" "-" (docs--chop-prefix
+                                                   "!"
+                                                   (format "%S %S" 
command-name signature)))))
+
+(defun s-replace (old new s)
+  "Replaces OLD with NEW in S."
+  (replace-regexp-in-string (regexp-quote old) new s t t))
+
+(defun function-summary (function)
+  (if (stringp function)
+      (concat "\n" function "\n")
+    (let ((command-name (car function))
+          (signature (cadr function)))
+      (format "* [%s](#%s) `%s`" command-name (github-id command-name 
signature) signature))))
+
+(defun simplify-quotes ()
+  (goto-char (point-min))
+  (while (search-forward "(quote nil)" nil t)
+    (replace-match "'()"))
+  (goto-char (point-min))
+  (while (search-forward "(quote " nil t)
+    (forward-char -7)
+    (let ((p (point)))
+      (forward-sexp 1)
+      (delete-char -1)
+      (goto-char p)
+      (delete-char 7)
+      (insert "'"))))
+
+(defun goto-and-remove (s)
+  (goto-char (point-min))
+  (search-forward s)
+  (delete-char (- (length s))))
+
+(defun create-info-file ()
+  (let ((functions (nreverse functions)))
+    (with-temp-file "./dash.texi"
+      (insert-file-contents-literally "./dash-template.texi")
+
+      (goto-and-remove "@c [[ function-nodes ]]")
+      (insert (mapconcat 'function-to-node
+                         (-filter (lambda (s)
+                                    (when (stringp s)
+                                      (string-match "^### " s)))
+                                  functions)
+                         "\n"))
+
+      (goto-and-remove "@c [[ function-nodes ]]")
+      (insert (mapconcat 'function-to-node
+                         (-filter (lambda (s)
+                                    (when (stringp s)
+                                      (string-match "^### " s)))
+                                  functions)
+                         "\n"))
+
+      (goto-and-remove "@c [[ function-docs ]]")
+      (insert (mapconcat 'function-to-info functions "\n"))
+
+      (simplify-quotes))))