adds a preamble to the guides generator, documents what it does and the environment variables it supports

railties/guides/rails_guides/generator.rb

@@ -1,3 +1,50 @@
+# ---------------------------------------------------------------------------
+#
+# This script generates the guides. It can be invoked either directly or via the
+# generate_guides rake task within the railties directory.
+#
+# Guides are taken from the source directory, and the resulting HTML goes into the
+# output directory. Assets are stored under files, and copied to output/files as
+# part of the generation process.
+#
+# Some arguments may be passed via environment variables:
+#
+#   WARN_BROKEN_LINKS
+#     Internal references (anchors) are checked. If a reference is broken
+#     levenshtein distance is used to suggest an existing one. This is useful
+#     since IDs are generated by Textile from titles and thus rewordings alter
+#     them.
+#
+#   WARN_DUPLICATE_HEADERS
+#     Warns about duplicate IDs in headers. Please do resolve them, if any,
+#     so guides are valid XHTML.
+#
+#     This check only happens if WARN_BROKEN_LINKS is also active.
+#
+#   EDGE_GUIDES
+#     Set to "1" to indicate edge guides are generated.
+#
+#   ALL
+#    Generate all guides.
+
+#   ONLY
+#     If you want to generate only one or a set of guides.
+#     Prefixes are enough:
+#
+#       # generates only association_basics.html
+#       ONLY=assoc ruby rails_guides.rb
+#
+#     Separate many using commas:
+#
+#       # generates only 
+#       ONLY=assoc,migrations ruby rails_guides.rb
+#
+#     Note that if you are working on a guide, generation will
+#     by default process only that one, so ONLY is rarely used
+#     nowadays.
+#
+# ---------------------------------------------------------------------------
+
 require 'set'
 require 'fileutils'