eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'HTMLDocGenerator':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: HTMLDocGenerator


Inheritance:

   Object
   |
   +--HTMLDocGenerator
      |
      +--HTMLDocGeneratorForJavaScript

Package:
stx:libbasic3
Category:
System-Documentation
Version:
rev: 1.132 date: 2019/06/28 07:02:35
user: cg
file: HTMLDocGenerator.st directory: libbasic3
module: stx stc-classLibrary: libbasic3
Author:
Claus Gittinger

Description:


Generates HTML documentation for a class.

This is used with the SystemBrowser (classes-generate documentation menu),
and the online documentation (which generates up-to-date documents just-in-time
out of the running system).

It may also be useful, to programatically generate up-to-date documents 
into a folder of self contained html files (eg. for deployment).

This generator extracts the documentation methods source
(or comment), individual method comments (the first comment in
a method) and version information to generate a neatly formatted
HTML page.
If executable examples (EXBEGIN .. EXEND) are present in the classes 
documentation category these are also added as executable code
to the document.

[instance variables:]
    outStream                               <WriteStream>   internal
    pathToTopOfDocumentation                <String>        will be prepended to links.
                                                            defaults to '../../doc'
    pathToLanguageTopOfDocumentation        <String>        defaults to '../../doc/online/<lang>'
    httpRequestOrNil                                        internal
    generateBodyOnly                                        internal
    backRef                                 <URLString>     if non-nil, the url for a back-button
    backCmd                                 <String>        if non-nil, the command for a back-button (for internal doc-browser only)
    imagePath                               <String>        path to image documents
    refLines                                                internal
    demoLines                                               internal
    warnLines                                               internal
    hintLines                                               internal
    authorLines                                             internal
    classProtocolCategories                                 internal
    instanceProtocolCategories                              internal
    generateJavaScriptCallInfo              <Boolean>       if true, synopsis is shown in JavaScript syntax also
    generateDocumentForOfflineReading       <Boolean>       if true, document is generated with file links (instead of browser command links)
                                                            for offline reading by an arbitrary browser.


Related information:

    BrowserView
    HTMLDocumentView

Class protocol:

document generation
o  generateOfflineDocIn: aTopDirectory
generate a full tree of documents for offline reading.
Similar to what is generated by the live-document generator, but
all links are to static files.
Tool for deployment.

usage example(s):

     self generateOfflineDocIn:'./offlineDoc' asFilename

o  htmlClassCategoryList
generate a formatted list of all available class categories as
an HTML string. Each category will be a hyperlink to another
autogenerated page, containing the classes per category.
The generated page is supposed to be given to an HTML reader
with home being set to ../doc/online/xxx/classDoc
(i.e. the images are to be found one-up in the doc hierarchy)

usage example(s):

     HTMLDocGenerator htmlClassCategoryList

o  htmlClassListPrefix: prefix
generate an HTML document string which contains HREFS for a list
of classes which start with some prefix (typically, the first
character is given)

usage example(s):

     HTMLDocGenerator htmlClassListPrefix:'A'

o  htmlClasses: classes title: title backTo: backRef
generate an HTML document string which contains HREFS for a given list
of classes. If backref is nonNil, a back-button to that
HREF is added at the top.
The generated page is supposed to be given to an HTML reader
with home being set to ../doc/online/xxx/classDoc
(i.e. the images are to be found one-up in the doc hierarchy)

o  htmlClassesListOfCategory: aCategory backTo: backMessage
generate an HTML document string which contains HREFS for a list
of classes which are contained in a particular category.

o  htmlDocOf: aClass
generate an HTML document string which contains a classes documentation

usage example(s):

     HTMLDocGenerator htmlDocOf:Array
     HTMLDocumentView openFullOnText:(HTMLDocGenerator htmlDocOf:Array)

o  htmlDocOf: aClass back: backCmd backRef: backRef imagePath: imagePath
generate a nice HTML page from a class, with a back-reference
to a command or document.

o  htmlDocOf: aClass backRef: backRef
generate an HTML document string which contains a classes documentation

o  htmlDocOfImplementorsOf: selector
generate an HTML document string which contains HREFS
to all implementors of a particular selector

