From 03311e72689111c76b07f39b1ed181a9efc4ebd0 Mon Sep 17 00:00:00 2001
From: Christian Groessler <chris@groessler.org>
Date: Fri, 12 Apr 2019 14:01:26 +0200
Subject: [PATCH] atari5200: update docs for recent conio changes

also renames libsrc/atari5200/extra/conioscreen_20x12.s to
libsrc/atari5200/extra/conioscreen-20x12.s to be in line with
other optional link modules
---
 doc/atari5200.sgml                            | 42 ++++++++++++++++++-
 doc/library.sgml                              |  1 +
 ...onioscreen_20x12.s => conioscreen-20x12.s} |  0
 3 files changed, 42 insertions(+), 1 deletion(-)
 rename libsrc/atari5200/extra/{conioscreen_20x12.s => conioscreen-20x12.s} (100%)

diff --git a/doc/atari5200.sgml b/doc/atari5200.sgml
index fedac4466..bd2b6adcb 100644
--- a/doc/atari5200.sgml
+++ b/doc/atari5200.sgml
@@ -52,7 +52,7 @@ Special locations:
   <tag/Text screen/
   The text screen is only enabled if any of the CONIO output functions
   is used in the program. Its size is 20x24 characters (Antic mode 6,
-  BASIC mode 1). The text screen is located at &dollar;3E00. The
+  BASIC mode 1) by default. The text screen is located at &dollar;3E00. The
   address of the screen memory is available at runtime in the variable
   SAVMSC (&dollar;001B).<p>
   If the program doesn't use any CONIO output functions it needs to setup its own
@@ -151,6 +151,43 @@ No serial drivers are available for the Atari 5200.
 
 <sect>Limitations<p>
 
+
+<sect1>Direct console I/O<p>
+
+The <tt/atari5200/ target uses Antic mode 6 (BASIC mode 1) for the console
+screen by default. There are four colors available:
+
+<itemize>
+<item><tt/COLOR_WHITE/
+<item><tt/COLOR_RED/
+<item><tt/COLOR_GREEN/
+<item><tt/COLOR_BLACK/
+</itemize>
+
+Note that the <tt/COLOR_GREEN/ and <tt/COLOR_RED/ colors aren't
+exactly the same colors as the ones with the same name on the
+<tt/atari/ target.
+They are the colors which are available as <tt/COLOR_LIGHTGREEN/
+and <tt/COLOR_LIGHTRED/ there.
+
+One can set the color shadow registers directly with other colors.
+Then the color defines from above will just become placeholders. In
+this scenario it might be more convenient to use index values (0..3)
+instead of the color defines. The index values specify which of the
+system shadow color registers (<tt/COLOR0/ .. <tt/COLOR3/) to use.
+
+The default console screen has a layout of 20x24 characters. An
+alternative layout, 20x12, Antic mode 7, BASIC mode 2, is provided in
+the file <tt/atari5200-conioscreen-20x12.o/.
+
+Using <tt/atari5200-conioscreen-20x12.o/ is as simple as placing it on
+the linker command line like this:
+
+<tscreen><verb>
+cl65 -t atari5200 myprog.c lib/atari5200-conioscreen-20x12.o
+</verb></tscreen>
+
+
 <sect1>Disk I/O<p>
 
 Disk I/O is not supported by the <tt/atari5200/ target. This means that
@@ -171,6 +208,9 @@ you cannot use any of the following functions (and a few others):
 
 <sect>Other hints<p>
 
+AtariROMMaker (<url url="https://www.wudsn.com/index.php/productions-atari800/tools/atarirommaker"> ) 
+can be used to create a <tt/.CAR/ file from the binary ROM image cc65 generates.
+This might be more convenient when working with emulators.
 
 
 <sect>License<p>
diff --git a/doc/library.sgml b/doc/library.sgml
index 8800c5496..e8ca84653 100644
--- a/doc/library.sgml
+++ b/doc/library.sgml
@@ -162,6 +162,7 @@ portable. conio implementations exist for the following targets:
   <item>apple2
   <item>apple2enh
   <item>atari
+  <item>atari5200
   <item>atarixl
   <item>atmos
   <item>c16 (works also for the c116 with up to 32K memory)
diff --git a/libsrc/atari5200/extra/conioscreen_20x12.s b/libsrc/atari5200/extra/conioscreen-20x12.s
similarity index 100%
rename from libsrc/atari5200/extra/conioscreen_20x12.s
rename to libsrc/atari5200/extra/conioscreen-20x12.s
-- 
2.39.5