From b0c505c4919a94bbf3f76e21981f265fe65179fd Mon Sep 17 00:00:00 2001
From: Peter Chang <peter.chang@diamond.ac.uk>
Date: Thu, 23 Jan 2020 12:00:57 -0600
Subject: [PATCH 1/2] Remove some references to NAPI for #699

Remove alias in schema, add links to schema documentation,
unescape HTML tags in doc generator
---
 nxdl.xsd               |  7 ++++---
 nxdlTypes.xsd          | 10 ----------
 utils/nxdl_desc2rst.py | 11 +++++++++++
 utils/types2rst.py     |  2 +-
 4 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/nxdl.xsd b/nxdl.xsd
index c1f8d23ea7..adcbb43f31 100644
--- a/nxdl.xsd
+++ b/nxdl.xsd
@@ -724,11 +724,12 @@
 						</xs:documentation>
 					</xs:annotation>
 				</xs:attribute>
-				<xs:attribute name="type" type="nx:NAPI" default="NX_CHAR">
+				<xs:attribute name="type" type="nx:primitiveType" default="NX_CHAR">
 					<xs:annotation>
 						<xs:documentation>
-							Defines the type of the element as allowed by the NAPI (NeXus Application Programmer Interface).
-							See elsewhere for the complete list of allowed NAPI types.
+							Defines the type of the element as allowed by NeXus.
+
+							See :ref:`here&lt;Design-DataTypes&gt;` and :ref:`elsewhere&lt;nxdl-types&gt;` for the complete list of allowed types.
 						</xs:documentation>
 					</xs:annotation>
 				</xs:attribute>
diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd
index 9acef2c9bf..08541f9c80 100644
--- a/nxdlTypes.xsd
+++ b/nxdlTypes.xsd
@@ -435,16 +435,6 @@
 	<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 	<xs:simpleType name="primitiveType">
-		<xs:annotation>
-			<xs:documentation>
-				Valid names for the type attribute on fields and attributes. 
-				This is an alias for NAPI (which is any valid NeXus type).
-			</xs:documentation>
-		</xs:annotation>
-		<xs:list itemType="nxdl:NAPI" />
-	</xs:simpleType>
-	
-	<xs:simpleType name="NAPI">
 		<xs:annotation>
 			<xs:documentation>any valid NeXus type</xs:documentation>
 		</xs:annotation>
diff --git a/utils/nxdl_desc2rst.py b/utils/nxdl_desc2rst.py
index e2a4c4e4a9..8af388d076 100755
--- a/utils/nxdl_desc2rst.py
+++ b/utils/nxdl_desc2rst.py
@@ -384,6 +384,17 @@ def getDocFromNode(ns, node, retval=None):
             if not len(line[:indent].strip()) == 0:
                 raise "Something wrong with indentation on this line:\n" + line
             text += '\n' + line[indent:]
+
+    # substitute HTML entities in markup: "<" for "&lt;"
+    # thanks: http://stackoverflow.com/questions/2087370/decode-html-entities-in-python-string
+    try:		# see #661
+        import html
+        text = html.unescape(text)
+    except (ImportError, AttributeError):
+        from six.moves import html_parser as HTMLParser
+        htmlparser = HTMLParser.HTMLParser()
+        text = htmlparser.unescape(text)
+
     return text.lstrip()
 
 
diff --git a/utils/types2rst.py b/utils/types2rst.py
index 5e6673e72c..cdf6d5af50 100755
--- a/utils/types2rst.py
+++ b/utils/types2rst.py
@@ -12,7 +12,7 @@
 
 
 if __name__ == '__main__':
-    units2rst.worker('NAPI', section = 'data')
+    units2rst.worker('primitiveType', section = 'data')
 
 
 # NeXus - Neutron and X-ray Common Data Format

From 0fa6d64f7b57bec4402b21d765d2c0ca12968501 Mon Sep 17 00:00:00 2001
From: Peter Chang <peter.chang@diamond.ac.uk>
Date: Thu, 23 Jan 2020 13:14:23 -0600
Subject: [PATCH 2/2] Tweak single phrase

---
 nxdlTypes.xsd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd
index 08541f9c80..f0bd5a80b6 100644
--- a/nxdlTypes.xsd
+++ b/nxdlTypes.xsd
@@ -436,7 +436,7 @@
 
 	<xs:simpleType name="primitiveType">
 		<xs:annotation>
-			<xs:documentation>any valid NeXus type</xs:documentation>
+			<xs:documentation>any valid NeXus field or attribute type</xs:documentation>
 		</xs:annotation>
 		<xs:union memberTypes="
 			nxdl:NX_CHAR