usage example(s):

     HTMLDocGenerator htmlDocOfImplementorsOf:#at:

o  htmlDocOfImplementorsOfAnyMatching: selectorPattern
generate an HTML document string which contains HREFS
to all implementors of a particular selector pattern

usage example(s):

     HTMLDocGenerator htmlDocOfImplementorsOfAnyMatching:'key*:x:y:'

o  htmlKWOCList
CachedKWIC := nil

usage example(s):

     HTMLDocGenerator htmlKWOCList

o  htmlOfflineClassCategoryList
generate a formatted list of all available class categories as
an HTML string. Each category will be a hyperlink to another
autogenerated page, containing the classes per category.
The generated page is supposed to be given to an HTML reader
with home being set to ../doc/online/xxx/classDoc
(i.e. the images are to be found one-up in the doc hierarchy)

usage example(s):

     HTMLDocGenerator htmlOfflineClassCategoryList

o  htmlOfflineDocOf: aClass
generate an HTML document string which contains a class's documentation for offline reading.
This is different in that it creates file links, instead of action links
(action links only work with the builtin doc reader).

o  htmlOfflineIndex

o  htmlOfflinePackageList
generate an HTML string for all packages in the system

usage example(s):

     HTMLDocGenerator htmlOfflinePackageList

o  htmlPackageDocOf: packageID
generate an HTML document string which contains a packages classlist

