Document file=NAME syntax.

4 files changed, 38 insertions, 4 deletions

diff --git a/src/alf.1 b/src/alf.1
index ae374fb..0f519b8 100644
--- a/src/alf.1
+++ b/src/alf.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "ALF" 1 "2025-12-04" "0.4.0" "Urchlay's Atari 8-bit Tools"
+.TH "ALF" 1 "2025-12-06" "0.4.0" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 alf \- create Atari 8-bit ALF archives
 .\" RST source for alf(1) man page. Convert with:
@@ -36,7 +36,7 @@ alf \- create Atari 8-bit ALF archives
 .
 .SH SYNOPSIS
 .sp
-alf [\fB\-\-help\fP] | [\fB\-\-version\fP | \fB\-V\fP | [\fB\-a\fP | \fB\-o\fP ] [\fB\-t[dgz]\fP] [\fB\-v\fP] \fIalf\-file\fP \fIfile\fP [\fIfile\fP ...]
+alf [\fB\-\-help\fP] | [\fB\-\-version\fP | \fB\-V\fP | [\fB\-a\fP | \fB\-o\fP ] [\fB\-t[dgz]\fP] [\fB\-v\fP] \fIalf\-file\fP \fIfile[=NAME]\fP [\fIfile[=NAME]\fP ...]
 .SH DESCRIPTION
 .sp
 \fBalf\fP creates \fIALF\fP archives.
@@ -159,6 +159,24 @@ With either of the above, the resulting \fIALF\fP archive will extract
 with \fBunalf\fP, but will have problems with \fBDZ.COM\fP running on an
 Atari. Or you can just rename the files so they comply with Atari DOS
 filename restrictions.
+.INDENT 0.0
+.TP
+.B \fBduplicate Atari filename\fP \fI<filename>\fP
+You gave the same filename twice, or you gave two (or more) filenames that
+convert to the same "8.3" Atari filename. Example: \fIfoo.bar\fP and \fIfoo.barf\fP
+both get stored as \fIFOO.BAR\fP\&. You can avoid this by using the \fIfile=NAME\fP
+syntax, e.g.:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ alf ARCHIVE.ALF foo.bar foo.barf=FOO.BRF
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
 .SS File Size
 .INDENT 0.0
 .TP
diff --git a/src/alf.rst b/src/alf.rst
index f265697..71a3dde 100644
--- a/src/alf.rst
+++ b/src/alf.rst
@@ -21,7 +21,7 @@ create Atari 8-bit ALF archives
 SYNOPSIS
 ========
 
-alf [**--help**] | [**--version** | **-V** | [**-a** | **-o** ] [**-t[dgz]**] [**-v**] *alf-file* *file* [*file* ...]
+alf [**--help**] | [**--version** | **-V** | [**-a** | **-o** ] [**-t[dgz]**] [**-v**] *alf-file* *file[=NAME]* [*file[=NAME]* ...]
 
 DESCRIPTION
 ===========
@@ -135,6 +135,14 @@ with **unalf**, but will have problems with **DZ.COM** running on an
 Atari. Or you can just rename the files so they comply with Atari DOS
 filename restrictions.
 
+**duplicate Atari filename** *<filename>*
+  You gave the same filename twice, or you gave two (or more) filenames that
+  convert to the same "8.3" Atari filename. Example: *foo.bar* and *foo.barf*
+  both get stored as *FOO.BAR*. You can avoid this by using the *file=NAME*
+  syntax, e.g.::
+
+    $ alf ARCHIVE.ALF foo.bar foo.barf=FOO.BRF
+
 File Size
 ---------
 
diff --git a/src/unalf.1 b/src/unalf.1
index 9af4d47..8acfbfb 100644
--- a/src/unalf.1
+++ b/src/unalf.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "UNALF" 1 "2025-12-04" "0.4.0" "Urchlay's Atari 8-bit Tools"
+.TH "UNALF" 1 "2025-12-06" "0.4.0" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 unalf \- extract Atari 8-bit ALF archives
 .\" RST source for unalf(1) man page. Convert with:
@@ -374,6 +374,10 @@ Atari DOS filenames. \fI<reason>\fP will be something like "doesn\(aqt start
 with A\-Z" or "invalid character". The filename will be printed with
 any unprintable characters as hex values (e.g. \fB$01\fP).
 .TP
+.B \fBduplicate Atari filename\fP \fI<filename>\fP
+The ALF archive contains duplicate filenames. Use \fB\-n\fP to extract the
+second (and any further) occurrences of the name.
+.TP
 .B \fBheader #<n> (compressed|original) size is...\fP
 Followed by "suspiciously large" or "too large to fit on a floppy
 disk". May indicate a corrupt archive, or someone really might have
diff --git a/src/unalf.rst b/src/unalf.rst
index 9d8e14a..7b519ba 100644
--- a/src/unalf.rst
+++ b/src/unalf.rst
@@ -322,6 +322,10 @@ Warnings
   with A-Z" or "invalid character". The filename will be printed with
   any unprintable characters as hex values (e.g. **$01**).
 
+**duplicate Atari filename** *<filename>*
+  The ALF archive contains duplicate filenames. Use **-n** to extract the
+  second (and any further) occurrences of the name.
+
 **header #<n> (compressed|original) size is...**
   Followed by "suspiciously large" or "too large to fit on a floppy
   disk". May indicate a corrupt archive, or someone really might have