From f7fa8ed22f49680a9fad4cdcb38d4d4cb71d454b Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Fri, 10 May 2024 19:32:20 -0400 Subject: convert ksiders man pages to RST, part 4. --- ksiders/sortatr.1 | 177 +++++++++++++++++++++++++++++++--------------------- ksiders/sortatr.rst | 84 +++++++++++++++++++++++++ 2 files changed, 190 insertions(+), 71 deletions(-) create mode 100644 ksiders/sortatr.rst diff --git a/ksiders/sortatr.1 b/ksiders/sortatr.1 index 98301b3..5d3847c 100644 --- a/ksiders/sortatr.1 +++ b/ksiders/sortatr.1 @@ -1,80 +1,115 @@ -.TH SORTATR "1" "April 2007" "sortatr" "Ken Siders' Atari 8-bit Tools" +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "SORTATR" 1 "2024-05-10" "0.9.0" "Ken Siders' Atari 8-bit Tools" .SH NAME -\fBsortatr\fR \- sort Atari DOS directory in an ATR image - +sortatr \- sort Atari DOS directory in an ATR image .SH SYNOPSIS -\fBsortatr\fR \fIimagefile.atr\fR - +.sp +sortatr \fIimagefile.atr\fP .SH DESCRIPTION -\fBsortatr\fR sorts the directory entries in an Atari DOS 2.0S or MyDOS +.sp +\fBsortatr\fP sorts the directory entries in an Atari DOS 2.0S or MyDOS compatible ATR images. The sort is alphabetical, and the disk image is modified in place. -.PP -\fBatrextr\fR does not take any options. +.sp +\fBsortatr\fP does not take any options. +.sp +XFD format images are not supported. .SH WARNINGS -\fBDO NOT USE\fR this utility with DOS 2.5 disk images! -.PP -\fBDO NOT USE\fR this utility with MyDOS images containing subdirectories! -.PP -\fBDATA LOSS\fR will occur if these warnings are not heeded! The modified -directory in the image will not contain any references to DOS 2.5 files -using sectors above 720, or to MyDOS subdirectories. This effectively -\fBdeletes\fR these files from the image. -.PP -If in doubt, list the image's directory with \fBatrdir\fR. If you see -files marked with a \fI:\fR (colon) or \fI<\fR (less-than), then -\fBsortatr\fR should not be used on the image. Even if your purpose -is actually to delete these files/dirs, you should use some other -utility (or DOS on a real or emulated Atari) to delete them, because -\fBsortatr\fR doesn't free the sectors occupied by the files/dirs. -.PP +.sp +\fBDO NOT USE\fP this utility with DOS 2.5 disk images! +.sp +\fBDO NOT USE\fP this utility with MyDOS images containing subdirectories! +.sp +\fBDATA LOSS\fP will occur if these warnings are not heeded! The +modified directory in the image will not contain any +references to DOS 2.5 files using sectors above 720, or to MyDOS +subdirectories. This effectively deletes these files from the image. +.sp +If in doubt, list the image\(aqs directory with \fBatrdir\fP\&. If you see +files marked with a \fI:\fP (colon) or \fI<\fP (less\-than), then \fBsortatr\fP +should not be used on the image. Even if your purpose is actually to +delete these files/dirs, you should use some other utility (or DOS +on a real or emulated Atari) to delete them, because \fBsortatr\fP +doesn\(aqt free the sectors occupied by the files/dirs. +.sp If you ignore these warnings and manage to delete files or directories -from your disk image, it should be possible to recover them with a good -Atari undelete or disk\-repair utility. Although the affected files/dirs -have been removed from the disk directory, the data sectors have not -been overwritten nor marked as free (meaning they won't be overwritten -by later write operations, unlike most "undelete" situations). -First, you have to -find the starting sector of the missing file/dir and -create a directory entry for it in the directory at sectors 36-368. You -will probably also have to change the file number in the sector link -bytes, or else delete the file in the new directory that's using the -file number of the old (deleted) file. -.PP -Further warnings: -.PP -\fBDO NOT USE\fR this utility with any non-standard (non\-AtariDOS, -non-MyDOS compatible) disk image. -.PP -Boot disks with no directory, -SpartaDOS, Atari DOS 3/4, DOS XE, or other non\-standard DOS formatted -disks might (if you're lucky) just cause an error message. If -you're not lucky, they may be corrupted. There is no easy way to -recover an image that gets damaged in this way. -.PP -\fBDO NOT USE\fR this utility with \fIany\fR image without creating a -backup first! -.PP -Any image you use with \fBsortatr\fR is modified in-place, -and no backup is made by \fBsortatr\fR. \fBAlways\fR make a backup -copy of an ATR image before you use \fBsortatr\fR on it. \fIYou have -been warned\fI. -.SH NOTES -XFD format images are not supported. -.PP -Exit status is zero if the sort was successful, or -non-zero if any errors occurred. In case of a non-zero return, -the disk image may be truncated, or its directory sectors may be -damaged. Hope you had a backup of that image! +from your disk image, it should be possible to recover them with +a good Atari undelete or disk\-repair utility. Although the affected +files/dirs have been removed from the disk directory, the data +sectors have not been overwritten nor marked as free (meaning they +won\(aqt be overwritten by later write operations, unlike most "undelete" +situations). First, you have to find the starting sector of the +missing file/dir and create a directory entry for it in the directory +at sectors 36\-368. You will probably also have to change the file +number in the sector link bytes, or else delete the file in the new +directory that\(aqs using the file number of the old (deleted) file. +.SS Further warnings +.sp +\fBDO NOT USE\fP this utility with any non\-standard (non\-AtariDOS, non\-MyDOS +compatible) disk image. +.sp +Boot disks with no directory, SpartaDOS, Atari DOS 3/4, DOS XE, +or other non\-standard DOS formatted disks might (if you\(aqre lucky) +just cause an error message. If you\(aqre not lucky, they may be +corrupted. There is no easy way to recover an image that gets damaged +in this way. +.sp +\fBDO NOT USE\fP this utility with any image without creating a backup first! +.sp +Any image you use with \fBsortatr\fP is modified in\-place, and no backup is +made by \fBsortatr\fP\&. Always make a backup copy of an ATR image before you +use \fBsortatr\fP on it. You have been warned. +.SH EXIT STATUS +.sp +Exit status is zero if the sort was successful, or non\-zero if any +errors occurred. In case of a non\-zero return, the disk image may be +truncated, or its directory sectors may be damaged. Hope you had a +backup of that image! +.SH COPYRIGHT +.sp +Copyright 1997, Ken Siders. .SH AUTHOR -Ken Siders <\fBatari8bit@columbus.rr.com\fR> -.PP -Man page by B. Watson <\fBurchlay@urchlay.com\fR> - +.sp +Ken Siders was the original author of this utility. +.sp +Man page and Linux port done by B. Watson <\fI\%urchlay@slackware.uk\fP>; +Urchlay on irc.libera.chat \fI##atari\fP\&. .SH SEE ALSO -\&\fIatrdir\fR\|(1), \&\fIatrextr\fR\|(1), \&\fImakeatr\fR\|(1), -\&\fIunmakatr\fR\|(1). -.PP -Ken Siders Atari 8-bit page: -.br -http://atari.ksiders.tzo.com/a8emulators.html +.sp +\fBatrdir\fP(1), +\fBatrextr\fP(1), +\fBmakeatr\fP(1), +\fBsortatr\fP(1). +.sp +Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference +Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. +.\" Generated by docutils manpage writer. +. diff --git a/ksiders/sortatr.rst b/ksiders/sortatr.rst new file mode 100644 index 0000000..552a960 --- /dev/null +++ b/ksiders/sortatr.rst @@ -0,0 +1,84 @@ +======= +sortatr +======= + +---------------------------------------- +sort Atari DOS directory in an ATR image +---------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== +sortatr *imagefile.atr* + +DESCRIPTION +=========== + +**sortatr** sorts the directory entries in an Atari DOS 2.0S or MyDOS +compatible ATR images. The sort is alphabetical, and the disk image +is modified in place. + +**sortatr** does not take any options. + +XFD format images are not supported. + +WARNINGS +======== + +**DO NOT USE** this utility with DOS 2.5 disk images! + +**DO NOT USE** this utility with MyDOS images containing subdirectories! + +**DATA LOSS** will occur if these warnings are not heeded! The +modified directory in the image will not contain any +references to DOS 2.5 files using sectors above 720, or to MyDOS +subdirectories. This effectively deletes these files from the image. + +If in doubt, list the image's directory with **atrdir**. If you see +files marked with a *:* (colon) or *<* (less-than), then **sortatr** +should not be used on the image. Even if your purpose is actually to +delete these files/dirs, you should use some other utility (or DOS +on a real or emulated Atari) to delete them, because **sortatr** +doesn't free the sectors occupied by the files/dirs. + +If you ignore these warnings and manage to delete files or directories +from your disk image, it should be possible to recover them with +a good Atari undelete or disk-repair utility. Although the affected +files/dirs have been removed from the disk directory, the data +sectors have not been overwritten nor marked as free (meaning they +won't be overwritten by later write operations, unlike most "undelete" +situations). First, you have to find the starting sector of the +missing file/dir and create a directory entry for it in the directory +at sectors 36-368. You will probably also have to change the file +number in the sector link bytes, or else delete the file in the new +directory that's using the file number of the old (deleted) file. + +Further warnings +---------------- + +**DO NOT USE** this utility with any non-standard (non-AtariDOS, non-MyDOS +compatible) disk image. + +Boot disks with no directory, SpartaDOS, Atari DOS 3/4, DOS XE, +or other non-standard DOS formatted disks might (if you're lucky) +just cause an error message. If you're not lucky, they may be +corrupted. There is no easy way to recover an image that gets damaged +in this way. + +**DO NOT USE** this utility with any image without creating a backup first! + +Any image you use with **sortatr** is modified in-place, and no backup is +made by **sortatr**. Always make a backup copy of an ATR image before you +use **sortatr** on it. You have been warned. + + +EXIT STATUS +=========== + +Exit status is zero if the sort was successful, or non-zero if any +errors occurred. In case of a non-zero return, the disk image may be +truncated, or its directory sectors may be damaged. Hope you had a +backup of that image! + +.. include:: manftr.rst -- cgit v1.2.3