From 67be99d28d7fc0f2f880ca2aa511733cfdaff93d Mon Sep 17 00:00:00 2001
From: Terry Catapano <thc4ster@gmail.com>
Date: Wed, 1 Feb 2023 15:02:13 +0100
Subject: [PATCH] #72: format taxpubcustom-elements documentation for
 dtddocumentor

---
 samples/test_tp1-3.xml           |   2 +-
 taxpubcustom-elements-NS0-v1.ent | 189 ++++++++++++++-----------------
 2 files changed, 84 insertions(+), 107 deletions(-)

diff --git a/samples/test_tp1-3.xml b/samples/test_tp1-3.xml
index 19acb53..170a4cd 100644
--- a/samples/test_tp1-3.xml
+++ b/samples/test_tp1-3.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE tp:taxon-treatment SYSTEM "../tax-treatment-NS0-v1_flat.dtd">
+<!DOCTYPE tp:taxon-treatment SYSTEM "http://taxpub.org/v1-0/schema/tax-treatment-NS0-v1_flat.dtd">
 <tp:taxon-treatment xmlns:tp="http://www.plazi.org/taxpub">
     <tp:treatment-meta>
         <contrib-group>
diff --git a/taxpubcustom-elements-NS0-v1.ent b/taxpubcustom-elements-NS0-v1.ent
index ab6b9ad..725d875 100644
--- a/taxpubcustom-elements-NS0-v1.ent
+++ b/taxpubcustom-elements-NS0-v1.ent
@@ -12,201 +12,187 @@ Delivered as file "taxpubcustom-elements-NS0-v1.ent"                       -->
 					%jats-common-atts;
 					%taxpub-namespace-att; 
 					auth-code		CDATA			#IMPLIED >
-<!--
-~tp:taxon-treatment~
-~note: A publication or or section of a publication documenting the features or distribution
+<!--~~ <tp:taxon-treatment>
+note: A publication or or section of a publication documenting the features or distribution
             of a related group of organisms (called a "taxon", plural "taxa") in ways adhering to
             highly formalized conventions. ~
 ~~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:treatment-meta      %sec-meta-model;	>
 <!ATTLIST    tp:treatment-meta
 					%jats-common-atts; >
-<!--
-~tp:treatment-meta~
-~note: Bibliographic metadata describing at taxonomic treatment ~
+<!--~~ <tp:treatment-meta>
+note: Bibliographic metadata describing at taxonomic treatment ~
 ~~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:nomenclature  			%nomenclature-model;	>
 <!ATTLIST 	tp:nomenclature
 					%jats-common-atts; >
-<!--
-~tp:nomenclature~
-~note: The heading of a taxonomic treatment, with element only content containing the scientific name of the taxon
+<!--~~ <tp:nomenclature>
+note: The heading of a taxonomic treatment, with element only content containing the scientific name of the taxon
             described by the treatment, and possibly the authority for the taxon, citations to
             previous descriptions, designations of type-genus, and type-species, and other
             information. ~
 ~~
 ~~
 
--->
+~~-->
 
 
 <!ELEMENT	tp:mixed-nomenclature  	%mixed-nomenclature-model;  	>
 <!ATTLIST 	tp:mixed-nomenclature
 					%jats-common-atts; >
-<!--
-~tp:mixed-nomenclature~
-~note: The heading of a taxonomic treatment, with possibly mixed content containing text the scientific name of the taxon
+<!--~~ <tp:mixed-nomenclature>
+note: The heading of a taxonomic treatment, with possibly mixed content containing text the scientific name of the taxon
             described by the treatment, and possibly the authority for the taxon, citations to
             previous descriptions, designations of type-genus, and type-species, and other
             information.  ~
 ~~
 ~~
 
--->
+~~-->
 
 
 <!ELEMENT	tp:treatment-sec        %taxon-sec-model;	>
 <!ATTLIST   tp:treatment-sec
 					%sec-atts; >
