"

 COPYRIGHT (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.

"

"{ Package: 'stx:libbasic3' }"

Object subclass:#HTMLDocGenerator

	instanceVariableNames:'outStream pathToTopOfDocumentation

		pathToLanguageTopOfDocumentation httpRequestOrNil

		generateBodyOnly backRef backCmd imagePath refLines demoLines

		warnLines hintLines authorLines classProtocolCategories

		instanceProtocolCategories'

	classVariableNames:''

	poolDictionaries:''

	category:'System-Documentation'

!

!HTMLDocGenerator class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (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.

"

!

documentation

"

    Generates HTML documentation for a class.

    Although this is normally used with the SystemBrowser

    (classes-generate documentation menu),

    it may be useful on its own, to programatically generate

    up-to-date documents from a classes source.

    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.

    [author:]

        Claus Gittinger

    [see also:]

        BrowserView

        HTMLDocumentView

"

! !

!HTMLDocGenerator class methodsFor:'document generation'!

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

    ^ self new htmlClassCategoryList

    "

     HTMLDocGenerator htmlClassCategoryList

    "

!

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

    ^ self new htmlClassListPrefix:prefix

    "

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

    ^ self new htmlClasses:classes title:title backTo:backRef

!

htmlClassesListOfCategory:aCategory backTo:backMessage

    "generate an HTML document string which contains HREFS for a list

     of classes which are contained in a particular category."

    ^ self new htmlClassesListOfCategory:aCategory backTo:backMessage

!

htmlDocOf:aClass

    "generate an HTML document string which contains a classes documentation"

    ^ self new htmlDocOf:aClass

    "

     HTMLDocGenerator htmlDocOf:Array

     HTMLDocumentView openFullOnText:(HTMLDocGenerator htmlDocOf:Array)

    "

    "Modified: / 05-11-2007 / 16:19:03 / cg"

!

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

    ^ self new htmlDocOf:aClass back:backCmd backRef:backRef imagePath:imagePath

!

htmlDocOf:aClass backRef:backRef

    "generate an HTML document string which contains a classes documentation"

    ^ self new htmlDocOf:aClass backRef:backRef

!

htmlDocOfImplementorsOf:selector

    "generate an HTML document string which contains HREFS

     to all implementors of a particular selector"

    ^ self new htmlDocOfImplementorsOf:selector

    "

     HTMLDocGenerator htmlDocOfImplementorsOf:#at:

    "

!

htmlDocOfImplementorsOfAnyMatching:selectorPattern

    "generate an HTML document string which contains HREFS

     to all implementors of a particular selector pattern"

    ^ self new htmlDocOfImplementorsOfAnyMatching:selectorPattern

    "

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

    "

!

htmlPackageDocOf:packageID

    "generate an HTML document string which contains a packages classlist"

    ^ self new htmlPackageDocOf:packageID

    "

     HTMLDocGenerator htmlPackageDocOf:#'stx:libbasic'

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

    "

!

htmlPackageList

    "generate an HTML string for all packages in the system"

    ^ self new htmlPackageList

    "

     HTMLDocGenerator htmlPackageList

    "

!

htmlSelectorList

    "generate an HTML string for all selectors (for which methods exist)

     in the system"

    ^ self new htmlSelectorList

    "

     HTMLDocGenerator htmlSelectorList

    "

!

htmlSelectorListMatching:prefix

    "generate an HTML string for all selectors which match a pattern

     (and for which methods exist) in the system"

    ^ self new htmlSelectorListMatching:prefix

!

htmlSelectorListPrefix:prefix

    "generate an HTML string for all selectors whose names starts with

     a prefix (and for which methods exist) in the system"

    ^ self new htmlSelectorListPrefix:prefix

    "

     HTMLDocGenerator htmlSelectorListPrefix:'a'

    "

!

manPageFor:aCommandName

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

    ^ self new manPageFor:aCommandName

    "

     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"

    ^ self new manPageFor:aManPageTemplateFile manCommand:nroffCommand

    "

     HTMLDocGenerator 

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

        manCommand:'nroff -man /usr/man/man2/open.2'

    "

!

manPageForFile:aManPageTemplateFile

    "convert a .man file to html"

    ^ self new manPageForFile:aManPageTemplateFile

    "

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

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

    "

! !

!HTMLDocGenerator class methodsFor:'pathnames'!

findPathToTopOfDocumentation

    #(

        '../../doc/online'

        'doc/online'

        '/opt/stx/doc/online'

    ) do:[:eachPathToTry |

        (eachPathToTry asFilename exists

        and:[eachPathToTry asFilename isDirectory])

        ifTrue:[

            ^ eachPathToTry

        ]

    ].

    ^ '.'

!

languageSpecificDocDirectory

    |lang|

    lang := UserPreferences current language.

    "XXX Kludge for now, map ISO-639 abbreviations to dir names.

     Should rename the directories"

    lang == #en ifTrue:[

        ^ 'english'.

    ].

    lang == #de ifTrue:[

        ^ 'german'.

    ].

    lang == #fr ifTrue:[

        ^ 'french'.

    ].

    lang == #it ifTrue:[

        ^ 'italian'.

    ].

    lang == #jp ifTrue:[

        ^ 'japanese'.

    ].

    ^ 'english'.

    "

     self languageSpecificDocDirectory

    "

