TODO

							     -*- outline -*-

* Copyright (C) 2010-2013, 2015-2017, 2022 Didier Verna

This file is part of Declt.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.

** Merging
See about standalone methods merging.

** Packages and symbols
- See what to do about shadowings, imports etc.

** Docstrings
In theory, it is possible for a symbol/doc-type and a corresponding object to
have different docstrings attached (one would be manually overridden after the
original assignment). We could check that and advertise both.

** String downcasing
Abstract it so that we may provide an option for case behavior.

** Lisp objects formatting
There are many places where we'd prefer ~S (e.g. to preserve colons in front
of keywords), but that would break on unreadable objects. A solution would be
to "ignore-errors" on ~S, and fall back to ~A instead. Make this work along
with format-tables.

** modify macros
Is there anything specific to do?

** Backend
Clean up the code so that Texinfo becomes a backend with a clean
interface. This way, we could envision adding other backends.

There are several obstacles to this:
1. currently, the constructed node structure contains a mix of things to be
rendered (such as the nodes titles and sections) and this already rendered as
strings (definitions in :before-menu-contents). We would need to completely
separate the structure from its rendering so that the structure itself can be
passed along to various backends. That shouldn't be too hard tho. THe node
structure can be augmented by additional slots for, e.g., a list of
definitions to render.

2. Part of the cleanup would also be to decide on a good coding style for
fresh lines (FRESH-LINE, TERPRI, ~& and ~%).

3. Another problem that will happen is that the introduction and conclusion
material are currently allowed to contain Texinfo directives (contrary to all
other user-provided contents). This will be difficult to abstract if we
generalize the backend notion.

** Strings formatting
Provide markup support through backends (Cf. MarCL). We could already have at
least the current DWIM one, plus a raw/verbatim one.

** Pathnames
If the system definition pathname or definition sources contain funky stuff
like ./, ../ or even are symlinks, the cross-references will most probably
break. We need to work on canonical pathnames.

** Foreign definitions
Even with the latest improvements in foreign definitions handling, there are
still some cases that could escape us. For example, a short form foreign setf
expander for which the update-fn is ours. The only general solution for that
kind of problem is for the finalization phase to scan /all/ symbols in the
Lisp image again, instead of only traversing definitions. That would be
introspection-level #3 (performance cost very high for probably very little
gain).

** Anchors
This is a note to myself rather than a TODO entry.
With the simplification of anchor names in v4 (namely, going numerical instead
of human-readable), it will become more complicated to cross-reference
different manual entries, if we ever go down that road.

** Call graphs
Cf.
sb-introspect:who-calls
sb-introspect:find-function-callees

** Source files
Currently, we can link to source files on the local machine, which is not
advisable for web installation of the reference manuals. However, if the
library provides a source control address, we could link to files in a public
repo !

** Profiling
It may be nice to do it at some point. For example, I wonder if the abundance
of STRING-CAPITALIZE on category names is costly, in which case we could
change the protocol to provide both versions as premade compile-time strings.