[Bleeding] Added support for custom index help topics in help.yml. Addresses BUKKIT-1263

src/main/java/org/bukkit/craftbukkit/help/CustomIndexHelpTopic.java

@@ -0,0 +1,40 @@
+package org.bukkit.craftbukkit.help;
+
+import org.bukkit.command.CommandSender;
+import org.bukkit.help.HelpMap;
+import org.bukkit.help.HelpTopic;
+import org.bukkit.help.IndexHelpTopic;
+
+import java.util.HashSet;
+import java.util.LinkedList;
+import java.util.List;
+
+/**
+ */
+public class CustomIndexHelpTopic extends IndexHelpTopic {
+    private List<String> futureTopics;
+    private HelpMap helpMap;
+    
+    public CustomIndexHelpTopic(HelpMap helpMap, String name, String shortText, String permission, List<String> futureTopics, String preamble) {
+        super(name, shortText, permission, new HashSet<HelpTopic>(), preamble);
+        this.helpMap = helpMap;
+        this.futureTopics = futureTopics;
+    }
+
+    @Override
+    public String getFullText(CommandSender sender) {
+        if (futureTopics != null) {
+            List<HelpTopic> topics = new LinkedList<HelpTopic>();
+            for (String futureTopic : futureTopics) {
+                HelpTopic topic = helpMap.getHelpTopic(futureTopic);
+                if (topic != null) {
+                    topics.add(topic);
+                }
+            }
+            setTopicsCollection(topics);
+            futureTopics = null;
+        }
+        
+        return super.getFullText(sender);
+    }
+}

src/main/java/org/bukkit/craftbukkit/help/HelpYamlReader.java

