OrgReadme-fy: README.org from your library's functions and tests (Emacs package)

(use-package orgreadme-fy
  :commands (orgreadme-fy-make-new-readme-template
             orgreadme-fy-make-new-readme
             orgreadme-fy-see-news
             orgreadme-fy-see-readme
             orgreadme-fy-see-library-readme))

(use-package orgreadme-fy :demand t)

(require 'orgreadme-fy)

#+begin_src emacs-lisp :exports results :results raw
(orgreadme-fy-libfile->orgstr
 "orgreadme-fy.el"
 (list :output-type 'table
       :include-pred (lambda (fun)
                       (s-match (rx symbol-start
                                    (| "orgreadme-fy-describe"
                                       "orgreadme-fy-make-new-readme-template"
                                       "orgreadme-fy-make-new-readme"
                                       "orgreadme-fy-libfile->orgstr"
                                       "orgreadme-fy-libfile->orgbuf"
                                       "orgreadme-fy-see-readme"
                                       "orgreadme-fy-see-library-readme")
                                    symbol-end)
                                fun))))
#+end_src

#+begin_src emacs-lisp :exports results :results raw
(orgreadme-fy-libfile->orgstr "orgreadme-fy.el"
                              (list :root-level                 1
                                    :output-type        'describe
                                    :only-with-examples       nil
                                    :exclude-pred  (lambda (fun)
                                                     (s-match "--" fun))))
#+end_src

;;; orgreadme-fy.el --- README.org from your library's functions and tests   -*- lexical-binding: t -*-
;;; Commentary:
;;;; For all the details, please do see the README
;;; Acknowledgments:
;;; Code:
;;;; Libraries
;;;; Obsolete symbols
;;;; Package metadata
;;;; Customizable variables
;;;; Functions
;;;;; The describe-heading macro
;;;;; Create your README
;;;;; Generate org strings from your library and its examples
;;;;; Generate hash tables
;;;;; Generate org pieces
;;;;; Generate parts of functions' documentation
;;;;; Generate parts of user options' documentation
;;;;; Buffer replacements and adjustments
;;;;;; README.org post-processing
;;;;;; libfile->orgstr generation post-processing
;;;;; Accessing READMEs
;;;;;; Quick access to a library's README
;;;;;; See OrgReadme-Fy's README
;;;;;; See OrgReadme-Fy's News
;;;; Wrapping up
;;; orgreadme-fy.el ends here

;;; orgreadme-fy.el --- README.org from your library's functions and tests   -*- lexical-binding: t -*-

;; SPDX-FileCopyrightText:  © flandrew <https://keyoxide.org/191F5B3E212EF1E515C19918AF32B9A5C1CCCB2D>
;; SPDX-License-Identifier: GPL-3.0-or-later

;;---------------------------------------------------------------------------
;; Author:            flandrew
;; Created:           2022-04-02
;; Version:           1.0
;; Homepage:          <https://flandrew.srht.site/listful/software.html>
;; Keywords:          maint, docs, lisp
;; Package-Requires:  ((emacs "25.1")  (dash "2.14")  (s "1.12")  (f "0.20")  (xht "1.0.5"))
;;---------------------------------------------------------------------------

;; This file is part of OrgReadme-fy, which is NOT part of GNU Emacs.

;; 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. For more details, see the full license at
;; either LICENSES/GPL-3.0-or-later.txt or <https://www.gnu.org/licenses/>.

;;; Commentary:
;;
;; OrgReadme-fy helps you create a README.org for your Emacs projects.
;; Features:
;;
;; - It can generate for you a readme-template.org so you don't have to start
;;   from scratch. This file will, upon creation, fetch some metadata from
;;   your package file (the main .el). It will have a skeleton of common
;;   sections.
;;
;; - It can generate for you a summary table and/or descriptive subtrees that
;;   feed readme-template.org to create the final README.org. This table
;;   and/or subtrees, in turn, are automatically generated from your package
;;   file and an optional examples.el file, providing a list of functions,
;;   their signature, their docstring, and examples of usage.
;;
;; It's independent from, but goes hand-in-hand with, Exemplify-ERT.
;;
;;;; For all the details, please do see the README
;;
;; Open it easily with any of the below:
;;   (find-file-read-only              "README.org")   <--- C-x C-e here¹, or
;;   (find-file-read-only-other-frame  "README.org")   <--- C-x C-e here¹, or
;;   (find-file-read-only-other-window "README.org")   <--- C-x C-e here¹
;;
;; or from any buffer:
;;   M-x orgreadme-fy-see-readme
;;
;; or read it online:
;;   <https://flandrew.srht.site/listful/sw-emacs-orgreadme-fy.html>
;;
;; ¹ or the key that ‘eval-last-sexp’ is bound to, if not C-x C-e.
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;; Acknowledgments:
;;
;; The idea for this library came after seeing how clean Dash's ERT tests
;; looked in Dash's dev/examples.el, and that these examples were being
;; used to generate Dash's README.md.
;;
;; After using the examples structure myself while writing XHT, I decided to
;; further develop the idea. The result was two independent packages that go
;; well together: Exemplify-ERT and OrgReadme-fy.
;;
;; My thanks to Magnar Sveen and the other Dash contributors.
;;
;; ------------------------------------------------------------------------
;;
;; Function ‘orgreadme-fy-list-loaded-libraries’ was adapted from apropos.el's
;; ‘apropos-library’.
;;
;; About apropos.el:
;;   SPDX-FileCopyrightText:  © Free Software Foundation, Inc.
;;   SPDX-License-Identifier: GPL-3.0-or-later
;;   Authors:                 Joe Wells, Daniel Pfeiffer
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;; Code:
;;;; Libraries

(require 'pcase)
(require 'dash)
(require 'xht)       ; <---also by the author of this package
(require 'rx)
(require 'f)
(require 's)
(require 'ox)        ; ‘org-export-to-file’
(require 'org)       ; ‘org-mark-subtree’, ‘org-at-heading-p’,
;;                     ‘org-map-region’, ‘org-entry-get’
(require 'subr-x)    ; ‘if-let’
(require 'lisp-mnt)  ; ‘lm-summary’, ‘lm-version’, ‘lm-homepage’

;;;; Obsolete symbols

(let ((new 'orgreadme-fy)
      (old 'ormfy)
      (ver "1.0"))

  (mapc
   (lambda (sym) (define-obsolete-variable-alias
              (intern (format "%s-%s" old sym))
              (intern (format "%s-%s" new sym)) ver))
   '(downcase-properties
     post-process-readme-org-user               function-word
     readme-template-org-rel-path                summary-word
     examples-rel-path                         signature-word
     templates-template-file-rel-path         alias-from-word
     templates-template-file                    alias-to-word
     top-callables-exclusions-list-default  ops-plist-default
     top-callables-exclusions-list-user     ops-plist-user))

  (mapc
   (lambda (sym) (define-obsolete-function-alias
              (intern (format "%s-%s" old sym))
              (intern (format "%s-%s" new sym)) ver))
   '(describe
     make-new-readme-template  see-readme                      lines-ht
     make-new-readme           see-library-readme           headings-ht
     libfile->orgstr           libname->libfile      headings-ranges-ht
     libfile->orgbuf           list-loaded-libraries           descs-ht
     fun->documentation   cusvar->documentation              aliases-ht
     fun->docstring       cusvar->docstring                     funs-ht
     fun->1stline         cusvar->1stline                   examples-ht
     fun->middledoc       cusvar->middledoc                range-lookup
     fun->signature       cusvar->signature
     fun->signature-from-symbol-function           make-links-in-buffer
     fun->org-src-block                          align-tables-in-buffer
     heading-elisp->org                         make-prop-nil-in-buffer
     post-process-readme-org              downcase-properties-in-buffer
     remove-empty-headings               promote-all-subtrees-in-buffer
     delete-subtree                       demote-all-subtrees-in-buffer
     adjust-root-level                       fetch-custom-ids-in-buffer
     -obj-sym-str-or-error   restore-params-of-org-src-blocks-in-buffer)))

;;;; Package metadata

(defconst orgreadme-fy--name "OrgReadme-Fy")

(defconst orgreadme-fy--dot-el
  (format "%s.el" (file-name-sans-extension (eval-and-compile
                                              (or load-file-name
                                                  buffer-file-name)))))
(defconst orgreadme-fy--readme-org
  (expand-file-name "README.org" (file-name-directory orgreadme-fy--dot-el)))

(defconst orgreadme-fy--summary  (lm-summary  orgreadme-fy--dot-el))
(defconst orgreadme-fy--version  (lm-version  orgreadme-fy--dot-el))
(defconst orgreadme-fy--homepage (lm-homepage orgreadme-fy--dot-el))

;;;; Customizable variables

(defgroup orgreadme-fy nil
  (format "%s." orgreadme-fy--summary)
  :group 'convenience
  :link  '(emacs-library-link :tag "Lisp file" "orgreadme-fy.el")
  :link  `(file-link :tag "README.org" ,orgreadme-fy--readme-org)
  :link  `(url-link  :tag "Homepage"   ,orgreadme-fy--homepage))

(defcustom orgreadme-fy-downcase-properties t
  "Downcase property words such as #+AUTHOR in README.org?"
  :type  'boolean
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-post-process-readme-org-user
  #'ignore
  "Additional function to call on README.org after post-processing.
This will be run after ‘orgreadme-fy-post-process-readme-org’,
which see. The default value here does nothing."
  :type  'function
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-function-word "Function"
  "Label of Functions column when :output-type is 'table."
  :type  'string
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-summary-word "Summary"
  "Label of  Summary column when :output-type is 'table."
  :type  'string
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-signature-word "Signature"
  "Label of Signature column when :output-type is 'table."
  :type  'string
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-alias-from-word "This function…"
  "Label of Alias from column when :output-subtype is 'aliases."
  :type  'string
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-alias-to-word "is an alias to…"
  "Label of Alias to column when :output-subtype is 'aliases."
  :type  'string
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-readme-template-org-rel-path "readme-template.org"
  "Name of the template file for .org."
  :type  'string
  :group 'orgreadme-fy)

(defcustom orgreadme-fy-examples-rel-path "dev/examples.el"
  "Where to look for the examples file if no path is passed.
This is relative to the location of the library file."
  :type  'string
  :group 'orgreadme-fy)

(defvar orgreadme-fy-templates-template-file-rel-path
  "templates/readme-templates-template.org"
  "Relative location of the default template's template file.")

(defcustom orgreadme-fy-templates-template-file ""
  "The path to the readme-template.org's file-generating template.
You can copy the default file from the templates subdir, modify it,
save it, and then pass this file's path to this variable.

See the docstring of ‘orgreadme-fy-new-readme’ for more information."
  :type  'file
  :group 'orgreadme-fy)

(defvar orgreadme-fy-top-callables-exclusions-list-default
  '(make-obsolete
    define-obsolete-variable-alias     define-obsolete-function-alias
    defalias   defvaralias   defgroup   defvar   defconst   defcustom
    require                      provide                     autoload
    let let* -let -let*        -if-let -when-let  -if-let* -when-let*
    setq setq-default setq-local -setq          if when unless and or
    mapc dolist -each --each                       ht-set!     h-put!
    eval     eval-after-load    eval-and-compile    eval-when-compile
    with-eval-after-load                        orgreadme-fy-describe)
  "Default list of functions and macro symbols to exclude.
When found being executed at the top level, will be excluded from
consideration and not documented.

Note that the ‘orgreadme-fy-describe’ macro is in this exclusion
list because it receives no function as argument. Its string
argument is retrieved separately and specially.")

(defcustom orgreadme-fy-top-callables-exclusions-list-user nil
  "A list of additional functions and macro symbols to exclude.
When found being executed at the top level, they will be excluded
from consideration and not documented. Add here whatever is not
about the functions and macros which you wish to describe and
exemplify in the README."
  :type '(repeat symbol)
  :group 'orgreadme-fy)

(defvar orgreadme-fy-ops-plist-default
  (list :only-non-empty-headings                t
        :inter-heading-spacing                  1
        :only-with-examples                     t
        :signatures-column                    nil
        :output-type                    'describe
        :output-subtype                'functions
        :describe-fun      'orgreadme-fy-describe
        :include-pred                         nil
        :exclude-pred                         nil
        :make-links                             t
        :root-level                             2)
  "Default property list of options to use when generating the org string.
Any item of this setting can be overridden when set with different
values in ‘orgreadme-fy-ops-plist-user’.")

(defcustom orgreadme-fy-ops-plist-user nil
  "Property list of options to use when generating the org string.
Values in ‘orgreadme-fy-ops-plist-user’ are overridden by those set
by this variable."
  :type  'plist
  :group 'orgreadme-fy)

;;;; Functions
;;;;; The describe-heading macro

;;;###autoload
(defmacro orgreadme-fy-describe (str)
  "Describe with string STR the contents under this heading.
Think of it as a docstring for the subheadings of your elisp files.

A heading is a line-beginning comment that has 3+ semicolons. Each
heading may have as many ‘orgreadme-fy-describe’ calls as you want,
although as a general rule a single one should suffice and is
preferable. (When more than one is present under a heading when
‘orgreadme-fy-libfile->orgbuf’ is called on your file, their
strings will be concatenated, separated from each other by an empty
line.)

You can use this in your programs to describe what each
section/heading of your program's file is about. You don't need to
install or require orgreadme-fy for that: just copy this macro to
some place in your program before the first call to it. Then rename
it using your library prefix.

For example: ‘yourlibrary-describe’ or ‘yourlibrary--describe’.

You'll need to pass :describe-fun #'<that-chosen-name> as a pair of
the OPS argument when calling ‘orgreadme-fy-libfile->orgstr’.

Feel free to strip away all of this docstring beyond the first two
lines (or even all of it) if that suits you and you'd rather have
it short. See ‘xht--describe’ for an example.

If you ever want to create org documentation from your file, it
will be ready. And if you don't, I'd say that using it will be more
manageable than using comments, and will make it more readable to
others. It will also help distinguish between documentation-like
descriptions (using this) and small, incidental, code-local
commenting (using regular comments).

Finally, remember that you can create org tables inside STR when
you call this macro — in fact, inside *any* function's docstring as
well — with the function ‘orgtbl-mode’, which is a minor mode that
works outside org. This can come handy to summarize properties of
functions under the heading you're describing."
  (declare (indent 0))
  (unless (stringp str)
    (user-error "The 'describe macro' must receive a string")))
;; ^ Why not read the line number of the declaration to feed a hash table in a
;;   global variable? Because it'd be unnecessarily complex and also fragile
;;   (since line numbers could be spurious if called from another function or
;;   depending on whether interpreted or compiled, etc).
;;
;;   This dumb-looking solution here works better and has no dependencies.
;;   Note that the macro itself does nothing with the string, which is
;;   completely ignored (but otherwise easily readable by whomever goes
;;   through your .el). The strings are recovered later, when creating your
;;   README, by ‘orgreadme-fy-descs-ht’, which is called by
;;   ‘orgreadme-fy-libfile->orgstr’, which is called by
;;   ‘orgreadme-fy-libfile->orgbuf’.

;;;;; Create your README

(orgreadme-fy-describe
  "We have two steps here:

1. Generate a readme-template.org that is specific to your project.
   This is done once, with ‘orgreadme-fy-make-new-readme-template’.
   This file will have calls for the insertion of other pieces —
   pieces such as functions' documentations and examples (generated
   by ‘orgreadme-fy-libfile->orgstr’).

2. Generate the README.org — the one people will read. This will be
   done from readme-template.org with
   ‘orgreadme-fy-make-new-readme’.

The first is better called interactively from your library.el, so
that it guesses paths, etc.

For the second, you can either:

  1. Open readme-template.org and:  M-x orgreadme-fy-make-new-readme

     This is already there at the top of the template, though.
     Just C-x C-e it.

  2. From the command line, cd to your project folder and run:

       ./make-readme.sh

     This script is placed on your project folder by
     ‘orgreadme-fy-make-new-readme-template’.

     It runs Emacs in batch mode, generates README.org, and exits.")

;;;###autoload
(defun orgreadme-fy-make-new-readme-template
    (&optional libfile templates-template-file)
  "Create a readme-template.org for your project.
Run it interactively and confirm filenames and directory.

LIBFILE is the project's main .el (the package file), from which
readme-template.org will have metadata extracted to fill out some
information for you already.

TEMPLATES-TEMPLATE-FILE is the template-generating template file;
the orgreadme-fy-template's template file. The default will be
suggested — a file provided with this package.

Eventually, you may want to copy this default and adapt it to your
needs — to however your README files are likely to be structured,
which will likely differ from my humbly suggested structure. Do so.
Save it somewhere and then pass this path to
‘orgreadme-fy-templates-template-file’. Your template's template
will then be the one suggested when you create a
readme-template.org."
  (interactive)
  (unless libfile
    (setq libfile (read-file-name
                   "Your library file (the .el): " nil nil nil
                   (let ((el (-> (f-base default-directory)
                                 (concat ".el"))))
                     (when (f-exists? (f-expand el default-directory))
                       el))
                   nil)))
  (let* ((root  (f-parent libfile))
         (pack  (f-base root))
         (this  (orgreadme-fy-libname->libfile 'orgreadme-fy))
         ;; make-readme.sh
         (mkrdt (->> this  f-parent (f-expand "templates/make-readme.sh")))
         (mkrd  (f-expand "make-readme.sh" root))
         ;; readme-template.org
         (rtorg (f-expand orgreadme-fy-readme-template-org-rel-path root)))

    ;; Make make-readme.sh
    (unless (f-exists? mkrd)
      (copy-file mkrdt mkrd)
      (set-file-modes  mkrd #o744))

    ;; Make readme-template.org
    (if (not (or (not (f-exists? rtorg))
                 (and (y-or-n-p (s-lex-format
                                 "File ${rtorg} exists. OVERWRITE?"))
                      (y-or-n-p (s-lex-format
                                 "Will overwrite ${rtorg}. Are you sure?")))))
        (message "Ok, nothing done")
      (--> (or templates-template-file
               (read-file-name
                "Template's template file to use:\n"
                "/" nil nil
                (or (s-presence orgreadme-fy-templates-template-file)
                    (->> this  f-parent
                         (f-expand
                          orgreadme-fy-templates-template-file-rel-path)))
                nil))
           f-read
           (s-replace-all `(("$PACKAGE"     . ,pack)
                            ("$DESCRIPTION" . ,(--> libfile  lm-summary))
                            ("$KEYWORDS"    . ,(--> libfile  lm-keywords))
                            ("$NAME"        . ,(--> libfile  lm-authors
                                                    (-map #'car it)
                                                    (s-join ", " it)))
                            ("$YEAR"        . ,(->> (decode-time)
                                                    (nth 5)
                                                    (format "%s"))))
                          it)
           (s-replace-regexp (concat "#.title:[ \t]+\\(" pack "\\)[ \t]*$")
                             (s-titleize pack)
                             it nil nil 1)
           ;; "or" because f-write returns nil with success, error otherwise.
           (or (f-write it 'utf-8 rtorg)
               (find-file         rtorg))))))

;;;###autoload
(defun orgreadme-fy-make-new-readme (&optional readme-template-org readme-org)
  "Create a README.org for your project.
This command should be called after you have created a
readme-template with ‘orgreadme-fy-make-new-readme-template’.

If filename README-TEMPLATE-ORG is provided, use it. Otherwise it's
assumed that the current buffer is the source template file.

If filename README-ORG is provided, use it.
Otherwise default to \"README.org\".

The generated README's buffer is then marked as read-only, to help
you remember that changes should be made upstream instead (to your
readme-template), lest a future conversion overwrites them."
  (interactive)
  (when readme-template-org
    (find-file readme-template-org))
  (unless readme-org
    (setq readme-org "README.org"))
  (unless (eq major-mode 'org-mode)
    (user-error "Not an org file: %s. Can't make %s"
                readme-template-org readme-org))
  (let ((was-already-open-p (find-buffer-visiting readme-org))
        (pr (make-progress-reporter
             (format "Creating %s..." readme-org))))
    (when was-already-open-p
      (pop-to-buffer was-already-open-p)
      (save-buffer)
      (kill-buffer   was-already-open-p))
    (org-export-to-file 'org readme-org)
    (find-file readme-org)
    (orgreadme-fy-post-process-readme-org)
    (when orgreadme-fy-post-process-readme-org-user
      (funcall orgreadme-fy-post-process-readme-org-user))
    (save-buffer)
    (read-only-mode 1)
    (progress-reporter-done pr)))

;;;;; Generate org strings from your library and its examples

(orgreadme-fy-describe
  "These are the main functions to be used for generating org strings. These
strings will be inserted in your final README.org with the help of org src
blocks calling ‘orgreadme-fy-libfile->orgstr’.")

;;;###autoload
(defun orgreadme-fy-libfile->orgstr (libfile &optional ops exmpfile excl-list)
  "Given LIBFILE, OPS, and EXMPFILE, return README-ready org string.
Your library file must have a heading \";;; Code:\".

OPS is a plist. It allows you to select the sort of org string that
you want and some further refinements. You can then call this
function repeatedly with separate parameters to generate separate
org string outputs, which may then be seamlessly included in
different parts of your README.org.

Here are the possibilities:
| Key                      | Default value           | Possible values       |
|--------------------------+-------------------------+-----------------------|
| :output-type             | 'describe               | '(table describe)     |
| :output-subtype          | 'functions              | '(functions aliases¹) |
| :only-non-empty-headings | t                       | t or nil              |
| :only-with-examples      | t                       | t or nil              |
| :describe-fun            | #'orgreadme-fy-describe | fun name or string    |
| :make-links              | t                       | t or nil              |
| :signatures-column       | nil                     | t or nil              |
| :inter-heading-spacing   | 0                       | natnump               |
| :root-level              | 2                       | natnump               |
| :include-pred            | nil (include all)       | any regexp            |
| :exclude-pred            | nil (exclude none)      | any regexp            |

¹ only when 'table, as 'describe can only be 'functions. So if you set
  :output-subtype to 'aliases under 'describe it will be ignored, and
  'describe will fall back to 'functions.

What is what:
| Key                      | Explanation                                   |
|--------------------------+-----------------------------------------------|
| :output-type             | Full documentation or summary table           |
| :output-subtype          | When 'table, output functions or aliases?     |
| :only-non-empty-headings | Whether to exclude empty headings             |
| :only-with-examples      | Whether to exclude functions without examples |
| :describe-fun            | Name of heading-describing function           |
| :make-links              | Whether to make links for functions           |
| :signatures-column       | Whether to add a signatures column            |
| :inter-heading-spacing   | Number of blank lines between headings        |
| :root-level              | Number of asterisks at root subtrees          |
| :include-pred            | Function/aliases names to include (predicate) |
| :exclude-pred            | Function/aliases names to exclude (predicate) |

So :root-level is the level (number of asterisks) to be assigned to
the root subtree(s) generated when :output-type (see below) is
'describe. (It has no influence when :output-type is 'table.)

When :root-level is nil, 0, 2, or not a natural number it defaults,
unchanged, to 2. If it's 1, all subtrees are promoted. If greater
than 2, all subtrees are demoted accordingly.

If you don't want to convert any links wrapped in `' or ‘’ from
your docstrings to point to custom_ids, set :make-links to nil.

Inclusion is processed before exclusion.

One example of :exclude-pred would be:

#+begin_src emacs-lisp
  (lambda (fun) (s-match \"--\" fun))
#+end_src

to exclude showing internal functions in the documentation (unless
you use \"--\" to denote anaphoric macros — then not).

Another example is a :include-pred of

#+begin_src emacs-lisp
  (lambda (fun) (commandp fun))
#+end_src

to only include functions that are commands — that is, interactive.

And :describe-fun is to allow LIBFILE to have the
‘orgreadme-fy-describe’ macro under a different name. See
‘orgreadme-fy-describe’ for more information.

Not all options apply to the different output types.
When not applicable (N/A), passing the option has no effect.

|                          | 'describe  | 'table     | 'table   |
|--------------------------+------------+------------+----------|
| Key                      | 'functions | 'functions | 'aliases |
|--------------------------+------------+------------+----------|
| :only-non-empty-headings | ✓          | N/A        | N/A      |
| :inter-heading-spacing   | ✓          | N/A        | N/A      |
| :only-with-examples      | ✓          | N/A        | N/A      |
| :describe-fun            | ✓          | N/A        | N/A      |
| :signatures-column       | N/A        | ✓          | N/A      |
| :root-level              | ✓          | N/A        | N/A      |
| :make-links              | ✓          | ✓          | N/A      |
| :include-pred            | ✓          | ✓          | ✓        |
| :exclude-pred            | ✓          | ✓          | ✓        |

The plist is updated in this order:
‘orgreadme-fy-ops-plist-default’, ‘orgreadme-fy-ops-plist-user’,
and OPS. So OPS has higher precedence.

If EXMPFILE is nil, use ‘orgreadme-fy-examples-rel-path’.

EXCL-LIST is a list of callables to exclude besides those of
‘orgreadme-fy-top-callables-exclusions-list-default’ and
‘orgreadme-fy-top-callables-exclusions-list-user’."
  (unless exmpfile
    (setq exmpfile (f-expand orgreadme-fy-examples-rel-path
                             (f-parent libfile))))
  (unless (f-exists? exmpfile)
    (warn "orgreadme-fy-library->subtree: Couldn't find %s" exmpfile))
  (unless (f-exists? libfile)
    (user-error "‘orgreadme-fy-library’->subtree: Couldn't find %s" libfile))

  ;; Library must be loaded so we can fetch docstrings and signatures:
  (-> libfile  f-long  f-no-ext  load)

  (setq ops (h-mix (h<-plist orgreadme-fy-ops-plist-default)
                   (h<-plist orgreadme-fy-ops-plist-user)
                   (h<-plist ops)))
  (h-let ops
    ;; Some more error handling
    (unless (natnump  .inter-heading-spacing)
      (error ":inter-heading-spacing must be a natural number"))
    (unless (booleanp .make-links)
      (error ":make-links must be a boolean"))
    (unless (booleanp .signatures-column)
      (error ":signatures-column must be a boolean"))
    (unless (booleanp .only-non-empty-headings)
      (error ":only-non-empty-headings must be a boolean"))
    (unless (booleanp .only-with-examples)
      (error ":only-with-examples must be a boolean"))
    (unless (memq     .output-type '(table describe))
      (error "Invalid :output-type option"))

    ;; Handle the case where :describe-fun isn't ‘orgreadme-fy-describe’, such
    ;; as when one borrows the macro and rename it with the package's prefix.
    (setq excl-list (-uniq (cons .describe-fun excl-list)))

    (let* ((lines-ht    (orgreadme-fy-lines-ht           libfile))
           (headings-ht (orgreadme-fy-headings-ht        lines-ht))
           (head-rng-ht (orgreadme-fy-headings-ranges-ht headings-ht libfile))
           ;; Further trim headings-ht: only those under "Code:"
           (code-line   (car (h--first (s-prefix? ";;; Code:"
                                                  value t)
                                       lines-ht)))
           (headcode-ht (h--sel (and (> key code-line)
                                     (not (s-match "^;;; .*"
                                                   value)))
                                headings-ht))
           examples-ht   descs-ht   funs-ht   aliases-ht
           hline  heading  level  descs  funs-to-ht  funs)

      (with-temp-buffer
        (let ((standard-output (current-buffer)))
          (pcase .output-type
            ('table
             (setq hline  "|----------+------------+-----------|\n")
             (princ  "| ")
             (pcase .output-subtype
               ('functions
                (setq funs-ht    (orgreadme-fy-funs-ht    lines-ht excl-list))
                (princ orgreadme-fy-function-word)
                (princ " | ") (princ orgreadme-fy-summary-word)
                (when .signatures-column
                  (princ " | ") (princ orgreadme-fy-signature-word)))
               ('aliases
                (setq aliases-ht (orgreadme-fy-aliases-ht libfile))
                (princ orgreadme-fy-alias-from-word)
                (princ " | ") (princ orgreadme-fy-alias-to-word)))
             (princ " |\n")

             (h--each headcode-ht
               (pcase .output-subtype
                 ('functions
                  (setq funs (->> (orgreadme-fy-range-lookup
                                   key head-rng-ht funs-ht)
                                  (-map #'cdr))))
                 ('aliases
                  ;; That's a ht of key:val = alias-from:alias-to
                  ;; aliases-ht holds cons-cells as values, and
                  ;; ‘orgreadme-fy-range-lookup’ makes that an alist
                  (setq funs-to-ht (->> (orgreadme-fy-range-lookup
                                         key head-rng-ht aliases-ht)
                                        h<-alist)
                        funs       (h-lkeys funs-to-ht))))

               (when .include-pred
                 (setq funs (--filter (funcall .include-pred it) funs)))
               (when .exclude-pred
                 (setq funs (-difference
                             funs
                             (--filter (funcall .exclude-pred it) funs))))

               ;; These work on each heading (inside ‘h--each’)
               ;; Make table
               (princ hline)
               (dolist (fun funs)
                 (pcase .output-subtype
                   ('functions
                    (let ((1st   (orgreadme-fy-fun->1stline fun))
                          (funli (if .make-links
                                     (format "[[#%s][%s]]" fun fun)
                                   fun)))
                      (mapc #'princ `("| " ,funli " | " ,1st " |"))
                      (when .signatures-column
                        (princ (->> (orgreadme-fy-fun->signature fun)
                                    read  (cons 'fn)  (format " %s |"))))))
                   ('aliases
                    (let ((to (h-get funs-to-ht fun)))
                      (mapc #'princ `("| " ,fun " | " ,to " |")))))
                 (terpri)))

             ;; These work globally (outside and after ‘h--each’)

             ;; Remove repeated hlines, align.
             (goto-char (point-min))
             (while (search-forward hline nil t)
               (while (looking-at (regexp-opt (list hline)))
                 (replace-match "" nil t)))
             (orgreadme-fy-align-tables-in-buffer))

            ('describe
             (setq examples-ht (orgreadme-fy-examples-ht exmpfile)
                   descs-ht    (orgreadme-fy-descs-ht    libfile .describe-fun)
                   funs-ht     (orgreadme-fy-funs-ht     lines-ht excl-list))

             (h--each headcode-ht
               (setq heading (orgreadme-fy-heading-elisp->org value)
                     level   (->> heading  (s-split " ")  car  length)
                     descs   (orgreadme-fy-range-lookup key
                                                        head-rng-ht descs-ht)
                     funs    (->> (orgreadme-fy-range-lookup
                                   key head-rng-ht funs-ht)
                                  (-map #'cdr)))
               (when .include-pred
                 (setq funs (--filter (funcall .include-pred it) funs)))
               (when .exclude-pred
                 (setq funs (-difference
                             funs
                             (--filter (funcall .exclude-pred it) funs))))

               ;; These work on each heading (inside ‘h--each’)

               ;; Heading proper
               (princ heading)  (terpri)

               ;; Heading description
               (dolist (desc descs)
                 ;; Add an empty line before each description — unless you
                 ;; chose tight spacing, in which case it'd look a bit odd.
                 (when (/= 0 .inter-heading-spacing)
                   (terpri))
                 (princ desc)  (terpri))

               (dotimes (_i .inter-heading-spacing)
                 (terpri))

               ;; Functions' signature, docstring, examples
               (dolist (fun funs)
                 (let ((src-block (orgreadme-fy-fun->org-src-block
                                   fun examples-ht))
                       signature  1stline  middledoc  asterisks)
                   (if (and .only-with-examples
                            (s-blank? src-block))
                       (ignore)
                     (setq signature (orgreadme-fy-fun->signature fun)
                           1stline   (orgreadme-fy-fun->1stline   fun)
                           middledoc (orgreadme-fy-fun->middledoc fun)
                           asterisks (s-repeat (1+ level) "*"))
                     (princ asterisks) (princ " ") (princ fun) (princ " ")
                     (princ "=") (princ signature) (princ "=") (terpri)

                     ;; Custom IDs
                     (princ ":PROPERTIES:\n:CUSTOM_ID:  ") (princ fun)
                     (princ "\n:END:\n")

                     (unless (s-blank? 1stline)
                       ;; Add an empty line after function's headline — unless
                       ;; you chose tight spacing, in which case it'd look a
                       ;; bit odd.
                       (when (/= 0 .inter-heading-spacing)
                         (terpri))
                       (princ 1stline)   (terpri))
                     (unless (s-blank? middledoc)
                       (terpri) (princ middledoc) (terpri))
                     (princ src-block)
                     (dotimes (_i .inter-heading-spacing)
                       (terpri))))))

             ;; These work globally (outside and after ‘h--each’)

             ;; Remove empty headings
             (when .only-non-empty-headings
               (orgreadme-fy-remove-empty-headings))

             ;; Adjust level
             (orgreadme-fy-adjust-root-level .root-level)

             ;; Create links
             (when .make-links
               (orgreadme-fy-make-links-in-buffer)))))

        ;; Get the string, adjusting empty lines at the top.
        (--> (buffer-substring-no-properties (point-min)
                                             (point-max))
             (s-trim it)
             (pcase .output-type
               ('table    (identity it))
               ('describe (s-prepend (s-repeat .inter-heading-spacing
                                               "\n")
                                     it))))))))

;;;###autoload
(defun orgreadme-fy-libfile->orgbuf
    (libfile &optional ops exmpfile excl-list)
  "Paste result of ‘orgreadme-fy-libfile->orgstr’ in an org buffer.
This way you can visualize the results of the insertion files that
you can generate with ‘orgreadme-fy-libfile->orgstr’.

LIBFILE is a library file.

For details about OPS, EXMPFILE, EXCL-LIST, see ‘orgreadme-fy-libfile->orgstr’."
  (let ((buffer (get-buffer-create "*orgreadme-fy results*")))
    (when (pop-to-buffer buffer)
      (erase-buffer)
      (ignore-errors (org-mode))
      (toggle-truncate-lines 1)
      (save-excursion
        (insert (orgreadme-fy-libfile->orgstr
                 libfile  ops  exmpfile  excl-list))))))

;;;;; Generate hash tables

(orgreadme-fy-describe
  "Functions that create hash tables using your library or examples file.")

(defun orgreadme-fy-lines-ht (file)
  "Given a FILE, create hash table with all its lines.
Keys are 0-started line numbers. Values are line contents as string."
  (-> file  f-read  h<-lines))

(defun orgreadme-fy-headings-ht (lines-ht)
  "Given a LINES-HT, return a ht with only lines of elisp headings.
Headings match this regex \"^;;;;* \"."
  (h--sel (s-match "^;;;;* " value)
          lines-ht))

(defun orgreadme-fy-headings-ranges-ht (headings-ht &optional file)
  "Return ht with the same keys, and values being 1- next key.
This is the range this heading, stored in HEADINGS-HT, covers.
Useful for lookup of descriptions and functions, since if their
line numbers fall inside this range they are under this heading.

If optional argument FILE is given, use its number of lines as the
limit for last range. Otherwise use 1000000."
  (let* ((keys-hd (h-lkeys headings-ht))
         (vals-hd (-snoc (-map #'1- (cdr keys-hd))
                         (if file
                             (with-temp-buffer
                               (insert-file-contents file)
                               (goto-char (point-max))
                               (line-number-at-pos))
                           1000000))))
    ;; Just a giant number ^ beyond the num lines of libfile.
    ;; This simplifies dealing with the last heading case.
    (h-zip-lists keys-hd vals-hd)))

(defun orgreadme-fy-descs-ht (libfile &optional describe-fun)
  "Given a LIBFILE, return a ht with ‘orgreadme-fy-describe’ strings.

The keys of the table will be the 0-started line-numbers where
calls to that macro are found in the LIBFILE, and the associated
values will be the strings passed to them.

In other words, this function recovers the strings from all calls to
‘orgreadme-fy-describe’ and their position in the file.

DESCRIBE-FUN is the name of the describe function used. It could
happen that LIBFILE used the macro but renamed it (for example, to
its same namespace), so this option allow for looking up different
names. If nil, it defaults to ‘orgreadme-fy-describe’.

DESCRIBE-FUN can be passed as string or symbol, both are ok. So if
your library is named foo and you decided to copy the
‘orgreadme-fy-describe’ macro into it and rename it to
foo-describe, you could pass this argument as either
#'foo-describe, 'foo-describe or \"foo-describe\".

The application of ‘1-’ to line numbers happens because
‘h<-lines’ (which see), used by ‘orgreadme-fy-lines-ht’, assigns an
index of 0 to the first line read, and we want the keys of the
generated hash tables to be comparable and refer to the same line
positions."
  (unless describe-fun
    (setq describe-fun #'orgreadme-fy-describe))
  (let ((res (h-new))
        ;; Q: Is there a better way than eval to pass a variable to rx?
        ;; A: Apparently these are equivalent:
        ;;   (eval `(rx (: bol.....   <=>   (rx-form `(: bol.....
        (rx  (eval `(rx (: bol (* blank) "("
                           (| ,(format "%s" describe-fun))
                           (+ (any " \t\n")))))))
    (with-temp-buffer
      (insert-file-contents libfile)
      (with-syntax-table emacs-lisp-mode-syntax-table
        (while (re-search-forward rx nil t)
          (h-put! res
                  (1- (line-number-at-pos))
                  (if (looking-at "\"")
                      (read (buffer-substring-no-properties
                             (point) (progn
                                       (forward-sexp)
                                       (point))))
                    (error
                     "‘orgreadme-fy-descs-ht’: %s %s"
                     describe-fun "not followed by string"))))
        res))))

(defun orgreadme-fy-aliases-ht (libfile)
  "Given a LIBFILE, return a ht with from-to aliases pairs.
The keys of the table will be the 0-started line-numbers where
calls to ‘defalias’ are found in the LIBFILE."
  (let ((result (h-new)))
    (with-temp-buffer
      (insert-file-contents libfile)
      (with-syntax-table emacs-lisp-mode-syntax-table
        (while (re-search-forward (rx (: bol (* blank) ?\(
                                         (| "defalias") symbol-end
                                         (+ (in " \t"))
                                         (? "#") (? "'")
                                         (group (* (| (syntax word)
                                                      (syntax symbol)
                                                      (: ?\\ nonl))))
                                         (+ (in " \t"))
                                         (? "#") (? "'")
                                         (group (* (| (syntax word)
                                                      (syntax symbol)
                                                      (: ?\\ nonl))))))
                                  nil t)
          (h-put! result
                  (1- (line-number-at-pos))
                  (cons (match-string 1) (match-string 2))))
        result))))

(defun orgreadme-fy-funs-ht (lines-ht &optional excl-list)
  "Given a LINES-HT, return a ht with only lines of top‑level defs.
Values are cons of deftype and callable (that is, the functions and
macro symbols passed to the deftype). For example, this could become:

#+begin_src emacs-lisp
   '(\"defun\" . \"orgreadme-fy-funs-ht\")
#+end_src

EXCL-LIST is a list of callables to exclude besides those of
‘orgreadme-fy-top-callables-exclusions-list-default’ and
‘orgreadme-fy-top-callables-exclusions-list-user’."
  (->> lines-ht
       (h--sel (s-starts-with? "(" value))
       (h--rej (member (->> value
                            (s-chop-prefix "(")
                            (s-replace-regexp " .*" "")
                            intern)
                       (-concat
                        excl-list
                        orgreadme-fy-top-callables-exclusions-list-user
                        orgreadme-fy-top-callables-exclusions-list-default)))
       (h--hmap key (->> value
                         (s-chop-prefix "(")
                         (s-split " ")
                         (-take 2)
                         (apply #'cons)))))

(defun orgreadme-fy-examples-ht (exmpfile)
  "Given an EXMPFILE, return a ht with ‘exemplify-ert’ sexp string.
Function name is what comes after \"(exemplify-ert \". This will be
the key.

The value will be the whole sexp as string. No change in formatting
happens: treated as string, not sexp — so it preserves indentations
and alignments from your examples file."
  (let ((result (h-new)))
    (if (not (f-exists? exmpfile))
        result
      (with-temp-buffer
        (insert-file-contents exmpfile)
        (with-syntax-table emacs-lisp-mode-syntax-table
          (while (re-search-forward
                  (rx (: bol (* blank) "(" (| "exemplify-ert")
                         (+ (any " \t\n"))
                         (group (+ (not (any " \t\n"))))))
                  nil t)
            (beginning-of-line)
            (h-put! result
                    (match-string 1)
                    (buffer-substring-no-properties (point)
                                                    (progn
                                                      (forward-sexp)
                                                      (point)))))
          result)))))

(defun orgreadme-fy-range-lookup (curkey range-ht some-ht)
  "Return values that fall within desirable range.
Return a list of values whose keys fall in the range between CURKEY
and its lookup on RANGE-HT for SOME-HT."
  (->> some-ht
       (h--sel (and (>= key curkey)
                    (<= key (h-get range-ht curkey))))
       h-lvalues))

;;;;; Generate org pieces

(orgreadme-fy-describe
  "Functions that generate org-mode strings, such as org headings or org
blocks from your examples.")

(defun orgreadme-fy-fun->org-src-block (fun examples-ht)
  "Given FUN and EXAMPLES-HT, return org src block as string.
FUN is passed as a string.
The first line and the closing parenthesis of the exemplify-ert sexp
are replaced by the block's beg and end."
  (if-let ((exemplify-ert-str (h-get examples-ht fun)))
      (->> exemplify-ert-str
           (s-replace-regexp "\\`.*\n+"
                             (concat "\n"
                                     "#+name: examples-" fun "\n"
                                     "#+begin_src emacs-lisp "
                                     ":exports code :eval no\n"))
           ;; It seems that the :exports etc params here ^ are lost when
           ;; exported to README.org — so we'll post-process it as well.
           (s-replace-regexp "\n*)\\'"
                             "\n#+end_src\n"))
    ""))

(defun orgreadme-fy-heading-elisp->org (str)
  "Convert an Elisp heading string STR into an org heading."
  (--> str
       (s-replace-regexp "^;;" "" it)
       (s-split " " it)
       (s-join  " " (cons (s-replace ";" "*" (car it))
                          (cdr it)))))

;;;;; Generate parts of functions' documentation

(orgreadme-fy-describe
  "Functions that generate parts of a function's documentation, such as their
signature, first line, and rest of its description.")

(defun orgreadme-fy-fun->documentation (fun)
  "Given FUN, return its documentation."
  (let ((text-quoting-style 'grave))
    (if-let ((doc (with-demoted-errors "Error: %S"
                    (documentation
                     (orgreadme-fy--obj-sym-str-or-error fun) t))))
        doc
      "")))

(defun orgreadme-fy-fun->docstring (fun)
  "Given FUN, return its docstring, trimmed."
  (if-let ((doc (orgreadme-fy-fun->documentation fun)))
      (->> doc  (s-replace-regexp "\n+(fn.*\\'" "")  s-trim)
    ""))

(defun orgreadme-fy-fun->1stline (fun)
  "Given FUN, return first line of its docstring."
  (->> (orgreadme-fy-fun->documentation fun)
       s-lines  car))

(defun orgreadme-fy-fun->middledoc (fun)
  "Given FUN, return the middle of its docstring, trimmed."
  (->> (orgreadme-fy-fun->docstring fun)
       s-lines  cdr  (s-join "\n")  s-trim-left))

(defun orgreadme-fy-fun->signature (fun)
  "Given FUN, return its signature.
If the docstring has (fn ...) usage, use that.
Otherwise, use the one found in ‘symbol-function’."
  (-if-let* ((doc   (orgreadme-fy-fun->documentation fun))
             (match (s-match "(fn.*\\'" doc)))
      (->> match  car  downcase  read  cdr  (format "%s"))
    (-if-let* ((sig (orgreadme-fy-fun->signature-from-symbol-function fun))
               (out (format "%s" sig)))
        (pcase out
          ("0" "()")
          (_   out))
      "()")))

(defun orgreadme-fy-fun->signature-from-symbol-function (fun)
  "Given FUN, return signature as it shows in ‘symbol-function’.
So if the docstring has (fn ...) usage, don't use it."
  (let ((foo (symbol-function (h-as-symbol fun))))
    ;; macro
    (and (eq 'cons  (type-of foo))
         (eq 'macro (car foo))
         (setq foo  (cdr foo)))
    ;; function
    (pcase (type-of foo)
      ;; byte-compiled
      ('compiled-function (aref foo 0))
      ;; regular
      ('cons              (cadr foo)))))

(defun orgreadme-fy--obj-sym-str-or-error (obj)
  "If OBJ isn't passed as either string or symbol, signal error.
Otherwise return OBJ as symbol."
  (cond ((symbolp obj) obj)
        ((stringp obj) (intern obj))
        (t (user-error "%s is neither symbol nor string" obj))))

;;;;; Generate parts of user options' documentation

(orgreadme-fy-describe
  "Functions that generate parts of a user option's documentation,
such as their first line, and the rest of its description.

These functions were added later and are still unused. For the
moment, automatic documentation of user options is unavailable, so
‘orgreadme-fy-top-callables-exclusions-list-default’ has
‘defcustom’ as member.

User options would need to be treated a bit differently from
functions: no signatures, no ‘exemplify-ert’, different way of
fetching the docstring, shouldn't mix with functions in the 'table
option of :output-type in ‘orgreadme-fy-libfile->orgstr’, etc. So
it seems that including them would add a bit of complexity to the
current code.

Given the above, and given that it seems likely that most people
won't be too interested in documenting their ‘defcustom’ variables
in their README, I haven't implemented it. In any case, with this
future possibility in mind, I leave these functions here.")

(defun orgreadme-fy-cusvar->documentation (cusvar)
  "Given custom variable CUSVAR, return its documentation."
  (setq cusvar (orgreadme-fy--obj-sym-str-or-error cusvar))
  (let ((text-quoting-style 'grave))
    (if (and (boundp cusvar)
             (custom-variable-p cusvar))
        (get cusvar 'variable-documentation)
      "")))

(defun orgreadme-fy-cusvar->docstring (cusvar)
  "Given custom variable CUSVAR, return its docstring, trimmed."
  (s-trim (orgreadme-fy-cusvar->documentation cusvar)))

(defun orgreadme-fy-cusvar->1stline (cusvar)
  "Given custom variable CUSVAR, return 1st line of its docstring."
  (->> (orgreadme-fy-cusvar->documentation cusvar)
       s-lines  car))

(defun orgreadme-fy-cusvar->middledoc (cusvar)
  "Given custom variable CUSVAR, return the middle of its docstring."
  (->> (orgreadme-fy-cusvar->docstring cusvar)
       s-lines  cdr  (s-join "\n")  s-trim-left))

(defun orgreadme-fy-cusvar->signature (cusvar)
  "Given custom variable CUSVAR, return an empty string.
Unlike functions, there are no signatures."
  (ignore cusvar)
  "")

;;;;; Buffer replacements and adjustments

(orgreadme-fy-describe
  "Functions that make replacements and adjustments in the current buffer
Used mostly for post-processing generated org files.")

;;;;;; README.org post-processing

(defun orgreadme-fy-post-process-readme-org ()
  "Post-process current buffer, assumed to be README.org."
  (when orgreadme-fy-downcase-properties
    (orgreadme-fy-downcase-properties-in-buffer))
  (orgreadme-fy-restore-params-of-org-src-blocks-in-buffer)
  ;; See function's docstring to see why:
  (orgreadme-fy-make-prop-nil-in-buffer)
  ;; For some reason org-export messes up with the already-aligned tables
  ;; when they have links. It seems that org-export re-aligns them with
  ;; link-visibility on. The easiest way that I've found to fix this is to
  ;; simply visit the file and realign all tables again while keeping link
  ;; visibility off:
  (orgreadme-fy-align-tables-in-buffer))

(defun orgreadme-fy-align-tables-in-buffer ()
  "Align all org tables in current buffer."
  (interactive)
  (ignore-errors (org-mode))
  (when (equal major-mode 'org-mode)
    (progn (add-to-invisibility-spec '(org-link))
           (org-restart-font-lock)
           (setq org-descriptive-links t))
    ;; Alternative to the below:
    ;; (goto-char 3)
    ;; (call-interactively #'org-ctrl-c-ctrl-c)
    (org-table-map-tables (lambda () (org-table-align))
                          t)))

(defun orgreadme-fy-make-prop-nil-in-buffer ()
  "Find #+:options: prop:t in this buffer and change it to nil.
Your readme-template.org should have prop:t so that property drawers
are exported to README.org. They have custom_ids, needed for anchors
and internal linking.

However, we want to turn this off in README.org, or they'll end up
exported to HTML as tiny code blocks having CUSTOM_ID: something."
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (let ((case-fold-search t))
      (when (re-search-forward "^#\\+options: *.*\\(prop:t\\)" nil t 1)
        (replace-match "prop:nil" nil nil nil 1)))))
;; ^ Other ways to fix this? Maybe some way to say in the template itself:
;;   if exporting to org, then prop:t, else prop:nil?

(defun orgreadme-fy-restore-params-of-org-src-blocks-in-buffer ()
  "Find Elisp source blocks and restore its parameters.
They were added by ‘orgreadme-fy-fun->org-src-block’, but lost when
exported — so restore them. While we're on it, downcase them all."
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (let ((case-fold-search t))
      (while (re-search-forward "^#\\+begin_src emacs-lisp.*$" nil t)
        (replace-match "#+begin_src emacs-lisp :exports code :eval no")
        ;; Make casing consistent with the above:
        (forward-line -1)
        (when (looking-at "#\\+NAME:")
          (downcase-region (point) (+ 6 (point))))
        (when (re-search-forward "^#\\+END_SRC" nil t)
          (replace-match "#+end_src" t))))))

(defun orgreadme-fy-downcase-properties-in-buffer ()
  "Downcase ^#+OPTIONS, ^#+AUTHOR and the like in the buffer."
  (interactive)
  (save-excursion
    (goto-char (point-min))
    (while (re-search-forward
            (rx (: bol ?# ?+ (group (| "OPTIONS"       "TOC"
                                       "TITLE"         "AUTHOR"
                                       "DESCRIPTION"   "KEYWORDS"
                                       "LANGUAGE"      "RESULTS"
                                       "BEGIN_EXAMPLE" "END_EXAMPLE"
                                       "BEGIN_QUOTE"   "END_QUOTE"
                                       "BEGIN_SRC"     "END_SRC"))
                   ?:))
            nil t)
      (replace-match (downcase (match-string 1)) t nil nil 1))))

;;;;;; libfile->orgstr generation post-processing

(defun orgreadme-fy-remove-empty-headings ()
  "Remove empty headings in buffer."
  (interactive)
  (let ((do-again t)
        count)
    ;; It may be nested with no contents at many levels, so we redo until
    ;; there's no more empty node.
    (while do-again
      (goto-char (point-max))
      (setq count 0)
      (while (re-search-backward org-outline-regexp-bol nil t)
        (--> (cadr (org-element-headline-parser (point-max)))
             (unless (plist-get it :contents-begin)
               (orgreadme-fy-delete-subtree)
               (1+ count))))
      (when (= count 0)
        (setq do-again nil)))))

(defun orgreadme-fy-delete-subtree ()
  "Delete subtree at point."
  (interactive)
  (atomic-change-group
    (when (org-mark-subtree)
      (delete-region (region-beginning) (region-end)))))

(defun orgreadme-fy-adjust-root-level (root-level)
  "Adjust to ROOT-LEVEL the root level of subtrees in buffer.
Current root level is assumed to be 2."
  (interactive)
  (cond ((or (not root-level)
             (not (natnump root-level))
             (= 2 root-level)
             (= 0 root-level))
         (ignore))
        ((= root-level 1)
         (orgreadme-fy-promote-all-subtrees-in-buffer 1))
        (t
         (goto-char (point-min))
         (orgreadme-fy-demote-all-subtrees-in-buffer (- root-level 2)))))

(defun orgreadme-fy-promote-all-subtrees-in-buffer (&optional n)
  "Promote all subtrees in buffer by N levels.
If nil, N defaults to 1."
  (interactive)
  (goto-char (point-min))
  (while (not (eobp))
    (when (org-at-heading-p)
      (delete-char (or n 1)))
    (forward-line)))

(defun orgreadme-fy-demote-all-subtrees-in-buffer (&optional n)
  "Demote all subtrees in buffer by N levels.
If nil, N defaults to 1."
  (interactive)
  (goto-char (point-min))
  (while (not (eobp))
    (when (org-at-heading-p)
      (insert (s-repeat (or n 1) "*")))
    (forward-line)))

(defun orgreadme-fy-make-links-in-buffer ()
  "Replace `'- and ‘’-wrapped links with org links to anchors.
Only make links if target anchors actually exist. Otherwise, replace the quotes
with equal signs to make it monospace.

Also replace Info links."
  (interactive)
  ;; Info
  (goto-char (point-min))
  (while (re-search-forward
          "Info anchor [‘`](\\([^ ]+\\)) *\\([^’']+\\)[’']"
          nil t)
    (let* ((m1 (match-string 1))
           (m2 (match-string 2))
           (ma (format "info:%s#%s" m1
                       (s-replace " " "%20" m2)))
           (mb (format "(%s) %s" m1 m2)))
      (replace-match (format "[[%s][%s]]" ma mb))))

  ;; Regular
  (goto-char (point-min))
  (let ((cid-ht (orgreadme-fy-fetch-custom-ids-in-buffer))
        m)
    (while (re-search-forward
            "[‘`]\\([^’' ]+\\)[’']" nil t)
      (setq m (match-string 1))
      (if (h-get cid-ht m)
          (replace-match (format "[[#%s][%s]]" m m))
        (replace-match (format "=%s=" m))))))

(defun orgreadme-fy-fetch-custom-ids-in-buffer ()
  "Make hash-table-as-set of all custom-id properties in buffer."
  (interactive)
  (let ((cid-ht (h-new)))
    (goto-char (point-min))
    (org-map-region
     ;; (lambda () (h-mix! cid-ht
     ;;               (h-as-set<-lines
     ;;                (org-entry-get nil "custom_id"))))
     ;; The below is the same but more straightforward:
     (lambda () (h-put! cid-ht (org-entry-get nil "custom_id") t))
     (point-min) (point-max))
    ;; remove nil key if it happened and return the table
    (h-rem cid-ht nil)))

;;;;; Accessing READMEs
;;;;;; Quick access to a library's README

(orgreadme-fy-describe
  "Commands to quickly access a library's README.")

;;;###autoload
(defun orgreadme-fy-see-library-readme (&optional libname)
  "Open library LIBNAME's README.org file.
Load LIBNAME, if not yet loaded, then search for README.org in the
directory from which it has been loaded.

If not found, look for README.md, README.markdown, README.rst,
README.txt, and README. The first one found, if any, is opened
read-only.

If called interactively, library name will be asked."
  (interactive)
  (unless libname
    (setq libname (completing-read "Library name: "
                                   (orgreadme-fy-list-loaded-libraries)
                                   nil t)))
  (--> (orgreadme-fy-locate-library-readme libname)
       (if (not it)
           (message "Couldn't find a README file for %s" libname)
         (let ((pr (make-progress-reporter
                    (format "Opening %s ... "
                            (abbreviate-file-name it)))))
           (find-file-read-only it)
           (progress-reporter-done pr)))))

(defun orgreadme-fy-locate-library-readme (libname)
  "Locate library LIBNAME's README file.
Load LIBNAME, if not yet loaded, then search for README.org in the
directory from which it has been loaded.

If not found, look for README.md, README.markdown, README.rst,
README.txt, and README. Return the filename if found, nil
otherwise."
  (--> (orgreadme-fy-libname->libfile libname)
       (expand-file-name "README" (file-name-directory it))
       (let* ((exts '(".org" ".md" ".markdown" ".rst" ".txt" ""))
              (all  (-map (lambda (ext) (format "%s%s" it ext)) exts)))
         (car (-filter #'file-exists-p all)))))


(defun orgreadme-fy-list-loaded-libraries ()
  "List all loaded libraries."
  (let ((libs (delq nil (-map #'car load-history))))
    (nconc (delq nil
                 (-map
                  (lambda (l)
                    (setq l (file-name-nondirectory l))
                    (while
                        (not
                         (equal (setq l (file-name-sans-extension l))
                                l)))
                    l)
                  libs))
           libs)))

(defun orgreadme-fy-libname->libfile (libname)
  "Given LIBNAME, load library and return filename it loaded from."
  (require (if (symbolp libname)
               libname
             (intern libname)))
  (--> load-history
       (-map #'car it)
       (car (-filter (lambda (lib)
                       (when (string-match
                              (format "/%s.el[cn]*$" libname)
                              lib)
                         lib))
                     it))))

;;;;;; See OrgReadme-Fy's README

(orgreadme-fy-describe
  "A command to quickly open the README.org of this very library.")

;;;###autoload
(defun orgreadme-fy-see-readme (&optional heading narrow)
  "Open orgreadme-fy's README.org file.
Search for the file in orgreadme-fy.el's directory.

If found, open it read-only.

If optional argument HEADING is passed, try to navigate to the
heading after opening it. HEADING should be a string.

If optional argument NARROW is non-nil, narrow to that heading.
This argument has no effect if HEADING is nil or not found.

Examples:
  (orgreadme-fy-see-readme \"News\" t)
  (orgreadme-fy-see-readme \"Installation\")"
  (interactive)
  (let ((readme orgreadme-fy--readme-org))
    (if (file-exists-p readme)
        (let ((pr (make-progress-reporter
                   (format "Opening %s ... "
                           (abbreviate-file-name readme)))))
          (find-file-read-only readme)
          (when heading
            (orgreadme-fy--goto-org-heading heading narrow))
          (progress-reporter-done pr))
      (message "Couldn't find %s's README.org" orgreadme-fy--name))))

(defun orgreadme-fy--goto-org-heading (heading &optional narrow)
  "Navigate to org HEADING and optionally NARROW to it."
  (let* ((hrx (format "^[*]+ %s" heading))
         (pos (save-match-data
                (save-excursion
                  (save-restriction
                    (widen)
                    (goto-char (point-max))
                    (re-search-backward hrx nil t 1))))))
    (when pos
      (widen)
      (goto-char pos)
      (if (and narrow (fboundp 'org-narrow-to-subtree))
          (org-narrow-to-subtree)
        (recenter-top-bottom 1))
      (when (fboundp 'outline-show-subtree)
        (outline-show-subtree)))))

;;;;;; See OrgReadme-Fy's News

;;;###autoload
(defun orgreadme-fy-see-news ()
  "See the News in orgreadme-fy's README.org file."
  (interactive)
  (orgreadme-fy-see-readme "News" 'narrow)
  (let ((cmds '(outline-hide-subtree
                outline-show-children
                outline-next-heading
                outline-show-subtree)))
    (and (fboundp (nth 0 cmds))
         (fboundp (nth 1 cmds))
         (fboundp (nth 2 cmds))
         (fboundp (nth 3 cmds))
         (mapc #'funcall cmds))))

;;;; Wrapping up

(provide 'orgreadme-fy)

;; Local Variables:
;; coding:                     utf-8
;; indent-tabs-mode:           nil
;; sentence-end-double-space:  nil
;; outline-regexp:             ";;;;* "
;; End:

;;; orgreadme-fy.el ends here