On 5-Apr-07, at 3:10 PM, Matthew Fulmer wrote:

>
> Max OrHai reminded me that we already have an excellent medium
> for storing Squeak documentation, better than Sophie, Pier, or
> anything else:
>
> COMMENTS!!!

Remember that comments (class or method) can make use of the linkage  
capabilities built into Squeak.
You can link pretty much any bit of text to class comments, class  
definitons, class hierarchies, methods or URLs.
cmd-6 opens the menu with those items near the end. To quote a  
message I sent to colleagues earlier this week:-
>  I wouldn't claim it was well implemented or wonderful but it's there.
>
> To link from a comment (method or class) to a class comment
> a) type the correct name of the class in your comment (duh)
> b) select it
> c) cmd-6 opens a menu - near the bottom you will see several items  
> related to this
> 	Do It
> 	Print It
> 	Link to comment of class
> 	Link to definition of class
> 	Link to hierarchy of class
> 	Link to method
> 	be a web URL link
> d) choose 'link to comment of class'
>
> Now if you click on the linked word (blue text) a browser will open  
> at the relevant class comment. The other options are useful at  
> times; in this context the 'Do It ' and 'Print it' actually make  
> links that do or print something. For example
> Date today
> select, choose 'Print It' and then click on it.
>
> The 'link to method ' is a tiny bit more complex; you have to type  
> something like
> Integer +
> and select it, choose 'link to method'.
>
> Probably the least useful part is that the implementation is  
> somewhat tacky. If you type
> Foo
> select it, choose one of the menu options and then carry on typing  
> you will find the new text is included in the link. To remove the  
> linkiness you will have to select across the bit that shouldn't be  
> linky, cmd-6 and choose 'Edit hidden info'. This will print the  
> hidden info ie the 'Integer +' bit from above) and remove the  
> linkiness. Usually. Like I said, rather tacky - in fact so tacky  
> that the 'hidden info' is printed at the current text selection  
> instead of where one might really expect it, next to the link.
>
> You can get extra clever and do something like an html anchor;
> click here for extra pleasure<Integer +>
> will do the same as above but displays 'click here for extra  
> pleasure' in the run of text. 'show hidden info' shows the Integer  
> + part.
>
> So, you can connect the class comment of a subsidiary class to a  
> main class to guide people to the subsystem doc. You can connect  
> comments to particular methods. You can connect a method to the  
> comment for an important class or other method.




tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: HAL: Murder Operator