Closed hawc2 closed 1 year ago
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.
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.
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
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.
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!
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!
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. “
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!
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!
Thanks all! @ericayhayes and @mapartlo I'll send you an email so we can plan out the revisions.
@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.
Looks good to go for copy-editing @anisa-hawes!
@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
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.
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
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
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)
![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.{% 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:
@hawc2, I've adjusted a couple of fields in the YAML and a couple are still to be completed:
activity: transforming
I've updated this because (although not very intuitive) mapping is only a topic
, not an activity
. The ES original uses 'transforming'. avatar_alt:
I've added in a translation of the avatar_alt from the ES originalabstract:
(v. brief at the moment. Can you expand?)doi:
For you to add in upon publicationtranslation_date: 2022-MM-DD
Update to reflect date of publicationNext steps:
Very best, Anisa
Hi @anisa-hawes @hawc2 What is the suggested length of the abstract, per PH standards?
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
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.
@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
Actually @anisa-hawes I think the liquid syntax broke the gifs
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.
thanks @lgauthereau. once I hear back from @anisa-hawes and we fix some minor rendering issues, we'll publish the lesson
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?
@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.
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: @.***>
@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!
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: @.***>
@anisa-hawes see @hawc2 comment above. Could you let us know what code to use for displaying the gifs inline?
@anisa-hawes lmk if I can help with finalizing this lesson, we've just got a couple tweaks to make before publishing
@ericayhayes and I investigated how to display the images and gifs inline. It looks like liquid syntax does not support this, so we need to rewrite the image code. Erica and I have been discussing, but we welcome any help.
Hello @hawc2, @ericayhayes and @mapartlo. Apologies for the delay. I've taken out the liquid syntax and have reintroduced the Markdown to display the .gifs inline.
N.B. Alex, when we move the files over, I will need to adjust the links so that they point to the .gifs on Jekyll (relative links) rather than on submissions i.e., </images/filename.gif> instead of < http://programminghistorian.github.io/ph-submissions/images/filename.gif >
Hello @ericayhayes, @mapartlo,
Just to draw your attention to a couple of outstanding questions from my comment above:
Next steps @hawc2:
doi:
add in upon publicationtranslation_date: 2022-MM-DD
update to reflect date of publicationHi @anisa-hawes,
To answer your questions:
Could you provide a link for World Map? (line.40): World Map is an exact word for word translation from the original Spanish lesson version. We do not have a link to World Map GIS software. We can take it out upon your request.
Do the links between lines 128-134 really need to be within a code block? We think so. In order to avoid these URLs appearing as links, we put them in a code block because they are Map Tile export URLs, not websites.
I noticed when copyediting that the .png tile image linked from line.240 (https://mapwarper.net/maps/tile/40217/{z}/{x}/{y}.png) was extremely small/almost impossible to see and wondered if it might have been a mistake... now I note that the link leads to a page error. Is this simply intended as an example of how map tile URLs are formatted? Again, I'm not sure this needs to be within a code block.
If you click on the link, it will appear as a small tile image because like the above question, it is a Map Tile export URL, not a website. We put this URL in a code block for this reason.
Let us know if we need to make any changes.
Thank you for the explanation, @ericayhayes. That approach to the map tile links makes sense.
I wonder if @rivaquiroga knows what the World Map tool referred to in paragraph 2 of the original ES lesson is? Is it still active?
If not, I think we should take this reference out. It isn't useful if it isn't identifiable. And it cannot be found through an online search because the name is too general.
Hello @hawc2
Other than this final query, the lesson is ready for your final read-through.
I've already received and uploaded the translators' copyright declaration forms.
There are a couple of YAML fields for you to complete when you move the files over too:
doi:
add in upon publicationtranslation_date: 2022-MM-DD
update to reflect date of publicationI wonder if @rivaquiroga knows what the World Map tool referred to in paragraph 2 of the original ES lesson is? Is it still active?
I believe it might be this one: https://worldmap.maps.arcgis.com/home/index.html
Thank you, @rivaquiroga!
@ericayhayes, I've updated the lesson to add in this link. (Please note that it hasn't been possible to create a perma.cc link in this case – I think the problem is that WorldMap's home page immediately launches a pop-up upon opening).
I've also updated the abstract. Upon re-reading I felt it could benefit from some more detail and could be clarified. Please let me know if you want to adjust this, or if you're happy with the changes. abstract: "This lesson introduces basic use of Map Warper for historical maps. It guides you from upload to export, demonstrating methods for georeferencing and producing visualizations."
@anisa-hawes I think the revised abstract sounds accurate. Thanks!
@anisa-hawes, Same. I think the revised abstract sounds good. Thanks!
hey all, I was hoping to say we could move forward with publication, but strangely enough, the images for this lesson aren't displaying normally on the preview now.
It took me a few to figure it out, but it must be due to @anisa-hawes adding the yaml line identifying the "original: introduccion-map-warper", which now leads the ph-submissions repo to look for the images in the Spanish image directory, as documented in this issue #2578 "Images not displaying on ph-submissions" (https://github.com/programminghistorian/jekyll/issues/2578) identified by @jenniferisasi.
Will this problem replicate on the Jekyll site, or is it only a preview problem with the ph-submissions repo @ZoeLeBlanc? Do we need to move all the image files to the Spanish language directory now, or is there another solution in how we edit the .yaml file?
Thanks to the authors for their patience as we figure this out - alot of these problems we're encountering relate to publishing PH tutorials in translation into English. We're trying to improve our docs and technical process for doing this as we work on this lesson. The cool thing is, and partially as an explanation for these bugs, as far as I understand this Map Warper translation will be the very first translation of a Programming Historian lesson into English from another language!
I've started drafting the final published version in our main site, and I created a pull request #2711 where we'll work out the remaining issues with the images rendering. I'll ping the authors if we need you to look it over. Almost there!
@lgauthereau @ericayhayes @mapartlo congratulations, your translation, "Introduction to Map Warper" is now published!:
https://programminghistorian.org/en/lessons/introduction-map-warper
This was the first translation into English of a lesson originally published in another language! So a cause for celebration and hopefully the first of many more.
Big thanks to @JoshuaGOB and @aycasarez for your thorough reviews!
And thanks everyone for your help with elements of this lesson, especially @anisa-hawes @rivaquiroga @jenniferisasi @svmelton!
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.