Added section on getting help. Added section on changing renaming separator and/or escape chars.

Fork: 0

tundra / tren

Browse code Added section on getting help. Added section on changing renaming separator and/or escape chars. master
1 parent f7b7a11 commit f968da4c2691d5da9cd2c5e1fff6b38cb1a74b97 tundra authored on 23 Mar 2010

Patch

Unified Split

Showing 1 changed file

                Ignore Space
               Show notes
              View
            
          
          56 ■■■■■
          tren.rst
 file or directory being processed and an error message will be
displayed.  This is intentional to force you to manually rename or
remove the file or directory that would have been clobbered by a
rename.  You can override this default and *force* a renaming via the 
'``-f``' option.  This will cause the orginal file or dictory itself
'``-f``' option.  This will cause the orginal file or directory itself
to be renamed with a '``.backup``' suffix.  You can change this
suffix via the '``-S``' option.
 
 
Getting Help
============
 
There are three command line options that can give you some
measure of help and information about using **tren**:
 
  -d   Dumps debug information out to stderr.  You can
       insert multiple instances of this option on the
       command line to see how the program has parsed
       everything *to the left* of it.  This is primarily
       intended as a debugging tool for people maintaining
       **tren** but it does provide considerable information
       on the internal state of the program that advanced
       users may like.
 
  -h   Prints a summary of the program invocation syntax
       and all the available options and then exits.
 
  -v   Prints the program version number and keeps running.
 
 
Renaming Building Blocks
========================
 
**tren** supports a variety of renaming mechanisms.  The one thing
they have in common is that you must specify an *old string* which
will be replaced by a *new string* when the file or directory is
to create expressive and powerful renaming schemes.
 
 
Literal String Substitution
---------------------------
===========================
 
Literal String Substitution is just that - it replaces one literal
string with another to rename the target file or directory.  This is
the most common, and simplest way to use **tren**.  This is handy when
 
  tren.py -r name\=bob=name\=sally name=bob.dbms
 
This renames the file '``name=bob.dbms``' to '``name=sally.dbms``'.
 
 
 
Forcing Renaming
================
 
takes place on the *original characters* of the target portion of the
name and does replacement as called for in the regex itself.
 
 
Changing The Renaming Separator & Escape Characters
===================================================
 
There may be times when the default renaming separator ('``=``')
and/or escape character ('``\``') make it clumsy to construct a
renaming request.  This can happen if, say, either the old- or new
string in a literal renaming needs to use the '``=``' symbol many
times.  Another case where this may be helpful is when constructing
complex regular expressions than need to make use of these characters.
 
The '``-R``' and '``-P``' options can be used to change the character
used for renaming separator and escape character respectively.  You
can use any character you like (these must be a single character
each), but bear in mind that the underlying operating system
understands certain characters as being special.  Trying to use them
here will undoubtedly deeply confuse your command shell, and possibly
your file system.  For example, the '``/``' character is used as a
path separator in Unix-derived systems.  It's therefore a Really Bad
Idea to try and use it as a renaming separator or escape character.
 
 
Interactive Renaming
====================
 
An Overview Of Renaming Tokens
==============================
 
-----------------------------
 
::
 
  $Id: tren.rst,v 1.145 2010/03/23 21:29:11 tundra Exp $
  $Id: tren.rst,v 1.146 2010/03/23 22:31:33 tundra Exp $
 
You can find the latest version of this program at:
 
  http://www.tundraware.com/Software/tren
 file or directory being processed and an error message will be
 displayed.  This is intentional to force you to manually rename or
 remove the file or directory that would have been clobbered by a
 rename.  You can override this default and *force* a renaming via the
+'``-f``' option.  This will cause the orginal file or dictory itself
+'``-f``' option.  This will cause the orginal file or directory itself
 to be renamed with a '``.backup``' suffix.  You can change this
 suffix via the '``-S``' option.
+Getting Help
+============
+There are three command line options that can give you some
+measure of help and information about using **tren**:
+  -d   Dumps debug information out to stderr.  You can
+       insert multiple instances of this option on the
+       command line to see how the program has parsed
+       everything *to the left* of it.  This is primarily
+       intended as a debugging tool for people maintaining
+       **tren** but it does provide considerable information
+       on the internal state of the program that advanced
+       users may like.
+  -h   Prints a summary of the program invocation syntax
+       and all the available options and then exits.
+  -v   Prints the program version number and keeps running.
+Renaming Building Blocks
+========================
 **tren** supports a variety of renaming mechanisms.  The one thing
 they have in common is that you must specify an *old string* which
 will be replaced by a *new string* when the file or directory is
 to create expressive and powerful renaming schemes.
 Literal String Substitution
+---------------------------
+===========================
 Literal String Substitution is just that - it replaces one literal
 string with another to rename the target file or directory.  This is
 the most common, and simplest way to use **tren**.  This is handy when
   tren.py -r name\=bob=name\=sally name=bob.dbms
 This renames the file '``name=bob.dbms``' to '``name=sally.dbms``'.
 Forcing Renaming
 ================
 takes place on the *original characters* of the target portion of the
 name and does replacement as called for in the regex itself.
+Changing The Renaming Separator & Escape Characters
+===================================================
+There may be times when the default renaming separator ('``=``')
+and/or escape character ('``\``') make it clumsy to construct a
+renaming request.  This can happen if, say, either the old- or new
+string in a literal renaming needs to use the '``=``' symbol many
+times.  Another case where this may be helpful is when constructing
+complex regular expressions than need to make use of these characters.
+The '``-R``' and '``-P``' options can be used to change the character
+used for renaming separator and escape character respectively.  You
+can use any character you like (these must be a single character
+each), but bear in mind that the underlying operating system
+understands certain characters as being special.  Trying to use them
+here will undoubtedly deeply confuse your command shell, and possibly
+your file system.  For example, the '``/``' character is used as a
+path separator in Unix-derived systems.  It's therefore a Really Bad
+Idea to try and use it as a renaming separator or escape character.
+Interactive Renaming
+====================
 An Overview Of Renaming Tokens
 ==============================
 -----------------------------
 ::
+  $Id: tren.rst,v 1.145 2010/03/23 21:29:11 tundra Exp $
+  $Id: tren.rst,v 1.146 2010/03/23 22:31:33 tundra Exp $
 You can find the latest version of this program at:
   http://www.tundraware.com/Software/tren

Show line notes below