usage example(s):

     HTMLDocGenerator htmlPackageDocOf:#'stx:libbasic'
     HTMLDocumentView openFullOnText:(HTMLDocGenerator htmlPackageDocOf:#'stx:libbasic')

o  htmlPackageList
generate an HTML string for all packages in the system

usage example(s):

     HTMLDocGenerator htmlPackageList

o  htmlSelectorList
generate an HTML string for all selectors (for which methods exist)
in the system

usage example(s):

     HTMLDocGenerator htmlSelectorList

o  htmlSelectorListMatching: prefix
generate an HTML string for all selectors which match a pattern
(and for which methods exist) in the system

o  htmlSelectorListPrefix: prefix
generate an HTML string for all selectors whose names starts with
a prefix (and for which methods exist) in the system

usage example(s):

     HTMLDocGenerator htmlSelectorListPrefix:'a'

o  manPageFor: aCommandName
generate a (unix-) man page for a given command & convert the output to html

usage example(s):

     HTMLDocGenerator manPageFor:'ls'

     HTMLDocumentView openFullOnText:(HTMLDocGenerator manPageFor:'ls')

o  manPageFor: aManPageTemplateFile manCommand: nroffCommand
convert man-command output to html.
Only the body of the text (without head../head and body../body) is generated

o  manPageForFile: aManPageTemplateFile
convert a .man file to html

usage example(s):

     HTMLDocGenerator manPageForFile:'/usr/man/man2/open.2'

     HTMLDocumentView openFullOnText:(HTMLDocGenerator manPageForFile:'../../stc/stc.1')

document generation-helpers
o  camelCaseSeparatedWordsOf: wordIn do: aBlock
self camelCaseSeparatedWordsOf:'HelloWorld' do:[:w | Transcript showCR:w]
self camelCaseSeparatedWordsOf:'abcDef' do:[:w | Transcript showCR:w]
self camelCaseSeparatedWordsOf:'UTFEncoder' do:[:w | Transcript showCR:w]
self camelCaseSeparatedWordsOf:'JisEncoder' do:[:w | Transcript showCR:w]
self camelCaseSeparatedWordsOf:'JISEncode' do:[:w | Transcript showCR:w]

o  generateKWIC
if we have a key like 'startWith:' in the list,

usage example(s):

     CachedKWIC := nil.
     self generateKWIC

o  generateKWICForClassAndMethodNames
'the' 'a'

usage example(s):

     CachedKWIC := nil.
     self generateKWICForClassAndMethodNames

o  htmlForMethod: aMethod

pathnames
o  findPathToTopOfDocumentation
find the 'doc/online' folder

usage example(s):

     self findPathToTopOfDocumentation

o  languageSpecificDocDirectory
XXX Kludge for now, map ISO-639 abbreviations to dir names.
Should rename the directories

usage example(s):

     self languageSpecificDocDirectory


Instance protocol:

accessing
o  generateBodyOnly: aBoolean

o  generateDocumentForOfflineReading

o  generateDocumentForOfflineReading: aBoolean

o  generateJavaScriptCallInfo

o  generateJavaScriptCallInfo: aBoolean

o  httpRequest: aRequest

o  pathToLanguageTopOfDocumentation: something

o  pathToTopOfDocumentation: something

o  showUpButton

o  showUpButton: aBoolean

document generation
o  generateClassInfoForClass: aClass
outStream nextPutAll:packageID.

o  generateClassProtocolDocumentationForClass: aClass

o  generateDemo

o  generateDescription: docu

o  generateExampleEnd

o  generateExampleStart
outStream nextPutAll:'<p></p>'.

o  generateExamples: examples
everything between exBegin and exEnd is shown as code example;
the remaining text is shown as regular text (commenting the code, I hope)

o  generateInheritanceTreeForClass: aClass

o  generateInstanceProtocolDocumentationForClass: aClass

o  generatePrivateClassInfoForClass: aClass withPrivateClasses: privateClasses

o  generateRefLineFor: ref forClass: aClass

o  generateRefLines: refLines forClass: aClass

o  generateSubclassInfoForClass: aClass

document generation-API
o  htmlDocOf: aClass
generate an HTML document string which contains a classes documentation

usage example(s):

     self htmlDocOf:PostscriptPrinterStream

o  htmlDocOf: aClass back: backCmd
generate an HTML document string which contains a classes documentation

o  htmlDocOf: aClass back: backCmd backRef: backRef
generate a nice HTML page from a class, with a back-reference
to a command or document.

Extract sections from the classes documentation method,
where the following lines start a special subsection:
[see also:] - references to other classes and/or documents
[start with:] - one-liners to start a demonstration
[author:] - author(s) of this class
[warning:] - usage warnings if any
[hints:] - usage hints if any
Each section ends with an empty line - however, for formatting,
a line consisting of a single backslash character will be converted
to an empty line.

Also extract examples from the classes example method,
where executable examples are made from sections enclosed in:
[exBegin]
...
[exEnd]
these parts are displayed in courier and will be made executable.
everything else is plain documentation text.

o  htmlDocOf: aClass back: backCmdArg backRef: backRefArg imagePath: imagePathArg
generate a nice HTML page from a class, with a back-reference
to a command or document.

Extract sections from the classes documentation method,
where the following lines start a special subsection:
[see also:] - references to other classes and/or documents
[start with:] - one-liners to start a demonstration
[author:] - author(s) of this class
[warning:] - usage warnings if any
[hints:] - usage hints if any
Each section ends with an empty line - however, for formatting,
a line consisting of a single backslash character will be converted
to an empty line.

Also extract examples from the classes example method,
where executable examples are made from sections enclosed in:
[exBegin]
...
[exEnd]
these parts are displayed in courier and will be made executable.
everything else is plain documentation text.

usage example(s):

     self htmlDocOf:Object
     self htmlDocOf:Array
     self htmlDocOf:Filename
     self htmlDocOf:Block

o  htmlDocOf: aClass backRef: backRef
generate an HTML document string which contains a classes documentation

o  htmlDocOfImplementorsOf: selector
generate an HTML document string which contains HREFS
to all implementors of a particular selector

o  htmlDocOfImplementorsOfAnyMatching: selectorPattern
generate an HTML document string which contains HREFS
to all implementors of a particular selector

o  htmlOfflineDocOf: aClass
generate an HTML document string which contains a class's documentation for offline reading.
Offline reading means that the links to other classes are created as file links,
(as opposed to action links, which only work with the builtin doc reader).

usage example(s):

     self htmlOfflineDocOf:PostscriptPrinterStream

document generation-helpers
o  extractAndRemoveSpecial: pattern from: docu
given a collection of docu lines (from documentation methods comment),
extract things like [see also:], [author:] etc.
If found, remove the lines from the string collection,
and return the extracted ones. Otherwise return nil.
Attention: docu is sideeffectively changed (lines removed)

o  extractAndRemoveSpecialLinesFromDocumentation: docu
Extract things like [see also:], [author:] etc. from docu
If found, remove the lines from the string collection,
and leave them in corresponding instVars.
Attention: docu is sideeffectively changed (lines removed)

o  extractDocumentationFromClass: aClass
try comment

o  extractExamplesFromClass: aClass

o  extractProtocolCategoriesFrom: aClass

o  htmlForMethod: arg

o  htmlRevisionDocOf: aClass to: s
extract a classes versionInfo and return an HTML document string
for that.

o  printOutHTMLCategoryProtocol: aCategory of: aClass on: aStream
append documentation on each method in a particular methodCategory
of the given class in HTML onto aStream.

o  printOutHTMLMethodProtocol: aMethod on: aStream
given the source in aString, print the method's message specification
and any method comments - without source; used to generate documentation
pages

o  printOutHTMLMethodProtocol: aMethod on: aStream showClassName: showClassName classRef: withClassRef
given the source in aString, print the method's message specification
and any method comments - without source; used to generate documentation
pages

o  printOutHTMLMethodProtocol: aMethod on: aStream showClassName: showClassName classRef: withClassRef picturePath: picturePath
given the source in aString, print the method's message specification
and any method comments - without source.
used to generate documentation pages

usage example(s):

     self basicNew
        printOutHTMLMethodProtocol:(Array compiledMethodAt:#addAllNonNilElementsTo:)
        on:Transcript 
        showClassName:true classRef:true picturePath:'pics'

o  printOutHTMLProtocolOf: aClass on: aStream
append documentation of the given class in HTML onto aStream.

usage example(s):

      self printOutHTMLProtocolOf:Float on:Stdout 

o  undentedToFirstLinesIndent: someText

document generation-lists
o  htmlClassCategoryList
generate a formatted list of all available class categories as
an HTML string. Each category will be a hyperlink to another
autogenerated page, containing the classes per category.
The generated page is supposed to be given to an HTML reader
with home being set to ../doc/online/xxx/classDoc
(i.e. the images are to be found one-up in the doc hierarchy)

usage example(s):

     HTMLDocGenerator new htmlClassCategoryList

o  htmlClassListPrefix: prefix
generate an HTML document string which contains HREFS for a list
of classes which start with some prefix (typically, the first
character is given)

o  htmlClasses: classes title: title
generate an HTML document string which contains HREFS for a given list
of classes

o  htmlClasses: classes title: title backTo: backRef
generate an HTML document string which contains HREFS for a given list
of classes. If backref is nonNil, a back-button to that
HREF is added at the top.
The generated page is supposed to be given to an HTML reader
with home being set to ../doc/online/xxx/classDoc
(i.e. the images are to be found one-up in the doc hierarchy)

o  htmlClassesListOfCategory: category
generate an HTML document string which contains HREFS for a list
of classes which are contained in a particular category.

o  htmlClassesListOfCategory: category backTo: backRef
generate an HTML document string which contains HREFS for a list
of classes which are contained in a particular category.

o  htmlClassesMatching: aMatchPattern backTo: backRef
generate an HTML document string which contains HREFS
for a list of classes whose name matches a given matchPattern.

usage example(s):

     self htmlClassesMatching:'Tgen::*' backTo:nil

o  htmlKWOCListFor: aKWIC
generate a formatted list of all keywords in context from class documentation
as an HTML string.
Each keword will be a hyperlinked to another
autogenerated page, containing the classes documentation.
The generated page is supposed to be given to an HTML reader
with home being set to ../doc/online/xxx/classDoc
(i.e. the images are to be found one-up in the doc hierarchy)

o  htmlPackageDocOf: packageID

o  htmlPackageList
generate an HTML string for a list of all packages in the system

usage example(s):

     self new
        generateDocumentForOfflineReading:true;
        htmlPackageList.

o  htmlPackageListFor: packageNames withDocumentation: withDocumentation
generate an HTML string for a given list of packages

o  htmlSelectorList
generate an HTML string for all selectors (for which methods exist)
in the system

usage example(s):

     self htmlSelectorList

o  htmlSelectorListMatching: pattern
generate an HTML string for all selectors which match a pattern
(and for which methods exist) in the system

usage example(s):

     self htmlSelectorListMatching:'*do*'

o  htmlSelectorListPrefix: prefix
generate an HTML string for all selectors whose names starts with
a prefix (and for which methods exist) in the system

usage example(s):

     self htmlSelectorListPrefix:'a'

o  htmlSelectors: selectors title: title
generate an HTML string for a given list of selectors

format conversion-man pages
o  manPageFor: aCommand
generate a (unix-) man page for a given command & convert the output to html

o  manPageFor: aCommand inSection: sectionOrNil
generate a (unix-) man page for some entry in a section
& convert the output to html

o  manPageFor: aCommand manCommand: manCommand
convert man-command output to html.
Only the body of the text (without head../head and body../body) is generated

usage example(s):

     self manPageFor:'cvs'

o  manPageForFile: aFilename
convert a .man file to html

usage example(s):

     self manPageForFile:'../../stc/stc.1'

usage example(s):

     HTMLDocumentView openFullOnText:(self manPageForFile:'../../stc/stc.1')

o  manPageFromStream: manPageStream
convert man-command output to html.
Only the body of the text (without head../head and body../body) is generated.
This method looks for
char-backspace-char -> bold
char-backspace-underline -> italic

o  noManPageForCommand: aCommand usingManCommand: manCommand

helpers
o  anchorFor: href info: infoMessageOrNil text: text name: nameOrNil
self new anchorFor:'foo' info:'bla' text:'text' name:nil

o  anchorForHTMLAction: actionString info: infoMessageOrNil text: text
self new anchorForHTMLAction:'foo' info:'bla' text:'text'

o  anchorForHTMLAction: actionString info: infoMessageOrNil text: text name: nameOrNil
self new anchorForHTMLAction:'foo' info:'bla' text:'text'

o  anchorForHTMLDocAction: actionString info: infoMessageOrNil text: text
self new anchorForHTMLDocAction:'foo' info:'bla' text:'text'

o  anchorForHTMLDocAction: actionString info: infoMessageOrNil text: text name: anchorName
self new anchorForHTMLDocAction:'foo' info:'bla' text:'text' name:'baz'

o  anchorForHTMLDocAction: actionString text: text
self new anchorForHTMLDocAction:'foo' text:'text'

o  findPathToTopOfDocumentation

o  generateBODYEnd

o  generateBODYStart

o  generateBODYandHTMLEnd

o  generateBackButton

o  generateClassDocReferenceFor: className

o  generateClassDocReferenceFor: className text: text

o  generateClassDocReferenceFor: className text: text autoloading: autoloadedClass
generates a link to a classes documentation

o  generateH1: headerLine

o  generateHTMLEnd

o  generateHTMLHeadWithTitle: title

o  generateHorizontalLine

o  generateMethodDocReferenceFor: selector inClass: className text: text autoloading: autoloadedClass
generates a link to a classes documentation

o  generatePackageDocReferenceFor: packageID text: text
generates a link to a package documentation

o  generateUpArrowButtonForTop

o  generateUpArrowButtonWithReference: backHRef command: backCmd imagePath: imagePath altLabel: altLabel

o  generatingForSTXBrowser

o  infoParameterFor: infoMessageOrNil

o  methodCommentOf: aMethod
extract the very first comment from the method

o  methodExampleCommentsOf: aMethod
extract the very last comment from the method

o  nextPutAllEscaped: aStringOrCharacter

o  nextPutBold: aStringOrCharacter

o  nextPutItalic: aStringOrCharacter

o  shownSubclassesOf: aClass

o  withSpecialHTMLCharactersEscaped: aStringOrCharacter
self new withSpecialHTMLCharactersEscaped:'foo>'
self new withSpecialHTMLCharactersEscaped:$<
self new withSpecialHTMLCharactersEscaped:$A

pathnames
o  pathToDocumentationFile: relativeHref
unix format: used as URL

o  pathToEnglishTopOfDocumentation
always unix-name convention (used as an URL)

o  pathToLanguageTopOfDocumentation
always unix-name convention (used as an URL)

o  pathToTopOfDocumentation



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Tue, 19 Mar 2024 10:59:41 GMT