Re: README.extfs

[Pavel Roskin <proski gnu org>]

Hello!

On Thu, 12 Dec 2002, Adam Byrtek 'alpha' wrote:

> First, very ROUGH draft attached. English is not my native language, so
> I would appreciate if somebody with a better English knowledge checked
> and corrected the text grammatically and stylistically.
>
> I'm also open to any suggestions concerning content.

I think you are getting too technical if your goal is to write
documentation for the end users.  There should not be such words as
"copyout" in this document.  Please remember that the users are not
interested in "integrating numerous features", they want to use them.

Documenting too many little details, like currently used file binding, is
counter-productive.  Those who care can find out.  On the other hand, I'll
have to require contributors to mc.ext to update this file for every minor
change or (most likely) do it myself.

Give the general idea (press Enter on the archive) and describe possible
limitations (some types of archives cannot be modified).

Please make the text 72 characters wide.  That's the default for mcedit.
Alt-P formats paragraphs.  We are gradually moving to the using two spaces
after the period that ends the sentence.  See "info texinfo", chapter
"Inserting Space".

When saying "type", don't use "$" in the beginning of the command.

I tried to make some fixes, but stopped when I encountered the first
"copyout".  The patch is attached, mostly to show the idea.

-- 
Regards,
Pavel Roskin

--- README.extfs
+++ README.extfs
@@ -1,55 +1,51 @@
+External Virtual Filesystem (extfs)
 
-EXTFS README
-
-Created by: Adam Byrtek <alpha debian org>
+Written by: Adam Byrtek <alpha debian org>
 Last update: 12 Dec 2002
 
-Starting with version 3.1, the Midnight Commander comes
-with a powerful feature called 'extfs' (EXTernal virtual
-FileSystem), which allows to integrate numerous features
-and file types into MC in an easy way.
-
-Extfs filesystems could be divided into two categories:
-
-1. Stand-alone extfs (like apt, audio and more). Those
-filesystems are NOT connected to any existing file, just
-provide some additional functionality. You can invoke them
-just by typing 'cd #fsname' where fsname is extfs short
-name (see 'Extfs reference below').
-
-  For example:
-  to list contents of CD-Audio in /dev/cdrom (default) type
-
-  $cd #audio
-
-2. 'Archive' extfs (like rpm, patchfs and more) show
-contents of some file. It can consist of 'real' files
-compressed in an archive (urar, rpm) but it could be also
-a 'virual' file, like one message in mailbox (mailfs) or a
-diff hunk (patchfs). To access such extfs '#fsname' has to
-be preceded by archive name (note that archive name could
-be in fact inside anoter vfs).
-
-  For example:
-  to list contents of rpm package type
-
-  $cd example-0.0.1-1.i686.rpm#rpm
-  
-Note that you could bind file type/extension to specified
-extfs by editing mc.ext, ~/.mcbindings or using
-'Command->Edit extension file'. Here is an example entry
-for Debian package:
+Starting with version 3.1, the Midnight Commander comes with a powerful
+feature called 'extfs' (EXTernal virtual FileSystem), which allows to
+integrate numerous features and file types into GNU Midnight Commander
+in an easy way, by writing scripts.
+
+Extfs filesystems can be divided into two categories:
+
+1. Stand-alone filesystems, which are not associated with any existing
+file.  They represent certain system-wide data as a directory tree.  You
+can invoke them by typing 'cd #fsname' where fsname is extfs short name
+(see 'Extfs reference below').  Examples of such filesystems include
+audio (list audio tracks on the CD) and apt (list of all Debian packages
+in the system).
+
+For example, to list CD-Audio tracks on your CD-ROM drive, type
+
+  cd #audio
+
+2. 'Archive' filesystems (like rpm, patchfs and more), which represent
+contents of a file as a directory tree.  It can consist of 'real' files
+compressed in an archive (urar, rpm) or virtual files, like messages in
+a mailbox (mailfs) or parts of a patch (patchfs).  To access such
+filesystems '#fsname' should be appended to the archive name.  Note that
+the archive itself can be on another vfs.
+
+For example, to list contents of zip archive documents.zip type
+
+  cd documents.zip#uzip
+
+Note that you could bind file type/extension to specified extfs by
+editing mc.ext, ~/.mc/bindings or using 'Command->Edit extension file'.
+Here is an example entry for Debian package:
 
   regex/\.deb$
           Open=%cd %p#deb
 
-In fact you could treat extfs as any other directory. For
-example you can add it to hotlist, or open with 'cd' as
-said before. There is one mail limitation: you cannot
-invoke shell command when you are inside extfs.
+In many aspects, you could treat extfs like any other directory.  For
+instance, you can add it to the hotlist or change to it from directory
+history.  An important limitation is that you cannot invoke shell
+commands inside extfs, just like any other non-local VFS.
 
-In addition to contents listing extfs can support up to
-five additional methods (see 'Extfs reference' below):
+In addition to contents listing extfs can support up to five additional
+methods (see 'Extfs reference' below):
 
   mkdir - create new directory
   rmdir - remove directory
@@ -57,10 +53,9 @@
   copyout - copy or view file (eg. extract from archive)
   copyin - copy file inside the extfs (eg. add to archive)
  
-Note: If you are looking for an information how to create
-your own extfs script to use with mc see vfat/extfs/README
-in mc source distribution. You can also browse existing
-extfs scripts in vfat/extfs/
+Note: If you are looking for an information how to create your own extfs
+script to use with mc see vfs/extfs/README in mc source distribution.
+You can also browse existing extfs scripts in vfs/extfs/