cc65/util/ca65html

#!/usr/bin/perl
###############################################################################
#                                                                             #
#                                  ca65html                                   #
#                                                                             #
#                      Convert a ca65 source into HTML                        #
#                                                                             #
#                                                                             #
#                                                                             #
#  (C) 2000-2007 Ullrich von Bassewitz                                        #
#                Roemerstrasse 52                                             #
#                D-70794 Filderstadt                                          #
#  EMail:        uz@cc65.org                                                  #
#                                                                             #
#                                                                             #
#  This software is provided 'as-is', without any expressed or implied        #
#  warranty.  In no event will the authors be held liable for any damages     #
#  arising from the use of this software.                                     #
#                                                                             #
#  Permission is granted to anyone to use this software for any purpose,      #
#  including commercial applications, and to alter it and redistribute it     #
#  freely, subject to the following restrictions:                             #
#                                                                             #
#  1. The origin of this software must not be misrepresented; you must not    #
#     claim that you wrote the original software. If you use this software    #
#     in a product, an acknowledgment in the product documentation would be   #
#     appreciated but is not required.                                        #
#  2. Altered source versions must be plainly marked as such, and must not    #
#     be misrepresented as being the original software.                       #
#  3. This notice may not be removed or altered from any source               #
#     distribution.                                                           #
#                                                                             #
###############################################################################



# Things currently missing:
#
#   - Scoping with .proc/.endproc, .scope/.endscope, .enum/.endenum,
#     .struct/.endstruct, .union/endunion, .repeat/.endrep, .local
#   - .global is ignored
#   - .case is ignored, labels are always case-sensitive
#   - .include handling (difficult)
#   - The global namespace operator ::
#



use strict 'vars';
use warnings;

# Modules
use Getopt::Long;



#-----------------------------------------------------------------------------#
#                                  Variables                                  #
# ----------------------------------------------------------------------------#



# Global variables
my %Files           = ();           # List of all files.
my $FileCount       = 0;            # Number of input files
my %Exports         = ();           # List of exported symbols.
my %Imports         = ();           # List of imported symbols.
my %Labels          = ();           # List of all labels
my $LabelNum        = 0;            # Counter to generate unique labels

# Command line options
my $BGColor         = "#FFFFFF";    # Background color
my $Colorize        = 0;            # Colorize the output
my $CommentColor    = "#B22222";    # Color for comments
my $CRefs           = 0;            # Add references to the C file
my $CtrlColor       = "#228B22";    # Color for control directives
my $CvtTabs         = 0;            # Convert tabs to spaces
my $TabSize         = 8;            # This is how god created them
my $Debug           = 0;            # No debugging
my $Help            = 0;            # Help flag
my $HTMLDir         = "";           # Directory in which to create the files
my $IndexCols       = 6;            # Columns in the file listing
my $IndexTitle      = "Index";      # Title of index page
my $IndexName       = "index.html"; # Name of index page
my $IndexPage       = 0;            # Create an index page
my $KeywordColor    = "#A020F0";    # Color for keywords
my $LineLabels      = 0;            # Add a HTML label to each line
my $LineNumbers     = 0;            # Add line numbers to the output
my $LinkStyle       = 0;            # Default link style
my $ReplaceExt      = 0;            # Replace extension instead of appending
my $StringColor     = "#6169C1";    # Color for strings
my $TextColor       = "#000000";    # Text color
my $Verbose         = 0;            # Be quiet

# Table used to convert the label number into names
my @NameTab         = ('A' .. 'Z', '0' .. '9');



#-----------------------------------------------------------------------------#
#                              Helper functions                               #
# ----------------------------------------------------------------------------#



# Terminate with an error
sub Abort {
    print STDERR "ca65html: @_\n";
    exit 1;
}

# Print a message if verbose is true
sub Gabble {
    if ($Verbose) {
        print "ca65html: @_\n";
    }
}

# Generate a label and return it
sub GenLabel {

    my $I;
    my $L = "";;
    my $Num = $LabelNum++;

    # Generate the label
    for ($I = 0; $I < 4; $I++) {
        $L = $NameTab[$Num % 36] . $L;
        $Num /= 36;
    }
    return $L;
}

# Make an output file name from an input file name
sub GetOutName {

    # Input name is parameter
    my $InName = $_[0];

    # Create the output file name from the input file name
    if ($ReplaceExt && $InName =~ /^(.+)\.([^\.\/]*)$/) {
        return "$1.html";
    } else {
        return "$InName.html";
    }
}

# Translate some HTML characters into harmless names.
sub Cleanup {
    my $S = shift (@_);
    $S =~ s/&/&amp;/g;
    $S =~ s/</&lt;/g;
    $S =~ s/>/&gt;/g;
    $S =~ s/\"/&quot;/g;
    return $S;
}

# Strip a path from a filename and return just the name
sub StripPath {

    # Filename is argument
    my $FileName = $_[0];

    # Remove a path name if we have one
    $FileName =~ /^(.*?)([^\/]*)$/;
    return $2;
}



#-----------------------------------------------------------------------------#
#                         Document header and footer                          #
# ----------------------------------------------------------------------------#



# Print the document header
sub DocHeader {
    my $OUT = shift (@_);
    my $Asm = shift (@_);
    print $OUT "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\n";
    print $OUT <<"EOF";
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="ca65html">
<title>$Asm</title>
<style type=\"text/css\">
body {
    background-color: $BGColor;
    color: $TextColor;
}
h1 {
    text-align: center;
}
#top {
    margin: 2em 0 3em 0;
    border-bottom: 1px solid grey;
}
#bottom {
    margin: 3em 0 1em 0;
    padding-top: 1em;
    border-top: 1px solid grey;
}
img {
    border: 0;
    margin: 0;
    float: right;
}
.ctrl {
    color: $CtrlColor;
}
.keyword {
    color: $KeywordColor;
}
.string {
    color: $StringColor;
}
.comment {
    color: $CommentColor;
}
a:link {
    color: #0000d0;
}
a:visited {
    color: #000060;
}
a:active {
    color: #00d0d0;
}
</style>
</head>
<body>
<div id=\"top\"><h1>$Asm</h1></div>
EOF
}

# Print the document footer
sub DocFooter {
    my $OUT  = shift (@_);
    my $Name = shift (@_);

    # Get the current date and time
    my $Today = localtime;

    # Print
    print $OUT "<div id=\"bottom\"><address>\n";
    print $OUT "<a href=\"http://validator.w3.org/check?uri=referer\">\n";
    print $OUT "<img src=\"http://www.w3.org/Icons/valid-xhtml10-blue\" alt=\"Valid XHTML 1.0 Strict\" height=\"31\" width=\"88\" /></a><br>\n";
    print $OUT "$Name; generated on $Today by ca65html<br>\n";
    print $OUT "<a href=\"mailto:uz&#64;cc65.org\">uz&#64;cc65.org</a>\n";
    print $OUT "</address></div>\n";
    print $OUT "</body></html>\n";
}



#-----------------------------------------------------------------------------#
#                                Colorization                                 #
#-----------------------------------------------------------------------------#



sub ColorizeComment {
    if ($Colorize && $_[0] ne "") {
        return "<span class=\"comment\">$_[0]</span>";
    } else {
        return $_[0];
    }
}



sub ColorizeCtrl {
    if ($Colorize) {
        return "<span class=\"ctrl\">$_[0]</span>";
    } else {
        return $_[0];
    }
}



sub ColorizeKeyword {
    if ($Colorize) {
        return "<span class=\"keyword\">$_[0]</span>";
    } else {
        return $_[0];
    }
}



sub ColorizeString {
    if ($Colorize) {
        return "<span class=\"string\">$_[0]</span>";
    } else {
        return $_[0];
    }
}



#-----------------------------------------------------------------------------#
#                            File list management                             #
#-----------------------------------------------------------------------------#



sub AddFile {

    # Argument is file to add
    my $FileName = $_[0];

    # Get just the name (remove a path if there is one)
    my $Name = StripPath ($FileName);

    # Check if we have the file already
    if (exists ($Files{$Name})) {
        Gabble ("File \"$FileName\" already known");
        return;
    }

    # Check with the full pathname. If we don't find it, search in the current
    # directory
    if (-f $FileName && -r _) {
        $Files{$Name} = $FileName;
        $FileCount++;
    } elsif (-f $Name && -r _) {
        $Files{$Name} = $Name;
        $FileCount++;
    } else {
        Abort ("$FileName not found or not readable");
    }
}



#-----------------------------------------------------------------------------#
#                       Referencing and defining labels                       #
#-----------------------------------------------------------------------------#



