tim Rowledge uploaded a new version of HelpSystem-Core to project The Trunk: http://source.squeak.org/trunk/HelpSystem-Core-tpr.104.mcz
==================== Summary ====================
Name: HelpSystem-Core-tpr.104 Author: tpr Time: 30 May 2018, 4:37:34.320801 pm UUID: f5c3b7ee-73f1-44c2-b379-af5934ffe16d Ancestors: HelpSystem-Core-mt.103
Update some help related methods
=============== Diff against HelpSystem-Core-mt.103 ===============
Item was changed: ----- Method: ClassBasedHelpTopic>>updateSubtopics (in category 'updating') ----- updateSubtopics + "build a list of subtopics; start with the list of page names specified by the helpClass' #pages method, remembering that it is an ordered list of + - selectors that return a HelpTopic, + - or the name of a class that must in turn provide help topics etc. This allows for hierarchies with 'subtrees in the middle'. + The order of the pages reflects the order of the selectors and class names given. + Then all the subclasses that are not #ignore'd and not already included are added. + Finally the list of class names and messages is used to assemble the actual help topics. + + Questions: + is it actually useful to include the possibility of class names as per the CustomHelpHelpBuilder>createTopicFrom: code? + is the #ignore testing worth keeping?" + - | pages | pages := (self helpClass pages collect: [:pageSelectorOrClassName | (Smalltalk hasClassNamed: pageSelectorOrClassName asString) ifTrue: [Smalltalk classNamed: pageSelectorOrClassName asString] ifFalse: [pageSelectorOrClassName]]) asOrderedCollection.
self helpClass subclasses select: [:cls | cls ignore not] thenDo: [:cls | pages addIfNotPresent: cls].
^ subtopics := pages withIndexCollect: [:pageSelectorOrClass :priority | pageSelectorOrClass isBehavior ifFalse: [(self helpClass perform: pageSelectorOrClass) priority: priority - pages size; key: pageSelectorOrClass; yourself] ifTrue: [pageSelectorOrClass asHelpTopic]]!
Item was changed: ----- Method: CustomHelpHelpBuilder>>createTopicFrom: (in category 'private') ----- createTopicFrom: aDescription + "Create a help topic from a description provided by a class. + aDescription must provide (via #pages) an ordered list of + - selectors that return a HelpTopic, + - or the name of a class that must in turn provide help topics etc. This allows for hierarchies with 'subtrees in the middle'. + The order of the pages reflects the order of the selectors and class names given" - "Create a topic from a description stored on a class. - aDescription can specify (via #pages) the name of a class and not - only a selector. This allows for hierarchies with 'subtrees in the middle'" |topic page pageClasses | topic := HelpTopic named: aDescription bookName. topic key: aDescription key. topic icon: aDescription icon. pageClasses := Set new. aDescription pages do: [:pageSelectorOrClass| page:= (Smalltalk hasClassNamed: pageSelectorOrClass asString) ifFalse: [aDescription perform: pageSelectorOrClass] ifTrue: [pageClasses add: (Smalltalk classNamed: pageSelectorOrClass asString). (Smalltalk classNamed: pageSelectorOrClass asString) asHelpTopic]. topic addSubtopic: page. ]. ((aDescription subclasses asSet) removeAllFoundIn: pageClasses; yourself) do: [:subclass | topic subtopics add: subclass asHelpTopic ]. ^topic!
Item was changed: ----- Method: HelpHowToHelpTopics class>>overview (in category 'pages') ----- overview + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopics edit: #overview" + ^HelpTopic - ^HelpTopic title: 'Overview' + contents: + 'THE IMPLEMENTATION - contents: - 'THE IMPLEMENTATION
The help system typically consists of help books including one or more pages. A book or page is therefore a "topic of interest" providing contents for help to a user. A topic has a title and an icon and is able to have subtopics forming a hierarchy of topics. This simple model is reflected in the class HelpTopic.
Since this model forms a hierarchical structure of help topics there is a browser with a tree to display the help contents. This browser is implemented in class HelpBrowser.
You can open this browser programmatically using:
HelpBrowser open + !!' readStream nextChunkText! - ' !
Item was changed: ----- Method: HelpHowToHelpTopics class>>page1 (in category 'pages') ----- page1 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopics edit: #page1" ^HelpTopic title: '1. Simple help topics' contents: 'The help browser usually operates on a hierarchy of help topics with one help topic at the root level. Evaluate the following expression in a workspace to contruct a simple help topic and open it as a root topic in the help browser. |root| root := HelpTopic title: ''My first topic'' contents: ''A simple topic of interest''. HelpBrowser openOn: root Note that the help browser displays the contents of our topic in the right page and uses the topics title as the title for the help browser window. '!
Item was changed: ----- Method: HelpHowToHelpTopics class>>page2 (in category 'pages') ----- page2 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopics edit: #page2" ^HelpTopic title: '2. Forming a hierarchy' contents: 'To form a hierarchy we just have to add new subtopics on our root topic. |root sub1 sub2| root := HelpTopic title: ''My first topic'' contents: ''A simple topic of interest''. sub1 := HelpTopic title: ''My first subtopic'' contents: ''First subsection''. sub2 := HelpTopic title: ''My second subtopic'' contents: ''Second subsection''. root addSubtopic: sub1; addSubtopic: sub2. HelpBrowser openOn: root '!
Item was changed: ----- Method: HelpHowToHelpTopics class>>page3 (in category 'pages') ----- page3 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopics edit: #page3" ^HelpTopic title: '3. Adding icons' contents: 'If you dont like the default icon you can add own custom icons to the topics. See the class HelpIcons for more details. |root sub1 sub2| root := HelpTopic title: ''My first topic'' contents: ''A simple topic of interest''. sub1 := HelpTopic title: ''My first subtopic'' contents: ''First subsection''. sub2 := HelpTopic title: ''My second subtopic'' icon: (HelpIcons iconNamed: #packageIcon) contents: ''Second subsection''. root addSubtopic: sub1; addSubtopic: sub2. HelpBrowser openOn: root '!
Item was changed: ----- Method: HelpHowToHelpTopics class>>page4 (in category 'pages') ----- page4 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopics edit: #page4" ^HelpTopic title: '4. Own help objects' contents: 'You can open this help browser directly on an instance of HelpTopic, but it is more common to open it on any object that understands the message #asHelpTopic.
So you can write for instance:
HelpBrowser openOn: Integer
opening a short API help/system reference on the Integer class. The above expression is the short form for:
HelpBrowser openOn: (SystemReference forClass: Integer)
If you want you can include the subclasses:
HelpBrowser openOn: (SystemReference hierarchyFor: Integer)
or even methods
HelpBrowser openOn: (SystemReference hierarchyWithMethodsFor: Integer)
You can browse the whole system reference documentation using:
HelpBrowser openOn: SystemReference
But these are only a few examples what we can extract from the system.
However - the major goal is NOT an API browser, the idea is to provide a simple architecture to provide browsable help contents depending on the context. For instance it should also be possible to use the help system to provide end user help on any commercial application that is written with the Smalltalk system.
' !
Item was changed: ----- Method: HelpHowToHelpTopics class>>page5 (in category 'pages') ----- page5 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopics edit: #page5" ^HelpTopic title: '5. Help sources' contents: 'Since the underlying model is very simple you can easily fill it with nearly any information from different sources. Try this:
|topic day url sub| topic := HelpTopic named: ''Last week on Squeak IRC''. 0 to: 7 do: [:index | day := (Date today subtractDays: index) printFormat: #(3 2 1 $. 1 2 2). url := ''http://tunes.org/~nef/logs/squeak/'' , day. sub := HelpTopic title: day contents: (HTTPLoader default retrieveContentsFor: url) contents. topic addSubtopic: sub. ]. HelpBrowser openOn: topic
' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>overview (in category 'pages') ----- overview + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #overview" ^HelpTopic title: 'Overview' contents: 'OVERVIEW The help system allows you to provide own books and help texts. You can open the help browser on any object that is able to understand #asHelpTopic.
This method returns the root node of the displayed topic hierarchy:
HelpBrowser openOn: myObject
Typically the object does not convert itself to a help topic structure, usually it dispatches to a builder (see HelpBuilder and subclasses) who does all this. A much more convenient and reproducable way is to implement custom help classes. This allows you to implement and manage your help texts using the standard development and code management tools. These custom help classes are subclasses of "CustomHelp" and are automatically included into the standard help browser. '!
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step1 (in category 'pages') ----- step1 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step1" ^HelpTopic title: 'Step 1 - Create a class for the book' contents: 'STEP 1 - CREATE A CLASS FOR THE BOOK There is a predefined class CustomHelp which you have to subclass for a custom help book to show up as a book in the Help browser: CustomHelp subclass: #MyAppHelp instanceVariableNames: '''' classVariableNames: '''' poolDictionaries: '''' category: ''MyApp-Help''
Class methods on this class can reflect pages and if you want to provide nested help books just subclass your own help class to form a hierarchy. Any new subclass of MyAppHelp will then be a new book in your hierarchy.
The class category used should end with "-Help" so it is easy to recognize that it includes the help support of your project.' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step2 (in category 'pages') ----- step2 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step2" ^HelpTopic title: 'Step 2 - Provide a book name' contents: 'STEP 2 - PROVIDE A BOOK NAME Now implement the class method #bookName to return the name of your help book.
bookName ^''My App help'' By implementing this method the system knows how you would like to name your book and uses the given string as a label in the HelpBrowser later.' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step3 (in category 'pages') ----- step3 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step3" ^HelpTopic title: 'Step 3 - Implement pages using methods' contents: 'STEP 3 - IMPLEMENT PAGES USING METHODS
Implement a page by defining a method that returns an instance of HelpPage defining a page title and a help text displayed in the help browser.
firstPage ^HelpTopic title: ''First Page'' contents: ''Hello world''
Define a new method for each page of your book. Please group the pages in a method category called "pages". You can also define an icon for the specific page:
secondPage ^HelpTopic title: ''Second Page'' icon: (HelpIcons iconNamed: #packageIcon) contents: ''More to come''
Note: ===== Later we may add support for better help contents than just plain text (markup descriptions, active morphs, ...) ' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step4 (in category 'pages') ----- step4 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step4" ^HelpTopic title: 'Step 4 - Defining the page order' contents: 'STEP 4 - DEFINING THE PAGE ORDER
By implementing the class method #pages you return a collection of method selectors to define the order in which the pages appear in your book:
pages ^#(firstPage secondPage)
' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step5 (in category 'pages') ----- step5 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step5" ^HelpTopic title: 'Step 5 - Test your help' contents: 'STEP 5 - TEST YOUR HELP By using
HelpBrowser open
' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step6 (in category 'pages') ----- step6 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step6" ^HelpTopic title: 'Step 6 - Add more structure' contents: 'STEP 6 - ADD MORE STRUCTURE
If you add a new subclass to your custom help class and repeating step 2 to 4 you can profide new substructures (subbooks) since the help books are mapped to the class hierarchy. Example:
MyAppHelp subclass: #MyAppTutorial instanceVariableNames: '''' classVariableNames: '''' poolDictionaries: '''' category: ''MyApp-Help''
then implement a #bookName, the pages and a #pages method as before on this new class and reopen the help browser. ' !
Item was changed: ----- Method: HelpHowToHelpTopicsFromCode class>>step7 (in category 'pages') ----- step7 + "This method was automatically generated. Edit it using:" + "HelpHowToHelpTopicsFromCode edit: #step7" ^HelpTopic title: 'Step 7 - Tips and Tricks' contents: 'STEP 7 - TIPS AND TRICKS
Tip1: If you implement the #pages method you can also use the name of a custom help class that should be integrated between the specific pages:
#pages ^(firstPage MyAppTutorial secondPage)
Tip2: You can easily edit the help contents of a page by using the #edit: message. For our example just evaluate:
MyAppHelp edit: #firstPage This will open a workspace with the help contents and when you accept it it will be saved back to the help method defining the topic.
' !