Permalink
Browse files

Added FAQs and related projects to the README

  • Loading branch information...
1 parent b747880 commit b43a37321fc56c27a13fc77b16b500b0d2eefcbe @JamieMason committed Jan 23, 2014
Showing with 416 additions and 48 deletions.
  1. +2 −0 CONTRIBUTING.md
  2. +213 −32 README.md
  3. +201 −16 src/README.md
View
2 CONTRIBUTING.md
@@ -2,6 +2,8 @@
## Creating issues
+Please first consult the README, which has a list of FAQs.
+
Please include the version number of ImageOptim-CLI you're using (`imageOptim --version`) and if applicable to your issue the version numbers of ImageOptim, ImageAlpha and JPEGmini.
## Contributing code
View
245 README.md
@@ -1,48 +1,91 @@
# ImageOptim-CLI
-Automates [ImageOptim](http://imageoptim.com), [ImageAlpha](http://pngmini.com), and [JPEGmini for Mac](http://jpegmini.com/mac) to make batch optimisation of images part of your automated build process.
+> Automates [ImageOptim](http://imageoptim.com), [ImageAlpha](http://pngmini.com), and
+> [JPEGmini for Mac](http://jpegmini.com/mac) to make batch optimisation of images part of your
+> automated build process.
+
+While other image optimization tools are available from the command line, ImageOptim-CLI exists
+because the [current benchmarks](http://jamiemason.github.io/ImageOptim-CLI/) suggest that
+ImageOptim, ImageAlpha and JPEGmini currently outperform those alternatives over lossless and
+lossy optimizations.
+
+Check out this short [video demo of ImageOptim-CLI](https://www.youtube.com/watch?v=HGBounRIzSs) to
+see how it works.
+
+
+
+
+## Contents
+ [Installation](#installation)
-+ [Performance](#performance)
-+ [Grunt Plugin](#grunt-plugin)
-+ [Demo](#demo)
+ + [Manual Installation](#manual-installation)
++ [Usage](#usage)
+ [Examples](#examples)
+ [Optimise a directory of images](#optimise-a-directory-of-images)
+ [Optimise a filtered set of images](#optimise-a-filtered-set-of-images)
+ [Passing additional options](#passing-additional-options)
+ [Adding to git pre-commit hook](#adding-to-git-pre-commit-hook)
-+ [Usage](#usage)
++ [Related projects](#related-projects)
+ + [Grunt plugin](#grunt-plugin)
+ + [Comparison of image optimization tools](#comparison-of-image-optimization-tools)
+ + [Article for Smashing Magazine](#article-for-smashing-magazine)
+ + [Alfred workflow](#alfred-workflow)
+ + [Gulp Plugin](#gulp-plugin)
++ [FAQs](#faqs)
+ + [General](#general)
+ + [ImageOptim](#imageoptim)
+ + [ImageAlpha](#imagealpha)
+ + [JPEGmini](#jpegmini)
+ + [Windows and Linux](#windows-and-linux)
+
+
+
## Installation
+ImageOptim-CLI is written in Shell and AppleScript, you don't _need_ Node.js to run it.
+[npm](https://npmjs.org/) is suggested because it makes installation very convenient.
+
$ npm install -g imageoptim-cli
-ImageOptim-CLI is written in Shell and AppleScript, so you don't _need_ Node.js or npm. You can install manually by downloading the latest zip then adding ImageOptim-CLI to your [$PATH](https://en.wikipedia.org/wiki/PATH_\(variable\)).
+
+### Manual Installation
+
+You can install manually by downloading the latest zip then adding ImageOptim-CLI to your
+[$PATH](https://en.wikipedia.org/wiki/PATH_\(variable\)).
$ curl --output imageoptim-cli.zip https://codeload.github.com/JamieMason/ImageOptim-CLI/zip/1.7.10
$ unzip imageoptim-cli.zip
$ export PATH=$PATH:imageoptim-cli/bin
-## Performance
+> Saving somewhere in your home directory such as `~/imageoptim-cli` is recommended, but not
+essential. Saving to `/Applications` is **not** recommended, do not do this.
-See [how ImageOptim performs compared to other image optimisation tools](http://jamiemason.github.io/ImageOptim-CLI/).
-[![](http://jamiemason.github.io/ImageOptim-CLI/static/image-optimisation-comparison.png)](http://jamiemason.github.io/ImageOptim-CLI/)
-## Grunt Plugin
-The ImageOptim-CLI [Grunt](http://gruntjs.com) plugin is [grunt-imageoptim](https://github.com/JamieMason/grunt-imageoptim).
+## Usage
+ Usage: imageOptim [options]
+
+ Options:
+
+ -d, --directory directory of images to process
+ -a, --image-alpha pre-process PNGs with ImageAlpha.app *
+ -j, --jpeg-mini pre-process JPGs with JPEGmini.app **
+ -q, --quit quit all apps when complete
+ -h, --help display this usage information
+ -e, --examples display some example commands and uses
+ -v, --version display the version number
+
+ * http://pngmini.com
+ ** https://itunes.apple.com/us/app/jpegmini/id498944723
+
-## Alfred Workflow
-The ImageOptim-CLI Workflow for Alfred app is [alfred-image-optim-workflow](https://github.com/ramiroaraujo/alfred-image-optim-workflow)
-## Demo
-There's a short [video demo](https://www.youtube.com/watch?v=HGBounRIzSs) to give you an idea of how it works.
## Examples
-
### Optimise a directory of images
This command will optimise all image files in your Awesome project.
@@ -74,20 +117,158 @@ aren't images will be ignored.
git diff --cached --name-only --diff-filter=ACM | imageOptim # [options]
-## Usage
- Usage: imageOptim [options]
-
- Options:
-
- -d, --directory directory of images to process
- -a, --image-alpha pre-process PNGs with ImageAlpha.app *
- -j, --jpeg-mini pre-process JPGs with JPEGmini.app **
- -q, --quit quit all apps when complete
- -h, --help display this usage information
- -e, --examples display some example commands and uses
- -v, --version display the version number
-
- * http://pngmini.com
- ** https://itunes.apple.com/us/app/jpegmini/id498944723
-
+
+
+
+
+
+## Related Projects
+
+
+### Grunt Plugin
+
+The ImageOptim-CLI [Grunt](http://gruntjs.com) plugin
+is [grunt-imageoptim](https://github.com/JamieMason/grunt-imageoptim).
+
+
+### Comparison of image optimization tools
+
+ImageOptim-CLI features in this comparison of the [performance of image optimisation
+tools](http://jamiemason.github.io/ImageOptim-CLI/) alongside Kraken.io, CodeKit,
+grunt-contrib-imagemin, Smush.it, and TinyPNG.
+
+
+### Article for Smashing Magazine
+
+[How Optimized Are Your Images? Meet ImageOptim-CLI, a Batch Compression
+Tool](http://www.smashingmagazine.com/2013/12/17/imageoptim-cli-batch-compression-tool/)
+
+
+### Alfred Workflow
+
+The ImageOptim-CLI Workflow for Alfred app
+is [alfred-image-optim-workflow](https://github.com/ramiroaraujo/alfred-image-optim-workflow)
+
+
+### Gulp Plugin
+
+The ImageOptim-CLI [Gulp](http://gulpjs.com) plugin is
+[gulp-imageoptim](https://github.com/JamieMason/gulp-imageoptim).
+
+
+
+
+## FAQs
+
+
+
+
+
+### General
+
+#### Do ImageOptim, ImageAlpha, or JPEGmini come bundled with the ImageOptim-CLI installation?
+
+You will need to install these applications separately.
+
+#### Do I have to pay to use ImageOptim-CLI?
+
+The CLI, ImageOptim and ImageAlpha are all free. JPEGmini is a paid-for product but you can use
+ImageOptim-CLI and choose not to run JPEGmini.
+
+#### Why are shorthand options supplied in the format `imageoptim -a -j -q` instead of the more common `imageoptim -ajq`?
+
+This was an early mistake which now needs supporting for backwards compatibility.
+[Issue 21](https://github.com/JamieMason/ImageOptim-CLI/issues/21) is open to add support for
+the `-ajq` format as well as the current format.
+
+#### The WebP image format looks promising, can you get ImageOptim-CLI to convert images to it?
+
+WebP looks great and may well overtake the formats handled by ImageOptim-CLI, but converting images
+to WebP is outside ImageOptim-CLI's chosen remit.
+
+#### Can you get ImageOptim-CLI to skip images it has already processed, if they haven't changed?
+
+JPEGmini does this today, but for ImageOptim and ImageAlpha I feel a feature like this belongs
+in those applications rather than this automator.
+
+
+
+
+### ImageOptim
+
+
+#### ImageOptim got my fans ackin' straight up Cray Cray.
+
+Optimising images is a pretty intensive process, so instead of optimising one image at a time (which
+would take forever) — ImageOptim optimises many images at the same time until all of them are done.
+
+A side effect of this is that the fans come on at full power to keep your machine cool while it's
+maxed out.
+
+
+
+
+
+### ImageAlpha
+
+#### I don't think ImageAlpha is running, I can't see anything.
+
+ImageOptim-CLI uses ImageAlpha's internal installation of [pngquant](http://pngquant.org) so it's
+normal that nothing is shown on screen.
+
+It's also possible that if you look in the [Activity Monitor](http://support.apple.com/kb/HT5890)
+you will not see `pngquant` displayed but it _is_ being run. In my experience it's only when you
+run ImageOptim-CLI on a very large number of PNGs that you have enough time to spot it.
+
+#### Can I configure ImageAlpha's settings using ImageOptim-CLI?
+
+ImageOptim-CLI is intended to be a simple, convenient, powerful, general-purpose image optimisation
+tool. If your needs have outgrown ImageOptim-CLI it's better to
+run [pngquant](http://pngquant.org) separately, passing whatever custom settings you need.
+
+
+
+
+
+### JPEGmini
+
+#### Can I use ImageOptim-CLI with JPEGmini Lite, the free version of JPEGmini?
+
+Not currently, the full version of JPEGmini already has some subtle differences and JPEGmini Lite
+causes further fragmentation. It is possible but not a priority, as the free version has a limit of
+processing 30 images per day anyway.
+
+#### I upgraded from JPEGmini Lite to JPEGmini but ImageOptim-CLI still says JPEGmini is not installed.
+
+Performing the in-app upgrade leaves the app named as jpegmini-lite, so ImageOptim-CLI can't
+determine whether it's the free or full version. It is better to instead buy [the full version of
+JPEGmini](https://itunes.apple.com/us/app/jpegmini/id498944723) separately.
+
+#### ImageOptim-CLI says “To automate JPEGmini we need to enable GUI Scripting”, how do I do that?
+
+See this tutorial on [how to manage Accessibility preferences
+and GUI Scripting](http://www.macosautomation.com/mavericks/guiscripting/index.html). In the case
+of OS X Mavericks, you will want to add the Applications JPEGmini and Terminal (or equivalent such
+as iTerm).
+
+
+
+
+
+### Windows and Linux
+
+#### Can I use ImageOptim-CLI on Windows or Linux?
+
+ImageOptim-CLI is responsible for automating 3 OS X applications so is inherently bound to OS X for
+that reason.
+
+#### Are there any plans for ImageOptim-CLI to support Windows or Linux?
+
+It would first require ImageOptim, ImageAlpha, and JPEGmini to be available for those platforms.
+
+#### I don't have OS X, can you recommend an alternative to ImageOptim-CLI?
+
+[@addyosmani](https://github.com/addyosmani) wrote a really thorough article on [tools for
+image optimization](http://addyosmani.com/blog/image-optimization-tools/) which discusses a wide
+range of options in great detail.
View
217 src/README.md
@@ -1,46 +1,231 @@
# ImageOptim-CLI
-Automates [ImageOptim](http://imageoptim.com), [ImageAlpha](http://pngmini.com), and [JPEGmini for Mac](http://jpegmini.com/mac) to make batch optimisation of images part of your automated build process.
+> Automates [ImageOptim](http://imageoptim.com), [ImageAlpha](http://pngmini.com), and
+> [JPEGmini for Mac](http://jpegmini.com/mac) to make batch optimisation of images part of your
+> automated build process.
+
+While other image optimization tools are available from the command line, ImageOptim-CLI exists
+because the [current benchmarks](http://jamiemason.github.io/ImageOptim-CLI/) suggest that
+ImageOptim, ImageAlpha and JPEGmini currently outperform those alternatives over lossless and
+lossy optimizations.
+
+Check out this short [video demo of ImageOptim-CLI](https://www.youtube.com/watch?v=HGBounRIzSs) to
+see how it works.
+
+
+
+
+## Contents
+ [Installation](#installation)
-+ [Performance](#performance)
-+ [Grunt Plugin](#grunt-plugin)
-+ [Demo](#demo)
+ + [Manual Installation](#manual-installation)
++ [Usage](#usage)
+ [Examples](#examples)
+ [Optimise a directory of images](#optimise-a-directory-of-images)
+ [Optimise a filtered set of images](#optimise-a-filtered-set-of-images)
+ [Passing additional options](#passing-additional-options)
+ [Adding to git pre-commit hook](#adding-to-git-pre-commit-hook)
-+ [Usage](#usage)
++ [Related projects](#related-projects)
+ + [Grunt plugin](#grunt-plugin)
+ + [Comparison of image optimization tools](#comparison-of-image-optimization-tools)
+ + [Article for Smashing Magazine](#article-for-smashing-magazine)
+ + [Alfred workflow](#alfred-workflow)
+ + [Gulp Plugin](#gulp-plugin)
++ [FAQs](#faqs)
+ + [General](#general)
+ + [ImageOptim](#imageoptim)
+ + [ImageAlpha](#imagealpha)
+ + [JPEGmini](#jpegmini)
+ + [Windows and Linux](#windows-and-linux)
+
+
+
## Installation
+ImageOptim-CLI is written in Shell and AppleScript, you don't _need_ Node.js to run it.
+[npm](https://npmjs.org/) is suggested because it makes installation very convenient.
+
$ npm install -g imageoptim-cli
-ImageOptim-CLI is written in Shell and AppleScript, so you don't _need_ Node.js or npm. You can install manually by downloading the latest zip then adding ImageOptim-CLI to your [$PATH](https://en.wikipedia.org/wiki/PATH_\(variable\)).
+
+### Manual Installation
+
+You can install manually by downloading the latest zip then adding ImageOptim-CLI to your
+[$PATH](https://en.wikipedia.org/wiki/PATH_\(variable\)).
$ curl --output imageoptim-cli.zip https://codeload.github.com/JamieMason/ImageOptim-CLI/zip/{{version}}
$ unzip imageoptim-cli.zip
$ export PATH=$PATH:imageoptim-cli/bin
-## Performance
+> Saving somewhere in your home directory such as `~/imageoptim-cli` is recommended, but not
+essential. Saving to `/Applications` is **not** recommended, do not do this.
+
+
-See [how ImageOptim performs compared to other image optimisation tools](http://jamiemason.github.io/ImageOptim-CLI/).
-[![](http://jamiemason.github.io/ImageOptim-CLI/static/image-optimisation-comparison.png)](http://jamiemason.github.io/ImageOptim-CLI/)
+## Usage
+{{usage}}
-## Grunt Plugin
-The ImageOptim-CLI [Grunt](http://gruntjs.com) plugin is [grunt-imageoptim](https://github.com/JamieMason/grunt-imageoptim).
-## Demo
-There's a short [video demo](https://www.youtube.com/watch?v=HGBounRIzSs) to give you an idea of how it works.
## Examples
-
{{examples}}
-## Usage
-{{usage}}
+
+
+
+
+
+## Related Projects
+
+
+### Grunt Plugin
+
+The ImageOptim-CLI [Grunt](http://gruntjs.com) plugin
+is [grunt-imageoptim](https://github.com/JamieMason/grunt-imageoptim).
+
+
+### Comparison of image optimization tools
+
+ImageOptim-CLI features in this comparison of the [performance of image optimisation
+tools](http://jamiemason.github.io/ImageOptim-CLI/) alongside Kraken.io, CodeKit,
+grunt-contrib-imagemin, Smush.it, and TinyPNG.
+
+
+### Article for Smashing Magazine
+
+[How Optimized Are Your Images? Meet ImageOptim-CLI, a Batch Compression
+Tool](http://www.smashingmagazine.com/2013/12/17/imageoptim-cli-batch-compression-tool/)
+
+
+### Alfred Workflow
+
+The ImageOptim-CLI Workflow for Alfred app
+is [alfred-image-optim-workflow](https://github.com/ramiroaraujo/alfred-image-optim-workflow)
+
+
+### Gulp Plugin
+
+The ImageOptim-CLI [Gulp](http://gulpjs.com) plugin is
+[gulp-imageoptim](https://github.com/JamieMason/gulp-imageoptim).
+
+
+
+
+## FAQs
+
+
+
+
+
+### General
+
+#### Do ImageOptim, ImageAlpha, or JPEGmini come bundled with the ImageOptim-CLI installation?
+
+You will need to install these applications separately.
+
+#### Do I have to pay to use ImageOptim-CLI?
+
+The CLI, ImageOptim and ImageAlpha are all free. JPEGmini is a paid-for product but you can use
+ImageOptim-CLI and choose not to run JPEGmini.
+
+#### Why are shorthand options supplied in the format `imageoptim -a -j -q` instead of the more common `imageoptim -ajq`?
+
+This was an early mistake which now needs supporting for backwards compatibility.
+[Issue 21](https://github.com/JamieMason/ImageOptim-CLI/issues/21) is open to add support for
+the `-ajq` format as well as the current format.
+
+#### The WebP image format looks promising, can you get ImageOptim-CLI to convert images to it?
+
+WebP looks great and may well overtake the formats handled by ImageOptim-CLI, but converting images
+to WebP is outside ImageOptim-CLI's chosen remit.
+
+#### Can you get ImageOptim-CLI to skip images it has already processed, if they haven't changed?
+
+JPEGmini does this today, but for ImageOptim and ImageAlpha I feel a feature like this belongs
+in those applications rather than this automator.
+
+
+
+
+### ImageOptim
+
+
+#### ImageOptim got my fans ackin' straight up Cray Cray.
+
+Optimising images is a pretty intensive process, so instead of optimising one image at a time (which
+would take forever) — ImageOptim optimises many images at the same time until all of them are done.
+
+A side effect of this is that the fans come on at full power to keep your machine cool while it's
+maxed out.
+
+
+
+
+
+### ImageAlpha
+
+#### I don't think ImageAlpha is running, I can't see anything.
+
+ImageOptim-CLI uses ImageAlpha's internal installation of [pngquant](http://pngquant.org) so it's
+normal that nothing is shown on screen.
+
+It's also possible that if you look in the [Activity Monitor](http://support.apple.com/kb/HT5890)
+you will not see `pngquant` displayed but it _is_ being run. In my experience it's only when you
+run ImageOptim-CLI on a very large number of PNGs that you have enough time to spot it.
+
+#### Can I configure ImageAlpha's settings using ImageOptim-CLI?
+
+ImageOptim-CLI is intended to be a simple, convenient, powerful, general-purpose image optimisation
+tool. If your needs have outgrown ImageOptim-CLI it's better to
+run [pngquant](http://pngquant.org) separately, passing whatever custom settings you need.
+
+
+
+
+
+### JPEGmini
+
+#### Can I use ImageOptim-CLI with JPEGmini Lite, the free version of JPEGmini?
+
+Not currently, the full version of JPEGmini already has some subtle differences and JPEGmini Lite
+causes further fragmentation. It is possible but not a priority, as the free version has a limit of
+processing 30 images per day anyway.
+
+#### I upgraded from JPEGmini Lite to JPEGmini but ImageOptim-CLI still says JPEGmini is not installed.
+
+Performing the in-app upgrade leaves the app named as jpegmini-lite, so ImageOptim-CLI can't
+determine whether it's the free or full version. It is better to instead buy [the full version of
+JPEGmini](https://itunes.apple.com/us/app/jpegmini/id498944723) separately.
+
+#### ImageOptim-CLI says “To automate JPEGmini we need to enable GUI Scripting”, how do I do that?
+
+See this tutorial on [how to manage Accessibility preferences
+and GUI Scripting](http://www.macosautomation.com/mavericks/guiscripting/index.html). In the case
+of OS X Mavericks, you will want to add the Applications JPEGmini and Terminal (or equivalent such
+as iTerm).
+
+
+
+
+
+### Windows and Linux
+
+#### Can I use ImageOptim-CLI on Windows or Linux?
+
+ImageOptim-CLI is responsible for automating 3 OS X applications so is inherently bound to OS X for
+that reason.
+
+#### Are there any plans for ImageOptim-CLI to support Windows or Linux?
+
+It would first require ImageOptim, ImageAlpha, and JPEGmini to be available for those platforms.
+
+#### I don't have OS X, can you recommend an alternative to ImageOptim-CLI?
+
+[@addyosmani](https://github.com/addyosmani) wrote a really thorough article on [tools for
+image optimization](http://addyosmani.com/blog/image-optimization-tools/) which discusses a wide
+range of options in great detail.

0 comments on commit b43a373

Please sign in to comment.