proc ::ruff::distill_body {text} {

    # Given a procedure or method body,
    # returns the documentation lines as a list.
    # text - text to be processed to collect all documentation lines.
    # The first block of contiguous comment lines preceding the
    # first line of code are treated as documentation lines.

    set lines {}
    set state init;             # init, collecting or searching
    foreach line [split $text \n] {
        set line [string trim $line]; # Get rid of whitespace
        if {$line eq ""} {
            # Blank lines.
            # If in init state, we will stay in init state
            if {$state ne "init"} {
                set state searching
            }
            continue
        }

        if {[string index $line 0] ne "#"} {
            # Not a comment
            set state searching
            continue
        }

        # At this point, the line is a comment line
        if {$state eq "searching"} {
            #ruff
            # The string #ruff at the beginning of a comment line
            # anywhere in the passed in text is considered the start
            # of a documentation block. All subsequent contiguous
            # comment lines are considered documentation lines.
            if {[string match "#ruff*" $line]} {
                set state collecting
                #ruff
                # Note a #ruff on a line by itself will terminate
                # the previous text block.
                set line [string trimright $line]
                if {$line eq "#ruff"} {
                    lappend lines {}
                } else {
                    #ruff If #ruff is followed by additional text
                    # on the same line, it is treated as a continuation
                    # of the previous text block.
                    lappend lines [string range $line 6 end]
                }
            }
        } else {
            # State is init or collecting

            if {$line eq "#"} {
                # Empty comment line
                lappend lines {}
                continue;       # No change in state
            }

            #ruff
            # The leading comment character and a single space (if present)
            # are trimmed from the returned lines.
            if {[string index $line 1] eq " "} {
                lappend lines [string range $line 2 end]
            } else {
                lappend lines [string range $line 1 end]
            }
            set state collecting
            continue
        }
    }

    # Returns a list of lines that comprise the raw documentation.
    return $lines
}

proc ::ruff::distill_docstring {text} {

    # Splits a documentation string to return the documentation lines
    # as a list.
    # text - documentation string to be parsed


    set lines {}
    set state init
    foreach line [split $text \n] {
        if {[regexp {^\s*$} $line]} {
            #ruff
            # Initial blank lines are skipped and
            # multiple empty lines are compressed into one empty line.
            if {$state eq "collecting"} {
                lappend lines ""
                set state empty
            }
            continue
        }
        #ruff
        # The very first non empty line determines the margin. This will
        # be removed from all subsequent lines. Note that this assumes that
        # if tabs are used for indentation, they are used on all lines
        # in consistent fashion.
        if {$state eq "init"} {
            regexp {^(\s*)\S} $line dontcare prefix
            set prefix_len [string length $prefix]
        }
        set state collecting

        # Remove the prefix if it exists from the line
        if {[string match ${prefix}* $line]} {
            set line [string range $line $prefix_len end]
        }

        lappend lines $line
    }

    # Returns a list of lines.
    return $lines
}

proc ::ruff::document {formatter classprocinfodict {docstrings {}} args} {

    # Generates documentation for the specified namespaces using the
    # specified formatter.
    # formatter - the formatter to be used to produce the documentation
    # classprocinfodict - dictionary containing the metainformation for
    #  classes and procs for which documentation is to be generated. This
    #  must be in the format returned by the extract command.
    # docstrings - a flat list of pairs consisting of a heading and
    #    corresponding content. These are inserted into the document
    #    before the actual class and command descriptions after being
    #    processed by extract_docstring.
    #
    # All additional arguments are passed through to the specified
    # formatter's generate_document command.
    #
    # Returns the documentation string as generated by the specified formatter.

    _load_formatter $formatter

    set preamble [dict create]
    foreach {sec docstring} $docstrings {
        # Treate the preamble as a "toplevel" preamble
        dict lappend preamble "::" $sec [extract_docstring $docstring]
    }

    return [eval [list [namespace current]::formatter::${formatter}::generate_document $classprocinfodict -preamble $preamble] $args]
}

proc ::ruff::document_namespace {formatter ns args} {

    # Obsolete, use document_namespaces instead.
    return [eval [list document_namespaces $formatter [list $ns] -title $ns] $args]
}

proc ::ruff::document_namespaces {formatter namespaces args} {

    # Generates documentation for the specified namespaces using the
    # specified formatter.
    # formatter - the formatter to be used to produce the documentation
    # namespaces - list of namespaces for which documentation is to be generated
    # -includeclasses BOOLEAN - if true (default), class information
    #     is collected
    # -includeprocs BOOLEAN - if true (default), proc information is
    #     collected
    # -includeprivate BOOLEAN - if true private methods are also included
    #  in the generated documentation. Default is false.
    # -includesource BOOLEAN - if true, the source code of the
    #  procedure is also included. Default value is false.
    # -output PATH - if specified, the generated document is written
    #  to the specified file which will overwritten if it already exists.
    # -append BOOLEAN - if true, the generated document is appended
    #  to the specified file instead of overwriting it.
    # -title STRING - specifies the title to use for the page
    # -recurse BOOLEAN - if true, child namespaces are recursively
    #  documented.
    #
    # Any additional arguments are passed through to the document command.
    #
    # Returns the documentation string if the -output option is not
    # specified, otherwise returns an empty string after writing the
    # documentation to the specified file.

    array set opts {
        -includeclasses true
        -includeprocs true
        -includeprivate false
        -includesource false
        -output ""
        -append false
        -title ""
        -recurse false
    }
    array set opts $args

    if {$opts(-recurse)} {
        set namespaces [_namespace_tree $namespaces]
    }

    set preamble [dict create]
    foreach ns $namespaces {
        if {[info exists ${ns}::_ruffdoc]} {
            foreach {section docstring} [set ${ns}::_ruffdoc] {
                dict lappend preamble $ns $section [extract_docstring $docstring]
            }
        }
    }

    set classprocinfodict [extract_namespaces $namespaces  -includeclasses $opts(-includeclasses)  -includeprocs $opts(-includeprocs)  -includeprivate $opts(-includeprivate)]

    _load_formatter $formatter
    set doc  [eval  [list formatter::${formatter}::generate_document  $classprocinfodict  -preamble $preamble  -modulename $opts(-title)  ]  $args]
    if {$opts(-output) ne ""} {
        if {$opts(-append)} {
            set fd [open $opts(-output) a]
        } else {
            set fd [open $opts(-output) w]
        }
        if {[catch {
            puts $fd $doc
        } msg]} {
            close $fd
            error $msg
        }
        close $fd
        return
    } else {
        return $doc
    }
}

proc ::ruff::document_self {formatter output_dir args} {

    # Generates documentation for Ruff!
    # formatter - the formatter to use
    # output_dir - the output directory where files will be stored. Note
    #  files in this directory with the same name as the output files
    #  will be overwritten!
    # -formatterpath PATH - path to the formatter. If unspecified, the
    #  the input files for the formatter are generated but the formatter
    #  is not run. This option is ignore for the built-in HTML formatter.
    # -includesource BOOLEAN - if true, include source code in documentation.

    variable names

    array set opts {
        -formatterpath ""
        -includesource FALSE
    }
    array set opts $args

    _load_all_formatters;       # So all will be documented!

    set modules [dict create]
    # Enumerate and set the descriptive text for all the modules.
    # TBD - use these settings to generate preambles for the modules
    dict set modules ::ruff  [dict create description "$names(display) main module"]
    dict set modules ::ruff::formatter  [dict create description "$names(display) formatters"]
    dict set modules ::ruff::formatter::doctools  [dict create description "$names(display) formatter for Doctools"]
    dict set modules ::ruff::formatter::naturaldocs  [dict create description "$names(display) formatter for NaturalDocs"]
    dict set modules ::ruff::formatter::robodoc  [dict create description "$names(display) formatter for ROBODoc"]
    dict set modules ::ruff::formatter::html  [dict create description "$names(display) formatter for HTML"]
    dict set modules ::ruff::app  [dict create description "$names(display) application callbacks"]

    file mkdir $output_dir
    if {$formatter ne "html"} {
        # For external formatters, we need input and output directories
        set outdir [file join $output_dir output]
        set indir  [file join $output_dir Ruff]
        file mkdir $indir;  # Input for formatter, output for us!
        file mkdir $outdir
    }
    switch -exact -- $formatter {
        naturaldocs {
            set projdir [file join $output_dir proj]
            file mkdir $projdir
            dict for {ns nsdata} $modules {
                set fn [string map {:: _} [string trimleft $ns :]]
                set fn "[file join $indir $fn].tcl"
                document_namespace naturaldocs $ns -output $fn -hidenamespace $ns
            }
            # We want to change the stylesheet for NaturalDocs
            set fd [open [file join $projdir ruff.css] w]
            puts $fd "p { text-indent: 0; margin-bottom: 1em; }"
            puts $fd "blockquote {margin-left: 5em;}"
            close $fd
            if {$opts(-formatterpath) ne ""} {
                if {[catch {
                    eval exec $opts(-formatterpath) [list --input $indir  --output HTML $outdir  --project $projdir  --rebuild  --style Default ruff  ]
                } msg]} {
                    app::log_error "Error executing NaturalDocs using path '$opts(-formatterpath)': $msg"
                }
            }
        }
        doctools {
            dict for {ns nsdata} $modules {
                set fn [string map {:: _} [string trimleft $ns :]]
                set fn "[file join $indir $fn].man"
                document_namespace doctools $ns -output $fn -hidenamespace $ns  -name $ns  -keywords [list "documentation generation"]  -modulename $ns  -titledesc [dict get $nsdata description]  -version $::ruff::version
            }
            if {$opts(-formatterpath) ne ""} {
                if {[catch {
                    eval exec $opts(-formatterpath) [list -o $outdir html $indir]
                } msg]} {
                    app::log_error "Error executing doctools using path '$opts(-formatterpath)': $msg"
                }
            }
        }
        html {
            # Note here we use $output_dir since will directly produce HTML
            # and not intermediate files
            document_namespaces html ::ruff -recurse true  -output [file join $output_dir ruff.html]  -titledesc "Ruff! - Runtime Formatting Function Reference (V$::ruff::version)"  -copyright "[clock format [clock seconds] -format %Y] Ashok P. Nadkarni"  -includesource $opts(-includesource)
        }
        default {
            # The formatter may exist but we do not support it for
            # out documentation.
            error "Formatter '$formatter' not implemented for generating Ruff! documentation."
        }
    }
    return
}

