diff --git a/library/nufx-addendum.htm b/library/nufx-addendum.htm index 162ab17..6458c41 100644 --- a/library/nufx-addendum.htm +++ b/library/nufx-addendum.htm @@ -24,9 +24,10 @@ -
NuFX Addendum - By Andy McFadden - Last revised 2022/05/28
-

This addendum clarifies and extends certain aspects of the NuFX -specification.  This is not an "official" modification +

NuFX Addendum - By Andy McFadden - Last revised 2022/10/07
+

This addendum clarifies and extends certain aspects of the + NuFX specification. This is not an +"official" modification of the original document - it has not been reviewed and approved by the original author - but anyone developing NuFX utilities would do well to follow these recommendations.

@@ -48,11 +49,10 @@ are strongly encouraged to follow.

Clarifications

Pronunciation

-

What's the correct way to pronounce "NuFX"?  The -specification doesn't say.  There are two basic camps, letter-by-letter -("en you eff ecks") and minimal-syllable ("new fix" or -"new fuchs").  I don't recall how Andy Nicholas says it, so let -it be "new fix".

+

What's the correct way to pronounce "NuFX"? One +approach is letter-by-letter ("en you eff ecks"), another is minimal-syllable +("new fix"). According to the file type note, it's a bit of both ("new eff ecks").

+

 

Use of ".SDK" suffix

Originally, only ".SHK" was used to represent a NuFX @@ -60,21 +60,25 @@ archive.  Over time, a convention of using ".SDK" to represent archives with a single disk image in them has arisen.  This is very convenient for emulators on systems that rely on the file extension (e.g. Windows), so use of ".SDK" is encouraged.

+

 

Archives with no records

An archive without records, i.e. nothing but a master header -block, serves no purpose.

-

Creating: Archives without any records in them must never -be created.  All archives must have at least one record.

+block, serves no purpose. However, it can be useful to have a "create new +archive" operation that creates an empty file to be populated later.

+

Creating: Archives without any records in them may be +created.

Opening: If asked to open a record-less archive, the application should recognize that the archive is empty and proceed as if it were a new archive.

Modifying: If all records in an archive are deleted, the -archive file must be deleted as well.

+archive file should be deleted as well.

 

Records with no threads

-

A record without threads is pretty pointless.

+

A record without threads is pretty pointless. The initial +release of the NuFX spec mandated that there be at least one thread attached +to each record, but this language was removed from later versions.

Creating: Records without threads must never be created.  All records must have at least one thread.

Extracting: Empty records should be ignored.

@@ -128,23 +132,27 @@ where the filename may live, and no guarantee that only one will be used..

Extracting: -The thread filename takes precedence over the record header filename.

+The thread filename takes precedence over the record header filename. + +

 

Filename character set

Filenames in NuFX archives use the Mac OS Roman character set, which is ASCII plus some symbols and the usual set of latin language characters (see Unicode definition).  The NuFX filename definition was intended to accommodate files from HFS volumes, which may contain any character except ':'.  -Control characters, including NUL ('\0'), were allowed but discouraged.

+Control characters, including NUL ('\0'), were allowed but discouraged. +

On modern systems, converting between Mac OS Roman and Unicode is useful and (mostly) straightforward.  Dealing with embedded null bytes is very -annoying in C-like languages though.

Creating: +annoying in C-like languages though. +

Creating: Convert Unicode to Mac OS Roman, replacing any untranslatable characters with -'?'.  Embedded nulls must be replaced with '?'.

+'?'.  Embedded nulls may be replaced with '?'.

Extracting: Convert Mac OS Roman to Unicode.  If embedded nulls -are encountered, they should be replaced with something appropriate for the -current system.  Applications are allowed to ignore the problem and -truncate the filename, but must be prepared to handle duplicate or empty +are encountered, they may be replaced with something appropriate for the +current system.  Applications should not ignore the problem and +truncate the filename; if they do, they must be prepared to handle duplicate or empty filenames.

 

