Maintenance tools - Revision history

Bssarkar: /* wmllint */ Explain no-icon flag based on code

2026-03-24T11:14:32Z

‎wmllint: Explain no-icon flag based on code

Egallager: /* wmllint */ wiki version of https://github.com/wesnoth/wesnoth/commit/2583d9ae80e26b433e04a74a78d83e72098a11b0

2024-12-31T23:47:25Z

‎wmllint: wiki version of https://github.com/wesnoth/wesnoth/commit/2583d9ae80e26b433e04a74a78d83e72098a11b0

Egallager: /* wmlscope */ Update with info from the big block comment at the top of the script

2024-08-17T23:19:50Z

‎wmlscope: Update with info from the big block comment at the top of the script

Egallager: /* wmllint */ additional note about spellchecking

2023-12-30T09:01:41Z

‎wmllint: additional note about spellchecking

Egallager: /* wmllint */ sync with current `wmllint --help` output, and update info about spellchecking

2023-12-30T08:54:56Z

‎wmllint: sync with current `wmllint --help` output, and update info about spellchecking

Egallager: add "See Also" section

2023-05-08T02:48:03Z

add "See Also" section

Elven: /* General Information */ 1.16

2022-10-13T22:08:46Z

‎General Information: 1.16

Egallager: /* wmlindent */ formatting; also remove sentences that got moved elsewhere in the section

2022-10-13T00:35:20Z

‎wmlindent: formatting; also remove sentences that got moved elsewhere in the section

Egallager: /* wmlindent */ update by re-pasting the equivalent comment from the wmlindent script itself (with some tweaks to make it merge back in with the existing text more cleanly)

2022-10-13T00:29:16Z

‎wmlindent: update by re-pasting the equivalent comment from the wmlindent script itself (with some tweaks to make it merge back in with the existing text more cleanly)

Egallager: /* Explanations of wmllint diagnostics */ One more `-K` flag instance

2022-08-03T16:52:04Z

‎Explanations of wmllint diagnostics: One more `-K` flag instance

@@ Line 381: / Line 381: @@
 * <code>noconvert</code>: Disables conversion of terrains and image/sound filenames on the current line only.
 * <code>markcheck [on|off]</code>: Enables or disables translation mark checking from the current (next?) line onward.
-* <code>no-icon</code>: Prevents description insertions (what does that mean?)
+* <code>no-icon</code>: If an attack has no description, without this wmllint adds a dummy description to the attack which is just the name of the attack. With this, this description insertion is suppressed.
 * <code>recognize <name></code>: Indicates that the character with the given name exists even though a declaration (ie a <code>[unit]</code> or <code>[side]</code> tag) is not visible.
 * <code>whofield <macro> <number></code>: Indicates that the specified macro declares a character whose name is given by the specified argument to the macro.

@@ Line 351: / Line 351: @@
 ; -d, --dryrun:               List changes (-v) but don't perform them.
 ; -r, --revert:               Revert the conversion from the -bak files.
-; -m, --missing:              Don't warn about tags without side= keys now applying to all sides.
+; -m, --missing:              Warn about tags without side= keys now applying to all sides.
 ; -s, --stripcr:              Convert DOS-style CR/LF to Unix-style LF.
 ; -v, --verbose:              Set verbosity; more details below.

@@ Line 55: / Line 55: @@
 == wmlscope ==
