Skip to content

Commit 71772e3

Browse files
hawc2hawc2
authored
Update software section for TEI encoding lesson
Reorganize section on software for text encoding and TEI.
1 parent e804ae8 commit 71772e3

File tree

1 file changed

+56
-57
lines changed

1 file changed

+56
-57
lines changed

‎en/lessons/encoding-texts-tei-1.md‎

Lines changed: 56 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -46,62 +46,6 @@ There are many ways to encode a text. For example, we can wrap the names of peop
4646

4747
In this lesson, we will learn to encode texts using a computer language specifically designed for them: TEI (Text Encoding Initiative)](https://tei-c.org/).
4848

49-
### Software for Text Encoding
50-
51-
Any plain text editor (`.txt` format) will work for everything you will learn to do in this lesson. Notepad for Windows, for example, is perfectly suited for these tasks. However, there are text editors that offer tools and functionalities designed to facilitate encoding with XML (Extensible Markup Language), and even with TEI. The most frequently used software is (Oxygen XML Editor)[https://www.oxygenxml.com/], available for Windows, MacOS, and Linux. However, it is not a free software, so we are not using it in this lesson.
52-
53-
For this lesson, we use the editor Visual Studio Code (VS Code, for short), which is free and compatible with Windows, MacOS, and Linux.
54-
55-
To get started, download the most [recent version of VS Code](https://code.visualstudio.com/download) and install it on your computer. Open it and you will encounter a screen like this:
56-
57-
{% include figure.html filename="en-tr-encoding-texts-tei-1-01.png" alt="Initial window of Visual Studio Code" caption="Figure 1. VS Code initial view." %}
58-
59-
Now you can install a VS Code extension for working more easily with XML and TEI-XML documents: Scholarly XML. You can click the [Scholarly XML link](https://perma.cc/3SY8-Z5Z4) to install the extension if you already have VS Code installed, or you can follow the walkthrough.
60-
61-
To do this, click the _Extensions_ button in the toolbar on the left side of the window:
62-
63-
{% include figure.html filename="en-tr-encoding-texts-tei-1-02.png" alt="Side panel of VS Code with button for extensions higlighted" caption="Figure 2. VS Code extensions." %}
64-
65-
Type 'Scholarly XML' in the search bar.
66-
67-
{% include figure.html filename="en-tr-encoding-texts-tei-1-03.png" alt="Side panel of VS Code showing extensions marketplace with search for scholarly XML highlighted" caption="Figure 3. Search for an extension in VS Code." %}
68-
69-
{% include figure.html filename="en-tr-encoding-texts-tei-1-04.png" alt="Side panel of VS Code showing the Scholarly XML extension with its install button higlighted" caption="Figure 4. Install Scholarly XML in VS Code." %}
70-
71-
To learn more about Scholarly XML, you can [read about it on the Visual Studio Code Marketplace](https://perma.cc/3SY8-Z5Z4) or [view its code repository on GitHub](https://perma.cc/KS74-A5B3). For now, we will highlight several things the Scholarly XML extension allows you to do with the code:
72-
73-
First, if you select any of the text in an XML document, you can use a keyboard shortcut to automatically enclose the text in an XML element in opening and closing tags. Well-formed XML--that is, code that is structurally sound and able to be processed--requires every XML tag to be closed. When you hit 'ctrl+E' (on Windows or Linux) or 'cmd+E' (on MacOS), VS code will open a window with the instruction _Enter abbreviation (Press Enter to confirm or Escape to cancel)_. Next, write the name of the element and hit the _enter_ key. The editor will then enclose the selected text between opening and closing tags. When we work with XML, automatically creating the opening and closing tags can save us a lot of time while also decreasing the likelihood of introducing typos.
74-
75-
{% include figure.html filename="en-tr-encoding-texts-tei-1-05.png" alt="Name element highlighted in the search bar and in the body of the code" caption="Figure 5. Automatically Introduce an XML element in VS Code." %}
76-
77-
Second, we can use the Scholarly XML extension to determine whether the document is structurally 'well-formed' following the syntax of XML--whether all text is inside those open and close tags and whether those tags are properly nested. The extension can also check whether the document is semantically 'valid' per the type of [RELAX NG](https://en.wikipedia.org/wiki/RELAX_NG) validation schema being used, such as the TEI schema (tei-all). We will explain the concepts of being 'structurally well-formed' vs 'semantically valid' below. The extension checks for both structural well-formedness and semantic validity automatically.
78-
79-
{% include figure.html filename="en-tr-encoding-texts-tei-1-06.png" alt="XML error in the body of the code marked with a red underline" caption="Figure 6. Automatically identify XML errors in VS Code." %}
80-
81-
To perform the second type of validation, the document must start with an XML Processing Instruction (`<?xml-model>`) followed by the URL of the schema you want to use, like this:
82-
83-
```
84-
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
85-
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml"
86-
schematypens="http://purl.oclc.org/dsdl/schematron"?>
87-
```
88-
89-
You can download the basic [template of a TEI-XML document](https://www.tei-c.org/release/doc/tei-p5-doc/en/html/examples-TEI.html), with these lines included.
90-
91-
Third, the Scholarly XML extension offers tools to autocomplete the XML code as part of the validation for the schema RELAX NG. For example, if you introduce the element `<l>` (used to mark a line of poetry), you can hit the space bar after the opening `<l>` and VS Code will show a list of possible attributes to select from the menu:
92-
93-
{% include figure.html filename="en-tr-encoding-texts-tei-1-07.png" alt="Popup menu of attributes that appears after beginning to type an element" caption="Figure 7. Menu of autocomplete options while encoding XML in VS Code." %}
94-
95-
Now, in order to use Scholarly XML or other VS Code extensions, it is necessary to check that the editor isn’t in restricted mode, as it appears in this window:
96-
97-
{% include figure.html filename="en-tr-encoding-texts-tei-1-08.png" alt="Popup notification along the top of the screen warning that the program is running in restricted mode" caption="Figure 8. The 'restricted mode' notice in VS Code." %}
98-
99-
This mode prevents extensions or document code from executing instructions that could damage our computer. Because we are working with a trusted extension, we can deactivate the restricted mode by clicking the hyperlink above that says _Manage_ and then the button that says _Trust_.
100-
101-
{% include figure.html filename="en-tr-encoding-texts-tei-1-09.png" alt="Popup window with that allows the user to exit restriced mode and choose to work in a trusted window" caption="Figure 9. Exit restricted mode in VS Code." %}
102-
103-
Now that you have configured our editing software, you can start to work in TEI-XML.
104-
10549
## Visualization vs. Categorization
10650
Those who are familiar with the markup language Markdown--common today in online technical forums, as well as in GitHub, GitLab, and other code repositories--will surely recognize the use of elements like asterisks (`*`), underscores (`_`), and number signs (`#`) to make text appear a certain way in a browser. For example, text wrapped in single asterisks will be shown in italics, and text wrapped in double asterisks will be in bold. In fact, the text of this lesson is written in Markdown following these conventions.
10751

@@ -170,8 +114,63 @@ The difference between the plain text and the encoded version for this part of t
170114

171115
Now, all of this and much more is possible only by virtue of the fact that we have made explicit, thanks to TEI, the content of those sonnets. If you only had their plain text versions, it would be technically impossible to leverage computing tools designed for editing, transforming, visualizing, analyzing, and publishing.
172116

117+
### Software for Text Encoding
118+
Any plain text editor (`.txt` format) will work for everything you will learn to do with TEI in this lesson. Notepad for Windows, for example, is perfectly suited for these tasks. However, there are text editors that offer tools and functionalities designed to facilitate encoding with XML (Extensible Markup Language), and even with TEI. The most frequently used software is (Oxygen XML Editor)[https://www.oxygenxml.com/], available for Windows, MacOS, and Linux. However, it is not a free software, so we are not using it in this lesson.
119+
120+
For this lesson, we use the editor Visual Studio Code (VS Code, for short), which is free and compatible with Windows, MacOS, and Linux.
121+
122+
To get started, download the most [recent version of VS Code](https://code.visualstudio.com/download) and install it on your computer. Open it and you will encounter a screen like this:
123+
124+
{% include figure.html filename="en-tr-encoding-texts-tei-1-01.png" alt="Initial window of Visual Studio Code" caption="Figure 1. VS Code initial view." %}
125+
126+
Now you can install a VS Code extension for working more easily with XML and TEI-XML documents: Scholarly XML. You can click the [Scholarly XML link](https://perma.cc/3SY8-Z5Z4) to install the extension if you already have VS Code installed, or you can follow the walkthrough.
127+
128+
To do this, click the _Extensions_ button in the toolbar on the left side of the window:
129+
130+
{% include figure.html filename="en-tr-encoding-texts-tei-1-02.png" alt="Side panel of VS Code with button for extensions higlighted" caption="Figure 2. VS Code extensions." %}
131+
132+
Type 'Scholarly XML' in the search bar.
133+
134+
{% include figure.html filename="en-tr-encoding-texts-tei-1-03.png" alt="Side panel of VS Code showing extensions marketplace with search for scholarly XML highlighted" caption="Figure 3. Search for an extension in VS Code." %}
135+
136+
{% include figure.html filename="en-tr-encoding-texts-tei-1-04.png" alt="Side panel of VS Code showing the Scholarly XML extension with its install button higlighted" caption="Figure 4. Install Scholarly XML in VS Code." %}
137+
138+
To learn more about Scholarly XML, you can [read about it on the Visual Studio Code Marketplace](https://perma.cc/3SY8-Z5Z4) or [view its code repository on GitHub](https://perma.cc/KS74-A5B3). For now, we will highlight several things the Scholarly XML extension allows you to do with the code:
139+
140+
First, if you select any of the text in an XML document, you can use a keyboard shortcut to automatically enclose the text in an XML element in opening and closing tags. Well-formed XML--that is, code that is structurally sound and able to be processed--requires every XML tag to be closed. When you hit 'ctrl+E' (on Windows or Linux) or 'cmd+E' (on MacOS), VS code will open a window with the instruction _Enter abbreviation (Press Enter to confirm or Escape to cancel)_. Next, write the name of the element and hit the _enter_ key. The editor will then enclose the selected text between opening and closing tags. When we work with XML, automatically creating the opening and closing tags can save us a lot of time while also decreasing the likelihood of introducing typos.
141+
142+
{% include figure.html filename="en-tr-encoding-texts-tei-1-05.png" alt="Name element highlighted in the search bar and in the body of the code" caption="Figure 5. Automatically Introduce an XML element in VS Code." %}
143+
144+
Second, we can use the Scholarly XML extension to determine whether the document is structurally 'well-formed' following the syntax of XML--whether all text is inside those open and close tags and whether those tags are properly nested. The extension can also check whether the document is semantically 'valid' per the type of [RELAX NG](https://en.wikipedia.org/wiki/RELAX_NG) validation schema being used, such as the TEI schema (tei-all). We will explain the concepts of being 'structurally well-formed' vs 'semantically valid' below. The extension checks for both structural well-formedness and semantic validity automatically.
145+
146+
{% include figure.html filename="en-tr-encoding-texts-tei-1-06.png" alt="XML error in the body of the code marked with a red underline" caption="Figure 6. Automatically identify XML errors in VS Code." %}
147+
148+
To perform the second type of validation, the document must start with an XML Processing Instruction (`<?xml-model>`) followed by the URL of the schema you want to use, like this:
149+
150+
```
151+
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
152+
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml"
153+
schematypens="http://purl.oclc.org/dsdl/schematron"?>
154+
```
155+
156+
You can download the basic [template of a TEI-XML document](https://www.tei-c.org/release/doc/tei-p5-doc/en/html/examples-TEI.html), with these lines included.
157+
158+
Third, the Scholarly XML extension offers tools to autocomplete the XML code as part of the validation for the schema RELAX NG. For example, if you introduce the element `<l>` (used to mark a line of poetry), you can hit the space bar after the opening `<l>` and VS Code will show a list of possible attributes to select from the menu:
159+
160+
{% include figure.html filename="en-tr-encoding-texts-tei-1-07.png" alt="Popup menu of attributes that appears after beginning to type an element" caption="Figure 7. Menu of autocomplete options while encoding XML in VS Code." %}
161+
162+
Now, in order to use Scholarly XML or other VS Code extensions, it is necessary to check that the editor isn’t in restricted mode, as it appears in this window:
163+
164+
{% include figure.html filename="en-tr-encoding-texts-tei-1-08.png" alt="Popup notification along the top of the screen warning that the program is running in restricted mode" caption="Figure 8. The 'restricted mode' notice in VS Code." %}
165+
166+
This mode prevents extensions or document code from executing instructions that could damage our computer. Because we are working with a trusted extension, we can deactivate the restricted mode by clicking the hyperlink above that says _Manage_ and then the button that says _Trust_.
167+
168+
{% include figure.html filename="en-tr-encoding-texts-tei-1-09.png" alt="Popup window with that allows the user to exit restriced mode and choose to work in a trusted window" caption="Figure 9. Exit restricted mode in VS Code." %}
169+
170+
Now that you have configured our editing software, you can start to work in TEI-XML.
171+
173172
## A Minimal TEI Document
174-
Now, let’s examine the following minimal document of TEI:
173+
To get started, let’s examine the following minimal document of TEI:
175174

176175
```
177176
<?xml version="1.0" encoding="UTF-8"?>

0 commit comments

Comments
 (0)