README.md 4.79 KB
Newer Older
Taddeüs Kroes's avatar
Taddeüs Kroes committed
1 2
About
=====
Taddeüs Kroes's avatar
Taddeüs Kroes committed
3

Taddeüs Kroes's avatar
Taddeüs Kroes committed
4 5 6 7
mincss is an extendible CSS minifier written in OCaml. It features a complete
parser for the CSS3 language, along with type definitions that are consistent
with the official CSS specification and a traversal utility function for use in
transformation passes.
Taddeüs Kroes's avatar
Taddeüs Kroes committed
8 9


10 11 12
Installation
============

13 14 15 16
For now, there is no easy installation option for mincss (yet). An up-to-date
64-bit ELF binary is available for download
[here](http://mincss.tkroes.nl/mincss). You can also build the binary from
source (see *Building mincss* below).
17 18 19 20


Features
========
Taddeüs Kroes's avatar
Taddeüs Kroes committed
21

Taddeüs Kroes's avatar
Taddeüs Kroes committed
22 23
Whitespace compression
----------------------
Taddeüs Kroes's avatar
Taddeüs Kroes committed
24

Taddeüs Kroes's avatar
Taddeüs Kroes committed
25 26 27 28
    a,                                  |  a,.myclass [class~="foo"]>p{color:#fff}
    .myclass [class ~= "foo"] >  p {    |
        color: #fff;                    |
    }                                   |
Taddeüs Kroes's avatar
Taddeüs Kroes committed
29

Taddeüs Kroes's avatar
Taddeüs Kroes committed
30 31
Compression of simple expressions
---------------------------------
Taddeüs Kroes's avatar
Taddeüs Kroes committed
32

Taddeüs Kroes's avatar
Taddeüs Kroes committed
33 34 35
    color: rgb(257, -2, 0);             |  color: red;
    color: rgb(67%, 67.5%, 68%);        |  color: #abacad;
    color: #aaffbb;                     |  color: #afb;
Taddeüs Kroes's avatar
Taddeüs Kroes committed
36 37
    color: white;                       |  color: #fff;
    font-weight: normal;                |  font-weight: 400;
Taddeüs Kroes's avatar
Taddeüs Kroes committed
38

Taddeüs Kroes's avatar
Taddeüs Kroes committed
39 40
Generation of shorthand properties
----------------------------------
Taddeüs Kroes's avatar
Taddeüs Kroes committed
41

Taddeüs Kroes's avatar
Taddeüs Kroes committed
42 43 44 45
    font-weight: normal;                |  font: normal 12px/15px sans-serif;
    font-size: 12px;                    |
    line-height: 15px;                  |
    font-family: sans-serif;            |
Taddeüs Kroes's avatar
Taddeüs Kroes committed
46

Taddeüs Kroes's avatar
Taddeüs Kroes committed
47
Any existing shorthands are first unfolded into their non-shorthand
48 49
counterparts to be folded back later. This means that if `--duplicates` is
enabled, the last value is used for shorthand generation, merging separate :
Taddeüs Kroes's avatar
Taddeüs Kroes committed
50

Taddeüs Kroes's avatar
Taddeüs Kroes committed
51 52
    font: normal 12px/15px sans-serif;  |  font: bold 12px/15px sans-serif;
    font-weight: bold;                  |
Taddeüs Kroes's avatar
Taddeüs Kroes committed
53

Taddeüs Kroes's avatar
Taddeüs Kroes committed
54 55 56 57 58 59 60 61 62 63 64 65
Pruning duplicate declarations
------------------------------

    color: #000;                        |  color: #fff;
    color: #fff;                        |

Note that `!important` annotations are correctly handled:

    color: #eee !important;             |  color: #000 !important;
    color: #000 !important;             |
    color: #fff;                        |

66 67 68 69 70
Sorting declarations
--------------------
The `--sort` command-line option sorts declarations alphabetically. This option
is disabled by default since it does not affect file size.

Taddeüs Kroes's avatar
Taddeüs Kroes committed
71

Taddeüs Kroes's avatar
Taddeüs Kroes committed
72 73 74
Command-line interface
======================
Output of `mincss -h`:
Taddeüs Kroes's avatar
Taddeüs Kroes committed
75

76
    Usage: mincss [<options>] [<file> ...]
Taddeüs Kroes's avatar
Taddeüs Kroes committed
77

Taddeüs Kroes's avatar
Taddeüs Kroes committed
78
    Generic options:
79 80 81 82 83
    -h, --help        Show this help message
    -v, --verbose     Verbose mode: show compression rate
    -o <file>
    --output=<file>   Output file (defaults to stdout)
    <file> ...        Input files (defaults to stdin or "-")
Taddeüs Kroes's avatar
Taddeüs Kroes committed
84

85
    Optimization flags (default is -w -c -s -d):
86 87 88 89 90
    -w, --whitespace  Eliminate unnecessary whitespaces (has the greatest effect, omit for pretty-printing)
    -c, --simple      Shorten colors, font weights and nth-child
    -s, --shorthands  Generate shorthand properties
    -d, --duplicates  Prune duplicate properties (WARNING: may affect cross-browser hacks)
    -p, --pretty      Shorthand for -c -s -d
Taddeüs Kroes's avatar
Taddeüs Kroes committed
91

Taddeüs Kroes's avatar
Taddeüs Kroes committed
92
    Formatting options:
93 94
    -r, --sort        Sort declarations in each ruleset (always on when --shorthands is enabled)
    -e, --echo        Just parse and pretty-print, no optimizations
Taddeüs Kroes's avatar
Taddeüs Kroes committed
95 96 97 98 99


Building mincss
===============

100 101 102
Dependencies are [OCaml](https://ocaml.org/docs/install.html) 4.02.0,
[menhir](http://cristal.inria.fr/~fpottier/menhir/) and
[Getopt](https://forge.ocamlcore.org/projects/ocaml-getopt/).
Taddeüs Kroes's avatar
Taddeüs Kroes committed
103

Taddeüs Kroes's avatar
Taddeüs Kroes committed
104
Bootstrapping on a Debian system can be done as follows:
Taddeüs Kroes's avatar
Taddeüs Kroes committed
105

106
    $ sudo apt-get install ocaml menhir libgetopt-ocaml-dev git
Taddeüs Kroes's avatar
Taddeüs Kroes committed
107 108 109 110
    $ git clone git@github.com:taddeus/mincss.git
    $ cd mincss
    $ make
    $ ./mincss --help
111

112 113 114 115 116 117 118 119
I prefer to use [Opam](https://opam.ocaml.org/) myself because it offers more
flexibility:

    $ sudo apt-get install opam
    $ opam init
    $ eval `opam config env`
    $ opam switch 4.02.0
    $ opam update
120
    $ opam install menhir getopt
121

122 123 124 125

TODO / bugs
===========

Taddeüs Kroes's avatar
Taddeüs Kroes committed
126 127 128 129 130
- `border` shorthand generation produces out-of-order results when
  direction-specific declarations follow a generic border declaration. This
  produces inequivalent CSS, and could be fixed by unfolding each generic
  border declaration into four direction-specific ones, and sybsequently
  generating the shortest possible representation of the resulting box model.
Taddeüs Kroes's avatar
Taddeüs Kroes committed
131 132 133
  Edit: a better/easier solution is to generate shorthand properties at the
  index of the first merged declaration. This might not work in all cases but
  it is better than putting everything at the end.
Taddeus Kroes's avatar
Taddeus Kroes committed
134 135
- `border:none` could be `border:0`, or in general any shorthand that has both
  a `style` and `width` property should be transformed from `none` into `0`.
136
- Automated test suite: auto-diff css files and expected minified versions.
137
- `mincss -s test/duplicates.css` gets stuck in an infinite loop.