[Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

Brian Brown rbb at techgame.net
Fri Apr 6 16:21:06 UTC 2007


I agree with Tim and Matt that using comments would be great way to  
go, with one caveat :)

The biggest frustration with using comments is that there is no good  
"starting place" for a given class category. For example, go browse  
the Seaside classes and categories and figure out where one should  
start. You can repeat this exercise for any number of categories. I  
propose that we we add a documentation attribute to the PackageInfo  
stuff, so there is a category level documentation spot, with links to  
the appropriate class comments.

Any thoughts?

Brian


On Apr 5, 2007, at 7:10 PM, tim Rowledge wrote:

>
> 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
>
>
>




More information about the Squeak-dev mailing list