path: root/development/dfsimage/man_page.diff

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
 ==================