Introduction to Encoding Texts in TEI (translation from spanish)

[hawc2]

Programming Historian in English has received a proposal for a translation from Spanish, 'Introduction to Encoding Texts in TEI,' by @ashlynstewart404.

I have circulated this proposal for feedback within the English team. We have considered this proposal for:

• Openness: we advocate for use of open source software, open programming languages and open datasets
• Global access: we serve a readership working with different operating systems and varying computational resources
• Multilingualism: we celebrate methodologies and tools that can be applied or adapted for use in multilingual research-contexts
• Sustainability: we're committed to publishing learning resources that can remain useful beyond present-day graphical user interfaces and current software versions

We are pleased to have invited @ashlynstewart404 to develop this Proposal into a Submission to be developed under the guidance of @semanticnoodles as editor.

The Submission package should include:

• Lesson text (written in Markdown)
  • For guidance, we recommend Sarah Simpkin's lesson Getting Started with Markdown
• Figures: images / plots / graphs (if using)
• Data assets: codebooks, sample dataset (if using)

We ask @ashlynstewart404 to share their Submission package with our Publishing team by email, copying in @semanticnoodles .

We've agreed a submission date of late April. We ask @ashlynstewart404 to contact us if they need to revise this deadline.

When the Submission package is received, our Publishing team will process the new lesson materials, and prepare a Preview of the initial draft. They will post a comment in this Issue to provide the locations of all key files, as well as a link to the Preview where contributors can read the lesson as the draft progresses.

If we have not received the Submission package by May, @semanticnoodles will attempt to contact @ashlynstewart404. If we do not receive any update, this Issue will be closed.

Our dedicated Ombudspersons are Ian Milligan (English), Silvia Gutiérrez De la Torre (español), Hélène Huet (français), and Luis Ferla (português) Please feel free to contact them at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudspersons will have no impact on the outcome of any peer review.

[charlottejmc]

Hello @ashlynstewart404 and @semanticnoodles,

You can find the key files here:

• .md: /en/drafts/translations/encoding-texts-tei-1.md
• images: /images/introduccion-a-tei-1
• assets: [none]

You can review a preview of the lesson here:

• http://programminghistorian.github.io/ph-submissions/en/drafts/translations/encoding-texts-tei-1

---

I noticed a couple minor things when processing this submission, which I've listed below:

• [x] I've replaced your image links with the liquid syntax we use in our lessons, which looks like this: {% include figure.html filename="file-name-1.png" alt="Visual description of figure image" caption="Figure 1. Caption text to display" %} I was able to fill in the captions you translated, but you'll see that this syntax also includes a placeholder for alt-text (Visual description of figure image). I would be grateful if you could provide this for each of the images. Unfortunately, the ES original lesson was published before we implemented alt-text, so I do not have any original text for you to translate.
• [x] I believe the image tei-translation-1.png which you provided for Figure 1 may be wrong, as it seems to be a replica of Figure 2. Could you please double-check, and perhaps send me the correct image if needed?
• [x] I'd also like to ask whether you could send me cropped versions of figures 2-8: this will allow us to size the images down (in line with our commitment to minimal compute and accessibility) while still retaining clarity.
  • 2, 3 and 4 could be cropped much closer to where the red circles appear
  • 5, 6, 7 and 8 could be cropped so as to remove empty space and show only the code
• [x] You'll see that I've added a YAML header to the lesson file. It contains an abstract and avatar_alt, which I've left in Spanish for now – could you please also translate these into English?

My colleague @anisa-hawes will invite you to join us here on GitHub as an Outside Collaborator. This will give you the Write access you'll need to edit your lesson directly.

Thank you very much for your time and your work! ✨

[semanticnoodles]

Hi @charlottejmc and @anisa-hawes, I wanted to flag some issues with the rendering of the page, but I can see you started fixing the problem, thanks!

[anisa-hawes]

Thank you, @charlottejmc!

--

Hello Ashlyn @ashlynstewart404,

I've sent you the invitation to join as an Outside Collaborator so you will be able to edit the abstract, avatar_alt etc. on your translation file here: /en/drafts/translations/encoding-texts-tei-1.md.

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 2: Initial Edit.

In this Phase, your editor Giulia @semanticnoodles will read your lesson, and provide some initial feedback. Giulia will post feedback and suggestions as a comment in this Issue, so that you can revise your draft in the following Phase 3: Revision 1.