@@ -171,8 +179,7 @@ be simple filenames.

have subdirectories and which don't, which would allow it to disregard the fssep char when it can't be relevant for a record, but it's easier to let the fssep char's usefulness be self-evident.

-

(NOTE: -as of v2.0.3, NufxLib rejects 0x00 as an fssep character.  This is a bug.)

+

(NOTE: NufxLib v2.0.3 rejected 0x00 as an fssep character. This was a bug.)

Creating: When adding files directly from filesystems without subdirectories, use 0x00 as the fssep char.

@@ -210,6 +217,9 @@ not meant to be significant when determining whether two records have the same filename.  This becomes important when adding files (to test for duplicates), extracting files by name, and when attempting to display archive contents as a hierarchical tree.

+

HFS files will use the Mac OS Roman character set, so a simple ASCII +case conversion will be inadequate. An HFS filename comparison routine must +be used.

Applications should try to recognize that "foo/bar", "foo/BAR", and "FOO/bar" are the same file, but it's probably not worth @@ -229,7 +239,8 @@ separator.  Two names should be considered identical if each distinct path component matches, so "foo/bar" and "foo:bar" are identical if the separators are '/' and ':', respectively.  Comparisons should be case-insensitive.

Adding/renaming: Applications -should prevent multiple records from having the same filename. +should prevent multiple records from having the same case-insensitive filename. +

 

Pre-sized or not pre-sized

The specification declares that filename threads and comments @@ -465,31 +476,30 @@ presumably have nonzero data in more places.

Sometimes the option list is a little messed up, e.g. the size field says 36 bytes, but there's only space for 18 bytes in the record header.

-

Unfortunately, when archiving files from an HFS volume under GS/OS, -GSHK records the ProDOS type/auxtype rather than the full HFS file type -and creator (likely because that's what GS/OS provides). The only way to +

When archiving files from an HFS volume under GS/OS, GSHK records the +ProDOS type/auxtype rather than the full HFS file type and creator, +because that's what GS/OS provides. The only way to recover the original Mac Finder types is through the option list.

Side note: the NuFX specification reversed the values of MFS and HFS in the file_sys_id enumeration. In practice, GS/ShrinkIt correctly uses the GS/OS FST definitions: MFS=5, HFS=6.

Opening: Assume the option_size field is correct unless it exceeds attrib_count-2. If it's too large, clip it down to size. -If the filesystem type is ProDOS or HFS, and the second 4 bytes look like -ASCII, use the first 4 bytes of the option list data as the file type and -the second 4 bytes as the creator.

-

Creating: For broadest compatibility it would be best to store -a ProDOS type/auxtype in the record header, and generate a filesystem-specific -option list with the HFS Finder types (i.e. 32 bytes for ProDOS or 36 -bytes for HFS). For an HFS record, simply using the four-byte HFS types -is allowed.

+If the filesystem type is ProDOS or HFS, and the second 4 bytes are nonzero, +use the first 4 bytes of the option list data as the file type and +the second 4 bytes as the creator. If a secondary test is desired to +avoid garbage, the creator value is usually ASCII.

+

Creating: The specification says that applications should store +whatever the OS gives them, which means putting a ProDOS type/auxtype in the +record header, and generating a filesystem-specific option list with the +HFS Finder types (i.e. 32 bytes for ProDOS or 36 bytes for HFS). Simply +storing the four-byte HFS types in the record header is not allowed.

Updating: Always output the actual record size. Do not propagate incorrect size values. Retaining option lists for ProDOS and HFS entries is required, since they may have the only copy of the original file type and creator. Updates to the archive attributes that alter the file/aux type should usually retain the option list, since the purpose may be to -improve ProDOS usability without losing the original type information. -However, applications are allowed to delete the option list in this case, -especially if it is storing the full HFS types in the record.

+improve ProDOS usability without losing the original type information.

 

Master EOF