proc ::ruff::extract {pattern args} {

    # Extracts metainformation for procs and classes
    #
    # pattern - glob-style pattern to match against procedure and class names
    # -includeclasses BOOLEAN - if true (default), class information
    #     is collected
    # -includeprocs - if true (default), proc information is
    #     collected
    # -includeprivate BOOLEAN - if true private methods are also included.
    #  Default is false.
    #
    # The value of the classes key in the returned dictionary is
    # a dictionary whose keys are class names and whose corresponding values
    # are in the format returned by extract_ooclass.
    # Similarly, the procs key contains a dictionary whose keys
    # are proc names and whose corresponding values are in the format
    # as returned by extract_proc.
    #
    # Note that only the program elements in the same namespace as
    # the namespace of $pattern are returned.
    #
    # Returns a dictionary with keys 'classes' and 'procs'

    array set opts {
        -includeclasses true
        -includeprocs true
        -includeprivate false
        -includeimports false
    }
    array set opts $args

    set classes [dict create]
    if {$opts(-includeclasses)} {
        # We do a catch in case this Tcl version does not support objects
        set class_names {}
        catch {set class_names [info class instances ::oo::class $pattern]}
        foreach class_name $class_names {
            # This covers child namespaces as well which we do not want
            # so filter those out. The differing pattern interpretations in
            # Tcl commands 'info class instances' and 'info procs'
            # necessitates this.
            if {[namespace qualifiers $class_name] ne [namespace qualifiers $pattern]} {
                # Class is in not in desired namespace
                # TBD - do we need to do -includeimports processing here?
                continue
            }
            # Names beginning with _ are treated as private
            if {(!$opts(-includeprivate)) &&
                [string index [namespace tail $class_name] 0] eq "_"} {
                continue
            }

            if {[catch {
                set class_info [extract_ooclass $class_name -includeprivate $opts(-includeprivate)]
            } msg]} {
                app::log_error "Could not document class $class_name"
            } else {
                dict set classes $class_name $class_info
            }
        }
    }

    set procs [dict create]
    if {$opts(-includeprocs)} {
        foreach proc_name [info procs $pattern] {
            #ruff
            # -includeimports BOOLEAN - if true commands imported from other
            #  namespaces are also included. Default is false.
            if {(! $opts(-includeimports)) &&
                [namespace origin $proc_name] ne $proc_name} {
                continue;       # Do not want to include imported commands
            }
            # Names beginning with _ are treated as private
            if {(!$opts(-includeprivate)) &&
                [string index [namespace tail $proc_name] 0] eq "_"} {
                continue
            }

            if {[catch {
                set proc_info [extract_proc $proc_name]
            } msg]} {
                app::log_error "Could not document proc $proc_name"
            } else {
                dict set procs $proc_name $proc_info
            }
        }
    }

    return [dict create classes $classes procs $procs]
}

proc ::ruff::extract_docstring {text} {

    # Parses a documentation string to return a structured text representation.
    # text - documentation string to be parsed
    #
    # The command extracts structured text from the given string
    # as described in the documentation for the distill_docstring
    # and parse commands. The result is further processed to
    # return a list of type and value elements described below:
    # deflist - the corresponding value is another list containing
    #   definition item name and its value as a string.
    # bulletlist - the corresponding value is a list of strings
    #   each being one list item.
    # paragraph - the corresponding value is a string comprising
    #   the paragraph.
    # preformatted - the corresponding value is a string comprising
    #   preformatted text.


    set paragraphs {}

    # Loop and construct the documentation
    foreach {type content} [parse [distill_docstring $text]] {
        switch -exact -- $type {
            deflist {
                # Each named list is a list of pairs
                set deflist {}
                foreach {name desc} $content {
                    lappend deflist $name [join $desc " "]
                }
                lappend paragraphs deflist $deflist
            }
            bulletlist {
                # Bullet lists are lumped with paragraphs
                set bulletlist {}
                foreach desc $content {
                    lappend bulletlist [join $desc " "]
                }
                lappend paragraphs bulletlist $bulletlist
            }
            summary {
                # Do nothing. Summaries are same as the first
                # paragraph. For docstrings, we do not show
                # them separately like we do for procs
            }
            paragraph {
                lappend paragraphs paragraph [join $content " "]
            }
            preformatted {
                lappend paragraphs preformatted [join $content \n]
            }
            default {
                error "Text fragments of type '$type' not supported in docstrings"
            }
        }
    }
    return $paragraphs
}

proc ::ruff::extract_namespace {ns args} {

    # Extracts metainformation for procs and objects in a namespace
    # ns - namespace to examine
    #
    # Any additional options are passed on to the extract command.
    #
    # Returns a dictionary with keys 'classes' and 'procs'. See ruff::extract
    # for details.

    return [eval [list extract ${ns}::*] $args]
}

proc ::ruff::extract_namespaces {namespaces args} {

    # Extracts metainformation for procs and objects in one or more namespace
    # namespaces - list of namespace to examine
    #
    # Any additional options are passed on to the extract_namespace command.
    #
    # Returns a dictionary with keys 'classes' and 'procs'. See ruff::extract
    # for details.

    set procs [dict create]
    set classes [dict create]
    foreach ns $namespaces {
        set nscontent [eval [list extract ${ns}::*] $args]
        set procs   [dict merge $procs [dict get $nscontent procs]]
        set classes [dict merge $classes [dict get $nscontent classes]]
    }
    return [dict create procs $procs classes $classes]
}

proc ::ruff::extract_ooclass {classname args} {

    # Extracts metainformation about the specified class
    # classname - name of the class to be documented
    # -includeprivate BOOLEAN - if true private methods are also included
    #  in the metainformation. Default is false.
    #
    # The metainformation. returned is in the form of a dictionary with
    # the following keys:
    # name - name of the class
    # methods - a list of method definitions for this class in the form
    #  returned by extract_ooclass_method with the additional key
    #  'visibility' which may have values 'public' or 'private'.
    # external_methods - a list of names of methods that are
    #  either inherited or mixed in
    # filters - a list of filters defined by the class
    # forwards - a list of forwarded methods, each element in the
    #  list being a dictionary with keys 'name' and 'forward'
    #  corresponding to the forwarded method name and the forwarding command.
    # mixins - a list of names of classes mixed into the class
    # superclasses - a list of names of classes which are direct
    #   superclasses of the class
    # subclasses - a list of classes which are direct subclasses of this class
    # constructor - method definition for the constructor in the format
    #   returned by extract_ooclass_method
    # destructor - method definition for the destructor
    #   returned by extract_ooclass_method
    #
    # Each method definition is in the format returned by the
    # extract_ooclass_method command with an additional keys:
    # visibility - indicates whether the method is 'public' or 'private'

    array set opts {-includeprivate false}
    array set opts $args

    set result [dict create methods {} external_methods {}  filters {} forwards {}  mixins {} superclasses {} subclasses {}  name $classname  ]

    if {$opts(-includeprivate)} {
        set all_local_methods [info class methods $classname -private]
        set all_methods [info class methods $classname -all -private]
    } else {
        set all_local_methods [info class methods $classname]
        set all_methods [info class methods $classname -all]
    }
    set public_methods [info class methods $classname -all]
    set external_methods {}
    foreach name $all_methods {
        set implementing_class [locate_ooclass_method $classname $name]
        if {[lsearch -exact $all_local_methods $name] < 0} {
            # Skip the destroy method which is standard and
            # appears in all classes.
            if {$implementing_class ne "::oo::object" ||
                $name ne "destroy"} {
                lappend external_methods [list $name $implementing_class]
            }
            continue
        }

        # Even if a local method, it may be hidden by a mixin
        if {$implementing_class ne $classname} {
            # TBD - should we make a note in the documentation somewhere ?
            app::log_error "Method $name in class $classname is hidden by class $implementing_class."
        }

        if {[lsearch -exact $public_methods $name] >= 0} {
            set visibility public
        } else {
            set visibility private
        }

        if {! [catch {
            set method_info [extract_ooclass_method $classname $name]
        } msg]} {
            dict set method_info visibility $visibility
            #dict set method_info name $name
            dict lappend result methods $method_info
        } else {
            # Error, may be it is a forwarded method
            if {! [catch {
                set forward [info class forward $classname $name]
            }]} {
                dict lappend result forwards [dict create name $name forward $forward]
            } else {
                ruff::app::log_error "Could not introspect method $name in class $classname"
            }
        }
    }

    foreach name {constructor destructor} {
        if {[info class $name $classname] ne ""} {
            # Class has non-empty constructor or destructor
            dict set result $name [extract_ooclass_method $classname $name]
        }
    }

    dict set result name $classname;   # TBD - should we fully qualify this?
    dict set result external_methods $external_methods
    dict set result filters [info class filters $classname]
    dict set result mixins [info class mixins $classname]
    dict set result subclasses [info class subclasses $classname]
    # We do not want to list ::oo::object which is a superclass
    # of all classes.
    set classes {}
    foreach class [info class superclasses $classname] {
        if {$class ne "::oo::object"} {
            lappend classes $class
        }
    }
    dict set result superclasses $classes

    return $result
}

proc ::ruff::extract_ooclass_method {class method} {


    # Extracts metainformation for the method in oo:: class
    # class - name of the class
    #
    # The command retrieves metainformation about
    # a Tcl class method. See the command extract_proc_or_method
    # for details.
    #
    # Returns a dictionary containing documentation related to the command.
    #


    switch -exact -- $method {
        constructor {
            foreach {params body} [info class constructor $class] break
        }
        destructor  {
            set body [lindex [info class destructor $class] 0]
            set params {}
        }
        default {
            foreach {params body} [info class definition $class $method] break
        }
    }


    set param_names {}
    set param_defaults {}
    foreach param $params {
        lappend param_names [lindex $param 0]
        if {[llength $param] > 1} {
            lappend param_defaults [lindex $param 0] [lindex $param 1]
        }
    }

    return [extract_proc_or_method method $method $param_names $param_defaults $body $class]
}

proc ::ruff::extract_proc {procname} {


    # Extracts meta information from a Tcl procedure.
    # procname - name of the procedure
    #
    # The command retrieves metainformation about
    # a Tcl procedure. See the command extract_proc_or_method
    # for details.
    #
    # Returns a dictionary containing metainformation for the command.
    #

    set param_names [info args $procname]
    set param_defaults {}
    foreach name $param_names {
        if {[info default $procname $name val]} {
            lappend param_defaults $name $val
        }
    }
    return [extract_proc_or_method proc $procname [info args $procname] $param_defaults [info body $procname]]
}

