tutorial: Modify links to pattern tutorialName-Author1-Authorn_languageSuffix

[DouSam]

All the tutorials have their name changed to follow the pattern.

[netlify]

✅ Deploy Preview for training-slicer-org ready!

Name	Link
🔨 Latest commit	0f97e78
🔍 Latest deploy log	https://app.netlify.com/projects/training-slicer-org/deploys/68de9ab30e1d1c0008e60ed8
😎 Deploy Preview	https://deploy-preview-9--training-slicer-org.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[jcfr]

Thanks for working on this 🙏

So that we can document the guidelines for anyone working on contributing training materials, I suggest we spend more time describing the convention to have an ambiguous and systematic way of deriving the file name from the tutorial title.

Looks like the convention seems to be further specified. I propose the following:

- tutorialName-Author1-AuthorN_languageSuffix
+ [Slicer]<TutorialBaseName>[Tutorial]-<Author1>[-<Author2>[...]]_<language>[_<region>].(pdf|md|html)

where:

• <TutorialBaseName> is the "camelized" title of the tutorial. The suffix Tutorial is appended if not already part of the name. See camelize section below. For examples:
  • "Welcome Tutorial" -> SlicerWelcomeTutorial
  • "Basics of Data Loading and Visualization" -> SlicerBasicsOfDataLoadingAndVisualizationTutorial
  • "Data Loading and 3D Visualization" -> SlicerDataLoadingAnd3DVisualizationTutorial
  • "DICOM Image Visualization" -> SlicerDicomImageVisualizationTutorial
• <AuthorN> is the Nth author of the source tutorial
  • The source tutorial is most likely the one written in american English and assumed to have en_US as <language>[_<region>]
  • Author is specified as camelize(first_name)[0] + camelize(last_name)

References:

• https://datatracker.ietf.org/doc/html/rfc5646#appendix-A
• https://en.wikipedia.org/wiki/IETF_language_tag

Questions

Can we revisit the approach for generating the BaseFileName of training material document ?

In the proposed pull request, it looks like the tutorial is inconsistently named:

• For "Welcome Tutorial" it uses the convention described above
• For "Basics of Data Loading and Visualization" it uses Slicer<LastWordOfTitle>Tutorial ()
• For "Data Loading and 3D Visualization" it uses Slicer<CamelizeWordsWithout3D>Tutorial (SlicerDataLoadingAndVisualizationTutorial)
• For "DICOM and Slicer" it uses 3DSlicer<FirstWordOfTitle>Tutorial (3DSlicerDICOMTutorial)

I suggest we revisit to have a systematic way of naming the files.

What to do if additional author contribute to an existing tutorial ?

Using <Author1>[-<Author2>[...]] should be further specified, may be it could be specified as the list of author up the 3rd one ?

Should we standardize on <language>[_<region>] or [-] ?

Since the _ seems to be used to visualize separate the different part in the filename, using - may be more appropriate ...

How do we cite tutorials ?

Do we want to have the tutorial to be cited ? Or do we want to redirect people to the citing guideline of Slicer. See https://slicer.readthedocs.io/en/latest/user_guide/about.html#how-to-cite

Related references:

• https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content

Convenient script & CLI to "camelize" tutorial name

import re

def camelize(s):
    words = re.split(r'[^a-zA-Z0-9]', s)
    return ''.join(word.capitalize() for word in words if word)

or

python3 -c "import re, sys; camelize=lambda s: re.sub(r'[^a-zA-Z0-9]', ' ', s).title().replace(' ', ''); print(camelize(sys.argv[1]))"

[jcfr]

cc: @lassoan

[lassoan]

It would be hard to enforce a particular naming convention for files that are store outside this repository. For example, I would not want to go and ask Sonia to please remove your name from the tutorial filename.

For any places where we want to have a string that is uniquely associated with a tutorial, we could use the tutorial ID. For example, we could use the tutorial ID for associating filenames of images that are stored in this repository. So, I think we can do without formalizing a BaseFileName for each tutorial and let users use any filename or URL to link to an external resource.

[lassoan]

Tutorials should ideally have all the source files stored on github and the PDFs generated from them are also stored in the same repository. In one of the commits, location of STC-VIS-102, STC-SEG-102, and STC-DEV-101 tutorials were changed, so I pushed a commit to restore the correct URLs.

Any update to the tutorials are welcome, but any source file changes and new generated PDFs should be made in the tutorial's repository (and then we probably we don't need to change anything here). If there are scripts to generate the tutorial then those scripts should be stored in the tutorial's repository, too.

With my commit, the suggested changes look good to me. @jcfr let us know if you agree. We need to merge these PR quickly because of reporting to CZI.