sanity check arguments in guides generation collapsed into a single W…

…ARNINGS flag, EDGE_GUIDES renamed to EDGE to be coherent with the rest, preamble revised

railties/guides/rails_guides/generator.rb

@@ -9,27 +9,23 @@
 #
 # 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.
+#   WARNINGS
+#     If you are writing a guide, please work always with WARNINGS=1. Users can
+#     generate the guides, and thus this flag is off by default.
 #
-#   WARN_DUPLICATE_HEADERS
-#     Warns about duplicate IDs in headers. Please do resolve them, if any,
-#     so guides are valid XHTML.
+#     Internal links (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 headers and thus edits alter them.
 #
-#     This check only happens if WARN_BROKEN_LINKS is also active.
-#
-#   EDGE_GUIDES
-#     Set to "1" to indicate edge guides are generated.
+#     Also detects duplicated IDs. They happen if there are headers with the same
+#     text. Please do resolve them, if any, so guides are valid XHTML.
 #
 #   ALL
-#    Generate all guides.
-
+#    Set to "1" to force the generation of all guides.
+#
 #   ONLY
-#     If you want to generate only one or a set of guides.
-#     Prefixes are enough:
+#     Use 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
@@ -39,9 +35,12 @@
 #       # 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.
+#     Note that if you are working on a guide generation will by default process
+#     only that one, so ONLY is rarely used nowadays.
+#
+#   EDGE
+#     Set to "1" to indicate generated guides should be marked as edge. This
+#     inserts a badge and changes the preamble of the home page.
 #
 # ---------------------------------------------------------------------------
 
@@ -85,7 +84,7 @@ def create_output_dir_if_needed
     end
 
     def set_edge
-      @edge = ENV['EDGE_GUIDES'] == '1'
+      @edge = ENV['EDGE'] == '1'
     end
 
     def generate_guides
@@ -97,11 +96,11 @@ def generate_guides
 
     def guides_to_generate
       guides = Dir.entries(source_dir).grep(GUIDES_RE)
-      ENV.key?("ONLY") ? select_only(guides) : guides
+      ENV.key?('ONLY') ? select_only(guides) : guides
     end
 
     def select_only(guides)
-      prefixes = ENV["ONLY"].split(",").map(&:strip)
+      prefixes = ENV['ONLY'].split(",").map(&:strip)
       guides.select do |guide|
         prefixes.any? {|p| guide.start_with?(p)}
       end
@@ -138,7 +137,7 @@ def generate_guide(guide, output_file)
 
           result = view.render(:layout => 'layout', :text => textile(body))
 
-          warn_about_broken_links(result) if ENV.key?("WARN_BROKEN_LINKS")
+          warn_about_broken_links(result) if ENV['WARNINGS'] == '1'
         end
 
         f.write result
@@ -229,7 +228,7 @@ def extract_anchors(html)
       anchors = Set.new
       html.scan(/<h\d\s+id="([^"]+)/).flatten.each do |anchor|
         if anchors.member?(anchor)
-          puts "*** DUPLICATE HEADER ID: #{anchor}, please consider rewording" if ENV.key?("WARN_DUPLICATE_HEADERS")
+          puts "*** DUPLICATE HEADER ID: #{anchor}, please consider rewording"
         else
           anchors << anchor
         end