proc ::ruff::extract_proc_or_method {proctype procname param_names param_defaults body {class {}}} {

    # Helper procedure used by extract_proc and extract_ooclass_method to
    # construct metainformation for a method or proc.
    #  proctype - should be either 'proc' or 'method'
    #  procname - name of the proc or method
    #  param_names - list of parameter names in order
    #  param_defaults - list of parameter name and default values
    #  body - the body of the proc or method
    #  class - the name of the class to which the method belongs. Not used
    #   for proc types.
    #
    # The command parses the $body parameter as described by the distill_body
    # and parse commands and then constructs the metainformation for
    # the proc or method using this along with the other passed arguments.
    # The metainformation is returned as a dictionary with the following keys:
    #   name - name of the proc or method
    #   parameters - a list of parameters. Each element of the
    #     list is a pair or a triple, consisting of the parameter name,
    #     the description and possibly the default value if there is one.
    #   options - a list of options. Each element is a pair consisting
    #     of the name and its description.
    #   description - a list of paragraphs describing the command. The
    #     list contains preformatted, paragraph, bulletlist and deflist
    #     elements as described for the extract_docstring command.
    #   return - a description of the return value of the command
    #   summary - a copy of the first paragraph if it was present
    #     before the parameter descriptions.
    #   source - the source code of the command
    #

    array set param_default $param_defaults
    array set params {}
    array set options {}
    set paragraphs {}

    # Loop and construct the documentation
    foreach {type content} [parse [distill_body $body]] {
        switch -exact -- $type {
            parameter {
                # For each parameter, check if it is a
                # parameter in the proc/method definition
                foreach {name desc} $content {
                    if {[lsearch -exact $param_names $name] >= 0} {
                        set params($name) [join $desc " "]
                    } else {
                        #TBD - how to handle this? For now, assume it's
                        #a parameter as well
                        app::log_error "Parameter '$name' not listed in arguments for '$procname'"
                        set params($name) [join $desc " "]
                    }
                }
            }
            summary -
            return {
                set doc($type) [join $content " "]
            }
            deflist {
                # Named lists are lumped with paragraphs
                # Each named list is a list of pairs
                set deflist {}
                foreach {name desc} $content {
                    lappend deflist $name [join $desc " "]
                }
                lappend paragraphs deflist $deflist
            }
            bulletlist {
                # Bullet lists are lumped with paragraphs
                set bulletlist {}
                foreach desc $content {
                    lappend bulletlist [join $desc " "]
                }
                lappend paragraphs bulletlist $bulletlist
            }
            option {
                foreach {name desc} $content {
                    if {[lsearch -exact $param_names "args"] < 0} {
                        app::log_error "Documentation for '$procname' contains option '$name' but the procedure definition does not have an 'args' parameter"
                    }
                    set options($name) [join $desc " "]
                }
            }
            paragraph {
                lappend paragraphs paragraph [join $content " "]
            }
            preformatted {
                lappend paragraphs preformatted [join $content \n]
            }
            default {
                error "Unknown text fragment type '$type'."
            }
        }
    }

    set doc(name)        $procname
    set doc(class)       $class
    set doc(description) $paragraphs
    set doc(proctype)    $proctype

    # Construct parameter descriptions. Note those not listed in the
    # actual proc definition are left out even if they are in the params
    # table
    set doc(parameters) {}
    foreach name $param_names {
        if {[info exists params($name)]} {
            set paramdata [dict create name $name description $params($name) type parameter]
        } else {
            set paramdata [dict create name $name type parameter]
        }

        # Check if there is a default
        if {[info exists param_default($name)]} {
            dict set paramdata default $param_default($name)
        }

        lappend doc(parameters) $paramdata
    }

    # Add the options into the parameter table
    foreach name [lsort [array names options]] {
        lappend doc(parameters) [dict create name $name description $options($name) type option]
    }

    set source "$proctype $procname "
    set param_list {}
    foreach name $param_names {
        if {[info exists param_default($name)]} {
            lappend param_list [list $name $param_default($name)]
        } else {
            lappend param_list $name
        }
    }


    append source "{$param_list} {\n"
    # We need to reformat the body. If nested inside a namespace eval
    # for example, the body will be indented too much. So we undent the
    # least indented line to 0 spaces and then add 4 spaces for each line.
    append source [::textutil::adjust::indent [::textutil::adjust::undent $body] "    "]
    append source "\n}"
    set doc(source) $source

    return [eval dict create [array get doc]]
}

proc ::ruff::formatters {} {

    # Get the list of supported formatters.
    #
    # Ruff! can produce documentation in several formats each of which
    # is produced by a specific formatter. This command returns the list
    # of such formatters that can be used with commands like
    # document.
    #
    # Returns a list of available formatters.
    variable ruff_dir
    set formatters {}
    set suffix "_formatter.tcl"
    foreach file [glob [file join $ruff_dir *$suffix]] {
        lappend formatters [string range [file tail $file] 0 end-[string length $suffix]]
    }
    return $formatters
}

proc ::ruff::get_ooclass_method_path {class_name method_name} {

    # Calculates the class search order for a method of the specified class
    # class_name - name of the class to which the method belongs
    # method_name - method name being searched for
    #
    # A method implementation may be provided by the class itself,
    # a mixin or a superclass.
    # This command calculates the order in which these are searched
    # to locate the method. The primary purpose is to find exactly
    # which class actually implements a method exposed by the class.
    #
    # If a class occurs multiple times due to inheritance or
    # mixins, the LAST occurence of the class is what determines
    # the priority of that class in method selection. Therefore
    # the returned search path may contain repeated elements.
    #
    # Note that this routine only applies to a class and cannot be
    # used with individual objects which may have their own mix-ins.


    # TBD - do we need to distinguish private/public methods

    set method_path {}
    #ruff
    # Search algorithm:
    #  - Filters are ignored. They may be invoked but are not considered
    #    implementation of the method itself.
    #  - The mixins of a class are searched even before the class itself
    #    as are the superclasses of the mixins.
    foreach mixin [info class mixins $class_name] {
        # We first need to check if the method name is in the public interface
        # for this class. This step is NOT redundant since a derived
        # class may unexport a method from an inherited class in which
        # case we should not have the inherited classes in the path
        # either.
        if {[lsearch -exact [info class methods $mixin -all] $method_name] < 0} {
            continue
        }

        set method_path [concat $method_path [get_ooclass_method_path $mixin $method_name]]
    }

    #ruff - next in the search path is the class itself
    if {[lsearch -exact [info class methods $class_name] $method_name] >= 0} {
        lappend method_path $class_name
    }

    #ruff - Last in the search order are the superclasses (in recursive fashion)
    foreach super [info class superclasses $class_name] {
        # See comment in mixin code above.
        if {[lsearch -exact [info class methods $super -all] $method_name] < 0} {
            continue
        }
        set method_path [concat $method_path [get_ooclass_method_path $super $method_name]]
    }


    #ruff
    # Returns an ordered list containing the classes that are searched
    # to locate a method for the specified class.
    return $method_path
}

proc ::ruff::locate_ooclass_method {class_name method_name} {

    # Locates the classe that implement the specified method of a class
    # class_name - name of the class to which the method belongs
    # method_name - method name being searched for
    #
    # The matching class may implement the method itself or through
    # one of its own mix-ins or superclasses.
    #
    # Returns the name of the implementing class or an empty string
    # if the method is not implemented.

    # Note: we CANNOT just calculate a canonical search path for a
    # given class and then search along that for a class that
    # implements a method. The search path itself will depend on the
    # specific method being searched for due to the fact that a
    # superclass may not appear in a particular search path if a
    # derived class hides a method (this is just one case, there may
    # be others). Luckily, get_ooclass_method_path does exactly this.


    set class_path [get_ooclass_method_path $class_name $method_name]

    if {[llength $class_path] == 0} {
        return "";              # Method not found
    }

    # Now we cannot just pick the first element in the path. We have
    # to find the *last* occurence of each class - that will decide
    # the priority order
    set order [dict create]
    set pos 0
    foreach path_elem $class_path {
        dict set order $path_elem $pos
        incr pos
    }

    return [lindex $class_path [lindex [lsort -integer [dict values $order]] 0] 0]
}

proc ::ruff::parse {lines} {

    # Creates a parse structure given a list of lines that are assumed
    # to be documentation for a programming structure
    #
    # lines - a list of lines comprising the documentation
    #
    set result(name) ""
    set result(listcollector) {}
    set result(fragment) {}
    set result(state) init
    set result(output) {}
    foreach line $lines {
        switch -regexp -- $line {
            {^\s*$} {
                #ruff
                # Empty lines or lines with only whitespace
                # terminate the preceding
                # text block (such as a paragraph or a list).
                switch -exact -- $result(state) {
                    init -
                    postsummary {
                        # No change
                    }
                    summary {
                        _change_state postsummary result
                    }
                    default {
                        _change_state blank result
                    }
                }
            }
            {^\s*[-\*]\s+(.*)$} {
                #ruff
                # A bulleted list item starts with a '-' or '*' character.
                # A list item may be continued across multiple lines by
                # indending succeeding lines belonging to the same list item.
                # Note an indented line will terminate the previous list
                # item if it itself looks like a new list item.
                # A bulleted
                # list is returned as a list containing the list items, each
                # of which is a list of lines.
                _change_state bulletlist result
                if {![regexp {^\s*[-\*]\s+(.*)$} $line dontcare fragment]} {
                    error "Internal error: regexp did not match after switch statement matched."
                }
                lappend result(fragment) $fragment
            }
            {^\s*(\w+)\s+-(\s+.*)$} {
                #ruff
                # A definition list or parameter list begins with a word
                # followed by whitespace, a '-' character, whitespace
                # and descriptive
                # text. Whether it is treated as a parameter list or a
                # definition list depends on whether it occurs in the comment
                # block. If it occurs at the beginning or just after the
                # summary line, it is treated as a parameter list.
                # In all other cases, it is treated as a definition list.
                # Like a bulleted list, each list item may be continued
                # on succeeding lines by indenting them.
                # Definition and parameter lists
                # are returned as flat list
                # of alternating list item name and list item value
                # pairs. The list item value is itself a list of lines.
                if {[lsearch -exact {init summary postsummary parameter} $result(state)] >= 0} {
                    _change_state parameter result
                } else {
                    _change_state deflist result
                }
                if {![regexp {^\s*(\w+)\s+-(\s+.*)$} $line dontcare result(name) fragment]} {
                    error "Internal error: regexp did not match after switch statement matched."
                }
                lappend result(fragment) $fragment
            }
            {^\s*(-\w+.*)\s+-(\s+.*)$} {
                #ruff
                # An option list is similar to a parameter list except that
                # the first word on the line begins with a '-' character and
                # is possibly followed by more words before the '-' character
                # that separates the descriptive text. The '-' separator
                # must be surrounded by whitespace. The value returned
                # for an option list follows the same structure as for
                # parameter or definition list items. Any line in any
                # documentation block that matches this is always added
                # to the option list, irrespective of where it occurs. This
                # means option descriptions can be mingled with other
                # documentation fragments and will show up in the options
                # section.

                _change_state option result

                if {![regexp {^\s*(-\w+.*)\s+-(.*)$} $line dontcare result(name) fragment]} {
                    error "Internal error: regexp did not match after switch statement matched."
                }
                lappend result(fragment) $fragment
            }
            {^Returns($|\s.*$)} {
                #ruff
                # Any paragraph that begins with the word 'Returns' is treated
                # as a description of the return value irrespective of where
                # it occurs. It is returned as a list of lines.
                _change_state return result
                lappend result(fragment) $line
            }
            {^\s+} {
                #ruff
                # Lines beginning with spaces
                # are treated as preformatted text unless they are part
                # of a list item. Preformatted text is returned as a list
                # of lines.
                switch -exact -- $result(state) {
                    preformatted -
                    bulletlist -
                    deflist -
                    parameter -
                    option {
                        # No change. Keep adding to existing block
                    }
                    default {
                        _change_state preformatted result
                    }
                }
                lappend result(fragment) $line
            }
            default {
                #ruff
                # All other text blocks are descriptive text paragraphs.
                # Paragraphs may extend across multiple lines and are
                # terminated either when the line matches one of the list
                # items patterns, an indented line (which is treated
                # as preformatted text), or an empty line. Paragraphs
                # are returned as a list of lines.

                switch -exact -- $result(state) {
                    init { _change_state summary result }
                    postsummary -
                    blank -
                    bulletlist -
                    parameter -
                    deflist -
                    option -
                    preformatted { _change_state paragraph result }
                    default {
                        # Stay in same state
                    }
                }
                lappend result(fragment) $line
            }
        }
    }
    _change_state finish result; # To process any leftovers in result(fragment)

    # Returns a list of key value pairs where key is one
    # of 'parameter', 'option', 'bulletlist', 'deflist', 'parameter',
    # 'preformatted', 'paragraph' or 'return',
    # and the value
    # is the corresponding value.
    return $result(output)
}

