This would involve rewriting everything to emit parse tree fragments or be able to produce html directly. Either way, it is not without cost.
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.
This either relies on the global value of TRANSCRIBE-CHECK-CONSISTENCY or it needs to see the ““`cl-transcript (…)” line.
This is partially done. CLHS is mostly implemented as an external link. See EXTERNAL-LOCATIVE-P and co.
Or fall back on this for deficient ARGLISTs. Will be really slow.
That is, link to github, without documenting anything. Useful for code examples without actually INCLUDEing them.
(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”)
(defun foo (x) ;; Just for the name, really. Maybe control what it can close over? (subfoo () ))
https://github.com/40ants/doc/commit/c3bf89fa88ab70074466aa07358caad159d45008
e.g. SB-PCL::MAKE-SPECIALIZER-FORM-USING-CLASS One cannot tell method qualifiers from specializers in the dspec without actually consulting the definition.
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.
E.g. for named-readtables, which has its docs in named-readtables/doc.
E.g. ‘clhs’ works in a package where pax used but not elsewhere.
But so does M-.’s history.
Package apropos could take advantage?
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.
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.
Like https://quickref.common-lisp.net/index-per-library.html, but more useful?
… somehow without breaking existing URLs, which have MGL-PAX:<LOCATIVE> all over them?
I.e. they shouldn’t be implemented with WITH-HEADING but maybe DOCUMENTING-REFERENCE like everything else.
Maybe. ASDF is a nickname of ASDF/INTERFACE.