Readme update

README.rst

@@ -2,14 +2,181 @@
 E-UAE Wrapper
 =============
 
-This little utility is a wrapper on old E-UAE_ emulator, to help divide
-configuration to common and specific per ``.uaerc`` configuration, and combine
-them together during runtime.
+This utility is a wrapper on old E-UAE_ emulator, to help divide configuration
+to common and specific per ``.uaerc`` configuration, and combine them together
+during runtime.
 
-Global (a common) config file will reside on ``XDG_CONFIG_HOME/e-uaerc``, and
-supports following options:
 
-(TODO)
+Requirements
+============
+
+- Python (2 or 3)
+- `e-uae`_
+
+e-uae-wrapper supports several types of archives:
+
+- `7z`_
+- `lha`_
+- `lzx`_ - decompress only
+- `rar`_ - if only ``unrar`` is available, than only decompression is supported
+- `tar`_, also compressed with:
+
+  - bzip2
+  - gzip
+  - xz
+
+- `zip`_
+
+All of those formats should have corresponding software available in the
+system, otherwise archive extraction/compression will fail.
+
+
+Configuration
+=============
+
+Optional, global (a common) config file will be searched on
+``XDG_CONFIG_HOME/e-uae.ini``, (usually at ``~/.config/e-uae.ini`` and supports
+anthing, which could be used for templating, ie paths to roms, floppies,
+harddrives etc. Anything which might be treated as a common variables for all
+avalialbel ``.uaerc`` configs.  For example:
+
+.. code:: ini
+
+   [config]
+   wrapper_kickstart_path = /home/user/Amiga/kickstart
+
+and with corresponding e-uae configuration (i.e. ``.uaerc``), it can be used
+like:
+
+.. code::
+
+   config_description=UAE default configuration
+   config_hardware=false
+   config_host=false
+   config_version=0.8.29
+   ...
+   kickstart_rom_file={{wrapper_kickstart_path}}/kick.rom
+
+Note, that such options should always start with ``wrapper`` word, and in
+``.uaerc`` has to be enclosed with curly braces, like in the example above.
+
+There are two additional build-in options which can be used in templates:
+
+* ``wrapper_tmp_path`` - which points to the path, where ``.uaerc`` is
+  generated, and potentially archives are extracted
+* ``wrapper_config_path`` - which point to the absolute path, where passed by
+  the commandline  configuration (``.uaerc``) is placed.
+
+All wrapper options which name contain *path* word will be treatead as paths,
+and as a consequence will be replaced with full path to the item, for example:
+
+.. code::
+
+   wrapper_foo_path=/some/filepath
+   filesystem=rw,HD:{{wrapper_foo_path}}../otherpath/hd
+
+will become:
+
+.. code::
+
+   filesystem=rw,HD:/some/otherpath/hd
+
+Note, that using templates like ``{{wrapper_foo_path}}/otherpath/hd`` will
+create path ``/otherpath/hd`` instead of ``/some/filepath/otherpath/hd``
+because of how ``os.path.join`` work. Be careful on using ``/`` in paths.
+
+
+Installation
+============
+
+It's alfa stage of the development, so that it is not easy way to do the
+installation yet. However, to use it, it's enough to clone this repository,
+copy ``scripts/e-uae-wrapper`` to sowhere in the ``PATH`` and point
+``PYTHONPATH`` to ``e_uae_wrapper``, like:
+
+.. code:: shell-session
+
+   $ git clone https://github.com/gryf/e-uae-wrapper
+   $ mkdir ~/bin
+   $ export PATH=$PATH:$HOME/bin
+   $ export PYTHONPATH=$PYTHONPATH:$(pwd)/e-uae-wrapper
+
+
+Usage
+=====
+
+The usage is simple. Prepare some ``.uaerc`` file as described above, use
+command ``e-uae-wrapper`` with configuration passed as an argument:
+
+.. code:: shell-session
+
+   $ e-uae-wrapper uaerc-config-file
+
+
+Modules
+=======
+
+There are following modules currently implemented:
+
+- plain
+- archive
+
+Plain
+-----
+
+This module is simply for running emulator with template usage. It makes easy
+to put relative paths in ``.uaerc`` configuration.
+
+Options used:
+
+* None
+
+archive
+-------
+
+This module is quite useful in two use cases. First is a usual work with
+Workbench, where there is a need to keep changes of filesystem. Second is the
+opposite - if there is a need to test some software, but not necessary keep it
+in a Workbench, than it will act as a temporary copy of the system, so that
+next time e-uae will be run, there will be no files of tested software
+cluttering around.
+
+Options used:
+
+* ``wrapper`` (required) with ``archive`` as an value
+* ``wrapper_archive`` (required) path to the archive with assets (usually means
+  whole system directories, floppies or hard disk images)
+* ``wrapper_gui_msg`` (optional) if set to "1", will display a graphical
+  message during extracting files
+* ``wrapper_persist_data`` (optional) if set to "1", will compress (possibly
+  changed) data, replacing original archive
+
+Example configuration:
+
+.. code::
+
+   config_description=UAE default configuration
+   wrapper=archive
+   wrapper_archive=Workbench_3.1.tar.bz2
+   wrapper_archiver=lha
+   wrapper_gui_msg=1
+   wrapper_persist_data=1
+   # ...
+
+And execution is as usual:
+
+.. code:: shell-session
+
+   $ e-uae-wrapper Workbench.fs-uae
+
+This module will do several steps:
+
+- create temporary directory
+- extract provided in configuration archive
+- copy configuration under name ``.uaerc``
+- run the e-uae emulator
+- optionally create new archive under the same name as the original one and
+  replace it with original one.
 
 License
 =======
@@ -17,3 +184,11 @@ License
 This work is licensed on 3-clause BSD license. See LICENSE file for details.
 
 .. _e-uae: http://www.rcdrummond.net/uae/
+.. _relative configuration file: https://fs-uae.net/configuration-files
+.. _rar: http://www.rarlab.com/rar_add.htm
+.. _7z: http://p7zip.sourceforge.net/
+.. _lha: http://lha.sourceforge.jp
+.. _lzx: http://aminet.net/package/misc/unix/unlzx.c.readme
+.. _tar: https://www.gnu.org/software/tar/
+.. _zip: http://www.info-zip.org
+.. _CheeseShop: https://pypi.python.org/pypi/fs-/fs-uae-wrapperuae-wrapper