proc ::ruff::app::log_error {msg} {

    # Stub function to log Ruff! errors.
    # msg - the message to be logged
    #
    # When Ruff! encounters errors, it calls this command to
    # notify the user. By default, the command writes $msg
    # to stderr output. An application using the ruff package
    # can redefine this command after loading ruff.
    puts stderr "$msg"
}

proc ::ruff::formatter::doctools::escape {s} {

    # s - string to be escaped
    # Protects a string against doctools substitution in text
    # (not to be used inside a doctools command argument as that
    # follows Tcl escaping rules and are easiest escaped by enclosing
    # in braces)

    # It appears as though the only characters needing replacing are
    # [ and ]. Other Tcl special chars ($ \ etc.) do not matter
    # return [string map [list \\ \\\\ \[ \[lb\] \] \[rb\] \$ \\\$] $s]
    return [string map [list \[ \[lb\] \] \[rb\]] $s]
}

proc ::ruff::formatter::doctools::generate_document {classprocinfodict args} {

    # Produces documentation in doctools format from the passed in
    # class and proc metainformation.
    #   classprocinfodict - dictionary containing meta information about the
    #     classes and procs
    #
    # In addition to options described in the ruff::document command,
    # the following additional ones may be specified:
    #   -preamble DICT - a dictionary indexed by a namespace. Each value is
    #    a flat list of pairs consisting of a heading and
    #    corresponding content. These are inserted into the document
    #    before the actual class and command descriptions for a namespace.
    #    The key "::" corresponds to documentation to be printed at
    #    the very beginning.
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.

    array set opts  [list  -includeclasses true  -includeprocs true  -includeprivate false  -includesource false  -hidenamespace ""  -section "n"  -version "0.0"  -name ""  -titledesc ""  -modulename ""  -require {}  -author ""  -keywords {}  -year [clock format [clock seconds] -format %Y]  -preamble [dict create]  ]

    array set opts $args

    # TBD - does anything need to be escape'ed here?
    set doc "\[manpage_begin \"$opts(-name)\" \"$opts(-section)\" \"$opts(-version)\"\]\n"
    if {$opts(-author) ne ""} {
        append doc "\[copyright {$opts(-year) \"$opts(-author)\"}\]\n"
    }
    if {$opts(-titledesc) ne ""} {
        append doc "\[titledesc \"$opts(-titledesc)\"\]\n"
    }
    if {$opts(-modulename) ne ""} {
        append doc "\[moddesc \"$opts(-modulename)\"\]\n"
    }
    if {[llength $opts(-require)]} {
        foreach require $opts(-require) {
            append doc "\[require $require\]\n"
        }
    }

    # Begin the description section
    append doc "\[description\]\n"

    if {[dict exists $opts(-preamble) "::"]} {
        # Print the toplevel (global stuff)
        foreach {sec paras} [dict get $opts(-preamble) "::"] {
            append doc [subsection $sec]
            append doc [_fmtparas $paras]
        }
    }

    set info_by_ns [_sift_classprocinfo $classprocinfodict]

    foreach ns [lsort -dictionary [dict keys $info_by_ns]] {
        append doc [section "Module $ns"]
        if {[dict exists $opts(-preamble) $ns]} {
            foreach {sec paras} [dict get $opts(-preamble) $ns] {
                append doc [section $sec]
                append doc [_fmtparas $paras]
            }
        }

        if {[dict exists $info_by_ns $ns classes]} {
            append doc [section Classes]\n
            append doc [generate_ooclasses [dict get $info_by_ns $ns classes]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  ]
        }
        if {[dict exists $info_by_ns $ns procs]} {
            append doc [section Commands]\n
            append doc [generate_procs [dict get $info_by_ns $ns procs]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  ]
        }
    }

    if {[llength $opts(-keywords)] == 0} {
        # dtplite will barf if no keywords in man page. Logged on sf.net
        # as a bug against doctools
        ::ruff::app::log_error "Warning: no keywords specified in this module. If no modules have keywords some versions of the doctools indexer may generate an error in some modes."
    }

    if {[llength $opts(-keywords)]} {
        append doc [eval keywords $opts(-keywords)]
    }


    append doc "\[manpage_end\]\n"

    return $doc
}

proc ::ruff::formatter::doctools::generate_ooclass {classinfo args} {


    # Formats the documentation for a class in doctools format
    # classinfo - class information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #
    # Returns the class documentation as a doctools formatted string.

    array set opts {-includesource false -hidenamespace ""}
    array set opts $args

    array set aclass $classinfo
    set doc ""

    # The quoting of strings below follows what I understand of doctools
    # - only [ and ] are special in text outside of doctools commands.
    # Such strings are quoted using the escape command. Arguments to
    # doctools commands are quoted using {}.

    set class_name [_trim_namespace $aclass(name) $opts(-hidenamespace)]
    set displayprefix "$class_name."

    append doc [section "Class $class_name"]

    if {[info exists aclass(constructor)]} {
        append doc [list_begin definitions]
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -displayprefix $displayprefix]
        append doc [list_end]
    }


    if {[llength $aclass(superclasses)]} {
        append doc [subsection "Superclasses"]
        # Don't sort - order matters!
        append doc [escape [join [_trim_namespace_multi $aclass(superclasses) $opts(-hidenamespace)]]]\n
    }
    if {[llength $aclass(subclasses)]} {
        append doc [subsection "Subclasses"]
        # Don't sort - order matters!
        append doc [escape [join [_trim_namespace_multi $aclass(subclasses) $opts(-hidenamespace)]]]\n
    }
    if {[llength $aclass(mixins)]} {
        append doc [subsection "Mixins"]
        # Don't sort - order matters!
        append doc [escape [join [_trim_namespace_multi $aclass(mixins) $opts(-hidenamespace)]]]\n
    }
    if {[llength $aclass(filters)]} {
        append doc [subsection "Filters"]
        # Don't sort - order matters!
        append doc [escape [join $aclass(filters) ", "]]\n
    }
    if {[llength $aclass(external_methods)]} {
        append doc [subsection "External Methods"]
        set external_methods {}
        foreach external_method $aclass(external_methods) {
            # Qualify the name with the name of the implenting class
            foreach {name imp_class} $external_method break
            if {$imp_class ne ""} {
                set name [_trim_namespace $imp_class $opts(-hidenamespace)].$name
            }
            lappend external_methods $name
        }
        append doc [escape [join [lsort $external_methods] ", "]]\n
    }

    append doc [subsection Methods]

    append doc [list_begin definitions]
    if {0} {
        # We are showing constructor as part of class definition
        if {[info exists aclass(constructor)]} {
            append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -displayprefix $displayprefix]
        }
    }
    if {[info exists aclass(destructor)]} {
        append doc [generate_proc_or_method $aclass(destructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -displayprefix $displayprefix]
    }

    # We want methods and forwarded methods listed together and sorted
    array set methods {}
    foreach methodinfo $aclass(methods) {
        set methods([dict get $methodinfo name]) [list method $methodinfo]
    }
    if {[info exists aclass(forwards)]} {
        foreach forwardinfo $aclass(forwards) {
            set methods([dict get $forwardinfo name]) [list forward $forwardinfo]
        }
    }

    foreach name [lsort [array names methods]] {
        foreach {type info} $methods($name) break
        if {$type eq "method"} {
            append doc [generate_proc_or_method $info  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -displayprefix $displayprefix]
        } else {
            # TBD - check formatting of forwarded methods
            # append doc [call [cmd "${displayprefix}[_trim_namespace [dict get $info name] $opts(-hidenamespace)]"]]
            append doc [call "[arg OBJECT] [cmd $name]"]
            # TBD - link to forwarded method if possible
            append doc "Method forwarded to [cmd [escape [dict get $info forward]]].\n"
        }
    }
    append doc [list_end]

    return $doc
}

proc ::ruff::formatter::doctools::generate_ooclasses {classinfodict args} {

    # Given a list of class information elements returns as string
    # containing class documentation formatted for doctools
    # classinfodict - dictionary keyed by class name and each element
    #   of which is in the format returned by extract_ooclass
    #
    # Additional parameters are passed on to the generate_ooclass procedure.

    set doc ""
    foreach name [lsort [dict keys $classinfodict]] {
        append doc  [eval [list generate_ooclass [dict get $classinfodict $name]] $args]
        append doc "\n\n"
    }
    return $doc
}

proc ::ruff::formatter::doctools::generate_proc_or_method {procinfo args} {

    # Formats the documentation for a proc in doctools format
    # procinfo - class information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -displayprefix METHODNAME - the string to use as a prefix
    #     for the method or proc name. Usually caller supplies this
    #     as the class name for the method.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #
    # Returns the proc documentation as a doctools formatted string.


    array set opts {-includesource false -displayprefix "" -hidenamespace ""}
    array set opts $args

    array set aproc $procinfo

    set doc ""

    # The quoting of strings below follows what I understand of doctools
    # - only [ and ] are special in text outside of doctools commands.
    # Such strings are quoted using the escape command. Arguments to
    # doctools commands are quoted using {}.

    set itemlist {};            # For the parameter descriptions
    set arglist {};             # For the synopsis
    # Construct command synopsis
    foreach param $aproc(parameters) {
        if {[dict get $param type] ne "parameter"} {
            # We do not deal with options here
            continue
        }
        set name [dict get $param name]
        set item [arg_def {} $name]
        if {[dict exists $param description]} {
            append item " [escape [dict get $param description]]"
        }
        if {[dict exists $param default]} {
            lappend arglist [opt [arg $name]]
            append item " (default \[const {[dict get $param default]}\])"
        } else {
            lappend arglist [arg $name]
        }
        lappend itemlist $item
    }
    set proc_name $opts(-displayprefix)[_trim_namespace $aproc(name) $opts(-hidenamespace)]

    if {$aproc(proctype) ne "method"} {
        append doc [eval [list call [cmd $proc_name]] $arglist]\n
    } else {
        switch -exact -- $aproc(name) {
            constructor {append doc [eval [list call [cmd "::oo::class create [_trim_namespace $aproc(class) $opts(-hidenamespace)]"]] $arglist]}
            destructor  {append doc [call "[arg OBJECT] [cmd destroy]"]}
            default  {append doc [eval [list call "[arg OBJECT] [cmd $aproc(name)]"] $arglist]}
        }
    }

    set sep ""
    # Parameter description
    if {[llength $itemlist]} {
        append doc [list_begin arguments]\n
        append doc [join $itemlist \n]\n
        append doc [list_end]\n
        set sep [para]
    }

    # Option description
    set itemlist {}
    foreach param $aproc(parameters) {
        if {[dict get $param type] ne "option"} {
            continue
        }
        set name [dict get $param name]
        if {[llength $name] > 1} {
            set arg  [arg [lrange $name 1 end]]
            set name [option [lindex $name 0]]
        } else {
            set name [option $name]
            set arg {}
        }
        if {[dict exists $param description]} {
            set desc [dict get $param description]
        } else {
            set desc "No description available."
        }
        lappend itemlist [opt_def $name $arg] [escape $desc]
    }
    if {[llength $itemlist]} {
        append doc $sep
        append doc [list_begin options]
        append doc [join $itemlist \n]\n
        append doc [list_end]\n
        set sep [para]
    }

    # Loop through all the paragraphs
    set paras [_fmtparas $aproc(description)]
    if {$paras ne ""} {
        append doc $sep$paras
        set sep [para]
    }

    if {[info exists aproc(return)] && $aproc(return) ne ""} {
        append doc $sep
        append doc [escape $aproc(return)]
    }

    if {$opts(-includesource)} {
        append doc $sep
        append doc "Source:"
        append doc [para]

        # Just [escape...] won't do it. We need the example_begin as well
        append doc "\[example_begin\]\n"
        append doc [escape $aproc(source)]
        append doc "\[example_end\]\n"
    }


    return "${doc}\n"
}

