<?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-wtf8">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>petscii-to-wtf8</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-wtf8</refname>
<refpurpose>convert Commodore PETSCII to WTF-8</refpurpose>
</refnamediv>

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

<refsection><title>Description</title>

<para>
<command>petscii-to-wtf8</command> converts Commodore PETSCII, the whole repertoire, into WTF-8, transcoding from PETSCII code points to Unicode ones.
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>
<note>
No <citerefentry><refentrytitle>iconv</refentrytitle><manvolnum>1</manvolnum></citerefentry> implementations even sort&#x2010;of provide a transcoding from PETSCII.
</note>

<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>
<command>petscii-to-wtf8</command> simply passes through most C0 and C1 control characters apart from the few that have ECMA-35 single&#x2010;octet equivalents.
</para>

<caution>
This changes the semantics of PETSCII and will not work with almost all Unix terminals without some form of post&#x2010;processing.
The UTF-8 (WTF-8) C0 and C1 controls have different meanings to the PETSCII C0 and C1 controls.
</caution>

<tip>
To preserve the Commodore BASIC <code>PRINT</code> semantics, at the expense of introducing extra control sequences and not having a one&#x2010;to&#x2010;one character correspondence, convert program code with <citerefentry><refentrytitle>petscii-to-ecma48</refentrytitle><manvolnum>1</manvolnum></citerefentry> <arg choice='plain'>--basic</arg> instead.
</tip>

</refsection>

<refsection><title>History</title>

<para>
<command>petscii-to-wtf8</command> was written in 2026, inspired by the author wanting to view and load the code of an old Commodore PET hangman game in UTF-8 tools (where most of PETSCII gets treated as continual coding errors).
</para>

</refsection>

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

</refentry>
