diff --git a/tren.rst b/tren.rst index f319a6b..33d727b 100644 --- a/tren.rst +++ b/tren.rst @@ -1558,11 +1558,13 @@ on Windows, consider installing the ``win32all`` extensions to your Windows Python installation. If you don't, **tren** will base its order on the generic names ``WindowsUser`` and - ``WindowsGroup``. (In any case, User/Group *ID* numbers are - not meaningful under Windows and default to 0. Renaming + ``WindowsGroup``. + + In any case, User/Group *ID* numbers, and the Nlink values + are not meaningful under Windows and default to 0. Renaming tokens based on these IDs should thus be avoided on Windows systems since every file- and directory will have the same - ID.) + ID. There is one other important detail to keep in mind here. When @@ -1591,32 +1593,33 @@ ================================= -NOTE TO WINDOWS USERS GOES HERE - - These tokens are derived from information about the file or -directory being renamed. +directory being renamed. (Windows users, see the section above, +`How tren Uses File Metadata`_, on limitatioins of ``/GID/``, +``/GROUP/``, ``/UID/``, ``/USER``, & ``/NLINK/``.) ``/DEV/ Returns File- Or Directory's Device ID`` - This is the ID of the device containing the file being renamed. - You might want to rename files so that all the files on a given - device start with the same key. That way, their names group - together in a directory listing:: + This is the ID of the device containing the file being + renamed. You might want to rename files so that all the + files on a given device start with the same key. That + way, their names group together in a sorted directory + listing:: tren.py -r=/DEV/-/FNAME/ file | dir, file | dir, ... - You end up with a directory listing that looks something like:: + You end up with a sorted directory listing that looks + something like:: 93-... 93-... 97-... 98-... - The filenames are still preserved in our renaming reqest above, - now they're just preceded by the device ID of the where they live - with a trailing ``-`` separator. + The filenames are still preserved in our renaming reqest + above, now they're just preceded by the device ID of the + where they live with a trailing ``-`` separator. ``/FNAME/ Returns Original File- Or Directory Name`` @@ -1635,42 +1638,69 @@ This is the number for the group to which the file- or directory belongs. One way to use this is to prepend it to every file name, thereby having all files (and or - directories) in the same group sort together in a + directories) in the same group sort together in a sorted directory listing:: - tren.py -r=/GID/-/FNAME/ file | dir ... + tren.py -r=/GID/-/FNAME/ * ``/GROUP/ Returns File- Or Directory's Group Name`` Essentially the same as ``/GID/`` except it returns the *name* of the group rather than the number. Again, this - is useful when clustering names together in a directory listing:: + is useful when clustering names together in a sorted + directory listing:: - tren.py -r=/GROUP/-/FNAME/ file | dir ... + tren.py -r=/GROUP/-/FNAME/ * -``/INODE/ Returns File- Or Directory's`` +``/INODE/ Returns File- Or Directory's Serial Number`` - Explanation + This is typically an identifier to the directory entry + for the file- or directory being renamed. ``/DEV/`` and + ``/INODE`` taken together provide a unique systemwide + identifier for the file- or directory being renamed. -``/MODE/ Returns File- Or Directory's`` +``/MODE/ Returns File- Or Directory's Permissions`` - Explanation + This is a numeric string that represents the permissions + of the file- or directory being renamed in standard Unix + format. -``/NLINK/ Returns File- Or Directory's`` +``/NLINK/ Returns Number Of Links To File- Or Directory Being Renamed`` - Explanation + Most operating systems allow a single file to have + multiple names. These names are "linked" to the an + instance of the file. This replacement token is a + numeric string representing the number of such links. -``/SIZE/ Returns File- Or Directory's`` +``/SIZE/ Returns File- Or Directory's Length In Bytes`` - Explanation + This is handy if you want a sorted directory listing to + list all the files of the same size together. You simply + prepend the file- or directory's length onto its name:: -``/UID/ Returns File- Or Directory's`` + tren.py -r=/SIZE/-/FNAME/ * - Explanation + Now all of the files of, say, length 23 will group + together in a sorted directory listing. -``/USER/ Returns File- Or Directory's`` +``/UID/ Returns File- Or Directory's User ID`` - Explanation + This is the number for the user that owns the file- or + directory being renamed. One way to use this is to + prepend it to every file name, thereby having all files + (and or directories) owned by the same user cluster + together in a sorted directory listing:: + + tren.py -r=/UID/-/FNAME/ * + +``/USER/ Returns File- Or Directory's User Name`` + + Essentially the same as ``/UID/`` except it returns the + *name* of the user rather than the number. Again, this + is useful when clustering names together in a sorted + directory listing:: + + tren.py -r=/USER/-/FNAME/ * Time-Related Attribute Renaming Tokens @@ -2143,7 +2173,7 @@ :: - $Id: tren.rst,v 1.171 2010/04/02 20:29:45 tundra Exp $ + $Id: tren.rst,v 1.172 2010/04/03 15:40:42 tundra Exp $ You can find the latest version of this program at: