Package: fensterbrief
fensterbriefis a python script for working with letters based on LaTeX and
markdown.Short introductionFeaturesUsageList all archived lettersSearch for a string in directory and filenamesCreate a new letter based on an old oneMarkdown-based lettersSending a letterBuying postageLookup an addressInstallationTechnical installation of the tool itselfSetup the environmentUpdate the installationCustomize templatesSample configuration fileSetupfrankto buy stampsCreate a signature fileObtain a Google API keyCopyright and LicenceShort introductionfensterbrief(German for window envelope) is a helper script to
manage the creation and archival of LaTeX- and Markdown-based
letters. It helps you in managing folders in a structured way and to
consistently name files. It helps in creating new letters based
on old ones. It tries to make letter writing easy witout adding
over-specialised functionality.fensterbriefdoes not process metadata beyond file and directory
names. It is not a LaTeX editor.Whilefensterbriefis more or less OS independent, it currently only
supports Unix-style environments.Featuresintended to be used via command linemaintaining a folder and document structuresupport for LaTeX and Markdown based letterssupport for fax transmissions via simple-fax.desupport for buying postage for the Deutsche Postlookup postal addresses via the Google APIUsageThefensterbrieftool is command line based:$ fensterbrief --help
usage: fensterbrief [-h] [--list-templates] [--list-letters] [--search STRING]
            [--create-folder] [--adopt FILE] [--edit [FILE]]
            [--render [FILE]] [--show-pdf [FILE]] [--set-folder DIR]
            [--cat FILE] [--mail-simple-fax DEST]
            [--soap-simple-fax DEST] [--buy-stamp [PRODUCT_ID]]
            [--lookup-address STRING] [--keep-folder] [--config FILE]
            [--verbose] [--configure] [--version]

Manage letters via command line

optional arguments:
  -h, --help            show this help message and exit
  --list-templates      List all letter templates
  --list-letters        List all letters
  --search STRING       Search for a string in filenames
  --create-folder       Ask for meta data and create a new folder
  --adopt FILE          Create a new letter based on a previous one
  --edit [FILE]         Edit the current letter or another source file
  --render [FILE]       Render PDF file from current markdown or latex
  --show-pdf [FILE]     Open PDF file in PDF viewer
  --set-folder DIR      Set the working folder
  --cat FILE            Dump content of a letter
  --mail-simple-fax DEST
                        Send a fax via simple-fax.de using the e-mail
                        interface
  --soap-simple-fax DEST
                        Send a fax via simple-fax.de using the SOAP interface
  --buy-stamp [PRODUCT_ID]
                        Buy a stamp. Place postage file in current folder or
                        use together with --adopt.
  --lookup-address STRING
                        Search for an address via Google. Can be used together
                        with --adopt.
  --keep-folder         Store the adopted letter in the same folder
  --config FILE         The configuration file to use
  --verbose             Show what is going on
  --configure           Initialize the environment and configure the tool
  --version             Show versionList all archived letters$ fensterbrief --list-letters
