diff --git a/doc/Makefile b/doc/Makefile index 9a32134d4..fff4315d9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,6 +9,7 @@ SGML = ar65.sgml \ atari.sgml \ c64.sgml \ ca65.sgml \ + ca65html.sgml \ cc65.sgml \ cl65.sgml \ co65.sgml \ diff --git a/doc/ca65html.sgml b/doc/ca65html.sgml new file mode 100644 index 000000000..6e797269d --- /dev/null +++ b/doc/ca65html.sgml @@ -0,0 +1,298 @@ + + +
+ca65html Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-10-16 + +<abstract> +ca65html is an assembler 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 assembler source files written for use with the <tt/<htmlurl +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 Colorize the output (generates non standard HTML) + --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). This color is used in the <tt/<body>/ tag 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. + + While this make the output look very nice, it generates invalid HTML, + because using colors in a <tt/<pre>/ environment is not allowed. + However, most browsers display it well, and it is used by several other + tools, so it's up to you. + + + <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 all label names and + 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 <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>/ + tag 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 + may like a little bit more progress information. + +</descrip> +<p> + + +<sect>Peculiarities<p> + +<sect1>Cross links<p> + +Since <tt/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, <tt/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 <tt/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 may miss a label may choose the +wrong color for an item in rare cases. Since 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 two drawbacks: + +<enum> + +<item>The output is not standard compliant HTML, because <tt/<font>/ +tags are use in a <tt/<pre>/ environment. This works with all browsers +I've tested, but it may not work with the one you're using. + +<item>Since lots of <tt/<font>/ tags are created in the output, the size +of the output file will literally explode. This seems to be the price, you +have to pay for color... + +</enum> + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the assembler, I would be glad to hear from +you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ca65html is (C) Copyright 2000-2003 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> + + + diff --git a/doc/index.sgml b/doc/index.sgml index 91a961926..9e07e18ab 100644 --- a/doc/index.sgml +++ b/doc/index.sgml @@ -9,71 +9,104 @@ Main documentation page, contains links to other available stuff. </abstract> -<sect>Documentation overview<p> +<sect>Program documentation<p> <descrip> - <tag><htmlurl url="BUGS" name="BUGS"></tag> - Known compiler bugs. - - <tag><htmlurl url="CREDITS" name="CREDITS"></tag> - Who helped with the compiler and tools? - <tag><htmlurl url="ar65.html" name="ar65.html"></tag> Describes the ar65 archiver. <tag><htmlurl url="ca65.html" name="ca65.html"></tag> Describes the ca65 macro assembler. + <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag> + Describes the ca65html assembler source to HTML converter. + <tag><htmlurl url="cc65.html" name="cc65.html"></tag> Describes the cc65 C compiler. <tag><htmlurl url="cl65.html" name="cl65.html"></tag> Describes the cl65 compile & link utility. + <tag><htmlurl url="da65.html" name="da65.html"></tag> + Describes the da65 6502/65C02 disassembler. + + <tag><htmlurl url="grc.txt" name="grc.txt"></tag> + Describes the GEOS resource compiler (grc). + + <tag><htmlurl url="ld65.html" name="ld65.html"></tag> + Describes the ld65 linker. + +</descrip> + + +<sect>Usage<p> + +<descrip> + + <tag><htmlurl url="intro.html" name="intro.html"></tag> + Describes the use of the tools by a short "hello world" example. + <tag><htmlurl url="coding.html" name="coding.html"></tag> Containes hints on creating the most effective code with cc65. <tag><htmlurl url="compile.txt" name="compile.txt"></tag> How to compile cc65 and the support tools. - <tag><htmlurl url="da65.html" name="da65.html"></tag> - Describes the da65 6502/65C02 disassembler. - <tag><htmlurl url="debugging.html" name="debugging.html"></tag> Debug programs using the VICE emulator. - <tag><htmlurl url="dio.html" name="dio.html"></tag> - Low level disk I/O API. +</descrip> + +<sect>Library information and other references<p> + +<descrip> <tag><htmlurl url="funcref.html" name="funcref.html"></tag> A (currently incomplete) function reference. + <tag><htmlurl url="dio.html" name="dio.html"></tag> + Low level disk I/O API. + <tag><htmlurl url="geos.html" name="geos.html"></tag> - GEOSLib manual in several formats. - - <tag><htmlurl url="grc.txt" name="grc.txt"></tag> - Describes the GEOS resource compiler (grc). - - <tag><htmlurl url="index.html" name="index.html"></tag> - This file. + The GEOSLib manual. <tag><htmlurl url="internal.txt" name="internal.txt"></tag> A somewhat older text describing several cc65 internals. - <tag><htmlurl url="intro.html" name="intro.html"></tag> - Describes the use of the tools by a short "hello world" example. - - <tag><htmlurl url="ld65.html" name="ld65.html"></tag> - Describes the ld65 linker. - <tag><htmlurl url="library.html" name="library.html"></tag> Describes the cc65 runtime and C libraries. +</descrip> + + +<sect>Platform specific information<p> + +<descrip> + + <tag><htmlurl url="atari.html" name="atari.html"></tag> + Topics specific to the Atari 8 bit machines. + + <tag><htmlurl url="c64.html" name="c64.html"></tag> + Topics specific to the Commodore 64. + +</descrip> + + +<sect>Miscellaneous<p> + +<descrip> + <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag> Somewhat outdated. Lists the differences between the current cc65 release and the original atari version created by J.R Dunning. + <tag><htmlurl url="BUGS" name="BUGS"></tag> + Known compiler bugs. + + <tag><htmlurl url="CREDITS" name="CREDITS"></tag> + Who helped with the compiler and tools? + </descrip> </article>