diff Readme.rst @ 31:3b0546fa0d74

Add documentation in alternative formats to HTML.
author David Barts <davidb@stashtea.com>
date Sat, 18 Apr 2020 09:08:23 -0700
parents
children 35fb8de77c7d
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Readme.rst	Sat Apr 18 09:08:23 2020 -0700
@@ -0,0 +1,159 @@
+[This file automatically generated by pandoc from 'Readme.html'.]
+
+Introducing JpegWasher
+======================
+
+Executive Summary
+-----------------
+
+This program makes it easy to remove metadata from the digital images
+you create.
+
+What is “Metadata” and Why Would I Want to Remove It?
+-----------------------------------------------------
+
+You may not realize it, but image files can (and typically do!) contain
+more than just image data. These data can include your camera make,
+model, and serial number; the location where you took the photo; the
+software you used to edit the photo (and what editing steps you did);
+etc.
+
+One of the most powerful uses of photography is to graphically document
+things that the wealthy and powerful might wish to remain concealed. The
+evils of slavery, child labor, poverty, war, and imperialism have all
+been documented photographically, and such photographs have often proved
+instrumental in helping to motivate social change.
+
+Because of the metadata they contain, digital photographs contain data
+which has been used to determine who took them, and in some cases to
+exact retribution against those photographers. JpegWasher makes it easy
+to see and remove the privacy-compromising metadata in your images.
+
+Even if your images are not of such a sensitive nature, that extra data
+takes up space. It is not uncommon for a 100 KiB image to contain 20 KiB
+of metadata in it; if that image is on a web page, that makes for 20 KiB
+of wasted network usage each time the image is sent.
+
+What Makes JpegWasher Different from Other Metadata Editors?
+------------------------------------------------------------
+
+Simply put, it is designed to *safely* remove *unimportant* metadata
+from JPEG files.
+
+There are plenty of general-purpose image metadata editors out there,
+and these tools can be employed to remove unimportant metadata. The
+trouble is, they are not user-friendly: it is up to you, the user, to
+know which metadata are unimportant, and to delete it.
+
+There can be literally *hundreds* of bits of metadata in an image, and
+*not all are safe to remove*. In particular, if you accidentally remove
+color-management metadata, computers that don’t handle images without
+color-management metadata properly (I’m talking about *you*, Apple
+Computer, Inc.) will display colors that often look all “washed-out” or
+otherwise incorrect.
+
+Likewise, there are already plenty of simple-to-use, user-friendly tools
+out there for cleaning the metadata out of image files, but they
+inevitably delete *all* metadata, resulting in files that often display
+improperly. Also of concern, many of these “tools” are actually online
+services. If you’re concerned about your privacy, why would you trust
+the images you’re processing to some unknown third party, who may be
+linked somehow to those who might want to retaliate against you?
+
+I wrote this program because I wanted there to be a quick, easy way to
+scrub images before they even left a photographer’s computer and made
+their way onto the Internet, and for that program to leave vital
+metadata alone, so that the resulting images continue to display
+properly.
+
+JpegWasher Washes More than Just Exif Metadata
+----------------------------------------------
+
+Jpeg is the most common type of metadata, but image files commonly
+contain compromising XMP or IPTC data, particularly if they have been
+edited with a tool like Photoshop. JpegWasher will seamlessly deal with
+these kinds of metadata, too. It tries to do as thorough a job as
+possible of scrubbing possibly compromising metadata from your images.
+
+Using JpegWasher
+----------------
+
+Just double-click on the JpegWasher icon and a main window should open
+up. Either choose the File… Wash from the menu bar, or just drag image
+files onto the main JpegWasher image.
+
+When JpegWasher opens an image, it displays all the metadata it finds.
+That metadata will be run through an internal whitelist, and any data
+whose “key” is not found on the whitelist will be automatically selected
+for deletion.
+
+If you disagree with JpegWasher’s decisions, you can check or uncheck
+the boxes next to the metadata in question. When you are satisfied with
+the choice of metadata to be scrubbed, click “Wash” and all offending
+metadata will be removed. A dialog will pop up showing the metadata
+remaining in the new, washed file.
+
+Important: Run JpegWasher Last!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most image-editing tools insert telltale bits of metadata into the
+output they create. Thus, only way you can create a file with the
+minimum amount of metadata in it is to run JpegWasher as the final step
+in your image preparation.
+
+Washing Non-JPEG Images
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In short: it’s possible, but it is not recommended unless you *really*
+know what you’re doing.
+
+JpegWasher is called JpegWasher for a reason: it is geared to cleaning
+metadata in *JPEG* files. Different types of images use metadata
+differently; metadata that would be extraneous deadwood in a JPEG can be
+critical to interpreting other image file formats correctly.
+JpegWasher’s built-in whitelist is geared to what must be retained when
+washing JPEG images, so *careless use of JpegWasher is likely to damage
+non-JPEG files.* It is for this reason that JpegWasher will warn you if
+you attempt to open and wash a non-JPEG file with it.
+
+Output Files
+------------
+
+JpegWasher never modifies an existing image file. Instead, it creates a
+new file of the same type but with “_washed” appended to its name. For
+example, processing ``foo.jpg`` will create ``foo_washed.jpg``. By
+default, the new file will be created in the same directory as the file
+being washed.
+
+JpegWasher is Configurable
+--------------------------
+
+Both the whitelist and the destination directory for the washed files
+are user-configurable in the Preferences menu.
+
+Configuring the Whitelist
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two kinds of whitelist entries: those that match an entire
+metadata key, and those that match a key prefix. The latter end in an
+asterisk. The whitelist is case-sensitive; i.e. the entry
+``exif.image.colormap`` *will not* match the ``Exif.Image.ColorMap``
+key.
+
+That’s about It
+---------------
+
+JpegWasher does not, and probably never will, do anything but remove
+extraneous metadata from JPEG files.
+
+First, I have no desire to re-invent the wheel. There are already
+excellent open-source tools like Gimp for image editing, and ExifTool
+and Exiv2 for general-purpose metadata editing (in fact, JpegWasher is
+built on top of Exiv2). If you need the functionality of some other
+tool, download and use it!
+
+Second (and more importantly), I want JpegWasher to be simple, and
+therefore easy to learn and easy to use. The more challenging an
+information-security tool is to use, the less likely it is to be used
+frequently, and the more likely it is that compromising information gets
+disclosed.