Machinery for sorting xrefs in the See Also sections.

Author: snarkhunter

DISCUSSIONS/common/menu/api_listing.xml

@@ -7,15 +7,19 @@
 # set to ~/Sites.  If you don't have a local server, set OOFWEBDIR to
 # any empty writable directory outside of tmpdir.
 
+# All xml files that are *not* part of the reference section generated
+# by OOF2's xmlmenudump need to be listed in the file xmlfilelist in
+# this directory.  The list needs to be in the order in which the
+# files are included in the main document.  This ordering is used in
+# the "See Also" sections of the reference pages.  If it's wrong, some
+# pages will be less pretty.
+
 # "make local" generates html from the xml source files, using the xml
 # tools, and then wraps the html output in NIST boilerplate and puts
 # it in OOFWEBDIR/oof2man.
 
 # "make publish" copies the local output to the CTCMS web server.
 
-XMLFILES = CH_graphics.xml CH_tasks.xml CH_windows.xml SN_skel.xml     \
-man_oof2.xml oof2_api.xml CH_overview.xml CH_concepts.xml SN_micro.xml
-
 # On macOS with macports, dvi2bitmap needs to be built with
 # --with-kpathsea --enable-fontgen
 
@@ -26,6 +30,10 @@ DVI2BITMAP = dvi2bitmap --magnification=5 --scaledown=4 --output-type=gif --font
 # mktexpk if it's not using kpathsea. 
 TEMPDIR = tmpdir
 
+# There's no need to explicitly list all of the xml files in the
+# dependencies.  They're included by man_oof2.xml, which depends on
+# oof2_api.xml, and oof2_api.ml is always rebuilt.
+
 SAXON = ../xsl/java/saxon.jar
 ## TODO: More up-to-date saxon from MacPorts raises lots of warnings
 ## and errors.  Is there any point in updating?
@@ -61,11 +69,11 @@ oof2man.tgz: $(TEMPDIR) saxonize.ext texify figs
 	tar -czf oof2man.tgz oof2man
 	-rm -rf oof2man
 
-saxonize.web: $(XMLFILES)
+saxonize.web: oof2_api.xml
 	mkdir $(TEMPDIR)/equations
 	(cd $(TEMPDIR); rm -f *.html; java -jar $(SAXON) ../man_oof2.xml ../xsl/oofchunk.xsl nist.exit.script=1)
 
-saxonize.ext: $(XMLFILES)
+saxonize.ext: oof2_api.xml
 	(cd $(TEMPDIR); rm -f *.html; java -jar $(SAXON) ../man_oof2.xml ../xsl/oofchunk.xsl)
 
 texify:
@@ -75,7 +83,7 @@ texify:
 oof2: always
 	(cd build; make -j 10 DESTDIR=~/stow/oof2-py311 install; cd ~/stow; ./switchto oof2-py311)
 
-oof2_api.xml: oof2
+oof2_api.xml: oof2 xmlfilelist
 	bin/oof2 --script xmldump.py --quiet --debug
 	sed s/Graphics_1/Graphics_n/g oof2_api.xml > tmp
 	mv -f tmp oof2_api.xml

Makefile

@@ -12,7 +12,45 @@
 # and RegisteredClasses, and some other bits and pieces.
 
 # Some menus aren't constructed until a graphics window is opened.
+
 OOF.Windows.Graphics.New()
 
-OOF.Help.API_Listing(filename='oof2_api.xml', format='xml')
+# Get the ids from the xml files other than oof2_api.xml. This lets
+# the code in SRC/common/IO/xmlmenudump.py sort cross references in
+# oof2_api.xml in a sensible way.
+
+import re
+# Regexp pattern that matches id="idtag" or id='idtag'.  It defines
+# two groups. This first is just the opening quotation mark, which is
+# in a group so that it can be compared to the closing quotation mark.
+# The second group is the idtag.
+pattern = re.compile(r"""id=(["'])(.+?)\1""") 
+
+xmlids = {}                     # xmlids[id] = order
+sourcefiles = open("xmlfilelist", "r")
+for fline in sourcefiles:
+    filename = fline.strip()
+    if filename and filename[0] != '#':
+        srcfile = open(filename, "r")
+        for srcline in srcfile:
+            # This might include commented out lines, but that
+            # shouldn't matter.  Adding them to the dict won't change
+            # the ordering of the other ids.
+            for r in pattern.findall(srcline):
+                # findall returns a list of strings that match the two
+                # groups defined in the regexp pattern.  The second
+                # group is the docbook id.
+                xmlids[r[1]] = len(xmlids)
+
+# Don't use an OOF2 menu item to generate the manual.  It's not
+# something that users will do, and not something that needs to be
+# logged.  Also, xmlids is too large to use as an OOFMenuItem
+# argument, since it will be echoed to the screen.  Just call
+# xmlmenudump directly.
+
+from ooflib.common.IO import xmlmenudump
+outfile = open('oof2_api.xml', 'w')
+xmlmenudump.xmlmenudump(outfile, xmlids)
+outfile.close()
+
 OOF.File.Quit()

xmldump.py

@@ -0,0 +1,57 @@
+# This software was produced by NIST, an agency of the U.S. government,
+# and by statute is not subject to copyright in the United States.
+# Recipients of this software assume all responsibilities associated
+# with its operation, modification and maintenance. However, to
+# facilitate maintenance we ask that before distributing modified
+# versions of this software, you first contact the authors at
+# [email protected].
+
+# This file lists the xml source files used to build the oof2 manual,
+# in the order in which they're imported.  It's used to build a table
+# of xml ids so that xmldump.py can create sensible cross references.
+
+# This list does not include oof2_api.xml or the files that are used
+# to create it.  The list is used before oof2_api.xml is generated.
+
+# Blank lines and lines beginning with '#' are ignored.
+
+CH_overview.xml
+CH_starting.xml
+CH_concepts.xml
+
+CH_tasks.xml
+# CH_tasks includes:
+SN_micro.xml
+SN_image.xml
+SN_pixelsel.xml
+SN_active.xml
+SN_material.xml
+# SN_interfaces.xml  (commented out until the interface branch is complete)
+SN_skel.xml
+SN_pinnodes.xml
+SN_skelsel.xml
+SN_skelbdy.xml
+SN_femesh.xml
+SN_fields.xml
+SN_bdycond.xml
+SN_scheduledout.xml
+SN_solver.xml
+SN_analysis.xml
+SN_bdyanalysis.xml
+
+CH_graphics.xml
+# CH_graphics includes:
+TB_viewer.xml
+TB_pixelinfo.xml
+TB_pixelsel.xml
+TB_skelinfo.xml
+TB_skelselection.xml
+TB_movenodes.xml
+TB_pinnodes.xml
+TB_meshinfo.xml
+TB_meshcs.xml
+
+CH_windows.xml
+CH_extending.xml
+CH_coding.xml
+appendices.xml