diff --git a/tren.rst b/tren.rst index 961a2aa..bc8081e 100644 --- a/tren.rst +++ b/tren.rst @@ -446,10 +446,35 @@ 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 @@ -476,7 +501,7 @@ 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 @@ -518,6 +543,8 @@ This renames the file '``name=bob.dbms``' to '``name=sally.dbms``'. + + Forcing Renaming ================ @@ -632,6 +659,29 @@ 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 ============================== @@ -1305,7 +1355,7 @@ :: - $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: