The Trunk: HelpSystem-Core-tpr.104.mcz

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.  
 
 
  '
  !