diff --git a/data/abilities.cfg b/data/abilities.cfg index a8a3837ba88..ed03db90075 100644 --- a/data/abilities.cfg +++ b/data/abilities.cfg @@ -436,7 +436,7 @@ Enemy units cannot see or attack this unit when it is in deep water, except for #weapons specials #define WEAPON_SPECIAL_BERSERK -# Canned definition of the Berserk ability to be included in an +# Canned definition of the Berserk ability to be included in a # [specials] clause. [berserk] id=berserk @@ -448,7 +448,7 @@ Whether used offensively or defensively, this attack presses the engagement unti #enddef #define WEAPON_SPECIAL_BACKSTAB -# Canned definition of the Backstab ability to be included in an +# Canned definition of the Backstab ability to be included in a # [specials] clause. [damage] id=backstab @@ -462,7 +462,7 @@ This attack deals double damage if there is an enemy of the target on the opposi #enddef #define WEAPON_SPECIAL_PLAGUE_TYPE TYPE -# Canned definition of the Plague ability to be included in an +# Canned definition of the Plague ability to be included in a # [specials] clause (with type specifier). [plague] id=plague({TYPE}) @@ -474,7 +474,7 @@ When a unit is killed by a Plague attack, that unit is replaced with a unit iden #enddef #define WEAPON_SPECIAL_PLAGUE -# Canned definition of the Plague ability to be included in an +# Canned definition of the Plague ability to be included in a # [specials] clause (without type specifier). [plague] id=plague @@ -485,7 +485,7 @@ When a unit is killed by a Plague attack, that unit is replaced with a unit iden #enddef #define WEAPON_SPECIAL_SLOW -# Canned definition of the Slow ability to be included in an +# Canned definition of the Slow ability to be included in a # [specials] clause. [slow] id=slow @@ -496,7 +496,7 @@ This attack slows the target until it ends a turn. Slow halves the damage caused #enddef #define WEAPON_SPECIAL_STONE -# Canned definition of the Stone ability to be included in an +# Canned definition of the Stone ability to be included in a # [specials] clause. [stones] id=stones @@ -507,7 +507,7 @@ This attack turns the target to stone. Units that have been turned to stone may #enddef #define WEAPON_SPECIAL_MARKSMAN -# Canned definition of the Marksman ability to be included in an +# Canned definition of the Marksman ability to be included in a # [specials] clause. [chance_to_hit] id=marksman @@ -521,7 +521,7 @@ When used offensively, this attack always has at least a 60% chance to hit." #enddef #define WEAPON_SPECIAL_MAGICAL -# Canned definition of the Magical (targeting) ability to be included in an +# Canned definition of the Magical (targeting) ability to be included in a # [specials] clause. [chance_to_hit] id=magical @@ -534,7 +534,7 @@ This attack always has a 70% chance to hit." #enddef #define WEAPON_SPECIAL_SWARM -# Canned definition of the Swarm ability to be included in an +# Canned definition of the Swarm ability to be included in a # [specials] clause. [attacks] id=swarm @@ -545,7 +545,7 @@ The number of strikes of this attack decreases when the unit is wounded. The num #enddef #define WEAPON_SPECIAL_CHARGE -# Canned definition of the Charge ability to be included in an +# Canned definition of the Charge ability to be included in a # [specials] clause. [damage] id=charge @@ -559,7 +559,7 @@ This attack deals double damage to the target. It also causes this unit to take #enddef #define WEAPON_SPECIAL_DRAIN -# Canned definition of the Drain ability to be included in an +# Canned definition of the Drain ability to be included in a # [specials] clause. [drains] id=drains @@ -570,7 +570,7 @@ This unit drains health from living units, healing itself for half the amount of #enddef #define WEAPON_SPECIAL_FIRSTSTRIKE -# Canned definition of the First-strike ability to be included in an +# Canned definition of the First-strike ability to be included in a # [specials] clause. [firststrike] id=firststrike @@ -581,7 +581,7 @@ This unit always strikes first with this attack, even if they are defending." #enddef #define WEAPON_SPECIAL_POISON -# Canned definition of the Poison ability to be included in an +# Canned definition of the Poison ability to be included in a # [specials] clause. [poison] id=poison diff --git a/data/tools/Makefile b/data/tools/Makefile index 8853f09521c..a7ba27338c8 100644 --- a/data/tools/Makefile +++ b/data/tools/Makefile @@ -34,5 +34,8 @@ utils-macros: definitions: @./macroscope --definitions --exclude data/scenarios --exclude data/campaigns $(EXCLUDE) $(TOPDIR) -help: - @./macroscope --extracthelp --exclude data/scenarios --exclude data/campaigns $(EXCLUDE) $(TOPDIR) +macro-reference.xhtml: + @cat helpheader.xhtml >macro-reference.xhtml + @./macroscope --extracthelp --exclude data/scenarios --exclude data/campaigns $(EXCLUDE) $(TOPDIR) >>macro-reference.xhtml + @cat helptrailer.xhtml >>macro-reference.xhtml + diff --git a/data/tools/helpheader.xhtml b/data/tools/helpheader.xhtml new file mode 100644 index 00000000000..69f9bedd199 --- /dev/null +++ b/data/tools/helpheader.xhtml @@ -0,0 +1,21 @@ + + + + + +Utility macro reference + + + + + +

