diff options
Diffstat (limited to 'development/dfsimage/man_page.diff')
| -rw-r--r-- | development/dfsimage/man_page.diff | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/development/dfsimage/man_page.diff b/development/dfsimage/man_page.diff new file mode 100644 index 0000000000000..590fc240f4ac7 --- /dev/null +++ b/development/dfsimage/man_page.diff @@ -0,0 +1,232 @@ +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 + ================== + |