<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta content="text/html;charset=UTF-8" http-equiv="Content-Type"></head><body ><div style='font-size:10pt;font-family:Verdana,Arial,Helvetica,sans-serif;'><div id="message"></div>SeasideDoc may be of use to you here.<br id="br3"><br><br id="br3">http://squeaksource.com/@98wPRO3xoqcWHC8c/NtvPSZ9c<div><br></div><div><br id="br3"><div id="signature"></div><div id="content"><br> ---- On Sat, 21 Mar 2020 17:34:10 -0400 <b> lewis@mail.msen.com </b> wrote ----<br><br><blockquote style="border-left: 1px solid rgb(204, 204, 204); padding-left: 6px; margin-left: 5px;"><div>Hmmm.... good points Christoph.<br><br>I'm sure this must have been done before, but how about a Seaside<br>application with an image keeping itself up-to-date with the trunk<br>update stream, and with Seaside rendering something similar to the<br>"show all comments" browser that Subbu reminded us about?<br><br>I recall an early Seaside demo that implemented Smalltalk browsing,<br>so it might be something similar to that browser but more focused<br>on rendering the documentation (comments) than the code.<br><br>I suppose that in this case, "editing the document" would amount<br>to putting some new or improved comments into trunk.<br><br>I think we already have (or had???) some way to embed href links<br>in Squeak comments, so possibly that would be a way to provide<br>links to more extensive documentation on the swiki. This has not<br>been very useful in the image (once apon a time we had the embedded<br>Whisker browser, but those days are gone). But maybe that sort<br>of linkage might be more useful if comments were being rendered<br>from a Seaside app.<br><br>Something like this might be a nice thing to have running on our<br>Rackspace servers and linked to squeak.org.<br><br>Dave<br><br><br>On Sat, Mar 21, 2020 at 07:11:08PM +0000, Thiede, Christoph wrote:<br>> > Actually, javadoc can do a very nice job of generating documentation if someone has taken the time to write good comments in the first place. Not unlike the situation in Squeak.<br>> <br>> I think I don't like documentation generation. This is a classical scenario of creating a representation that lacks liveness and needs to be kept in sync, making it impossible to edit the generated document, unless the synchronization is implemented as a bidirectional process. Especially in Squeak, we should be very careful to create such derived representations. Ideally, we should also never copy documentation stuff into the Swiki, but implement a hook/special syntax there that allows citing it directly from the Swiki server's image.<br>> <br>> Best,<br>> Christoph<br>> <br>> ________________________________<br>> Von: Squeak-dev <<a href="mailto:squeak-dev-bounces@lists.squeakfoundation.org" target="_blank">squeak-dev-bounces@lists.squeakfoundation.org</a>> im Auftrag von David T. Lewis <<a href="mailto:lewis@mail.msen.com" target="_blank">lewis@mail.msen.com</a>><br>> Gesendet: Samstag, 21. M?rz 2020 20:03:36<br>> An: The general-purpose Squeak developers list<br>> Betreff: Re: [squeak-dev] self error: 'comment only'<br>> <br>> On Sat, Mar 21, 2020 at 11:21:39AM -0700, tim Rowledge wrote:<br>> ><br>> ><br>> > > On 2020-03-17, at 12:56 AM, K K Subbu <<a href="mailto:kksubbu.ml@gmail.com" target="_blank">kksubbu.ml@gmail.com</a>> wrote:<br>> > ><br>> > >><br>> > ><br>> > > It already does - Browser -> Object -> show all comments -> class side<br>> ><br>> > Hunh. Never noticed that before; which is an example of a mix of "long-habit making new stuff almost invisible" and "too long menu disease".<br>> ><br>> <br>> I overlooked this too. Thanks Subbu!<br>> <br>> <br>> > I think it does the wrong thing though; a more consistent approach would be to have the HelpBrowser page with that info installed in the HB that opens when you ask for Help. Removes a then-pointless menu entry and make the HB more useful.<br>> ><br>> > A related issue is the lack of actually useful class comments - and indeed the fact that class comments are a small part of the total need to explanations. If we were to make really thorough use of the HB to document things one might argue that individual class comments would become irrelevant. Certainly the tragically simplistic approach I've seen (I think it was called javadoc?) that simply gathers up every comment and tries to pretend that it makes actual documentation is not one to copy.<br>> ><br>> <br>> Actually, javadoc can do a very nice job of generating documentation<br>> if someone has taken the time to write good comments in the first<br>> place. Not unlike the situation in Squeak.<br>> <br>> Dave<br>> <br>> <br>> > Making good doc and good tools to make that easily available and easy to keep up to date is hard work. I think we have a lot of decent starting points though. We can, for example fetch swiki pages fairly easily, which would be a great thing to improve for major doc items. They can be updated easily by a wide community, which is hopeful. A downside is the requirement to be online, which means we might want to work out a way of having some basic doc held in local space (probably best is the sources file since we usually at least have that) as well. And being better at parsing the content of swiki pages would be nice; or perhaps extending the swiki system to be able to return data in a more digestible form when the requestor is an HB?<br>> ><br>> > tim<br>> > --<br>> > tim Rowledge; <a href="mailto:tim@rowledge.org" target="_blank">tim@rowledge.org</a>; <a href="http://www.rowledge.org/tim" target="_blank">http://www.rowledge.org/tim</a><br>> > <-------- The information went data way --------><br>> ><br>> ><br>> ><br>> <br><br>> <br><br><br></div></blockquote></div></div></div><br></body></html>