proc ::ruff::formatter::doctools::generate_procs {procinfodict args} {

    # Given a dictionary of proc information elements returns a string
    # containing documentation formatted for doctools
    # procinfodict - dictionary keyed by name of the proc with the associated
    #   value being in the format returned by extract_proc
    #
    # Additional parameters are passed on to the generate_proc procedure.

    #ruff
    # The returned procedure descriptions are sorted in alphabetical order.
    set doc "\[list_begin definitions\]\n"
    foreach name [lsort -dictionary [dict keys $procinfodict]] {
        append doc  [eval [list generate_proc_or_method [dict get $procinfodict $name]] $args]\n\n
    }
    append doc "\[list_end\]\n"

    return $doc
}

proc ::ruff::formatter::html::escape {s} {

    # s - string to be escaped
    # Protects characters in $s against interpretation as
    # HTML special characters.
    #
    # Returns the escaped string

    return [string map {
        &    &
        \"   "
        <    &lt;
        >    &gt;
    } $s]
}

proc ::ruff::formatter::html::generate_document {classprocinfodict args} {

    # Produces documentation in HTML format from the passed in
    # class and proc metainformation.
    #   classprocinfodict - dictionary containing meta information about the
    #    classes and procs
    # The following options may be specified:
    #   -preamble DICT - a dictionary indexed by a namespace. Each value is
    #    a flat list of pairs consisting of a heading and
    #    corresponding content. These are inserted into the document
    #    before the actual class and command descriptions for a namespace.
    #    The key "::" corresponds to documentation to be printed at
    #    the very beginning.
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #   -titledesc STRING - the title for the documentation.
    #    Used as the title for the document.
    #    If undefined, the string "Reference" is used.
    #   -stylesheet URLLIST - if specified, the stylesheets passed in URLLIST
    #    are used instead of the built-in styles. Note the built-in YUI is always
    #    included.

    variable yui_style;         # Contains default YUI based layout
    variable ruff_style;        # Contains default Ruff style sheet
    variable javascript;        # Javascript used by the page
    variable navlinks;          # Links generated for navigation menu
    variable link_targets;    # Links for cross-reference purposes

    # Re-initialize in case of multiple invocations
    array unset link_targets
    array set link_targets {}
    set navlinks [dict create]

    array set opts  [list  -includesource false  -hidenamespace ""  -titledesc ""  -modulename "Reference"  ]

    array set opts $args

    # TBD - create a link_target entry for each namespace

    # First collect all "important" names so as to build a list of
    # linkable targets. These will be used for cross-referencing and
    # also to generate links correctly in the case of
    # duplicate names in different namespaces or classes.
    #
    # A class name is also treated as a namespace component
    # although that is not strictly true.
    # TBD - the linked_targets and navlinks should really be merged
    # in some fashion as they overlap in function. The difference is
    # that the former needs to be built before any text processing is
    # done so linking in paras can be done. The latter is created as
    # the text is processed and also contains only links to be displayed
    # in the navigation menu.
    foreach {class_name class_info} [dict get $classprocinfodict classes] {
        set ns [namespace qualifiers $class_name]
        set link_targets($class_name) [_anchor $class_name]
        set method_info_list [concat [dict get $class_info methods] [dict get $class_info forwards]]
        foreach name {constructor destructor} {
            if {[dict exists $class_info $name]} {
                lappend method_info_list [dict get $class_info $name]
            }
        }
        foreach method_info $method_info_list {
            # The class name is the scope for methods. Because of how
            # the link target lookup works, we use the namespace
            # operator to separate the class from method. We also
            # store it a second time using the "." separator as that
            # is how they are sometimes referenced.
            set method_name [dict get $method_info name]
            set anchor [_anchor ${class_name}::${method_name}]
            set link_targets(${class_name}::${method_name}) $anchor
            set link_targets(${class_name}.${method_name}) $anchor
        }
    }
    foreach proc_name [dict keys [dict get $classprocinfodict procs]] {
        set link_targets(${proc_name}) [_anchor $proc_name]
    }

    set doc {<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">}
    append doc "<html><head><title>$opts(-titledesc)</title>\n"
    if {[info exists opts(-stylesheets)]} {
        append doc "<style>\n$yui_style\n</style>\n"
        foreach url $opts(-stylesheets) {
            append doc "<link rel='stylesheet' type='text/css' href='$url' />"
        }
    } else {
        # Use built-in styles
        append doc "<style>\n$yui_style\n$ruff_style\n</style>\n"
    }
    append doc "<script>$javascript</script>"
    append doc "</head><body>"

    # YUI stylesheet templates
    append doc "<div id='doc3' class='yui-t2'>"
    if {$opts(-titledesc) ne ""} {
        append doc "<div id='hd' class='banner'>\n$opts(-titledesc)\n</div>\n"
    }
    append doc "<div id='bd'>"
    append doc "<div id='yui-main'>"
    append doc "<div class='yui-b'>"
    append doc "<a name='_top'></a>"

    # Build a regexp that can be used to convert references to classes, methods
    # and procedures to links.
    set methods {}
    foreach {class_name class_info} [dict get $classprocinfodict classes] {
        # Note we add both forms of method qualification - using :: and . -
        # since comments might be use both forms.
        foreach name {constructor destructor} {
            if {[dict exists $class_info $name]} {
                lappend methods ${class_name}.$name ${class_name}::$name
            }
        }
        foreach method_info [dict get $class_info methods] {
            lappend methods ${class_name}.[dict get $method_info name] ${class_name}::[dict get $method_info name]
        }
        foreach method_info [dict get $class_info forwards] {
            lappend methods ${class_name}.[dict get $method_info name] ${class_name}::[dict get $method_info name]
        }
    }
    set ref_regexp [_build_symbol_regexp  [concat  [dict keys [dict get $classprocinfodict procs]]  [dict keys [dict get $classprocinfodict classes]]  $methods
                            ]
                   ]

    if {$opts(-modulename) ne ""} {
        append doc [_fmthead $opts(-modulename) 1]
    }

    if {[info exists opts(-preamble)] &&
        [dict exists $opts(-preamble) "::"]} {
        # Print the toplevel (global stuff)
        foreach {sec paras} [dict get $opts(-preamble) "::"] {
            append doc [_fmthead $sec 1]
            append doc [_fmtparas $paras $ref_regexp]
        }
    }

    set info_by_ns [_sift_classprocinfo $classprocinfodict]
    foreach ns [lsort [dict keys $info_by_ns]] {
        set link_targets($ns) [_anchor $ns]
        append doc [_fmthead $ns 1]

        if {[info exists opts(-preamble)] &&
            [dict exists $opts(-preamble) $ns]} {
            # Print the preamble for this namespace
            foreach {sec paras} [dict get $opts(-preamble) $ns] {
                append doc [_fmthead $sec 2]
                append doc [_fmtparas $paras $ref_regexp]
            }
        }

        if {[dict exists $info_by_ns $ns procs]} {
            append doc [_fmthead "Commands" 2 -namespace $ns]
            append doc [generate_procs [dict get $info_by_ns $ns procs]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $ref_regexp  ]
        }

        if {[dict exists $info_by_ns $ns classes]} {
            append doc [_fmthead "Classes" 2 -namespace $ns]
            append doc [generate_ooclasses [dict get $info_by_ns $ns classes]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $ref_regexp  ]
        }
    }
    append doc "</div>";        # <div class='yui-b'>
    append doc "</div>";        # <div id='yui-main'>

    # Add the navigation bits
    append doc "<div class='yui-b navbox'>"
    dict for {text link} $navlinks {
        set label [dict get $link label]
        set tag  [dict get $link tag]
        set href [dict get $link href]
        if {[dict exists $link tip]} {
            append doc "<$tag><a class='tooltip' href='$href'>$label<span>[dict get $link tip]</span></a></$tag>"
        } else {
            append doc "<$tag><a href='$href'>$label</a></$tag>"
        }
    }
    append doc "</div>";        # <div class='yui-b' for navigation>

    append doc "</div>";        # <div id='bd'>

    # The footer
    append doc "<div id='ft'>"
    append doc "<div style='float: right;'>Document generated by Ruff!</div>"
    if {[info exists opts(-copyright)]} {
        append doc "<div>&copy; [escape $opts(-copyright)]</div>"
    }
    append doc "</div>\n"

    append doc "</div>";        # <div id='doc3' class='t3'>
    append doc "</body></html>"

    return $doc
}

proc ::ruff::formatter::html::generate_ooclass {classinfo args} {


    # Formats the documentation for a class in HTML format
    # classinfo - class information in the format returned
    #   by extract_ooclass
    # -includesource BOOLEAN - if true, the source code of the
    #   procedure is also included. Default value is false.
    # -hidenamespace NAMESPACE - if specified as non-empty,
    #  program element names beginning with NAMESPACE are shown
    #  with that namespace component removed.
    # -linkregexp REGEXP - if specified, any word matching the
    #  regular expression REGEXP is marked as a link.
    #
    # Returns the class documentation as a NaturalDocs formatted string.

    variable header_levels
    array set opts {
        -includesource false
        -hidenamespace ""
        -mergeconstructor false
        -linkregexp ""
    }
    array set opts $args

    array set aclass $classinfo
    set class_name [_trim_namespace $aclass(name) $opts(-hidenamespace)]
    set scope [namespace qualifiers $aclass(name)]

    array set method_summaries {}

    # We want to put the class summary right after the header but cannot
    # generate it till the end so we put the header in a separate variable
    # to be merged at the end.
    append dochdr [_fmtprochead $aclass(name) -level $header_levels(class)]

    set doc ""
    # Include constructor in main class definition
    if {$opts(-mergeconstructor) && [info exists aclass(constructor)]} {
        error "-mergeconstructor not implemented"
        TBD
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -skipsections [list header name]  -linkregexp $opts(-linkregexp)  ]
    }

    if {[llength $aclass(superclasses)]} {
        append doc [_fmthead Superclasses $header_levels(nonav)]
        # Don't sort - order matters!
        append doc [_fmtpara [join [_trim_namespace_multi $aclass(superclasses) $opts(-hidenamespace)] {, }] $opts(-linkregexp) $scope]
    }
    if {[llength $aclass(mixins)]} {
        append doc [_fmthead "Mixins" $header_levels(nonav)]

        # Don't sort - order matters!
        append doc [_fmtpara [join [_trim_namespace_multi $aclass(mixins) $opts(-hidenamespace)] {, }] $opts(-linkregexp) $scope]
    }

    if {[llength $aclass(subclasses)]} {
        # Don't sort - order matters!
        append doc [_fmthead "Subclasses" $header_levels(nonav)]
        append doc [_fmtpara [join [_trim_namespace_multi $aclass(subclasses) $opts(-hidenamespace)] {, }] $opts(-linkregexp) $scope]
    }

    # Inherited and derived methods are listed as such.
    if {[llength $aclass(external_methods)]} {
        array set external_methods {}
        foreach external_method $aclass(external_methods) {
            # Qualify the name with the name of the implenting class
            foreach {name imp_class} $external_method break
            if {$imp_class ne ""} {
                set imp_class [_trim_namespace_multi $imp_class $opts(-hidenamespace)]
            }
            lappend external_methods($imp_class) ${imp_class}.$name
            set method_summaries($name) [dict create label [escape $name] desc [_linkify "See ${imp_class}.$name" $opts(-linkregexp) $scope]]
        }
        append doc [_fmthead "Inherited and mixed-in methods" $header_levels(nonav)]
        # Construct a sorted list based on inherit/mixin class name
        set ext_list {}
        foreach imp_class [lsort -dictionary [array names external_methods]] {
            lappend ext_list  [_linkify $imp_class $opts(-linkregexp) $scope]  [_linkify $external_methods($imp_class)  $opts(-linkregexp)  $imp_class]
        }
        append doc [_fmtdeflist $ext_list -preformatted both]
    }
    if {[llength $aclass(filters)]} {
        append doc [_fmthead "Filters" $header_levels(nonav)]
        append doc [_fmtpara [join [lsort $aclass(filters)] {, }] $opts(-linkregexp) $scope]
    }

    if {[info exists aclass(constructor)] && !$opts(-mergeconstructor)} {
        set method_summaries($aclass(name).constructor) [dict create label [_linkify "$aclass(name).constructor" $opts(-linkregexp) $aclass(name)] desc "Constructor for the class" ]
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $opts(-linkregexp)  ]
    }
    if {[info exists aclass(destructor)]} {
        set method_summaries($aclass(name).destructor) [dict create label [_linkify "$aclass(name).destructor" $opts(-linkregexp) $aclass(name)] desc "Destructor for the class" ]
        append doc [generate_proc_or_method $aclass(destructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $opts(-linkregexp)  ]
    }

    # We want methods and forwarded methods listed together and sorted
    array set methods {}
    foreach methodinfo $aclass(methods) {
        set methods([dict get $methodinfo name]) [list method $methodinfo]
    }
    if {[info exists aclass(forwards)]} {
        foreach forwardinfo $aclass(forwards) {
            set methods([dict get $forwardinfo name]) [list forward $forwardinfo]
        }
    }

    foreach name [lsort [array names methods]] {
        foreach {type info} $methods($name) break
        if {$type eq "method"} {
            append doc [generate_proc_or_method $info  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $opts(-linkregexp)  ]
            if {[dict exists $info summary]} {
                set summary [escape [dict get $info summary]]
            } elseif {[dict exists $info return]} {
                set summary [escape [dict get $info return]]
            } else {
                set summary ""
            }
            set method_summaries($aclass(name).$name) [dict create label [_linkify $aclass(name).$name $opts(-linkregexp) $aclass(name)] desc $summary]
        } else {
            set forward_text "Method forwarded to [dict get $info forward]"
            append doc [_fmtprochead $aclass(name)::$name -tooltip $forward_text -level $header_levels(method)]
            append doc [_fmtpara $forward_text $opts(-linkregexp) $scope]
            set method_summaries($aclass(name).$name) [dict create label [_linkify $aclass(name).$name  $opts(-linkregexp) $aclass(name)] desc [_linkify $forward_text $opts(-linkregexp) $scope]]
        }
    }

    set summary_list {}
    foreach name [lsort -dictionary [array names method_summaries]] {
        lappend summary_list [dict get $method_summaries($name) label] [dict get $method_summaries($name) desc]
    }
    if {[llength $summary_list]} {
        # append dochdr [_fmthead "Method summary" $header_levels(nonav)]
        append dochdr [_fmtdeflist $summary_list -preformatted both]
    }

    return "$dochdr\n$doc"
}

