pandoc --from markdown --to rst --reference-links LICENSE.md > LICENSE.rst
vim LICENSE.MD # edit vim to change the links to be named links
git add LICENSE.rst
git rm LICENSE.md
# edit any references to LICENSE.md to refer to .rst
For LICENSE only, since it had existing translations, those needed to be updated
make gettext
cp _build/gettext/*.pot includes/
sphinx-intl update -p _build/gettext -l es -l pt # this update the existing templates
make -e SPHINXOPTS="-D language='pt'" html # build the pt docs
open _build/html/LICENSE.html # check that the translation templates still worked
# if there are problems
meld _build/gettext/user_guide.pot locales/pt/LC_MESSAGES/user_guide.po
# look for `fuzzy`
Note: the links in the output from pandoc need to be adjusted, even with --reference-links. This is the vim step above, and can be done with any editor.
Change the links from this style:
All Common Workflow Language project instructional material and changes
to the structure are also made available under the `Creative Commons
Attribution license`_. The following is a human-readable summary of (and
not a substitute for) the `full legal text of the CC BY 4.0 license`_.
.. _Creative Commons Attribution license: https://creativecommons.org/licenses/by/4.0/
.. _full legal text of the CC BY 4.0 license: https://creativecommons.org/licenses/by/4.0/legalcode
to
All Common Workflow Language project instructional material and changes
to the structure are also made available under the `Creative Commons
Attribution license <cc-by-human_>`_. The following is a human-readable summary of (and
not a substitute for) the `full legal text of the CC BY 4.0 license <cc-by-legal_>`_.
.. _cc-by-human: https://creativecommons.org/licenses/by/4.0/
.. _cc-by-legal: https://creativecommons.org/licenses/by/4.0/legalcode
That way the links have a target (cc-by-human) independent of the link text, which will need to change in the translations.
Not using --reference-links leads to in-line URLs, but I'd rather those stay out of the translations to avoid typos or the need to adjust translations when updating links:
All Common Workflow Language project instructional material and changes
to the structure are also made available under the `Creative Commons
Attribution license <https://creativecommons.org/licenses/by/4.0/>`__.
The following is a human-readable summary of (and not a substitute for)
the `full legal text of the CC BY 4.0
license <https://creativecommons.org/licenses/by/4.0/legalcode>`__.
Example of working around https://github.com/executablebooks/MyST-Parser/issues/690
The following files also have internal links that need converting to ReST.
src/index.mdsrc/topics/additional-arguments-and-parameters.mdsrc/topics/best-practices.mdsrc/topics/custom-types.mdsrc/topics/expressions.mdsrc/topics/file-formats.mdsrc/topics/metadata-and-authorship.mdsrc/topics/specifying-software-requirements.mdsrc/topics/using-containers.mdsrc/topics/yaml-guide.mdMy conversion process:
For LICENSE only, since it had existing translations, those needed to be updated
Note: the links in the output from pandoc need to be adjusted, even with
--reference-links. This is thevimstep above, and can be done with any editor.Change the links from this style:
to
That way the links have a target (
cc-by-human) independent of the link text, which will need to change in the translations.Not using
--reference-linksleads to in-line URLs, but I'd rather those stay out of the translations to avoid typos or the need to adjust translations when updating links: