Store screenshot annotations in tutorial's markdown file

[lassoan]

The annotation editor should read the list of annotated screenshots from the tutorial text (markdown file).

For example, the SlicerFourMinuteTutorial.md file can contain screenshots like this: https://github.com/SlicerLatinAmerica/TestSlicerTutorials/blob/8d702775d8db9c30e52c91bfc8576505ea81bc01/Tutorials/FourMinuteTutorial/FourMinuteTutorial.md?plain=1#L46-L54

If the editor finds an image caption starting with Screenshot: then the annotation editor should add that image to its image list. The annotation editor should also read the list of annotations from the caption and apply it to the screenshot. For example, this image is in the markdown file:

![Screenshot:({"annotation":"click","widget":"toolbar/layouts","label":"1"},{"annotation":"click","widget":"toolbar/layouts/conventional","label":"2"})](Screenshots/en-US/002-part1-after-scene-load.png)

Then the image caption can be parsed with this very simple code:

imageCaption = 'Screenshot:({"annotation":"click","widget":"toolbar/layouts","label":"1"},{"annotation":"click","widget":"toolbar/layouts/conventional","label":"2"})'

screenshotPrefix = "Screenshot:"
if imageCaption.startswith(screenshotPrefix):
    annotations = eval(imageCaption.removeprefix(screenshotPrefix))

annotation now contains the list of annotations and its arguments:

annotation = (
    {'annotation': 'click', 'widget': 'toolbar/layouts', 'label': '1'},
    {'annotation': 'click', 'widget': 'toolbar/layouts/conventional', 'label': '2'}
)

After the annotation is edited in the annotation editor, the editor should write the modified annotations back into the markdown file.

[LuskasHusty]

@enriquehdez98 The PDF/HTML Creator has to work with the markdown file.

[DouSam]

Since we changed the export of the tutorial to use HTML and gave the responsibility to generate the PDF using GitHub actions. I don't think MD its necessary, we can also use the HTML to deploy the tutorials and the TutorialsRepository.

[lassoan]

Every good tutorial has introduction, background, motivation, etc. slides that mostly contain just formatted text (maybe with some illustrative image).
What format the tutorial authors can use to create/edit sections that do not use screenshots?
Markdown would be ideal for this. It would not be convenient to edit json or html files. The current visual editor can only add short text with limited formatting (no paragraphs, bullet-point lists, etc.).

[DouSam]

That is what I am asking in the meetings... we propose the following infrastructure to translate the tutorials using Weblate as a base, and no one discussed about.

• The user creates the .py and runs to add annotations to the screenshots
• Then he sends that tutorial to the TestTutorials repository, where we will have inside the folder language, a .py and a .json with the following "key": text.
  Here the user doesn't need to do anything more.

The nightly build will

• Download the scripts from the TestTutorials repository which will be connected to Weblate to save the translations.
• Check the languages selected for translation (Portuguese, Spanis,h and French)
• Download the .json from that language and change the settings according to each one
• Generate a new HTML with the screenshots translated, the descriptions and titles translated
• Then the repository receives these files and generates a PDF using Actions

In that way, we continue to use Weblate, the linguists don't need to know git and the process will run automatically.

The only way that I see to create MD is by using GitHub, I don't see how we could integrate Weblate in that, without needing the user to translate in Weblate and then come to the repository to translate again the tutorial since we need to manually edit the MD.

What I would suggest is to change the Annotator to allow users to put raw HTML, so if they want, they can just create a < ul> element inside the description, using the blank slide (that we already have developed for those cases when the user doesn't need to use the image). In that way, we continue to use Weblate, and not just export all the images to the repository acquiring the user to translate the MD on GitHub.

[lassoan]

There is nothing new to invent here. We can follow best practices implemented in other software. You can translate .md files by splitting the markdown file into sentences, put each sentence in a translation file, upload to Weblate, let translators on Weblate create translation files in many languages, then replace the translated sentences in the original markdown file to create translated markdown files.

The translated documentation of the Godot engine is a good example. See detailed description of their approach here: https://godotengine.org/article/godots-documentation-now-open-translation/

Also check out description of the process in their documentation: https://docs.godotengine.org/en/latest/contributing/documentation/editor_and_docs_localization.html (in Spanish: https://docs.godotengine.org/es/latest/contributing/documentation/editor_and_docs_localization.html).

Example translated sentences on weblate:
https://hosted.weblate.org/translate/godot-engine/godot-docs/es/?&offset=500

I would prefer to use .ts files for translating documentation so that we can use the same file format for source code and documentation. However, if you cannot find a tool that can work with .ts files, and you find it very difficult to implement such a tool then it is OK to use .po files - the same way as Godot.