TODO

							     -*- outline -*-

* Copyright (C) 2010-2013 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.

** Labels
Node and anchor names are restricted (Cf. section 4.4 of the Texinfo manual)
and I should respect that. Texinfo 6.1 seems to issue warnings now.

** DEFPACKAGE wrappers
Declt scans calls to DEFPACKAGE, which won't work when libraries provide
wrappers. This happens with UIOP for example. Cf. Robert's mail.

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

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

** 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
Lift the 80 columns formatting assumption, for instance by providing an
additional keyword to DECLT. In the future, 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
Because of the way we collect our definitions (system -> packages -> symbols),
we're currently unable to document foreign definitions, that is, provided in a
file of ours but belonging to a foreign package.

In general, it's not clear whether we want to do that. In some specific cases
however, it does makes sense; when the foreign definition has something to do
with the current system for instance. In those cases, we are in fact usually
able to get a handle to the definition in question.  For instance, method
definitions for foreign generic functions (e.g. MOP extensions such as
VALIDATE-SUPERCLASS) may be retreived from classes direct methods.

Even then, the next problem is where to advertise those definitions. They are
neither internal, nor exported. Maybe we could add a section for foreign
definitions.

Other definitions potentially concerned:
-  setf expanders for which the access-fn is foreign, but the
update-fn is ours. I currently don't know how to retrieve those.

** Floating setf expanders
Setf expanders are documented when the access-fn is a (generic) function or
macro. If a setf expander is defined on a symbol that has no such definition
(which is possible), it will not currently appear anywhere. What should we do?
Probably create toplevel setf expander definitions.

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