<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.... vim: indentexpr=:
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="petscii-to-ecma48">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>petscii-to-ecma48</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">BASIC</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>petscii-to-ecma48</refname>
<refpurpose>convert Commodore PETSCII to ECMA-48</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>petscii-to-ecma48</command>
<arg choice='opt'>--basic</arg>
<arg choice='opt'>--7-bit</arg>
<arg choice='opt' repeat='rep'><replaceable>filename(s)</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>
<command>petscii-to-ecma48</command> converts Commodore PETSCII into WTF-8, transcoding from PETSCII to Unicode, except for control characters, which are converted into the ECMA-48 UTF-8 equivalent control sequences where possible.
It is a filter program, in the same vein as <citerefentry><refentrytitle>linenumber</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>vis</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>

<para>
If invoked with one or more <filename><replaceable>filenames</replaceable></filename>, it will read those files and output their converted contents.
Otherwise it will act as a filter and convert its standard input.
The input is always taken as the PETSCII single&#x2010;byte character set.
All output is always written to standard output, with any error messsages written to standard error, in WTF-8.
</para>

<para>
Successive cursor motions of the same kind are batched up into a single ECMA-48 control sequence.
</para>

<note>
The ECMA-48 relative cursor motion control sequences that are output are non&#x2010;scrolling ones that stop at the screen margins.
</note>

<para>
By default, <command>petscii-to-ecma48</command> expects to be processing screen output, and will reset colours and reverse video whenever a PETSCII newline is encountered.
It is suitable to receive over a pipe the (converted to SBCS) standard outputs from <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry> when running a Commodore BASIC program whose output strings have not been converted.
</para>

<note>
<command>petscii-to-ecma48</command> cannot directly convert the output of an unconverted PETSCII Commodore BASIC program.
<citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry> do not know that the program is PETSCII and write PETSCII control codes and graphics as WTF-8 encoded output with no transcoding.
The WTF-8 encoded PETSCII written by such a program must first be decoded back to the proper PETSCII single&#x2010;byte character set with <citerefentry><refentrytitle>iconv</refentrytitle><manvolnum>1</manvolnum></citerefentry> <arg choice='plain'>--to-code-Latin1</arg> instead.
</note>

<para>
The <arg choice='plain'>--basic</arg> command&#x2010;line option is for processing (detokenized) BASIC programs (the output of <citerefentry><refentrytitle>commodore-basic-detokenize</refentrytitle><manvolnum>1</manvolnum></citerefentry> or similar) and will attempt to reset colours and reverse video at the ends of string literals.
Because it does not process the <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry> grammar, it does not necessarily produce program code that works as intended.
It does not know about <code>PRINT</code> statements, let alone has a way of knowing what they would do at runtime.
</para>
<caution>
Usually a converted BASIC program that does screen output will require some tweaking of the ECMA-48 control sequences embedded into it.
</caution>

<para>
The <arg choice='plain'>--7-bit</arg> command&#x2010;line option causes <command>petscii-to-ecma48</command> to emit 7&#x2010;bit ECMA-35 control codes instead of 8&#x2010;bit ones.
Usually whether to do this is determined from the terminal type.
</para>

</refsection>

<refsection><title>History</title>

<para>
<command>petscii-to-ecma48</command> was written in 2026, inspired by the author wanting to see the output of an old Commodore PET hangman game.
</para>

</refsection>

<refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
