Read Me

********************************************************************************
* Guidelines README                                                            *
********************************************************************************

What it is:

	The EpiDoc Guidelines is a prose document intended to provide
	complete guidance for the application of TEI markup to the preparation
	of digital editions of primary source documents like inscriptions or
	papyri.
	The canonical version of the Guidelines are also available in HTML at 
	http://www.stoa.org/epidoc/gl/latest/

License:

	The EpiDoc Guidelines is copyright the contributors. 
	See LICENSE.txt for license details.

To cite the EpiDoc Guidelines, please use the following information:

	Tom Elliott, Gabriel Bodard, Elli Mylonas, Simona Stoyanova, Charlotte Tupman,
	Scott Vanderbilt, et al. (2007-2017), EpiDoc Guidelines: Ancient documents in
	TEI XML (Version 8). Available: http://www.stoa.org/epidoc/gl/latest/.

Technical requirements and limitations:

	The Guidelines consist of XML files in TEI P5 (see guidelines/xml/), and as such
	they need to be transformed using a combination of the TEI XSLT 
	provided here and the example XSLT, for which see example-p5-xslt. 
	The Guidelines are part of the TEI ODD.
          
How to use it:

    Validation:
    
        Validation of the XML files that comprise the guidelines is accomplished 
            using an NVDL script (guidelines/schema/epidoc.nvdl). This script makes
            use of the most recent TEI ODD schema, accessible via the following URI:
                http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_odds.rng
            It also makes use of a locally modified version of the EpiDoc schema,
            which is stored in guidelines/schema/tei-epidoc-examples.rng . This 
            modified version may be generated by running the transform in 
            guidelines/schema/schema2egSchema.xsl against the current version
            of the EpiDoc schema. It copies the contents of the schema, modifying 
            the namespace to match that of the <egXML> element and replaces the
            top-level content model from TEI's strict hierarchical structure to a 
            permissive structure in which mixed content involving any combination
            of TEI tags may appear as the direct children of <egXML>. Below that
            level, all validation requirements of the TEI are enforced. This permits
            validation of all content in the guidelines files, as well as tag assist and
            has been tested in OxygenXML. Whenever the EpiDoc schema is revised,
            the example schema used here should be regenerated to ensure an
            exact match. It may be possible in future to modify the NVDL script to 
            perform this update automatically, but at present we'll have to live with
            this manual step. A transformation configuration has been added to 
            the Oxygen project file (EpiDoc Schema to egXML Schema).

          

    Generate HTML Guidelines from XML files
    
        1. Make sure you have a full checkout of the SVN repository.
        2. *IMPORTANT*
           Make a copy of the Oxygen project file guidelines/Guidelines-generation-project.xpreg
           and name it guidelines/Guidelines-generation-project.xpr. This is necessary because
           the project file is changed by using it. When you are finished, you can discard the
           new project file.
        3. Open OxygenXML and open the project file: 
            guidelines/Guidelines-generation-project.xpr
        4. Open the xml file: guidelines/xml/driver.xml
	5. If you need to run all the XML transforms (this is your first run,
	   or you've changed content) then run the XSLT transformation scenarios:
		* Generate DDBDP Examples
		* Generate Dohnicht Examples
		* Generate EDH Web Examples
		* Generate IOSPE Examples
		* Generate London Examples
		* Generate Panciera Examples
		* Generate Petrae Examples
		* Generate RIB Examples
		* Generate Seg Examples
		* Generate Verse Examples
		* Generate Copy Example Template
        6. Run the guidelines generation XSLT scenario against it (Scenario called:
           "EpiDoc P5 Guidelines HTML")
        7. Results of the transformation will be output to guidelines/output/