diff --git a/AppCommon/GlobalAppVersion.cs b/AppCommon/GlobalAppVersion.cs index b44c065..7dc9105 100644 --- a/AppCommon/GlobalAppVersion.cs +++ b/AppCommon/GlobalAppVersion.cs @@ -27,7 +27,7 @@ public static class GlobalAppVersion { /// Overall application version. /// 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 } } diff --git a/DiskArc/Defs.cs b/DiskArc/Defs.cs index 9c3c2e3..94bc4b4 100644 --- a/DiskArc/Defs.cs +++ b/DiskArc/Defs.cs @@ -27,7 +27,7 @@ public static class Defs { /// DiskArc library version number. /// 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 diff --git a/Install.md b/Install.md index 4ec2b5c..5569be7 100644 --- a/Install.md +++ b/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. diff --git a/SourceNotes.md b/SourceNotes.md index 7464237..cf06918 100644 --- a/SourceNotes.md +++ b/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,7 +36,8 @@ 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): @@ -41,8 +45,9 @@ 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. diff --git a/docs/Manual-cp2.md b/docs/Manual-cp2.md index 1e22e5b..4f3292c 100644 --- a/docs/Manual-cp2.md +++ b/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`? diff --git a/docs/README.md b/docs/README.md index 35629c3..88148c7 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/cli-tutorial/import.html b/docs/cli-tutorial/import.html index 59b7848..c83783d 100644 --- a/docs/cli-tutorial/import.html +++ b/docs/cli-tutorial/import.html @@ -110,8 +110,9 @@

Importing Files

(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.

-

The only import converters currently defined are text, for text -files, and bas, for Applesoft BASIC.

+

The import converters currently available are text for text +files, bas for Applesoft BASIC, and merlin for +Merlin assembly source files.

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 diff --git a/docs/doc-index.html b/docs/doc-index.html index 27e1c54..61cab7e 100644 --- a/docs/doc-index.html +++ b/docs/doc-index.html @@ -158,12 +158,10 @@

Multi-Part Disk Formats

Filesystems

+

Vintage File Formats