Let documents {attach} static files. Fixes #1019.

Until now, making static files end up in the same output directory as an
article that links to them has been difficult, especially when the article's
output path is generated based on metadata. This changeset introduces the
{attach} link syntax, which works like the {filename} syntax, but also
overrides the static file's output path with the directory of the
linking document.

It also clarifies and expands the documentation on linking to internal content.

pelican/tests/test_pelican.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 from __future__ import unicode_literals, print_function
 
+import collections
 import os
 import sys
 from tempfile import mkdtemp
@@ -77,14 +78,17 @@ class TestPelican(LoggedTestCase):
         assert not err, err
 
     def test_order_of_generators(self):
-        # StaticGenerator must run last, so it can find files that were
-        # skipped by the other generators.
+        # StaticGenerator must run last, so it can identify files that
+        # were skipped by the other generators, and so static files can
+        # have their output paths overridden by the {attach} link syntax.
 
         pelican = Pelican(settings=read_settings(path=None))
         generator_classes = pelican.get_generator_classes()
 
         self.assertTrue(generator_classes[-1] is StaticGenerator,
             "StaticGenerator must be the last generator, but it isn't!")
+        self.assertIsInstance(generator_classes, collections.Sequence,
+            "get_generator_classes() must return a Sequence to preserve order")
 
     def test_basic_generation_works(self):
         # when running pelican without settings, it should pick up the default