Add Simplified Chinese Support (#772)

* Add Simplified Chinese Support

* Add zh_cn CliRunner tests

* fix chinese help

* align clitest names

* Fix minor flaws

* Modify Chinese internal name

* Fix Pipeline tab not raffected by localization

* refine zh_cn text

* Make tile MenuItem localizable

* add spaces between char

* fix: en docs typo

* add zh_cn docs

* feat: add zhcn docs build script

* fix: malformed table

* action: add zhcn docs pdf upload

* neutralize: codacy warnings

* fix PDF build by specifying a supported language

see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language

'zh' is not the correct language code for Simplified Chinese, 'zh_CN' is.

* wip: try to fix rst2pdf for zh_CN output (not working)

* wip: move font in the conf dir (still not working)

* fix: still trying to fix blocky docs issue

* wip: recover stylesheet

* Remove zh docs pdf upload action

* fix: correct workflow get version

* fix: ci cannot find right jar

* wip: try to fix deploy-web

* wip: try to allow rst2pdf to find correct styles

* wip: force utf-8 everywhere

* Revert "wip: try to allow rst2pdf to find correct styles"

This reverts commit 09d19af,
due to docs being accidentally broken

* add: garbled text warning

* fix: tiny errors

* fix: correct error

---------

Co-authored-by: Andrea Spadaccini <andrea.spadaccini@gmail.com>

.github/workflows/ci.yml

@@ -67,6 +67,14 @@ jobs:
         with:
           name: Italian manual (PDF)
           path: ./build/docs/it/pdf/EduMIPS64.pdf
+      #
+      # Disabled due to not working properly
+      #
+      # - name: Upload Simplified Chinese Manual PDF 
+      #   uses: actions/upload-artifact@v3.1.2
+      #   with:
+      #     name: Chinese manual (PDF)
+      #     path: ./build/docs/zh/pdf/EduMIPS64.pdf
 
       - name: Upload JAR
         uses: actions/upload-artifact@v3.1.2
@@ -137,6 +145,7 @@ jobs:
 
   deploy-web:
     name: Deploy web application
+    permissions: write-all
     runs-on: ubuntu-latest
     needs: build-web
     steps:

build.gradle.kts

@@ -51,6 +51,9 @@ application {
 val codename: String by project
 val version: String by project
 
+
+
+
 // Specify Java source/target version and source encoding.
 tasks.compileJava {
     sourceCompatibility = "17"
@@ -75,6 +78,10 @@ tasks.register<PythonTask>("htmlDocsIt") {
     workDir = "${projectDir}/docs/user/en/src"
     command = buildDocsCmd("it", "html")
 }
+tasks.register<PythonTask>("htmlDocsZh") {
+    workDir = "${projectDir}/docs/user/zh/src"
+    command = buildDocsCmd("zh", "html")
+}
 
 tasks.register<PythonTask>("pdfDocsEn") {
     workDir = "${projectDir}/docs/user/en/src"
@@ -86,10 +93,15 @@ tasks.register<PythonTask>("pdfDocsIt") {
     command = buildDocsCmd("it", "pdf")
 }
 
+tasks.register<PythonTask>("pdfDocsZh") {
+    workDir = "${projectDir}/docs/user/zh/src"
+    command = buildDocsCmd("zh", "pdf")
+}
+
 
 // Catch-all task for documentation
 tasks.create<GradleBuild>("allDocs") {
-    tasks = listOf("htmlDocsIt", "htmlDocsEn", "pdfDocsEn", "pdfDocsIt")
+    tasks = listOf("htmlDocsIt","htmlDocsZh", "htmlDocsEn", "pdfDocsEn", "pdfDocsZh", "pdfDocsIt")
     description = "Run all documentation tasks"
 }
 
@@ -115,6 +127,14 @@ tasks.create<Copy>("copyHelpIt") {
     into ("${docsDir}/user/it")
     dependsOn("htmlDocsIt")
 }
+tasks.create<Copy>("copyHelpZh") {
+    from("${buildDir}/docs/zh") {
+        include("html/**")
+        exclude("**/_sources/**")
+    }
+    into ("${docsDir}/user/zh")
+    dependsOn("htmlDocsZh")
+}
 
 tasks.create<Copy>("copyHelp") {
     from("docs/") {
@@ -124,6 +144,7 @@ tasks.create<Copy>("copyHelp") {
     into ("${docsDir}")
     dependsOn("copyHelpEn")
     dependsOn("copyHelpIt")
+    dependsOn("copyHelpZh")
 }
 
 /*
@@ -268,7 +289,7 @@ tasks.create<Exec>("msi"){
         }
 
         println("Creating EduMIPS64-${version}.msi.");
-        val cmd = "jpackage.exe --main-jar edumips64-${version}.jar --input ./build/libs/ --app-version ${version} --name EduMIPS64 --description \"Educational MIPS64 CPU Simulator\" --vendor \"EduMIPS64 Development Team\" --copyright \"Copyright ${LocalDateTime.now().year}, EduMIPS64 development Team\" --license-file ./LICENSE --win-shortcut --win-dir-chooser --win-menu --type msi --icon ./src/main/resources/images/ico.ico --win-per-user-install"
+        val cmd = "jpackage.exe --main-jar edumips64-${version}.jar --input ./build/libs/ --app-version ${version} --name EduMIPS64 --description \"Educational MIPS64 CPU Simulator\" --vendor \"EduMIPS64 Development Team\" --copyright \"Copyright ${LocalDateTime.now().year}, EduMIPS64 development Team\" --license-file ./LICENSE --win-shortcut --win-dir-chooser --win-menu --type msi --icon ./src/main/resources/images/ico.ico --win-per-user-install --java-options -Dfile.encoding=utf-8"
         commandLine(cmd.split(" "));
     }
 }

docs/user/en/src/examples.rst

@@ -198,7 +198,7 @@ usual, the strings containing the error message and the success message.
 In the .text section, we save the params_sys4 address to register r14, we save
 in the memory cells for the SYSCALL parameters the file descriptor (that we
 suppose to have in $s2) and the address from where we must take the bytes to
-weite.
+write.
 
 Next we can call SYSCALL 3, and then we call the print_string function
 passing as argument error_3 or ok_message, according to the success of the

docs/user/zh/EduMIPS64.hs

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE helpset 
+  PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN" 
+         "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
+
+
+<!--This Helpset was first generated by JHelpDev 0.63 (jhelpdev.sourceforge.net),
+    and then modified by Andrea Spadaccini using as a guideline the JavaHelp
+    System User's Guide.-->
+
+<helpset version="2.0">
+    <title>EduMIPS64 帮助</title>
+
+    <maps>
+        <homeID>top</homeID>
+        <mapref location="Map.jhm"/>
+    </maps>
+
+    <view>
+        <name>TOC</name>
+        <label>目录</label>
+        <type>javax.help.TOCView</type>
+        <data>EduMIPS64TOC.xml</data>
+    </view>
+
+    <presentation default="true" displayviewimages="false">
+        <name>main window</name>
+        <size width="400" height="400" />
+        <location x="200" y="200" />
+        <title>EduMIPS64 帮助</title>
+        <toolbar>
+            <helpaction image = "img_back">javax.help.BackAction</helpaction>
+            <helpaction image = "img_fwd">javax.help.ForwardAction</helpaction>
+            <helpaction image = "img_home">javax.help.HomeAction</helpaction>
+            <helpaction image = "img_print">javax.help.PrintAction</helpaction>
+        </toolbar>
+    </presentation>
+</helpset>

docs/user/zh/EduMIPS64Index.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN" "http://java.sun.com/products/javahelp/index_2_0.dtd"><!--generated by JHelpDev Version: 0.63, 14 May 2008, see jhelpdev.sourceforge.net-->
+
+<index version="1.0"/>

docs/user/zh/EduMIPS64TOC.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN" "http://java.sun.com/products/javahelp/toc_2_0.dtd"><!--generated by JHelpDev Version: 0.63, 14 May 2008, see jhelpdev.sourceforge.net-->
+
+<toc version="1.0">
+ <tocitem text="欢迎访问 EduMIPS64 文档！ " target="index"/>
+
+ <tocitem text="源文件格式" target="source-files-format"/>
+
+ <tocitem text="指令集" target="instructions"/>
+
+ <tocitem text="浮点单元" target="fpu"/>
+
+ <tocitem text="用户界面" target="user-interface"/>
+
+ <tocitem text="代码示例" target="examples"/>
+
+</toc>

docs/user/zh/JavaHelpSearch/DOCS.TAB

@@ -0,0 +1 @@
+ť￿￿￿￿￿￿￿￿￿￿￿￿￿￿￝翿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿ｵ￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿￿촧￿￿￿￿￿￿￿￿￿￿䀁㈬쨫뺾﮾ꮪꮯﺿ뿻ꫫ￿￿ꪪ讪껫꯿ꮾ못꯯껺﫪﫪ꪺ뺪ꮪꪪ뺪꿻몪ꪫ뮫뻪뺪﫺뫺몪ꪪ꫺뻪뺪ꫫ絛뮾ꪪꮫꪪꪪ꯮ꪪꪺꮺ着﫻ꪾ몪ꪪ꺻몪ꮺꪪ着몺ꪾ꪿ꪺꪮꮮ꾺ꪮ꺪뿫뫫ꪻ뺪몾￯ꮿꫪ꺺ꪪ못ꪪꮺ꺪꺪꺪ꪪꪪꪪꪮꪺꪻ뮮ꪪꪪꪪꪪꪪꪪꪪꪪꪪꪪꪪꪪꪪ�

docs/user/zh/JavaHelpSearch/OFFSETS

@@ -0,0 +1 @@
+��Zl�m�H�	>�G��j�H @	�|f������D

docs/user/zh/JavaHelpSearch/SCHEMA

@@ -0,0 +1,2 @@
+JavaSearch 1.0
+TMAP bs=2048 rt=1 fl=-1 id1=1045 id2=1

docs/user/zh/Map.jhm

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN" "http://java.sun.com/products/javahelp/map_2_0.dtd">
+
+<map version="1.0" xml:lang="zh">
+    <mapID target="top" url="html/index.html "/>
+    <mapID target="index" url="html/index.html"/>
+    <mapID target="user-interface" url="html/user-interface.html"/>
+    <mapID target="instructions" url="html/instructions.html"/>
+    <mapID target="fpu" url="html/fpu.html"/>
+    <mapID target="search" url="html/search.html"/>
+    <mapID target="source-files-format" url="html/source-files-format.html"/>
+    <mapID target="genindex" url="html/genindex.html"/>
+    <mapID target="examples" url="html/examples.html"/>
+    <mapID target="_static.file" url="html/_static/file.png"/>
+    <mapID target="_static.minus" url="html/_static/minus.png"/>
+    <mapID target="_static.plus" url="html/_static/plus.png"/>
+    <mapID target="img_back" url="img/Back.png"/>
+    <mapID target="img_fwd" url="img/Forward.png"/>
+    <mapID target="img_home" url="img/Home.png"/>
+    <mapID target="img_print" url="img/Print.png"/>
+</map>

docs/user/zh/src/Makefile

@@ -0,0 +1,138 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python3 -msphinx
+PAPER         =
+BUILDDIR      = ../output
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  pdf   		to make PDF files using rst2pdf"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) --version
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/EduMIPS64.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/EduMIPS64.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/EduMIPS64"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/EduMIPS64"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+pdf:
+	$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished. The PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+

docs/user/zh/src/conf.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+#
+# EduMIPS64 documentation build configuration file, created by
+# sphinx-quickstart on Tue Apr 26 23:10:10 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+#
+# Note: all the common configuration of the EduMIPS64 documentation is stored
+# in docs/common_conf.py. This file just imports all the identifiers from that
+# module and adds language-specific configuration items.
+
+import sys, os
+sys.path.append(os.path.abspath("../.."))
+from common_conf import *
+
+pdf_stylesheets = ['sphinx', 'kerning', 'a4', 'zh_CN.json', 'chinese']
+pdf_font_path = [os.path.abspath(".\\docs\\zh\\src"),'C:\\Windows\\Fonts']
+pdf_language = "zh_CN"
+source_encoding = "utf-8"
+language = "zh_CN"
+copyright = u'2011, Andrea Spadaccini (and the EduMIPS64 development team)'
+man_pages = [
+    ('index', 'edumips64', u'EduMIPS64 Documentation',
+     [u'Andrea Spadaccini (and the EduMIPS64 development team)'], 1)
+]
+latex_documents = [
+  ('index', 'EduMIPS64.tex', u'EduMIPS64 Documentation',
+   u'Andrea Spadaccini (and the EduMIPS64 development team)', 'manual'),
+]