! !

!HTMLDocGenerator methodsFor:'accessing'!

generateBodyOnly:something

    "set the value of the instance variable 'generateBodyOnly' (automatically generated)"

    generateBodyOnly := something.

!

httpRequest:aRequest

    httpRequestOrNil := aRequest.

!

pathToLanguageTopOfDocumentation:something

    "set the value of the instance variable 'pathToLanguageTopOfDocumentation' (automatically generated)"

    pathToLanguageTopOfDocumentation := something.

!

pathToTopOfDocumentation:something

    "set the value of the instance variable 'pathToTopOfDocumentation' (automatically generated)"

    pathToTopOfDocumentation := something.

! !

!HTMLDocGenerator methodsFor:'document generation'!

generateClassInfoForClass:aClass

    |owner packageID|

    owner := aClass owningClass.

    packageID := aClass package.

    outStream nextPutLine:'<dl>'.

    outStream nextPutLine:'<dt><a name="PACKAGE"><b>Package:</b></A>'.

    outStream nextPutAll:'<dd><b>'.

    self generatePackageDocReferenceFor:packageID text:packageID.

    "/ outStream nextPutAll:packageID.

    outStream nextPutLine:'</b>'.

    outStream nextPutLine:'</dl>'.

    aClass category notNil ifTrue:[

        outStream nextPutLine:'<dl>'.

        outStream nextPutLine:'<dt><a name="CATEGORY"><b>Category:</b></A>'.

        outStream nextPutLine:'<dd><b>', aClass category , '</b>'.

        outStream nextPutLine:'</dl>'.

    ].

    owner notNil ifTrue:[

        outStream nextPutLine:'<dl>'.

        outStream nextPutLine:'<dt><a name="OWNER"><b>Owner:</b></A>'.

        outStream nextPutAll:'<dd><b>'. 

        self generateClassDocReferenceFor:owner name.

        outStream cr.

"/        outStream nextPutLine:(self 

"/                    anchorForHTMLDocAction:

"/                        ('htmlDocOf:', owner name )

"/                    info:

"/                        ( 'Show documentation of ' , owner nameWithoutPrefix )

"/                    text:

"/                        owner nameWithoutPrefix).

        outStream nextPutLine:'</b>'.

    ] ifFalse:[

        self htmlRevisionDocOf:aClass to:outStream.

    ].

    outStream nextPutLine:'</dl>'.

    authorLines notNil ifTrue:[

        outStream nextPutLine:'<dl><dt><a name="AUTHOR"><b>Author:</b></A>'.

        authorLines do:[:l|

            outStream nextPutLine:'<dd><b>', l , '</b>'.

        ].

        outStream nextPutLine:'</dl>'.

    ].

!

