[squeak-dev] The Trunk: HelpSystem-Core-tpr.104.mcz

commits at source.squeak.org commits at source.squeak.org
Wed May 30 23:37:52 UTC 2018


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



More information about the Squeak-dev mailing list