+ Looking up letters in /home/martin/Documents/Vorgaenge/
[...]
+ 2010-09-company_X-anmeldung/2010-09-28_anmeldung.tex
+ 2010-09-company_X-anmeldung/2011-05-04-vertragsunterlagen.tex
+ 2014-09-company_Y-guthabenerstattung/2014-09-29-companyY-guthabenerstattung.tex
[...]Search for a string in directory and filenames$ fensterbrief --search companyX
+ Looking up letters in /home/martin/Documents/Vorgaenge/
[...]
+ 2010-09-company_X-anmeldung/2010-09-28_anmeldung.tex
+ 2010-09-company_X-anmeldung/2011-05-04-vertragsunterlagen.tex
[...]Create a new letter based on an old oneOften you already started a letter conversation with a recipient and
have a followup letter. You like to adopt the old LaTeX letter, because
you inserted reference numbers such as you customer or tax ID or the
destination address. To write a new letter, you simply copy the old
LaTeX file to a new destination folder. Technically, it makes no
difference, whether you adopt an old letter or a template file.$ fensterbrief --adopt 2014-09-company_X-guthabenerstattung/2014-09-29-company_X-guthabenerstattung.tex
Recipient short name: company X
Folder subject: Klärung Situation X
Letter subject: Klärung Situation X
+ Folder subject: Klarung_Situation_X
+ Letter subject: Klarung_Situation_X
+ Recipient: company_X
+ Creating folder /home/martin/Documents/Vorgaenge/2016-12_company_X-Klarung_Situation_X
+ Copy file /home/martin/Documents/Vorgaenge/2014-09-company_X-guthabenerstattung/2014-09-29-company_X-guthabenerstattung.tex to /home/martin/Documents/Vorgaenge/2016-12_company_X-Klarung_Situation_X/2016-12-14_company_X-Klarung_Situation_X.texAfterwards, the fensterbrief script will launch the LaTeX editor that
has been configured. Since LaTeX editors usually support a build-in
function for rendering and printing, there are no further steps relevant
here. If you use a editor that does not support rendering, you can
render your letter from command line, too. Please refer to the bext
section.If you write a follow-up letter and want to store this letter in the
same directory as the original letter, just add option –keep-folder.$ fensterbrief --adopt ... --keep-folderWhen a letter is created,fensterbriefkeeps track of it in a file${ROOT_DIR}/.working_object.conf. This file references the current
letter and simplifies the process of interacting with the letter.Markdown-based lettersAdopting a Markdown letter isn’t much different from creating a
LaTeX-based letter. The source file of a Markdown-based letter looks
like this:Sample Markdown letterUsually, you likely use a more general editor that may not support
LaTeX/pandoc directly. Therefore, you may want to render your letters
explicitly as shown below:$ fensterbrief --renderAfterwards you can open the rendered PDF file in a PDF viewer, check the
output and print the document:$ fensterbrief --show-pdfIf you want to make further changes to your letter, you can run the
editor again:$ fensterbrief --editCommands can be chained, for example:$ fensterbrief --edit --render --show-pdfTo render PDF files from Markdown via LaTeX,fensterbriefusespandocwith this LaTeX template:LaTeX letter template used as pandoc
templateSending a letterUsually, you will print your letter from the LaTex editor and close the
editor afterwards. However, sometimes a letter should not be sent via
snail mail, instead it should be sent via Fax. Because I use the prepaid
service fromhttp://simple-fax.de,fensterbriefsupports this
service provider.Simple-fax.de supports fax sending via aSOAP-based web
API. However,
this interface lacks support for a transmission confirmation. The
simple-fax interface will call you back on your own web interface for
status tracking, but you have to setup your status handler and you will
not get a fancy transmission confirmation.Therefore, I prefer the mail interface, because their e-mail interface
sends status messages, a transmission confirmation PDF including the
first page of your fax message, and you will have everything archived in
your mail user agent. To send your letterfensterbriefwill invoke
your mail client.$ fensterbrief --mail-simple-fax <faxnum>It will launch a prefilled ‘new mail’ dialog. Currently, only
Thunderbird is supported. If you work with multiple e-mail accounts or
e-mail identities, please make sure, the correct ‘from’ address is
selected. The~/.fensterbrief.confconfiguration file has a setting
for this (mail_fromin sectionmail_to_simple_fax_de). For some
reason, an index such asid2must be specified to select the ‘from’
address instead of using just an ordinary e-mail address.Buying postagefensterbriefuses the toolfrankto buy stamps for the
Deutsche Post. These stamps are named “Internetmarke” or “1C4A” for
“1Click4Applikation”. Once,frankis set up, you can buy stamps in
two modes.Buying postage, when creating a letter:$ fensterbrief --adopt 2014-09-company_X-guthabenerstattung/2014-09-29-company_X-guthabenerstattung.tex --buy-stampBuying postage for the current letter:$ fensterbrief --buy-stampThe later approach works, becausefensterbriefstores the path and
filenames of the current folder and letter.Lookup an addressWhen adopting a Markdown-based letter, you can lookup a postal address
via Google and the address is used in the letter as destination address:$ fensterbrief --adopt _templates/template-pandoc.md --keep-folder --lookup-address 'rathaus mitte, berlin'If there are multiple matches, a list of matches is shown and you select
an index.This operation requires a Google API key.InstallationTechnical installation of the tool itselfInstall dependencies:$ sudo apt-get install texlive texlive-lang-german \
    texlive-fonts-extra texlive-latex-extra texlive-generic-recommended \
    python3-pip pandoc \Installfensterbrief:$ sudo pip3 install fensterbriefSetup the environmentAfter installing the tool, the configuration file must be created. A