generateClassProtocolDocumentationForClass:aClass

    |metaClass shortMetaName|

    classProtocolCategories notEmpty ifTrue:[

        metaClass := aClass class.

        shortMetaName := metaClass nameWithoutPrefix.

        outStream nextPutLine:'<li><a href="#CLASSPROTOCOL" name="I_CLASSPROTOCOL">Class protocol</a>'.

        outStream nextPutLine:'<ul>'.

        classProtocolCategories do:[:cat |

            outStream nextPutLine:'<li><a name="I_' , shortMetaName , '_category_' , cat , '"' ,

                                     ' href="#' , shortMetaName , '_category_' , cat ,

                                     '">' , cat , '</a> '.

        ].

        outStream nextPutLine:'</ul>'.

    ].

!

generateDemo

    outStream nextPutLine:'<h2><a name="DEMOSTARTUP" href="#I_DEMOSTARTUP">Demonstration:</A></h2>'.

    demoLines do:[:l |

        outStream nextPutLine:'<a INFO="demonstration" type="example">'.

        outStream nextPutLine:'<pre><code>'.

        outStream nextPutLine:'    ' , l withoutSeparators.

        outStream nextPutLine:'</code></pre>'.

        outStream nextPutLine:'</a>'.

        outStream nextPutLine:'<br>'.

    ].

!

generateDescription:docu

    docu notNil ifTrue:[

        outStream nextPutLine:'<h2><a name="DESCRIPTION" href="#I_DESCRIPTION">Description:</A></h2>'.

        outStream nextPutLine:'<BR>'.

        outStream nextPutLine:'<pre>'.

        outStream nextPutLine:docu.

        outStream nextPutLine:'</pre>'.

        self generateHorizontalLine.

    ].

!

generateExampleEnd

    outStream nextPutLine:'</code></pre>'.

    self generatingForSTXBrowser ifTrue:[

        outStream nextPutLine:'</a>'.

    ].

    outStream nextPutLine:'</td></tr></table>'.

!

generateExampleStart

    outStream nextPutLine:'<p></p><table width="100%" bgcolor="#eedddd"><tr><td>'.

    self generatingForSTXBrowser ifTrue:[

        outStream nextPutLine:'<a info="execute the example" type="example" showresult>'.

    ].

    outStream nextPutLine:'<pre><code>'.

!

generateExamples:examples

    |inExample|

    inExample := false.

    outStream nextPutLine:'<h2><a name="EXAMPLES" href="#I_EXAMPLES">Examples:</A></h2>'.

    outStream nextPutLine:'<BR>'.

    examples do:[:line |

        line withoutSeparators = '[exBegin]' ifTrue:[

            inExample ifTrue:[

                self generateExampleEnd.

            ].

            self generateExampleStart.

            inExample := true.

        ] ifFalse:[

            line withoutSeparators = '[exEnd]' ifTrue:[

                inExample ifTrue:[

                    self generateExampleEnd.

                ].

                inExample := false.

            ] ifFalse:[

                outStream nextPutLine:line

            ]

        ].

    ].

    inExample ifTrue:[

        self generateExampleEnd.

    ].

    self generateHorizontalLine.

!

generateInheritanceTreeForClass:aClass

    |indent first supers subs|

    supers := aClass allSuperclasses.

    (aClass == Autoload or:[aClass == Object]) ifTrue:[

        subs := #()

    ] ifFalse:[

        subs := self shownSubclassesOf:aClass. 

    ].

    outStream nextPutLine:'<h2><a name="INHERITANCE" href="#I_INHERITANCE">Inheritance:</A></h2>'.

    outStream nextPutLine:'<pre>'.

    indent := 3.

    first := true.

    (supers size > 0) ifTrue:[

        supers reverseDo:[:cls |

            |className|

            className := cls name.    

            first ifFalse:[

                outStream spaces:indent; nextPutLine:'|'.

                outStream spaces:indent; nextPutAll:'+--'.

                indent := indent + 3.

            ] ifTrue:[

                outStream spaces:indent

            ].

            first := false.

            self generateClassDocReferenceFor:className.

            outStream cr.

        ].