"{ Encoding: utf8 }"

"

 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' }"

"{ NameSpace: Smalltalk }"

Object subclass:#HTMLDocGenerator

	instanceVariableNames:'outStream pathToTopOfDocumentation

		pathToLanguageTopOfDocumentation httpRequestOrNil

		generateBodyOnly backRef backCmd imagePath refLines demoLines

		warnLines hintLines authorLines classProtocolCategories

		instanceProtocolCategories generateJavaScriptCallInfo

		generateDocumentForOfflineReading showUpButton'

	classVariableNames:'CachedKWIC'

	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.

    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.

    [author:]

        Claus Gittinger

    [see also:]

        BrowserView

        HTMLDocumentView

"

! !

!HTMLDocGenerator class methodsFor:'document generation'!

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

    aTopDirectory recursiveMakeDirectory.

    (aTopDirectory / 'packages') recursiveMakeDirectory.

    (aTopDirectory / 'categories') recursiveMakeDirectory.

    (aTopDirectory / 'index.html') contents:(self htmlOfflineIndex).

    (aTopDirectory / 'packages/index.html') contents:(self htmlOfflinePackageList).

    (aTopDirectory / 'categories/index.html') contents:(self htmlOfflineClassCategoryList).

    "/ (aTopDirectory / 'classes/index.html') contents:(self htmlOfflineClassList).

    "

     self generateOfflineDocIn:'./offlineDoc' asFilename

    "

!

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

    "

!

htmlKWOCList

    "

    CachedKWIC := nil

    "

    CachedKWIC isNil ifTrue:[

        "/ CachedKWIC := self generateKWIC.

        CachedKWIC := self generateKWICForClassAndMethodNames.

        "/ to flush the cached kwic, whenever a class-documentation method is changed

        Smalltalk addDependent:self class. 

    ].

    ^ self new htmlKWOCListFor:CachedKWIC

    "

     HTMLDocGenerator htmlKWOCList

    "

!

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

    ^ self new 

        generateDocumentForOfflineReading:true;

        htmlClassCategoryList

    "

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

    ^ self new htmlOfflineDocOf:aClass

    "

     HTMLDocGenerator htmlDocOf:Array

     HTMLDocumentView openFullOnText:(HTMLDocGenerator htmlDocOf:Array)

    "

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

!

htmlOfflineIndex

    ^ '<html>

<body>

<ul>

<li><A HREF="packages/index.html">By Package</A>

<li><A HREF="categories/index.html">By Category</A>

<li><A HREF="classes/index.html">By Class Name</A>

</ul>

</body>

</html>

'

!

htmlOfflinePackageList

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

    ^ self new 

        generateDocumentForOfflineReading:true;

        htmlPackageList

    "

     HTMLDocGenerator htmlOfflinePackageList

    "

!

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

    "

    |state newState in out ch part|

    in := wordIn readStream.

    out := '' writeStream.

    [in atEnd] whileFalse:[

        ch := in next.

        (ch isDigit or:[ch == $_]) ifFalse:[

            newState := ch isUppercase.

        ].

        (newState ~~ state) ifTrue:[

            newState == true ifTrue:[

                "/ going from lower- to uppercase

                part := out contents.

                part notEmpty ifTrue:[ aBlock value:part ].

                out :=  '' writeStream.

                out nextPut:ch.

                state := newState.

            ] ifFalse:[

                "/ going upper- to lowercase

                out size <= 1 ifTrue:[

                    out nextPut:ch.

                ] ifFalse:[

                    |prev|

                    prev := out contents.

                    aBlock value:(prev copyButLast).

                    out := '' writeStream.

                    out nextPut:prev last.

                    out nextPut:ch.

                ].    

                state := newState.

            ].    

        ] ifFalse:[

            out nextPut:ch.

        ].    

    ].

    part := out contents.

    part notEmpty ifTrue:[ aBlock value:part ].

!

generateKWIC

    |fillWords kwic|

    fillWords := 

        #(

            'the' 'a'

            'can' 'you' 

            'to' 'in' 'out' 'at' 'of' 

            'also' 'with' 'without' 'all' 'any' 'how' 

            'however' 'although' 'always' 'either' 'neither'

            'anywhere' 'anyway' 'anything' 'anyone'

            'not' 'but' 'else' 'elsewhere'

            'am' 'are' 'is' 'be' 'will' 'wont' 'won''t' 'do' 'don''t'

            'no' 'non' 'now' 'old' 'on' 'only'

            'my' 'their' 'your' 'its'

            'one' 'two' 'three'

            'etc' 'for' 'lot' 'lots' 'made' 'may' 'most' 'mostly' 'much'

            'use' 'this' 'that' 'which' 'what' 'why'

            'or' 'other' 'please'

        ).

    kwic := KeywordInContextIndexBuilder new.

    kwic excluded:fillWords.

    kwic separatorAlgorithm:[:line | 

            line asCollectionOfSubstringsSeparatedByAny:' ^~=@.:,;-+*/()[]|{}#"''<>',Character cr

        ].

    kwic exclusionFilter:[:word | 

                word size == 1

                or:[ word conform:#isDigit ]].

    Smalltalk allClassesDo:[:eachClass |

        eachClass isLoaded ifTrue:[

            |doc|

            doc := eachClass commentOrDocumentationString.

            doc notEmptyOrNil ifTrue:[

                kwic addLine:doc reference:eachClass ignoreCase:true.

            ].    

        ].

    ].

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

    "/ and 'starts' is also there, place the 'startsWith:' entries into the same bin.

    kwic remapKeywordsWith:[:oldKey :knownMappings |

        |newKey|

        6 to:oldKey size - 1 do:[:len |

            newKey isNil ifTrue:[

                |part|

                part := (oldKey copyTo:len).

                (knownMappings includes:part) ifTrue:[

                    newKey := part.

                ].

            ].

        ].

        newKey ? oldKey.

    ].

    ^ kwic

    "

     CachedKWIC := nil.

     self generateKWIC

    "

!

generateKWICForClassAndMethodNames

    |fillWords kwic|