#+STARTUP: overview
#+SEQ_TODO: TODO(t@) NEXT(n@) STARTED(s@) WAITING(w@) | DONE(d@) OLD(o@) CANCELLED(c@)
#+TODO: MAYBE(m@) FAILED(f@) LOG(l@) DEFERRED(e@) BUG(b@)
* OPT parse and print markdown once when *format* is :html?
This would involve rewriting everything to emit parse tree fragments or be able to produce html directly. Either way, it is not without cost.
* MAYBE pretty print lambda-lists (including default values)
and values of variables. Unfortunately, there seems to be no way to
use the lisp pretty printer for this because output also includes
markup. We could get the original indentation from the sources.
* MAYBE transcribe: emacs retranscribe should not update if consistent?
This either relies on the global value of
*TRANSCRIBE-CHECK-CONSISTENCY* or it needs to see the
"```cl-transcript (...)" line.
* TODO support external links
This is partially done. CLHS is mostly implemented as an external
link. See EXTERNAL-LOCATIVE-P and co.
* MAYBE link to MOP
* MAYBE consider CommonDoc from the 40ants fork
* MAYBE remove some markup in :PLAIN format?
* MAYBE get variable initforms from source?
Or fall back on this for deficient ARGLISTs. Will be really slow.
* MAYBE add format control character locative?
* MAYBE add loop keyword locative?
* MAYBE move towards literate programming
** MAYBE todo/comment locative?
** add SYMBOL as an alias for dislocated?
** add source locative
That is, link to github, without documenting anything. Useful for code
examples without actually INCLUDEing them.
** reorder source definitions
** autoinclude docstrings
(with-implementation
  (defvar *document-uppercase-is-code* t
    "First line.")
  (defun foo ()
    "Second line.")
  "3rd line with narrative"
  (defvar saf
    "more"))

expands to

(defvar *document-uppercase-is-code* t
  "First line"
  "[foo function][docstring]"
  "3rd line with narrative"
  "more")

(defun foo ()
  "Second line.")

(defvar saf
  "more")
** local functions?
** named one-off local functions?
(defun foo (x)
  ;; Just for the name, really. Maybe control what it can close over?
  (subfoo ()
   ))
* MAYBE add list of dependencies to ASDF system doc
https://github.com/40ants/doc/commit/c3bf89fa88ab70074466aa07358caad159d45008
* BUG (low) method dspec parsing is incorrect
e.g. SB-PCL::MAKE-SPECIALIZER-FORM-USING-CLASS One cannot tell method
qualifiers from specializers in the dspec without actually consulting
the definition.
* MAYBE use SECTION-PACKAGE from "first" enclosing section?
That is, when generating documentation for something that's referenced
by one or more sections. See PAX::SECTIONS-THAT-CONTAIN and
PAX::SORT-BY-PROXIMITY.
* MAYBE autoload documentation when needed?
E.g. for named-readtables, which has its docs in named-readtables/doc.
* BUG (low) C-. history depends on current package
E.g. 'clhs' works in a package where pax used but not elsewhere.

But so does M-.'s history.
* OPT 3bmd parsing performance on large blocks
https://github.com/3b/3bmd/issues/56
* MAYBE when exported by pax, we know the exact definition being exported
Package apropos could take advantage?
* MAYBE mgl-pax-apropos should defer to slime-apropos if pax not loaded?
* MAYBE add TAB completion to M-. prompt
* MAYBE add SPECIAL locative and make variable an alias of it?
* MAYBE support DECLARATION docstrings?
* MAYBE support setf docstring?
* MAYBE better SOURCE addressing for INCLUDE
* MAYBE live browsing: reload page automatically on redefinition
* compare DRef to the Definitions library
Pros of DRef:
- Supports string names (called designators in Definitions). PAX needs
  to distinguish those from symbol-based ones.
- Operations such as ARGLIST (~ DEFINITIONS:ARGUMENTS) can be
  specialized on normal objects for RESOLVEable definitions. In
  Definitions, operations are always specialized on a DEFINITION
  subclass, which can result in unnecessary duplication of the
  hierarchy.
- (LOCATE #'PRINT) is fast, the equivalent DEFINITIONS:WHO-DEFINES is
  very slow. DRef uses this to allow specialization of ARGLIST on
  either object or definition type.
- Can LOCATE a single unresolvable definition (e.g. (DREF 'XXX
  'VARIABLE)). Definitions only has WHO-DEFINES, which needs the
  OBJECT of the definition. Needed by PAX.
- DRef supports Swank buffer source locations when running under
  Slime. Needed by PAX.
- DRef has XREFs, which do not need even the locative type to be
  defined when they are created. Needed by PAX.
- DREF-APROPOS more flexible. Needed by PAX.
- ARGLIST returns the type of arglist.
- DOCSTRING returns the package if available. Needed by PAX.
- The DRef packages can be :USEd without conflicts with CL.
  Definitions shadows CL:SYMBOL, CL:PACKAGE, CL:CLASS, etc.
- DRef supports only 7 Lisps, Definitions 3.
- DRef has an extensive test suite. Definitions has no tests.
- DRef has extensive documentation.

Pros of Definitions:
- Definitions has BIND, (SETF OBJECT), UNBIND, (SETF DOCUMENTATION).
  These can be added to DRef if needed.
* MAYBE transcript: don't treat "debugger invoked on" is treated like output
Well, it's a kind of output, but maybe it would be better for
consistency checking to treat it as a different kind of output. First,
capturing interaction with the debugger needs to be though out though.
* MAYBE DREF-APROPOS: allow :LOCATIVE-TYPES to match subclasses?
* MAYBE generate offline documentation for everything in quicklisp?
Like https://quickref.common-lisp.net/index-per-library.html, but more
useful?
* MAYBE swap the MGL-PAX package name with the PAX nickname
... somehow without breaking existing URLs, which have
MGL-PAX:<LOCATIVE> all over them?
* MAYBE ASDF:SYSTEMs should not be sectionlike
I.e. they shouldn't be implemented with WITH-HEADING but maybe
DOCUMENTING-REFERENCE like everything else.
* print ASDF/SYSTEM:SYSTEM as ASDF:SYSTEM
Maybe. ASDF is a nickname of ASDF/INTERFACE.
