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