@@ -19,8 +19,11 @@ public class HelpYamlReader {
 
     private YamlConfiguration helpYaml;
     private final char ALT_COLOR_CODE = '&';
+    private final Server server;
 
     public HelpYamlReader(Server server) {
+        this.server = server;
+        
         File helpYamlFile = new File("help.yml");
         YamlConfiguration defaultConfig = YamlConfiguration.loadConfiguration(getClass().getClassLoader().getResourceAsStream("configurations/help.yml"));
 
@@ -44,6 +47,7 @@ public class HelpYamlReader {
 
     /**
      * Extracts a list of all general help topics from help.yml
+     *
      * @return A list of general topics.
      */
     public List<HelpTopic> getGeneralTopics() {
@@ -61,9 +65,31 @@ public class HelpYamlReader {
         return topics;
     }
 
+    /**
+     * Extracts a list of all index topics from help.yml
+     *
+     * @return A list of index topics.
+     */
+    public List<HelpTopic> getIndexTopics() {
+        List<HelpTopic> topics = new LinkedList<HelpTopic>();
+        ConfigurationSection indexTopics = helpYaml.getConfigurationSection("index-topics");
+        if (indexTopics != null) {
+            for (String topicName : indexTopics.getKeys(false)) {
+                ConfigurationSection section = indexTopics.getConfigurationSection(topicName);
+                String shortText = ChatColor.translateAlternateColorCodes(ALT_COLOR_CODE, section.getString("shortText"));
+                String preamble = ChatColor.translateAlternateColorCodes(ALT_COLOR_CODE, section.getString("preamble"));
+                String permission = ChatColor.translateAlternateColorCodes(ALT_COLOR_CODE, section.getString("permission"));
+                List<String> commands = section.getStringList("commands");
+                topics.add(new CustomIndexHelpTopic(server.getHelpMap(), topicName, shortText, permission, commands, preamble));
+            }
+        }
+        return topics;
+    }
+
     /**
      * Extracts a list of topic amendments from help.yml
-     * @return A list of amendments
+     *
+     * @return A list of amendments.
      */
     public List<HelpTopicAmendment> getTopicAmendments() {
         List<HelpTopicAmendment> amendments = new LinkedList<HelpTopicAmendment>();

src/main/java/org/bukkit/craftbukkit/help/SimpleHelpMap.java

@@ -17,16 +17,15 @@ import java.util.*;
  */
 public class SimpleHelpMap implements HelpMap {
 
-    private final HelpTopic defaultTopic;
+    private HelpTopic defaultTopic;
     private final Map<String, HelpTopic> helpTopics;
-    private final Set<HelpTopic> pluginIndexes;
     private final Map<Class, HelpTopicFactory<Command>> topicFactoryMap;
     private final CraftServer server;
     private HelpYamlReader yaml;
 
+    @SuppressWarnings("unchecked")
     public SimpleHelpMap(CraftServer server) {
         this.helpTopics = new TreeMap<String, HelpTopic>(HelpTopicComparator.topicNameComparatorInstance()); // Using a TreeMap for its explicit sorting on key
-        this.pluginIndexes = new TreeSet<HelpTopic>(HelpTopicComparator.helpTopicComparatorInstance());
         this.topicFactoryMap = new HashMap<Class, HelpTopicFactory<Command>>();
         this.server = server;
         this.yaml = new HelpYamlReader(server);
@@ -36,7 +35,7 @@ public class SimpleHelpMap implements HelpMap {
             indexFilter = Predicates.and(indexFilter, Predicates.not(new IsCommandTopicPredicate()));
         }
 
-        this.defaultTopic = new IndexHelpTopic("Index", null, null, Collections2.filter(helpTopics.values(), indexFilter));
+        this.defaultTopic = new IndexHelpTopic("Index", null, null, Collections2.filter(helpTopics.values(), indexFilter), "Use /help [n] to get page n of help.");
 
         registerHelpTopicFactory(MultipleCommandAlias.class, new MultipleCommandAliasHelpTopicFactory());
     }
@@ -82,6 +81,15 @@ public class SimpleHelpMap implements HelpMap {
         for (HelpTopic topic : yaml.getGeneralTopics()) {
             addTopic(topic);
         }
+        
+        // Initialize index help topics from the help.yml file
+        for (HelpTopic topic : yaml.getIndexTopics()) {
+            if (topic.getName().equals("Default")) {
+                defaultTopic = topic;
+            } else {
+                addTopic(topic);
+            }
+        }
     }
 
     /**
@@ -146,7 +154,7 @@ public class SimpleHelpMap implements HelpMap {
         fillPluginIndexes(pluginIndexes, server.getCommandMap().getFallbackCommands());
 
         for (Map.Entry<String, Set<HelpTopic>> entry : pluginIndexes.entrySet()) {
-            addTopic(new IndexHelpTopic(entry.getKey(), "All commands for " + entry.getKey(), null, entry.getValue(), ChatColor.GRAY + "Below is a list of all " + entry.getKey() + " commands:"));
+            addTopic(new IndexHelpTopic(entry.getKey(), "All commands for " + entry.getKey(), null, entry.getValue(), "Below is a list of all " + entry.getKey() + " commands:"));
         }
 
         // Amend help topics from the help.yml file

src/main/resources/configurations/help.yml

@@ -5,19 +5,21 @@
 # your server or override the help pages of existing plugin commands.
 # 
 # This file is divided up into the following parts:
-# -- general-topics: lists admin defined topics
+# -- general-topics: lists admin defined help topics
+# -- index-topics:   lists admin defined index topics
 # -- amend-topics:   lists topic amendments to apply to existing help topics
 # -- ignore-plugins: lists any plugins that should be excluded from help
 # 
 # Examples are given below. When amending command topic, the string <text> will be replaced with the existing value
 # in the help topic. Color codes can be used in topic text. The color code character is & followed by 0-F.
+# ================================================================
 # 
 # Set this to true to list the individual command help topics in the master help.
 # command-topics-in-master-index: true
 # 
 # Each general topic will show up as a separate topic in the help index along with all the plugin command topics.
 # general-topics:
-#     rules:
+#     Rules:
 #         shortText: Rules of the server
 #         fullText: |
 #             &61. Be kind to your fellow players.
@@ -25,6 +27,18 @@
 #             &D3. No swearing.
 #         permission: topics.rules
 # 
+# Each index topic will show up as a separate sub-index in the help index along with all the plugin command topics.
+# To override the default help index (displayed when the user executes /help), name the index topic "Default".
+# index-topics:
+#     Ban Commands:
+#         shortText: Player banning commands
+#         preamble: Moderator - do not abuse these commands
+#         permission: op
+#         commands:
+#             - /ban
+#             - /ban-ip
+#             - /banlist
+# 
 # Topic amendments are used to change the content of automatically generated plugin command topics.
 # amended-topics:
 #     /stop: