## Time-stamp: <2013-05-16 19:05:51 vk>
## -*- coding: utf-8 -*-
## This file is best viewed with GNU Emacs Org-mode: http://orgmode.org/

* appendfilename.py

This Python script adds a string to a file name. The string gets added
between the original file name and its extension.

In case the file name contains tags as handled as with [[https://github.com/novoid/filetag][filetag]], the
string gets added right before the separator between file name and
tags.

Examples for adding the string "foo bar":

| *old file name*                        | *new file name*                                |
|----------------------------------------+------------------------------------------------|
| a simple file.txt                      | a simple file foo bar.txt                      |
| 2013-05-09T16.17_img_00042.jpeg        | 2013-05-09T16.17_img_00042 foo bar.jpeg        |
| 2013-05-09T16.17_img_00042 -- fun.jpeg | 2013-05-09T16.17_img_00042 foo bar -- fun.jpeg |

- *Target group*: users who are able to use command line tools and who
  are using tags in file names.
- Hosted on github: https://github.com/novoid/appendfilename

** Why

Besides the fact that I am using [[https://en.wikipedia.org/wiki/Iso_date][ISO dates and times]] in file names
(as shown in examples above), I am using tags with file names. To
separate tags from the file name, I am using the separator ~ -- ~
(space dash dash space).

For people familiar with [[https://en.wikipedia.org/wiki/Regex][Regular Expressions]]:

: (<ISO date/time stamp>)? <descriptive file name> -- <list of tags separated by spaces>.extension

For tagging, please refer to [[https://github.com/novoid/filetag][filetag]] and its documentation.

If I want to add a descriptive file name to files like ,e.g.,
photographs, I have to rename the original file and insert the
description at the right spot of the existing file name.

This is not an error-prone task. If I am not careful, I can overwrite
parts of the old file name I wanted to keep. Or I could mess up
spacing between the old file name, tags, and the new description.

Therefore, I wrote this script that adds a description to the file
name without removing old file name parts or tags.

You may like to add this tool to your image or file manager of
choice. I added mine to [[http://geeqie.sourceforge.net/][geeqie]] which is my favorite image viewer on
GNU/Linux.

** Usage

: appendfilename.py --text foo a_file_name.txt
... adds "foo" such that it results in ~a_file_name foo.txt~

: appendfilename.py a_file_name.txt
... (implicit) interactive mode: asking for the string to add from the user

: appendfilename.py --text "foo bar" "file name 1.jpg" "file name 2 -- foo.txt" "file name 3 -- bar.csv"
... adds tag "foo" such that it results in ...
: "file name 1 foo bar.jpg"
: "file name 2 foo bar -- foo.txt"
: "file name 3 foo bar -- bar.csv"

For a complete list of parameters, please try:
: appendfilename.py --help

** Bonus: integrating into Geeqie (or similar file browsers)

I am using [[http://geeqie.sourceforge.net/][geeqie]] for browsing/presenting image files. For quickly
adding descriptive text to image file(s), I mapped this script to
~r~. This way, I can go through my image files very quickly and do not
have to worry about placing cursor in the rename dialog of geeqie.

Using GNU/Linux, this is quite easy accomplished. The only thing that
is not straight forward is the need for a wrapper script. The wrapper
script does provide a shell window for entering the tags.

~vk-appendfilename-interactive-wrapper-with-gnome-terminal.sh~ looks like:
: #!/bin/sh
: 
: /usr/bin/gnome-terminal \
:     --geometry=157x56+330+5  \
:     --tab-with-profile=big \
:     --hide-menubar \
:     -x /home/vk/src/appendfilename/appendfilename.py "${@}"
: 
: #end

In ~$HOME/.config/geeqie/applications~ I wrote a desktop file such
that geeqie shows the wrapper script as external editor to its
image files:

~$HOME/.config/geeqie/applications/appendfilename.desktop~ looks like:
: [Desktop Entry]
: Name=appendfilename
: GenericName=appendfilename
: Comment=
: Exec=/home/vk/src/misc/vk-appendfilename-interactive-wrapper-with-gnome-terminal.sh %F
: Icon=
: Terminal=true
: Type=Application
: Categories=Application;Graphics;
: hidden=false
: MimeType=image/*;video/*;image/mpo;image/thm
: Categories=X-Geeqie;

In order to be able to use the keyboard shortcuts ~r~, you can define
them in geeqie:
1. Edit > Preferences > Preferences ... > Keyboard.
2. Scroll to the bottom of the list.
3. Double click in the ~KEY~-column of ~appendfilename~ and choose
   your desired keyboard shortcut accordingly.

I hope this method is as handy for you as it is for me :-)


* Contribute!

I am looking for your ideas!

If you want to contribute to this cool project, please fork and
contribute!


* Local Variables                                                  :noexport:
# Local Variables:
# mode: auto-fill
# mode: flyspell
# eval: (ispell-change-dictionary "en_US")
# End: