Improve discoverability of cddatags (#37954)

* Mention cddatags in the JSON docs

* Strip platform-specific path separator for tags

This is fixing a hypothetical bug which I think cddatags would have
suffered from on Windows (but untested there).

* Use cddatags in Makefile

There were already two rules for creating tags; update them both.

* Move some cddatags docs to DEVELOPER_TOOLING

The second paragraph was not useful to non-code-writing contributors, so
move it and rewrite it.

* cddatags: Force UTF-8 encoding for json files

* Expand on the cddatags docs

Thanks to snipercup for researching useful tips for Windows.

Makefile

@@ -1039,12 +1039,13 @@ endif
 
 export ODIR _OBJS LDFLAGS CXX W32FLAGS DEFINES CXXFLAGS TARGETSYSTEM
 
-ctags: $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR)
-	ctags $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR)
+ctags: $(ASTYLE_SOURCES)
+	ctags $^
+	./tools/json_tools/cddatags.py
 
-etags: $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR)
-	etags $(SOURCES) $(HEADERS) $(TESTSRC) $(TESTHDR)
-	find data -name "*.json" -print0 | xargs -0 -L 50 etags --append
+etags: $(ASTYLE_SOURCES)
+	etags $^
+	./tools/json_tools/cddatags.py
 
 astyle: $(ASTYLE_SOURCES)
 	$(ASTYLE_BINARY) --options=.astylerc -n $(ASTYLE_SOURCES)

doc/DEVELOPER_TOOLING.md

@@ -42,6 +42,11 @@ On Windows, there is an [AStyle extension for Visual Studio](https://github.com/
 
 See the [JSON style guide](JSON_STYLE.md).
 
+## ctags
+
+In addition to the usual means of creating a `tags` file via e.g. [`ctags`](http://ctags.sourceforge.net/), we provide `tools/json_tools/cddatags.py` to augment a `tags` file with locations of definitions taken from CDDA JSON data.  `cddatags.py` is designed to safely update a tags file containing source code tags, so if you want both types of tag in your `tags` file then you can run `ctags -R . && tools/json_tools/cddatags.py`.  Alternatively, there is a rule in the `Makefile` to do this for you; just run `make ctags` or `make etags`.
+
+
 ## clang-tidy
 
 Cataclysm has a [clang-tidy configuration file](../.clang-tidy) and if you have

doc/JSON_INFO.md

@@ -3,6 +3,7 @@
 Use the `Home` key to return to the top.
 
 - [Introduction](#introduction)
+- [Navigating the JSON](#navigating-the-json)
 - [File descriptions](#file-descriptions)
   * [`data/json/`](#datajson)
   * [`data/json/items/`](#datajsonitems)
@@ -162,6 +163,16 @@ Use the `Home` key to return to the top.
 # Introduction
 This document describes the contents of the json files used in Cataclysm: Dark days ahead. You are probably reading this if you want to add or change content of Catacysm: Dark days ahead and need to learn more about what to find where and what each file and property does.
 
+# Navigating the JSON
+A lot of the JSON involves cross-references to other JSON entities.  To make it easier to navigate, we provide a script `tools/json_tools/cddatags.py` that can build a `tags` file for you.
+
+To run the script you'll need Python 3.  On Windows you'll probably need to install that, and associate `.py` files with Python.  Then open a command prompt, navigate to your CDDA folder, and run `tools\json_tools\cddatags.py`.
+
+To use this feature your editor will need [ctags support](http://ctags.sourceforge.net/).  When that's working you should be able to easily jump to the definition of any entity.  For example, by positioning your cursor over an id and hitting the appropriate key combination.
+
+* In Vim, this feature exists by default, and you can jump to a definition using [`^]`](http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#tagsrch.txt).
+* In Notepad++ go to "Plugins" -> "Plugins Admin" and enable the "TagLEET" plugin.  Then select any id and press Alt+Space to open the references window.
+
 # File descriptions
 Here's a quick summary of what each of the JSON files contain, broken down by folder. This list is not comprehensive, but covers the broad strokes.
 

tools/json_tools/cddatags.py

@@ -35,8 +35,8 @@ def main(args):
             if filename.endswith('.json'):
                 full_path = os.path.join(dirpath, filename)
                 assert full_path.startswith(TOP_DIR)
-                relative_path = full_path[len(TOP_DIR):].lstrip('/')
-                with open(full_path) as file:
+                relative_path = full_path[len(TOP_DIR):].lstrip(os.path.sep)
+                with open(full_path, encoding='utf-8') as file:
                     try:
                         json_data = json.load(file)
                     except Exception as err: