Documentation.

.readthedocs.yaml

@@ -4,11 +4,14 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.9"
-  apt_packages:
-    - libisal-dev
   jobs:
     pre_build:
+      - doxygen docs/Doxyfile
       - make -C build/linux doc
 
+python:
+   install:
+   - requirements: docs/requirements.txt
+
 sphinx:
   configuration: docs/conf.py

build/linux/Makefile

@@ -15,7 +15,7 @@ $(EXEC): $(MAIN) $(OBJS)
 %.o: $(PTH)/%.c $(PTH)/%.h
 	$(CC) $(CFLAGS) -c $<
 
-../../docs/cli.rst: ../../docs/cli_template.rst $(EXEC)
+../../docs/cli.rst: ../../docs/cli_template.rst_ $(EXEC)
 	cp $< $@ && ./$(EXEC) -h >> $@
 
 clean:

docs/Doxyfile

@@ -0,0 +1,10 @@
+INPUT                  = src/
+OUTPUT_DIRECTORY       = docs/
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+
+INLINE_SIMPLE_STRUCTS  = YES
+
+FILE_PATTERNS          = *.c *.h

docs/api.rst

@@ -0,0 +1,12 @@
+API documentation
+=================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+   :glob:
+
+   api/wav
+   api/mzf
+   api/write
+   api/methods

docs/api/methods.rst

@@ -0,0 +1,8 @@
+Tape write methods
+==================
+
+.. code-block:: cpp
+
+    #include "methods.h"
+
+.. doxygenfile:: methods.h

docs/api/mzf.rst

@@ -0,0 +1,8 @@
+MZF files
+=========
+
+.. code-block:: cpp
+
+    #include "mzf.h"
+
+.. doxygenfile:: mzf.h

docs/api/wav.rst

@@ -0,0 +1,8 @@
+WAV files
+=========
+
+.. code-block:: cpp
+
+    #include "wav.h"
+
+.. doxygenfile:: wav.h

docs/api/write.rst

@@ -0,0 +1,8 @@
+Tape write functions
+====================
+
+.. code-block:: cpp
+
+    #include "write.h"
+
+.. doxygenfile:: write.h

docs/conf.py

@@ -0,0 +1,12 @@
+project = 'mzf2wav'
+author = 'Jeroen F.J. Laros'
+copyright = '2003-2023, {}'.format(author)
+
+extensions = ['breathe']
+breathe_projects = {'doxygen': 'xml'}
+breathe_default_project = 'doxygen'
+breathe_default_members = ('members',)
+
+master_doc = 'index'
+
+highlight_language = 'none'

docs/index.rst

@@ -8,4 +8,5 @@
    install
    cli
    usage
+   api
    credits

docs/requirements.txt

@@ -0,0 +1,2 @@
+breathe>=4.3.1
+docutils>=0.17.1

docs/usage.rst

@@ -9,70 +9,82 @@ named ``image.wav``:
     mzf2wav image.mzf image.wav
 
 
-Operation modes
----------------
+Modes of operation
+------------------
 
-Conventional sending mode
-~~~~~~~~~~~~~~~~~~~~~~~~~
+MZF2WAV supports different writing techniques that can shorten the loading
+time considerably. Please see the tape_ data processing page for more
+background information.
 
-This is the safest (and slowest) way to transfer an image, everything is done
-according to the Sharp MZ series conventions: A long gap is 22000 pulses, a
-short gap is 11000 pulses. The header and body are transferred twice to allow
-for errors.
-
-Fast sending mode
+Conventional mode
 ~~~~~~~~~~~~~~~~~
 
-This is the easiest way to transfer a file. In this mode the long gap (a tape
-marker) is 4000 pulses and the short gap is 5000 pulses. Both the header and
-the MZF image body are transferred once.
+In this mode, everything is done according to the Sharp MZ series
+conventions. A long gap is 22000 pulses, a short gap is 11000 pulses. The
+header and body are written twice to allow for errors. This mode can be
+selected using the ``-c`` command line option.
+
+Fast mode
+~~~~~~~~~
 
-Turbo sending mode
-~~~~~~~~~~~~~~~~~~
+In this mode, the long gap is 4000 pulses and the short gap is 5000 pulses.
+Both the header and the MZF image body are written once. This is the default
+mode.
 
-In this mode, the turbo loader is transferred using fast sending mode, this
-turbo loader enables the MZ to operate at higher transfer speeds. The MZF
-image is then sent using fast sending mode, but now at a higher speed.
+Turbo mode
+~~~~~~~~~~
 
-The speed at which the turbo loader is transferred is controlled with the
-``-i`` option, the speed at which the MZF image is sent is controlled with the
-``-t`` option.
+In this mode, a turbo loader is written using fast sending mode, which
+enables the MZ to operate at higher speeds. The MZF image is then sent using
+fast sending mode, but now at a higher speed. This mode can be selected using
+the ``-t`` command line option.
 
 
 Speeds
 ------
 
 Apart from increasing the pulse frequency, the waveforms themselves can be
-altered in order to increase speed. The "fast waveform" was found by minimising
-the high and the low states of the pulses independently.
+altered in order to increase speed.
+
+For conventional and fast mode, two predefined waveform configurations are
+available that can be selected using the ``-n`` command line option.
+
+For turbo mode, three predefined waveform configurations are available that
+can be selected using the ``-s`` command line option. This option can be
+combined with the ``-n`` option to also write the turbo loader at a higher
+speed. For example:
+
+::
 
-At this time, five speeds are implemented:
+    mzf2wav -t -n 1 -s 2 image.mzf image.wav
 
-- Speed 0: normal speed with normal waveforms.
-- Speed 1: normal speed with fast waveforms.
-- Speed 2: 2x speed with normal waveforms.
-- Speed 3: 3x speed with normal waveforms.
-- Speed 4: 3x speed with fast waveforms.
 
-These speeds can be set for all operation modes, although some combinations may
-not work. The most commonly used speeds are: speed 0 or 1 for initial speed
-mode and speed 2 or higher for turbo speed mode.
+Pulse customisation
+~~~~~~~~~~~~~~~~~~~
 
-If multiple images are transferred, using speed 3 or 4 with fast sending mode
-may be preferred.
+Next to the predefined waveform configurations, it is possible to make custom
+waveform configurations using the ``-N`` (conventional and fast mode) and
+``-S`` (turbo mode) options. For example:
 
-Corrections
-~~~~~~~~~~~
+::
+
+    mzf2wav -t -N 480,494,260,264 -S 248,248,113,140 image.mzf image.wav
 
-Because the waveforms used by speeds 1 and 4 may not always work, two
-correction factors for these speeds are implemented, controlled with the ``-1``
-and ``-2`` options.
+The pulse configuration consists of four comma separated values giving the
+length of the long pulse up, long pulse down, short pulse up and short pulse
+down times in microseconds.
 
 
 Polarity
 --------
 
-The polarity can be revered with the ``-p`` option.
+The polarity can be inverted using the ``-p`` option.
+
+
+Bit rate
+--------
+
+The bit rate is set using the ``-b`` option.
 
 
 Related software
@@ -83,6 +95,6 @@ Please check out MZF2WAVGUI_, a graphical user interface for this project
 directly connect to an MZ.
 
 
-.. _operation modes: https://github.com/jfjlaros/mzput#operation-modes
 .. _MZF2WAVGUI: https://github.com/rickyelqasem/MZF2WAVGUI
 .. _tutorial: https://www.youtube.com/watch?v=iwD3-5ENyE8
+.. _tape: https://web.archive.org/web/20201127232159/https://original.sharpmz.org/mz-700/tapeproc.htm

src/argparse.c

@@ -15,30 +15,6 @@ uint16_t const turboDefaults_[][4] = {
 Options const default_ = {
   NULL, NULL, fast, false, 44100, {0}, {0}, false, false, false};
 
-char const usage[] =
-  "usage: %s [-c] [-t] [-p] [-b BITRATE] [-n SPEED] [-s SPEED] "
-  "[-N FMT] [-S FMT] MZF WAV\n\n"
-  "positional arguments:\n"
-  "  MZF          input file in MZF format\n"
-  "  WAV          input file in WAV format\n\n"
-  "options:\n"
-  "  -h           display help information and exit\n"
-  "  -v           display version information and exit\n"
-  "  -c           conventional mode\n"
-  "  -t           turbo mode\n"
-  "  -p           invert polarity\n"
-  "  -b BITRATE   bit rate (dafault: 44100)\n"
-  "  -n SPEED     normal mode speed 0 or 1 (default: 0)\n"
-  "  -s SPEED     turbo mode speed 0, 1 or 2 (default: 0)\n"
-  "  -N FMT       custom waveform for normal mode\n"
-  "  -S FMT       custom waveform for turbo mode\n\n"
-  "FMT: long_up,long_down,short_up,short_down\n";
-
-char const version[] =
-  "MZF2WAV version 2.0.0\n"
-  "Copyright (c) 2003-2023 Jeroen F.J. Laros <jlaros@fixedpoint.nl>\n"
-  "Homepage: https://mzf2wav.readthedocs.io\n";
-
 
 size_t parseInt_(char const *const text, size_t const range) {
   size_t idx = strtoul(text, NULL, 10);

src/argparse.h

@@ -17,9 +17,6 @@ typedef struct {
   bool version;        //!< Version.
 } Options;
 
-extern char const usage[];    // Usage string.
-extern char const version[];  // Version string.
-
 
 /*! Parse command line arguments.
  *

src/mzf2wav.c

@@ -3,6 +3,30 @@
 
 #include "argparse.h"
 
+char const usage_[] =
+  "usage: %s [-c] [-t] [-p] [-b BITRATE] [-n SPEED] [-s SPEED] "
+  "[-N FMT] [-S FMT] MZF WAV\n\n"
+  "positional arguments:\n"
+  "  MZF          input file in MZF format\n"
+  "  WAV          input file in WAV format\n\n"
+  "options:\n"
+  "  -h           display help information and exit\n"
+  "  -v           display version information and exit\n"
+  "  -c           conventional mode\n"
+  "  -t           turbo mode\n"
+  "  -p           invert polarity\n"
+  "  -b BITRATE   bit rate (dafault: 44100)\n"
+  "  -n SPEED     normal mode speed 0 or 1 (default: 0)\n"
+  "  -s SPEED     turbo mode speed 0, 1 or 2 (default: 0)\n"
+  "  -N FMT       custom waveform for normal mode\n"
+  "  -S FMT       custom waveform for turbo mode\n\n"
+  "FMT: long_up,long_down,short_up,short_down\n";
+
+char const version_[] =
+  "MZF2WAV version 2.0.0\n"
+  "Copyright (c) 2003-2023 Jeroen F.J. Laros <jlaros@fixedpoint.nl>\n"
+  "Homepage: https://mzf2wav.readthedocs.io\n";
+
 
 unsigned int fileSize_(FILE *handle) {
   fseek(handle, 0, SEEK_END);
@@ -79,14 +103,16 @@ bool mzf2wav(Options const *const options) {
 
 int main(int const argc, char *const *const argv) {
   Options options = argParse(argc, argv);
-  if (options.version) {
-    printf(version);
+  if (options.help) {
+    printf(usage_, argv[0]);
     return 0;
   }
-  if (options.help || options.error) {
-    printf(usage, argv[0]);
+  if (options.version) {
+    printf(version_);
+    return 0;
   }
   if (options.error || !mzf2wav(&options)) {
+    printf(usage_, argv[0]);
     return 1;
   }
 }

src/wav.c

@@ -24,8 +24,8 @@ void writeInt_(FILE *const output, uint32_t const data) {
 
 
 void writeBit(FILE *const output, bool const bit, bool const invert) {
-  uint8_t const zero = 0x30;  // TODO: 0x00?
-  uint8_t const one = 0xd0;   // TODO: 0xff?
+  uint8_t const zero = 0x00;
+  uint8_t const one = 0xff;
 
   if (bit != invert) {
     fprintf(output, "%c", one);