diff -Naur dfsimage/readme.rst dfsimage.patched/readme.rst --- dfsimage/readme.rst 2023-05-04 17:38:19.198961496 -0400 +++ dfsimage.patched/readme.rst 2023-05-06 01:58:17.771007300 -0400 @@ -1,33 +1,21 @@ +.. |version| replace:: 0.9rc3_20210220_de24cf0 +.. |date| date:: + ======== dfsimage ======== -**BBC Micro Acorn DFS floppy disk image maintenance utility** - -This package contains a command-line utility and a Python module dedicated for -maintenance of **BBC Micro** disk image files. Those files usually have extensions -*.ssd* - for single sided disk image, or *.dsd* - for double sided disk image. - -This package allows indexing contents of the disk images, importing files to and -exporting from the disk images, modifying disk images in place, such as -renaming files or changing disk title and transferring data between disk images. +--------------------------------------------------------- +BBC Micro Acorn DFS floppy disk image maintenance utility +--------------------------------------------------------- + +:Manual section: 1 +:Manual group: SlackBuilds.org +:Date: |date| +:Version: |version| -The ``dfsimage`` module also supports *MMB* files. *MMB* files are containers for -large number of *.ssd* disk images, designed for storing disk images on a -MMC or SD card. All commands that work with *.ssd* FILES can be also used on a disk -image contained within an MMB file. Index of a disk image within an MMB file can be -either specified using `index`__ option, or appended to the MMB file name, following -a colon character, e.g. ``beeb.mmb:12``. Commands |list|_, |dump|_ and |digest|_ can -take a range of disk images, e.g. ``beeb.mmb:10-20`` or an entire *MMB* file. In that -case command will be applied to all *initialized* disk image in the specified range. - -There are few commands intended specially for MMB files, such as |donboot|_ or -|drecat|_. - -__ index-opt_ - -usage -===== +SYNOPSIS +======== .. code-block:: shell-session @@ -36,121 +24,31 @@ dfsimage --help-options dfsimage --help-format -**examples**: - -Index all floppy images with contents from the 'images' directory to 'index.json' file - -.. code-block:: shell-session - - dfsimage index -f json images/*.ssd images/*.dsd > index.json - -Covert a linear double sided image to a '.dsd' file - -.. code-block:: shell-session - - dfsimage convert --from -D -L linear.img --to inter.dsd - -Import all files from the 'files' directory to a new image 'games.ssd' - -.. code-block:: shell-session - - dfsimage import --new games.ssd --title="GAMES" files/* - -Export all files from the disk image at index 12 in 'beeb.mmb' file to the 'files' directory - -.. code-block:: shell-session - - dfsimage export beeb.mmb:12 -o files/ +DESCRIPTION +=========== -Index all floppy image contents from the 'images' directory to text table file - -.. code-block:: shell-session - - dfsimage index --only-files -f table images/*.ssd images/*.dsd > files.csv - -installation -============ - -At this point the package is not yet available in the PyPI repository, so -it has to be build and installed manually: - -Linux ------ - -Make sure that pip and dependencies are installed. -If you are running Debian, Ubuntu or derived Linux distribution, -install the python3-pip package like this. - -.. code-block:: shell-session - - ~$ sudo apt-get install python3-pip - -Upgrade pip to latest version. - -.. code-block:: shell-session - - ~$ python -m pip install --upgrade pip - -Clone the repository - -.. code-block:: shell-session +**dfsimage** is a command-line utility and a Python module dedicated for +maintenance of **BBC Micro** disk image files. These files usually have extensions +*.ssd* for a single sided disk image, or *.dsd* for a double sided disk image. - ~/src$ git clone https://github.com/monkeyman79/dfsimage.git - ~/src$ cd dfsimage - -Build and install package - -.. code-block:: shell-session - - ~/src/dfsimage$ python -m pip install . - -Windows -------- - -Before installing this package on a Windows machine, make sure that -both Python and Git are installed on your system. - -* Python can be downloaded from here: https://www.python.org/downloads/ -* Git for Windows can be downloaded from here: https://gitforwindows.org/ - -Make sure to add both Python and Git to your PATH when asked by the installer. - -Execute steps below in either Command Prompt or Windows PowerShell. - -.. code-block:: ps1con - - PS C:\Users\you> mkdir Documents\src - PS C:\Users\you> cd Documents\src - PS C:\Users\you\Documents\src> git clone "https://github.com/monkeyman79/dfsimage.git" - PS C:\Users\you\Documents\src> cd dfsimage - PS C:\Users\you\Documents\src\dfsimage> python -m pip install --user . - -During installation, you may see the following warning message: - - **WARNING**: The script dfsimage.exe is installed in ``'C:\Users\you\AppData\Local\Packages\...\Scripts'`` - which is not on PATH. - - Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location. - -This means that the ``'dfsimage'`` command will not be directly available. There are two options here: - -* Always execute dfsimage via ``python -m dfsimage COMMAND...`` -* Add the Scripts directory to your PATH variable - -**Adding Scripts directory to your PATH variable** - -We can combine powers of Python and PowerShell to automatically add your local -Scripts directory to PATH. -Execute the steps below in the Windows PowerShell: +**dfsimage** allows indexing contents of the disk images, importing files to and +exporting from the disk images, modifying disk images in place, such as +renaming files or changing disk title, and transferring data between disk images. -.. code-block:: ps1con +The ``dfsimage`` module also supports *MMB* files. *MMB* files are containers for +large number of *.ssd* disk images, designed for storing disk images on a +MMC or SD card. All commands that work with *.ssd* FILES can be also used on a disk +image contained within an MMB file. Index of a disk image within an MMB file can be +either specified using the `index` option, or appended to the MMB file name, following +a colon character, e.g. beeb.mmb:12. Commands **list**, **dump** and **digest** can +take a range of disk images, e.g. beeb.mmb:10-20 or an entire *MMB* file. In that +case the command will be applied to all *initialized* disk image in the specified range. - PS C:\Users\you> $USER_SITE = python -m site --user-site - PS C:\Users\you> $USER_SCRIPTS = (Get-ChildItem (Split-Path -Path $USER_SITE -Parent) Scripts).FullName - PS C:\Users\you> [Environment]::SetEnvironmentVariable("PATH", - >> [Environment]::GetEnvironmentVariable("PATH", "User") + ";$USER_SCRIPTS", "User") +There are few commands intended specially for MMB files, such as **donboot** or +**drecat**. -Now close your console window and open it again to make the change take effect. +OPTIONS +======= command list ============ @@ -1123,6 +1021,39 @@ * ``mmb_status_byte`` - Raw MMB status byte value in the MMB catalog. * ``sha1`` - SHA1 digest of the entire disk image file. +EXAMPLES +======== + +Index all floppy images with contents from the 'images' directory to 'index.json' file + +.. code-block:: shell-session + + dfsimage index -f json images/*.ssd images/*.dsd > index.json + +Covert a linear double sided image to a '.dsd' file + +.. code-block:: shell-session + + dfsimage convert --from -D -L linear.img --to inter.dsd + +Import all files from the 'files' directory to a new image 'games.ssd' + +.. code-block:: shell-session + + dfsimage import --new games.ssd --title="GAMES" files/* + +Export all files from the disk image at index 12 in 'beeb.mmb' file to the 'files' directory + +.. code-block:: shell-session + + dfsimage export beeb.mmb:12 -o files/ + +Index all floppy image contents from the 'images' directory to text table file + +.. code-block:: shell-session + + dfsimage index --only-files -f table images/*.ssd images/*.dsd > files.csv + development status ==================