Set up infrastructure for documentation translation

[lassoan]

Evaluate slideshow generation tools, see for example: https://tiiny.host/blog/the-ultimate-list-of-markdown-presentation-tools/

• markdown input, simple extra format
• output as html slides: viewable without web server!, html document, maybe pdf, readthedocs compatible
• free!, open-source!
• widely used!
• visual appearance of the generated slides with default options; availability of templates!
• ecosystem: other tools that use it
• connection to translation tools, text split&merge for translation, https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
• visual editor: preferably free, such as a VS Code plugin (such as vscode-reveal by evilz)
• Python-friendly text extraction, processing (instead of JavaScript)

[lassoan]

Presentation that could be used in the software evaluation pilot: https://github.com/PerkLab/PerkLabBootcamp/blob/master/Doc/day1_2_DataLoadingAndVisualizationTutorial.pptx

Automatic annotation of screenshots:

• when capturing the screenshot, store in image comments the rectangle of selected (or all visible) widgets
• create a python script that can generate annotation (e.g., click on the button and a label) on a widget

Example:

Source text:

![SomeImage | [{"type"="clickMarker", "position": "updateButton", "label": "1"}] ](image.png)

Processed text that displays the annotated image:

![SomeImage](image_234234.png)

[lassoan]

Try to set up github actions to automate generation and deployment of github pages: https://github.com/ralexander-phi/marp-to-pages

Have a look at more complex examples, such as:

• deployed: https://cs199emp.netlify.app/
• source: https://github.com/harsh183/emp-125/tree/master/slides

Write more slides of DataLoadingAndVisualizationTutorial.pptx.

For the future: Implementing custom image processing (e.g., add mouse click marker and labels), check if it is possible to add custom image processing plugins; if not then we can parse the markdown file (https://github.com/syntax-tree/mdast), preprocess it, update the image source, and use marp on the preprocessed markdown and images.

[lassoan]

Testing repository: https://github.com/Adama-WADE/Tutorial-Translation

Side-by-side image and text:

• https://github.com/orgs/marp-team/discussions/62
• https://github.com/marp-team/marpit/issues/137#issuecomment-524175560
• https://stackoverflow.com/questions/30861845/how-to-use-two-column-layout-with-reveal-js

Two columns: https://github.com/orgs/marp-team/discussions/192?#discussioncomment-1516155 (need to Enable HTML in Marp Markdown)

Image sizing: need to specify in pixels? https://github.com/orgs/marp-team/discussions/167

[lassoan]

Meeting 20230410

Todo:

• [x] Add text to all slides in https://github.com/Adama-WADE/Tutorial-Translation/blob/main/Marp.md
• [x] Extract sentences from md and write it to .h file (so that lupdate can extract text into .ts file). Use an AST.
• [x] Write sentences from translated .ts file into .md file

.h file created from .md by a script similar to update_translations.py:

// Slide 1
// from VotingBinaryHoleFillingImageFilter.xml
// {"filename": "filename.md", "startRow": 356, "startColumn": 23, "endRow": 357, "endColumn": 40}
QT_TRANSLATE_NOOP("VisualizationTutorial", "3d slicer logo")
// {"filename": "filename.md", "startRow": 356, "startColumn": 23, "endRow": 357, "endColumn": 40}
QT_TRANSLATE_NOOP("VisualizationTutorial", "3D Slicer")
// {"filename": "filename.md", "startRow": 356, "startColumn": 23, "endRow": 357, "endColumn": 40}
QT_TRANSLATE_NOOP("VisualizationTutorial", "Data Loading and <br> Visualization Tutorial")

// Slide 2
// {"filename": "filename.md", "startRow": 356, "startColumn": 23, "endRow": 357, "endColumn": 40}
QT_TRANSLATE_NOOP("VisualizationTutorial", "Please download the following dataset:")

// Slide 3
// {"filename": "filename.md", "startRow": 356, "startColumn": 23, "endRow": 357, "endColumn": 40}
QT_TRANSLATE_NOOP("CLI_VotingBinaryHoleFillingImageFilter", "This command module was derived from Insight/Examples/Filtering/VotingBinaryHoleFillingImageFilter (copyright) Insight Software Consortium")

https://waylonwalker.com/python-markdown-ast-paragraph/

with open(r'c:\D\Tutorial-Translation\Marp.md', 'r') as fin:
    md = fin.read()

import commonmark
import json
parser = commonmark.Parser()
ast = parser.parse(md)

# Json representation is simple but does not include source location
jsonRoot = json.loads(commonmark.dumpJSON(ast))
for item in jsonRoot:
    if item['children']:
        for childItem in item['children']:
            if "literal" in childItem:
                print(childItem["literal"])

# AST object API is more complicated but necessary, as it includes row/column information for each block
commonmark.dumpAST(ast) # pretty print generated AST structure

paragraphs = ''
for node in ast.walker():
    if node[0].t == "paragraph":
        paragraphs += " "
        if node[0].first_child.literal:
            paragraphs += node[0].first_child.literal + "\n"

[Adama-WADE]

extract_strings.py:

• input: source .md file (English)
• outputs:
  • .h file: list of all extracted strings
  • .json file: location of each extracted string

lupdate:

• input:
  • .h file
  • previous .ts file (if exists)
• output: updates .ts file

translate_strings:

• inputs:
  • source .md file (English)
  • .ts file
  • .json file
• output: translated .md file

[Adama-WADE]

Refer to the following commit fort the resolution of tasks listed in the issue comment above