proc ::ruff::formatter::html::generate_ooclasses {classinfodict args} {

    # Given a list of class information elements returns as string
    # containing class documentation formatted for NaturalDocs
    # classinfodict - dictionary keyed by class name and each element
    #   of which is in the format returned by extract_ooclass
    #
    # Additional parameters are passed on to the generate_ooclass procedure.

    set doc ""
    foreach name [lsort [dict keys $classinfodict]] {
        append doc  [eval [list generate_ooclass [dict get $classinfodict $name]] $args]
        append doc "\n\n"
    }

    return $doc
}

proc ::ruff::formatter::html::generate_proc_or_method {procinfo args} {

    # Formats the documentation for a proc in HTML format
    # procinfo - proc or method information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #   -skipsections SECTIONLIST - a list of sections to be left
    #    out from the generated document. This is generally useful
    #    if the return value is to be included as part of a larger
    #    section (e.g. constructor within a class)
    #   -linkregexp REGEXP - if specified, any word matching the
    #    regular expression REGEXP is marked as a link.
    #
    # Returns the proc documentation as a HTML formatted string.

    variable header_levels

    array set opts {
        -includesource false
        -hidenamespace ""
        -skipsections {}
        -linkregexp ""
    }
    array set opts $args

    array set aproc $procinfo

    if {$aproc(proctype) ne "method"} {
        set scope [namespace qualifiers $aproc(name)]
    } else {
        set scope $aproc(class); # Scope is name of class
    }

    set doc "";                 # Document string

    set header_title [_trim_namespace $aproc(name) $opts(-hidenamespace)]
    set proc_name [_trim_namespace $aproc(name) $opts(-hidenamespace)]

    # Construct the synopsis and simultaneously the parameter descriptions
    # These are constructed as HTML (ie. already escaped) since we want
    # to format parameters etc.
    set desclist {};            # For the parameter descriptions
    set arglist {};             # Used later for synopsis
    foreach param $aproc(parameters) {
        set name [dict get $param name]
        set desc {}
        if {[dict get $param type] eq "parameter"} {
            lappend arglist [_arg $name]
            if {[dict exists $param default]} {
                lappend desc "(optional, default [_const [dict get $param default]])"
            }
        }
        if {[dict exists $param description]} {
            lappend desc [_linkify [dict get $param description] $opts(-linkregexp) $scope]
        } elseif {$name eq "args"} {
            lappend desc "Additional options."
        }

        lappend desclist [_arg $name] [join $desc " "]
    }

    if {$aproc(proctype) ne "method"} {
        set synopsis "[_cmd [namespace tail $proc_name]] [join $arglist { }]"
    } else {
        switch -exact -- $aproc(name) {
            constructor {set synopsis "[_cmd $aproc(class)] [_cmd create] [join $arglist { }]"}
            destructor  {set synopsis "[_arg OBJECT] [_cmd destroy]"}
            default  {set synopsis "[_arg OBJECT] [_cmd [namespace tail $aproc(name)]] [join $arglist { }]"}
        }
    }

    if {[info exists aproc(summary)] && $aproc(summary) ne ""} {
        set summary $aproc(summary)
    } elseif {[info exists aproc(return)] && $aproc(return) ne ""} {
        set summary $aproc(return)
    }

    if {[lsearch -exact $opts(-skipsections) header] < 0} {
        # We need a fully qualified name for cross-linking purposes
        if {$aproc(proctype) eq "method"} {
            set fqn $aproc(class)::$aproc(name)
        } else {
            set fqn $aproc(name)
        }

        if {[info exists summary]} {
            append doc [_fmtprochead $fqn -tooltip $summary -level $header_levels($aproc(proctype))]
        } else {
            append doc [_fmtprochead $fqn -level $header_levels($aproc(proctype))]
        }
    }

    if {[info exists summary]} {
        append doc [_fmtpara $summary $opts(-linkregexp) $scope]
    }

    append doc "<p><div class='ruff_synopsis'>$synopsis</div></p>\n"

    if {[llength $desclist]} {
        append doc [_fmthead Parameters $header_levels(nonav)]
        # Parameters are output as a list.
        append doc [_fmtdeflist $desclist -preformatted both]
    }

    if {[info exists aproc(return)] && $aproc(return) ne ""} {
        append doc [_fmthead "Return value" $header_levels(nonav)]
        append doc [_fmtpara $aproc(return) $opts(-linkregexp) $scope]
    }

    # Loop through all the paragraphs. Note the first para is also
    # the summary (already output) but we will show that in the general
    # description as well.
    if {[llength $aproc(description)]} {
        append doc [_fmthead "Description" $header_levels(nonav)]
        append doc [_fmtparas $aproc(description) $opts(-linkregexp) $scope]
    }

    # Do we include the source code in the documentation?
    if {$opts(-includesource)} {
        set src_id [_new_srcid]
        append doc "<div class='ruff_source'>"
        append doc "<p class='ruff_source_link'>"
        append doc "<a id='l_$src_id' href=\"javascript:toggleSource('$src_id')\">Show source</a>"
        append doc "</p>\n"
        append doc "<div id='$src_id' class='ruff_dyn_src'><pre>\n[escape $aproc(source)]\n</pre></div>\n"
        append doc "</div>";    # class='ruff_source'
    }


    return "${doc}\n"
}

proc ::ruff::formatter::html::generate_procs {procinfodict args} {

    # Given a dictionary of proc information elements returns a string
    # containing HTML format documentation.
    # procinfodict - dictionary keyed by name of the proc with the associated
    #   value being in the format returned by extract_proc
    #
    # Additional parameters are passed on to the generate_proc procedure.
    #
    # Returns documentation string in NaturalDocs format with
    # procedure descriptions sorted in alphabetical order
    # within each namespace.

    set doc ""
    set namespaces [_sift_names [dict keys $procinfodict]]
    foreach ns [lsort -dictionary [dict keys $namespaces]] {
        foreach name [lsort -dictionary [dict get $namespaces $ns]] {
            append doc  [eval [list generate_proc_or_method [dict get $procinfodict $name]] $args]\n\n
        }
    }

    return $doc
}