-<!--
-~tp:treatment-sec~
-~note: A section of a taxonomic treatment. For example, diagnosis, materials examined,
+<!--~~ <tp:treatment-sec>
+note: A section of a taxonomic treatment. For example, diagnosis, materials examined,
             etymology, etc,,, ~
 ~~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:taxon-authority			(#PCDATA | object-id | tp:taxon-authority-part)*  >
 <!ATTLIST	tp:taxon-authority
 					%jats-common-atts;
 					role			CDATA		#IMPLIED>
-<!--
-~tp:taxon-authority~
-~note: Elements that are linked to the name in the original treatment of a taxon as
+<!--~~ <tp:taxon-authority>
+note: Elements that are linked to the name in the original treatment of a taxon as
             designated by the authors of the respective original publication. ~
-~modelNote: This can be anything from a single author to a whole string including author,
+~
+~~ model This can be anything from a single author to a whole string including author,
             year, publication page, etc.. Formica rufa L. or Formica rufa Linnaeus 1758:580 ~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:taxon-authority-part			(#PCDATA | object-id | tp:taxon-authority-part)* >
 <!ATTLIST	tp:taxon-authority-part
 					%jats-common-atts;
 					tp:taxon-authority-part-type			CDATA		#IMPLIED>
-<!--
-~tp:taxon-authority-part~
-~note: An element that is linked to the name in the original treatment of a taxon as
+<!--~~ <tp:taxon-authority-part>
+note: An element that is linked to the name in the original treatment of a taxon as
             designated by the authors of the respective original publication. ~
-~modelNote: This is a single element in of the taxon-authority element. er.g. a single author
+~~ model This is a single element in of the taxon-authority element. er.g. a single author
             (Linnaeus), the year of publication (1758) >~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:taxon-status			(#PCDATA) >
 <!ATTLIST	tp:taxon-status
 				%jats-common-atts;
 				%might-link-atts;		>
-<!--
-~tp:taxon-status~
-~note: The nomenclatorial status of a particular taxon. ~
-~modelNote: This can designate an act that happened in an earlier, but cited citation, or
+<!--~~ <tp:taxon-status>
+note: The nomenclatorial status of a particular taxon. ~
+~~ model This can designate an act that happened in an earlier, but cited citation, or
             that happens within this treatment. Eg syn. vs. syn. nov.: The former refers to a
             synonymy made, the latter to a synonym being proposed in the actual treatment. ~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:taxon-identifier			(#PCDATA) >
 <!ATTLIST	tp:taxon-identifier
 				%jats-common-atts;
 				%might-link-atts;		>
-<!--
-~tp:taxon-identifier~
-~note: A standard identifier associated with a particular taxon. ~
-~modelNote: The taxon-identifier could be a LSID or other GUID ~
+<!--~~ <tp:taxon-identifier>
+note: A standard identifier associated with a particular taxon. ~
+~~ model The taxon-identifier could be a LSID or other GUID ~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:nomenclature-citation-list			(#PCDATA | tp:taxon-name | tp:nomenclature-citation)* >
 <!ATTLIST 	tp:nomenclature-citation-list
 					%jats-common-atts;
 					content-type		CDATA		#IMPLIED >
-<!--
-~tp:nomenclature-citation-list~
-~note: A section in a treatment that includes the citation of one or several previous
+<!--~~ <tp:nomenclature-citation-list>
+note: A section in a treatment that includes the citation of one or several previous
             treatments of the taxon. ~
 ~~
 ~~
 
--->
+~~-->
 <!ELEMENT	tp:nomenclature-citation	(#PCDATA | tp:taxon-name | tp:taxon-authority | tp:type-genus | tp:type-species | mixed-citation | xref |  tp:material-citation | tp:taxon-status | comment )* >
 <!ATTLIST 	tp:nomenclature-citation
 					%jats-common-atts;
 					content-type		CDATA		#IMPLIED >
-<!--
-~tp:nomenclature-citation~
-~note: The citation of a nomenclatorial act or other citation of the taxon in the published
+<!--~~ <tp:nomenclature-citation>
+note: The citation of a nomenclatorial act or other citation of the taxon in the published
             record. ~
 ~~
 ~~
 
--->						
+~~-->						
 
 <!ELEMENT	tp:type-genus				(tp:taxon-name, tp:material-location?) >
 <!ATTLIST    tp:type-genus
 					%jats-common-atts;     >
-<!--
-~tp:type-genus~
-~note: The species selected as the reference species at the moment of the description of a
+<!--~~ <tp:type-genus>
+note: The species selected as the reference species at the moment of the description of a
             new genus level taxon. ~
 ~~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:type-species			(tp:taxon-name, tp:material-location?) >
 <!ATTLIST    tp:type-species
 					%jats-common-atts;     >
-<!--
-~tp:type-species~
-~note: The specimen upon which the species or infraspecific level taxon is based and which is
+<!--~~ <tp:type-species>
+note: The specimen upon which the species or infraspecific level taxon is based and which is
             explicitly designated as the holotype. ~
-~modelNote: The status is defined by the code, of which the designation as holotype is
+~~ model The status is defined by the code, of which the designation as holotype is
             requested to create an available name , lectotype the selection of a type from a series
             of syntypes and neotype the designation of a new type. These designations are ruled by
             the Code (see ICZN ). The designation of paratypes, androtypes is arbitrary. ~
 ~~
 
--->
+~~-->
 
 
 <!ELEMENT	tp:type-status		           (#PCDATA  | object-id)*  >
 <!ATTLIST	tp:type-status
 						%jats-common-atts;
 						designation    (y|n)		'n' >
-<!--
-~tp:type-status~
+<!--~~ <tp:type-status>
 ~~
 ~~
 ~~
 
--->
+~~-->
 <!ELEMENT	tp:taxon-type-location  	(#PCDATA  | object-id)* >
 <!ATTLIST	tp:taxon-type-location
 						%jats-common-atts;        >
-<!--
-~tp:taxon-type-location~
-~note: The institution where a type specimen is housed. ~
-~modelNote: From a nomenclatorial point of view the name of depositary institution of the
+<!--~~ <tp:taxon-type-location>
+note: The institution where a type specimen is housed. ~
+~~ model From a nomenclatorial point of view the name of depositary institution of the
             holotype has to be explicitely mentioned in a treatment of a new species level taxon in
             order to create an available name. Acronoyms of the institutions can be used. The
             location of the institution has to be provided. Institutions can be private collections
             to public natural history museums. ~
 ~~
 
--->
+~~-->
 
 <!-- RED ELEMENTS -->
 
@@ -217,15 +203,14 @@ Delivered as file "taxpubcustom-elements-NS0-v1.ent"                       -->
 					auth-code		CDATA			#IMPLIED 
                     rank 		    CDATA			#IMPLIED
                     reg             CDATA           #IMPLIED >
- <!--
-~tp:taxon-name~
-~note: The name of a taxon. ~
-~modelNote: Generally this is a scientific name following the convention of the Codes ruling
+ <!--~~ <tp:taxon-name>
+note: The name of a taxon. ~
+~~ model Generally this is a scientific name following the convention of the Codes ruling
             nomenclature (eg International Code for Zoological Nomenclature (ICZN ), but if can also
             be a vernacular name as used in field guides. ~
 ~~
 
--->                                                      
+~~-->                                                      
 
 
 <!ELEMENT	tp:taxon-name-part		(#PCDATA  | tp:taxon-name-part | object-id)* >
@@ -233,92 +218,84 @@ Delivered as file "taxpubcustom-elements-NS0-v1.ent"                       -->
 				%jats-common-atts;
 				taxon-name-part-type		CDATA		#REQUIRED 
                 reg                         CDATA       #IMPLIED >
-<!--
-~tp:taxon-name-part~
-~note: A component of taxonomic name. For example, specific epithet, genus name, etc... ~
+<!--~~ <tp:taxon-name-part>
+note: A component of taxonomic name. For example, specific epithet, genus name, etc... ~
 ~~
 ~~
 
--->
+~~-->
 <!ELEMENT	tp:descriptive-statement	(#PCDATA | tp:descriptive-statement-part | object-id)* >
 <!ATTLIST	tp:descriptive-statement
 				    %jats-common-atts;
 					%might-link-atts;      >
-<!--
-~tp:descriptive-statement~
-~note: The description of a morphological trait.~
+<!--~~ <tp:descriptive-statement>
+note: The description of a morphological trait.~
 ~~
 ~~
 
--->
+~~-->
 <!ELEMENT    tp:descriptive-statement-part 	(#PCDATA | object-id)* >
 <!ATTLIST	tp:descriptive-statement-part
 					%jats-common-atts;
 					%might-link-atts;      >
-<!--
-~tp:descriptive-statement-part~
-~note: An individual component of a description morphological trait. ~
-~modelNote: This can be the character (e.g. head) or the character state (round, ovoid,
+<!--~~ <tp:descriptive-statement-part>
+note: An individual component of a description of a morphological trait. ~
+~~ model This can be the character (e.g. head) or the character state (round, ovoid,
             red,..) ~
 ~~
 
--->																						
+~~-->																						
 <!ELEMENT	tp:material-citation		(#PCDATA | named-content | tp:collecting-event  | object-id | tp:type-status | tp:material-location | tp:taxon-name | xref)*>
 <!ATTLIST	tp:material-citation
 					%jats-common-atts;
 					%might-link-atts;      >
-<!--
-~tp:material-citation~
-~note: A reference to biological material (e.g., a specimen, an observation) including those
+<!--~~ <tp:material-citation>
+note: A reference to biological material (e.g., a specimen, an observation) including those
             used as the basis of a taxonomic description. ~
-~modelNote: These can be very cursory to very detailed ("Costa Rica" to all the details
+~~ model These can be very cursory to very detailed ("Costa Rica" to all the details
             recorded during the collection). ~
 ~~
 
--->
+~~-->
 <!ELEMENT 	tp:material-location                (#PCDATA | object-id)* >
 <!ATTLIST	 tp:mayterial-location
 					%jats-common-atts;     >
-<!--
-~tp:material-location~
-~note: The physical location of the material referenced in the material citation. ~
-~modelNote: The material-location can be a collection given by its acronym (e.g. AMNH for
+<!--~~ <tp:material-location>
+note: The physical location of the material referenced in the material citation. ~
+~~ model The material-location can be a collection given by its acronym (e.g. AMNH for
             American Museum of Natural History, New York) ~
 ~~
 
--->
+~~-->
 <!ELEMENT 	tp:collecting-event		(#PCDATA | tp:collecting-location | date | tp:taxon-name | object-id | named-content)* >
 <!ATTLIST	 tp:collecting-event
 					%jats-common-atts;     >
-<!--
-~tp:collecting-event~
-~note: The specific spatio-temporal event during which observations have been made or
+<!--~~ <tp:collecting-event>
+note: The specific spatio-temporal event during which observations have been made or
             specimens have been collected. ~
-~modelNote: This can refer to a specific collection or many collections made. For example, if
+~~ model This can refer to a specific collection or many collections made. For example, if
             a Malaise trap is set and collected thousands of species, then the collecting-event
             remains the same for all the specimens. ~
 ~~
 
--->
+~~-->
 
 <!ELEMENT	tp:collecting-location		(object-id*, tp:location*, comment? ) >
 <!ATTLIST	tp:collecting-location
 					%jats-common-atts;     >
-<!--
-~tp:collecting-location~
-~note: The specific location or circumscription of the location of a collecting event. ~
+<!--~~ <tp:collecting-location>
+note: The specific location or circumscription of the location of a collecting event. ~
 ~~
 ~~
 
--->
+~~-->
 <!ELEMENT 	tp:location	(#PCDATA %country-elements;)*  >
 <!ATTLIST     tp:location                         
                                         %jats-common-atts;
                                         location-type             CDATA              #IMPLIED >
-<!--
-~tp:location~
-~note: A named spatial area. ~
+<!--~~ <tp:location>
+note: A named spatial area. ~
 ~~
 ~~
 
--->
+~~-->