Author: esr
Date: Tue Apr 17 04:34:51 2007
New Revision: 16873
URL: http://svn.gna.org/viewcvs/wesnoth?rev=16873&view=rev
Log:
Third step in automated documentation extraction for macros.
We're making web pages that pass XHTML validation now;
the rest of the work is cleanup and polishing.
Added:
trunk/data/tools/helpheader.xhtml
trunk/data/tools/helptrailer.xhtml
Modified:
trunk/data/abilities.cfg
trunk/data/tools/Makefile
trunk/data/tools/macroscope
trunk/data/utils/sound-utils.cfg
Modified: trunk/data/abilities.cfg
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/data/abilities.cfg?rev=16873&r1=16872&r2=16873&view=diff
==============================================================================
--- trunk/data/abilities.cfg (original)
+++ trunk/data/abilities.cfg Tue Apr 17 04:34:51 2007
@@ -436,7 +436,7 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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 @@
#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
Modified: trunk/data/tools/Makefile
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/data/tools/Makefile?rev=16873&r1=16872&r2=16873&view=diff
==============================================================================
--- trunk/data/tools/Makefile (original)
+++ trunk/data/tools/Makefile Tue Apr 17 04:34:51 2007
@@ -34,5 +34,8 @@
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
+
Added: trunk/data/tools/helpheader.xhtml
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/data/tools/helpheader.xhtml?rev=16873&view=auto
==============================================================================
--- trunk/data/tools/helpheader.xhtml (added)
+++ trunk/data/tools/helpheader.xhtml Tue Apr 17 04:34:51 2007
@@ -1,0 +1,21 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml";>
+
+<head>
+<title>Utility macro reference</title>
+<link rev="made" href="mailto:[EMAIL PROTECTED]" />
+<style type="text/css">
+/*<![CDATA[*/
+.listing {font-family:monospace;}
+.bold {font-style:bold;}
+/*]]>*/
+</style>
+</head>
+<body>
+
+<p>This page is an automatically-generated reference for all the
+utility macros with documentation strings in the Wesnoth source
+distribution.</p>
+
Added: trunk/data/tools/helptrailer.xhtml
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/data/tools/helptrailer.xhtml?rev=16873&view=auto
==============================================================================
--- trunk/data/tools/helptrailer.xhtml (added)
+++ trunk/data/tools/helptrailer.xhtml Tue Apr 17 04:34:51 2007
@@ -1,0 +1,3 @@
+
+</body>
+</html>
Modified: trunk/data/tools/macroscope
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/data/tools/macroscope?rev=16873&r1=16872&r2=16873&view=diff
==============================================================================
--- trunk/data/tools/macroscope (original)
+++ trunk/data/tools/macroscope Tue Apr 17 04:34:51 2007
@@ -41,6 +41,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 = "<p>"
+ for line in lines:
+ line = line.rstrip()
+ if not inlisting and not line:
+ outstr += "</p><p>"
+ continue
+ if not inlisting and line[0] == '!':
+ outstr += "</p>\n<pre class='listing'>"
+ 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 += "</pre>\n<p>"
+ inlisting = False
+ if not inlisting:
+ outstr += "</p>\n"
+ else:
+ outstr += "</pre>\n"
+ outstr = outstr.replace("<p></p>", "")
+ outstr = outstr.replace("\n\n</pre>", "\n</pre>")
+ return outstr
def allfiles(dirpath, exclude):
"Get the names of all files under dirpath, ignoring .svn directories."
@@ -73,6 +107,16 @@
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 @@
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 += "</dl>\n"
+ counted += 1
+ filename = entry.filename
+ outstr += "<h1>From file: " + filename + "</h1>\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 += "<dl>\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 @@
outstr += "\n<dt>\n"
outstr += "<emphasis role='bold'>" + header[0] + "</emphasis>"
if header[1:]:
- outstr += "<emphasis>"+" ".join(header[1:])+"</emphasis>"
+ outstr += " <emphasis>"+" ".join(header[1:])+"</emphasis>"
outstr += "\n</dt>\n"
- outstr += "<dd>\n<p>"
- inlisting = False
- for line in lines:
- line = line.rstrip()
- if not inlisting and not line:
- outstr += "</p><p>"
- continue
- if not inlisting and line[0] == '!':
- outstr += "</p>\n<listing>\n"
- inlisting = True
- bracketdepth = curlydepth = 0
- if inlisting:
- outstr += line[1:] + "\n"
- else:
- outstr += line + "\n"
- if inlisting:
- if line and line[0] != '!':
- outstr += "</listing>\n<p>"
- inlisting = False
- if not inlisting:
- outstr += "</p>\n"
- else:
- outstr += "</listing>\n"
+ outstr += "<dd>\n"
+ outstr += interpret(lines)
outstr += "</dd>\n"
- outstr = outstr.replace("<p></p>", "")
- outstr = outstr.replace("\n\n</listing>", "\n</listing>")
+ outstr += "</dl>\n"
fp.write(outstr)
if __name__ == "__main__":
@@ -365,15 +399,17 @@
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 @@
xref.deflist(predicate)
if unresolved:
xref.unresdump()
- if extracthelp:
- xref.extracthelp(sys.stdout)
Modified: trunk/data/utils/sound-utils.cfg
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/data/utils/sound-utils.cfg?rev=16873&r1=16872&r2=16873&view=diff
==============================================================================
--- trunk/data/utils/sound-utils.cfg (original)
+++ trunk/data/utils/sound-utils.cfg Tue Apr 17 04:34:51 2007
@@ -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
_______________________________________________
Wesnoth-commits mailing list
[email protected]
https://mail.gna.org/listinfo/wesnoth-commits
