[editor-hints-devel] My thoughts about markup and docstrings

[Robert Goldman]

David Lichteblau wrote:
> Hi,
> 
> Quoting Robert Goldman (rpgoldman at sift.info):
>> I am very impressed by this design.  Is there a simple version of these
>> docstrings that is visible through the existing documentation interface?
>>  E.g., does parse-docstrings strip markup and then (SETF DOCUMENTATION)?
> 
> good question.
> 
> So far, I'm inclined to say "no".
> 
> For one thing, some people would probably prefer to keep traditional
> docstrings and this new kind of documentation entirely separate (like
> Tobias, if I understand correctly).
> 
> Also, one would want DOCUMENTATION to be available right after loading a
> system.  But to parse docstrings, you would first have to load the
> `parse-docstrings' system and its dependencies.  Do we really want to
> force every author to depend on `parse-docstrings', in the ASDF
> :DEPENDS-ON meaning of dependency?
> 
> 
> Instead, I am hoping for a Slime contrib that would make the new
> documentation available easily through Emacs.  This Slime contrib would
> have to use `parse-docstrings', but I'm hoping that this kind of
> dependency would be easier to accept for users.

As someone who uses ELI more than SLIME, still, I would prefer to see a
technique that extended the existing documentation facility, rather than
supplanting it and dictating a particular development environment.  I
even work with people who use vim, and there are also Cusp, and Allegro
and LispWorks' IDEs.

In keeping with your notion of choice above all, I don't see any reason
one would need to forbid my proposed approach above --- instead,
couldn't one simply make that a configuration option?

That said, where would such configuration options live?  Would they be
attached to an ASDF system (hard to see off hand how this would work),
to a package that is documented (easier to implement, but does the
policy of the documented symbol or that of *package* dominate?) or to an
installation of parse-docstrings (probably not a good idea, since one
might use multiple libraries with different configuration philosophies).


I suspect all of these remarks are symptoms of an underlying discomfort
with the concept.  I'm uncomfortable with the idea of having
documentation that is compiled separately, in some kind of batch mode,
rather than being compiled incrementally together with the code.  Of
course, *manuals* can be compiled separately, but it seems like this
approach sacrifices the interactive aspect of the lisp environment in
order to avoid adding dependencies (per your earlier email).

Best,
R