The Trunk: Help-Squeak-Project-pre.65.mcz

Patrick Rein uploaded a new version of Help-Squeak-Project to project The Trunk:
http://source.squeak.org/trunk/Help-Squeak-Project-pre.65.mcz

==================== Summary ====================

Name: Help-Squeak-Project-pre.65
Author: pre
Time: 25 January 2019, 6:12:43.460527 pm
UUID: e1f3f5cb-41b0-334f-af09-83a6d3aa6484
Ancestors: Help-Squeak-Project-pre.64

Adds longer help texts to the message categories help chapters.

=============== Diff against Help-Squeak-Project-pre.64 ===============

Item was changed:
+ ----- Method: SqueakMessageCategoriesHelp class>>addAllCategoriesTopicTo: (in category 'private') -----
- ----- Method: SqueakMessageCategoriesHelp class>>addAllCategoriesTopicTo: (in category 'converting') -----
  addAllCategoriesTopicTo: newTopic
 
  | mapping allCategoriesTopic |
  allCategoriesTopic := HelpTopic
  title: 'All message categories'
  icon: (HelpIcons iconNamed: #bookIcon)
+ contents: self allCategoriesExplanation.
- contents: 'This topic contains a list of all message categories used in the system'.
 
  mapping := IdentityDictionary new.
  SystemNavigation allBehaviorsDo: [:behavior |
  ((behavior organization categories
  reject: [:category | category first = $*])
  collect: [:category | (category findTokens: '-') first withBlanksTrimmed])
  do: [:category |
  (mapping at: category asLowercase asSymbol ifAbsentPut: [Set new]) add: behavior]].
 
  mapping keys sorted do: [:categoryName |
  allCategoriesTopic addSubtopic: (HelpTopic
  title: categoryName
  icon: (HelpIcons iconNamed: #pageIcon)
  contents: (((mapping at: categoryName) collect: [:c | c printString]) sorted joinSeparatedBy: ',' , String crlf))].
 
  ^ newTopic addSubtopic: allCategoriesTopic!

Item was added:
+ ----- Method: SqueakMessageCategoriesHelp class>>allCategoriesExplanation (in category 'contents') -----
+ allCategoriesExplanation
+
+ ^ 'This chapter contains a list of all message categories used in the system and in which classes they are used.'!

Item was changed:
+ ----- Method: SqueakMessageCategoriesHelp class>>mainTopicExplanation (in category 'contents') -----
- ----- Method: SqueakMessageCategoriesHelp class>>mainTopicExplanation (in category 'converting') -----
  mainTopicExplanation
 
+ ^ 'Message categories are useful for readers of a class to distinguish between different aspects of the class. Depending on the category users might have a different perspective on the class they look at. Selecting the right message category can be difficult as there might be several categories the method would fit into. The following guidelines might help with judging where to put methods:
+
+ 1. Look for matching method categories in common classes such as Collections, Magnitude, or Object. Depending on the domain of your method this might also include common, but specialized, classes such as Form, Morph, AbstractSound and so on.
+
+ 2. If the category you would like to use is already very full or does not describe the concern of your method very well, consider using subcategories. You can specify one by putting a dash between the category name and the subcategory name, e.g. ''menu - layout menu''.
+
+ 3. Method categories are often used to denote whether a method should only be called by an object on itself. Such methods are often sorted into the ''private'' category. This immediately indicates which methods should rather not be used by other objects. At the same time the ''private'' category is very generic and does not help readers very much. Thus, consider using a subcategory which describes the concern of the method.
+
+ This chapter further contains a more detailed description of some of the message categories and a separate subchapter listing all categories used in the system. The detailed descriptions all contain a list of example methods and, where appropriate, specify the meaning of the category in different contexts (e.g. packages or particular class hierarchies).'!
- ^ 'Message categories are useful for readers of a class to distinguish between different aspects of the class. Depening on the category users might have a different perspective on the class they look at.'!