--- a/doc/main.docbook	Wed Jan 28 05:38:15 2009 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,97 +0,0 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
-<book>
-<bookinfo>
-<title>LW Tool Chain</title>
-<author><firstname>William</firstname><surname>Astle</surname></author>
-<copyright><year>2009</year><holder>William Astle</holder></copyright>
-</bookinfo>
-<chapter>
-
-<title>Introduction</title>
-
-<para>
-The LW tool chain provides utilities for building binaries for MC6809 and
-HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
-which support several styles of output.
-</para>
-
-<section>
-<title>History</title>
-<para>
-For a long time, I have had an interest in creating an operating system for
-the Coco3. I finally started working on that project around the beginning of
-2006. I had a number of assemblers I could choose from. Eventually, I settled
-on one and started tinkering. After a while, I realized that assembler was not
-going to be sufficient due to lack of macros and issues with forward references.
-Then I tried another which handled forward references correctly but still did
-not support macros. I looked around at other assemblers and they all lacked
-one feature or another that I really wanted for creating my operating system.
-</para>
-
-<para>
-The solution seemed clear at that point. I am a fair programmer so I figured
-I could write an assembler that would do everything I wanted an assembler to
-do. Thus the LWASM probject was born. After more than two years of on and off
-work, version 1.0 of LWASM was released in October of 2008.
-</para>
-
-<para>
-As the aforementioned operating system project progressed further, it became
-clear that while assembling the whole project through a single file was doable,
-it was not practical. When I found myself playing some fancy games with macros
-in a bid to simulate sections, I realized I needed a means of assembling
-source files separately and linking them later. This spawned a major development
-effort to add an object file support to LWASM. It also spawned the LWLINK
-project to provide a means to actually link the files.
-</para>
-
-</section>
-
-</chapter>
-
-<chapter>
-<title>Output Formats</title>
-
-<para>
-The LW tool chain supports multiple output formats. Each format has its
-advantages and disadvantages. Each format is described below.
-</para>
-
-<section>
-<title>Raw Binaries</title>
-<para>
-A raw binary is simply a string of bytes. There are no headers or other
-niceties. Both lwlink and lwasm support generating raw binaries. ORG directives
-in the source code only serve to set the addresses that will be used for
-symbols but otherwise have no direct impact on the resulting binary.
-</para>
-
-</section>
-<section>
-<title>DECB Binaries</title>
-
-<para>A DECB binary is compatible with the LOADM command in Disk Extended
-Color Basic on the CoCo. They are also compatible with CLOADM from Extended
-Color Basic. These binaries include the load address of the binary as well
-as encoding an execution address. These binaries may contain multiple loadable
-sections, each of which has its own load address.</para>
-
-<para>
-Each binary starts with a preamble. Each preamble is five bytes long. The
-first byte is zero. The next two bytes specify the number of bytes to load
-and the last two bytes specify the address to load the bytes at. Then, a
-string of bytes follows. After this string of bytes, there may be another
-preamble or a postamble. A postamble is also five bytes in length. The first
-byte of the postamble is $FF, the next two are zero, and the last two are
-the execution address for the binary.
-</para>
-
-<para>
-Both lwasm and lwlink can output this format.
-</para>
-</section>
-
-
-</chapter>
-</book>
-

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual.docbook.sgml	Wed Jan 28 05:38:21 2009 +0000
@@ -0,0 +1,122 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
+<book>
+<bookinfo>
+<title>LW Tool Chain</title>
+<author><firstname>William</firstname><surname>Astle</surname></author>
+<copyright><year>2009</year><holder>William Astle</holder></copyright>
+</bookinfo>
+<chapter>
+
+<title>Introduction</title>
+
+<para>
+The LW tool chain provides utilities for building binaries for MC6809 and
+HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
+which support several styles of output.
+</para>
+
+<section>
+<title>History</title>
+<para>
+For a long time, I have had an interest in creating an operating system for
+the Coco3. I finally started working on that project around the beginning of
+2006. I had a number of assemblers I could choose from. Eventually, I settled
+on one and started tinkering. After a while, I realized that assembler was not
+going to be sufficient due to lack of macros and issues with forward references.
+Then I tried another which handled forward references correctly but still did
+not support macros. I looked around at other assemblers and they all lacked
+one feature or another that I really wanted for creating my operating system.
+</para>
+
+<para>
+The solution seemed clear at that point. I am a fair programmer so I figured
+I could write an assembler that would do everything I wanted an assembler to
+do. Thus the LWASM probject was born. After more than two years of on and off
+work, version 1.0 of LWASM was released in October of 2008.
+</para>
+
+<para>
+As the aforementioned operating system project progressed further, it became
+clear that while assembling the whole project through a single file was doable,
+it was not practical. When I found myself playing some fancy games with macros
+in a bid to simulate sections, I realized I needed a means of assembling
+source files separately and linking them later. This spawned a major development
+effort to add an object file support to LWASM. It also spawned the LWLINK
+project to provide a means to actually link the files.
+</para>
+
+</section>
+
+</chapter>
+
+<chapter>
+<title>Output Formats</title>
+
+<para>
+The LW tool chain supports multiple output formats. Each format has its
+advantages and disadvantages. Each format is described below.
+</para>
+
+<section>
+<title>Raw Binaries</title>
+<para>
+A raw binary is simply a string of bytes. There are no headers or other
+niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
+in the source code only serve to set the addresses that will be used for
+symbols but otherwise have no direct impact on the resulting binary.
+</para>
+
+</section>
+<section>
+<title>DECB Binaries</title>
+
+<para>A DECB binary is compatible with the LOADM command in Disk Extended
+Color Basic on the CoCo. They are also compatible with CLOADM from Extended
+Color Basic. These binaries include the load address of the binary as well
+as encoding an execution address. These binaries may contain multiple loadable
+sections, each of which has its own load address.</para>
+
+<para>
+Each binary starts with a preamble. Each preamble is five bytes long. The
+first byte is zero. The next two bytes specify the number of bytes to load
+and the last two bytes specify the address to load the bytes at. Then, a
+string of bytes follows. After this string of bytes, there may be another
+preamble or a postamble. A postamble is also five bytes in length. The first
+byte of the postamble is $FF, the next two are zero, and the last two are
+the execution address for the binary.
+</para>
+
+<para>
+Both LWASM and LWLINK can output this format.
+</para>
+</section>
+
+<section>
+<title>Object Files</title>
+<para>LWASM supports generating a proprietary object file format which is
+described in <xref linkend="objchap">. LWLINK is then used to link these
+object files into a final binary in any of LWLINK's supported binary
+formats.</para>
+
+<para>Object files are very flexible in that they allow references that are not
+known at assembly time to be resolved at link time. However, because the
+addresses of such references are not known, there is no way for the assembler
+has to use sixteen bit addressing modes for these references. The linker
+will always use sixteen bits when resolving a reference which means any
+instruction that requires an eight bit operand cannot use external references.
+</para>
+
+<para>Object files also support the concept of sections which are not valid
+for other output types. This allows related code from each object file
+linked to be collapsed together in the final binary.</para> 
+
+</section>
+
+</chapter>
+
+<chapter id="objchap">
+<title>Object Files</title>
+<para></para>
+</chapter>
+</book>
+