wizzard mode asks for certain configuration points as shown below.$ fensterbrief --configure
+ Root directory, where letters should be stored
  ---------------------------------------------------------------
  Default value: /home/martin/Documents/letters/
  Current value: /home/martin/Documents/Vorgaenge/
  Enter: keep current configuration, 'd': use default configuration
  >
+ Use value: /home/martin/Documents/Vorgaenge/

+ Template directory, where template letters are stored
  ---------------------------------------------------------------
  Default value: ${ROOT_DIR}/_templates/
  Current value: /home/martin/Documents/Vorgaenge//_templates/
  Enter: keep current configuration, 'd': use default configuration
  > d
+ Use value: ${ROOT_DIR}/_templates/

  [...]It is possible to use text makros such as the${ROOT_DIR}.Update the installationTo upgradefensterbrief, use the following commands:$ sudo pip3 install fensterbrief --upgrade
$ fensterbrief --configureIf--configureis used and there is already a configuration file,fensterbriefwill ask whether you want to use the default value or an existing configuration entry or a new value.Customize templatesThe wizzard copys template files to the user’s template directory. These
templates should be customized in a last step.You can use your own LaTeX templates. They can be based on the LaTeX
g-brief, on scrlttr2 or on any other letter class. The templates that
are shipped in this package are based on scrlttr2. There are plenty of
template examples on the Internet, which you can adjust to your needs.
My templates look like this:Rendered standard letter
templateRendered standard invoice
templateRendered standard letter template for defeating advertising and
personal data
usageWhen running--configure,.lcofiles are copied to the~/texmf/tex/latex/fensterbrief/directory andtexhashis run
afterwards.Sample configuration fileExample configuration file~/.fensterbrief.conf:[DEFAULT]
root_dir = /home/martin/Documents/Vorgaenge/
template_dir = ${ROOT_DIR}/_templates/
tex_editor = texmaker
md_editor = emacs -nw

[pandoc]
program = pandoc
template = ${template_dir}/template-pandoc.tex

[latex]
program = latex

[google]
api_key = xxxx

[mail_to_simple_fax_de]
mail_client = thunderbird
mail_from = id3

[soap_to_simple_fax_de]
user = foo@example.com
password = secret

[frank]
program = /home/martin/Development/frank/frank.py
product = 1Setupfrankto buy stampsfensterbriefuses the toolfrankto buy stamps, which itself is
based on the python modulepython-inema.Setting upfrankis a bit complex, because it requires manual
interactions aka. sending mails to the system operator. To use frank,
please refer to the instructions on thegithub page of
frank.Create a signature fileSometimes it is useful to have a digital version of one’s signature to
include it in a letter, when it is sent as fax via an Internet service.
This is more convinient than printing a letter, placing a signature,
scan it as PDF file.A step-by-step guide to achieve this is describe in astackoverflow
article.Obtain a Google API keyYou need a Google API key in order to use this feature. You can get an
API key fromGoogle,
which requires a Google account.It may also be possible to find API keys atGithubCopyright and Licencefensterbriefis developed by Martin Schobertmartin@schobert.ccand
published under a BSD licence with a non-military clause. Please readLICENSE.txtfor further details.