editorial revision

diff --git a/README.adoc b/README.adoc
index efd47b29e2abdf2ca069ced8eaa028496b30744f..ffc927cd9af36add12da7ff095ba2ab39558dee0 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -1,105 +1,26 @@
-fusefile
-========
-:colon: :
-:noop:
+# fusefile
 
 This project implements a "fuse" device to mount as a single file that
 is a concatenation of fragments of one or more files. The fused file
-allows overwriting the parts files, but not changing their sizes, and
-only for parts files that are writable upon first access.
-
-FUSE file mount for combining file fragments.
- 
-== SYNOPSIS
+allows overwriting to fragments but not changing their sizes and only
+for writable fragment files. A fused file may also be set up with an
+overlay file in which case that file will capture all changes instead
+of changing the underlying fragment files.
 
 ====
-*fusefile* [ _fuse options_ ] *mountpoint*  [ _overlay_ ] +_filename_/from:to+ ...
+This is a nominal usage example to set up a fused file C consisting of
+files A and B:
+----
+$ fusefile C A B
+----
 ====
 
-## DESCRIPTION
-
-*fusefile* is FUSE file mount that presents a series of fragments of
-other files as a contiguous concatenation. It bind mounts a driver on
-top of the file mountpoint to present the nominated file fragments as
-a single, contiguous file. single, contiguous file. It accepts
-over-writing on the fused file which gets distributed accordingly to
-the fragments, but cannot change size.
-
-An optional overlay file is declared with an
-**-overlay:**__filename__ argument between the mount point and
-the fragments. This file is then set up as an overlay for capturing
-writes to the fused file. The overlay file will contain the written
-fused file regions, followed by meta data to distinguish between
-written content and "holes" (where content comes from the fused
-fragments).
-       
-The fragment arguments include the filename of a source file, and
-optionally start and end byte positions. All in all there five
-variations:
-
- * __filename__ include all of the file.
-
- * __filename/__ include all of the file named with "/" in the pathname. This case requires a final "/", since the last "/" separates the filename from the position details.
-
- * __filename/from__ include the file from the given start position, to end.
-
- * __filename/-to__ include the file from beginning to the given end position (not included).
-
- * __filename/from:to__ include the file from the given start position, up to the given end position (not included). 
-
-## EXAMPLES
-
-.Insert file "y" into file "x" at position 1200:
-  
-    $ fusefile -ononempty x x/:1200 y x/1200:
-
-That mount will shadow the original file "x", and presents the
-fused file instead.
-
-.Make file y be a swap of the beginning and end of file "x", at position 2442:
-
-    $ fusefile y x/2442: x/:2442
-
-.Replace a partition in an image file with a different file
-
-    $ partx -oNR,START,SECTORS disk.raw
-    NR   START  SECTORS
-     1    2048  2097152
-     2 2099200   409600
-     3 2508800 14268383
-    # Replace partition 2 of 409600 sectors from 2099200 with
-    # the file "insert.fat" clipped to 409600 sectors.
-    $ fusefile -ononempty disk.raw \
-         disk.raw/0:$(( 2099200*512 )) \
-         insert.fat/0:$(( 409600*512 )) \
-         disk.raw/$(( (2099200+409600)*512 )):
-
-.Protect raw disk image file with an overlay:
-    $ fusefile -ononempty disk.raw -overlay:today disk.raw
-
-By that set up, the overlay file, "today", will protect the disk image
-file, "disk.raw" from changes, and also override the pathname
-"disk.raw" to be the fused file.
-
-
-## NOTES
-
-Note that **fusefile** opens the nominated source file(s) before bind
-mounting. With the fuse option __-ononempty__ it will bind over an
-non-empty file, which may be useful. The source file descriptors
-remain open, but the source fragments are not recomputed. If a source
-file changes or reduces in size "behind" the fused file, then anything
-may happen.
-
-If the mountpoint file doesn't exist, then **fusefile** creates it.
-
-Unmounting is done with "**fusermount -u** __mountpoint__" as usual.
-
-Using an overlay file makes the fused file writable regardless of the
-fused fragments with the overlay file containing any changes to the
-original. The overlay file is reusable for subsequent fusing of the
-same fragments for reconstructing a prior session with changes.
+====
+This is a nominal example of tearing down a fused file X:
+----
+$ fusermount -u C
+----
+====
 
-## AUTHOR
+See the +man page+ for usage details and some more examples.
 
-Ralph Rönnquist <ralph.ronnquist@gmail.com>.