proc ::ruff::formatter::naturaldocs::generate_document {classprocinfodict args} {

    # Produces documentation in NaturalDocs format from the passed in
    # class and proc metainformation.
    #   classprocinfodict - dictionary containing meta information about the
    #    classes and procs
    #
    # The following options may be specified:
    #   -preamble DICT - a dictionary indexed by a namespace. Each value is
    #    a flat list of pairs consisting of a heading and
    #    corresponding content. These are inserted into the document
    #    before the actual class and command descriptions for a namespace.
    #    The key "::" corresponds to documentation to be printed at
    #    the very beginning.
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #   -modulename NAME - the name of the module. Used as the title for the document.
    #    If undefined, the string "Reference" is used.

    array set opts  [list  -includesource false  -hidenamespace ""  -modulename "Reference"  -preamble [dict create]  ]

    array set opts $args
    set doc [_fmtheading Title $opts(-modulename)]

    # Build a regexp that can be used to convert references to classes, methods
    # and procedures to links.
    set methods {}
    foreach {class_name class_info} [dict get $classprocinfodict classes] {
        foreach method_info [dict get $class_info methods] {
            lappend methods ${class_name}.[dict get $method_info name]
        }
        foreach method_info [dict get $class_info forwards] {
            lappend methods ${class_name}.[dict get $method_info name]
        }
    }
    set ref_regexp [_build_symbol_regexp  [concat  [dict keys [dict get $classprocinfodict procs]]  [dict keys [dict get $classprocinfodict classes]]  $methods
                            ]
                   ]

    if {[dict exists $opts(-preamble) "::"]} {
        # Print the toplevel (global stuff)
        foreach {sec paras} [dict get $opts(-preamble) "::"] {
            append doc [_fmtheading $sec]
            append doc [_fmtparas $paras $ref_regexp]
        }
    }

    set info_by_ns [_sift_classprocinfo $classprocinfodict]

    foreach ns [lsort -dictionary [dict keys $info_by_ns]] {
        # append doc [_fmtheading Section $ns] <- this causes dup headings?
        if {[dict exists $opts(-preamble) $ns]} {
            foreach {sec paras} [dict get $opts(-preamble) $ns] {
                append doc [_fmtheading $sec]
                append doc [_fmtparas $paras $ref_regexp]
            }
        }

        # Output commands BEFORE classes else they show up as
        # part of a class definition unless they are grouped into a
        # separate section in which case summaries are duplicated.
        if {[dict exists $info_by_ns $ns procs]} {
            append doc [_fmtheading Section Commands]
            append doc [generate_procs [dict get $info_by_ns $ns procs]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $ref_regexp  ]
        }

        if {[dict exists $info_by_ns $ns classes]} {
            append doc [generate_ooclasses [dict get $info_by_ns $ns classes]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $ref_regexp  ]
        }
    }

    return $doc
}

proc ::ruff::formatter::naturaldocs::generate_ooclass {classinfo args} {


    # Formats the documentation for a class in NaturalDocs format
    # classinfo - class information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #   -linkregexp REGEXP - if specified, any word matching the
    #    regular expression REGEXP is marked as a link.
    #
    # Returns the class documentation as a NaturalDocs formatted string.

    variable markers
    variable leaders

    array set opts {
        -includesource false
        -hidenamespace ""
        -mergeconstructor false
        -linkregexp ""
    }
    array set opts $args

    array set aclass $classinfo
    set class_name [_trim_namespace $aclass(name) $opts(-hidenamespace)]

    set doc ""
    append doc [_fmtheading class $class_name]

    # Include constructor in main class definition
    if {$opts(-mergeconstructor) && [info exists aclass(constructor)]} {
        error "-mergeconstructor not implemented"
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -skipsections [list header name]  -linkregexp $opts(-linkregexp)  ]
    }

    # TBD - in the various sections below we include some leading text
    # that is not really necessary. This is because NaturalDocs assumes
    # anything starting with a ":" is a code line and does not format
    # or link any words in it. This is a problem since class names etc.
    # may start with a ":" if namespace qualified

    if {[llength $aclass(superclasses)]} {
        append doc [_fmtheading Superclasses]
        # Don't sort - order matters!
        append doc [_fmtpara "The class inherits from the following classes: [join [_trim_namespace_multi $aclass(superclasses) $opts(-hidenamespace)] {, }]" $opts(-linkregexp)]
    }
    if {[llength $aclass(mixins)]} {
        append doc [_fmtheading "Mixins"]

        # Don't sort - order matters!
        append doc [_fmtpara "The class has the following classes mixed-in: [join [_trim_namespace_multi $aclass(mixins) $opts(-hidenamespace)] {, }]" $opts(-linkregexp)]
    }

    if {[llength $aclass(subclasses)]} {
        # Don't sort - order matters!
        append doc [_fmtheading "Subclasses"]
        append doc [_fmtpara "The following classes inherit from this class: [join [_trim_namespace_multi $aclass(subclasses) $opts(-hidenamespace)] {, }]" $opts(-linkregexp)]
    }

    # Inherited and derived methods are listed as such.
    if {[llength $aclass(external_methods)]} {
        set external_methods {}
        foreach external_method $aclass(external_methods) {
            # Qualify the name with the name of the implenting class
            foreach {name imp_class} $external_method break
            if {$imp_class ne ""} {
                set name [_trim_namespace_multi $imp_class $opts(-hidenamespace)].$name
            }
            lappend external_methods $name
        }
        append doc [_fmtheading "External methods"]
        append doc [_fmtpara "The following methods are either mixed-in or inherited: [join [lsort $external_methods] {, }]" $opts(-linkregexp)]
    }
    if {[llength $aclass(filters)]} {
        append doc [_fmtheading "Filters"]
        append doc [_fmtpara "The following methods are attached as filters for this class : [join [lsort $aclass(filters)] {, }]" $opts(-linkregexp)]
    }

    # In NaturalDocs, the Class heading establishes the "scope"
    # and we can straightaway list the methods directly after it and
    # have them tagged as belonging to the class.

    if {[info exists aclass(constructor)] && !$opts(-mergeconstructor)} {
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $opts(-linkregexp)  ]
    }
    if {[info exists aclass(destructor)]} {
        append doc [generate_proc_or_method $aclass(destructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $opts(-linkregexp)  ]
    }

    # We want methods and forwarded methods listed together and sorted
    array set methods {}
    foreach methodinfo $aclass(methods) {
        set methods([dict get $methodinfo name]) [list method $methodinfo]
    }
    if {[info exists aclass(forwards)]} {
        foreach forwardinfo $aclass(forwards) {
            set methods([dict get $forwardinfo name]) [list forward $forwardinfo]
        }
    }

    foreach name [lsort [array names methods]] {
        foreach {type info} $methods($name) break
        if {$type eq "method"} {
            append doc [generate_proc_or_method $info  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -linkregexp $opts(-linkregexp)  ]
        } else {
            # TBD - check formatting of forwarded methods
            append doc [_fmtheading "Method" $name]
            # TBD - link to forwarded method if possible
            append doc [_fmtpara "Method forwarded to [dict get $info forward]" $opts(-linkregexp)]
        }
    }

    return $doc
}

proc ::ruff::formatter::naturaldocs::generate_ooclasses {classinfodict args} {

    # Given a list of class information elements returns as string
    # containing class documentation formatted for NaturalDocs
    # classinfodict - dictionary keyed by class name and each element
    #   of which is in the format returned by extract_ooclass
    #
    # Additional parameters are passed on to the generate_ooclass procedure.

    set doc ""
    foreach name [lsort [dict keys $classinfodict]] {
        append doc  [eval [list generate_ooclass [dict get $classinfodict $name]] $args]
        append doc "\n\n"
    }
    return $doc
}

proc ::ruff::formatter::naturaldocs::generate_proc_or_method {procinfo args} {

    # Formats the documentation for a proc in NaturalDocs format
    # procinfo - proc or method information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #   -skipsections SECTIONLIST - a list of sections to be left
    #    out from the generated document. This is generally useful
    #    if the return value is to be included as part of a larger
    #    section (e.g. constructor within a class)
    #   -linkregexp REGEXP - if specified, any word matching the
    #    regular expression REGEXP is marked as a link.
    #
    # Returns the proc documentation as a NaturalDocs formatted string.

    variable markers
    variable leaders

    array set opts {-includesource false
        -hidenamespace ""
        -skipsections {}
        -linkregexp ""
    }
    array set opts $args

    array set aproc $procinfo

    set doc "";                 # Document string

    # In NaturalDocs, method names are never qualifed by a class prefix
    # since they
    # automatically get scoped by previous Class or namespace headings.
    set header_title [_trim_namespace $aproc(name) $opts(-hidenamespace)]
    set proc_name [_trim_namespace $aproc(name) $opts(-hidenamespace)]

    if {[lsearch -exact $opts(-skipsections) header] < 0} {
        if {$aproc(proctype) eq "method"} {
            append doc [_fmtheading method $header_title]
        } else {
            append doc [_fmtheading proc $header_title]
        }
    }

    # Loop through all the paragraphs
    append doc [_fmtparas $aproc(description) $opts(-linkregexp)]

    if {[info exists aproc(return)] && $aproc(return) ne ""} {
        append doc [_fmtheading return]
        append doc [_fmtpara $aproc(return) $opts(-linkregexp)]
    }

    # Now spit out the parameter list. Note we do this AFTER
    # the paragraphs so NaturalDocs correctly picks up
    # a summary line (it wants it right after the topic.
    # Construct the synopsis and simultaneously the parameter descriptions
    set desclist {};            # For the parameter descriptions
    set arglist {};             # Used later for synopsis
    foreach param $aproc(parameters) {
        set name [dict get $param name]
        set desc {}
        if {[dict get $param type] eq "parameter"} {
            lappend arglist $name
            if {[dict exists $param default]} {
                # No visual way in NaturalDocs to show as optional so
                # explicitly state (although the synopsis will show the
                # default)
                lappend desc "(optional, default [dict get $param default])"
            }
        }
        if {[dict exists $param description]} {
            lappend desc "[dict get $param description]"
        }

        lappend desclist $name [join $desc " "]
    }

    if {[llength $desclist]} {
        append doc [_fmtheading parameters]
        # Parameters are output as a list.
        append doc [_fmtdeflist $desclist $opts(-linkregexp)]
    }

    # Do we include the source code in the documentation?
    if {$opts(-includesource)} {
        append doc [_fmtheading source]
        append doc "$leaders(text)(start code)"
        append doc [::textutil::adjust::indent $aproc(source) $leaders(text)]\n
        append doc "$leaders(text)(end code)"
    }

    # Synopsis - write a dummy proc WITHOUT any comment headers and
    # NaturalDocs will pick out the appropriate elements
    if {$aproc(proctype) ne "method"} {
        append doc "\nproc $proc_name \{$arglist\} {}\n"
    } else {
        switch -exact -- $aproc(name) {
            constructor {append doc "\nconstructor $arglist {}\n"}
            destructor  {append doc "\ndestructor {} {}\n"}
            default  {append doc "\nmethod $aproc(name) \{$arglist\} {}\n"}
        }
    }

    return "${doc}\n"
}

proc ::ruff::formatter::naturaldocs::generate_procs {procinfodict args} {

    # Given a dictionary of proc information elements returns a string
    # containing documentation formatted for NaturalDocs
    # procinfodict - dictionary keyed by name of the proc with the associated
    #   value being in the format returned by extract_proc
    #
    # Additional parameters are passed on to the generate_proc procedure.
    #
    # Returns documentation string in NaturalDocs format with
    # procedure descriptions sorted in alphabetical order.

    set doc ""
    foreach name [lsort -dictionary [dict keys $procinfodict]] {
        append doc  [eval [list generate_proc_or_method [dict get $procinfodict $name]] $args]\n\n
    }

    return $doc
}

