TODO.txt

==========
Need to Do
==========

Most of the things marked with TODO in a comment are need-to-do items.

-----

Better template handling. Right now, there is little debugging information for
templates. If the template itself is badly formed, you get a direct error from
the parser without the usual file name and position. That is easy enough to
clean up. But if the document resulting from the template has errors or
warnings, you get source locations that say nothing more than "automatically
generated". This can be improved to refer to an actual file if the --autogen-dir
switch is used.

-----

Generating DITA and HTML from the internal data structure. This includes
generating indices.

I'm thinking the user won't be able to extensively customize the generated HTML
document. Probably just CSS styles, maybe a logo or common header or footer. We
should offer a couple of different layout styles. For anything more extensive,
the user should generate DITA output and use XSLT or a DITA processing system.

-------

Note API names that do not correspond to topics, such as names imported from
external libraries. If the author attempts to link to such a name, give the link
the API style and turn it into normal text.

Once that is done, we can probably do something smarter with imported and
renamed external APIs.

-------

In DITA, footnotes cannot contain the full selection of division content, so
restrict it. Exhibits cannot contain nested images, at least not if they are
wrapped in a <fig> of their own. Think about how to solve this.


==========
Want to Do
==========

Note direct and indirect libraries required, so developer can make sure those
are available. More important for GD than OD.

------

Tables. The table syntax requires that the code figures out table columns before
tokenizing words -- actual character boundaries matter.

------

Figure out how to turn "--" into an em-dash automatically. This won't interfere
with ASCII lines because an ASCII line needs *three* consecutive characters.

------

Replace topic templates with code-generated markup representation. This will be
faster and provide opportunities to preserve source locations, insert syntax
information, and be absolutely sure of parm-lists.

------

Implement comment block that follow the element to be documented, à la Doxygen's
"//<" comments.

------

Handle spaces in markup better. Sometimes spaces (or lack of spaces) needs to be
preserved. For example, "Footnote [1]." renders as "Footnote<sup>1</sup> ." Note
the extra space. This is done for the special case of quotes, but needs to be
generalized.


============
Bonus Points
============ 

Create some sort of standalone installation that does not need to live in the
source code directory. Some arrangement has to be made for the contents of the
Doctower's defaults directory, though. Typical locations would be:

- "${PREFIX}/share/doctower" on Unix
- "C:\Program Files\Doctower" on Windows
- "/Applications/Doctower.app/Contents/Resources" on Mac OS

------

Figure out how to do something like the abbreviated syntax shown at
http://naturaldocs.org/documenting/walkthrough.html#AbbreviatedSyntax.

--------

Interconnect separate documentation packages, e.g. the Koala package can connect
to the main Dylan package so that references to "<integer>" in Koala link to the
Dylan documentation.

This requires some sort of repository. The user should be able to set this up
wherever he likes; it should be a strictly optional feature. The HTML or DITA
output (or maybe the internal representation saved to a file) will need to have
hooks recognizable and replaceable by the system. To keep the main application
from being overburdened with purposes and options, a separate tool should manage
the user's document collections and interconnections.