|
| 1 | +--- |
| 2 | +layout: page.njk |
| 3 | +title: "Using the TEI GitHub Repository" |
| 4 | +--- |
| 5 | +# Using the TEI GitHub Repository |
| 6 | +Introduction |
| 7 | +------------ |
| 8 | + |
| 9 | + |
| 10 | +The TEI makes its development files openly available on <https://github.com/TEIC> so that users can try out |
| 11 | +the latest developments and provide feedback about how they |
| 12 | +think the TEI should develop. This document aims to give a |
| 13 | +brief introduction to using these files directly from the TEI |
| 14 | +GitHub git Repository in which they are kept. However, it is not |
| 15 | +necessary to learn how to use the Repository if you simply want |
| 16 | +to use the most stable versions of the various TEI products. |
| 17 | + |
| 18 | +About Version Control |
| 19 | +--------------------- |
| 20 | + |
| 21 | + |
| 22 | +The Repository uses a Version Control System known as |
| 23 | +git. This tool, like its predecessors CVS |
| 24 | +(Concurrent Versions System) and SVN (Subversion), |
| 25 | +is a content versioning tool used |
| 26 | +by many software developers to keep track of changes within |
| 27 | +their source code tree. Git provides the means to store |
| 28 | +not only the current version of a file, but a record of all |
| 29 | +changes (and who made those changes) that have occurred to that |
| 30 | +file. Use of git is particularly common on projects |
| 31 | +whose development is being undertaken by those in disparate |
| 32 | +geographical locations, or with multiple developers, since it |
| 33 | +ensures that changes made by one person are not accidentally |
| 34 | +removed when another person posts their changes to the source |
| 35 | +tree. |
| 36 | +The GitHub site provides more detailed [information |
| 37 | +about Git](https://help.github.com/articles/set-up-git/) and how to use it. |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | + |
| 42 | +Checking files out of the Repository |
| 43 | +------------------------------------ |
| 44 | + |
| 45 | + |
| 46 | +To check out the contents of a TEI GitHub Repository |
| 47 | +with a simple Unix git client, enter a command like |
| 48 | +this: |
| 49 | +`git clone https://github.com/TEIC/TEI.git ./TEI` |
| 50 | +This will copy all files from the TEI repository into the |
| 51 | +directory ./TEI. |
| 52 | + |
| 53 | + |
| 54 | +You can also browse the whole Repository using |
| 55 | +GitHub's [web\-based Repository viewer](https://github.com/TEIC/TEI). |
| 56 | + |
| 57 | + |
| 58 | + |
| 59 | + |
| 60 | +TEIC Packages |
| 61 | +------------- |
| 62 | + |
| 63 | + |
| 64 | +The TEIC Repository contains files which are grouped into a |
| 65 | +small number of discrete packages for release. The following |
| 66 | +packages are currently maintained: |
| 67 | +* [TEI P5](#P5) |
| 68 | + + TEI P5 Guidelines and Schema |
| 69 | +* [Stylesheets](#Stylesheets) |
| 70 | + + TEI XSLT Stylesheets Development Module |
| 71 | +* [Roma](#Roma) |
| 72 | + + TEI\-Conformant Validator (DTD, RELAX NG or W3C Schema) |
| 73 | + Creator Development |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +### Prerequisites for use of TEI Modules |
| 80 | + |
| 81 | + |
| 82 | +These packages and their associated Makefiles and scripts are |
| 83 | +all developed and tested on a Debian Linux system. While they |
| 84 | +should work (possibly with customization) on other \*NIX |
| 85 | +systems (including OSX), they are not designed to work on Microsoft Windows. |
| 86 | +If you want to use the scripts provided with these packages, |
| 87 | +we recommend you to install the following additional software |
| 88 | +packages: |
| 89 | + |
| 90 | + |
| 91 | +* ant |
| 92 | +* jing |
| 93 | +* perl |
| 94 | +* saxon |
| 95 | +* trang |
| 96 | +* xmllint |
| 97 | +* xsltproc |
| 98 | + |
| 99 | + |
| 100 | + |
| 101 | + |
| 102 | +### P5 Guidelines and Schema Development Package |
| 103 | + |
| 104 | + |
| 105 | +This package contains the source files for the development |
| 106 | +version of the TEI Guidelines and associated schemas. Inside the |
| 107 | +TEIC/TEI repository the sources of the English chapters of the Guidelines are in |
| 108 | +`P5/Source/Guidelines/en/`. To allow for |
| 109 | +internationalization, if translations of the |
| 110 | +Guidelines are made available they will be located in the same |
| 111 | +place but under their ISO two\-letter language code. The source |
| 112 | +files of the Guidelines also reference separate specifications of |
| 113 | +elements, attributes and classes which are maintained in a |
| 114 | +separate directory `P5/Source/Specs/` with |
| 115 | +internationlization handled internally. All of these files are |
| 116 | +in the TEI ODD (One Document Does it all) |
| 117 | +format. This is a TEI format specifically intended for writing |
| 118 | +guidelines about encoding, from which schemas and reference |
| 119 | +documentation can be automatically generated. |
| 120 | +As part of the P5 module, a Makefile is provided to |
| 121 | +help generate HTML versions of the TEI |
| 122 | +Guidelines, create compiled schemas, and various other |
| 123 | +possibilities. There are a number of variables that one can |
| 124 | +change at the beginning of the Makefile. Some of the more |
| 125 | +important of these are: |
| 126 | + |
| 127 | + |
| 128 | +PREFIX |
| 129 | + |
| 130 | + |
| 131 | +* + This is the default location under which you wish to |
| 132 | + install files locally if you use the |
| 133 | + 'install' target. By default this is: /usr |
| 134 | + |
| 135 | + |
| 136 | +XSL |
| 137 | +* + This is the location of the XSLT stylesheets required |
| 138 | + for the transformation of ODD files. By default this points |
| 139 | + to the location of the stylesheets as installed by the TEI |
| 140 | + Debian Packages: /usr/share/xml/tei/stylesheet however, if you want to |
| 141 | + use a remote copy of the stylesheets you may wish to change |
| 142 | + this. One option is to use the stylesheets on the TEI |
| 143 | + website: [http://www.tei\-c.org/release/xml/tei/stylesheet/](/release/xml/tei/stylesheet/) as |
| 144 | + the value of this variable. |
| 145 | + |
| 146 | + |
| 147 | +ROMAOPTS |
| 148 | +* + This variable is used to pass options to Roma such as the |
| 149 | + local source file for the TEI Guidelines. By default this is |
| 150 | + "`--localsource=${DRIVER}.xml`" |
| 151 | + |
| 152 | + |
| 153 | +DRIVER |
| 154 | +* This points to the available local source file for the |
| 155 | +TEI Guidelines. By default this is |
| 156 | +"`${LANGTREE}/guidelines-${LANGUAGE}.xml`", and changing |
| 157 | +LANGTREE and LANGUAGE would allow the generation of the |
| 158 | +guidelines in different languages if the source files for |
| 159 | +those languages exist. |
| 160 | + |
| 161 | + |
| 162 | +The makefile has a number of requirements, these include |
| 163 | +internet access (or a local copy of the stylesheets), and |
| 164 | +up\-to\-date versions of the ant, perl, jing, trang, saxon, xmllint and |
| 165 | +xsltproc programs. If you do not have these installed then many |
| 166 | +of the make targets will not work. Fortunately, there is a target |
| 167 | +which will check to make sure you have these installed: |
| 168 | +`make check`. Some of the more important targets are |
| 169 | +listed below: |
| 170 | +* Makefile Targets |
| 171 | + + checkUsage: `make check`This target checks to see whether you have ant perl, jing, |
| 172 | + trang, xmllint, saxon, and xsltproc installed. |
| 173 | + + defaultUsage: `make`This is the default target and creates the TEI P5 schemas |
| 174 | + in RELAX NG \& DTD and the HTML version of the |
| 175 | + Guidelines. |
| 176 | + + convertUsage: `make convert`This target creates the TEI P5 schemas in RELAX NG |
| 177 | + \& DTD. |
| 178 | + + dtdsUsage: `make dtds`This target creates DTDs for TEI P5 in the DTD/ directory. |
| 179 | + + schemasUsage: `make schemas`This target creates RELAX NG Schemas for TEI P5 in the |
| 180 | + Schema/ directory. |
| 181 | + + html\-webUsage: `make html-web`This target creates an HTML version of the TEI Guidelines |
| 182 | + in the Guidelines/ directory. |
| 183 | + + xmlUsage: `make xml`This target creates a TEI Lite (P5\) XML version of the |
| 184 | + Guidelines as Guidelines.xml in the current directory (i.e., |
| 185 | + P5/) as well as also making the exemplars discussed |
| 186 | + below. |
| 187 | + + splitUsage: `make split`This target creates a set of TEI P5 ODD files, with entities |
| 188 | + resolved, that are a version of the Guidelines split into |
| 189 | + chapters, in the split/ directory. |
| 190 | + |
| 191 | + |
0 commit comments