# Get a label reference
sub RefLabel {

    # Arguments are: Filename, identifier, item that should be tagged
    my $FileName = $_[0];
    my $Id       = $_[1];
    my $Item     = $_[2];

    # Search for the identifier in the list of labels
    if (exists ($Labels{$FileName}{$Id})) {
        # It is a label (in this file)
        return sprintf ("<a href=\"#%s\">%s</a>", $Labels{$FileName}{$Id}, $Item);
    } elsif (exists ($Imports{$FileName}{$Id})) {
        # It is an import. If LinkStyle is 1, or if the file exporting the
        # identifier is not visible, we link to the .import statement in the
        # current file. Otherwise we link directly to the referenced symbol
        # in the file that exports it.
        if ($LinkStyle == 1 or not exists ($Exports{$Id})) {
            return sprintf ("<a href=\"#%s\">%s</a>", $Imports{$FileName}{$Id}, $Item);
        } else {
            # Get the filename from the export
            my $Label;
            ($FileName, $Label) = split (/#/, $Exports{$Id});
            if (not defined ($Labels{$FileName}{$Id})) {
                # This may currently happen because we don't see .include
                # statements, so we may have an export but no definition.
                # Link to the .export statement instead
                $Label = $Exports{$Id};
            } else {
                # Link to the definition in the file
                $Label = sprintf ("%s#%s", $FileName, $Labels{$FileName}{$Id});
            }
            return sprintf ("<a href=\"%s\">%s</a>", $Label, $Item);
        }
    } else {
        # The symbol is unknown, return as is
        return $Item;
    }
}



#-----------------------------------------------------------------------------#
#                                   Pass 1                                    #
# ----------------------------------------------------------------------------#



# Process1: Read one file for the first time.
sub Process1 {

    # Variables
    my $Line;
    my $Id;

    # Filename is parameter
    my $InName = shift(@_);

    # Create the output file name from the input file name
    my $OutName = GetOutName ($InName);

    # Current cheap local label prefix is empty
    my $CheapPrefix = "";

    # Open a the input file
    my $FileName = $Files{$InName};     # Includes path if needed
    open (INPUT, "<$FileName") or Abort ("Cannot open $FileName: $!");

    # Keep the user happy
    Gabble ("$FileName => $OutName");

    # Read and process all lines from the file
    while ($Line = <INPUT>) {

        # Remove the newline
        chomp ($Line);

        # Check for a label
        if ($Line =~ /^\s*(([\@?]?)[_a-zA-Z]\w*)\s*(?::=?|=)/) {

            # Is this a local label?
            if ($2 ne "") {
                # Use the prefix
                $Id = "$CheapPrefix$1";
            } else {
                # Use as is
                $Id = $1;
                # Remember the id as new cheap local prefix
                $CheapPrefix = $Id;
            }

            # Remember the label
            $Labels{$OutName}{$Id} = GenLabel();

        # Check for an import statement
        } elsif ($Line =~ /^\s*\.(?:(?:force)?import|importzp)\s+(.*?)\s*(?:;.*)?$/i) {

            # Split into a list of identifiers
            my @Ids = split (/\s*(?::\s*[A-Za-z]+\s*)?,\s*/, $1);

            # Remove an address-size specifier, from the last identifier,
            # if there is one.
            $Ids[$#Ids] =~ s/\s*:\s*[A-Za-z]+//;

            for $Id (@Ids) {
                $Imports{$OutName}{$Id} = GenLabel();
            }

        # Check for an export statement
        } elsif ($Line =~ /^\s*\.export(?:zp)?\s+(.*?)\s*(?:;.*)?$/i) {

            # Split into a list of identifiers
            my @Ids = split (/\s*(?::\s*[A-Za-z]+\s*)?,\s*/, $1);

            # Remove an address-size specifier, from the last identifier,
            # if there is one.
            $Ids[$#Ids] =~ s/\s*:\s*[A-Za-z]+//;

            for $Id (@Ids) {
                $Exports{$Id} = sprintf ("%s#%s", $OutName, GenLabel());
            }

        # Check for an actor statement.
        } elsif ($Line =~ /^\s*\.(?:(?:(?:con|de)struc|interrup)tor|condes)\s+([_a-z]\w*)/i) {
            $Exports{$1} = sprintf ("%s#%s", $OutName, GenLabel());

        # Check for a .proc statement
        } elsif ($Line =~ /^\s*\.proc\s+([_a-z]\w*)/i) {

            # Remember the ID as the new cheap-local prefix.
            $CheapPrefix = $1;
            $Labels{$OutName}{$1} = GenLabel();
        }
    }

    # Close the input file
    close (INPUT);
}



# Pass1: Read all files for the first time.
sub Pass1 () {

    # Keep the user happy
    Gabble ("Pass 1");

    # Walk over the files
    for my $InName (keys (%Files)) {
        # Process one file
        Process1 ($InName);
    }
}



#-----------------------------------------------------------------------------#
#                                   Pass 2                                    #
# ----------------------------------------------------------------------------#



# Process2: Read one file the second time.
sub Process2 {

    # Variables
    my $Base;
    my $Ext;
    my $Line;
    my $OutLine;
    my $Id;
    my $Label;
    my $Comment;
    my $Trailer;

    # Input file is parameter
    my $InName = shift(@_);

    # Create the output file name from the input file name
    my $OutName = GetOutName ($InName);

    # Current cheap local label prefix is empty
    my $CheapPrefix = "";

    # Open a the input file
    my $FileName = $Files{$InName};     # Includes path if needed
    open (INPUT, "<$FileName") or Abort ("Cannot open $FileName: $!");

    # Open the output file and print the HTML header
    open (OUTPUT, ">$HTMLDir$OutName") or Abort ("Cannot open $OutName: $!");
    DocHeader (OUTPUT, $InName);
    print OUTPUT "<pre>\n";

    # Keep the user happy
    Gabble ("$FileName => $OutName");

    # The instructions that will have hyperlinks if a label is used.
    # And, they will be highlighted when color is used.
    my $LabelIns = "adc|add|and|asl|bb[rs][0-7]|b[cv][cs]|beq|bge|bit|blt|".
                 "bmi|bne|bpl|br[akl]|bsr|cmp|cop|cp[axy]|dec|eor|inc|jml|".
                 "jmp|jsl|jsr|ld[axy]|lsr|mvn|mvp|ora|pe[air]|rep|".
                 "[rs]mb[0-7]|rol|ror|sbc|sep|st[012axyz]|sub|tai|tam|tdd|".
                 "ti[ain]|tma|trb|tsb|tst";

    # Instructions that have only the implied-addressing mode -- therefore,
    # no hyperlinking.  They will be highlighted only, when color is used.
    my $OtherIns = "cl[acdivxy]|csh|csl|de[axy]|in[axy]|nop|ph[abdkpxy]|".
                 "pl[abdpxy]|rt[ils]|sax|say|se[cdit]|stp|swa|sxy|ta[dsxy]|".
                 "tam[0-7]|tcd|tcs|tda|tdc|tma[0-7]|ts[acx]|tx[asy]|tya|tyx|".
                 "wai|xba|xce";

    # Read the input file, replacing references with hyperlinks; and, mark
    # labels as link targets.
    my $LineNo = 0;
    LINE: while ($Line = <INPUT>) {

        # Count input lines
        $LineNo++;

        # Remove the newline at the end of line. Don't use chomp to be able to
        # read dos/windows sources on unices.
        $Line =~ s/[\r\n]*$//;

        # If requested, convert tabs to spaces
        if ($CvtTabs) {
            # Don't ask me - this is from the perl manual page
            1 while ($Line =~ s/\t+/' ' x (length($&) * $TabSize - length($`) % $TabSize)/e) ;
        }

        # Clear the output line
        $OutLine = "";

        # If requested, add a html label to each line with a name "linexxx",
        # so it can be referenced from the outside (this is the same convention
        # that is used by c2html). If we have line numbers enabled, add them.
        if ($LineLabels && $LineNumbers) {
            $OutLine .= sprintf ("<a name=\"line%d\">%6d</a>:  ", $LineNo, $LineNo);
        } elsif ($LineLabels) {
            $OutLine .= sprintf ("<a name=\"line%d\"></a>", $LineNo);
        } elsif ($LineNumbers) {
            $OutLine .= sprintf ("%6d:  ", $LineNo);
        }

        # Cut off a comment from the input line. Beware: We have to check for
        # strings, since these may contain a semicolon that is no comment
        # start.
        ($Line, $Comment) = $Line =~ /^((?:[^"';]+|".*?"|'.*?')*)(.*)$/;
        if ($Comment =~ /^["']/) {
            # Line with invalid syntax - there's a string start but
            # no string end.
            Abort (sprintf ("Invalid input at %s(%d)", $FileName, $LineNo));
        }

        # Remove trailing whitespace and move it together with the comment
        # into the $Trailer variable.
        $Line =~ s/\s*$//;
        $Trailer = $& . ColorizeComment (Cleanup ($Comment));

        # Check for a label at the start of the line. If we have one, process
        # it, and remove it from the line.
        if ($Line =~ s/^\s*?(([\@?]?)[_a-zA-Z]\w*)(\s*(?::=?|=))//) {

            # Is this a local label?
            if ($2 ne "") {
                # Use the prefix
                $Id = "$CheapPrefix$1";
            } else {
                # Use as is
                $Id = $1;
                # Remember the id as new cheap local prefix
                $CheapPrefix = $Id;
            }

            # Get the label for the id
            $Label = $Labels{$OutName}{$Id};

            # Print the label with a tag
            $OutLine .= "<a name=\"$Label\">$1</a>$3";

            # Is the name explicitly assigned a value?
            if ($3 =~ /=$/) {
                # Print all identifiers if there are any.
                while ($Line =~ s/^([^_a-zA-Z]*?)(([\@?]?)[_a-zA-Z]\w*)//) {
                    # Add the non-label stuff.
                    $OutLine .= Cleanup ($1);

                    # Use the prefix if the label is local.
                    # Get the reference to that label if we find it.
                    $OutLine .= RefLabel ($OutName, ($3 ne "") ? "$CheapPrefix$2" : $2, $2);
                }

                # Add a remainder if there is one.
                $OutLine .= Cleanup ($Line);

                # The line is complete; print it.
                next LINE;
            }
        }

        # Print any leading whitespace and remove it, so we don't have to
        # care about whitespace below.
        if ($Line =~ s/^\s+//) {
            $OutLine .= $&;
        }

        # Handle the import statements
        if ($Line =~ s/^\.(?:(?:force)?import|importzp)\s+//i) {

            # Print any fixed stuff from the line and remove it
            $OutLine .= $&;

            # Print all identifiers if there are any
            while ($Line =~ s/^[_a-zA-Z]\w*//) {

                # Remember the identifier
                my $Id = $&;

                # Variable to assemble HTML representation
                my $Contents = "";

                # Make this import a link target
                if (exists ($Imports{$OutName}{$Id})) {
                    $Label = $Imports{$OutName}{$Id};
                    $Contents .= sprintf (" name=\"%s\"", $Label);
                }

                # If we have an export for this import, add a link to this
                # export definition
                if (exists ($Exports{$Id})) {
                    $Label = $Exports{$Id};
                    $Contents .= sprintf (" href=\"%s\"", $Label);
                }

                # Add the HTML stuff to the output line
                if ($Contents ne "") {
                    $OutLine .= sprintf ("<a%s>%s</a>", $Contents, $Id);
                } else {
                    $OutLine .= $Id;
                }

                # Check if another identifier follows
                if ($Line =~ s/^\s*(?::\s*[A-Za-z]+\s*)?,\s*//) {
                    $OutLine .= $&;
                } else {
                    last;
                }
            }

            # Add an remainder if there is one
            $OutLine .= Cleanup ($Line);

        # Handle export statements
        } elsif ($Line =~ s/^\.export(?:zp)?\s+//i) {

            # Print the command and the whitespace.
            $OutLine .= $&;

            # Print all identifiers if there are any
            while ($Line =~ s/^[_a-zA-Z]\w*//) {

                # Remember the identifier
                my $Id = $&;

                # Variable to assemble HTML representation
                my $Contents = "";

                # If we have a definition for this export in this file, add
                # a link to the definition.
                if (exists ($Labels{$OutName}{$Id})) {
                    $Label = $Labels{$OutName}{$Id};
                    $Contents = sprintf (" href=\"#%s\"", $Label);
                }

                # If we have this identifier in the list of exports, add a
                # jump target for the export.
                if (exists ($Exports{$Id})) {
                    $Label = $Exports{$Id};
                    # Be sure to use only the label part
                    $Label =~ s/^.*#//;
                    $Contents .= sprintf (" name=\"%s\"", $Label);
                }

                # Add the HTML stuff to the output line
                if ($Contents ne "") {
                    $OutLine .= sprintf ("<a%s>%s</a>", $Contents, $Id);
                } else {
                    $OutLine .= $Id;
                }

                # Check if another identifier follows
                if ($Line =~ s/^\s*(?::\s*[A-Za-z]+\s*)?,\s*//) {
                    $OutLine .= $&;
                } else {
                    last;
                }
            }

            # Add an remainder if there is one
            $OutLine .= Cleanup ($Line);

        # Handle actor statements.
        } elsif ($Line =~ s/^(\.(?:(?:(?:con|de)struc|interrup)tor|condes)\s+)([_a-z]\w*)//i) {

            # Print the command and the whitespace.
            $OutLine .= $1;

            # Remember the identifier.
            $Id = $2;

            # Variable to assemble HTML representation
            my $Contents = "";

            # If we have a definition for this actor, in this file,
            # then add a link to that definition.
            if (exists ($Labels{$OutName}{$Id})) {
                $Contents = sprintf (" href=\"#%s\"", $Labels{$OutName}{$Id});
            }

            # Get the target, for linking from imports in other files.
            $Label = $Exports{$Id};
            # Be sure to use only the label part.
            $Label =~ s/^.*#//;

            # Add the HTML stuff and the remainder of the actor
            # to the output line.
            $OutLine .= sprintf ("<a name=\"%s\"%s>%s</a>%s", $Label,
                                 $Contents, $Id, Cleanup ($Line));

        # Check for .faraddr, .addr, .dword, .word, .dbyt, .byt, .byte, .res,
        # .elseif, .if, .align, and .org.
        } elsif ($Line =~ s/^\.(?:(?:far)?addr|d?word|d?byte?|res|(?:else)?if|align|org)\s+//i) {

            # Print the command and the white space
            $OutLine .= $&;

            # Print all identifiers if there are any
            while ($Line =~ s/^([^_a-zA-Z]*?)(([\@?]?)[_a-zA-Z]\w*)//) {
                # Add the non label stuff
                $OutLine .= Cleanup ($1);

                # Use the prefix if the label is local.
                # Get the reference to that label if we find it.
                $OutLine .= RefLabel ($OutName, ($3 ne "") ? "$CheapPrefix$2" : $2, $2);
            }

            # Add an remainder if there is one
            $OutLine .= Cleanup ($Line);

        # Handle .proc
        } elsif ($Line =~ /^(\.proc)(\s+)([_a-z]\w*)?(.*)$/i) {

            # Do we have an identifier?
            if ($3 ne "") {
                # Remember the ID as the new cheap-local prefix.
                $CheapPrefix = $3;

                # Get the label for the id
                $Label = $Labels{$OutName}{$3};

                # Print the label with a tag
                $OutLine .= "$1$2<a name=\"$Label\">$3</a>";

            } else {

                # Print a line that has invalid syntax (its operand isn't
                # a correctly formed name).
                $OutLine .= "$1$2";
            }

            # Add the remainder
            $OutLine .= Cleanup ($4);

        # Handle .include
        } elsif ($Line =~ /^(\.include)(\s*)\"((?:[^\"]+?|\\\")+)(\".*)$/i) {

            # Add the fixed stuff to the output line
            $OutLine .= "$1$2&quot;";

            # Get the filename into a named variable
            my $FileName = Cleanup ($3);

            # Get the name without a path
            my $Name = StripPath ($3);

            # If the include file is among the list of our files, add a link,
            # otherwise just add the name as is.
            if (exists ($Files{$Name})) {
                $OutLine .= sprintf ("<a href=\"%s\">%s</a>", GetOutName ($Name), $FileName);
            } else {
                $OutLine .= $FileName;
            }

            # Add the remainder
            $OutLine .= Cleanup ($4);

        # Handle .dbg line
        } elsif ($CRefs && $Line =~ s/^\.dbg\s+//) {

            # Add the fixed stuff to the output line
            $OutLine .= $&;

            # Check for the type of the .dbg directive
            if ($Line =~ /^(line,\s*)\"((?:[^\"]+?|\\\")+)\"(,\s*)(\d+)(.*)$/) {

                # Add the fixed stuff to the output line
                $OutLine .= "$1&quot;";

                # Get the filename and line number into named variables
                my $DbgFile = $2;
                my $DbgLine = $4;

                # Remember the remainder
                $Line = "\"$3$4$5";

                # Get the name without a path
                my $Name = StripPath ($DbgFile);

                # We don't need FileName any longer as is, so clean it up
                $DbgFile = Cleanup ($DbgFile);

                # Add a link to the source file
                $OutLine .= sprintf ("<a href=\"%s.html#line%d\">%s</a>", $Name, $DbgLine, $DbgFile);

                # Add the remainder
                $OutLine .= Cleanup ($Line);

            } elsif ($Line =~ /^(file,\s*)\"((?:[^\"]+?|\\\")+)\"(.*)$/) { #pf FIXME: doesn't handle \" correctly!

                # Get the filename into a named variables
                my $DbgFile = Cleanup ($2);

                # Get the name without a path
                my $Name = Cleanup (StripPath ($2));

                # Add the fixed stuff to the output line
                $OutLine .= sprintf ("%s\"<a href=\"%s.html\">%s</a>\"%s",
                                     $1, $Name, $DbgFile, $3);

            } else {

                # Add the remainder
                $OutLine .= Cleanup ($Line);

            }

        } elsif ($CRefs && $Line =~ /^(\.dbg)(\s+line,\s*)\"((?:[^\"]+?|\\\")+)\"(,\s*)(\d+)(.*$)/) {

            # Add the fixed stuff to the output line
            $OutLine .= "$1$2&quot;";

            # Get the filename and line number into named variables
            my $FileName = $3;
            my $LineNo   = $5;

            # Remember the remainder
            $Line = "\"$4$5$6";

            # Get the name without a path
            my $Name = StripPath ($FileName);

            # We don't need FileName any longer as is, so clean it up
            $FileName = Cleanup ($FileName);

            # Add a link to the source file
            $OutLine .= sprintf ("<a href=\"%s.html#line%d\">%s</a>", $Name, $LineNo, $FileName);

            # Add the remainder
            $OutLine .= Cleanup ($Line);

        # Check for .ifdef, .ifndef, .ifref, and .ifnref.
        } elsif ($Line =~ s/^(\.ifn?[dr]ef\s+)(([\@?]?)[_a-z]\w*)?//i) {

            # Print the command and the whitespace.
            $OutLine .= $1;

            if ($2 ne "") {
                # Use the prefix if the label is local.
                # Get the reference to that label if we find it.
                $OutLine .= RefLabel ($OutName, ($3 ne "") ? "$CheapPrefix$2" : $2, $2);
            }

            # Add a remainder if there is one.
            $OutLine .= Cleanup ($Line);

        # Check for assertions.
        } elsif ($Line =~ s/^(\.assert\s+)(.+?)(,\s*(?:error|warning)\s*(?:,.*)?)$/$2/i) {

            # Print the command and the whitespace.
            $OutLine .= $1;

            $Comment = $3;

            # Print all identifiers if there are any.
            while ($Line =~ s/^([^_a-zA-Z]*?)(([\@?]?)[_a-zA-Z]\w*)//) {
                # Add the non-label stuff.
                $OutLine .= Cleanup ($1);

                # Use the prefix if the label is local.
                # Get the reference to that label if we find it.
                $OutLine .= RefLabel ($OutName, ($3 ne "") ? "$CheapPrefix$2" : $2, $2);
            }

            # Add a remainder if there is one.
            $OutLine .= Cleanup ($Line . $Comment);

        # Check for instructions with labels
        } elsif ($Line =~ s/^($LabelIns)\b(\s*)//io) {

            # Print the instruction and white space
            $OutLine .= ColorizeKeyword ($1) . $2;

            # Print all identifiers if there are any.
            while ($Line =~ s/^([^_a-zA-Z]*?)(([\@?]?)[_a-zA-Z]\w*)//) {

                # Add the non-label stuff.
                $OutLine .= Cleanup ($1);

                # Is this a local label?
                if ($3 ne "") {
                    # Use the prefix
                    $Id = "$CheapPrefix$2";
                } else {
                    # Use as is
                    $Id = $2;
                }

                # Get the reference to this label if we find it
                $OutLine .= RefLabel ($OutName, $Id, $2);
            }

            # Reassemble and print the line
            $OutLine .= Cleanup ($Line);

        # Check for all other instructions
        } elsif ($Line =~ /^($OtherIns)\b(.*)$/io) {

            # Colorize and print
            $OutLine .= ColorizeKeyword ($1) . Cleanup ($2);

        } else {

            # Nothing known - print the line
            $OutLine .= Cleanup ($Line);

        }

    } continue {
        # Colorize all keywords
        $OutLine =~ s/(?<![\w;])\.[_a-zA-Z]\w*/ColorizeCtrl ($&)/ge;

        # Print the result with the trailer.
        print OUTPUT "$OutLine$Trailer\n";
    }

    # Print the HTML footer
    print OUTPUT "</pre>\n";
    DocFooter (OUTPUT, $OutName);

    # Close the files
    close (INPUT);
    close (OUTPUT);
}



# Pass2: Read all files the second time.
sub Pass2 () {

    # Keep the user happy
    Gabble ("Pass 2");

    # Walk over the files
    for my $InName (keys (%Files)) {
        # Process one file
        Process2 ($InName);
    }
}



#-----------------------------------------------------------------------------#
#                            Create an index page                             #
# ----------------------------------------------------------------------------#



# Print a list of all files
sub FileIndex {

    # File is argument
    my $INDEX = $_[0];

    # Print the file list in a table
    print $INDEX "<h2>Files</h2><p>\n";
    print $INDEX "<table border=\"0\" width=\"100%\">\n";
    my $Count = 0;
    for my $File (sort (keys (%Files))) {

        #
        if (($Count % $IndexCols) == 0) {
            print $INDEX "<tr>\n";
        }
        printf $INDEX "<td><a href=\"%s\">%s</a></td>\n", GetOutName ($File), $File;
        if (($Count % $IndexCols) == $IndexCols-1) {
            print $INDEX "</tr>\n";
        }
        $Count++;
    }
    if (($Count % $IndexCols) != 0) {
        print $INDEX "</tr>\n";
    }
    print $INDEX "</table><p><br><p>\n";
}



# Print a list of all exports
sub ExportIndex {

    # File is argument
    my $INDEX = $_[0];

    # Print the file list in a table
    print $INDEX "<h2>Exports</h2><p>\n";
    print $INDEX "<table border=\"0\" width=\"100%\">\n";
    my $Count = 0;
    for my $Export (sort (keys (%Exports))) {

        # Get the export
        my $File;
        my $Label;
        ($File, $Label) = split (/#/, $Exports{$Export});

        # The label is the label of the export statement. If we can find the
        # actual label, use this instead.
        if (exists ($Labels{$File}{$Export})) {
            $Label = $Labels{$File}{$Export};
        }

        #
        if (($Count % $IndexCols) == 0) {
            print $INDEX "<tr>\n";
        }
        printf $INDEX "<td><a href=\"%s#%s\">%s</a></td>\n", $File, $Label, $Export;
        if (($Count % $IndexCols) == $IndexCols-1) {
            print $INDEX "</tr>\n";
        }
        $Count++;
    }
    if (($Count % $IndexCols) != 0) {
        print $INDEX "</tr>\n";
    }
    print $INDEX "</table><p><br><p>\n";
}



sub CreateIndex {

    # Open the index page file
    open (INDEX, ">$HTMLDir$IndexName") or Abort ("Cannot open $IndexName: $!");

    # Print the header
    DocHeader (INDEX, $IndexTitle, 0);

    # Print the file list in a table
    FileIndex (INDEX);
    ExportIndex (INDEX);

    # Print the document footer
    DocFooter (INDEX, $IndexName);

    # Close the index file
    close (INDEX);
}



#-----------------------------------------------------------------------------#
#                           Print usage information                           #
# ----------------------------------------------------------------------------#



sub Usage {
    print "Usage: ca65html [options] file ...\n";
    print "Options:\n";
    print "  --bgcolor c        Use background color c instead of $BGColor\n";
    print "  --colorize         Add color highlights to the output\n";
    print "  --commentcolor c   Use color c for comments instead of $CommentColor\n";
    print "  --crefs            Generate references to the C source file(s)\n";
    print "  --ctrlcolor c      Use color c for directives instead of $CtrlColor\n";
    print "  --cvttabs          Convert tabs to spaces in the output\n";
    print "  --help             This text\n";
    print "  --htmldir dir      Specify directory for HTML files\n";
    print "  --indexcols n      Use n columns on index page (default $IndexCols)\n";
    print "  --indexname file   Use file for the index file instead of $IndexName\n";
    print "  --indexpage        Create an index page\n";
    print "  --indextitle title Use title as the index title instead of $IndexTitle\n";
    print "  --keywordcolor c   Use color c for keywords instead of $KeywordColor\n";
    print "  --linelabels       Generate a linexxx HTML label for each line\n";
    print "  --linenumbers      Add line numbers to the output\n";
    print "  --linkstyle style  Use the given link style\n";
    print "  --replaceext       Replace source extension instead of appending .html\n";
    print "  --tabsize n        Use n spaces when replacing tabs (default $TabSize)\n";
    print "  --textcolor c      Use text color c instead of $TextColor\n";
    print "  --verbose          Be more verbose\n";
}



#-----------------------------------------------------------------------------#
#                                    Main                                     #
# ----------------------------------------------------------------------------#



# Get program options
GetOptions ("bgcolor=s"         => \$BGColor,
            "colorize"          => \$Colorize,
            "commentcolor=s"    => \$CommentColor,
            "crefs"             => \$CRefs,
            "ctrlcolor=s"       => \$CtrlColor,
            "cvttabs"           => \$CvtTabs,
            "debug!"            => \$Debug,
            "help"              => \$Help,
            "htmldir=s"         => \$HTMLDir,
            "indexcols=i"       => \$IndexCols,
            "indexname=s"       => \$IndexName,
            "indexpage"         => \$IndexPage,
            "indextitle=s"      => \$IndexTitle,
            "keywordcolor=s"    => \$KeywordColor,
            "linelabels"        => \$LineLabels,
            "linenumbers"       => \$LineNumbers,
            "linkstyle=i"       => \$LinkStyle,
            "replaceext"        => \$ReplaceExt,
            "tabsize=i"         => \$TabSize,
            "textcolor=s"       => \$TextColor,
            "verbose!"          => \$Verbose,
            "<>"                => \&AddFile);

# Check some arguments
if ($IndexCols <= 0 || $IndexCols >= 20) {
    Abort ("Invalid value for --indexcols option");
}
if ($TabSize < 1 || $TabSize > 16) {
    Abort ("Invalid value for --tabsize option");
}
if ($HTMLDir ne "" && $HTMLDir =~ /[^\/]$/) {
    # Add a trailing path separator
    $HTMLDir .= "/";
}



# Print help if requested
if ($Help) {
    Usage ();
}

# Check if we have input files given
if ($FileCount == 0) {
    Abort ("No input files");
}

# Convert the documents
Pass1 ();
Pass2 ();

# Generate an index page if requested
if ($IndexPage) {
    CreateIndex ();
}

# Done
exit 0;