=============================================================================
Strong Extract - Extract the files from StrongHelp manuals       Version 1.00

(c) Stephen Fryatt, 2021                                      31 October 2021
=============================================================================


Licence
-------

  Strong Extract is licensed under the EUPL, Version 1.2 only (the
  "Licence"); you may not use this work except in compliance with the
  Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for Strong Extract can be found on GitHub, at
  https://github.com/steve-fryatt/strongex



Introduction
------------

  Strong Extract is a command line tool for performing simple validation on
  StrongHelp manuals, and extracting the files from them.  It is written in
  C, and can be compiled to run on platforms other than RISC OS.

  It can provide details of the differences between the contents of a manual
  file and a corresponding collection of files on disc.  There is also
  support for cross-platform handling of RISC OS filetypes.



Command Line Usage
------------------

  Strong Extract is a command line tool, and should placed in your library or
  on your path as appropriate.  Once installed, it can be used in its most
  basic form as

  "strongex <source manual> [-out] <output folder> [<options>]"

  If given only a source manual and an output folder, Strong Extract will
  compare the files contained in the source manual with the files in the
  output folder.  Any changes which would be required to bring the output
  folder into step with the source manual are reported: files which would
  need to be added to the folder, deleted from it, or which are different in
  the manual.  If the specified output folder does not exist, then Strong
  Extract will report that all of files from the manual will need to be
  added.

  A file is considered to have changed if its filetype or contents are
  different.  Since some tools generate manuals with all their files dated 1
  January 1900, dates are not compared.  Files with different names are
  treated as being completely different: there is no attempt to detect files
  which have been renamed but are otherwise unchanged.

  As Strong Extract reads the manual file, simple integrity checks are
  carried out to verify that the contents make sense.  This is not a
  foolproof guarantee that the manual is correctly formed, however.  Any
  potential problems with the file structure are reported, including:

  * File entries which point to a "DIR$" block.
  * Directory entries which point to a "DATA" block.
  * Files and directories whose size does not match the block pointed to.
  * Files with no block whose size is not zero.
  * Blocks with unrecognized guard words.

  If the -verbose parameter switch is used, Strong Extract will output more
  detailed information about the objects that it is reading.

  By default, Strong Extract will simply compare the source manual and output
  folder contents, but if the -update parameter switch is used it will
  proceed to update the contents of the output folder from the source manual.
  The folder will be created if it does not already exist, and files will
  then be added, updated and removed until its contents match those of the
  source manual.

  For more information about the options available, use "strongex -help".


  RISCOS and Linux
  -----------------

  Strong Extract can be built for use on both RISC OS and Linux, and the main
  difference between the two versions is in their handling of filenames and
  filetypes.

  On RISC OS, the contents of the manual is extracted on to disc in the same
  form as it was stored in the manual.  The main differences will stem from
  the fact that datestamps and file attributes are not preserved.

  On Linux, filetypes are preserved by appending a standard ",xxx" suffix to
  the filename, where "xxx" is the filetype in hexadecimal.  These suffixes
  are assumed to be present in any pre-existing output folder, and are used
  to obtain the filetypes of the files already there.  Files whose names have
  no extension will be assumed to have a type of Data (&FFD).

  In addition, any "/" characters in the source manual filenames are mapped
  to "." in the output folder.  All other characters in names are retained,
  and care should be taken to ensure that they are valid on the target filing
  system.



Version History
---------------

  Here is a list of the versions of Strong Extract, along with all the
  changes made.


  1.00 (31 October 2021)
  ----------------------

  Initial release.



Updates and Contacting Me
-------------------------

  If you have any comments about Strong Extract, or would like to report any
  bugs that you find, you can email me at the address below.

  Updates to Strong Extract and more programs for RISC OS computers can be
  found on my website at http://www.stevefryatt.org.uk/risc-os/

  Stephen Fryatt
  email: info@stevefryatt.org.uk
