+++ /dev/null
-<!doctype linuxdoc system>
-
-<article>
-<title>ca65html Users Guide
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2007-10-2
-
-<abstract>
-ca65html is an assembly-source-to-HTML converter. It is very useful if you
-want to publish your assembler sources in the web.
-</abstract>
-
-<!-- Table of contents -->
-<toc>
-
-<!-- Begin the document -->
-
-<sect>Overview<p>
-
-ca65html converts assembly source files written for use with the <tt/<url
-url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone
-tool written in PERL; and as such, it does not understand the structure of
-assembler sources in the same depth as ca65 does, so it may fail in very rare
-cases. In all other cases, it generates very nice output.
-
-
-<sect>Usage<p>
-
-
-<sect1>Command line option overview<p>
-
-The HTML converter accepts the following options:
-
-<tscreen><verb>
----------------------------------------------------------------------------
-Usage: ca65html [options] file ...
-Options:
- --bgcolor c Use background color c instead of #FFFFFF
- --colorize Add color highlights to the output
- --commentcolor c Use color c for comments instead of #B22222
- --crefs Generate references to the C source file(s)
- --ctrlcolor c Use color c for directives instead of #228B22
- --cvttabs Convert tabs to spaces in the output
- --help This text
- --htmldir dir Specify directory for HTML files
- --indexcols n Use n columns on index page (default 6)
- --indexname file Use file for the index file instead of index.html
- --indexpage Create an index page
- --indextitle title Use title as the index title instead of Index
- --keywordcolor c Use color c for keywords instead of #A020F0
- --linelabels Generate a linexxx HTML label for each line
- --linenumbers Add line numbers to the output
- --linkstyle style Use the given link style
- --replaceext Replace source extension instead of appending .html
- --textcolor c Use text color c instead of #000000
- --verbose Be more verbose
----------------------------------------------------------------------------
-</verb></tscreen>
-
-
-<sect1>Command line options in detail<p>
-
-Here is a description of all the command line options:
-
-<descrip>
-
- <tag><tt>--bgcolor c</tt></tag>
-
- Set the background color. The argument c must be a valid HTML color, usually
- given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the
- respective red, green, and blue parts as two-digit hex values. The default is
- <tt/#FFFFFF/ (white). That color is used in the <tt/<body>/ of the
- generated HTML output.
-
-
- <tag><tt>--colorize</tt></tag>
-
- Colorize the output. The converter outputs processor instructions, assembler
- control commands, and comments in different colors.
-
-
- <tag><tt>--commentcolor c</tt></tag>
-
- Set the color used for comments. The argument c must be a valid HTML color,
- usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
- the respective red, green, and blue parts as two-digit hex values. The
- default is <tt/#B22222/ (red).
-
- Note that this option has no effect if <tt/--colorize/ is not also given.
-
-
- <tag><tt>--crefs</tt></tag>
-
- Generate references to the C file, when a <tt/.dbg/ command is found with a
- file name. The converter assumes that the C source was also converted into
- HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and
- lives in the same directory as the assembler file. If the <tt/.dbg/
- directive specifies a line, a link to the correct line in the C file is
- generated, using a label in the form <tt/linexxx/, as it is created by
- <tt/c2html/ by use of the <tt/-n/ option.
-
-
- <tag><tt>--commentcolor c</tt></tag>
-
- Set the color used for assembler control commands. The argument c must be a
- valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
- where r, g, and b are the respective red, green, and blue parts as two-digit
- hex values. The default is <tt/#228B22/ (green).
-
- Note that this option has no effect if <tt/--colorize/ is not also given.
-
-
- <tag><tt>--cvttabs</tt></tag>
-
- Convert tabs in the input into spaces in the output, assuming the standard
- tab width of 8. This is useful if the <tt/--linenumbers/ option is used to
- retain the indentation.
-
-
- <tag><tt>--help</tt></tag>
-
- Print the command line option summary shown above.
-
-
- <tag><tt>--htmldir dir</tt></tag>
-
- Specify an output directory for the generated HTML files.
-
-
- <tag><tt>--indexcols n</tt></tag>
-
- Use n columns on the index page. This option has no effect if used without
- <tt/--indexpage/.
-
-
- <tag><tt>--indexname name</tt></tag>
-
- Use another index file name instead of <tt/index.html/. This option has no
- effect if used without <tt/--indexpage/.
-
-
- <tag><tt>--indexpage</tt></tag>
-
- Causes the converter to generate an index page listing file names, and all
- exports found in the converted files.
-
-
- <tag><tt>--indextitle title</tt></tag>
-
- Use "title" as the title of the index page. This option has no effect if
- used without <tt/--indexpage/.
-
-
- <tag><tt>--keywordcolor c</tt></tag>
-
- Set the color used for processor instructions. The argument c must be a
- valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
- where r, g, and b are the respective red, green, and blue parts as two-digit
- hex values. The default is <tt/#A020F0/ (purple).
-
- Note that this option has no effect if <tt/--colorize/ is not also given.
-
- <tag><tt>--linelabels</tt></tag>
-
- Generate a label for each line using the name <tt/linexxx/ where xxx is the
- number of the line.
-
- Note: The converter will not make use of this label. Use this option if you
- have other HTML pages referencing the converted assembler file.
-
-
- <tag><tt>--linenumbers</tt></tag>
-
- Generate line numbers on the left side of the output.
-
-
- <tag><tt>--linkstyle n</tt></tag>
-
- Influences the style used when generating links for imports. If n is zero
- (the default), the converter creates a link to the actual symbol if it is
- defined somewhere in the input files. If not, it creates a link to the
- <tt/.import/ statement. If n is one, the converter will always generate a
- HTML link to the <tt/.import/ statement.
-
-
- <tag><tt>--replaceext</tt></tag>
-
- Replace the file extension of the input file instead of appending <tt/.html/
- when generating the output file name.
-
-
- <tag><tt>--textcolor c</tt></tag>
-
- Set the color for normal text. The argument c must be a valid HTML color,
- usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
- the respective red, green, and blue parts as two-digit hex values. The
- default is <tt/#000000/ (black). This color is used in the <tt/<body>/
- of the generated HTML output.
-
-
- <tag><tt>--verbose</tt></tag>
-
- Increase the converter verbosity. Without this option, ca65html is quiet
- when working. If you have a slow machine and lots of files to convert, you
- might like a little bit more progress information.
-
-</descrip>
-<p>
-
-
-<sect>Peculiarities<p>
-
-<sect1>Cross links<p>
-
-Since ca65html is able to generate links between modules, the best way to use
-it is to supply all modules to it in one run, instead of running each file
-separately through it.
-
-
-<sect1>Include files<p>
-
-For now, ca65html will not read files included with <tt/.include/. Specifying
-the include files as normal input files on the command line works in many
-cases.
-
-
-<sect1>Conversion errors<p>
-
-Since ca65html does not really parse the input, but does most of its work
-applying text patterns, it doesn't know anything about scoping and advanced
-features of the assembler. This means that it might miss a label. And, it
-might choose the wrong color for an item, in rare cases. Because it's just a
-tool for displaying sources in a nice form, I think that's OK. Anyway, if you
-find a conversion problem, you can send me a short piece of example input code.
-If possible, I will fix it.
-
-
-<sect1>Colorization<p>
-
-While having colors in the output looks really nice, it has one drawback:
-
-<enum>
-
-<item>Because lots of <tt/<span>/ tags are created in the output,
-the size of the output file literally will explode. It seems to be the price
-that you have to pay for color.
-
-</enum>
-
-
-<sect>Copyright<p>
-
-ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the
-following conditions apply:
-
-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:
-
-<enum>
-<item> 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.
-<item> Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-<item> This notice may not be removed or altered from any source
- distribution.
-</enum>
-
-
-
-</article>
-
-
-
projects / cc65 / commitdiff