proc ::ruff::formatter::robodoc::generate_document {classprocinfodict args} {

    # Produces documentation in robodoc format from the passed in
    # class and proc metainformation.
    #  classprocinfodict - dictionary containing meta information about the
    #    classes and procs
    #   -preamble DICT - a dictionary indexed by a namespace. Each value is
    #    a flat list of pairs consisting of a heading and
    #    corresponding content. These are inserted into the document
    #    before the actual class and command descriptions for a namespace.
    #    The key "::" corresponds to documentation to be printed at
    #    the very beginning.
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.

    variable markers

    array set opts  [list  -includesource false  -hidenamespace ""  -modulename MODULE  -preamble [dict create]  ]

    array set opts $args
    set doc ""

    if {[dict exists $opts(-preamble) "::"]} {
        # Print the toplevel (global stuff)
        foreach {sec paras} [dict get $opts(-preamble) "::"] {
            append doc "$markers(module) $opts(-modulename)/$sec\n"
            append doc [_fmtitem DESCRIPTION]
            append doc [_fmtparas $paras]
            append doc "$markers(end)\n"
        }
    }

    set info_by_ns [_sift_classprocinfo $classprocinfodict]
    foreach ns [lsort -dictionary [dict keys $info_by_ns]] {
        # TBD - does the following line cause dup headings?
        # append doc [_fmtheading Section $ns]
        if {[dict exists $opts(-preamble) $ns]} {
            foreach {sec paras} [dict get $opts(-preamble) $ns] {
                append doc "$markers(module) $ns/$sec\n"
                append doc [_fmtitem DESCRIPTION]
                append doc [_fmtparas $paras]
                append doc "$markers(end)\n"
            }
        }

        if {[dict exists $info_by_ns $ns classes]} {
            append doc [generate_ooclasses [dict get $info_by_ns $ns classes]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  ]
        }
        if {[dict exists $info_by_ns $ns procs]} {
            append doc [generate_procs [dict get $info_by_ns $ns procs]  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  ]
        }
    }

    return $doc
}

proc ::ruff::formatter::robodoc::generate_ooclass {classinfo args} {


    # Formats the documentation for a class in robodoc format
    # classinfo - class information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #
    # Returns the class documentation as a robodoc formatted string.

    variable markers
    variable leaders

    array set opts {-includesource false -hidenamespace "" -mergeconstructor true}
    array set opts $args

    array set aclass $classinfo
    set class_name [_trim_namespace $aclass(name) $opts(-hidenamespace)]

    set doc ""
    set header_title "[namespace qualifiers $aclass(name)]/[namespace tail $aclass(name)]"
    append doc "$markers(class) $header_title\n"

    append doc [_fmtitem NAME $class_name]

    # Include constructor in main class definition
    if {$opts(-mergeconstructor) && [info exists aclass(constructor)]} {
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)  -skipsections [list header name]  ]
    }

    #ruff
    # Because robodoc does not have a heading for mix-ins, they are include
    # within the DERIVED FROM section.
    if {[llength $aclass(superclasses)] || [llength $aclass(mixins)]} {
        append doc [_fmtitem "DERIVED FROM"]

        # Don't sort - order matters! Also, there is no heading for mixins
        # so we add them here.
        if {[llength $aclass(mixins)]} {
            # Don't sort - order matters!
            append doc [_fmtpara "Mixins: [join [_trim_namespace_multi $aclass(mixins) $opts(-hidenamespace)] {, }]"]
        }
        if {[llength $aclass(superclasses)]} {
            append doc [_fmtpara "Superclasses: [join [_trim_namespace_multi $aclass(superclasses) $opts(-hidenamespace)] {, }]"]
        }
    }


    if {[llength $aclass(subclasses)]} {
        # Don't sort - order matters!
        append doc [_fmtitem "DERIVED BY" [join [_trim_namespace_multi $aclass(subclasses) $opts(-hidenamespace)] ", "]]
    }

    #ruff
    # Documentation for a class only lists the method names. The
    # methods themselves are documented separately.
    set class_methods {}
    foreach methodinfo $aclass(methods) {
        lappend class_methods ${class_name}.[dict get $methodinfo name]
    }
    if {[info exists aclass(constructor)] && !$opts(-mergeconstructor)} {
        set class_methods [linsert $class_methods 0 constructor]
    }
    if {[info exists aclass(destructor)]} {
        set class_methods [linsert $class_methods 0 destructor]
    }
    append doc [_fmtitem METHODS]
    append doc [_fmtpara [join $class_methods ", "]]

    #ruff
    # Inherited and derived methods are listed as such.
    if {[llength $aclass(external_methods)]} {
        set external_methods {}
        foreach external_method $aclass(external_methods) {
            # Qualify the name with the name of the implenting class
            foreach {name imp_class} $external_method break
            if {$imp_class ne ""} {
                set name [_trim_namespace_multi $imp_class $opts(-hidenamespace)].$name
            }
            lappend external_methods $name
        }
        append doc [_fmtpara "External methods: [join [lsort $external_methods] {, }]"]
    }
    if {[llength $aclass(filters)]} {
        append doc [_fmtpara "Filters: [join [lsort $aclass(filters)] {, }]"]
    }

    # Finish up the class description
    append doc $markers(end)

    # Next we will generate the documentation for the methods themselves

    append doc "\n\n"

    if {[info exists aclass(constructor)] && !$opts(-mergeconstructor)} {
        append doc [generate_proc_or_method $aclass(constructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)]
    }
    if {[info exists aclass(destructor)]} {
        append doc [generate_proc_or_method $aclass(destructor)  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)]
    }

    # We want methods and forwarded methods listed together and sorted
    array set methods {}
    foreach methodinfo $aclass(methods) {
        set methods([dict get $methodinfo name]) [list method $methodinfo]
    }
    if {[info exists aclass(forwards)]} {
        foreach forwardinfo $aclass(forwards) {
            set methods([dict get $forwardinfo name]) [list forward $forwardinfo]
        }
    }

    foreach name [lsort [array names methods]] {
        foreach {type info} $methods($name) break
        if {$type eq "method"} {
            append doc [generate_proc_or_method $info  -includesource $opts(-includesource)  -hidenamespace $opts(-hidenamespace)]
        } else {
            # Forwarded method
            set header_title "[namespace qualifiers $aclass(name)]/[namespace tail $aclass(name)].$name"
            append doc "\n$markers(method) $header_title\n"
            append doc [_fmtitem NAME "[_trim_namespace $aclass(name) $opts(-hidenamespace)].$name"]
            # TBD - link to forwarded method if possible
            append doc [_fmtpara "Method forwarded to [dict get $info forward]."]
            append doc "\n$markers(end)\n"
        }
    }

    return $doc
}

proc ::ruff::formatter::robodoc::generate_ooclasses {classinfodict args} {

    # Given a list of class information elements returns as string
    # containing class documentation formatted for robodoc
    # classinfodict - dictionary keyed by class name and each element
    #   of which is in the format returned by extract_ooclass
    #
    # Additional parameters are passed on to the generate_ooclass procedure.

    set doc ""
    foreach name [lsort [dict keys $classinfodict]] {
        append doc  [eval [list generate_ooclass [dict get $classinfodict $name]] $args]
        append doc "\n\n"
    }
    return $doc
}

proc ::ruff::formatter::robodoc::generate_proc_or_method {procinfo args} {

    # Formats the documentation for a proc in robodoc format
    # procinfo - proc or method information in the format returned
    #   by extract_ooclass
    #
    # The following options may be specified:
    #   -includesource BOOLEAN - if true, the source code of the
    #     procedure is also included. Default value is false.
    #   -hidenamespace NAMESPACE - if specified as non-empty,
    #    program element names beginning with NAMESPACE are shown
    #    with that namespace component removed.
    #   -skipsections SECTIONLIST - a list of sections to be left
    #    out from the generated document. This is generally useful
    #    if the return value is to be included as part of a larger
    #    section (e.g. constructor within a class)
    # Returns the proc documentation as a robodoc formatted string.

    variable markers
    variable leaders

    array set opts {-includesource false -hidenamespace "" -skipsections {}}
    array set opts $args

    array set aproc $procinfo

    set doc "";                 # Document string

    #ruff
    # In order for the Robodoc cross-links to work, the header markers
    # generated use the namespace as the section followed by the command
    # name or class name and method combined with a period.
    if {$aproc(proctype) eq "method"} {
        set header_title "[namespace qualifiers $aproc(class)]/[namespace tail $aproc(class)].$aproc(name)"
        set proc_name [_trim_namespace $aproc(class) $opts(-hidenamespace)].$aproc(name)
    } else {
        set header_title [namespace qualifiers $aproc(name)]/[namespace tail $aproc(name)]
        set proc_name [_trim_namespace $aproc(name) $opts(-hidenamespace)]
    }

    # TBD - mark header as internal depending on whether private method
    if {[lsearch -exact -nocase $opts(-skipsections) header] < 0} {
        if {$aproc(proctype) eq "method"} {
            append doc "$markers(method) $header_title\n"
        } else {
            append doc "$markers(function) $header_title\n"
        }
    }

    if {[lsearch -exact -nocase $opts(-skipsections) name] < 0} {
        append doc [_fmtitem NAME $proc_name]
    }


    # Construct the synopsis and simultaneously the parameter descriptions
    set desclist {};            # For the parameter descriptions
    set arglist {};             # For the synopsis
    # Construct command synopsis and parameter block
    # Unfortunately Robodoc does not seem to have any special way of
    # formatting these. Just output as text strings
    foreach param $aproc(parameters) {
        set name [dict get $param name]
        if {[dict get $param type] eq "parameter"} {
            lappend arglist $name
        }
        set desc "$name --"
        if {[dict exists $param default]} {
            # No visual way in robodoc to show as optional so explicitly state
            append desc " (optional, default [dict get $param default])"
        }
        if {[dict exists $param description]} {
            append desc " [dict get $param description]"
        }

        lappend desclist $desc
    }

    # Synopsis
    if {$aproc(proctype) ne "method"} {
        append doc [_fmtitem SYNOPSIS "$proc_name $arglist"]
    } else {
        switch -exact -- $aproc(name) {
            constructor {append doc [_fmtitem SYNOPSIS "::oo::class create [_trim_namespace $aproc(class) $opts(-hidenamespace)] $arglist"]}
            destructor  {append doc [_fmtitem SYNOPSIS "OBJECT destroy"]}
            default  {append doc [_fmtitem SYNOPSIS "OBJECT $aproc(name) $arglist"]}
        }
    }

    # Parameter descriptions
    if {[llength $desclist]} {
        append doc [_fmtitem PARAMETERS]
        # Parameters are output as a list.
        append doc [_fmtlist $desclist]
    }

    append doc [_fmtitem DESCRIPTION]


    # Loop through all the paragraphs
    # We need to remember the last character to detect possible errors
    # in Robodoc's list recognition. Either the list must follow a item
    # header or a line ending in colon (:). We pass : as the second
    # parameter below because we just put out a item header which
    # is equivalent.
    append doc [_fmtparas $aproc(description) :]

    if {[info exists aproc(return)] && $aproc(return) ne ""} {
        append doc [_fmtpara $aproc(return)]
    }

    if {$opts(-includesource)} {
        append doc [_fmtitem SOURCE]
        append doc [::textutil::adjust::indent $aproc(source) $leaders(text)]\n
    }

    if {[lsearch -exact -nocase $opts(-skipsections) header] < 0} {
        append doc $markers(end)
    }

    return "${doc}\n"
}

proc ::ruff::formatter::robodoc::generate_procs {procinfodict args} {

    # Given a dictionary of proc information elements returns a string
    # containing documentation formatted for robodoc
    # procinfodict - dictionary keyed by name of the proc with the associated
    #   value being in the format returned by extract_proc
    #
    # Additional parameters are passed on to the generate_proc procedure.

    set doc ""

    foreach name [lsort -dictionary [dict keys $procinfodict]] {
        append doc  [eval [list generate_proc_or_method [dict get $procinfodict $name]] $args]\n\n
    }

    return $doc
}