From 07ec0a5771968ea060393e21298beff322908f97 Mon Sep 17 00:00:00 2001 From: Sean Budd Date: Wed, 28 Feb 2024 13:41:43 +1100 Subject: [PATCH] Restore numbering for TOC, add TOC to keyCommands (#16226) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- sconstruct | 17 +++- site_scons/site_tools/md2html.py | 13 +++ source/setup.py | 1 + user_docs/en/changes.t2t | 1 + user_docs/keyCommandsDoc.py | 2 + user_docs/numberedHeadings.css | 152 +++++++++++++++++++++++++++++++ 6 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 user_docs/numberedHeadings.css diff --git a/sconstruct b/sconstruct index 0aefe68a08d..63cf9c2e9cb 100755 --- 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 index 362b9ab4d17..adc93cd28eb 100644 --- a/site_scons/site_tools/md2html.py +++ b/site_scons/site_tools/md2html.py @@ -49,6 +49,7 @@ {title} +{extraStylesheet} """.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 = '' + 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 index 78be179e74c..8ef69e8e59c 100755 --- 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 index c3918f6d960..03984c04055 100644 --- 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 index f2716fe0d32..5d7a90a7eeb 100644 --- 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 new file mode 100644 index 00000000000..e23a1d30051 --- /dev/null +++ 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) ". "; +}