Translation of Introducción a Map Warper

[hawc2]

The Programming Historian has received a proposal to translate "Introducción a Map Warper" into English. The translation will be authored by @lgauthereau @ericayhayes and @mapartlo.

This translation has been developed out of an original proposal by @ericayhayes and @mapartlo entitled "Georeferencing and Displaying Historical Maps using Map Warper and StoryMap JS" (issue #349). As noted in that ticket, their proposal overlaps with the previously published Spanish lesson introducing Map Warper. To avoid overlap, @ericayhayes and @mapartlo will revise their original English lesson to focus on building off the Spanish lesson to focus on Storymap JS and other extensions of Mapwarper.

In parallel, this translation of the Spanish Mapwarper lesson into English will ensure both lessons can be linked in English and build off one another. Subsequent to the publishing of the original English lesson on StoryMap JS, it will also be translated into Spanish (by @lgauthereau or another translator we find). In this way, both English and Spanish journals will have published a two-part lesson on MapWarper and StoryMap JS.

I will act as editor for the review process. My role is to solicit two reviews from the community and to manage the discussions, which should be held here on this forum. I have already read through the lesson and provided feedback, to which the author has responded.

Members of the wider community are also invited to offer constructive feedback which should post to this message thread, but they are asked to first read our Reviewer Guidelines (http://programminghistorian.org/reviewer-guidelines) and to adhere to our anti-harassment policy (below). We ask that all reviews stop after the second formal review has been submitted so that the author can focus on any revisions. I will make an announcement on this thread when that has occurred.

I will endeavor to keep the conversation open here on Github. If anyone feels the need to discuss anything privately, you are welcome to email me.

Our dedicated Ombudsperson is (Ian Milligan - http://programminghistorian.org/en/project-team). Please feel free to contact him at any time if you have concerns that you would like addressed by an impartial observer. Contacting the ombudsperson will have no impact on the outcome of any peer review.

Anti-Harassment Policy

This is a statement of the Programming Historian's principles and sets expectations for the tone and style of all correspondence between reviewers, authors, editors, and contributors to our public forums.

The Programming Historian is dedicated to providing an open scholarly environment that offers community participants the freedom to thoroughly scrutinize ideas, to ask questions, make suggestions, or to requests for clarification, but also provides a harassment-free space for all contributors to the project, regardless of gender, gender identity and expression, sexual orientation, disability, physical appearance, body size, race, age or religion, or technical experience. We do not tolerate harassment or ad hominem attacks of community participants in any form. Participants violating these rules may be expelled from the community at the discretion of the editorial board. Thank you for helping us to create a safe space.

[hawc2]

The lesson files and images have now been uploaded, and the lesson is previewable at the following link.

https://programminghistorian.github.io/ph-submissions/en/drafts/translations/introduction-map-warper

Let me know if you see any small changes I should make. I'll review the lesson once and will follow up with you shortly.

[lgauthereau]

NB: This is a liberal translation, not a word-for-word translation, as it was first submitted as a lesson in English. I tried to include as much as possible from the English submission and integrate it into the translation. We swapped out the example to include a map in English, but the original map is cited in a note in the translation.

[ericayhayes]

Please note this is a liberal translation and is not an exact word-for-word translation. Some of the differences include:

-A USA North Carolina map example rather than a Map of the Republic of Colombia -More notes and explanations (e.g., the RMS error code section) -A note about displaying the map online with a link to the Displaying A Georeferencing Map in StoryMap JS lesson

[hawc2]

This lesson looks good to go out for review. Thanks to the authors for help fixing some markdown issues. I'll follow up once we've identified two reviewers.

[hawc2]

I'm happy to report @JoshuaGOB and @aycasarez have agreed to be reviewers of this translated lesson. Let's aim to get both reviews in by mid-June.

Please post your feedback here, general and specific line edits. Using Markdown checkboxes can make the minor edits easier for the authors.

In this case, keep an eye out for differences between the original and the new translation, and we can discuss here which differences make sense for the translated version.

Thanks all!

[aycasarez]

Hi everyone! I fell a little behind on this, but I am working on reviewing the lesson now. I will have the review finished by Friday at the latest. Thanks for your patience and talk soon!

[aycasarez]

Apologies for the delay. Here is my review of the translated lesson. These are just suggestions and I am happy to discuss or clarify any of my comments! Thank you @lgauthereau and @ericayhayes for your excellent work in translating and adapting this lesson. I have often shied away from spatial humanities, but I found this really approachable and dare I say- fun?

To start off, I really appreciate the addition of georeferencing definition in the translated version.

Para 7 - Is there clearer way to indicate how to download the jpg version of the map? Or another way to provide the jpg? This might just be user error on my part, but I had some trouble finding a jpg to download on the David Ramsey site. The download links under the Media Information only seem to provide JP2 and SID files. I right clicked and saved as on the map to download a png, which is the file that I used in the tutorial.

Para 13- historical maps instead of antique maps?

Para 18 - Source: url for the document source [I think that is what we're trying to refer to]

Para 25 - Layer icon link broken -New line for the Add custom basemap feature explanation

Para 33 - This table also includes a section that defines the geometric error value, caused by the georeferencing of the historic map document

Para 38 - is it possible to create a frame around this box like used in the original?

Para 39 - Fantastic walkthrough! Could you title it with something that distinguishes it from the explanatory interface section above? Perhaps a title like “Practice” or “Activity”? Also, I appreciate the note on the error value and what it means.

Para 48 - display window? or display box? as a translation for “recuadro de visualización”

Para 51 - Title suggestion - “Preview” instead of “Previsualization"

Para 53 - ellipsoid

Para 56 - "Any MapWarper user can monitor the changes to the map” in place of 'All users can monitor the change to the map. “

[JoshuaGOB]

Congratulations to @lgauthereau, @ericayhayes, and @mapartlo for their fantastic work. It complements and improves on the original lesson while still making it approachable and easy to follow. Kudos!

Being familiar with the original, I have to admit that I was even more impressed by the translation. I only have a few suggestions to add to the fantastic work by @aycasarez and I'll try to not repeat myself except to offer additional phrasing or emphasizing key comments.

• [x] 90 - Echoing @aycasarez comment. It might be useful to either provide a screenshot or explain that there is an export button to download the image from the Rumsey Map Collection that exports as jpg

• [x] 154 - This table also includes a section that defines the geometric error value, caused by the georeferencing of the historic map document -> This table also includes a section that defines the geometric error value, caused by the georeferencing of the historic map document

154 - Could also read: This table also includes a section that defines the geometric error value, caused by ~~the~~ georeferencing the historic map document

• [x] 156 - Download points as CSV, displayed below the table allows you to download the table as a Comma Separated Values (CSV) file. -> Download the points as a CSV file (comma separated values) by selecting the option under Ground Control Points.

• [x] 179 - Spread them out across your historic map–focusing on state borders, rivers, county lines, and major cities is a good strategy. -> Spreading the points out across your historic map and focusing on state borders, rivers, county lines, and major cities is a good strategy

• [x] 256 - Miguel Cuadros is a historian who studied at Universidad Industrial ~~de~~ de Santander and received his Master of Arts in History at the State University of New York.

Thank you for the opportunity to review the lesson and congratulations on doing such good work!

[hawc2]

Thank you @JoshuaGOB and @aycasarez! Sounds like this lesson is in really solid shape, and all the feedback is clearcut.

@lgauthereau @ericayhayes @mapartlo can you make these revisions soon? I can read through it and give a last round of feedback, and @anisa-hawes will also give it a final round of copy-edits. Hopefully we can publish this pretty quickly!

[lgauthereau]

Thanks all! @ericayhayes and @mapartlo I'll send you an email so we can plan out the revisions.

[ericayhayes]

@hawc2, we went through the revisions and I went ahead and pushed those changes to GitHub. Let us know if there is anything else you need from us.

[hawc2]

Looks good to go for copy-editing @anisa-hawes!

[hawc2]

@lgauthereau while we wait on copyedits, can you post this statement to this ticket?:

I the author|translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a [CC-BY](https://creativecommons.org/licenses/by/4.0/deed.en) license.

There's also some other metadata we'll need for the lesson. Take a look at the markdown on the original Spanish lesson to translate it from there:

difficulty: TBC
activity: [TBC]
topics: [TBC]
abstract: TBC
avatar_alt: TBD

[lgauthereau]

I the translator hereby grant a non-exclusive license to ProgHist Ltd to allow The Programming Historian English|en français|en español to publish the tutorial in this ticket (including abstract, tables, figures, data, and supplemental material) under a CC-BY license.

[lgauthereau]

Hi @hawc2 I'm only seeing difficulty in the original metadata. Is there a guide with specific vocabulary for activity/topics? And do we determine the avatar_alt?

difficulty: Medium activity: [TBC] topics: mapping abstract: This lesson will guide users through uploading a scanned map and georeferencing against OpenStreetMap using Map Warper. avatar_alt: TBD

[hawc2]

No worries, I can update the rest of that and I'll ping you if I have questions. Still figuring out how some of this works for translations. Once Anisa finished copy-edits on this lesson, I'll move it into publication. Thanks all!

On Mon, 8 Aug 2022 at 11:41, Lorena Gauthereau @.***> wrote:

Hi @hawc2 https://github.com/hawc2 I'm only seeing difficulty in the original metadata. Is there a guide with specific vocabulary for activity/topics? And do we determine the avatar_alt?

difficulty: Medium activity: [TBC] topics: mapping abstract: This lesson will guide users through uploading a scanned map and georeferencing against OpenStreetMap using Map Warper. avatar_alt: TBD

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1208291538, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4ED73HZFDLPL3ERNGEDVYETBRANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

--

*Alex Wermer-Colan, PhD *

Temple University, Scholars Studio

[anisa-hawes]

Dear @lgauthereau, @ericayhayes, @mapartlo + @hawc2.

I've applied the copyedits + perma.cc links to your translation. Please let me know if you're happy with the adjustments. See Update introduction-map-warper.md.

I do have a couple of small questions: (N.B. Line numbers below refer to the line numbers of the Markdown file here)

• [ ] Could you provide a link for World Map? (line.40)
• [ ] Do the links between lines 128-134 need to be within a code block?
• [ ] I notice that the .png tile image linked from line.240 (https://mapwarper.net/maps/tile/40217/{z}/{x}/{y}.png) is extremely small/almost impossible to see! Is this expected/or a mistake?
• [x] We use liquid syntax to include images in our lessons, so I replaced the alternative formatting you'd used, e.g., ![Layer icon](http://programminghistorian.github.io/ph-submissions/images/introduction-map-warper/layer_switcher_maximize.png) throughout the lesson. However, I see in the re-built preview that the icon images no longer display 'inline' with the text, which I gather is what you wanted. What are your thoughts, @hawc2? (I haven't seen that ![text](link) formatting used anywhere else across the journals). I can change these back if you want, we'll just need to update the links to /images in Jekyll when you move the lesson files over for publication.
• [x] Aside from those small icon images, I'd like to ask if you could add alt-text to your figure images? The syntax to use is: {% include figure.html filename="file-name.png" alt="Visual description of figure image" caption="Caption text to display" %}. One thing to note is that Markdown styling should not be included within your alt, because screen readers read the characters directly (so bold is read as asterisks).

Last thing:

• [x] I can see that you've each posted your Permission to Publish statements in the thread above. We've introduced a new step in our workflow, where we are asking authors and translators to complete a declaration form to acknowledge their copyright and grant us permission to publish. Could one of you download, complete + sign this on behalf of you and your co-authors, and email it to me? admin [@] programminghistorian.org.

@hawc2, I've adjusted a couple of fields in the YAML and a couple are still to be completed:

• [x] activity: transforming I've updated this because (although not very intuitive) mapping is only a topic, not an activity. The ES original uses 'transforming'.
• [x] avatar_alt: I've added in a translation of the avatar_alt from the ES original
• [x] abstract: (v. brief at the moment. Can you expand?)
• [ ] doi: For you to add in upon publication
• [ ] translation_date: 2022-MM-DD Update to reflect date of publication

Next steps:

• [ ] Something to think about for after publication is preparing 2 posts for our Twitter Bot. We can Tweet directly after publication, but the Bot will help us to publicise the lesson in the future

Very best, Anisa

[lgauthereau]

Hi @anisa-hawes @hawc2 What is the suggested length of the abstract, per PH standards?

[hawc2]

2-3 sentences is good, in this case it can be similar or the same as on the original spanish lesson

On Mon, 15 Aug 2022 at 09:56, Lorena Gauthereau @.***> wrote:

Hi @anisa-hawes https://github.com/anisa-hawes @hawc2 https://github.com/hawc2 What is the suggested length of the abstract, per PH standards?

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1215043079, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4EAQIX6GUEWW4QOIBYTVZJEBJANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

-- --- Alex Wermer-Colan, Ph.D. (he/him)

Administrative Lead, Philly Community Wireless

Managing Editor, Programming Historian in English Interim Academic Director, Temple University's Scholars Studio

[anisa-hawes]

Thank you @lgauthereau! I've received your Authorial-copyright-and-publishing-rights form 🙂

The original ES abstract is: En esta lección aprenderás a georreferenciar imágenes digitales con la herramienta Map Warper y a vincularlas a sistemas de información geográficos if you want to use or adapt this.

[hawc2]

@lgauthereau @ericayhayes @mapartlo, as I go to publish this lesson, I'm noticing images for the buttons aren't rendering the same. @anisa-hawes this is actually because we switched to the liquid syntax. They used the syntax for images because that's what the original spanish used.

Did the other minor changes Anisa asked for get done? I'll aim to publish this very soon. We can always tweak the button images later if necessary, as this seems to stray from our usual formatting and may require some thinking about liquid syntax for this kind of bullet point

[hawc2]

Actually @anisa-hawes I think the liquid syntax broke the gifs

[lgauthereau]

Hi all, I realized I had already translated the original abstract (which was only 1 sentence). But if we want something longer, I've added more below:

This lesson will guide users through uploading a scanned historical map and georeferencing against OpenStreetMap using Map Warper. Users will then export the georeferenced map as a WMS, Tiles, GeoTIFF, or KML file. This lesson can be used in conjunction with the Displaying a Georeferenced Maps in Story Map JS Programming Historian lesson.

[hawc2]

thanks @lgauthereau. once I hear back from @anisa-hawes and we fix some minor rendering issues, we'll publish the lesson

[anisa-hawes]

Actually @anisa-hawes I think the liquid syntax broke the gifs

Hello @hawc2. Oh, this is strange. As I explained above, I did notice that the tiny icon images no longer displayed 'inline' with the text when I added in the liquid syntax, but I don't think this is what has broken the .gifs. Also, I note also that the Create an Account .gif in the Getting Started section (l.75 of the Markdown) still works as it should... (Is it because there are no captions caption=?) Anyway, if we want to keep the icons, and display them inline, I think we would need to add the ![text](link) formatting back in.

I know that liquid syntax can work with .gifs because I checked the code for an ES lesson that I remembered includes them too: Análisis de corpus con Voyant Tools. The Markdown for that lesson is here.

--

Reviewing my comment above and double checking the recent commit history, it looks like we are still waiting for the other small changes/responses to those suggestions. Let us know if you have time to check in, @lgauthereau / @ericayhayes / @mapartlo?

[hawc2]

@ericayhayes was helping before with a bunch of the formatting and liquid syntax stuff. Erica, would you be available to help with making some of these final changes to the lesson? I'm agnostic about using Liquid or simpler syntax, so I'll leave it up to the authors in this case as long as it renders right.

[mapartlo]

Erica and I are taking a look at this next week, it may not be until next Friday that we're able to dive in.

On Thu, Sep 1, 2022 at 9:11 PM Alex Wermer-Colan @.***> wrote:

@ericayhayes https://github.com/ericayhayes was helping before with a bunch of the formatting and liquid syntax stuff. Erica, would you be available to help with making some of these final changes to the lesson? I'm agnostic about using Liquid or simpler syntax, so I'll leave it up to the authors in this case as long as it renders right.

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1234957313, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHST52TDSGZ7PHEJPLVLILTV4FH53ANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

[ericayhayes]

@hawc2 @mapartlo and I met last Friday to go over Anisa's comments. We tried to figure out how to display the tiny icon images 'inline' with the text in liquid syntax, but none of my edits worked. The only way I was able to display them inline without using markdown was using html code directly in the file. For example, img src="/ph-submissions/images/introduction-map-warper/add_control_point.gif" alt="Add Control Point icon" works. See line 122 or paragraph 25 as an example. I didn't want to go through and change all of the liquid syntax to html if it is unacceptable to you and the editors. Please let me know. @mapartlo and I are meeting again this Friday to go through the rest of Anisa's comments and I can update those changes if that's okay with you. Thanks!

[hawc2]

that sounds great, thanks!

I'll defer to Anisa about finalizing the code for rendering gifs, but I guess I thought the first option, used in the original Spanish lesson, was the simplest?

On Tue, Sep 13, 2022, 11:48 AM Erica Y. Hayes @.***> wrote:

@hawc2 https://github.com/hawc2 @mapartlo https://github.com/mapartlo and I met last Friday to go over Anisa's comments. We tried to figure out how to display the tiny icon images 'inline' with the text in liquid syntax, but none of my edits worked. The only way I was able to display them inline without using markdown was using html code directly in the file. For example, [image: Add Control Point icon] http:///ph-submissions/images/introduction-map-warper/add_control_point.gif works. See line 122 or paragraph 25 as an example. I didn't want to go through and change all of the liquid syntax to html if it is unacceptable to you and the editors. Please let me know. @mapartlo https://github.com/mapartlo and I are meeting again this Friday to go through the rest of Anisa's comments and I can update those changes if that's okay with you. Thanks!

— Reply to this email directly, view it on GitHub https://github.com/programminghistorian/ph-submissions/issues/426#issuecomment-1245604189, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADXF4EERGR5BN7VHHOGNOT3V6CO37ANCNFSM5HS2MFPA . You are receiving this because you were mentioned.Message ID: @.***>

[ericayhayes]

@anisa-hawes see @hawc2 comment above. Could you let us know what code to use for displaying the gifs inline?