def sitemap(name = :sitemap, options = {}, &block)
      options = name.kind_of?(Hash) ? name : options
      name = name.kind_of?(String) || name.kind_of?(Symbol) ? name : :sitemap
      config = {controller: :sitemap, url_limit: nil}.merge(options)

      sitemap_raw_route_name = "#{name}_sitemap"
      sitemap_route_name = name_for_action(sitemap_raw_route_name, nil)

      begin

        unless @set.routes.find {|route| route.name.eql?(sitemap_route_name)}

          # create a route for the sitemap using the name that was passed to the sitemap method inside config/routes.
          match %(/#{name}.:format), controller: config[:controller], action: name, via: [:get], as: sitemap_raw_route_name

          # if not found here, then, there must be a real problem.
          # later, i will implement an exception, etc.
          sitemap_route = @set.routes.find {|route| route.name.eql?(sitemap_route_name)}

          # identify the route as a "sitemap" route and build it's full name.
          sitemap_route.is_sitemap = true
          sitemap_route.url_limit = config[:url_limit]
          sitemap_route.sitemap_route_name = sitemap_route_name
          sitemap_route.sitemap_raw_route_name = sitemap_raw_route_name

          # this is how I am faking to always point to the SitemapController
          # regardless of namespace
          sitemap_route.defaults[:controller] = "sitemap"

        end

      rescue ArgumentError => e
        unless e.message.include?("Invalid route name")
          raise e
        end
      end

      # now, find the route again, because, we need to set the following boolean and there might be several
      # calls to sitemap without a block.  if we were to set this boolean in the code above when checking
      # if the route already exists, then, the boolean may never be set.
      sitemap_route = @set.routes.find {|route| route.is_sitemap? && route.name.eql?(sitemap_route_name) }

      # once a sitemap route has been flagged as being defined with a block, then, you should never set it back to false.
      # one of the features is to be able to encapsulate a set of routes within a sitemap as many times as you need.
      # meaning, you might want to wrap five routes at the top of the file, three in the middle, and two at the bottom and
      # have all of them included in the default sitemap.
      # Since all routes within a sitemap block will be marked with the same name, 
      # I am not keeping track of sitemaps being defined with or without a block, so, all I need to know is about one of them.
      unless sitemap_route.sitemap_with_block?
        sitemap_route.sitemap_with_block = true if block_given?
      end

      # DuckMap::SitemapControllerHelpers is a module that is included in SitemapBaseController and contains
      # methods such as sitemap_build, etc.  Define a method to handle the sitemap on DuckMap::SitemapControllerHelpers
      # so that method is visible to the default sitemap controller as well as any custom controllers that inherit from it.
      # originally, I was simply defining the method directly on SitemapBaseController, however, it was causing problems
      # during the development cycle of edit and refresh.  Defining methods here seemed to cure that problem.
      # for example, the default sitemap: /sitemap.xml will define a method named: sitemap
      # on the DuckMap::SitemapControllerHelpers module.
      unless DuckMap::SitemapControllerHelpers.public_method_defined?(name)
        DuckMap::SitemapControllerHelpers.send :define_method, name do

          if DuckMap::Config.attributes[:sitemap_content].eql?(:xml)

            sitemap_build

          end

          respond_to do |format|
            format.xml { render }
          end
        end
      end

      # determine if the sitemap definition included a block.
      if block_given?

        # the starting point would be after the current set of routes and would be length plus one.
        # however, the starting point index is the length of routes, since arrays are zero based.
        start_point = @set.routes.length

        # push a copy of the current filter settings onto an array.
        # this will allow you to specify criteria setting within a sitemap definition without affecting
        # the default settings after the block is finished executing.
        @set.sitemap_filters.push

        # yield to the block.  all standard route code should execute just fine and define namespaces, resource, matches, etc.
        yield

        total = run_filter(sitemap_route.sitemap_route_name, start_point)

        # knock the current filter setting off of the stack
        @set.sitemap_filters.pop

        DuckMap.logger.debug %(total routes filtered: #{@set.routes.length - start_point}  included? #{total})

        @set.routes.each do |route|
          DuckMap.logger.debug %(  Route name: #{route.name}) if route.sitemap_route_name.eql?(sitemap_route.sitemap_route_name)
        end

      end

      return nil
    end
def sitemap(name = :sitemap, options = {}, &block)
      options = name.kind_of?(Hash) ? name : options
      name = name.kind_of?(String) || name.kind_of?(Symbol) ? name : :sitemap
      config = {controller: :sitemap, url_limit: nil}.merge(options)

      sitemap_raw_route_name = "#{name}_sitemap"
      sitemap_route_name = name_for_action(sitemap_raw_route_name, nil)

      begin

        unless @set.routes.find {|route| route.name.eql?(sitemap_route_name)}

          # create a route for the sitemap using the name that was passed to the sitemap method inside config/routes.
          match %(/#{name}.:format), controller: config[:controller], action: name, via: [:get], as: sitemap_raw_route_name

          # if not found here, then, there must be a real problem.
          # later, i will implement an exception, etc.
          sitemap_route = @set.routes.find {|route| route.name.eql?(sitemap_route_name)}

          # identify the route as a "sitemap" route and build it's full name.
          sitemap_route.is_sitemap = true
          sitemap_route.url_limit = config[:url_limit]
          sitemap_route.sitemap_route_name = sitemap_route_name
          sitemap_route.sitemap_raw_route_name = sitemap_raw_route_name

          # this is how I am faking to always point to the SitemapController
          # regardless of namespace
          sitemap_route.defaults[:controller] = "sitemap"

        end

      rescue ArgumentError => e
        unless e.message.include?("Invalid route name")
          raise e
        end
      end

      # now, find the route again, because, we need to set the following boolean and there might be several
      # calls to sitemap without a block.  if we were to set this boolean in the code above when checking
      # if the route already exists, then, the boolean may never be set.
      sitemap_route = @set.routes.find {|route| route.is_sitemap? && route.name.eql?(sitemap_route_name) }

      # once a sitemap route has been flagged as being defined with a block, then, you should never set it back to false.
      # one of the features is to be able to encapsulate a set of routes within a sitemap as many times as you need.
      # meaning, you might want to wrap five routes at the top of the file, three in the middle, and two at the bottom and
      # have all of them included in the default sitemap.
      # Since all routes within a sitemap block will be marked with the same name, 
      # I am not keeping track of sitemaps being defined with or without a block, so, all I need to know is about one of them.
      unless sitemap_route.sitemap_with_block?
        sitemap_route.sitemap_with_block = true if block_given?
      end

      # DuckMap::SitemapControllerHelpers is a module that is included in SitemapBaseController and contains
      # methods such as sitemap_build, etc.  Define a method to handle the sitemap on DuckMap::SitemapControllerHelpers
      # so that method is visible to the default sitemap controller as well as any custom controllers that inherit from it.
      # originally, I was simply defining the method directly on SitemapBaseController, however, it was causing problems
      # during the development cycle of edit and refresh.  Defining methods here seemed to cure that problem.
      # for example, the default sitemap: /sitemap.xml will define a method named: sitemap
      # on the DuckMap::SitemapControllerHelpers module.
      unless DuckMap::SitemapControllerHelpers.public_method_defined?(name)
        DuckMap::SitemapControllerHelpers.send :define_method, name do

          if DuckMap::Config.attributes[:sitemap_content].eql?(:xml)

            sitemap_build

          end

          respond_to do |format|
            format.xml { render }
          end
        end
      end

      # determine if the sitemap definition included a block.
      if block_given?

        # the starting point would be after the current set of routes and would be length plus one.
        # however, the starting point index is the length of routes, since arrays are zero based.
        start_point = @set.routes.length

        # push a copy of the current filter settings onto an array.
        # this will allow you to specify criteria setting within a sitemap definition without affecting
        # the default settings after the block is finished executing.
        @set.sitemap_filters.push

        # yield to the block.  all standard route code should execute just fine and define namespaces, resource, matches, etc.
        yield

        total = run_filter(sitemap_route.sitemap_route_name, start_point)

        # knock the current filter setting off of the stack
        @set.sitemap_filters.pop

        DuckMap.logger.debug %(total routes filtered: #{@set.routes.length - start_point}  included? #{total})

        @set.routes.each do |route|
          DuckMap.logger.debug %(  Route name: #{route.name}) if route.sitemap_route_name.eql?(sitemap_route.sitemap_route_name)
        end

      end

      return nil
    end
Defines a sitemap for a Rails app.


 You can find a few examples and apps at:
 - (http://www.jeffduckett.com/blog/11/defining-rails-3-x-sitemaps-using-duckmap.html)
 - (http://www.jeffduckett.com/blog/12/multiple-sitemap-definitions.html)

 @return [Nil]