Restore numbering for TOC, add TOC to keyCommands (#16226)

Fixes #16059 Closes #16106 Summary of the issue: Due to markdown limitations, numbered headings and a numbered table of contents was removed from the user and dev guide when migrating from t2t to markdown. However, these can be restored with CSS. Description of user facing changes Restores numbered headings to the table of contents and the headings within the user guide and developer guide. Added TOC to key commands guide. Numbered heading are avoided as they don't match the user guide and may be misleading.
nvaccess · Feb 28, 2024 · 07ec0a5 · 07ec0a5
1 parent 64c9160
commit 07ec0a5
Show file tree

Hide file tree

Showing 6 changed files with 184 additions and 2 deletions.
diff --git a/sconstruct b/sconstruct
@@ -238,6 +238,7 @@ userGuideConf = os.path.join(userDocsDir.path, 'userGuide.t2tconf')
 globalConf = os.path.join(userDocsDir.path, 'global.t2tconf')
 changesConf = os.path.join(userDocsDir.path, 'changes.t2tconf')
 styles = os.path.join(userDocsDir.path, 'styles.css')
+numberedHeadingsStyle = os.path.join(userDocsDir.path, "numberedHeadings.css")
 
 #Allow all t2t files to be converted to html in user_docs
 #As we use scons Glob this will also include the keyCommands.t2t files
@@ -256,11 +257,14 @@ for t2tFile in env.Glob(os.path.join(userDocsDir.path,'*','*.t2t')):
 	htmlFile = env.md2html(t2tFile.abspath.replace(".t2t", ".md"))
 	styleInstallPath = os.path.dirname(t2tFile.abspath)
 	installedStyle = env.Install(styleInstallPath, styles)
+	installedHeadingsStyle = env.Install(styleInstallPath, numberedHeadingsStyle)
 	env.Depends(
 		htmlFile,
 		[
 			styles,
 			installedStyle,
+			numberedHeadingsStyle,
+			installedHeadingsStyle,
 		]
 	)
 	env.Depends(htmlFile, mdFile)
@@ -412,12 +416,21 @@ env.Alias("launcher", launcher)
 clientArchive = env.ZipArchive(outputDir.File("%s_controllerClient.zip" % outFilePrefix), clientDir, relativeTo=clientDir)
 env.Alias("client", clientArchive)
 
-outputStylesFile=env.Command(outputDir.File("styles.css"),userDocsDir.File('styles.css'),Copy('$TARGET','$SOURCE'))
+outputStylesFile = env.Command(
+	outputDir.File("styles.css"),
+	userDocsDir.File("styles.css"),
+	Copy("$TARGET", "$SOURCE")
+)
+outputHeadingStylesFile = env.Command(
+	outputDir.File("numberedHeadings.css"),
+	userDocsDir.File("numberedHeadings.css"),
+	Copy("$TARGET", "$SOURCE")
+)
 changesFile=env.Command(outputDir.File("%s_changes.html" % outFilePrefix),userDocsDir.File('en/changes.html'),Copy('$TARGET','$SOURCE'))
 changesMDFile = env.Command(
 	outputDir.File("changes.md"),
 	userDocsDir.File('en/changes.md'),
-	Copy('$TARGET','$SOURCE')
+	Copy('$TARGET', '$SOURCE')
 )
 env.Depends(changesFile, changesMDFile)
 env.Depends(changesFile, outputStylesFile)

diff --git a/site_scons/site_tools/md2html.py b/site_scons/site_tools/md2html.py
@@ -49,6 +49,7 @@
 <title>{title}</title>
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="stylesheet" href="styles.css">
+{extraStylesheet}
 </head>
 <body>
 """.strip()
@@ -147,6 +148,9 @@ def md2html_actionFunc(
 		env: SCons.Environment.Environment
 ):
 	isKeyCommands = target[0].path.endswith("keyCommands.html")
+	isUserGuide = target[0].path.endswith("userGuide.html")
+	isDevGuide = target[0].path.endswith("developerGuide.html")
+	isChanges = target[0].path.endswith("changes.html")
 
 	with open(source[0].path, "r", encoding="utf-8") as mdFile:
 		mdStr = mdFile.read()
@@ -158,12 +162,21 @@ def md2html_actionFunc(
 		title = _getTitle(mdBuffer, isKeyCommands)
 
 	lang = pathlib.Path(source[0].path).parent.name
+
+	if isUserGuide or isDevGuide:
+		extraStylesheet = '<link rel="stylesheet" href="numberedHeadings.css">'
+	elif isChanges or isKeyCommands:
+		extraStylesheet = ""
+	else:
+		raise ValueError(f"Unknown target type for {target[0].path}")
+
 	htmlBuffer = io.StringIO()
 	htmlBuffer.write(
 		HTML_HEADERS.format(
 			lang=lang,
 			dir="rtl" if lang in RTL_LANG_CODES else "ltr",
 			title=title,
+			extraStylesheet=extraStylesheet,
 		)
 	)
 

diff --git a/source/setup.py b/source/setup.py
@@ -269,6 +269,7 @@ def _genManifestTemplate(shouldHaveUIAccess: bool) -> tuple[int, int, bytes]:
 		"*.t2tconf",
 		"*.md",
 		"*/user_docs/styles.css",
+		"*/user_docs/numberedHeadings.css",
 		"*/developerGuide.*"
 		)
 	)

diff --git a/user_docs/en/changes.t2t b/user_docs/en/changes.t2t
@@ -76,6 +76,7 @@ This option now announces additional relevant information about an object when t
 Users of Poedit 1 are encouraged to update to Poedit 3 if they want to rely on enhanced accessibility in Poedit, such as shortcuts to read translator notes and comments. (#15313, #7303, @LeonarddeR)
 - Braille viewer and speech viewer are now disabled in secure mode. (#15680)
 - During object navigation, disabled (unavailable) objects will not be ignored anymore. (#15477, @CyrilleB79)
+- Added table of contents to key commands document. (#16106)
 -
 
 == Bug Fixes ==

diff --git a/user_docs/keyCommandsDoc.py b/user_docs/keyCommandsDoc.py
@@ -122,6 +122,8 @@ def _command(self, cmd: Command | None = None, arg: str | None = None):
 				raise KeyCommandsError(f"{self._lineNum}, title command is not valid here")
 			# Write the title and two blank lines to complete the txt2tags header section.
 			self._kcLines.append("# " + arg + LINE_END * 2)
+			# Add table of contents marker
+			self._kcLines.append("[TOC]" + LINE_END * 2)
 			self._kcSect = Section.BODY
 			return
 

diff --git a/user_docs/numberedHeadings.css b/user_docs/numberedHeadings.css
@@ -0,0 +1,152 @@
+/* Numbering for table of contents.
+.toc > ul > li is used as the base for the numbering.
+This is because the first and only first level TOC element is the heading for the page, so it should be skipped.
+*/
+.toc > ul > li > ul {
+  list-style-type: none;
+  counter-reset: toc1-counter;
+}
+
+.toc > ul > li > ul > li a:before {
+  counter-increment: toc1-counter;
+  content: counter(toc1-counter) ". ";
+}
+
+.toc > ul > li > ul > li > ul {
+  list-style-type: none;
+  counter-reset: toc2-counter;
+}
+
+.toc > ul > li > ul > li > ul > li a:before {
+  counter-increment: toc2-counter;
+  content: counter(toc1-counter) "." counter(toc2-counter) ". ";
+}
+
+.toc > ul > li > ul > li > ul > li > ul {
+  list-style-type: none;
+  counter-reset: toc3-counter;
+}
+
+.toc > ul > li > ul > li > ul > li > ul > li a:before {
+  counter-increment: toc3-counter;
+  content: counter(toc1-counter) "." counter(toc2-counter) "." counter(toc3-counter) ". ";
+}
+
+.toc > ul > li > ul > li > ul > li > ul > li > ul {
+  list-style-type: none;
+  counter-reset: toc4-counter;
+}
+
+.toc > ul > li > ul > li > ul > li > ul > li > ul > li a:before {
+  counter-increment: toc4-counter;
+  content: counter(toc1-counter) "." counter(toc2-counter) "." counter(toc3-counter) "." counter(toc4-counter) ". ";
+}
+
+.toc > ul > li > ul > li > ul > li > ul > li > ul > li > ul {
+  list-style-type: none;
+  counter-reset: toc5-counter;
+}
+
+.toc > ul > li > ul > li > ul > li > ul > li > ul > li > ul > li a:before {
+  counter-increment: toc5-counter;
+  content: counter(toc1-counter) "." counter(toc2-counter) "." counter(toc3-counter) "." counter(toc4-counter) "." counters(toc5-counter) ". ";
+}
+
+/* RTL */
+
+:lang(ar) .toc > ul > li > ul > li a:before,
+:lang(fa) .toc > ul > li > ul > li a:before {
+  content: counter(toc1-counter, arabic-indic) ". ";
+}
+
+:lang(ar) .toc > ul > li > ul > li > ul > li a:before,
+:lang(fa) .toc > ul > li > ul > li > ul > li a:before {
+  content: counter(toc2-counter, arabic-indic) "." counter(toc1-counter, arabic-indic) ". ";
+}
+
+:lang(ar) .toc > ul > li > ul > li > ul > li > ul > li a:before,
+:lang(fa) .toc > ul > li > ul > li > ul > li > ul > li a:before {
+  content: counter(toc3-counter, arabic-indic) "." counter(toc2-counter, arabic-indic) "." counter(toc1-counter, arabic-indic) ". ";
+}
+
+:lang(ar) .toc > ul > li > ul > li > ul > li > ul > li > ul > li a:before,
+:lang(fa) .toc > ul > li > ul > li > ul > li > ul > li > ul > li a:before {
+  content: counter(toc4-counter, arabic-indic) "." counter(toc3-counter, arabic-indic) "." counter(toc2-counter, arabic-indic) "." counter(toc1-counter, arabic-indic) ". ";
+}
+
+:lang(ar) .toc > ul > li > ul > li > ul > li > ul > li > ul > li > ul > li a:before,
+:lang(fa) .toc > ul > li > ul > li > ul > li > ul > li > ul > li > ul > li a:before {
+  content: counter(toc5-counter, arabic-indic) "." counter(toc4-counter, arabic-indic) "." counter(toc3-counter, arabic-indic) "." counter(toc2-counter, arabic-indic) "." counter(toc1-counter, arabic-indic) ". ";
+}
+
+
+/* Numbering for headings. */
+
+h1 {
+  counter-reset: h2counter;
+}
+
+h2 {
+  counter-reset: h3counter;
+  counter-increment: h2counter;
+}
+
+h3 {
+  counter-reset: h4counter;
+  counter-increment: h3counter;
+}
+
+h4 {
+  counter-reset: h5counter;
+  counter-increment: h4counter;
+}
+
+h5 {
+  counter-reset: h6counter;
+  counter-increment: h5counter;
+}
+
+h6 {
+  counter-increment: h6counter;
+}
+
+h2:before {
+  content: counter(h2counter) ". ";
+}
+
+h3:before {
+  content: counter(h2counter) "." counter(h3counter) ". ";
+}
+
+h4:before {
+  content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) ". ";
+}
+
+h5:before {
+  content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) "." counter(h5counter) ". ";
+}
+
+h6:before {
+  content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) "." counter(h5counter) "." counter(h6counter) ". ";
+}
+
+/* RTL */
+:lang(ar) h2:before, :lang(fa) h2:before {
+  content: counter(h2counter, arabic-indic) ". ";
+}
+
+:lang(ar) h3:before, :lang(fa) h3:before {
+  content: counter(h3counter, arabic-indic) "." counter(h2counter, arabic-indic) ". ";
+}
+
+:lang(ar) h4:before, :lang(fa) h4:before {
+  content: counter(h4counter, arabic-indic) "."  counter(h3counter, arabic-indic) "." counter(h2counter, arabic-indic) ". ";
+}
+
+:lang(ar) h5:before, :lang(fa) h5:before {
+  content: counter(h5counter, arabic-indic) "." counter(h4counter, arabic-indic) "."  counter(h3counter, arabic-indic) "." counter(h2counter, arabic-indic) ". ";
+}
+
+:lang(ar) h6:before, :lang(fa) h6:before {
+  content: counter(h6counter, arabic-indic) "." counter(h5counter, arabic-indic) "." counter(h4counter, arabic-indic) "."  counter(h3counter, arabic-indic) "." counter(h2counter, arabic-indic) ". ";
+}