This page is an automatically-generated reference for all the +utility macros with documentation strings in the Wesnoth source +distribution.

+ diff --git a/data/tools/helptrailer.xhtml b/data/tools/helptrailer.xhtml new file mode 100644 index 00000000000..11a09caf829 --- /dev/null +++ b/data/tools/helptrailer.xhtml @@ -0,0 +1,3 @@ + + + diff --git a/data/tools/macroscope b/data/tools/macroscope index f94a17b69de..63ccc7a9143 100755 --- a/data/tools/macroscope +++ b/data/tools/macroscope @@ -42,6 +42,40 @@ import sys, os, time, re, getopt, sre_constants resource_extensions = ("png", "jpg", "ogg", "wav") +def htmlize(line): + "HTML-escape a text line" + return line.replace("<", "<").replace(">", ">").replace("&", "&") + +def interpret(lines): + "Interpret the ! convention for .cfg comments." + inlisting = False + outstr = "

" + for line in lines: + line = line.rstrip() + if not inlisting and not line: + outstr += "

" + continue + if not inlisting and line[0] == '!': + outstr += "

\n
"
+            inlisting = True
+            bracketdepth = curlydepth = 0
+        line = htmlize(line)
+        if inlisting:
+            outstr += line[1:] + "\n"
+        else:
+            outstr += line + "\n"
+        if inlisting:
+            if line and line[0] != '!':
+                outstr += "
\n

" + inlisting = False + if not inlisting: + outstr += "

\n" + else: + outstr += "\n" + outstr = outstr.replace("

", "") + outstr = outstr.replace("\n\n", "\n") + return outstr + def allfiles(dirpath, exclude): "Get the names of all files under dirpath, ignoring .svn directories." datafiles = [] @@ -73,6 +107,16 @@ class reference: def dump_references(self): for (file, linenumbers) in self.references.items(): print " %s: %s" % (file, `linenumbers`[1:-1]) + def __cmp__(self, other): + "Compare two documentation objects for place in the sort order." + # Major sort by file, minor by line number. This presumes that the + # files correspond to coherent topics and gives us control of the + # sequence. + byfile = cmp(self.filename, other.filename) + if byfile: + return byfile + else: + return cmp(self.line, other.line) def __str__(self): if self.line: return '"%s", line %d' % (self.filename, self.line) @@ -249,20 +293,32 @@ class CrossRef: def extracthelp(self, fp): "Deliver all macro help comments in HTML form." doclist = self.xref.keys() - def defcmp(s, t): - "Compare two documentation objects for place in the sort order." - # Major sort by file, minor by name. This presumes that the - # files correspond to coherent topics. - byfile = cmp(self.xref[s].filename, self.xref[t].filename) - if byfile: - return byfile - else: - return cmp(s, t) - doclist.sort(defcmp) + doclist = filter(lambda x: self.xref[x].docstring, doclist) + doclist.sort(lambda x, y: cmp(self.xref[x], self.xref[y])) outstr = "" + filename = None + counted = 0 for name in doclist: - if self.xref[name].docstring: - lines = self.xref[name].docstring.split("\n") + entry = self.xref[name] + if entry.filename != filename: + if counted: + outstr += "\n" + counted += 1 + filename = entry.filename + outstr += "

From file: " + filename + "

\n" + hdr = [] + dfp = open(filename) + for line in dfp: + if line[0] == '#': + hdr.append(line[1:]) + else: + break + dfp.close() + if hdr: + outstr += interpret(hdr) + outstr += "
\n" + if entry.docstring: + lines = entry.docstring.split("\n") header = lines.pop(0).split() if lines and not lines[-1]: # Ignore trailing blank lines lines.pop() @@ -271,34 +327,12 @@ class CrossRef: outstr += "\n
\n" outstr += "" + header[0] + "" if header[1:]: - outstr += ""+" ".join(header[1:])+"" + outstr += " "+" ".join(header[1:])+"" outstr += "\n
\n" - outstr += "
\n

" - inlisting = False - for line in lines: - line = line.rstrip() - if not inlisting and not line: - outstr += "

" - continue - if not inlisting and line[0] == '!': - outstr += "

\n\n" - inlisting = True - bracketdepth = curlydepth = 0 - if inlisting: - outstr += line[1:] + "\n" - else: - outstr += line + "\n" - if inlisting: - if line and line[0] != '!': - outstr += "\n

" - inlisting = False - if not inlisting: - outstr += "

\n" - else: - outstr += "\n" + outstr += "
\n" + outstr += interpret(lines) outstr += "
\n" - outstr = outstr.replace("

", "") - outstr = outstr.replace("\n\n", "\n") + outstr += "
\n" fp.write(outstr) if __name__ == "__main__": @@ -365,15 +399,17 @@ Usage: macroscope [options] dirpath dirpath = arguments[0].split(":") else: dirpath = ['.'] - print "# Macroscope reporting on %s" % time.ctime() - print "# Invocation: %s" % " ".join(sys.argv) - print "# Working directory: %s" % os.getcwd() - if crossreference or definitions or listfiles or unresolved or extracthelp: - filelist = allfiles(dirpath, "|".join(exclude)) - if listfiles: - for filename in filelist: - print filename - xref = CrossRef(filelist) + filelist = allfiles(dirpath, "|".join(exclude)) + xref = CrossRef(filelist) + if extracthelp: + xref.extracthelp(sys.stdout) + elif listfiles: + for filename in filelist: + print filename + elif crossreference or definitions or listfiles or unresolved: + print "# Macroscope reporting on %s" % time.ctime() + print "# Invocation: %s" % " ".join(sys.argv) + print "# Working directory: %s" % os.getcwd() def predicate(name, defloc): if from_restrict and not defloc.filename.startswith(from_restrict): return False @@ -391,7 +427,5 @@ Usage: macroscope [options] dirpath xref.deflist(predicate) if unresolved: xref.unresdump() - if extracthelp: - xref.extracthelp(sys.stdout) diff --git a/data/utils/sound-utils.cfg b/data/utils/sound-utils.cfg index d44b096f1fe..2a35e1f434b 100644 --- a/data/utils/sound-utils.cfg +++ b/data/utils/sound-utils.cfg @@ -1,9 +1,9 @@ # Music control macros, and declarations of sound resource lists. # # As of 1.1.3, music is parsed as follows: -# 1. the [scenario]-level [music] tag -# 2. the [story]-level music key -# 3. any [event]-level [music] tags +#! 1. the [scenario]-level [music] tag +#! 2. the [story]-level music key +#! 3. any [event]-level [music] tags # # If you change the music at a lower level, the tags above it will NOT # be re-parsed and your scenario will sound wrong. For example, if @@ -91,7 +91,7 @@ # It should be positioned at the top of the scenario file # so it can be overridden by other prestart or start events. # -# It also allows for the convenient use of a standardized +# It also allows for the convenient use of standardized # intra-scenario music, should we decide to use one. [music] name="wesnoth-2.ogg" @@ -108,7 +108,7 @@ # randomly picked every time, instead of a single sound. Here the most commonly # used lists are wrapped inside macros. # -# These are used in unit .cfg's for example like this: +# These are used in unit .cfg files, for example like this: # #! [animation] #! hits=no