Smalltalk/X Webserver

Documentation of class 'HTMLDocGenerator':

Class: HTMLDocGenerator

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--HTMLDocGenerator
      |
      +--HTMLDocGeneratorForJavaScript

Package:: stx:libbasic3

Category:: System-Documentation

Version:: rev: 1.160 date: 2023/12/08 13:18:54; user: cg; file: HTMLDocGenerator.st directory: libbasic3; module: stx stc-classLibrary: libbasic3

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.

copyrightCOPYRIGHT (c) 1996 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

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

htmlClassListMatching: pattern

generate an HTML document string which contains HREFS for a list
of classes which match the pattern (typically, *Array* or similar)

Usage example(s):

     HTMLDocGenerator htmlClassListMatching:'*Array*'

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'

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)

htmlClassesListOfCategory: aCategory backTo: backMessage

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

htmlDocOf: aClass

generate an HTML document string which contains a classes documentation

Usage example(s):

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

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.

htmlDocOf: aClass backRef: backRef

generate an HTML document string which contains a classes documentation

htmlDocOfImplementorsOf: selector

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

Usage example(s):

     HTMLDocGenerator htmlDocOfImplementorsOf:#at:

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:'

htmlKWOCList

CachedKWIC := nil

Usage example(s):

     HTMLDocGenerator htmlKWOCList

htmlOfflineClassCategoryList

Usage example(s):

     HTMLDocGenerator htmlOfflineClassCategoryList

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).

htmlOfflineIndex

htmlOfflinePackageList

generate an HTML string for all packages in the system

Usage example(s):

     HTMLDocGenerator htmlOfflinePackageList

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')

htmlPackageList

generate an HTML string for all packages in the system

Usage example(s):

     HTMLDocGenerator htmlPackageList

htmlSelectorList

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

Usage example(s):

     HTMLDocGenerator htmlSelectorList

htmlSelectorListMatching: prefix

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

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'

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')

manPageFor: aManPageTemplateFile manCommand: nroffCommand

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

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

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]

generateKWIC

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

Usage example(s):

     CachedKWIC := nil.
     self generateKWIC

generateKWICForClassAndMethodNames

eachClass isLoaded ifTrue:[

Usage example(s):

     CachedKWIC := nil.
     self generateKWICForClassAndMethodNames

htmlForMethod: aMethod

pathnames

findPathToTopOfDocumentation

find the 'doc/online' folder

Usage example(s):

     self findPathToTopOfDocumentation

languageSpecificDocDirectory

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

Usage example(s):

     self languageSpecificDocDirectory

Instance protocol:

accessing

generateBodyOnly: aBoolean
generateDocumentForOfflineReading
generateDocumentForOfflineReading: aBoolean
generateJavaScriptCallInfo
generateJavaScriptCallInfo: aBoolean
httpRequest: aRequest
pathToLanguageTopOfDocumentation: something
pathToTopOfDocumentation: something
showUpButton
showUpButton: aBoolean

document generation

generateClassInfoForClass: aClass: outStream nextPutAll:packageID.
generateClassProtocolDocumentationForClass: aClass
generateDemo
generateDescription: docu
generateExampleEnd
generateExampleStart: outStream nextPutAll:'<p></p>'.
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)
generateInheritanceTreeForClass: aClass
generateInstanceProtocolDocumentationForClass: aClass
generatePrivateClassInfoForClass: aClass withPrivateClasses: privateClasses
generateRefLineFor: ref forClass: aClass
generateRefLines: refLines forClass: aClass
generateSubclassInfoForClass: aClass

document generation-API

htmlDocOf: aClass

generate an HTML document string which contains a classes documentation

Usage example(s):

     self htmlDocOf:PostscriptPrinterStream

htmlDocOf: aClass back: backCmd

generate an HTML document string which contains a classes documentation

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.

htmlDocOf: aClass back: backCmdArg backRef: backRefArg imagePath: imagePathArg

Usage example(s):

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

htmlDocOf: aClass backRef: backRef

generate an HTML document string which contains a classes documentation

htmlDocOfImplementorsOf: selector

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

htmlDocOfImplementorsOfAnyMatching: selectorPattern

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

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

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)

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)

extractDocumentationFromClass: aClass

try comment

extractDocumentationFromString: docString

helper

extractExamplesFromClass: aClass

extractProtocolCategoriesFrom: aClass

htmlForMethod: arg

htmlRevisionDocOf: aClass to: s

extract a classes versionInfo and return an HTML document string
for that.

printOutHTMLCategoryProtocol: aCategory of: aClass on: aStream

append documentation on each method in a particular methodCategory
of the given class in HTML onto aStream.

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

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

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'

printOutHTMLProtocolOf: aClass on: aStream

append documentation of the given class in HTML onto aStream.

Usage example(s):

      self printOutHTMLProtocolOf:Float on:Stdout

undentedToFirstLinesIndent: someText

document generation-lists

htmlClassCategoryList

Usage example(s):

     HTMLDocGenerator new htmlClassCategoryList

htmlClassListMatching: aMatchPattern

generate an HTML document string which contains HREFS for a list
of classes which match the pattern (typically, *Array* or similar)

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)

htmlClasses: classes title: title

generate an HTML document string which contains HREFS for a given list
of classes

htmlClasses: classes title: title backTo: backRef

htmlClassesListOfCategory: category

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

htmlClassesListOfCategory: category backTo: backRef

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

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 basicNew htmlClassesMatching:'Tgen::*' backTo:nil
     self basicNew htmlClassesMatching:'Tools::*' backTo:nil

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)

htmlPackageDocOf: packageID

htmlPackageList

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

Usage example(s):

     self new
        generateDocumentForOfflineReading:true;
        htmlPackageList.

htmlPackageListFor: packageNames withDocumentation: withDocumentation

generate an HTML string for a given list of packages

htmlSelectorList

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

Usage example(s):

     self htmlSelectorList

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*'

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'

htmlSelectors: selectors title: title

generate an HTML string for a given list of selectors

format conversion-man pages

manPageFor: aCommand

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

manPageFor: aCommand inSection: sectionOrNil

generate a (unix-) man page for some entry in a section
& convert the output to html

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:'malloc'
     self manPageFor:'cvs'

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')

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

noManPageForCommand: aCommand usingManCommand: manCommand

helpers

anchorFor: href info: infoMessageOrNil text: text name: nameOrNil: self new anchorFor:'foo' info:'bla' text:'text' name:nil
anchorForHTMLAction: actionString info: infoMessageOrNil text: text: self new anchorForHTMLAction:'foo' info:'bla' text:'text'
anchorForHTMLAction: actionString info: infoMessageOrNil text: text name: nameOrNil: self new anchorForHTMLAction:'foo' info:'bla' text:'text'
anchorForHTMLDocAction: actionString info: infoMessageOrNil text: text: self new anchorForHTMLDocAction:'foo' info:'bla' text:'text'
anchorForHTMLDocAction: actionString info: infoMessageOrNil text: text name: anchorName: self new anchorForHTMLDocAction:'foo' info:'bla' text:'text' name:'baz'
anchorForHTMLDocAction: actionString text: text: self new anchorForHTMLDocAction:'foo' text:'text'
findPathToTopOfDocumentation: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
generateBODYEnd
generateBODYStart
generateBODYandHTMLEnd
generateBackButton
generateClassDocReferenceFor: className
generateClassDocReferenceFor: className text: text
generateClassDocReferenceFor: className text: text autoloading: autoloadedClass: generates a link to a classes documentation
generateH1: headerLine
generateHTMLEnd
generateHTMLHeadWithTitle: title
generateHorizontalLine
generateMethodDocReferenceFor: selector inClass: className text: text autoloading: autoloadedClass: generates a link to a classes documentation
generatePackageDocReferenceFor: packageID text: text: generates a link to a package documentation
generateUpArrowButtonForTop
generateUpArrowButtonWithReference: backHRef command: backCmd imagePath: imagePath altLabel: altLabel
generatingForSTXBrowser
infoParameterFor: infoMessageOrNil
methodCommentOf: aMethod: extract the very first comment from the method
methodExampleCommentsOf: aMethod: extract the very last comment from the method
methodSendsObsoleteMethodWarning: aMethod infoInto: aBlock: parse its source and return true, if it does send one of the
obsoleteMethodWarning messages
nextPutAllEscaped: aStringOrCharacter
nextPutBold: aStringOrCharacter
nextPutItalic: aStringOrCharacter
setupOutStream
shownSubclassesOf: aClass
withSpecialHTMLCharactersEscaped: aStringOrCharacter: self new withSpecialHTMLCharactersEscaped:'foo>'
self new withSpecialHTMLCharactersEscaped:$<
self new withSpecialHTMLCharactersEscaped:$A

pathnames

pathToDocumentationFile: relativeHref: unix format: used as URL
pathToEnglishTopOfDocumentation: always unix-name convention (used as an URL)
pathToLanguageTopOfDocumentation: always unix-name convention (used as an URL)
pathToTopOfDocumentation

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:20:07 GMT

Smalltalk/X Webserver

Documentation of class 'HTMLDocGenerator':

Class: HTMLDocGenerator

Inheritance:

Description:

copyright

Class protocol:

Instance protocol: