[plt-scheme] Some PLT environment issues

Hi,

Concerning the docs, I've just recently made such a tool to easily create
documentation from comments :
http://planet.plt-scheme.org/display.ss?package=lazy-doc.plt&owner=orseau

You can check the docs online.
However, there is one remaining bug that prevents the package from being
correctly installed but nobody seems to be able to help me...
(see the thread "Error when installing package : ...")
So I do not recommend to install the package right now, as it would screw
your local documentation (removing the package would safely reverse the
process though).

Apart from this, it should work fine and I think it would partly answer your
first question.

There is also in-line scribble documenting:
http://docs.plt-scheme.org/scribble/srcdoc.html

And I agree with you, something that gives information about a function more
quickly than F1 and HTML in a browser would be great.
Why not a function (help some-function) that renders docs in the interaction
window ?

Best regards,
Laurent



On Tue, Oct 27, 2009 at 09:59, Scott McLoughlin <scott at adrenaline.com>wrote:

> I'm fairly new to PLT, so I may be unaware of some features that i
> think are sorely lacking. As well, this is in part just a late night dump
> of an insomniac :-)
>
>
> 1) First, while Scribble is a very cool virtual troff/TeX replacement,
> it's just *WAY* too complicated for documenting code quickly during the
> process of code writing. A more appropriate tool, IMHO, would simply
> embed docs in comments (or some other s-expr, docstring format, etc.).
> It would impose some minor structure via section tags, such as date,
> author, function parameters (checked by the documentation processor
> of course), type information where appropriate(including types from
> a fully integrated typed-scheme)  etc.
>
> The default doc processor should be a simple menu item that just
> generates HTML for a collection of source files, including hyper links
> where appropriate (who calls, struct use to struct definition, and
> so on). Ideally the docs would feature an index, search, etc. in
> the generated HTML docs.
>
> And sure, there may be some more involved doc generation options
> provided by DrScheme as well - options for printed docs, PDF output
> and what not. But aside from the basic "Update Docs" menu item.
>
> 2) Regarding the "collection of files" refered to above, DrScheme
> would benefit greatly from a simple default Project structure concept.
> A simple directory hierarchy of files, included libraries, perhaps sub
> projects, maybe sharing - pretty much standard fare for many IDE's that
> have been out there for years now.  Regarding HTML doc generations, it's
> the project files (or a subdir or even sub project) that is the
> "collection of files" unit of HTML documentation.
>
> 3) Spawning the browser to view the docs is fine, but really, just as
> easy these days  is providing an HTML tab for viewing the hyperlinked
> documentation. This avoids repeatedly switching between apps to compare
> source and documentation, especially if DrScheme would provide both
> horizontal and vertical window splitting as Emacs does.  Ideally, the
> source editor would be modified to hyperlink source forms directly to their
> associated documentation, presumably by an unobtrusive right mouse button
> context menu item.  Request for such a source item doc could easily
> verify the up-to-date status of the HTML docs and bring them back up
> to date as necessary (CPUs and Disks are blessedly fast these days).
>
>
> 4) Dr Scheme needs clean, simple revision control integration. I've been
> on quite an illness driven coding hiatus, but not too many years ago, emacs
> and cvs went together like rum and coke, and setting up a CVS server was
> only
> a little harder than falling off a log.  Subversion seems the new CVS if
> I'm
> reading the lay of the tech land correctly, but ideally, DrScheme should
> support
> a family of the most popular version control systems. The source file tabs
> can
> then show the checkin and even remote modification status, display inline
> diffs,
> generate regular diffs and of course allow resolution of conflicts right
> within
> the editor and so forth.  Basically, on any kind of multi-user project, or
> even
> a  large single user project, including this type of revision control by
> default
> would be a MAJOR productivity enhancement.
>
> 5) Anyway, just some immediate off the cuff observations.
>
> I *REALLY DO* have the greatest admiration for the folks banging on
> DrScheme and
> the whole PLT technology suite, and I (reluctantly) understand that there
> are
> design priorities outside of building a commercial software development
> tool.
>
> I also want to say that the resulting technology to date is nothing short
> of
> amazing and is, so far, my development technology of choice for so many
> different
> and good reasons.
>
> So I hope my critiques are taken in the right spirit.
>
> Night all,
>
> Scott
>
> _________________________________________________
>  For list-related administrative tasks:
>  http://list.cs.brown.edu/mailman/listinfo/plt-scheme
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20091027/aae0f113/attachment.html>