-The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist.  These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic.  They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.
+The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist.  These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic (see [https://github.com/wesnoth/wesnoth/issues/5332 issue 5332] for more info).  They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.
 <tt>wmlscope</tt> also checks macro invocations for consistency.  It will complain
@@ Line 199: / Line 199: @@
 </table>
-If the actual argument is a macro call {.*}, then it matches any formal  Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.
+If the actual argument is a macro call {.*}, then it matches any formal.  Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.
 The argument type check only works in macro calls that fit on a single line.
@@ Line 215: / Line 215: @@
 ; -h, --help:                 Emit a help message and quit
-; -c, --crossreference:       Report resolved macro references (implies -w 1)
+; -c, --crossreference:       Report resolved macro references (implies <tt>-w 1</tt>)
 ; -C, --collisions:           Report duplicate resource files
 ; -d, --deflist:              Make definition list.  (This one is for campaign server maintainers.)
@@ Line 222: / Line 222: @@
 ; -l, --listfiles:            List files that will be processed
 ; -r <i>ddd</i>, --refcount=<i>ddd</i>:     Report only on macros with references in exactly <i>ddd</i> files.
 ; -u, --unresolved:           Report unresolved macro references
 ; -w, --warnlevel:            Set to 1 to warn of duplicate macro definitions
-; --force-used reg:          Ignore reference count 0 on names matching regexp
+; -p, --progress:             Show progress
 ; --extracthelp:              Extract help from macro definition comments.
 == wmllint ==

@@ Line 277: / Line 277: @@
 # Use either --clean to remove the -bak files or --revert to undo the conversion.
-Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings.  It will work automatically with any of [https://github.com/AbiWord/enchant enchant]'s spellchecking backends (including aspell, myspell, ispell, applespell, hunspell, nuspell, and so on, depending on the version of enchant), provided you have the <tt>enchant.py</tt> Python library installed.
+Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings.  It will work automatically with any of [https://github.com/AbiWord/enchant enchant]'s spellchecking backends (including aspell, myspell, ispell, applespell, hunspell, nuspell, and so on, depending on the version of enchant), provided you have the <tt>enchant.py</tt> Python library installed. Note that the spellchecking results can vary depending on which backend enchant decides to use.
 wmllint supports a number of magic comments to customize its behaviour and avoid false positives. All magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. In the below explanations, a string of the form <code>[a|b]</code> means you may use either <code>a</code> or <code>b</code> at that location, while a string of the form <code><arg></code> indicates free text substitution.

@@ Line 250: / Line 250: @@
 ; -h, --help:                 Emit a help message and quit.
 ; -c, --clean:                Clean up -bak files.
-; -D, --diff:                 Show diffs between converted and unconverted files.
+; -D, --diffs:                Display diffs between converted and unconverted files.
 ; -r, --revert:               Revert the conversion from the -bak files.
-; -n, --nolift:               Suppress lifting, do sanity checks only
+; -m, --missing:              Don't warn about tags without side= keys now applying to all sides.
 The verbosity option works like this:
@@ Line 273: / Line 277: @@
 # Use either --clean to remove the -bak files or --revert to undo the conversion.
-Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings.  It will work automatically with either aspell, myspell, or ispell provided you have the <tt>enchant.py</tt> Python library installed.
+Additionally, wmllint tries to locate a spell checker on your system and spell-checks storyline and message strings.  It will work automatically with any of [https://github.com/AbiWord/enchant enchant]'s spellchecking backends (including aspell, myspell, ispell, applespell, hunspell, nuspell, and so on, depending on the version of enchant), provided you have the <tt>enchant.py</tt> Python library installed.
 wmllint supports a number of magic comments to customize its behaviour and avoid false positives. All magic wmllint comments begin with the string <tt>wmllint:</tt>, followed by some additional keyword and potentially some arguments. In the below explanations, a string of the form <code>[a|b]</code> means you may use either <code>a</code> or <code>b</code> at that location, while a string of the form <code><arg></code> indicates free text substitution.

@@ Line 387: / Line 387: @@
 To start it, just double click on the GUI.pyw file. The interface is pretty much self-explanatory, and allows you to run wmllint, wmlscope, wmlindent and wmlxgettext, modify their options, select an add-on and save the tools' output as a text file.
 [[Category:Create]]
 [[Category:Tools]]

@@ Line 17: / Line 17: @@
 from http://www.python.org.  You will also need to know how to run command-line tools on your system.
-If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.14-tools (or the convenient version).
+If you're working with Debian or Ubuntu you might have to install the package wesnoth-1.16-tools (or the convenient version).
-  sudo apt install wesnoth-1.14-tools
+  sudo apt install wesnoth-1.16-tools
@@ Line 39: / Line 39: @@
 '''A convenient way of running wmllint''' on Linux (Debian or Ubuntu) and Windows in comparison, '''Linux''':
-Assuming we're working with wesnoth 1.14 or more advanced versions.
+Assuming we're working with wesnoth 1.16 or more advanced versions.
-  python3 /usr/share/games/wesnoth/1.14/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.14/data/core ~/.local/share/wesnoth/1.14/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
+  python3 /usr/share/games/wesnoth/1.16/data/tools/wmllint --dryrun /usr/share/games/wesnoth/1.16/data/core ~/.local/share/wesnoth/1.16/data/add-ons/A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
 I have these commands inside of a file named
   wmllint_dryrun_ASC.sh
@@ Line 47: / Line 47: @@
 The python3 command should be automatically known on Debian. The path to the script tells the python interpreter what to execute. --dryrun: A wmllint option, see below. The path to the core files is needed to let wmllint know about e.g. defined core units, followed by the path to the add-on that shall be checked; the last two commands cause the result of the wmllint usage to be written into those files in the same directory as the script.
 '''Windows''', this is logically exactly the same as the Linux shell script above, so if you are on a Mac you can probably conclude how you need to adapt the paths:
-  E:\Python37\python.exe E:\Programme\Wesnoth_1.14_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.14_git\data\core E:\Programme\Wesnoth_1.14_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
+  E:\Python37\python.exe E:\Programme\Wesnoth_1.16_git\data\tools\wmllint --dryrun E:\Programme\Wesnoth_1.16_git\data\core E:\Programme\Wesnoth_1.16_git\userdata\data\add-ons\A_Simple_Campaign 1>wmllint-run.log 2>wmllint-err.log
 This is the content of a .txt file, whose extension I rename to .bat and double-click onto it. Opening a command window is not needed this way.
 Since Python isn't natively installed on windows and I don't have environment variables set, the full path to python.exe is given. If your directories contain spaces it may help to include the path in quotes:
-  "C:\Programs\Battle for Wesnoth 1.14\data\tools\wmllint"
+  "C:\Programs\Battle for Wesnoth 1.16\data\tools\wmllint"
 Remember that you do not need to enter all of the commands/paths at once. If it doesn't work, start with only "python" or "C:\Python37\python.exe" or the like and interpret the error messages that you get. If you get an "unknown command", python isn't installed or environment variables aren't set correctly. After that, you can add the later commands one by one.

@@ Line 324: / Line 324: @@
 standard output.  If arguments are specified, they are taken to be files to be
 re-indented in place; a directory name causes reindenting on all WML
-beneath it. Interrupting wmlindent ought to be safe, as each reindenting
+beneath it.
 The indent unit is four spaces.  Absence of an option to change this is
@@ Line 335: / Line 333: @@
 trailing whitespace. Leading whitespace will be regularized to the
 current indent; trailing whitespace will be stripped.  After processing
-all lines will end with a Unix-style \n end-of-line marker.
+all lines will end with a Unix-style <code>\n</code> end-of-line marker.
 Runs of entirely blank lines will be reduced to one blank line, except
@@ Line 342: / Line 340: @@
 It is possible to wrap a section of lines in special comments so that
-wmlindent will ignore them.  You may need to do this for unbalanced
+<tt>wmlindent</tt> will ignore them.  You may need to do this for unbalanced
 macros (it's better, though, to get rid of those where possible).
-Use 'wmlindent: {start,stop} ignoring' anywhere in a comment.
+Use '<code>wmlindent: {start,stop} ignoring</code>' anywhere in a comment.
 It is also possible to declare custom openers an closers, e.g for macros
@@ Line 357: / Line 355: @@
 will be recognized.
-The public utility macros "{FOREACH" and "{NEXT" come as wired-in exceptions,
+The public utility macros "<code>{FOREACH</code>" and "<code>{NEXT</code>" come as wired-in exceptions,
 because it is not guaranteed that their indent declarations will be processed
 before the macro library is reached.
-Interrupting will be safe, as each reindenting will be done to a copy
+Interrupting <tt>wmlindent</tt> ought to be safe, as each reindenting will be done to a copy
 that is atomically renamed when it's done.  If the output file is identical
 to the input, the output file will simply be deleted, so the timestamp
 on the input file won't be touched.
-The --dryrun option detects and reports files that would be changed
+The <tt>--dryrun</tt> option detects and reports files that would be changed
-without changing them. The --verbose or -v option enables reporting
+without changing them. The <tt>--verbose</tt> or <tt>-v</tt> option enables reporting
-of files that are (or would be, under --dryrun) changed.  With -v -v,
+of files that are (or would be, under <tt>--dryrun</tt>) changed.  With <tt>-v -v</tt>,
-unchanged files are also reported.  The --exclude option takes a regexp
+unchanged files are also reported.  The <tt>--exclude</tt> option takes a regexp
 and excludes files matching it.

@@ Line 323: / Line 323: @@
 Call with no arguments to filter WML on standard input to reindented WML on
 standard output.  If arguments are specified, they are taken to be files to be
-re-indented in place; interrupting will be safe, as each reindenting
+re-indented in place; a directory name causes reindenting on all WML
-will be done to a copy that is atomically renamed when it's done. This
+beneath it. Interrupting wmlindent ought to be safe, as each reindenting
 code never modifies anything but blank lines and leading and trailing whitespace on non-blank lines.
 The indent unit is four spaces.  Absence of an option to change this is
-deliberate; the purpose of this tool is to prevent style wars, not encourage
+deliberate; the purpose of this tool is to ''prevent'' style wars, not encourage
 them.
-If you don't apply this tool to your own WML, the mainline-campaign maintainers
+On non-empty lines, this code never modifies anything but leading and
-will do it when and if your code is accepted into the tree.
+trailing whitespace. Leading whitespace will be regularized to the
 Note: This tool does not include a parser.  It will produce bad results on WML

@@ Line 306: / Line 306: @@
 * <code>nonstandard word-wrap style within message</code>: This message meant there was an unexpected newline character within a <code>[message]</code> tag. However, this check was removed in the 1.15.10 release. Pre-1.15.10, add-on developers could silence by putting a <code># wmllint: display on</code> comment before the string and a <code># wmllint: display off</code> comment after the string, however, post-1.15.10, this is no longer necessary.
-* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types.
+* <code>%s is not a known unit type</code> (in cases where you'd think the unit type ''would'' be known): This means the unit has a type that was never defined in mainline or in the add-on. This is why you're supposed to always add Wesnoth's core directory as the first item to be checked when using <tt>wmllint</tt> (which is something that the GUI version of it will do automatically for you), so that it can load the mainline unit types. (You can also silence this warning by passing the <tt>-K</tt> flag to <tt>wmllint</tt>.)
 * <code>unknown speaker '%s' of [message]</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the speaker is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is SPEAKER</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.
 * <code>unknown '%s' referred to by id</code>: use a <code># wmllint: recognize %s</code> magic comment, or, alternatively, if the unit is created by a macro, use a magic comment of the form of either <code># wmllint: who MACRO is UNIT</code> or <code># wmllint: whofield MACRO NUMBER</code>, depending on whether the macro takes an argument for the unit's name or not.