From 7034d3f180f5bf5f47ff1099a04b9bf352dd7be7 Mon Sep 17 00:00:00 2001
From: David Anderson <davea42@earthlink.net>
Date: Wed, 19 Feb 2014 11:34:00 -0800
Subject: [PATCH] tools/README: Documented what each .py file does.
 tools/refclassfixup.py: Added a comment documenting    what this code does
 (it lacked any hint).

---
 dwarf5/tools/README           | 76 +++++++++++++++++++++++++++++++++++
 dwarf5/tools/refclassfixup.py |  2 +
 2 files changed, 78 insertions(+)

diff --git a/dwarf5/tools/README b/dwarf5/tools/README
index 130214c..142fac3 100644
--- a/dwarf5/tools/README
+++ b/dwarf5/tools/README
@@ -1,6 +1,8 @@
 These tools are intended to help updating the latex
 source of a DWARF document to get its references
 complete and correct.
+A list of the python source files with the purpose
+of each is near the end of this FILE.
 
 CAUTION: 
 The tools don't really do parsing and
@@ -116,3 +118,77 @@ Performance:
 We simply don't care about performance as long as a task takes
 less than a few minutes. There are only about 70,000 words in a complete
 document so we ignore efficiency issues.
+
+SOURCE FILES:
+The change to internal use of DWTAGfoo etc in the document
+instead of DW\_AT\_foo (see dwarfnamecmds.tex) 
+means many of these commands are not as useful
+as they were originally.  But even so they may form useful
+examples.
+
+anylink.py: Looks for designated prefixes like DW_ADDR etc.
+  Used by other code, this was never that useful alone.
+
+attrlink.py: Uses anylink.py to turn DW_AT_ into \livelink
+
+copyfile.py: Uses fileio.py to parse and output a .tex file.
+ So we can use diff to verify the result is byte-for-byte
+ identical to the input.
+
+dellivelink.py: This uses fileio.py and replaces \livelink
+ and \livetarg with \DWXXXyyy per Ron Brender email of
+ Oct 4, 2013. Strives to be idempotent so rerunning
+ produces no further changes.  A few cases not
+ handled perfectly (where a } is at end of line?) 
+ so if needed again could use a bit of fixing.
+ Files to process must be on command line.
+
+fileio.py:  Given a list of file (.tex) names, it reads in
+  and tokenizes each file.  Functions here let
+  code eventually write stuff back out (changed or not)
+  but the output file always has a ".out" appended, it won't
+  overwrite the input.
+
+formlink.py: Using anylink.py, this transforms DW_FORM_ into
+  \livelink and \livetarg.
+
+printnameswithinteger.py: Identical to dellivelink.py, but this
+  one has a precanned list of files to process built in.
+
+
+printstandard.py:  Print the DW_* entries (and only them)
+  in the files named on the command line
+  one per line.   With any \- or \_ removed.
+  use example:
+  python printstandard.py ../latexdoc/*.tex  |sort|uniq 
+
+printtokens.py: Reads and tokenizes files named on the command
+  line . Prints the tokenized data.
+  Solely for debugging the tokenizing.
+
+refclassfixup.py:  Fixes up certain strings
+  (specified in this file) to use \livelink
+
+removehyphen.py: Turns \-\_ into \_ .
+  This was once a needed task. But run long ago, so
+  This is now a useless bit of code.
+
+removeutf8.py:  The pdf we started from had
+  various utf-8 characters. These got in the way of
+  our text processing, so this app deleted those.
+  This is now a useless bit of code.
+  
+taglink.py:  Finds all the instances of DW_TAG_ in 
+  .tex files named on the command line.
+
+tohyphen.py: The opposite of removehyphen.
+  This is now a useless bit of code.
+
+uses.py: Looks for duplicate uses and definitions of 
+  latex tags.  
+  This is based on the original approach to naming
+  and linking in .tex, not the
+  latest use using dwarfnamecmds.tex
+  
+
+
diff --git a/dwarf5/tools/refclassfixup.py b/dwarf5/tools/refclassfixup.py
index ccf8dcd..c0ea7ef 100644
--- a/dwarf5/tools/refclassfixup.py
+++ b/dwarf5/tools/refclassfixup.py
@@ -3,6 +3,8 @@
 # writes them out in new files.  
 # Used to verify that the output matches the input byte-for-byte
 
+# Transforms certain strings (see refclass below) into livelink commands.
+
 import sys
 import fileio
 
-- 
2.17.1