At the moment, you'll notice that the Preview doesn't render images – we are waiting until we receive the revised files before uploading these. We'll send you a note to confirm when the preview is complete and ready to review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 1 <br> Submission
Who worked on this? : Publishing Assistant (@charlottejmc) 
All  Phase 1 tasks completed? : Awaiting revised images
Section Phase 2 <br> Initial Edit
Who's working on this? : Editor (@semanticnoodles)  
Expected completion date? : June 3
Section Phase 3 <br> Revision 1
Who's responsible? : Author (@ashlynstewart404) 
Expected timeframe? : ~30 days after feedback is received

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

[semanticnoodles]

Hi @ashlynstewart404,

here follows my initial review; I added the various points in the form of a checklist for your convenience, so it may facilitate you in keeping track of the changes.

Overall, you did fantastic work by staying as close as possible to the original, and I appreciate that. Most of the flagged items in the list below are formatting inconsistencies/missing links. In a few limited cases, some expressions could be reviewed for improved clarity -- not sticking so close to the literal translation. You changed the examples to enhance understanding, and I believe you did a fantastic job, as they make more sense in English.

Revisions list

• [x] Para 3: In the original the word “ignorante” uses quotation marks, so please keep it in the EN version too.

• [x] Para 4: Consider to perform rephrasing for increased readability e.g. ‘The computer cannot "understand" or recognise any content in the plain text without human intervention, for example through the use of TEI (Text Encoding Initiative).’

  • [x] Attention to information granularity: “búsquedas estructuradas” translates into “structured queries” – there should be another occurrence of these terms.
  • [x] Missing monotype rendering for txt

• [x] Para 7: Could you please replace the links to Wikipedia EN version, thanks?

• [x] Para 14: Missing monotype rendering for Scholarly XML

• [x] Para 31: Missing monotype rendering for elements *, _, #

• [x] Para 37: This could be formatted using a code block for improved rendering. There are a few imprecisions in the syntax of the example. Here is a reviewed version:

  <name>Fernando</name>’s <name>Manrico</name>’s passionate call, <name>Ernani</name>’s, sweet <name>Gennaro</name>’s

• [x] Para 39: Heading rendering is incorrect (paragraph-like)

• [x] Para 40: Missing link to TEI and XML

• [x] Para 46: Maybe less literal, like “Thus, while XML does not care whether the elements of a document describe text (or its properties), TEI is designed exclusively to work with them”.

  • [x] Missing links to TEI rules.

• [x] Para 51: missing monotype rendering for @rhyme, @met, @n.

• [ ] Para 54: missing TEI document example

• [x] Para 57: missing links to TEI documentation, please put teiHeader and text in bullet points or outside a code block

• [x] Para 59: missing all the links to the documentation

• [x] Para 60: Typo + missing link to Walt Whitman’s piece on the Internet Archive

• [x] Para 66:68 missing links

• [ ] Para 67: missing

• [x] Para 71: Readability, just me being a bit over-meticulous, maybe works smoothly “At first glance, all these possibilities may seem overwhelming. However, it is important to remember that a text is usually naturally divided into sections or parts.”

• [x] Para 78: a missing link to and (N goes uppercased).

• [x] Para 79: Maybe clarify the second part of the tutorial is not available yet in translation, and point still to the original one.

Check the use of sentence case in the headings and please do not forget to implement the changes requested by @charlottejmc in the message quoted below. Thank you very much for your excellent work!🌟

Hello @ashlynstewart404 and @semanticnoodles,

You can find the key files here:

• .md: /en/drafts/translations/encoding-texts-tei-1.md
• images: They will be uploaded to /images/introduccion-a-tei-1 once we've resolved my queries about them (see checklist below)
• assets: [none]

You can review a preview of the lesson here:

• http://programminghistorian.github.io/ph-submissions/en/drafts/translations/encoding-texts-tei-1

I noticed a couple minor things when processing this submission, which I've listed below:

• [x] I've replaced your image links with the liquid syntax we use in our lessons, which looks like this: {% include figure.html filename="file-name-1.png" alt="Visual description of figure image" caption="Figure 1. Caption text to display" %} I was able to fill in the captions you translated, but you'll see that this syntax also includes a placeholder for alt-text (Visual description of figure image). I would be grateful if you could provide this for each of the images. Unfortunately, the ES original lesson was published before we implemented alt-text, so I do not have any original text for you to translate.
• [x] I believe the image tei-translation-1.png which you provided for Figure 1 may be wrong, as it seems to be a replica of Figure 2. Could you please double-check, and perhaps send me the correct image if needed?
• [x] I'd also like to ask whether you could send me cropped versions of figures 2-8: this will allow us to size the images down (in line with our commitment to minimal compute and accessibility) while still retaining clarity.
  • 2, 3 and 4 could be cropped much closer to where the red circles appear
  • 5, 6, 7 and 8 could be cropped so as to remove empty space and show only the code
• [x] You'll see that I've added a YAML header to the lesson file. It contains an abstract and avatar_alt, which I've left in Spanish for now – could you please also translate these into English?

My colleague @anisa-hawes will invite you to join us here on GitHub as an Outside Collaborator. This will give you the Write access you'll need to edit your lesson directly.

Thank you very much for your time and your work! ✨

[anisa-hawes]

Hello Ashlyn @ashlynstewart404,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 3: Revision 1.

This phase is an opportunity for you to revise your draft in response to @semanticnoodles's initial feedback.

I've checked to ensure that you have the 'write access' you need to edit your draft directly.

We ask authors to work on their own files with direct commits: we prefer you don't fork our repo, or use the Pull Request system to edit in ph-submissions. You can make direct commits to your file here: /en/drafts/translations/encoding-texts-tei-1.md. Remember that Charlotte and I are here to help if you encounter any practical problems!

When you and Giulia are both happy with the revised draft, we will move forward to Phase 4: Open Peer Review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#882b4f', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 2 <br> Initial Edit
Who worked on this? : Editor (@semanticnoodles) 
All  Phase 2 tasks completed? : Yes
Section Phase 3 <br> Revision 1
Who's working on this? : Author (@ashlynstewart404)  
Expected completion date? : June 29
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers (TBC) 
Expected timeframe? : ~60 days after request is accepted

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

[charlottejmc]

Hello @semanticnoodles and @ashlynstewart404,

You'll see I've checked off a number of points from Giulia's helpful comment above. Please let me know if you need any more help with the outstanding points!

[ashlynstewart404]

Hello, @charlottejmc! I have cropped the images you requested and uploaded them here. If it's better for me to send them over email or upload them elsewhere, please let me know. Also, if you need to crop them more, feel free to shrink them to your liking if that is easier.

[ashlynstewart404]

And, @charlottejmc, here is a corrected first image (and again let me know if there's somewhere else I should send/upload):

[ashlynstewart404]

Sorry to keep spamming you, @charlottejmc, but I wanted to let you know that I added the alt text for the images into the file in ph-submissions/en/drafts/translations/encoding-texts-tei-1.md. I got a notification from GitHub that there was a build error, and I'll admit that I don't know what that means or how to fix it. 🙈 Hopefully I didn't break anything!

[anisa-hawes]

Hello Ashlyn @ashlynstewart404,

Don't worry! The build was breaking because you'd included " quotation marks within your alt-text for Figure 10. These disrupt the liquid syntax we use to display images, unless we 'escape' them with a backslash \". That's done now: https://github.com/programminghistorian/ph-submissions/commit/99b839c9fcba66a06c11f5a909f54088acd46c4c ☺️

(I've also gone through and added backticks `` around the tei tags so that they display as text: https://github.com/programminghistorian/ph-submissions/commit/1c3f06b5fc6cdd5096e0b0163c587dac04f97962)

Thank you for sharing the images. It would be great if you could email these to Charlotte (programming.assistant[@]programminghistorian.org) in .png or .jpg format (maximum of 840px on the longest edge).

[charlottejmc]

Hello @ashlynstewart404, I just wanted to check whether you've caught that we still need you to send the images to my email address?

(EDIT: Actually, there is a mistake in the address you were given initially! Apologies if you had already sent the email – but could you please send it again to publishing.assistant@programminghistorian.org?

Thank you!)

[anisa-hawes]

Hello all. Just noting here that I have edited @ashlynstewart404's comments above (here and here) to remove the embedded/linked images which can make Issue threads long and a little unwieldy. Thank you for sharing the image files with us directly via email. ☺️