Documentation options
Locked
123
123
 
|
"tim Rowledge" <[hidden email]> wrote
> That's such a 19th century approach. Why would anyone want to have a > fixed linear view of a mesh entity dynamic system? Is it more the "static" aspect you object to, or the web/hyperlinked interface? In that case one could always have a Seaside-like application provide a documentation interface to a live image. The web interface rocks, for many reasons. e.g. there is no simple in-image browser with a back-button, or multiple tabs. Squeak browsers are not good at this kind of browsing. Sophie |
|
|
In reply to this post by Sophie424
On Thu, 03 Jan 2008 18:14:11 +0100, itsme213 wrote:
> > "Klaus D. Witzel" <[hidden email]> wrote in message > >> some time ago I tried to convince people to make available >> auto-generated, web searchable sourcecode pages from all public Squeak >> repositories > > +1 > > Like this > http://common-lisp.net/project/cl-weblocks/docs/weblocks-package/index.html > sample from a Lisp web framework - it made it so easy to access and > browse > something without having to download, install, and poke around in an IDE. I prefer +open_without_install +poke_around_in_a_Smalltalk_IDE, am a frequent user of the File Contents Browser. Wouldn't change the format of the sourcecode so existing tools can be used. Example: search for class name InstrumentingAssociation on the web, - http://www.google.com/search?q=InstrumentingAssociation+From+Squeak+latest+update Pull the one that looks interesting into Squeak's File Contents Browser (just in case you haven't used it before, the tools opens .cs and .st files from local directories and server directories) and browse it. As usual the tool tells about differences to your running image. /Klaus P.S. I don't compare the above with MC ;-) |
|
|
In reply to this post by Sophie424
On 3-Jan-08, at 10:34 AM, itsme213 wrote: > "tim Rowledge" <[hidden email]> wrote > >> That's such a 19th century approach. Why would anyone want to have a >> fixed linear view of a mesh entity dynamic system? > > Is it more the "static" aspect you object to, Yah - I triggered on printed. Way back ('82-ish) I even printed out the class library source myself. Of course back then I had no machine at home that I could have used for online reading away from work. > or the web/hyperlinked > interface? In that case one could always have a Seaside-like > application > provide a documentation interface to a live image. There is - or at least, was. It was at http://swiki.gsug.org:8888/browser/ but that seems no longer to be there. > > > The web interface rocks, for many reasons. e.g. there is no simple > in-image > browser with a back-button, or multiple tabs. Squeak browsers are > not good > at this kind of browsing. I think there is indeed a browser (diving browser?) that does that but us aging greybeards tend to stick to decade old reflexes. tim -- tim Rowledge; [hidden email]; http://www.rowledge.org/tim Thesaurus: Ancient reptile with a truly extensive vocabulary |
|
|
On Thu, Jan 03, 2008 at 11:19:13AM -0800, tim Rowledge wrote:
> > On 3-Jan-08, at 10:34 AM, itsme213 wrote: > > or the web/hyperlinked interface? In that case one could > > always have a Seaside-like application provide a documentation > > interface to a live image. > > There is - or at least, was. It was at http://swiki.gsug.org:8888/browser/ > but that seems no longer to be there. By golly you're right. Somebody should do something about that. It was a good idea then and it still is. It's a nice courtesy to let folks poke around in a Squeak class library without forcing them to drink the coolaid. Dave |
|
|
On Jan 4, 2008, at 3:39 , David T. Lewis wrote: > On Thu, Jan 03, 2008 at 11:19:13AM -0800, tim Rowledge wrote: >> >> On 3-Jan-08, at 10:34 AM, itsme213 wrote: >>> or the web/hyperlinked interface? In that case one could >>> always have a Seaside-like application provide a documentation >>> interface to a live image. >> >> There is - or at least, was. It was at http://swiki.gsug.org:8888/ >> browser/ >> but that seems no longer to be there. > > By golly you're right. Somebody should do something about that. It > was a good idea then and it still is. It's a nice courtesy to let > folks poke around in a Squeak class library without forcing them > to drink the coolaid. Hehe. This is gone for years. swiki.gsug.org used to run on my desktop machine back at the University of Magdeburg, and indeed allowed you to peek inside the running Swiki server image with an interface similar to a System Browser implemented as HTML frames. I guess someone else did the same for newer HTTP server frameworks, in any case it shouldn't take more than a few minutes to implement ... Nowadays http://swiki.gsug.org/ is a SmallWiki installation at http:// www.seasidehosting.st/ and does not have a browser module anymore. - Bert - |
|
|
In reply to this post by Igor Stasenko
On Jan 2, 2008 7:05 PM, Igor Stasenko <[hidden email]> wrote:
> On 02/01/2008, Randal L. Schwartz <[hidden email]> wrote: > > >>>>> "Ralph" == Ralph Johnson <[hidden email]> writes: > > > > Ralph> People talk about language changes all the time, but they rarely > > Ralph> happen. If you want to change Squeak, it is easier to do it by > > Ralph> changing tools or libraries, not by changing the language. > > > > Agreed. > > > > As I said a few months ago > > in http://www.nabble.com/forum/ViewPost.jtp?post=12469219&framed=y > > > > I just don't like version creep in languages. Smalltalk has remained > > relatively stable for nearly 3 decades. Anything to disrupt that has got to > > meet a pretty high standard for me personally. > > > > As i suspected, this discussion is going to nowhere, because of > conservative people like you. > There is no point to prove anything, if people simply don't want to > change anything. > If you don't want to change, don't want to move on, then squeak's > destiny is to vanish and be forgotten when last living mammoth will > die. > > Do we need a better tools/ways for delivering content(documentation) > to developers? Yes we are! > So, please, can you, instead of rejecting proposals, which are > incompetent or which can't stand under pressure of your high > standards, propose own solution? > > > -- > Best regards, > Igor Stasenko AKA sig. There is something to be said for progress but one still has to think *how* to progress. There are plenty of examples of people making progress in the wrong direction and messing everything up. In this case, why do we need compiler changes? If we want to make the documentation more explicit wouldn't a better solution to add some extra machinery into the code browser? Some extra indicators could appear for methods, class or what ever that have documentation associated with them. The possibilities are endless. Personally I have never liked the idea of "documentation methods". For me that is a very load "we have no better way to do this" smell. And given the malleability of Squeak there is no reason to not have a better way (well, besides time of course, but adding something like this can't be too much more involved then a bunch of compiler changes). |
|
|
In reply to this post by Igor Stasenko
On Jan 2, 2008 7:18 PM, Igor Stasenko <[hidden email]> wrote:
> > I am not sure what "the right thing" is in this situation. > > > > Does this mean that the result is executable in place? Can it be copied > > and pasted to another workspace and > > still be executed as is? > > > > Adding features to browsers is a lost cause now that there are so many > > browsers to support with such features. > > > > I am not sure that I want all of my comments/documentation to be in > > green barely legible italics. > > > > The option of finishing method parsing at a line beginning with """""" > > is trivial to add to current systems in a safe way. I am using this for > > the 'Sake' documentation. Once we have an example of this in use it > > might be worth looking to put in place a more comprehensive solution. > > > > I think, reserving a slot in CompiledMethod and in Class(es) for > documentation is better way. > Simply put there any object , which should answer #show message. And > then you can attach anything you like: URL, in-image PDF or > whatever... > > cheers > > > > Keith > > > > > > > > -- > Best regards, > Igor Stasenko AKA sig. > > We don't have to modify those classes, we can make the relationship on the documentation side (i.e. documentation classes point to what they document). This would ensure we don't make a big increase in the size of a running image. The documentation aware messages can still be on the message objects, they just do their work by asking the documentation machinery. This would be a little slower, but have potentially less impact to a deployed image and displaying documentation isn't happening in tight loops so it should be fine. |
|
|
In reply to this post by Igor Stasenko
On Jan 2, 2008 9:20 PM, Igor Stasenko <[hidden email]> wrote:
> > Yes, it is. But if you know, compiled methods are well-known objects > handled by VM. > > The current format of a CompiledMethod is as follows: > header (4 bytes) > literals (4 bytes each) > bytecodes (variable) > trailer (variable) > > now, suppose you want to add new field, called 'docs' or whatever. > Where would you put it? But a better question is *why would you*? From an OO design point of view, a CompiledMethod has nothing to do with documentation, it does not need something like that to do it's job. Documentation, however refers to compiled methods. So the documentation classes should point to what they document, and you can put a method on CompiledMethod like so: CompiledMethod>>showDocumentation Documentation showFor: self |
|
|
In reply to this post by Bert Freudenberg
On Jan 4, 2008 11:18 AM, Bert Freudenberg <[hidden email]> wrote:
> > > On Jan 4, 2008, at 3:39 , David T. Lewis wrote: > > > On Thu, Jan 03, 2008 at 11:19:13AM -0800, tim Rowledge wrote: > >> > >> On 3-Jan-08, at 10:34 AM, itsme213 wrote: > >>> or the web/hyperlinked interface? In that case one could > >>> always have a Seaside-like application provide a documentation > >>> interface to a live image. > >> > >> There is - or at least, was. It was at http://swiki.gsug.org:8888/ > >> browser/ > >> but that seems no longer to be there. > > > > By golly you're right. Somebody should do something about that. It > > was a good idea then and it still is. It's a nice courtesy to let > > folks poke around in a Squeak class library without forcing them > > to drink the coolaid. > > Hehe. This is gone for years. swiki.gsug.org used to run on my > desktop machine back at the University of Magdeburg, and indeed > allowed you to peek inside the running Swiki server image with an > interface similar to a System Browser implemented as HTML frames. I > guess someone else did the same for newer HTTP server frameworks, in > any case it shouldn't take more than a few minutes to implement ... > > Nowadays http://swiki.gsug.org/ is a SmallWiki installation at http:// > www.seasidehosting.st/ and does not have a browser module anymore. > > - Bert - > > > > Well seaside comes with a web based class browser. |
|
|
In reply to this post by Jason Johnson-5
"Jason Johnson" <[hidden email]> wrote in message
> But a better question is *why would you*? From an OO design point of > view, a CompiledMethod has nothing to do with documentation, it does > not need something like that to do it's job. Documentation, however > refers to compiled methods. So the documentation classes should point > to what they document, and you can put a method on CompiledMethod like > so: +1 Also means that as code is changed e.g. re-factored, we have a handle to find which documentation may need to be changed, perhaps in some cases even update it automatically. |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |