Version 1.0.3

Bumped versions, pushed doc updates.

AppCommon/GlobalAppVersion.cs

@@ -27,7 +27,7 @@ public static class GlobalAppVersion {
         /// Overall application version.
         /// </summary>
         public static readonly CommonUtil.Version AppVersion =
-            new CommonUtil.Version(1, 0, 3, CommonUtil.Version.PreRelType.Dev, 3);
+            new CommonUtil.Version(1, 0, 3, CommonUtil.Version.PreRelType.Final, 0);
         // NOTE: there's an independent version in DiskArc/Defs.cs
     }
 }

DiskArc/Defs.cs

@@ -27,7 +27,7 @@ public static class Defs {
         /// DiskArc library version number.
         /// </summary>
         public static CommonUtil.Version LibVersion { get; } =
-            new CommonUtil.Version(1, 0, 2, CommonUtil.Version.PreRelType.Final, 0);
+            new CommonUtil.Version(1, 0, 3, CommonUtil.Version.PreRelType.Final, 0);
 
         public const string BUILD_TYPE =
 #if DEBUG

Install.md

@@ -17,19 +17,19 @@ or use one of the links below to download the most recent stable release.
 
 System        | Link
 ------------- | ----
-Windows x86   | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_win-x86_sc.zip
-Windows x64   | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_win-x64_sc.zip
-Mac OS x64    | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_osx-x64_sc.zip
-Linux x64     | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_linux-x64_sc.zip
+Windows x86   | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_win-x86_sc.zip
+Windows x64   | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_win-x64_sc.zip
+Mac OS x64    | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_osx-x64_sc.zip
+Linux x64     | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_linux-x64_sc.zip
 
 **Framework-Dependent** (~1 MB)
 
 System        | Link
 ------------- | ----
-Windows x86   | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_win-x86_fd.zip
-Windows x64   | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_win-x64_fd.zip
-Mac OS x64    | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_osx-x64_fd.zip
-Linux x64     | https://github.com/fadden/CiderPress2/releases/download/v1.0.2/cp2_1.0.2_linux-x64_fd.zip
+Windows x86   | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_win-x86_fd.zip
+Windows x64   | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_win-x64_fd.zip
+Mac OS x64    | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_osx-x64_fd.zip
+Linux x64     | https://github.com/fadden/CiderPress2/releases/download/v1.0.3/cp2_1.0.3_linux-x64_fd.zip
 
 Once downloaded, unzip the file somewhere convenient (Safari on the Mac will do the unzip
 for you).  There is no installer; the commands are executed directly from where they are unzipped.

SourceNotes.md

@@ -8,15 +8,18 @@ for a 32-bit or 64-bit environment.
 
 When installing Visual Studio, be sure to include ".NET Desktop Development".
 
-See [MakeDist](MakeDist/README.md) for build and packaging.  You will need a
-full .NET SDK installation to do builds (with `dotnet build`).
+The [MakeDist](MakeDist/README.md) command handles building and packaging for
+releases.  You will need a full .NET SDK installation to do builds (with
+`dotnet build` if you want to use the command line).
 
-The source files that deal with disk and file formats have accompanying
-"-notes" documents that describes the format in some detail, and has
+The source files that implement disk and file formats have accompanying
+"-notes" documents that describe the formats in some detail, and have
 references to primary sources.
 
 ## Projects ##
 
+The "solution" is comprised of several projects.
+
 Libraries:
 
  - CommonUtil: a library of handy functions.  This library does not depend
@@ -33,16 +36,18 @@ Libraries:
 
 Applications:
 
- - cp2: command-line application for Windows, Linux, Mac, et.al.
+ - cp2: command-line application for Windows, Linux, Mac, et.al. (regression
+   tests are built in).
  - cp2_wpf: GUI application for Windows.
 
 Other (not included in binary distribution):
 
  - Examples/*: some simple command-line applications that demonstrate
    the use of the libraries.
  - MakeDist: build utility that creates distribution packages.
- - TestData: a collection of file archives and disk images, used by the
-   DiskArc library tests and the cp2 command-line application tests.
+ - TestData: not actually a project.  This is a collection of file archives
+   and disk images, used by the DiskArc library tests and the cp2
+   command-line application tests.
 
 ## Tests ##
 
@@ -62,18 +67,24 @@ for certain operations.  For example, `cp2 help --debug` also lists the
 commands used to run the tests, and `cp2 version --debug` will display
 additional information about the runtime environment.
 
+In addition, the GUI application has a "bulk compression test" in the DEBUG
+menu that will compress all files in a disk image or file archive with a
+specific compression algorithm, then decompress them and verify that the output
+matches the input.  This can be used for performance and correctness testing
+of compression code.
+
 ## GUI Tool Development ##
 
 During development, the command-line interface was developed first.  The
-graphical interface is currently being prototyped with WPF (Windows
-Presentation Foundation).  This might seem an odd choice, since WPF is several
-years old and Windows-only, and there are multi-platform UI toolkits. The
-motivations are:
+graphical interface is currently implemented with WPF (Windows Presentation
+Foundation).  This might seem an odd choice, since WPF is several years old
+and Windows-only, and there are multi-platform UI toolkits.  The motivations
+for using it are:
 
  1. Some multi-platform UI toolkits don't work on all of my target platforms.
     For example, Microsoft's MAUI doesn't currently work on Linux.
  2. Some UI toolkits emphasize mobile device interaction, making them less
-    suitable for what is intended as a desktop application.
+    suitable for what is primarily a desktop application.
  3. Some UI toolkits are missing important pieces, like robust display of
     formatted text.
  4. I'm familiar with WPF.
@@ -102,14 +113,14 @@ WPF version.  This will ensure that the various APIs work correctly with a GUI
 app, and demonstrate how I think the tool should behave.  Fortunately, the GUI
 application code is a relatively small part of the overall package.
 
-## Source Code Division ##
+## Source Code Proportions ##
 
 As of v1.0, the division of code between components is approximately:
 
  - 4% generic libraries (CommonUtil)
  - 54% app-specific libraries (DiskArc, FileConv, AppCommon)
  - 14% library tests (DiskArcTests and FileConvTests)
- - 13% CLI (includes regression tests)
+ - 13% CLI (about half of which is regression tests)
  - 13% WPF GUI
  - 1% miscellaneous (Examples, MakeDist)
 
@@ -119,7 +130,7 @@ Metrics" feature.)
 ## Publishing a New Release ##
 
 There are several steps involved in publishing a new release.  Start by
-updating versions and running a final set of tests on the app.
+updating version numbers and running a final set of tests on the app.
 
  1. Update the version number in `AppCommon/GlobalAppVersion.cs`.  This
     changes the version number displayed by the applications, and
@@ -137,18 +148,21 @@ updating versions and running a final set of tests on the app.
  5. Run the command-line tests: `cp2 debug-test`, `cp2 debug-test-da`,
     and `cp2 debug-test-fc`.  These require files in the TestData directory.
     All tests must pass.  If you're not built for Debug mode, you will see
-    a warning at the end of the test runs.
+    a warning at the end of the test runs.  Ideally these would be run on
+    all supported platforms (Win10+, macOS 11+, Linux).
 
-If this is a "final" release, you will need to publish updated documentation
-as well.  Don't do this for pre-releases; the web documentation should
-always match the latest final release.
+If this is a "final" release, you will need to publish updated documentation,
+from the "ndocs" directory to the live github website "docs" directory.  You
+should not do this for pre-releases, because the web site contents should
+always match the current "final" release.
 
  6. Update the `app_version` number in `ndocs/publish.py`.  This is used
     for text substitution in the descriptive text and installer links.
  7. From the command line, in the `ndocs` directory, run `publish.py`
-    (you may need to explicitly run python).  This will update the contents
-    of the `docs` directory and the top-level documentation (including
-    this file) with the contents of `ndocs`.  Check the diffs.
+    (you may need to explicitly run python if the shell isn't set up to
+    execute scripts directly).  This will update the contents of the `docs`
+    directory and the top-level documentation (including this file) with the
+    contents of `ndocs`.  Check the diffs.
 
 Finally, build the applications and submit the changes.
 

docs/Manual-cp2.md

@@ -475,7 +475,7 @@ archive specifiers does not match, the copy process is cancelled.
 
 The destination may not be a single-file archive like AppleSingle or gzip.
 
-The `--raw-mode` option is not used here.  Files copied from DOS volumes
+The `--raw` option is not handled here.  Files copied from DOS volumes
 are always treated as "cooked" unless they are being copied to another
 DOS volume, in which case the files are transferred "raw", with the sparse
 structure preserved.
@@ -1096,9 +1096,9 @@ the word "locked", or the word "unlocked".
 timestamps, respectively.  Date/time strings will be parsed according
 to local conventions.  It's best to use an unambiguous format like
 [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt)
-(e.g. "yyyy-MM-ddTHH:mm:ssZ"), though other common formats like "dd-MMM-yyyy
-HH:mm:ss" will also work.  Bear in mind that most formats store timestamps
-in local time, without time zone information.
+(e.g. `yyyy-MM-ddTHH:mm:ssZ`), though other common formats like
+`dd-MMM-yyyy HH:mm:ss` will also work.  Bear in mind that most disk and file
+archive formats store timestamps as local time, without time zone information.
 
 Not all filesystems and archive formats support all attributes, or all
 possible values for a given attribute.  Attempting to set an unsupported
@@ -1482,7 +1482,7 @@ of the extensions are allowed to mean more than one thing.
  - ".woz" - WOZ format nibble image, for 5.25" (35- or 40-track)
    or 3.5" (SSDD or DSDD) disks
  - ".2mg", ".2img" - DOS-order 16-sector disks, or ProDOS-order blocks
- - ".dc", ".image" - DiskCopy 4.2 3.5" floppy (400KB, 720KB, 800KB, or 1440KB)
+ - ".dc", ".dc42", ".image" - DiskCopy 4.2 3.5" floppy (400KB, 720KB, 800KB, or 1440KB)
  - ".app" - Trackstar 5.25" (35- or 40-track) disk nibble image
  - ".sdk" - NuFX (ShrinkIt) disk archive
  - ".zip" - ZIP file archive
@@ -1710,6 +1710,13 @@ When files are added without file type information, default types are
 provided.  For ProDOS this is NON/$0000, for HFS 'BINA'/'CPII' is used
 (generic binary).
 
+The add, extract, import, and export operations attempt to preserve the file
+timestamps, even when the preservation mode is set to "none".  Some timestamps
+cannot be stored or can only be partially represented, e.g. the ProDOS file
+creation time has no equivalent on Linux systems, and ProDOS timestamps have
+1-minute granularity.  Many systems are unable to store dates with years that
+will be reached soon, e.g. HFS can't represent dates after February 2040.
+
 #### None (default) ####
 
 Resource forks, file types, and access flags are discarded.  File dates will
@@ -1977,6 +1984,7 @@ Some ideas for the future:
  - Support editing of ZIP/NuFX file comments in set-attr.
  - Add `get-attr` to get file attributes in machine-readable form.
  - Add a better way to set access flags in `set-attr`, e.g. by letter.
+ - Add a way to set attributes for multiple files, e.g. mark as read-only.
  - Add `show-vol-bitmap` to display free/in-use blocks.
  - Allow `test` to descend into the archive (use `--depth` option).
  - Add command to zero out unused blocks on disk images, and perhaps the
@@ -1987,3 +1995,4 @@ Additional short options to consider:
  - `-v` for `--verbose`?  (Not needed, verbose is default)
  - `-r` for `--recurse`?  (Not needed, recurse is default)
  - `-w` for `--wide`?  (Rarely used)
+ - `-0` for `--no-compress`?

docs/README.md

@@ -28,7 +28,7 @@ handful of top-level documents (like the project README and installation
 instructions) are copied out of the `top` directory.
 
 Some text variable substitutions can be performed on HTML and Markdown files
-as they are copied, e.g. all occurrences of `1.0.2` will be replaced with
+as they are copied, e.g. all occurrences of `1.0.3` will be replaced with
 the current app version.  This is used to update the links in the download
 instructions (`Install.md`) to point at the current release.
 

docs/cli-tutorial/import.html

@@ -110,8 +110,9 @@ <h2>Importing Files</h2>
 (like an invalid line number) or it's simply the wrong type of file (like a PNG),
 the command will halt with an error message.</p>
 
-<p>The only import converters currently defined are <kbd>text</kbd>, for text
-files, and <kbd>bas</kbd>, for Applesoft BASIC.</p>
+<p>The import converters currently available are <kbd>text</kbd> for text
+files, <kbd>bas</kbd> for Applesoft BASIC, and <kbd>merlin</kbd> for
+Merlin assembly source files.</p>
 <p>The text converter will change the text to use the proper end-of-line character,
 usually carriage return ($0D).  The character set for the input can be
 specified as UTF-8, ISO 8859-1, or CP1252, while the output can be encoded as

docs/doc-index.html

@@ -158,12 +158,10 @@ <h3>Multi-Part Disk Formats</h3>
 
 <h3>Filesystems</h3>
 <ul>
-  <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/Hybrid-notes.md">
-      Hybrid (DOS + ProDOS / Pascal / CP/M) disks, and embedded volumes</a></li>
-  <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/CPM-notes.md">
-      CP/M for Apple II 5.25" and 3.5" disks</a></li>
   <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/DOS-notes.md">
       Apple DOS (Disk Operating System) 3.2 / 3.3</a></li>
+  <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/CPM-notes.md">
+      CP/M for Apple II 5.25" and 3.5" disks</a></li>
   <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/Gutenberg-notes.md">
       Gutenberg word processor filesystem</a></li>
   <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/HFS-notes.md">
@@ -177,6 +175,10 @@ <h3>Filesystems</h3>
   <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/RDOS-notes.md">
       SSI RDOS</a></li>
 </ul>
+<ul>
+  <li><a href="https://github.com/fadden/CiderPress2/blob/main/DiskArc/FS/Hybrid-notes.md">
+      Hybrid (DOS + ProDOS / Pascal / CP/M) disks, and embedded volumes</a></li>
+</ul>
 
 <h3>Vintage File Formats</h3>
 <ul>

docs/gui-manual/creating.html

@@ -107,14 +107,15 @@ <h2>Creating Disk Images</h2>
 
 <p>Briefly:</p>
 <ul>
+  <li>Simple block image (.iso/.hdv): this stores a disk as a series of 512-byte blocks.
+    This is the most common format for 3.5" disks, hard drives, and other
+    block-oriented media.</li>
+  <li>Unadorned ProDOS-order (.po): same as .iso/.hdv.  The ".po" extension is
+    recognized by many Apple II emulators, so this is here for convenience.
   <li>Unadorned DOS-order (.do/.d13): this stores an Apple II 5.25" floppy disk as a
     series of 256-byte sectors.  This is probably the most common format used for 5.25"
     disks, often used with the ambiguous ".dsk" extension.  ".do" is used for 16-sector
     disks, ".d13" for 13-sector disks.</li>
-  <li>Unadorned ProDOS-order (.po): this stores a disk as a series of 512-byte blocks.
-    The popular ".hdv" and ".iso" extensions are identical, and sometimes ".dsk" is
-    used for this as well.  This is the most common
-    format for 3.5" disks, hard drives, and other block-oriented media.</li>
   <li>2IMG (.2mg): this can store data the same way a .do, .po, or .nib image would, but
     it also adds a file header that allows the receiving application to recognize
     the contents unambiguously.  This format is widely supported by Apple II emulators.

docs/gui-manual/diskops.html

@@ -76,11 +76,19 @@
 
 <div id="main">
 
+<h2>Disk Operations</h2>
+
+<p>The disk operations are available when a disk image or partition is selected
+in the archive tree.  They will not be visible when a filesystem or file
+archive is active.</p>
+<p>Block/sector editing is covered in the next section.</p>
+
+
 <h2>Save As Disk Image</h2>
 
-<p>This option is available for disk images and partitions (not filesystems).  It allows
-you to save the contents to a new disk image.  The new disk does not have to use the
-same format, so this is a quick way to convert a disk image from one format to another.</p>
+<p>This features allows you to save the contents of a disk image or disk
+partition to a new disk image.  The new disk does not have to use the same file
+format, so this is a quick way to convert a disk image from one format to another.</p>
 <p>Select the disk image or partition in the archive tree, then either click the
 <samp>Save As Disk Image</samp> button in the center panel, or use the corresponding
 item in the <samp>Actions</samp> menu.  This opens a window that lets you pick a
@@ -127,8 +135,9 @@ <h2>Scan For Bad Blocks</h2>
 
 <h2>Defragment Filesystem</h2>
 
-<p>This option is only available for filesystems that have serious problems with fragmentation
-(this is technically a filesystem utility, not a disk utility).  This is currently
+<p>This option is only available for filesystems that have serious problems with fragmentation.
+(This is technically a filesystem utility, not a disk utility, but it requires
+that all file access be disabled while running.)  This is currently
 implemented only for Apple Pascal.</p>
 <p>Select the filesystem, then select <samp>Actions &gt; Defragment Filesystem</samp> from
 the menu.  The operation runs immediately.</p>

docs/gui-manual/editsector.html

@@ -125,8 +125,8 @@ <h3>Navigation</h3>
 <p>To edit sector data, click in the hex data area on the byte you wish to change, and
 enter two hex digits (0-9, a-f).  Editing the text area directly is not currently supported.</p>
 
-<p>For 16-sector disks, the sector skew can be changed with the <samp>Sector Order</samp>
-pop-up menu.</p>
+<p>For 16-sector 5.25" disk images, the sector skew can be changed with the
+<samp>Sector Order</samp> pop-up menu.</p>
 <p>For nibble images, the sector format is displayed.</p>
 <p>The character conversion mode used for the text portion of the hex dump can be
 altered with the <samp>Text Conversion</samp> buttons.</p>

docs/index.html

@@ -105,7 +105,7 @@ <h4>Key features:</h4>
 
 <p>
 <a href="https://github.com/fadden/CiderPress2/releases/latest">
-<b>Download</b> the latest release (1.0.2)</a> from github.</p>
+<b>Download</b> the latest release (1.0.3)</a> from github.</p>
 
 <h4>Free Software</h4>
 <p>The full source code for CiderPress II is available on

ndocs/publish.py

@@ -15,7 +15,7 @@
 
 
 # Current version string.  Used for text substitution.
-app_version = "1.0.2"
+app_version = "1.0.3"
 pkg_version = app_version
 
 # ----- nothing configurable below -----