Upgrading from Cocoon 1.0

This page outlines what users of Cocoon 1.0 must do in order to work with the most recent version.

Formatting of Source Code

The good news is that all formatting conventions are the same in later versions, so no source code changes are necessary!

Invoking cocoon

The bad news is that spindoc is no longer around, and the way you invoke the Cocoon utilities has changed. You'll be able to leverage your existing cocoon.ini customization files, but you'll have to create a small amount of new stuff...

...unless...

If you have but a single library, and you simply want to generate all the HTML pages on the directory where the source exists, and you are not using any customization options, there is a special shortcut available to you: go to the directory where your source files are and type in cocoon -l libraryname, where libraryname is, strangely enough, the name of your library. If these special conditions don't hold for you, continue reading...

The big change in using Cocoon is that now all the stuff to generate documentation from single or multiple libraries goes into one easy to use configuration file. This file is fed as input to the cocoon utility:


cocoon  configfile

Full details regarding the configuration file are provided elsewhere, but a brief introduction will be given here. The format of the configfile obeys the same general syntax rules as the customization file of version 1.0--and actually centralizes individual customization data for each library, rather than having them spread around in individual .ini files. The general format is:

		    # generic data for constructing the pages
    webroot   directorypath
    urlroot   url

		    # default customization options for all libraries
    customize
	customization option(s)
    end_customize

		    # library definition (as many as you want)
    library	libname  sourcedir  websubdir
		    # customization overrides for this library
    customize
	customization option(s)
    end_customize

The webroot directory says where, on disk, to put the output HTML files. The urlroot directive gives a partial URL that specifes the web location of that directory. Both should point to the same place, but in different ways. Currently, all directory paths specified in the documentation configuration files must be complete path specifications. Each library indicates a subdirectory path that is appended to both the webroot and urlroot to determine the on-disk location of the HTML page, as well as the URL-path of links to the page, respectively.

The customize sections contain all the customization directives, just as they are specified in version 1.0. The contents of existing cocoon.ini files can be directly pasted into these sections. The first customize section encountered is assumed to be the default customization settings. Individual libraries can specify overrides for all the customization settings except, usetable, namelength, server, and extension: these can only be specified in the default customizations section.

Each library is specified using a library directive, which may optionally be followed by a customization override section. The overrides, if given, will apply only to that library. The library directive must specify the name of the library, the directory path to use to access the source code (all .h files found at that directory will be processed), and a web sub-directory and -url path (see above). Any number of libraries can be specified.

Don't be intimidated by this. Really, the only required stuff are the webroot, urlroot, and library directives--the rest is optional.

As an example, here is a configuration file I use in testing cocoon:

    webroot	/devfiles/kotula/public_html/2html/test
    urlroot	/~kotula/2html/test

    customize
	extension .htm
	usetable
	backcolor white
	logo	/~kotula/bonewhoa.gif
    end_customize

    library	cocoon /devfiles/kotula/public_html/2html cocoon
    customize
	linkcolor red
    end_customize

SO...

Once you've got your configuration file made, just feed it as input to cocoon and watch the magic...

Cocoon 3.0. Created with pride, distributed with fear... by jkotula@unimax.com