From c7892fe1a11367872de6f3ee0fa074b39824e59c Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 31 Oct 2022 03:04:01 +0000 Subject: CTAN sync 202210310303 --- FILES.byname | 891 +- FILES.byname.gz | Bin 2472359 -> 2472213 bytes FILES.last07days | 709 +- biblio/ctan-bibdata/ctan.bib | 69 +- biblio/ctan-bibdata/ctan.pdf | Bin 3620853 -> 3621491 bytes fonts/gillius/README | 2 +- fonts/gillius/latex/gillius.sty | 3 +- graphics/pgf/contrib/bodeplot/README.md | 3038 ++++- graphics/pgf/contrib/bodeplot/bodeplot.dtx | 13662 ++++++++++++++++--- graphics/pgf/contrib/bodeplot/bodeplot.ins | 3179 ++++- graphics/pgf/contrib/bodeplot/bodeplot.pdf | Bin 1062592 -> 1066728 bytes macros/generic/tracklang/CHANGES | 6 + macros/generic/tracklang/README | 6 +- .../samples/animals/sample-animals-babel.pdf | Bin 14855 -> 15690 bytes .../samples/animals/sample-animals-de-poly.pdf | Bin 3820 -> 3823 bytes .../samples/animals/sample-animals-de-poly.tex | 1 + .../samples/animals/sample-animals-de.pdf | Bin 13625 -> 14463 bytes .../samples/animals/sample-animals-poly.pdf | Bin 3556 -> 3560 bytes .../samples/animals/sample-animals-sr-poly.pdf | Bin 7547 -> 0 bytes .../tracklang/samples/animals/sample-animals.pdf | Bin 12656 -> 13489 bytes .../samples/animals/sample-animals2-de.pdf | Bin 13625 -> 14463 bytes .../samples/animals/sample-animals2-de2.pdf | Bin 13625 -> 14463 bytes .../samples/animals/sample-animals2-de3.pdf | Bin 13607 -> 14444 bytes .../samples/animals/sample-animals2-de4.pdf | Bin 3820 -> 3823 bytes .../samples/animals/sample-animals2-poly.pdf | Bin 3560 -> 3559 bytes .../tracklang/samples/animals/sample-animals2.pdf | Bin 12656 -> 13489 bytes .../tracklang/samples/regions/sample-regions.pdf | Bin 13161 -> 13996 bytes .../samples/regions/sample-regions2-manx.pdf | Bin 21945 -> 23587 bytes .../samples/regions/sample-regions2-map.pdf | Bin 26000 -> 27666 bytes .../samples/regions/sample-regions2-map2.pdf | Bin 25852 -> 27515 bytes .../samples/regions/sample-regions2-map3.pdf | Bin 24924 -> 26590 bytes .../samples/regions/sample-regions2-nomap.pdf | Bin 25468 -> 27134 bytes .../tracklang/samples/regions/sample-regions2.pdf | Bin 14716 -> 15551 bytes .../generic/tracklang/samples/sample-tracklang.pdf | Bin 19552 -> 20388 bytes .../tracklang/samples/sample-tracklang2.pdf | Bin 19802 -> 20747 bytes .../tracklang/samples/sample-tracklang3.pdf | Bin 19814 -> 20758 bytes .../tracklang/samples/sample-tracklang4.pdf | Bin 6202 -> 6869 bytes .../tracklang/samples/sample-tracklang5.pdf | Bin 16914 -> 17857 bytes .../tracklang/samples/sample-tracklang6.pdf | Bin 19897 -> 19898 bytes macros/generic/tracklang/tracklang-code.pdf | Bin 0 -> 629107 bytes macros/generic/tracklang/tracklang-manual.html | 6522 +++++++++ macros/generic/tracklang/tracklang-manual.pdf | Bin 0 -> 764697 bytes macros/generic/tracklang/tracklang-manual.tex | 5641 ++++++++ macros/generic/tracklang/tracklang.dtx | 3780 +---- macros/generic/tracklang/tracklang.ins | 4 +- macros/generic/tracklang/tracklang.pdf | Bin 742279 -> 0 bytes .../biblatex-caspervector/doc/ChangeLog.txt | 5 + .../biblatex-caspervector/doc/caspervector-ay.pdf | Bin 172785 -> 212575 bytes .../biblatex-caspervector/doc/caspervector.pdf | Bin 314272 -> 393884 bytes .../biblatex-caspervector/doc/caspervector.tex | 12 +- .../tex/blx-caspervector-base.def | 29 +- .../tex/blx-caspervector-gbk.def | 2 +- .../tex/blx-caspervector-utf8.def | 2 +- .../biblatex-caspervector/tex/caspervector-ay.bbx | 2 +- .../biblatex-caspervector/tex/caspervector-ay.cbx | 2 +- .../biblatex-caspervector/tex/caspervector.bbx | 2 +- .../biblatex-caspervector/tex/caspervector.cbx | 2 +- macros/latex/contrib/eolang/DEPENDS.txt | 1 + macros/latex/contrib/eolang/eolang.dtx | 100 +- macros/latex/contrib/eolang/eolang.pdf | Bin 969068 -> 1036825 bytes macros/latex/contrib/ffcode/DEPENDS.txt | 2 - macros/latex/contrib/ffcode/README.md | 9 +- macros/latex/contrib/ffcode/ffcode.dtx | 201 +- macros/latex/contrib/ffcode/ffcode.ins | 8 +- macros/latex/contrib/ffcode/ffcode.pdf | Bin 395644 -> 487461 bytes macros/latex/contrib/pkuthss/doc/example.pdf | Bin 103792 -> 103719 bytes macros/latex/contrib/pkuthss/doc/example/spine.tex | 9 +- .../latex/contrib/pkuthss/doc/example/thesis.tex | 4 +- macros/latex/contrib/pkuthss/doc/pkuthss.pdf | Bin 439556 -> 348380 bytes .../latex/contrib/pkuthss/doc/readme/ChangeLog.txt | 9 + .../pkuthss/doc/readme/chap/pkuthss-chap2.tex | 5 +- .../pkuthss/doc/readme/chap/pkuthss-chap3.tex | 17 +- .../pkuthss/doc/readme/chap/pkuthss-intro.tex | 4 +- .../pkuthss/doc/readme/ctex-fontset-pkuthss.def | 1 + .../latex/contrib/pkuthss/doc/readme/ctexopts.cfg | 1 + .../latex/contrib/pkuthss/doc/readme/pkuthss.bib | 20 +- .../latex/contrib/pkuthss/doc/readme/pkuthss.tex | 4 +- macros/latex/contrib/pkuthss/tex/pkulogo.pdf | Bin 3530 -> 3530 bytes macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def | 2 +- macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def | 2 +- macros/latex/contrib/pkuthss/tex/pkuthss.cls | 24 +- macros/latex/contrib/pkuthss/tex/pkuthss.def | 2 +- macros/latex/contrib/pkuthss/tex/pkuword.pdf | Bin 6280 -> 6280 bytes macros/luatex/latex/luaoptions/Contributors.md | 6 + macros/luatex/latex/luaoptions/LICENSE | 21 + macros/luatex/latex/luaoptions/README.md | 15 + macros/luatex/latex/luaoptions/latexmkrc | 2 + macros/luatex/latex/luaoptions/luaoptions-lib.lua | 240 + macros/luatex/latex/luaoptions/luaoptions.lua | 329 + macros/luatex/latex/luaoptions/luaoptions.pdf | Bin 0 -> 28593 bytes macros/luatex/latex/luaoptions/luaoptions.sty | 36 + macros/luatex/latex/luaoptions/luaoptions.tex | 188 + macros/luatex/latex/luaoptions/luaoptionsbase.cls | 37 + .../luatex/latex/luaoptions/luaoptionsmanual.cls | 41 + macros/unicodetex/latex/bithesis/bithesis.dtx | 115 +- macros/unicodetex/latex/bithesis/bithesis.pdf | Bin 1033346 -> 1043619 bytes macros/xetex/latex/xepersian/README | 4 +- .../xetex/latex/xepersian/xepersian-doc-intro.ltx | 2 +- .../xetex/latex/xepersian/xepersian-doc-title.ltx | 4 +- macros/xetex/latex/xepersian/xepersian-doc.ltx | 2 +- macros/xetex/latex/xepersian/xepersian-doc.pdf | Bin 243511 -> 236749 bytes macros/xetex/latex/xepersian/xepersian.dtx | 37 +- macros/xetex/latex/xepersian/xepersian.pdf | Bin 775123 -> 777678 bytes support/latexindent/LatexIndent/GetYamlSettings.pm | 6 + support/latexindent/LatexIndent/Version.pm | 4 +- support/latexindent/README | 26 +- support/latexindent/bin/linux/latexindent | Bin 0 -> 6159922 bytes support/latexindent/bin/macos/latexindent | Bin 0 -> 6389393 bytes support/latexindent/defaultSettings.yaml | 2 +- support/latexindent/documentation/cmhlistings.tex | 35 - support/latexindent/documentation/contributors.bib | 176 + .../latexindent/documentation/figure-schematic.tex | 31 - support/latexindent/documentation/latex-indent.bib | 138 + .../documentation/latexindent-yaml-schema.json | 2 +- support/latexindent/documentation/latexindent.pdf | Bin 1106074 -> 1105223 bytes support/latexindent/documentation/latexindent.tex | 7235 +++++++++- support/latexindent/documentation/logo.tex | 33 - .../latexindent/documentation/sec-appendices.tex | 720 - .../sec-conclusions-know-limitations.tex | 28 - .../documentation/sec-default-user-local.tex | 1304 -- .../documentation/sec-demonstration.tex | 42 - .../latexindent/documentation/sec-fine-tuning.tex | 311 - .../latexindent/documentation/sec-how-to-use.tex | 549 - .../sec-indent-config-and-settings.tex | 207 - .../latexindent/documentation/sec-introduction.tex | 250 - .../latexindent/documentation/sec-references.tex | 16 - .../latexindent/documentation/sec-replacements.tex | 407 - .../documentation/sec-the-line-switch.tex | 198 - .../latexindent/documentation/sec-the-m-switch.tex | 60 - .../subsec-combine-text-wrap-para-line-breaks.tex | 111 - .../subsec-commands-and-their-options.tex | 251 - .../subsec-noAdditionalIndent-indentRules.tex | 36 - .../documentation/subsec-one-sentence-per-line.tex | 380 - .../documentation/subsec-poly-switches.tex | 1053 -- .../latexindent/documentation/subsec-text-wrap.tex | 513 - .../subsubsec-commands-with-arguments.tex | 109 - .../subsubsec-environments-and-their-arguments.tex | 294 - .../subsubsec-environments-with-items.tex | 60 - .../documentation/subsubsec-headings.tex | 87 - .../documentation/subsubsec-ifelsefi.tex | 87 - .../subsubsec-no-add-remaining-code-blocks.tex | 134 - .../documentation/subsubsec-special.tex | 67 - .../documentation/test-default-settings.tex | 65 - support/latexindent/documentation/title.tex | 30 - support/latexindent/latexindent.pl | 2 +- support/lyluatex/Contributors.md | 6 +- support/lyluatex/LICENSE | 2 +- support/lyluatex/README.md | 53 +- support/lyluatex/lyluatex-lib.lua | 163 - support/lyluatex/lyluatex-options.lua | 266 - support/lyluatex/lyluatex.lua | 275 +- support/lyluatex/lyluatex.pdf | Bin 1664216 -> 2028732 bytes support/lyluatex/lyluatex.sty | 27 +- support/lyluatex/lyluatex.tex | 301 +- support/lyluatex/lyluatexbase.cls | 6 +- support/lyluatex/lyluatexmanual.cls | 8 +- .../texlive/tlnet/tlpkg/installer/ctan-mirrors.pl | 5 - systems/texlive/tlnet/tlpkg/texlive.tlpdb | 375 +- systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 | 2 +- systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 | 2 +- .../texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc | 14 +- systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz | Bin 2422448 -> 2423428 bytes systems/win32/miktex/tm/packages/next/pr.ini | 8 +- systems/win32/miktex/tm/packages/pr.ini | 8 +- timestamp | 2 +- 165 files changed, 40442 insertions(+), 15215 deletions(-) delete mode 100644 macros/generic/tracklang/samples/animals/sample-animals-sr-poly.pdf create mode 100644 macros/generic/tracklang/tracklang-code.pdf create mode 100644 macros/generic/tracklang/tracklang-manual.html create mode 100644 macros/generic/tracklang/tracklang-manual.pdf create mode 100644 macros/generic/tracklang/tracklang-manual.tex delete mode 100644 macros/generic/tracklang/tracklang.pdf create mode 120000 macros/latex/contrib/pkuthss/doc/readme/ctex-fontset-pkuthss.def create mode 120000 macros/latex/contrib/pkuthss/doc/readme/ctexopts.cfg create mode 100644 macros/luatex/latex/luaoptions/Contributors.md create mode 100644 macros/luatex/latex/luaoptions/LICENSE create mode 100644 macros/luatex/latex/luaoptions/README.md create mode 100644 macros/luatex/latex/luaoptions/latexmkrc create mode 100644 macros/luatex/latex/luaoptions/luaoptions-lib.lua create mode 100644 macros/luatex/latex/luaoptions/luaoptions.lua create mode 100644 macros/luatex/latex/luaoptions/luaoptions.pdf create mode 100644 macros/luatex/latex/luaoptions/luaoptions.sty create mode 100644 macros/luatex/latex/luaoptions/luaoptions.tex create mode 100644 macros/luatex/latex/luaoptions/luaoptionsbase.cls create mode 100644 macros/luatex/latex/luaoptions/luaoptionsmanual.cls create mode 100644 support/latexindent/bin/linux/latexindent create mode 100644 support/latexindent/bin/macos/latexindent delete mode 100644 support/latexindent/documentation/cmhlistings.tex create mode 100644 support/latexindent/documentation/contributors.bib delete mode 100644 support/latexindent/documentation/figure-schematic.tex create mode 100644 support/latexindent/documentation/latex-indent.bib delete mode 100644 support/latexindent/documentation/logo.tex delete mode 100644 support/latexindent/documentation/sec-appendices.tex delete mode 100644 support/latexindent/documentation/sec-conclusions-know-limitations.tex delete mode 100644 support/latexindent/documentation/sec-default-user-local.tex delete mode 100644 support/latexindent/documentation/sec-demonstration.tex delete mode 100644 support/latexindent/documentation/sec-fine-tuning.tex delete mode 100644 support/latexindent/documentation/sec-how-to-use.tex delete mode 100644 support/latexindent/documentation/sec-indent-config-and-settings.tex delete mode 100644 support/latexindent/documentation/sec-introduction.tex delete mode 100644 support/latexindent/documentation/sec-references.tex delete mode 100644 support/latexindent/documentation/sec-replacements.tex delete mode 100644 support/latexindent/documentation/sec-the-line-switch.tex delete mode 100644 support/latexindent/documentation/sec-the-m-switch.tex delete mode 100644 support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex delete mode 100644 support/latexindent/documentation/subsec-commands-and-their-options.tex delete mode 100644 support/latexindent/documentation/subsec-noAdditionalIndent-indentRules.tex delete mode 100644 support/latexindent/documentation/subsec-one-sentence-per-line.tex delete mode 100644 support/latexindent/documentation/subsec-poly-switches.tex delete mode 100644 support/latexindent/documentation/subsec-text-wrap.tex delete mode 100644 support/latexindent/documentation/subsubsec-commands-with-arguments.tex delete mode 100644 support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex delete mode 100644 support/latexindent/documentation/subsubsec-environments-with-items.tex delete mode 100644 support/latexindent/documentation/subsubsec-headings.tex delete mode 100644 support/latexindent/documentation/subsubsec-ifelsefi.tex delete mode 100644 support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex delete mode 100644 support/latexindent/documentation/subsubsec-special.tex delete mode 100644 support/latexindent/documentation/test-default-settings.tex delete mode 100644 support/latexindent/documentation/title.tex delete mode 100644 support/lyluatex/lyluatex-lib.lua delete mode 100644 support/lyluatex/lyluatex-options.lua diff --git a/FILES.byname b/FILES.byname index 28ebf079c6..7f5cb1cfde 100644 --- a/FILES.byname +++ b/FILES.byname @@ -2035,12 +2035,12 @@ 2022/09/23 | 1673 | biblio/citation-style-language/README.md 2022/09/23 | 11958 | biblio/citation-style-language/vancouver.csl 2022/09/23 | 591448 | biblio/citation-style-language.zip -2022/10/29 | 1678 | biblio/ctan-bibdata/biblatex-ctan/ctan.bbx +2022/10/30 | 1678 | biblio/ctan-bibdata/biblatex-ctan/ctan.bbx 2022/10/08 | 127 | biblio/ctan-bibdata/biblatex-ctan/ctan.cbx -2022/10/29 | 2742861 | biblio/ctan-bibdata/ctan.bib -2022/10/29 | 3620091 | biblio/ctan-bibdata/ctan.pdf +2022/10/30 | 2743007 | biblio/ctan-bibdata/ctan.bib +2022/10/30 | 3620853 | biblio/ctan-bibdata/ctan.pdf 2022/10/08 | 1415 | biblio/ctan-bibdata/README -2022/10/29 | 4012177 | biblio/ctan-bibdata.zip +2022/10/30 | 4012760 | biblio/ctan-bibdata.zip 2022/02/06 | 3110 | biblio/pbibtex/pbibtex-base/cpp.awk 2022/02/06 | 1009 | biblio/pbibtex/pbibtex-base/generate.sh 2022/02/06 | 22422 | biblio/pbibtex/pbibtex-base/jabbrv.bst @@ -5414,7 +5414,7 @@ 1990/10/02 | 5440 | dviware/vutex/vaxvms.hlp 1990/10/02 | 812 | dviware/vutex/vaxvms.ins 1990/10/02 | 127576 | dviware/vutex/vutex.web -2022/10/29 | 57086 | FILES.last07days +2022/10/30 | 61524 | FILES.last07days 2021/07/24 | 1139410 | fonts/aboensis/Aboensis.glyphs 2021/07/24 | 18907382 | fonts/aboensis/aboensis.pdf 2021/07/24 | 137860 | fonts/aboensis/Aboensis-Regular.otf @@ -47109,7 +47109,7 @@ 2013/11/03 | 2854 | fonts/gillius/enc/gls_pqq4vh.enc 2013/11/03 | 3350 | fonts/gillius/enc/gls_shb4ap.enc 2022/10/28 | 2585 | fonts/gillius/latex/gillius2.sty -2022/10/28 | 2559 | fonts/gillius/latex/gillius.sty +2022/10/30 | 2525 | fonts/gillius/latex/gillius.sty 2013/11/03 | 1343 | fonts/gillius/latex/LY1GilliusADFCond-LF.fd 2013/11/03 | 1227 | fonts/gillius/latex/LY1GilliusADF-LF.fd 2013/11/03 | 1480 | fonts/gillius/latex/LY1GilliusADFNoTwoCond-LF.fd @@ -47143,7 +47143,7 @@ 2013/11/03 | 39280 | fonts/gillius/opentype/GilliusADFNo2-Italic.otf 2013/11/03 | 36280 | fonts/gillius/opentype/GilliusADFNo2-Regular.otf 2013/11/03 | 36488 | fonts/gillius/opentype/GilliusADF-Regular.otf -2022/10/28 | 1804 | fonts/gillius/README +2022/10/30 | 1804 | fonts/gillius/README 2013/11/03 | 2112 | fonts/gillius/tfm/GilliusADF-BoldItalic-lf-ly1--base.tfm 2013/11/03 | 160 | fonts/gillius/tfm/GilliusADF-BoldItalic-lf-ly1--lcdfj.tfm 2013/11/03 | 8012 | fonts/gillius/tfm/GilliusADF-BoldItalic-lf-ly1.tfm @@ -47416,7 +47416,7 @@ 2013/11/03 | 828 | fonts/gillius/vf/GilliusADF-Regular-lf-ot1.vf 2013/11/03 | 1472 | fonts/gillius/vf/GilliusADF-Regular-lf-t1.vf 2013/11/03 | 568 | fonts/gillius/vf/GilliusADF-Regular-lf-ts1.vf -2022/10/28 | 1692245 | fonts/gillius.zip +2022/10/30 | 1692229 | fonts/gillius.zip 2010/09/19 | 4330104 | fonts/gnu-freefont/freefont-otf-20100919.zip 2010/09/19 | 198 | fonts/gnu-freefont/freefont-otf-20100919.zip.sig 2012/05/03 | 4487813 | fonts/gnu-freefont/freefont-otf-20120503.tar.gz @@ -158655,11 +158655,11 @@ 2010/10/10 | 82 | graphics/pgf/contrib/bodegraph/gnuplot/bodegraph/9.table 2010/10/10 | 473 | graphics/pgf/contrib/bodegraph/README 2010/10/10 | 421558 | graphics/pgf/contrib/bodegraph.zip -2022/07/31 | 97095 | graphics/pgf/contrib/bodeplot/bodeplot.dtx -2022/07/31 | 1416 | graphics/pgf/contrib/bodeplot/bodeplot.ins -2022/07/31 | 1062592 | graphics/pgf/contrib/bodeplot/bodeplot.pdf -2022/07/31 | 3623 | graphics/pgf/contrib/bodeplot/README.md -2022/08/01 | 775056 | graphics/pgf/contrib/bodeplot.zip +2022/10/30 | 910334 | graphics/pgf/contrib/bodeplot/bodeplot.dtx +2022/10/30 | 239667 | graphics/pgf/contrib/bodeplot/bodeplot.ins +2022/10/30 | 1066728 | graphics/pgf/contrib/bodeplot/bodeplot.pdf +2022/10/30 | 231797 | graphics/pgf/contrib/bodeplot/README.md +2022/10/30 | 933144 | graphics/pgf/contrib/bodeplot.zip 2022/10/26 | 83144 | graphics/pgf/contrib/braids/braids_code.dtx 2022/10/26 | 456447 | graphics/pgf/contrib/braids/braids_code.pdf 2022/10/26 | 301271 | graphics/pgf/contrib/braids/braids.pdf @@ -189542,7 +189542,7 @@ 2022/10/01 | 2854553 | install/fonts/gandhi.tds.zip 2020/10/04 | 2453307 | install/fonts/garamondx.tds.zip 2010/07/30 | 245583 | install/fonts/gillcm.tds.zip -2022/10/28 | 1721197 | install/fonts/gillius.tds.zip +2022/10/30 | 1721181 | install/fonts/gillius.tds.zip 2022/09/12 | 2337829 | install/fonts/gofonts.tds.zip 2012/09/06 | 467812 | install/fonts/hacm.tds.zip 2019/06/10 | 1774481 | install/fonts/heuristica.tds.zip @@ -189694,7 +189694,7 @@ 2014/01/02 | 496633 | install/macros/generic/minifp.tds.zip 2012/09/20 | 369585 | install/macros/generic/plainpkg.tds.zip 2018/08/26 | 1014893 | install/macros/generic/tex-locale.tds.zip -2020/06/30 | 1215011 | install/macros/generic/tracklang.tds.zip +2022/10/29 | 1943892 | install/macros/generic/tracklang.tds.zip 2022/09/17 | 591247 | install/macros/generic/unicode-data.tds.zip 2022/06/11 | 4242531 | install/macros/generic/xint.tds.zip 2022/07/13 | 10946453 | install/macros/jptex/latex/jlreq.tds.zip @@ -189730,7 +189730,7 @@ 2019/01/28 | 1087181 | install/macros/latex/contrib/bezos.tds.zip 2009/07/16 | 3362 | install/macros/latex/contrib/biblatex-contrib/authoryear-icomp-tt.tds.zip 2019/12/30 | 7384611 | install/macros/latex/contrib/biblatex-contrib/biblatex-archaeology.tds.zip -2020/11/01 | 512537 | install/macros/latex/contrib/biblatex-contrib/biblatex-caspervector.tds.zip +2022/10/30 | 632099 | install/macros/latex/contrib/biblatex-contrib/biblatex-caspervector.tds.zip 2021/02/24 | 1516879 | install/macros/latex/contrib/biblatex-contrib/biblatex-chem.tds.zip 2016/12/06 | 1778620 | install/macros/latex/contrib/biblatex-contrib/biblatex-dw.tds.zip 2021/12/06 | 712419 | install/macros/latex/contrib/biblatex-contrib/biblatex-ieee.tds.zip @@ -189917,7 +189917,7 @@ 2019/09/23 | 318990 | install/macros/latex/contrib/perltex.tds.zip 2013/10/16 | 519904 | install/macros/latex/contrib/pfarrei.tds.zip 2014/07/10 | 183200 | install/macros/latex/contrib/pgfopts.tds.zip -2022/05/04 | 608085 | install/macros/latex/contrib/pkuthss.tds.zip +2022/10/30 | 518498 | install/macros/latex/contrib/pkuthss.tds.zip 2019/12/05 | 621416 | install/macros/latex/contrib/pmboxdraw.tds.zip 2014/09/10 | 1054773 | install/macros/latex/contrib/pressrelease.tds.zip 2017/07/10 | 1127276 | install/macros/latex/contrib/probsoln.tds.zip @@ -190048,7 +190048,7 @@ 2015/02/17 | 92757 | install/macros/xetex/latex/interchar.tds.zip 2021/08/19 | 464024 | install/macros/xetex/latex/mynsfc.tds.zip 2022/08/05 | 2009524 | install/macros/xetex/latex/xecjk.tds.zip -2022/07/02 | 1295671 | install/macros/xetex/latex/xepersian.tds.zip +2022/10/30 | 1290311 | install/macros/xetex/latex/xepersian.tds.zip 2008/06/20 | 3954 | install/macros/xetex/plain/xetexfontinfo.tds.zip 2013/01/04 | 36361 | install/support/adhocfilelist.tds.zip 2021/11/27 | 2294905 | install/support/albatross.tds.zip @@ -198916,84 +198916,86 @@ 2020/02/04 | 131 | macros/generic/tokcycle/tokcycle.sty 2021/08/25 | 18738 | macros/generic/tokcycle/tokcycle.tex 2021/08/25 | 1223986 | macros/generic/tokcycle.zip -2020/06/30 | 4310 | macros/generic/tracklang/CHANGES -2020/06/30 | 930 | macros/generic/tracklang/README -2020/06/30 | 313 | macros/generic/tracklang/samples/animals/animals2-en-GB.ldf -2020/06/30 | 249 | macros/generic/tracklang/samples/animals/animals2-english.ldf -2020/06/30 | 310 | macros/generic/tracklang/samples/animals/animals2-en-US.ldf -2020/06/30 | 246 | macros/generic/tracklang/samples/animals/animals2-german.ldf -2020/06/30 | 848 | macros/generic/tracklang/samples/animals/animals2.sty -2020/06/30 | 221 | macros/generic/tracklang/samples/animals/animals-en-GB.ldf -2020/06/30 | 249 | macros/generic/tracklang/samples/animals/animals-english.ldf -2020/06/30 | 221 | macros/generic/tracklang/samples/animals/animals-en-US.ldf -2020/06/30 | 246 | macros/generic/tracklang/samples/animals/animals-german.ldf -2020/06/30 | 784 | macros/generic/tracklang/samples/animals/animals.sty -2020/06/30 | 13625 | macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf -2020/06/30 | 166 | macros/generic/tracklang/samples/animals/sample-animals2-de2.tex -2020/06/30 | 13607 | macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf -2020/06/30 | 178 | macros/generic/tracklang/samples/animals/sample-animals2-de3.tex -2020/06/30 | 3820 | macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf -2020/06/30 | 194 | macros/generic/tracklang/samples/animals/sample-animals2-de4.tex -2020/06/30 | 13625 | macros/generic/tracklang/samples/animals/sample-animals2-de.pdf -2020/06/30 | 173 | macros/generic/tracklang/samples/animals/sample-animals2-de.tex -2020/06/30 | 12656 | macros/generic/tracklang/samples/animals/sample-animals2.pdf -2020/06/30 | 3560 | macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf -2020/06/30 | 215 | macros/generic/tracklang/samples/animals/sample-animals2-poly.tex -2020/06/30 | 271 | macros/generic/tracklang/samples/animals/sample-animals2.tex -2020/06/30 | 14855 | macros/generic/tracklang/samples/animals/sample-animals-babel.pdf -2020/06/30 | 327 | macros/generic/tracklang/samples/animals/sample-animals-babel.tex -2020/06/30 | 13625 | macros/generic/tracklang/samples/animals/sample-animals-de.pdf -2020/06/30 | 3820 | macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf -2020/06/30 | 193 | macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex -2020/06/30 | 172 | macros/generic/tracklang/samples/animals/sample-animals-de.tex -2020/06/30 | 12656 | macros/generic/tracklang/samples/animals/sample-animals.pdf -2020/06/30 | 3556 | macros/generic/tracklang/samples/animals/sample-animals-poly.pdf -2020/06/30 | 214 | macros/generic/tracklang/samples/animals/sample-animals-poly.tex -2020/06/30 | 7547 | macros/generic/tracklang/samples/animals/sample-animals-sr-poly.pdf -2020/06/30 | 223 | macros/generic/tracklang/samples/animals/sample-animals.tex -2020/06/30 | 1124 | macros/generic/tracklang/samples/regions/regions2.sty -2020/06/30 | 221 | macros/generic/tracklang/samples/regions/regions-BE.ldf -2020/06/30 | 221 | macros/generic/tracklang/samples/regions/regions-CA.ldf -2020/06/30 | 165 | macros/generic/tracklang/samples/regions/regions-dutch.ldf -2020/06/30 | 164 | macros/generic/tracklang/samples/regions/regions-english.ldf -2020/06/30 | 164 | macros/generic/tracklang/samples/regions/regions-french.ldf -2020/06/30 | 221 | macros/generic/tracklang/samples/regions/regions-GB.ldf -2020/06/30 | 171 | macros/generic/tracklang/samples/regions/regions-german.ldf -2020/06/30 | 226 | macros/generic/tracklang/samples/regions/regions-IM.ldf -2020/06/30 | 153 | macros/generic/tracklang/samples/regions/regions-italian.ldf -2020/06/30 | 193 | macros/generic/tracklang/samples/regions/regions-manx.ldf -2020/06/30 | 941 | macros/generic/tracklang/samples/regions/regions.sty -2020/06/30 | 221 | macros/generic/tracklang/samples/regions/regions-US.ldf -2020/06/30 | 21945 | macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf -2020/06/30 | 158 | macros/generic/tracklang/samples/regions/sample-regions2-manx.tex -2020/06/30 | 25852 | macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf -2020/06/30 | 562 | macros/generic/tracklang/samples/regions/sample-regions2-map2.tex -2020/06/30 | 24924 | macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf -2020/06/30 | 376 | macros/generic/tracklang/samples/regions/sample-regions2-map3.tex -2020/06/30 | 26000 | macros/generic/tracklang/samples/regions/sample-regions2-map.pdf -2020/06/30 | 630 | macros/generic/tracklang/samples/regions/sample-regions2-map.tex -2020/06/30 | 25468 | macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf -2020/06/30 | 359 | macros/generic/tracklang/samples/regions/sample-regions2-nomap.tex -2020/06/30 | 14716 | macros/generic/tracklang/samples/regions/sample-regions2.pdf -2020/06/30 | 186 | macros/generic/tracklang/samples/regions/sample-regions2.tex -2020/06/30 | 13161 | macros/generic/tracklang/samples/regions/sample-regions.pdf -2020/06/30 | 257 | macros/generic/tracklang/samples/regions/sample-regions.tex -2020/06/30 | 19802 | macros/generic/tracklang/samples/sample-tracklang2.pdf -2020/06/30 | 1454 | macros/generic/tracklang/samples/sample-tracklang2.tex -2020/06/30 | 19814 | macros/generic/tracklang/samples/sample-tracklang3.pdf -2020/06/30 | 1459 | macros/generic/tracklang/samples/sample-tracklang3.tex -2020/06/30 | 6202 | macros/generic/tracklang/samples/sample-tracklang4.pdf -2020/06/30 | 781 | macros/generic/tracklang/samples/sample-tracklang4.tex -2020/06/30 | 16914 | macros/generic/tracklang/samples/sample-tracklang5.pdf -2020/06/30 | 689 | macros/generic/tracklang/samples/sample-tracklang5.tex -2020/06/30 | 19897 | macros/generic/tracklang/samples/sample-tracklang6.pdf -2020/06/30 | 1041 | macros/generic/tracklang/samples/sample-tracklang6.tex -2020/06/30 | 19552 | macros/generic/tracklang/samples/sample-tracklang.pdf -2020/06/30 | 1454 | macros/generic/tracklang/samples/sample-tracklang.tex -2020/06/30 | 434306 | macros/generic/tracklang/tracklang.dtx -2020/06/30 | 1553 | macros/generic/tracklang/tracklang.ins -2020/06/30 | 742279 | macros/generic/tracklang/tracklang.pdf -2020/06/30 | 1179750 | macros/generic/tracklang.zip +2022/10/29 | 4436 | macros/generic/tracklang/CHANGES +2022/10/29 | 930 | macros/generic/tracklang/README +2022/10/29 | 313 | macros/generic/tracklang/samples/animals/animals2-en-GB.ldf +2022/10/29 | 249 | macros/generic/tracklang/samples/animals/animals2-english.ldf +2022/10/29 | 310 | macros/generic/tracklang/samples/animals/animals2-en-US.ldf +2022/10/29 | 246 | macros/generic/tracklang/samples/animals/animals2-german.ldf +2022/10/29 | 848 | macros/generic/tracklang/samples/animals/animals2.sty +2022/10/29 | 221 | macros/generic/tracklang/samples/animals/animals-en-GB.ldf +2022/10/29 | 249 | macros/generic/tracklang/samples/animals/animals-english.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/animals/animals-en-US.ldf +2022/10/29 | 246 | macros/generic/tracklang/samples/animals/animals-german.ldf +2022/10/29 | 784 | macros/generic/tracklang/samples/animals/animals.sty +2022/10/29 | 14463 | macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf +2022/10/29 | 166 | macros/generic/tracklang/samples/animals/sample-animals2-de2.tex +2022/10/29 | 14444 | macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf +2022/10/29 | 178 | macros/generic/tracklang/samples/animals/sample-animals2-de3.tex +2022/10/29 | 3823 | macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf +2022/10/29 | 194 | macros/generic/tracklang/samples/animals/sample-animals2-de4.tex +2022/10/29 | 14463 | macros/generic/tracklang/samples/animals/sample-animals2-de.pdf +2022/10/29 | 173 | macros/generic/tracklang/samples/animals/sample-animals2-de.tex +2022/10/29 | 13489 | macros/generic/tracklang/samples/animals/sample-animals2.pdf +2022/10/29 | 3559 | macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf +2022/10/29 | 215 | macros/generic/tracklang/samples/animals/sample-animals2-poly.tex +2022/10/29 | 271 | macros/generic/tracklang/samples/animals/sample-animals2.tex +2022/10/29 | 15690 | macros/generic/tracklang/samples/animals/sample-animals-babel.pdf +2022/10/29 | 327 | macros/generic/tracklang/samples/animals/sample-animals-babel.tex +2022/10/29 | 14463 | macros/generic/tracklang/samples/animals/sample-animals-de.pdf +2022/10/29 | 3823 | macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf +2022/10/29 | 232 | macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex +2022/10/29 | 172 | macros/generic/tracklang/samples/animals/sample-animals-de.tex +2022/10/29 | 13489 | macros/generic/tracklang/samples/animals/sample-animals.pdf +2022/10/29 | 3560 | macros/generic/tracklang/samples/animals/sample-animals-poly.pdf +2022/10/29 | 214 | macros/generic/tracklang/samples/animals/sample-animals-poly.tex +2022/10/29 | 223 | macros/generic/tracklang/samples/animals/sample-animals.tex +2022/10/29 | 1124 | macros/generic/tracklang/samples/regions/regions2.sty +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-BE.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-CA.ldf +2022/10/29 | 165 | macros/generic/tracklang/samples/regions/regions-dutch.ldf +2022/10/29 | 164 | macros/generic/tracklang/samples/regions/regions-english.ldf +2022/10/29 | 164 | macros/generic/tracklang/samples/regions/regions-french.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-GB.ldf +2022/10/29 | 171 | macros/generic/tracklang/samples/regions/regions-german.ldf +2022/10/29 | 226 | macros/generic/tracklang/samples/regions/regions-IM.ldf +2022/10/29 | 153 | macros/generic/tracklang/samples/regions/regions-italian.ldf +2022/10/29 | 193 | macros/generic/tracklang/samples/regions/regions-manx.ldf +2022/10/29 | 941 | macros/generic/tracklang/samples/regions/regions.sty +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-US.ldf +2022/10/29 | 23587 | macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf +2022/10/29 | 158 | macros/generic/tracklang/samples/regions/sample-regions2-manx.tex +2022/10/29 | 27515 | macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf +2022/10/29 | 562 | macros/generic/tracklang/samples/regions/sample-regions2-map2.tex +2022/10/29 | 26590 | macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf +2022/10/29 | 376 | macros/generic/tracklang/samples/regions/sample-regions2-map3.tex +2022/10/29 | 27666 | macros/generic/tracklang/samples/regions/sample-regions2-map.pdf +2022/10/29 | 630 | macros/generic/tracklang/samples/regions/sample-regions2-map.tex +2022/10/29 | 27134 | macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf +2022/10/29 | 359 | macros/generic/tracklang/samples/regions/sample-regions2-nomap.tex +2022/10/29 | 15551 | macros/generic/tracklang/samples/regions/sample-regions2.pdf +2022/10/29 | 186 | macros/generic/tracklang/samples/regions/sample-regions2.tex +2022/10/29 | 13996 | macros/generic/tracklang/samples/regions/sample-regions.pdf +2022/10/29 | 257 | macros/generic/tracklang/samples/regions/sample-regions.tex +2022/10/29 | 20747 | macros/generic/tracklang/samples/sample-tracklang2.pdf +2022/10/29 | 1454 | macros/generic/tracklang/samples/sample-tracklang2.tex +2022/10/29 | 20758 | macros/generic/tracklang/samples/sample-tracklang3.pdf +2022/10/29 | 1459 | macros/generic/tracklang/samples/sample-tracklang3.tex +2022/10/29 | 6869 | macros/generic/tracklang/samples/sample-tracklang4.pdf +2022/10/29 | 781 | macros/generic/tracklang/samples/sample-tracklang4.tex +2022/10/29 | 17857 | macros/generic/tracklang/samples/sample-tracklang5.pdf +2022/10/29 | 689 | macros/generic/tracklang/samples/sample-tracklang5.tex +2022/10/29 | 19898 | macros/generic/tracklang/samples/sample-tracklang6.pdf +2022/10/29 | 1041 | macros/generic/tracklang/samples/sample-tracklang6.tex +2022/10/29 | 20388 | macros/generic/tracklang/samples/sample-tracklang.pdf +2022/10/29 | 1454 | macros/generic/tracklang/samples/sample-tracklang.tex +2022/10/29 | 629107 | macros/generic/tracklang/tracklang-code.pdf +2022/10/29 | 310371 | macros/generic/tracklang/tracklang.dtx +2022/10/29 | 1554 | macros/generic/tracklang/tracklang.ins +2022/10/29 | 1023122 | macros/generic/tracklang/tracklang-manual.html +2022/10/29 | 764697 | macros/generic/tracklang/tracklang-manual.pdf +2022/10/29 | 210917 | macros/generic/tracklang/tracklang-manual.tex +2022/10/30 | 1908612 | macros/generic/tracklang.zip 2017/01/21 | 537 | macros/generic/trigonometry/README.txt 1991/10/06 | 5675 | macros/generic/trigonometry/trigonometry.tex 2017/01/21 | 2844 | macros/generic/trigonometry.zip @@ -209331,22 +209333,22 @@ 2012/05/21 | 106326 | macros/latex/contrib/biblatex-contrib/biblatex-bwl/doc/bwl-FU.pdf 2012/05/21 | 766 | macros/latex/contrib/biblatex-contrib/biblatex-bwl/doc/bwl-FU.tex 2012/05/21 | 115659 | macros/latex/contrib/biblatex-contrib/biblatex-bwl.zip -2020/11/01 | 172785 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf -2020/11/01 | 2272 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.tex -2020/11/01 | 24633 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.bib -2020/11/01 | 314272 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf -2020/11/01 | 23876 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex -2020/11/01 | 7778 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt -2020/11/01 | 227 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/latexmkrc -2020/11/01 | 532 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/README.txt -2020/11/01 | 14527 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def -2020/11/01 | 1500 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def -2020/11/01 | 1531 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def -2020/11/01 | 2349 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx -2020/11/01 | 1119 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx -2020/11/01 | 1061 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx -2020/11/01 | 1664 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx -2020/11/02 | 510993 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector.zip +2022/10/30 | 212575 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf +2022/10/30 | 2272 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.tex +2022/10/30 | 24633 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.bib +2022/10/30 | 393884 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf +2022/10/30 | 23969 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex +2022/10/30 | 7844 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt +2022/10/30 | 227 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/latexmkrc +2022/10/30 | 532 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/README.txt +2022/10/30 | 14902 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def +2022/10/30 | 1500 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def +2022/10/30 | 1531 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def +2022/10/30 | 2349 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx +2022/10/30 | 1119 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx +2022/10/30 | 1061 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx +2022/10/30 | 1664 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx +2022/10/30 | 630555 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector.zip 2021/02/24 | 291091 | macros/latex/contrib/biblatex-contrib/biblatex-chem/biblatex-chem-acs.pdf 2021/02/24 | 2485 | macros/latex/contrib/biblatex-contrib/biblatex-chem/biblatex-chem-acs.tex 2021/02/24 | 275052 | macros/latex/contrib/biblatex-contrib/biblatex-chem/biblatex-chem-angew.pdf @@ -215591,15 +215593,15 @@ 2008/06/01 | 200380 | macros/latex/contrib/envlab/envlab.pdf 1997/07/16 | 3824 | macros/latex/contrib/envlab/readme.v12 2008/06/02 | 372141 | macros/latex/contrib/envlab.zip -2022/10/29 | 47687 | macros/latex/contrib/eolang/cactus.pdf -2022/10/29 | 146 | macros/latex/contrib/eolang/DEPENDS.txt -2022/10/29 | 641 | macros/latex/contrib/eolang/eolang.bib -2022/10/29 | 25212 | macros/latex/contrib/eolang/eolang.dtx -2022/10/29 | 2628 | macros/latex/contrib/eolang/eolang.ins -2022/10/29 | 969068 | macros/latex/contrib/eolang/eolang.pdf -2022/10/29 | 1083 | macros/latex/contrib/eolang/LICENSE.txt -2022/10/29 | 1352 | macros/latex/contrib/eolang/README.md -2022/10/29 | 996929 | macros/latex/contrib/eolang.zip +2022/10/30 | 47687 | macros/latex/contrib/eolang/cactus.pdf +2022/10/30 | 159 | macros/latex/contrib/eolang/DEPENDS.txt +2022/10/30 | 641 | macros/latex/contrib/eolang/eolang.bib +2022/10/30 | 27563 | macros/latex/contrib/eolang/eolang.dtx +2022/10/30 | 2628 | macros/latex/contrib/eolang/eolang.ins +2022/10/30 | 1036825 | macros/latex/contrib/eolang/eolang.pdf +2022/10/30 | 1083 | macros/latex/contrib/eolang/LICENSE.txt +2022/10/30 | 1352 | macros/latex/contrib/eolang/README.md +2022/10/30 | 1063401 | macros/latex/contrib/eolang.zip 1991/01/31 | 1291 | macros/latex/contrib/epic/epic.readme 2009/07/09 | 25846 | macros/latex/contrib/epic/epic.sty 1991/01/31 | 2444 | macros/latex/contrib/epic/misc.sty @@ -216876,13 +216878,13 @@ 2013/05/03 | 374250 | macros/latex/contrib/feynmp-auto/feynmp-auto.pdf 2013/05/03 | 1652 | macros/latex/contrib/feynmp-auto/README 2013/05/03 | 378807 | macros/latex/contrib/feynmp-auto.zip -2022/10/03 | 62 | macros/latex/contrib/ffcode/DEPENDS.txt -2022/10/03 | 9582 | macros/latex/contrib/ffcode/ffcode.dtx -2022/10/03 | 2644 | macros/latex/contrib/ffcode/ffcode.ins -2022/10/03 | 395644 | macros/latex/contrib/ffcode/ffcode.pdf -2022/10/03 | 1083 | macros/latex/contrib/ffcode/LICENSE.txt -2022/10/03 | 1351 | macros/latex/contrib/ffcode/README.md -2022/10/03 | 398411 | macros/latex/contrib/ffcode.zip +2022/10/30 | 40 | macros/latex/contrib/ffcode/DEPENDS.txt +2022/10/30 | 9122 | macros/latex/contrib/ffcode/ffcode.dtx +2022/10/30 | 2628 | macros/latex/contrib/ffcode/ffcode.ins +2022/10/30 | 487461 | macros/latex/contrib/ffcode/ffcode.pdf +2022/10/30 | 1083 | macros/latex/contrib/ffcode/LICENSE.txt +2022/10/30 | 1376 | macros/latex/contrib/ffcode/README.md +2022/10/30 | 488622 | macros/latex/contrib/ffcode.zip 2015/10/21 | 398 | macros/latex/contrib/ffslides/bground-example.txt 2015/11/19 | 15305 | macros/latex/contrib/ffslides/ffslides.cls 2015/11/19 | 2747893 | macros/latex/contrib/ffslides/ffslides-doc.pdf @@ -227717,48 +227719,48 @@ 2018/04/29 | 1768 | macros/latex/contrib/pkgloader/pkgloader-true.sty 2018/04/29 | 1388 | macros/latex/contrib/pkgloader/README 2018/04/29 | 488889 | macros/latex/contrib/pkgloader.zip -2022/05/04 | 288 | macros/latex/contrib/pkuthss/doc/example/chap/abs.tex -2022/05/04 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/ack.tex -2022/05/04 | 138 | macros/latex/contrib/pkuthss/doc/example/chap/chap1.tex -2022/05/04 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/chap2.tex -2022/05/04 | 147 | macros/latex/contrib/pkuthss/doc/example/chap/chap3.tex -2022/05/04 | 2349 | macros/latex/contrib/pkuthss/doc/example/chap/copy.tex -2022/05/04 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/encl1.tex -2022/05/04 | 3775 | macros/latex/contrib/pkuthss/doc/example/chap/origin.tex -2022/05/04 | 2224 | macros/latex/contrib/pkuthss/doc/example/ctex-fontset-pkuthss.def -2022/05/04 | 115 | macros/latex/contrib/pkuthss/doc/example/ctexopts.cfg -2022/05/04 | 461 | macros/latex/contrib/pkuthss/doc/example/latexmkrc -2022/05/04 | 364 | macros/latex/contrib/pkuthss/doc/example/Make.bat -2022/05/04 | 103792 | macros/latex/contrib/pkuthss/doc/example.pdf -2022/05/04 | 1434 | macros/latex/contrib/pkuthss/doc/example/spine.tex -2022/05/04 | 294 | macros/latex/contrib/pkuthss/doc/example/thesis.bib -2022/05/04 | 5446 | macros/latex/contrib/pkuthss/doc/example/thesis.tex -2022/05/04 | 439556 | macros/latex/contrib/pkuthss/doc/pkuthss.pdf -2022/05/04 | 14997 | macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt -2022/05/04 | 3035 | macros/latex/contrib/pkuthss/doc/readme/ChangeLog-upto-1.3.txt -2022/05/04 | 1219 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-abs.tex -2022/05/04 | 1994 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-ack.tex -2022/05/04 | 7065 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap1.tex -2022/05/04 | 16545 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex -2022/05/04 | 6275 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex -2022/05/04 | 1143 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-concl.tex -2022/05/04 | 1569 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-copy.tex -2022/05/04 | 1170 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-encl1.tex -2022/05/04 | 2705 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex -2022/05/04 | 237 | macros/latex/contrib/pkuthss/doc/readme/latexmkrc -2022/05/04 | 8040 | macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib -2022/05/04 | 10371 | macros/latex/contrib/pkuthss/doc/readme/pkuthss-english.patch -2022/05/04 | 3304 | macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex -2022/05/04 | 684 | macros/latex/contrib/pkuthss/README.txt -2022/05/04 | 3957 | macros/latex/contrib/pkuthss/tex/pkulogo.eps -2022/05/04 | 3530 | macros/latex/contrib/pkuthss/tex/pkulogo.pdf -2022/05/04 | 16832 | macros/latex/contrib/pkuthss/tex/pkuthss.cls -2022/05/04 | 1575 | macros/latex/contrib/pkuthss/tex/pkuthss.def -2022/05/04 | 1593 | macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def -2022/05/04 | 1682 | macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def -2022/05/04 | 8139 | macros/latex/contrib/pkuthss/tex/pkuword.eps -2022/05/04 | 6280 | macros/latex/contrib/pkuthss/tex/pkuword.pdf -2022/05/04 | 604529 | macros/latex/contrib/pkuthss.zip +2022/10/30 | 288 | macros/latex/contrib/pkuthss/doc/example/chap/abs.tex +2022/10/30 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/ack.tex +2022/10/30 | 138 | macros/latex/contrib/pkuthss/doc/example/chap/chap1.tex +2022/10/30 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/chap2.tex +2022/10/30 | 147 | macros/latex/contrib/pkuthss/doc/example/chap/chap3.tex +2022/10/30 | 2349 | macros/latex/contrib/pkuthss/doc/example/chap/copy.tex +2022/10/30 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/encl1.tex +2022/10/30 | 3775 | macros/latex/contrib/pkuthss/doc/example/chap/origin.tex +2022/10/30 | 2224 | macros/latex/contrib/pkuthss/doc/example/ctex-fontset-pkuthss.def +2022/10/30 | 115 | macros/latex/contrib/pkuthss/doc/example/ctexopts.cfg +2022/10/30 | 461 | macros/latex/contrib/pkuthss/doc/example/latexmkrc +2022/10/30 | 364 | macros/latex/contrib/pkuthss/doc/example/Make.bat +2022/10/30 | 103719 | macros/latex/contrib/pkuthss/doc/example.pdf +2022/10/30 | 1489 | macros/latex/contrib/pkuthss/doc/example/spine.tex +2022/10/30 | 294 | macros/latex/contrib/pkuthss/doc/example/thesis.bib +2022/10/30 | 5463 | macros/latex/contrib/pkuthss/doc/example/thesis.tex +2022/10/30 | 348380 | macros/latex/contrib/pkuthss/doc/pkuthss.pdf +2022/10/30 | 15217 | macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt +2022/10/30 | 3035 | macros/latex/contrib/pkuthss/doc/readme/ChangeLog-upto-1.3.txt +2022/10/30 | 1219 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-abs.tex +2022/10/30 | 1994 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-ack.tex +2022/10/30 | 7065 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap1.tex +2022/10/30 | 16627 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex +2022/10/30 | 5804 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex +2022/10/30 | 1143 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-concl.tex +2022/10/30 | 1569 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-copy.tex +2022/10/30 | 1170 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-encl1.tex +2022/10/30 | 2713 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex +2022/10/30 | 237 | macros/latex/contrib/pkuthss/doc/readme/latexmkrc +2022/10/30 | 8078 | macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib +2022/10/30 | 10371 | macros/latex/contrib/pkuthss/doc/readme/pkuthss-english.patch +2022/10/30 | 3305 | macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex +2022/10/30 | 684 | macros/latex/contrib/pkuthss/README.txt +2022/10/30 | 3957 | macros/latex/contrib/pkuthss/tex/pkulogo.eps +2022/10/30 | 3530 | macros/latex/contrib/pkuthss/tex/pkulogo.pdf +2022/10/30 | 16634 | macros/latex/contrib/pkuthss/tex/pkuthss.cls +2022/10/30 | 1575 | macros/latex/contrib/pkuthss/tex/pkuthss.def +2022/10/30 | 1593 | macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def +2022/10/30 | 1682 | macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def +2022/10/30 | 8139 | macros/latex/contrib/pkuthss/tex/pkuword.eps +2022/10/30 | 6280 | macros/latex/contrib/pkuthss/tex/pkuword.pdf +2022/10/30 | 514814 | macros/latex/contrib/pkuthss.zip 2010/09/19 | 255447 | macros/latex/contrib/placeins/placeins-doc.pdf 2010/09/19 | 2914 | macros/latex/contrib/placeins/placeins-doc.tex 2005/04/19 | 4087 | macros/latex/contrib/placeins/placeins.sty @@ -239325,6 +239327,18 @@ 2022/07/11 | 48647 | macros/luatex/latex/luamesh/scripts/luamesh-tex.lua 2022/07/11 | 40229 | macros/luatex/latex/luamesh/tex/luamesh.sty 2022/07/11 | 274586 | macros/luatex/latex/luamesh.zip +2022/10/30 | 256 | macros/luatex/latex/luaoptions/Contributors.md +2022/10/30 | 58 | macros/luatex/latex/luaoptions/latexmkrc +2022/10/30 | 1099 | macros/luatex/latex/luaoptions/LICENSE +2022/10/30 | 1039 | macros/luatex/latex/luaoptions/luaoptionsbase.cls +2022/10/30 | 6378 | macros/luatex/latex/luaoptions/luaoptions-lib.lua +2022/10/30 | 10161 | macros/luatex/latex/luaoptions/luaoptions.lua +2022/10/30 | 984 | macros/luatex/latex/luaoptions/luaoptionsmanual.cls +2022/10/30 | 28593 | macros/luatex/latex/luaoptions/luaoptions.pdf +2022/10/30 | 827 | macros/luatex/latex/luaoptions/luaoptions.sty +2022/10/30 | 8322 | macros/luatex/latex/luaoptions/luaoptions.tex +2022/10/30 | 881 | macros/luatex/latex/luaoptions/README.md +2022/10/30 | 39904 | macros/luatex/latex/luaoptions.zip 2021/05/08 | 1069 | macros/luatex/latex/lua-physical/LICENSE 2021/05/08 | 52565 | macros/luatex/latex/lua-physical/lua-physical_example.pdf 2021/05/08 | 3427 | macros/luatex/latex/lua-physical/lua-physical_example.tex @@ -247571,13 +247585,13 @@ 2022/09/03 | 19106 | macros/unicodetex/latex/beaulivre/LICENSE 2022/09/03 | 1458 | macros/unicodetex/latex/beaulivre/README.md 2022/09/03 | 555182 | macros/unicodetex/latex/beaulivre.zip -2022/10/24 | 192811 | macros/unicodetex/latex/bithesis/bithesis.dtx -2022/10/24 | 3720 | macros/unicodetex/latex/bithesis/bithesis.ins -2022/10/24 | 1033346 | macros/unicodetex/latex/bithesis/bithesis.pdf -2022/10/24 | 2332 | macros/unicodetex/latex/bithesis/contributing.md -2022/10/24 | 2643 | macros/unicodetex/latex/bithesis/contributing-zh.md -2022/10/24 | 1993 | macros/unicodetex/latex/bithesis/README.md -2022/10/24 | 1061972 | macros/unicodetex/latex/bithesis.zip +2022/10/30 | 193944 | macros/unicodetex/latex/bithesis/bithesis.dtx +2022/10/30 | 3720 | macros/unicodetex/latex/bithesis/bithesis.ins +2022/10/30 | 1043619 | macros/unicodetex/latex/bithesis/bithesis.pdf +2022/10/30 | 2332 | macros/unicodetex/latex/bithesis/contributing.md +2022/10/30 | 2643 | macros/unicodetex/latex/bithesis/contributing-zh.md +2022/10/30 | 1993 | macros/unicodetex/latex/bithesis/README.md +2022/10/30 | 1073024 | macros/unicodetex/latex/bithesis.zip 2022/02/26 | 128251 | macros/unicodetex/latex/book-of-common-prayer/book-of-common-prayer.pdf 2022/02/26 | 6771 | macros/unicodetex/latex/book-of-common-prayer/book-of-common-prayer.sty 2022/02/26 | 17327 | macros/unicodetex/latex/book-of-common-prayer/book-of-common-prayer.tex @@ -248980,9 +248994,9 @@ 2014/12/05 | 4915 | macros/xetex/latex/xeindex/xeindex.sty 2014/12/05 | 19009 | macros/xetex/latex/xeindex/xeindex.tex 2014/12/05 | 79942 | macros/xetex/latex/xeindex.zip -2022/07/01 | 15976 | macros/xetex/latex/xepersian/dkun-0.3.py -2022/07/01 | 15867 | macros/xetex/latex/xepersian/dkun-0.4.py -2022/07/01 | 38725 | macros/xetex/latex/xepersian/ftxe-0.12.py +2022/10/30 | 15976 | macros/xetex/latex/xepersian/dkun-0.3.py +2022/10/30 | 15867 | macros/xetex/latex/xepersian/dkun-0.4.py +2022/10/30 | 38725 | macros/xetex/latex/xepersian/ftxe-0.12.py 2020/09/04 | 13130 | macros/xetex/latex/xepersian-hm/doc-ligature-xepersian-hm.pdf 2020/09/04 | 10104 | macros/xetex/latex/xepersian-hm/doc-ligature-xep.pdf 2020/09/04 | 63436 | macros/xetex/latex/xepersian-hm/doc-samples-glyph.pdf @@ -249004,26 +249018,26 @@ 2020/09/04 | 106056 | macros/xetex/latex/xepersian-hm/xepersian-XB.pdf 2020/09/04 | 2945 | macros/xetex/latex/xepersian-hm/xepersian-XB.tex 2020/09/04 | 2217805 | macros/xetex/latex/xepersian-hm.zip -2022/07/01 | 18304 | macros/xetex/latex/xepersian/img/ireland.jpg -2022/07/01 | 13088 | macros/xetex/latex/xepersian/img/weather/clouds.jpg -2022/07/01 | 14616 | macros/xetex/latex/xepersian/img/weather/rain.jpg -2022/07/01 | 10896 | macros/xetex/latex/xepersian/img/weather/sun.jpg -2022/07/02 | 1390 | macros/xetex/latex/xepersian/README -2022/07/01 | 13804 | macros/xetex/latex/xepersian/undk-0.6.py -2022/07/01 | 12348 | macros/xetex/latex/xepersian/unldk-0.2.py -2022/07/01 | 71387 | macros/xetex/latex/xepersian/xepersian-doc-basics.ltx -2022/07/01 | 410 | macros/xetex/latex/xepersian/xepersian-doc-boolean.ltx -2022/07/01 | 3099 | macros/xetex/latex/xepersian/xepersian-doc-captions.ltx -2022/07/01 | 5447 | macros/xetex/latex/xepersian/xepersian-doc-envcs.ltx -2022/07/01 | 2574 | macros/xetex/latex/xepersian/xepersian-doc-intro.ltx -2022/07/01 | 454 | macros/xetex/latex/xepersian/xepersian-doc.ltx -2022/07/02 | 243511 | macros/xetex/latex/xepersian/xepersian-doc.pdf -2022/07/01 | 25876 | macros/xetex/latex/xepersian/xepersian-doc-pkgs.ltx -2022/07/01 | 4149 | macros/xetex/latex/xepersian/xepersian-doc-preamble.ltx -2022/07/01 | 2108 | macros/xetex/latex/xepersian/xepersian-doc-title.ltx -2022/07/01 | 342921 | macros/xetex/latex/xepersian/xepersian.dtx -2022/07/02 | 775123 | macros/xetex/latex/xepersian/xepersian.pdf -2022/07/02 | 1130406 | macros/xetex/latex/xepersian.zip +2022/10/30 | 18304 | macros/xetex/latex/xepersian/img/ireland.jpg +2022/10/30 | 13088 | macros/xetex/latex/xepersian/img/weather/clouds.jpg +2022/10/30 | 14616 | macros/xetex/latex/xepersian/img/weather/rain.jpg +2022/10/30 | 10896 | macros/xetex/latex/xepersian/img/weather/sun.jpg +2022/10/30 | 1390 | macros/xetex/latex/xepersian/README +2022/10/30 | 13804 | macros/xetex/latex/xepersian/undk-0.6.py +2022/10/30 | 12348 | macros/xetex/latex/xepersian/unldk-0.2.py +2022/10/30 | 71387 | macros/xetex/latex/xepersian/xepersian-doc-basics.ltx +2022/10/30 | 410 | macros/xetex/latex/xepersian/xepersian-doc-boolean.ltx +2022/10/30 | 3099 | macros/xetex/latex/xepersian/xepersian-doc-captions.ltx +2022/10/30 | 5447 | macros/xetex/latex/xepersian/xepersian-doc-envcs.ltx +2022/10/30 | 2609 | macros/xetex/latex/xepersian/xepersian-doc-intro.ltx +2022/10/30 | 454 | macros/xetex/latex/xepersian/xepersian-doc.ltx +2022/10/30 | 236749 | macros/xetex/latex/xepersian/xepersian-doc.pdf +2022/10/30 | 25876 | macros/xetex/latex/xepersian/xepersian-doc-pkgs.ltx +2022/10/30 | 4149 | macros/xetex/latex/xepersian/xepersian-doc-preamble.ltx +2022/10/30 | 2108 | macros/xetex/latex/xepersian/xepersian-doc-title.ltx +2022/10/30 | 343317 | macros/xetex/latex/xepersian/xepersian.dtx +2022/10/30 | 777678 | macros/xetex/latex/xepersian/xepersian.pdf +2022/10/30 | 1124966 | macros/xetex/latex/xepersian.zip 2021/03/29 | 142 | macros/xetex/latex/xesoul/README 2021/03/29 | 3942 | macros/xetex/latex/xesoul/xesoul.dtx 2021/03/29 | 1517 | macros/xetex/latex/xesoul/xesoul.ins @@ -275688,87 +275702,61 @@ 2018/04/15 | 1313 | support/latex-git-log/po/de.po 2020/02/26 | 3353 | support/latex-git-log/README.md 2020/02/27 | 87742 | support/latex-git-log.zip -2022/06/12 | 19920 | support/latexindent/defaultSettings.yaml -2022/06/12 | 633 | support/latexindent/documentation/cmhlistings.tex -2022/06/12 | 7161 | support/latexindent/documentation/figure-schematic.png -2022/06/12 | 1879 | support/latexindent/documentation/figure-schematic.tex -2022/06/12 | 1106074 | support/latexindent/documentation/latexindent.pdf -2022/06/12 | 24110 | support/latexindent/documentation/latexindent.tex -2022/06/12 | 54383 | support/latexindent/documentation/latexindent-yaml-schema.json -2022/06/12 | 44096 | support/latexindent/documentation/logo.png -2022/06/12 | 1664 | support/latexindent/documentation/logo.tex -2022/06/12 | 31717 | support/latexindent/documentation/sec-appendices.tex -2022/06/12 | 1929 | support/latexindent/documentation/sec-conclusions-know-limitations.tex -2022/06/12 | 74181 | support/latexindent/documentation/sec-default-user-local.tex -2022/06/12 | 2109 | support/latexindent/documentation/sec-demonstration.tex -2022/06/12 | 15976 | support/latexindent/documentation/sec-fine-tuning.tex -2022/06/12 | 25309 | support/latexindent/documentation/sec-how-to-use.tex -2022/06/12 | 10829 | support/latexindent/documentation/sec-indent-config-and-settings.tex -2022/06/12 | 12065 | support/latexindent/documentation/sec-introduction.tex -2022/06/12 | 610 | support/latexindent/documentation/sec-references.tex -2022/06/12 | 21628 | support/latexindent/documentation/sec-replacements.tex -2022/06/12 | 8026 | support/latexindent/documentation/sec-the-line-switch.tex -2022/06/12 | 2997 | support/latexindent/documentation/sec-the-m-switch.tex -2022/06/12 | 5715 | support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex -2022/06/12 | 14024 | support/latexindent/documentation/subsec-commands-and-their-options.tex -2022/06/12 | 1887 | support/latexindent/documentation/subsec-noAdditionalIndent-indentRules.tex -2022/06/12 | 22332 | support/latexindent/documentation/subsec-one-sentence-per-line.tex -2022/06/12 | 66115 | support/latexindent/documentation/subsec-poly-switches.tex -2022/06/12 | 24851 | support/latexindent/documentation/subsec-text-wrap.tex -2022/06/12 | 5958 | support/latexindent/documentation/subsubsec-commands-with-arguments.tex -2022/06/12 | 16560 | support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex -2022/06/12 | 3433 | support/latexindent/documentation/subsubsec-environments-with-items.tex -2022/06/12 | 5266 | support/latexindent/documentation/subsubsec-headings.tex -2022/06/12 | 4855 | support/latexindent/documentation/subsubsec-ifelsefi.tex -2022/06/12 | 7193 | support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex -2022/06/12 | 3831 | support/latexindent/documentation/subsubsec-special.tex -2022/06/12 | 5717 | support/latexindent/documentation/test-default-settings.tex -2022/06/12 | 1486 | support/latexindent/documentation/title.tex -2022/06/12 | 65059 | support/latexindent/LatexIndent/AlignmentAtAmpersand.pm -2022/06/12 | 24410 | support/latexindent/LatexIndent/Arguments.pm -2022/06/12 | 7329 | support/latexindent/LatexIndent/BackUpFileProcedure.pm -2022/06/12 | 4816 | support/latexindent/LatexIndent/BlankLines.pm -2022/06/12 | 12646 | support/latexindent/LatexIndent/Braces.pm -2022/06/12 | 5390 | support/latexindent/LatexIndent/Check.pm -2022/06/12 | 10622 | support/latexindent/LatexIndent/Command.pm -2022/06/12 | 22818 | support/latexindent/LatexIndent/Document.pm -2022/06/12 | 1485 | support/latexindent/LatexIndent/DoubleBackSlash.pm -2022/06/12 | 6023 | support/latexindent/LatexIndent/Else.pm -2022/06/12 | 6808 | support/latexindent/LatexIndent/Environment.pm -2022/06/12 | 9815878 | support/latexindent/latexindent.exe -2022/06/12 | 11300 | support/latexindent/LatexIndent/FileContents.pm -2022/06/12 | 8462 | support/latexindent/LatexIndent/FileExtension.pm -2022/06/12 | 48605 | support/latexindent/LatexIndent/GetYamlSettings.pm -2022/06/12 | 11142 | support/latexindent/LatexIndent/Heading.pm -2022/06/12 | 13420 | support/latexindent/LatexIndent/HiddenChildren.pm -2022/06/12 | 3482 | support/latexindent/LatexIndent/HorizontalWhiteSpace.pm -2022/06/12 | 8829 | support/latexindent/LatexIndent/IfElseFi.pm -2022/06/12 | 21564 | support/latexindent/LatexIndent/Indent.pm -2022/06/12 | 6694 | support/latexindent/LatexIndent/Item.pm -2022/06/12 | 5430 | support/latexindent/LatexIndent/KeyEqualsValuesBraces.pm -2022/06/12 | 9843 | support/latexindent/LatexIndent/Lines.pm -2022/06/12 | 12897 | support/latexindent/LatexIndent/LogFile.pm -2022/06/12 | 2320 | support/latexindent/LatexIndent/Logger.pm -2022/06/12 | 7280 | support/latexindent/LatexIndent/MandatoryArgument.pm -2022/06/12 | 18321 | support/latexindent/LatexIndent/ModifyLineBreaks.pm -2022/06/12 | 1558 | support/latexindent/latexindent-module-installer.pl -2022/06/12 | 4340 | support/latexindent/LatexIndent/NamedGroupingBracesBrackets.pm -2022/06/12 | 6522 | support/latexindent/LatexIndent/OptionalArgument.pm -2022/06/12 | 3410 | support/latexindent/latexindent.pl -2022/06/12 | 2690 | support/latexindent/LatexIndent/Preamble.pm -2022/06/12 | 3747 | support/latexindent/LatexIndent/Replacement.pm -2022/06/12 | 4365 | support/latexindent/LatexIndent/RoundBrackets.pm -2022/06/12 | 20388 | support/latexindent/LatexIndent/Sentence.pm -2022/06/12 | 13890 | support/latexindent/LatexIndent/Special.pm -2022/06/12 | 2701 | support/latexindent/LatexIndent/Switches.pm -2022/06/12 | 3339 | support/latexindent/LatexIndent/Tokens.pm -2022/06/12 | 6964 | support/latexindent/LatexIndent/TrailingComments.pm -2022/06/12 | 5809 | support/latexindent/LatexIndent/UnNamedGroupingBracesBrackets.pm -2022/06/12 | 27328 | support/latexindent/LatexIndent/Verbatim.pm -2022/06/12 | 836 | support/latexindent/LatexIndent/Version.pm -2022/06/12 | 17979 | support/latexindent/LatexIndent/Wrap.pm -2022/06/12 | 1874 | support/latexindent/README -2022/06/13 | 6167406 | support/latexindent.zip +2022/10/30 | 6159922 | support/latexindent/bin/linux/latexindent +2022/10/30 | 6389393 | support/latexindent/bin/macos/latexindent +2022/10/30 | 8700045 | support/latexindent/bin/windows/latexindent.exe +2022/10/30 | 19920 | support/latexindent/defaultSettings.yaml +2022/10/30 | 5206 | support/latexindent/documentation/contributors.bib +2022/10/30 | 7161 | support/latexindent/documentation/figure-schematic.png +2022/10/30 | 4402 | support/latexindent/documentation/latex-indent.bib +2022/10/30 | 1105223 | support/latexindent/documentation/latexindent.pdf +2022/10/30 | 408105 | support/latexindent/documentation/latexindent.tex +2022/10/30 | 54383 | support/latexindent/documentation/latexindent-yaml-schema.json +2022/10/30 | 44096 | support/latexindent/documentation/logo.png +2022/10/30 | 65059 | support/latexindent/LatexIndent/AlignmentAtAmpersand.pm +2022/10/30 | 24410 | support/latexindent/LatexIndent/Arguments.pm +2022/10/30 | 7329 | support/latexindent/LatexIndent/BackUpFileProcedure.pm +2022/10/30 | 4816 | support/latexindent/LatexIndent/BlankLines.pm +2022/10/30 | 12646 | support/latexindent/LatexIndent/Braces.pm +2022/10/30 | 5390 | support/latexindent/LatexIndent/Check.pm +2022/10/30 | 10622 | support/latexindent/LatexIndent/Command.pm +2022/10/30 | 22818 | support/latexindent/LatexIndent/Document.pm +2022/10/30 | 1485 | support/latexindent/LatexIndent/DoubleBackSlash.pm +2022/10/30 | 6023 | support/latexindent/LatexIndent/Else.pm +2022/10/30 | 6808 | support/latexindent/LatexIndent/Environment.pm +2022/10/30 | 11300 | support/latexindent/LatexIndent/FileContents.pm +2022/10/30 | 8462 | support/latexindent/LatexIndent/FileExtension.pm +2022/10/30 | 48856 | support/latexindent/LatexIndent/GetYamlSettings.pm +2022/10/30 | 11142 | support/latexindent/LatexIndent/Heading.pm +2022/10/30 | 13420 | support/latexindent/LatexIndent/HiddenChildren.pm +2022/10/30 | 3482 | support/latexindent/LatexIndent/HorizontalWhiteSpace.pm +2022/10/30 | 8829 | support/latexindent/LatexIndent/IfElseFi.pm +2022/10/30 | 21564 | support/latexindent/LatexIndent/Indent.pm +2022/10/30 | 6694 | support/latexindent/LatexIndent/Item.pm +2022/10/30 | 5430 | support/latexindent/LatexIndent/KeyEqualsValuesBraces.pm +2022/10/30 | 9843 | support/latexindent/LatexIndent/Lines.pm +2022/10/30 | 12897 | support/latexindent/LatexIndent/LogFile.pm +2022/10/30 | 2320 | support/latexindent/LatexIndent/Logger.pm +2022/10/30 | 7280 | support/latexindent/LatexIndent/MandatoryArgument.pm +2022/10/30 | 18321 | support/latexindent/LatexIndent/ModifyLineBreaks.pm +2022/10/30 | 1558 | support/latexindent/latexindent-module-installer.pl +2022/10/30 | 4340 | support/latexindent/LatexIndent/NamedGroupingBracesBrackets.pm +2022/10/30 | 6522 | support/latexindent/LatexIndent/OptionalArgument.pm +2022/10/30 | 3410 | support/latexindent/latexindent.pl +2022/10/30 | 2690 | support/latexindent/LatexIndent/Preamble.pm +2022/10/30 | 3747 | support/latexindent/LatexIndent/Replacement.pm +2022/10/30 | 4365 | support/latexindent/LatexIndent/RoundBrackets.pm +2022/10/30 | 20388 | support/latexindent/LatexIndent/Sentence.pm +2022/10/30 | 13890 | support/latexindent/LatexIndent/Special.pm +2022/10/30 | 2701 | support/latexindent/LatexIndent/Switches.pm +2022/10/30 | 3339 | support/latexindent/LatexIndent/Tokens.pm +2022/10/30 | 6964 | support/latexindent/LatexIndent/TrailingComments.pm +2022/10/30 | 5809 | support/latexindent/LatexIndent/UnNamedGroupingBracesBrackets.pm +2022/10/30 | 27328 | support/latexindent/LatexIndent/Verbatim.pm +2022/10/30 | 836 | support/latexindent/LatexIndent/Version.pm +2022/10/30 | 17979 | support/latexindent/LatexIndent/Wrap.pm +2022/10/30 | 2006 | support/latexindent/README +2022/10/30 | 11009879 | support/latexindent.zip 2021/10/26 | 16439 | support/latex-make/figlatex.dtx 2021/10/26 | 238535 | support/latex-make/figlatex.pdf 2001/06/07 | 302 | support/latexmake/latexmake.diz @@ -276145,21 +276133,19 @@ 1995/07/07 | 217081 | support/lxmail/lxmail10.exe 1995/07/07 | 987 | support/lxmail/lxmail10.txt 2007/12/25 | 217923 | support/lxmail.zip -2019/05/27 | 130 | support/lyluatex/Contributors.md -2019/05/27 | 58 | support/lyluatex/latexmkrc -2019/05/27 | 1090 | support/lyluatex/LICENSE -2019/05/27 | 158 | support/lyluatex/ly/eight-systems.ly -2019/05/27 | 320 | support/lyluatex/ly/fonts.ly -2019/05/27 | 1101 | support/lyluatex/lyluatexbase.cls -2019/05/27 | 4277 | support/lyluatex/lyluatex-lib.lua -2019/05/27 | 44110 | support/lyluatex/lyluatex.lua -2019/05/27 | 973 | support/lyluatex/lyluatexmanual.cls -2019/05/27 | 8659 | support/lyluatex/lyluatex-options.lua -2019/05/27 | 1664216 | support/lyluatex/lyluatex.pdf -2019/05/27 | 10502 | support/lyluatex/lyluatex.sty -2019/05/27 | 96489 | support/lyluatex/lyluatex.tex -2019/05/27 | 2868 | support/lyluatex/README.md -2019/05/28 | 1334865 | support/lyluatex.zip +2022/10/30 | 325 | support/lyluatex/Contributors.md +2022/10/30 | 58 | support/lyluatex/latexmkrc +2022/10/30 | 1090 | support/lyluatex/LICENSE +2022/10/30 | 158 | support/lyluatex/ly/eight-systems.ly +2022/10/30 | 320 | support/lyluatex/ly/fonts.ly +2022/10/30 | 1105 | support/lyluatex/lyluatexbase.cls +2022/10/30 | 44673 | support/lyluatex/lyluatex.lua +2022/10/30 | 983 | support/lyluatex/lyluatexmanual.cls +2022/10/30 | 2028732 | support/lyluatex/lyluatex.pdf +2022/10/30 | 10254 | support/lyluatex/lyluatex.sty +2022/10/30 | 97205 | support/lyluatex/lyluatex.tex +2022/10/30 | 2960 | support/lyluatex/README.md +2022/10/30 | 1657005 | support/lyluatex.zip 2022/03/22 | 36066 | support/make4ht/changelog.tex 2022/03/22 | 4641 | support/make4ht/domfilters/make4ht-aeneas.lua 2022/03/22 | 2741 | support/make4ht/domfilters/make4ht-booktabs.lua @@ -282578,8 +282564,8 @@ 2019/02/28 | 7996 | systems/texlive/tlnet/archive/abstyles.r15878.tar.xz 2022/03/12 | 103532 | systems/texlive/tlnet/archive/academicons.doc.r62622.tar.xz 2022/03/12 | 35252 | systems/texlive/tlnet/archive/academicons.r62622.tar.xz -2019/02/28 | 300384 | systems/texlive/tlnet/archive/accanthis.doc.r32089.tar.xz -2019/02/28 | 368064 | systems/texlive/tlnet/archive/accanthis.r32089.tar.xz +2022/10/30 | 300388 | systems/texlive/tlnet/archive/accanthis.doc.r64844.tar.xz +2022/10/30 | 368064 | systems/texlive/tlnet/archive/accanthis.r64844.tar.xz 2019/06/28 | 239048 | systems/texlive/tlnet/archive/accents.doc.r51497.tar.xz 2019/06/28 | 2956 | systems/texlive/tlnet/archive/accents.r51497.tar.xz 2020/07/08 | 496876 | systems/texlive/tlnet/archive/accessibility.doc.r55777.tar.xz @@ -283062,8 +283048,8 @@ 2019/02/28 | 1924 | systems/texlive/tlnet/archive/assignment.r20431.tar.xz 2019/02/28 | 353364 | systems/texlive/tlnet/archive/assoccnt.doc.r38497.tar.xz 2019/02/28 | 4036 | systems/texlive/tlnet/archive/assoccnt.r38497.tar.xz -2022/01/24 | 251112 | systems/texlive/tlnet/archive/association-matrix.doc.r61719.tar.xz -2022/01/24 | 3604 | systems/texlive/tlnet/archive/association-matrix.r61719.tar.xz +2022/10/30 | 268584 | systems/texlive/tlnet/archive/association-matrix.doc.r64845.tar.xz +2022/10/30 | 4188 | systems/texlive/tlnet/archive/association-matrix.r64845.tar.xz 2022/07/09 | 117844 | systems/texlive/tlnet/archive/asternote.doc.r63838.tar.xz 2022/07/09 | 1400 | systems/texlive/tlnet/archive/asternote.r63838.tar.xz 2019/02/28 | 4220 | systems/texlive/tlnet/archive/astro.doc.r15878.tar.xz @@ -284834,7 +284820,7 @@ 2022/06/10 | 700 | systems/texlive/tlnet/archive/collection-latex.r63515.tar.xz 2022/06/12 | 736 | systems/texlive/tlnet/archive/collection-latexrecommended.r63547.tar.xz 2022/09/15 | 920 | systems/texlive/tlnet/archive/collection-luatex.r64393.tar.xz -2022/10/21 | 1632 | systems/texlive/tlnet/archive/collection-mathscience.r64763.tar.xz +2022/10/30 | 1636 | systems/texlive/tlnet/archive/collection-mathscience.r64853.tar.xz 2021/06/10 | 548 | systems/texlive/tlnet/archive/collection-metapost.r59531.tar.xz 2021/02/24 | 476 | systems/texlive/tlnet/archive/collection-music.r57878.tar.xz 2022/10/12 | 1552 | systems/texlive/tlnet/archive/collection-pictures.r64681.tar.xz @@ -285622,9 +285608,9 @@ 2019/02/28 | 13996 | systems/texlive/tlnet/archive/dcpic.r30206.tar.xz 2019/09/02 | 284556 | systems/texlive/tlnet/archive/ddphonism.doc.r52009.tar.xz 2019/09/02 | 3000 | systems/texlive/tlnet/archive/ddphonism.r52009.tar.xz -2022/10/05 | 326644 | systems/texlive/tlnet/archive/debate.doc.r64602.tar.xz -2022/10/05 | 1680 | systems/texlive/tlnet/archive/debate.r64602.tar.xz -2022/10/05 | 3044 | systems/texlive/tlnet/archive/debate.source.r64602.tar.xz +2022/10/30 | 285712 | systems/texlive/tlnet/archive/debate.doc.r64846.tar.xz +2022/10/30 | 1688 | systems/texlive/tlnet/archive/debate.r64846.tar.xz +2022/10/30 | 3084 | systems/texlive/tlnet/archive/debate.source.r64846.tar.xz 2019/02/28 | 155764 | systems/texlive/tlnet/archive/decimal.doc.r23374.tar.xz 2019/02/28 | 1420 | systems/texlive/tlnet/archive/decimal.r23374.tar.xz 2019/02/28 | 6576 | systems/texlive/tlnet/archive/decimal.source.r23374.tar.xz @@ -286466,9 +286452,9 @@ 2022/02/08 | 341332 | systems/texlive/tlnet/archive/envlab.doc.r61937.tar.xz 2022/02/08 | 5492 | systems/texlive/tlnet/archive/envlab.r61937.tar.xz 2022/02/08 | 14628 | systems/texlive/tlnet/archive/envlab.source.r61937.tar.xz -2022/10/28 | 875488 | systems/texlive/tlnet/archive/eolang.doc.r64834.tar.xz -2022/10/28 | 3900 | systems/texlive/tlnet/archive/eolang.r64834.tar.xz -2022/10/28 | 8008 | systems/texlive/tlnet/archive/eolang.source.r64834.tar.xz +2022/10/30 | 880404 | systems/texlive/tlnet/archive/eolang.doc.r64847.tar.xz +2022/10/30 | 3996 | systems/texlive/tlnet/archive/eolang.r64847.tar.xz +2022/10/30 | 8372 | systems/texlive/tlnet/archive/eolang.source.r64847.tar.xz 2019/02/28 | 266312 | systems/texlive/tlnet/archive/epigrafica.doc.r17210.tar.xz 2019/02/28 | 343668 | systems/texlive/tlnet/archive/epigrafica.r17210.tar.xz 2019/02/28 | 852 | systems/texlive/tlnet/archive/epigram.r20513.tar.xz @@ -287503,8 +287489,8 @@ 2020/02/18 | 1833412 | systems/texlive/tlnet/archive/ghsystem.r53822.tar.xz 2019/02/28 | 196160 | systems/texlive/tlnet/archive/gillcm.doc.r19878.tar.xz 2019/02/28 | 13792 | systems/texlive/tlnet/archive/gillcm.r19878.tar.xz -2019/02/28 | 216008 | systems/texlive/tlnet/archive/gillius.doc.r32068.tar.xz -2019/02/28 | 941896 | systems/texlive/tlnet/archive/gillius.r32068.tar.xz +2022/10/30 | 216008 | systems/texlive/tlnet/archive/gillius.doc.r64859.tar.xz +2022/10/30 | 941916 | systems/texlive/tlnet/archive/gillius.r64859.tar.xz 2020/09/08 | 168440 | systems/texlive/tlnet/archive/gincltex.doc.r56291.tar.xz 2020/09/08 | 1908 | systems/texlive/tlnet/archive/gincltex.r56291.tar.xz 2020/09/08 | 5132 | systems/texlive/tlnet/archive/gincltex.source.r56291.tar.xz @@ -287931,6 +287917,9 @@ 2019/02/28 | 83952 | systems/texlive/tlnet/archive/hepparticles.doc.r35723.tar.xz 2019/02/28 | 4448 | systems/texlive/tlnet/archive/hepparticles.r35723.tar.xz 2019/02/28 | 2124 | systems/texlive/tlnet/archive/hep.r15878.tar.xz +2022/10/30 | 461932 | systems/texlive/tlnet/archive/hep-reference.doc.r64853.tar.xz +2022/10/30 | 1920 | systems/texlive/tlnet/archive/hep-reference.r64853.tar.xz +2022/10/30 | 4468 | systems/texlive/tlnet/archive/hep-reference.source.r64853.tar.xz 2021/11/28 | 494980 | systems/texlive/tlnet/archive/hep-text.doc.r61172.tar.xz 2021/11/28 | 1632 | systems/texlive/tlnet/archive/hep-text.r61172.tar.xz 2021/11/28 | 4228 | systems/texlive/tlnet/archive/hep-text.source.r61172.tar.xz @@ -288050,9 +288039,9 @@ 2019/02/28 | 98316 | systems/texlive/tlnet/archive/hrlatex.doc.r18020.tar.xz 2019/02/28 | 3528 | systems/texlive/tlnet/archive/hrlatex.r18020.tar.xz 2019/02/28 | 3768 | systems/texlive/tlnet/archive/hrlatex.source.r18020.tar.xz -2022/10/16 | 409768 | systems/texlive/tlnet/archive/huawei.doc.r64718.tar.xz -2022/10/16 | 6412 | systems/texlive/tlnet/archive/huawei.r64718.tar.xz -2022/10/16 | 9596 | systems/texlive/tlnet/archive/huawei.source.r64718.tar.xz +2022/10/30 | 777364 | systems/texlive/tlnet/archive/huawei.doc.r64848.tar.xz +2022/10/30 | 260132 | systems/texlive/tlnet/archive/huawei.r64848.tar.xz +2022/10/30 | 9860 | systems/texlive/tlnet/archive/huawei.source.r64848.tar.xz 2022/10/17 | 328068 | systems/texlive/tlnet/archive/huaz.doc.r64723.tar.xz 2022/10/17 | 4692 | systems/texlive/tlnet/archive/huaz.r64723.tar.xz 2021/02/01 | 213632 | systems/texlive/tlnet/archive/hu-berlin-bundle.doc.r57580.tar.xz @@ -288231,9 +288220,9 @@ 2022/04/06 | 17644 | systems/texlive/tlnet/archive/ieejtran.r62957.tar.xz 2019/02/28 | 3464 | systems/texlive/tlnet/archive/ietfbibs.doc.r41332.tar.xz 2019/02/28 | 456 | systems/texlive/tlnet/archive/ietfbibs.r41332.tar.xz -2022/10/26 | 325748 | systems/texlive/tlnet/archive/iexec.doc.r64810.tar.xz -2022/10/26 | 2412 | systems/texlive/tlnet/archive/iexec.r64810.tar.xz -2022/10/26 | 5548 | systems/texlive/tlnet/archive/iexec.source.r64810.tar.xz +2022/10/30 | 325444 | systems/texlive/tlnet/archive/iexec.doc.r64849.tar.xz +2022/10/30 | 2416 | systems/texlive/tlnet/archive/iexec.r64849.tar.xz +2022/10/30 | 5612 | systems/texlive/tlnet/archive/iexec.source.r64849.tar.xz 2021/07/24 | 175068 | systems/texlive/tlnet/archive/ifallfalse.doc.r60027.tar.xz 2021/07/24 | 1248 | systems/texlive/tlnet/archive/ifallfalse.r60027.tar.xz 2021/07/24 | 3084 | systems/texlive/tlnet/archive/ifallfalse.source.r60027.tar.xz @@ -288476,8 +288465,8 @@ 2022/08/08 | 237760 | systems/texlive/tlnet/archive/japanese-otf.r64072.tar.xz 2022/08/08 | 67336 | systems/texlive/tlnet/archive/japanese-otf.source.r64072.tar.xz 2019/11/12 | 9792 | systems/texlive/tlnet/archive/jbact.r52717.tar.xz -2022/10/28 | 5509864 | systems/texlive/tlnet/archive/jeuxcartes.doc.r64827.tar.xz -2022/10/28 | 5328884 | systems/texlive/tlnet/archive/jeuxcartes.r64827.tar.xz +2022/10/30 | 6404764 | systems/texlive/tlnet/archive/jeuxcartes.doc.r64850.tar.xz +2022/10/30 | 5642836 | systems/texlive/tlnet/archive/jeuxcartes.r64850.tar.xz 2019/02/28 | 340 | systems/texlive/tlnet/archive/jfmutil.aarch64-linux.r46228.tar.xz 2019/02/28 | 340 | systems/texlive/tlnet/archive/jfmutil.amd64-freebsd.r44835.tar.xz 2019/02/28 | 340 | systems/texlive/tlnet/archive/jfmutil.amd64-netbsd.r44835.tar.xz @@ -289347,8 +289336,8 @@ 2019/02/28 | 5428 | systems/texlive/tlnet/archive/ling-macros.r42268.tar.xz 2019/02/28 | 274676 | systems/texlive/tlnet/archive/linguex.doc.r30815.tar.xz 2019/02/28 | 6924 | systems/texlive/tlnet/archive/linguex.r30815.tar.xz -2020/03/24 | 42252 | systems/texlive/tlnet/archive/linguisticspro.doc.r54512.tar.xz -2020/03/24 | 1395864 | systems/texlive/tlnet/archive/linguisticspro.r54512.tar.xz +2022/10/30 | 46052 | systems/texlive/tlnet/archive/linguisticspro.doc.r64858.tar.xz +2022/10/30 | 1377940 | systems/texlive/tlnet/archive/linguisticspro.r64858.tar.xz 2019/02/28 | 226748 | systems/texlive/tlnet/archive/linop.doc.r41304.tar.xz 2019/02/28 | 1376 | systems/texlive/tlnet/archive/linop.r41304.tar.xz 2020/06/05 | 1464640 | systems/texlive/tlnet/archive/lion-msc.doc.r55415.tar.xz @@ -291512,9 +291501,9 @@ 2019/02/28 | 352 | systems/texlive/tlnet/archive/pdflatexpicscale.x86_64-linuxmusl.r46840.tar.xz 2019/02/28 | 348 | systems/texlive/tlnet/archive/pdflatexpicscale.x86_64-linux.r41779.tar.xz 2019/02/28 | 348 | systems/texlive/tlnet/archive/pdflatexpicscale.x86_64-solaris.r41779.tar.xz -2019/12/07 | 298264 | systems/texlive/tlnet/archive/pdflscape.doc.r53047.tar.xz -2019/12/07 | 2252 | systems/texlive/tlnet/archive/pdflscape.r53047.tar.xz -2019/12/07 | 6000 | systems/texlive/tlnet/archive/pdflscape.source.r53047.tar.xz +2022/10/30 | 314616 | systems/texlive/tlnet/archive/pdflscape.doc.r64851.tar.xz +2022/10/30 | 2612 | systems/texlive/tlnet/archive/pdflscape.r64851.tar.xz +2022/10/30 | 6508 | systems/texlive/tlnet/archive/pdflscape.source.r64851.tar.xz 2022/09/27 | 8723252 | systems/texlive/tlnet/archive/pdfmanagement-testphase.doc.r64521.tar.xz 2022/09/27 | 76696 | systems/texlive/tlnet/archive/pdfmanagement-testphase.r64521.tar.xz 2022/09/27 | 137740 | systems/texlive/tlnet/archive/pdfmanagement-testphase.source.r64521.tar.xz @@ -291950,8 +291939,8 @@ 2022/08/08 | 137636 | systems/texlive/tlnet/archive/plautopatch.doc.r64072.tar.xz 2022/08/08 | 7076 | systems/texlive/tlnet/archive/plautopatch.r64072.tar.xz 2019/02/28 | 552 | systems/texlive/tlnet/archive/play.doc.r15878.tar.xz -2020/08/01 | 251112 | systems/texlive/tlnet/archive/playfair.doc.r56005.tar.xz -2020/08/01 | 1679544 | systems/texlive/tlnet/archive/playfair.r56005.tar.xz +2022/10/30 | 251116 | systems/texlive/tlnet/archive/playfair.doc.r64857.tar.xz +2022/10/30 | 1679528 | systems/texlive/tlnet/archive/playfair.r64857.tar.xz 2019/02/28 | 2196 | systems/texlive/tlnet/archive/play.r15878.tar.xz 2019/02/28 | 4972 | systems/texlive/tlnet/archive/play.source.r15878.tar.xz 2021/03/23 | 25344 | systems/texlive/tlnet/archive/pl.doc.r58661.tar.xz @@ -292028,8 +292017,8 @@ 2019/02/28 | 292288 | systems/texlive/tlnet/archive/poetrytex.doc.r39921.tar.xz 2019/02/28 | 3096 | systems/texlive/tlnet/archive/poetrytex.r39921.tar.xz 2019/02/28 | 13964 | systems/texlive/tlnet/archive/poetrytex.source.r39921.tar.xz -2022/09/28 | 12968 | systems/texlive/tlnet/archive/poiretone.doc.r64527.tar.xz -2022/09/28 | 172692 | systems/texlive/tlnet/archive/poiretone.r64527.tar.xz +2022/10/30 | 12964 | systems/texlive/tlnet/archive/poiretone.doc.r64856.tar.xz +2022/10/30 | 172672 | systems/texlive/tlnet/archive/poiretone.r64856.tar.xz 2022/05/20 | 123176 | systems/texlive/tlnet/archive/polexpr.doc.r63337.tar.xz 2022/05/20 | 39920 | systems/texlive/tlnet/archive/polexpr.r63337.tar.xz 2021/08/26 | 284808 | systems/texlive/tlnet/archive/polski.doc.r60322.tar.xz @@ -293315,8 +293304,8 @@ 2019/02/28 | 292656 | systems/texlive/tlnet/archive/simplecv.doc.r35537.tar.xz 2019/02/28 | 2112 | systems/texlive/tlnet/archive/simplecv.r35537.tar.xz 2019/02/28 | 5844 | systems/texlive/tlnet/archive/simplecv.source.r35537.tar.xz -2022/10/22 | 1979080 | systems/texlive/tlnet/archive/simpleicons.doc.r64769.tar.xz -2022/10/22 | 2698076 | systems/texlive/tlnet/archive/simpleicons.r64769.tar.xz +2022/10/30 | 1982104 | systems/texlive/tlnet/archive/simpleicons.doc.r64855.tar.xz +2022/10/30 | 2700300 | systems/texlive/tlnet/archive/simpleicons.r64855.tar.xz 2019/02/28 | 224844 | systems/texlive/tlnet/archive/simpleinvoice.doc.r45673.tar.xz 2019/02/28 | 2420 | systems/texlive/tlnet/archive/simpleinvoice.r45673.tar.xz 2022/10/03 | 130940 | systems/texlive/tlnet/archive/simplekv.doc.r64578.tar.xz @@ -294260,7 +294249,7 @@ 2022/09/13 | 600 | systems/texlive/tlnet/archive/texlive-scripts.amd64-freebsd.r64356.tar.xz 2022/09/13 | 596 | systems/texlive/tlnet/archive/texlive-scripts.amd64-netbsd.r64356.tar.xz 2022/09/13 | 596 | systems/texlive/tlnet/archive/texlive-scripts.armhf-linux.r64356.tar.xz -2022/10/28 | 422980 | systems/texlive/tlnet/archive/texlive-scripts.doc.r64830.tar.xz +2022/10/30 | 422980 | systems/texlive/tlnet/archive/texlive-scripts.doc.r64843.tar.xz 2020/01/27 | 916 | systems/texlive/tlnet/archive/texlive-scripts-extra.aarch64-linux.r53577.tar.xz 2020/01/27 | 924 | systems/texlive/tlnet/archive/texlive-scripts-extra.amd64-freebsd.r53577.tar.xz 2020/01/27 | 916 | systems/texlive/tlnet/archive/texlive-scripts-extra.amd64-netbsd.r53577.tar.xz @@ -294284,7 +294273,7 @@ 2022/09/13 | 592 | systems/texlive/tlnet/archive/texlive-scripts.i386-linux.r64356.tar.xz 2022/09/13 | 596 | systems/texlive/tlnet/archive/texlive-scripts.i386-netbsd.r64356.tar.xz 2022/09/13 | 596 | systems/texlive/tlnet/archive/texlive-scripts.i386-solaris.r64356.tar.xz -2022/10/28 | 113728 | systems/texlive/tlnet/archive/texlive-scripts.r64830.tar.xz +2022/10/30 | 113684 | systems/texlive/tlnet/archive/texlive-scripts.r64843.tar.xz 2022/09/13 | 580 | systems/texlive/tlnet/archive/texlive-scripts.universal-darwin.r64356.tar.xz 2022/04/19 | 36296 | systems/texlive/tlnet/archive/texlive-scripts.win32.r63068.tar.xz 2022/09/13 | 596 | systems/texlive/tlnet/archive/texlive-scripts.x86_64-cygwin.r64356.tar.xz @@ -294952,11 +294941,11 @@ 2019/02/28 | 404 | systems/texlive/tlnet/archive/translation-tabbing-fr.r24228.tar.xz 2021/06/01 | 216032 | systems/texlive/tlnet/archive/translator.doc.r59412.tar.xz 2021/06/01 | 28304 | systems/texlive/tlnet/archive/translator.r59412.tar.xz -2019/12/01 | 266624 | systems/texlive/tlnet/archive/transparent.doc.r52981.tar.xz +2022/10/30 | 275336 | systems/texlive/tlnet/archive/transparent.doc.r64852.tar.xz 2022/08/14 | 76976 | systems/texlive/tlnet/archive/transparent-io.doc.r64113.tar.xz 2022/08/14 | 852 | systems/texlive/tlnet/archive/transparent-io.r64113.tar.xz -2019/12/01 | 1992 | systems/texlive/tlnet/archive/transparent.r52981.tar.xz -2019/12/01 | 5448 | systems/texlive/tlnet/archive/transparent.source.r52981.tar.xz +2022/10/30 | 2272 | systems/texlive/tlnet/archive/transparent.r64852.tar.xz +2022/10/30 | 5284 | systems/texlive/tlnet/archive/transparent.source.r64852.tar.xz 2019/02/28 | 92268 | systems/texlive/tlnet/archive/tree-dvips.doc.r21751.tar.xz 2019/02/28 | 7964 | systems/texlive/tlnet/archive/tree-dvips.r21751.tar.xz 2019/02/28 | 23484 | systems/texlive/tlnet/archive/treetex.doc.r28176.tar.xz @@ -295027,8 +295016,8 @@ 2019/02/28 | 7888 | systems/texlive/tlnet/archive/turnstile.source.r15878.tar.xz 2019/02/28 | 78428 | systems/texlive/tlnet/archive/turnthepage.doc.r29803.tar.xz 2019/02/28 | 1664 | systems/texlive/tlnet/archive/turnthepage.r29803.tar.xz -2021/07/18 | 708 | systems/texlive/tlnet/archive/twemoji-colr.doc.r59957.tar.xz -2021/07/18 | 564740 | systems/texlive/tlnet/archive/twemoji-colr.r59957.tar.xz +2022/10/30 | 712 | systems/texlive/tlnet/archive/twemoji-colr.doc.r64854.tar.xz +2022/10/30 | 581228 | systems/texlive/tlnet/archive/twemoji-colr.r64854.tar.xz 2022/04/06 | 4751536 | systems/texlive/tlnet/archive/twemojis.doc.r62930.tar.xz 2022/04/06 | 4425040 | systems/texlive/tlnet/archive/twemojis.r62930.tar.xz 2022/04/06 | 70504 | systems/texlive/tlnet/archive/twemojis.source.r62930.tar.xz @@ -296131,16 +296120,16 @@ 2020/07/18 | 47816 | systems/texlive/tlnet/archive/zztex.doc.r55862.tar.xz 2020/07/18 | 101724 | systems/texlive/tlnet/archive/zztex.r55862.tar.xz 2022/07/17 | 124404 | systems/texlive/tlnet/install-tl -2022/10/29 | 5834398 | systems/texlive/tlnet/install-tl-unx.tar.gz -2022/10/29 | 152 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512 -2022/10/29 | 455 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512.asc +2022/10/30 | 5834574 | systems/texlive/tlnet/install-tl-unx.tar.gz +2022/10/30 | 152 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512 +2022/10/30 | 455 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512.asc 2021/04/11 | 4945 | systems/texlive/tlnet/install-tl-windows.bat -2022/10/29 | 20435279 | systems/texlive/tlnet/install-tl-windows.exe -2022/10/29 | 153 | systems/texlive/tlnet/install-tl-windows.exe.sha512 -2022/10/29 | 455 | systems/texlive/tlnet/install-tl-windows.exe.sha512.asc -2022/10/29 | 25518566 | systems/texlive/tlnet/install-tl.zip -2022/10/29 | 145 | systems/texlive/tlnet/install-tl.zip.sha512 -2022/10/29 | 455 | systems/texlive/tlnet/install-tl.zip.sha512.asc +2022/10/30 | 20434885 | systems/texlive/tlnet/install-tl-windows.exe +2022/10/30 | 153 | systems/texlive/tlnet/install-tl-windows.exe.sha512 +2022/10/30 | 455 | systems/texlive/tlnet/install-tl-windows.exe.sha512.asc +2022/10/30 | 25518528 | systems/texlive/tlnet/install-tl.zip +2022/10/30 | 145 | systems/texlive/tlnet/install-tl.zip.sha512 +2022/10/30 | 455 | systems/texlive/tlnet/install-tl.zip.sha512.asc 2022/04/03 | 1229 | systems/texlive/tlnet/README.md 2022/04/03 | 0 | systems/texlive/tlnet/TEXLIVE_2022 2022/02/28 | 7791 | systems/texlive/tlnet/tlpkg/gpg/pubring.gpg @@ -296150,7 +296139,7 @@ 2022/02/28 | 1280 | systems/texlive/tlnet/tlpkg/gpg/trustdb.gpg 2022/10/09 | 49938 | systems/texlive/tlnet/tlpkg/installer/config.guess 2010/11/11 | 11651 | systems/texlive/tlnet/tlpkg/installer/COPYING.MinGW-runtime.txt -2022/10/27 | 7528 | systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl +2022/10/29 | 7362 | systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl 2022/10/13 | 225403 | systems/texlive/tlnet/tlpkg/installer/curl/curl-ca-bundle.crt 2020/04/15 | 2606592 | systems/texlive/tlnet/tlpkg/installer/curl/curl.exe 2017/04/16 | 2629 | systems/texlive/tlnet/tlpkg/installer/installer-options.txt @@ -296193,12 +296182,12 @@ 2021/05/16 | 20371 | systems/texlive/tlnet/tlpkg/TeXLive/TLCrypto.pm 2021/12/21 | 5429 | systems/texlive/tlnet/tlpkg/TeXLive/TLDownload.pm 2021/12/21 | 27582 | systems/texlive/tlnet/tlpkg/TeXLive/TLPaper.pm -2022/10/29 | 17795535 | systems/texlive/tlnet/tlpkg/texlive.tlpdb -2022/10/29 | 48 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 +2022/10/30 | 17800554 | systems/texlive/tlnet/tlpkg/texlive.tlpdb +2022/10/30 | 48 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 2022/04/18 | 86658 | systems/texlive/tlnet/tlpkg/TeXLive/TLPDB.pm -2022/10/29 | 144 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 -2022/10/29 | 455 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc -2022/10/29 | 2422448 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz +2022/10/30 | 144 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 +2022/10/30 | 455 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc +2022/10/30 | 2423428 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz 2022/09/14 | 58922 | systems/texlive/tlnet/tlpkg/TeXLive/TLPOBJ.pm 2022/10/04 | 42404 | systems/texlive/tlnet/tlpkg/TeXLive/TLPSRC.pm 2021/12/21 | 16130 | systems/texlive/tlnet/tlpkg/TeXLive/TLTREE.pm @@ -301595,7 +301584,7 @@ 2020/10/03 | 318630 | systems/win32/miktex/tm/packages/filehook.tar.lzma 2012/12/04 | 924573 | systems/win32/miktex/tm/packages/fileinfo.tar.lzma 2011/09/21 | 281409 | systems/win32/miktex/tm/packages/filemod.tar.lzma -2022/10/29 | 668296 | systems/win32/miktex/tm/packages/files.csv.lzma +2022/10/30 | 668296 | systems/win32/miktex/tm/packages/files.csv.lzma 2001/05/14 | 5617 | systems/win32/miktex/tm/packages/finbib.tar.lzma 2015/10/20 | 44379 | systems/win32/miktex/tm/packages/findhyph.tar.lzma 2011/10/21 | 89323 | systems/win32/miktex/tm/packages/fink.tar.lzma @@ -303327,9 +303316,9 @@ 2018/01/12 | 157226 | systems/win32/miktex/tm/packages/miktex-zip-bin-x64.tar.lzma 2022/07/26 | 39695 | systems/win32/miktex/tm/packages/miktex-zlib-bin-2.9.tar.lzma 2022/10/15 | 43540 | systems/win32/miktex/tm/packages/miktex-zlib-bin-x64-2.9.tar.lzma -2022/10/29 | 299974 | systems/win32/miktex/tm/packages/miktex-zzdb1-2.9.tar.lzma -2022/10/29 | 1507333 | systems/win32/miktex/tm/packages/miktex-zzdb2-2.9.tar.lzma -2022/10/29 | 1384033 | systems/win32/miktex/tm/packages/miktex-zzdb3-2.9.tar.lzma +2022/10/30 | 299956 | systems/win32/miktex/tm/packages/miktex-zzdb1-2.9.tar.lzma +2022/10/30 | 1507162 | systems/win32/miktex/tm/packages/miktex-zzdb2-2.9.tar.lzma +2022/10/30 | 1386224 | systems/win32/miktex/tm/packages/miktex-zzdb3-2.9.tar.lzma 2022/07/26 | 13519 | systems/win32/miktex/tm/packages/miktex-zzip-bin-2.9.tar.lzma 2022/10/15 | 14426 | systems/win32/miktex/tm/packages/miktex-zzip-bin-x64-2.9.tar.lzma 2016/07/15 | 35914 | systems/win32/miktex/tm/packages/mil3.tar.lzma @@ -303578,102 +303567,102 @@ 2018/04/09 | 400132 | systems/win32/miktex/tm/packages/newunicodechar.tar.lzma 2011/09/19 | 101312 | systems/win32/miktex/tm/packages/newvbtm.tar.lzma 2021/03/17 | 232249 | systems/win32/miktex/tm/packages/newverbs.tar.lzma -2022/10/29 | 667232 | systems/win32/miktex/tm/packages/next/files.csv.lzma -2022/10/29 | 57317 | systems/win32/miktex/tm/packages/next/miktex-arctrl-bin-x64-2.9.tar.lzma -2022/10/29 | 1161751 | systems/win32/miktex/tm/packages/next/miktex-asymptote-bin-x64-2.9.tar.lzma -2022/10/29 | 31588 | systems/win32/miktex/tm/packages/next/miktex-autosp-bin-x64-2.9.tar.lzma -2022/10/29 | 35265 | systems/win32/miktex/tm/packages/next/miktex-axohelp-bin-x64-2.9.tar.lzma -2022/10/29 | 65130 | systems/win32/miktex/tm/packages/next/miktex-bibarts-bin-x64-2.9.tar.lzma -2022/10/29 | 95468 | systems/win32/miktex/tm/packages/next/miktex-bibtex8bit-bin-x64-2.9.tar.lzma -2022/10/29 | 77212 | systems/win32/miktex/tm/packages/next/miktex-bibtex-bin-x64-2.9.tar.lzma -2022/10/29 | 31562 | systems/win32/miktex/tm/packages/next/miktex-bzip2-bin-x64-2.9.tar.lzma -2022/10/29 | 394144 | systems/win32/miktex/tm/packages/next/miktex-cairo-bin-x64-2.9.tar.lzma -2022/10/29 | 37051 | systems/win32/miktex/tm/packages/next/miktex-chktex-bin-x64-2.9.tar.lzma -2022/10/29 | 57506 | systems/win32/miktex/tm/packages/next/miktex-cjkutils-bin-x64-2.9.tar.lzma -2022/10/29 | 270466 | systems/win32/miktex/tm/packages/next/miktex-console-bin-x64-2.9.tar.lzma -2022/10/29 | 196213 | systems/win32/miktex/tm/packages/next/miktex-curl-bin-x64-2.9.tar.lzma -2022/10/29 | 103246 | systems/win32/miktex/tm/packages/next/miktex-cweb-bin-x64-2.9.tar.lzma -2022/10/29 | 24212 | systems/win32/miktex/tm/packages/next/miktex-devnag-bin-x64-2.9.tar.lzma -2022/10/29 | 481894 | systems/win32/miktex/tm/packages/next/miktex-doc.tar.lzma -2022/10/29 | 52037 | systems/win32/miktex/tm/packages/next/miktex-dvicopy-bin-x64-2.9.tar.lzma -2022/10/29 | 325981 | systems/win32/miktex/tm/packages/next/miktex-dvipdfmx-bin-x64-2.9.tar.lzma -2022/10/29 | 45796 | systems/win32/miktex/tm/packages/next/miktex-dvipng-bin-x64-2.9.tar.lzma -2022/10/29 | 135465 | systems/win32/miktex/tm/packages/next/miktex-dvips-bin-x64-2.9.tar.lzma -2022/10/29 | 1458151 | systems/win32/miktex/tm/packages/next/miktex-dvisvgm-bin-x64-2.9.tar.lzma -2022/10/29 | 112979 | systems/win32/miktex/tm/packages/next/miktex-epstopdf-bin-x64-2.9.tar.lzma -2022/10/29 | 48852 | systems/win32/miktex/tm/packages/next/miktex-expat-bin-x64-2.9.tar.lzma -2022/10/29 | 28510 | systems/win32/miktex/tm/packages/next/miktex-findtexmf-bin-x64-2.9.tar.lzma -2022/10/29 | 63241 | systems/win32/miktex/tm/packages/next/miktex-fmt-bin-x64-2.9.tar.lzma -2022/10/29 | 155431 | systems/win32/miktex/tm/packages/next/miktex-fontconfig-bin-x64-2.9.tar.lzma -2022/10/29 | 79064 | systems/win32/miktex/tm/packages/next/miktex-fonts-bin-x64-2.9.tar.lzma -2022/10/29 | 81448 | systems/win32/miktex/tm/packages/next/miktex-freeglut-bin-x64-2.9.tar.lzma -2022/10/29 | 295946 | systems/win32/miktex/tm/packages/next/miktex-freetype2-bin-x64-2.9.tar.lzma -2022/10/29 | 25119 | systems/win32/miktex/tm/packages/next/miktex-fribidixetex-bin-x64-2.9.tar.lzma -2022/10/29 | 112879 | systems/win32/miktex/tm/packages/next/miktex-gd-bin-x64-2.9.tar.lzma -2022/10/29 | 73264 | systems/win32/miktex/tm/packages/next/miktex-graphite2-bin-x64-2.9.tar.lzma -2022/10/29 | 115581 | systems/win32/miktex/tm/packages/next/miktex-gregorio-bin-x64-2.9.tar.lzma -2022/10/29 | 43890 | systems/win32/miktex/tm/packages/next/miktex-gsf2pk-bin-x64-2.9.tar.lzma -2022/10/29 | 565082 | systems/win32/miktex/tm/packages/next/miktex-harfbuzz-bin-x64-2.9.tar.lzma -2022/10/29 | 247207 | systems/win32/miktex/tm/packages/next/miktex-hitex-bin-x64.tar.lzma -2022/10/29 | 169679 | systems/win32/miktex/tm/packages/next/miktex-hunspell-bin-x64-2.9.tar.lzma -2022/10/29 | 109650 | systems/win32/miktex/tm/packages/next/miktex-jpeg-bin-x64-2.9.tar.lzma -2022/10/29 | 18382 | systems/win32/miktex/tm/packages/next/miktex-kpathsea-bin-x64-2.9.tar.lzma -2022/10/29 | 30571 | systems/win32/miktex/tm/packages/next/miktex-lacheck-bin-x64-2.9.tar.lzma -2022/10/29 | 682214 | systems/win32/miktex/tm/packages/next/miktex-lcdf-typetools-bin-x64-2.9.tar.lzma -2022/10/29 | 599105 | systems/win32/miktex/tm/packages/next/miktex-libressl-bin-x64-2.9.tar.lzma -2022/10/29 | 527570 | systems/win32/miktex/tm/packages/next/miktex-log4cxx-bin-x64-2.9.tar.lzma -2022/10/29 | 103597 | systems/win32/miktex/tm/packages/next/miktex-lua53-bin-x64-2.9.tar.lzma -2022/10/29 | 2023134 | systems/win32/miktex/tm/packages/next/miktex-luatex-bin-x64-2.9.tar.lzma -2022/10/29 | 74099 | systems/win32/miktex/tm/packages/next/miktex-lzma-bin-x64-2.9.tar.lzma -2022/10/29 | 32074 | systems/win32/miktex/tm/packages/next/miktex-makeindex-bin-x64-2.9.tar.lzma -2022/10/29 | 8826 | systems/win32/miktex/tm/packages/next/miktex-md5-bin-x64-2.9.tar.lzma -2022/10/29 | 209139 | systems/win32/miktex/tm/packages/next/miktex-metafont-bin-x64-2.9.tar.lzma -2022/10/29 | 286685 | systems/win32/miktex/tm/packages/next/miktex-metapost-bin-x64-2.9.tar.lzma -2022/10/29 | 104921 | systems/win32/miktex/tm/packages/next/miktex-mfware-bin-x64-2.9.tar.lzma -2022/10/29 | 140012 | systems/win32/miktex/tm/packages/next/miktex-mktex-bin-x64-2.9.tar.lzma -2022/10/29 | 325485 | systems/win32/miktex/tm/packages/next/miktex-mo-bin-x64-2.9.tar.lzma -2022/10/29 | 181724 | systems/win32/miktex/tm/packages/next/miktex-mpfr-bin-x64-2.9.tar.lzma -2022/10/29 | 55320 | systems/win32/miktex/tm/packages/next/miktex-mpmcli-bin-x64-2.9.tar.lzma -2022/10/29 | 35232 | systems/win32/miktex/tm/packages/next/miktex-mspack-bin-x64-2.9.tar.lzma -2022/10/29 | 43618 | systems/win32/miktex/tm/packages/next/miktex-mthelp-bin-x64-2.9.tar.lzma -2022/10/29 | 48038 | systems/win32/miktex/tm/packages/next/miktex-mtprint-bin-x64-2.9.tar.lzma -2022/10/29 | 52369 | systems/win32/miktex/tm/packages/next/miktex-m-tx-bin-x64-2.9.tar.lzma -2022/10/29 | 213847 | systems/win32/miktex/tm/packages/next/miktex-omegaware-bin-x64-2.9.tar.lzma -2022/10/29 | 41179 | systems/win32/miktex/tm/packages/next/miktex-patgen-bin-x64.tar.lzma -2022/10/29 | 824996 | systems/win32/miktex/tm/packages/next/miktex-pdftex-bin-x64-2.9.tar.lzma -2022/10/29 | 203420 | systems/win32/miktex/tm/packages/next/miktex-pixman-bin-x64-2.9.tar.lzma -2022/10/29 | 245152 | systems/win32/miktex/tm/packages/next/miktex-pmx-bin-x64-2.9.tar.lzma -2022/10/29 | 88483 | systems/win32/miktex/tm/packages/next/miktex-png-bin-x64-2.9.tar.lzma -2022/10/29 | 1323743 | systems/win32/miktex/tm/packages/next/miktex-poppler-bin-x64-2.9.tar.lzma -2022/10/29 | 23950 | systems/win32/miktex/tm/packages/next/miktex-popt-bin-x64-2.9.tar.lzma -2022/10/29 | 37507 | systems/win32/miktex/tm/packages/next/miktex-posix-bin-x64-2.9.tar.lzma -2022/10/29 | 72980 | systems/win32/miktex/tm/packages/next/miktex-ps2pk-bin-x64-2.9.tar.lzma -2022/10/29 | 58632 | systems/win32/miktex/tm/packages/next/miktex-psutils-bin-x64-2.9.tar.lzma -2022/10/29 | 769652 | systems/win32/miktex/tm/packages/next/miktex-ptex-bin-x64.tar.lzma -2022/10/29 | 1503054 | systems/win32/miktex/tm/packages/next/miktex-runtime-bin-x64-2.9.tar.lzma -2022/10/29 | 52627 | systems/win32/miktex/tm/packages/next/miktex-synctex-bin-x64-2.9.tar.lzma -2022/10/29 | 63803 | systems/win32/miktex/tm/packages/next/miktex-tdsutil-bin-x64.tar.lzma -2022/10/29 | 27464 | systems/win32/miktex/tm/packages/next/miktex-teckit-bin-x64-2.9.tar.lzma -2022/10/29 | 18511 | systems/win32/miktex/tm/packages/next/miktex-tex2xindy-bin-x64-2.9.tar.lzma -2022/10/29 | 70939 | systems/win32/miktex/tm/packages/next/miktex-tex4ht-bin-x64-2.9.tar.lzma -2022/10/29 | 173177 | systems/win32/miktex/tm/packages/next/miktex-tex-bin-x64-2.9.tar.lzma -2022/10/29 | 68147 | systems/win32/miktex/tm/packages/next/miktex-texify-bin-x64-2.9.tar.lzma -2022/10/29 | 107438 | systems/win32/miktex/tm/packages/next/miktex-texware-bin-x64-2.9.tar.lzma -2022/10/29 | 2821672 | systems/win32/miktex/tm/packages/next/miktex-texworks-bin-x64-2.9.tar.lzma -2022/10/29 | 62359 | systems/win32/miktex/tm/packages/next/miktex-ttf2pk2-bin-x64-2.9.tar.lzma -2022/10/29 | 41190 | systems/win32/miktex/tm/packages/next/miktex-upmendex-bin-x64.tar.lzma -2022/10/29 | 33863 | systems/win32/miktex/tm/packages/next/miktex-uriparser-bin-x64-2.9.tar.lzma -2022/10/29 | 73685 | systems/win32/miktex/tm/packages/next/miktex-web-bin-x64-2.9.tar.lzma -2022/10/29 | 352464 | systems/win32/miktex/tm/packages/next/miktex-xetex-bin-x64-2.9.tar.lzma -2022/10/29 | 57501 | systems/win32/miktex/tm/packages/next/miktex-xml2pmx-bin-x64.tar.lzma -2022/10/29 | 630433 | systems/win32/miktex/tm/packages/next/miktex-yap-bin-x64-2.9.tar.lzma -2022/10/29 | 43527 | systems/win32/miktex/tm/packages/next/miktex-zlib-bin-x64-2.9.tar.lzma -2022/10/29 | 299960 | systems/win32/miktex/tm/packages/next/miktex-zzdb1-2.9.tar.lzma -2022/10/29 | 1506393 | systems/win32/miktex/tm/packages/next/miktex-zzdb2-2.9.tar.lzma -2022/10/29 | 1385541 | systems/win32/miktex/tm/packages/next/miktex-zzdb3-2.9.tar.lzma -2022/10/29 | 14434 | systems/win32/miktex/tm/packages/next/miktex-zzip-bin-x64-2.9.tar.lzma +2022/10/30 | 667232 | systems/win32/miktex/tm/packages/next/files.csv.lzma +2022/10/30 | 57318 | systems/win32/miktex/tm/packages/next/miktex-arctrl-bin-x64-2.9.tar.lzma +2022/10/30 | 1161751 | systems/win32/miktex/tm/packages/next/miktex-asymptote-bin-x64-2.9.tar.lzma +2022/10/30 | 31587 | systems/win32/miktex/tm/packages/next/miktex-autosp-bin-x64-2.9.tar.lzma +2022/10/30 | 35265 | systems/win32/miktex/tm/packages/next/miktex-axohelp-bin-x64-2.9.tar.lzma +2022/10/30 | 65130 | systems/win32/miktex/tm/packages/next/miktex-bibarts-bin-x64-2.9.tar.lzma +2022/10/30 | 95468 | systems/win32/miktex/tm/packages/next/miktex-bibtex8bit-bin-x64-2.9.tar.lzma +2022/10/30 | 77212 | systems/win32/miktex/tm/packages/next/miktex-bibtex-bin-x64-2.9.tar.lzma +2022/10/30 | 31563 | systems/win32/miktex/tm/packages/next/miktex-bzip2-bin-x64-2.9.tar.lzma +2022/10/30 | 394144 | systems/win32/miktex/tm/packages/next/miktex-cairo-bin-x64-2.9.tar.lzma +2022/10/30 | 37051 | systems/win32/miktex/tm/packages/next/miktex-chktex-bin-x64-2.9.tar.lzma +2022/10/30 | 57506 | systems/win32/miktex/tm/packages/next/miktex-cjkutils-bin-x64-2.9.tar.lzma +2022/10/30 | 270466 | systems/win32/miktex/tm/packages/next/miktex-console-bin-x64-2.9.tar.lzma +2022/10/30 | 196213 | systems/win32/miktex/tm/packages/next/miktex-curl-bin-x64-2.9.tar.lzma +2022/10/30 | 103246 | systems/win32/miktex/tm/packages/next/miktex-cweb-bin-x64-2.9.tar.lzma +2022/10/30 | 24212 | systems/win32/miktex/tm/packages/next/miktex-devnag-bin-x64-2.9.tar.lzma +2022/10/30 | 481893 | systems/win32/miktex/tm/packages/next/miktex-doc.tar.lzma +2022/10/30 | 52037 | systems/win32/miktex/tm/packages/next/miktex-dvicopy-bin-x64-2.9.tar.lzma +2022/10/30 | 325979 | systems/win32/miktex/tm/packages/next/miktex-dvipdfmx-bin-x64-2.9.tar.lzma +2022/10/30 | 45795 | systems/win32/miktex/tm/packages/next/miktex-dvipng-bin-x64-2.9.tar.lzma +2022/10/30 | 135466 | systems/win32/miktex/tm/packages/next/miktex-dvips-bin-x64-2.9.tar.lzma +2022/10/30 | 1458152 | systems/win32/miktex/tm/packages/next/miktex-dvisvgm-bin-x64-2.9.tar.lzma +2022/10/30 | 112980 | systems/win32/miktex/tm/packages/next/miktex-epstopdf-bin-x64-2.9.tar.lzma +2022/10/30 | 48852 | systems/win32/miktex/tm/packages/next/miktex-expat-bin-x64-2.9.tar.lzma +2022/10/30 | 28511 | systems/win32/miktex/tm/packages/next/miktex-findtexmf-bin-x64-2.9.tar.lzma +2022/10/30 | 63241 | systems/win32/miktex/tm/packages/next/miktex-fmt-bin-x64-2.9.tar.lzma +2022/10/30 | 155433 | systems/win32/miktex/tm/packages/next/miktex-fontconfig-bin-x64-2.9.tar.lzma +2022/10/30 | 79064 | systems/win32/miktex/tm/packages/next/miktex-fonts-bin-x64-2.9.tar.lzma +2022/10/30 | 81449 | systems/win32/miktex/tm/packages/next/miktex-freeglut-bin-x64-2.9.tar.lzma +2022/10/30 | 295945 | systems/win32/miktex/tm/packages/next/miktex-freetype2-bin-x64-2.9.tar.lzma +2022/10/30 | 25119 | systems/win32/miktex/tm/packages/next/miktex-fribidixetex-bin-x64-2.9.tar.lzma +2022/10/30 | 112876 | systems/win32/miktex/tm/packages/next/miktex-gd-bin-x64-2.9.tar.lzma +2022/10/30 | 73264 | systems/win32/miktex/tm/packages/next/miktex-graphite2-bin-x64-2.9.tar.lzma +2022/10/30 | 115581 | systems/win32/miktex/tm/packages/next/miktex-gregorio-bin-x64-2.9.tar.lzma +2022/10/30 | 43890 | systems/win32/miktex/tm/packages/next/miktex-gsf2pk-bin-x64-2.9.tar.lzma +2022/10/30 | 565082 | systems/win32/miktex/tm/packages/next/miktex-harfbuzz-bin-x64-2.9.tar.lzma +2022/10/30 | 247207 | systems/win32/miktex/tm/packages/next/miktex-hitex-bin-x64.tar.lzma +2022/10/30 | 169678 | systems/win32/miktex/tm/packages/next/miktex-hunspell-bin-x64-2.9.tar.lzma +2022/10/30 | 109650 | systems/win32/miktex/tm/packages/next/miktex-jpeg-bin-x64-2.9.tar.lzma +2022/10/30 | 18383 | systems/win32/miktex/tm/packages/next/miktex-kpathsea-bin-x64-2.9.tar.lzma +2022/10/30 | 30571 | systems/win32/miktex/tm/packages/next/miktex-lacheck-bin-x64-2.9.tar.lzma +2022/10/30 | 682214 | systems/win32/miktex/tm/packages/next/miktex-lcdf-typetools-bin-x64-2.9.tar.lzma +2022/10/30 | 599105 | systems/win32/miktex/tm/packages/next/miktex-libressl-bin-x64-2.9.tar.lzma +2022/10/30 | 527570 | systems/win32/miktex/tm/packages/next/miktex-log4cxx-bin-x64-2.9.tar.lzma +2022/10/30 | 103599 | systems/win32/miktex/tm/packages/next/miktex-lua53-bin-x64-2.9.tar.lzma +2022/10/30 | 2023133 | systems/win32/miktex/tm/packages/next/miktex-luatex-bin-x64-2.9.tar.lzma +2022/10/30 | 74099 | systems/win32/miktex/tm/packages/next/miktex-lzma-bin-x64-2.9.tar.lzma +2022/10/30 | 32075 | systems/win32/miktex/tm/packages/next/miktex-makeindex-bin-x64-2.9.tar.lzma +2022/10/30 | 8826 | systems/win32/miktex/tm/packages/next/miktex-md5-bin-x64-2.9.tar.lzma +2022/10/30 | 209139 | systems/win32/miktex/tm/packages/next/miktex-metafont-bin-x64-2.9.tar.lzma +2022/10/30 | 286685 | systems/win32/miktex/tm/packages/next/miktex-metapost-bin-x64-2.9.tar.lzma +2022/10/30 | 104923 | systems/win32/miktex/tm/packages/next/miktex-mfware-bin-x64-2.9.tar.lzma +2022/10/30 | 140012 | systems/win32/miktex/tm/packages/next/miktex-mktex-bin-x64-2.9.tar.lzma +2022/10/30 | 325482 | systems/win32/miktex/tm/packages/next/miktex-mo-bin-x64-2.9.tar.lzma +2022/10/30 | 181725 | systems/win32/miktex/tm/packages/next/miktex-mpfr-bin-x64-2.9.tar.lzma +2022/10/30 | 55320 | systems/win32/miktex/tm/packages/next/miktex-mpmcli-bin-x64-2.9.tar.lzma +2022/10/30 | 35230 | systems/win32/miktex/tm/packages/next/miktex-mspack-bin-x64-2.9.tar.lzma +2022/10/30 | 43619 | systems/win32/miktex/tm/packages/next/miktex-mthelp-bin-x64-2.9.tar.lzma +2022/10/30 | 48037 | systems/win32/miktex/tm/packages/next/miktex-mtprint-bin-x64-2.9.tar.lzma +2022/10/30 | 52370 | systems/win32/miktex/tm/packages/next/miktex-m-tx-bin-x64-2.9.tar.lzma +2022/10/30 | 213848 | systems/win32/miktex/tm/packages/next/miktex-omegaware-bin-x64-2.9.tar.lzma +2022/10/30 | 41180 | systems/win32/miktex/tm/packages/next/miktex-patgen-bin-x64.tar.lzma +2022/10/30 | 824996 | systems/win32/miktex/tm/packages/next/miktex-pdftex-bin-x64-2.9.tar.lzma +2022/10/30 | 203420 | systems/win32/miktex/tm/packages/next/miktex-pixman-bin-x64-2.9.tar.lzma +2022/10/30 | 245152 | systems/win32/miktex/tm/packages/next/miktex-pmx-bin-x64-2.9.tar.lzma +2022/10/30 | 88484 | systems/win32/miktex/tm/packages/next/miktex-png-bin-x64-2.9.tar.lzma +2022/10/30 | 1323744 | systems/win32/miktex/tm/packages/next/miktex-poppler-bin-x64-2.9.tar.lzma +2022/10/30 | 23951 | systems/win32/miktex/tm/packages/next/miktex-popt-bin-x64-2.9.tar.lzma +2022/10/30 | 37507 | systems/win32/miktex/tm/packages/next/miktex-posix-bin-x64-2.9.tar.lzma +2022/10/30 | 72979 | systems/win32/miktex/tm/packages/next/miktex-ps2pk-bin-x64-2.9.tar.lzma +2022/10/30 | 58633 | systems/win32/miktex/tm/packages/next/miktex-psutils-bin-x64-2.9.tar.lzma +2022/10/30 | 769653 | systems/win32/miktex/tm/packages/next/miktex-ptex-bin-x64.tar.lzma +2022/10/30 | 1503055 | systems/win32/miktex/tm/packages/next/miktex-runtime-bin-x64-2.9.tar.lzma +2022/10/30 | 52627 | systems/win32/miktex/tm/packages/next/miktex-synctex-bin-x64-2.9.tar.lzma +2022/10/30 | 63803 | systems/win32/miktex/tm/packages/next/miktex-tdsutil-bin-x64.tar.lzma +2022/10/30 | 27464 | systems/win32/miktex/tm/packages/next/miktex-teckit-bin-x64-2.9.tar.lzma +2022/10/30 | 18510 | systems/win32/miktex/tm/packages/next/miktex-tex2xindy-bin-x64-2.9.tar.lzma +2022/10/30 | 70939 | systems/win32/miktex/tm/packages/next/miktex-tex4ht-bin-x64-2.9.tar.lzma +2022/10/30 | 173177 | systems/win32/miktex/tm/packages/next/miktex-tex-bin-x64-2.9.tar.lzma +2022/10/30 | 68147 | systems/win32/miktex/tm/packages/next/miktex-texify-bin-x64-2.9.tar.lzma +2022/10/30 | 107439 | systems/win32/miktex/tm/packages/next/miktex-texware-bin-x64-2.9.tar.lzma +2022/10/30 | 2821671 | systems/win32/miktex/tm/packages/next/miktex-texworks-bin-x64-2.9.tar.lzma +2022/10/30 | 62360 | systems/win32/miktex/tm/packages/next/miktex-ttf2pk2-bin-x64-2.9.tar.lzma +2022/10/30 | 41192 | systems/win32/miktex/tm/packages/next/miktex-upmendex-bin-x64.tar.lzma +2022/10/30 | 33862 | systems/win32/miktex/tm/packages/next/miktex-uriparser-bin-x64-2.9.tar.lzma +2022/10/30 | 73684 | systems/win32/miktex/tm/packages/next/miktex-web-bin-x64-2.9.tar.lzma +2022/10/30 | 352465 | systems/win32/miktex/tm/packages/next/miktex-xetex-bin-x64-2.9.tar.lzma +2022/10/30 | 57502 | systems/win32/miktex/tm/packages/next/miktex-xml2pmx-bin-x64.tar.lzma +2022/10/30 | 630437 | systems/win32/miktex/tm/packages/next/miktex-yap-bin-x64-2.9.tar.lzma +2022/10/30 | 43528 | systems/win32/miktex/tm/packages/next/miktex-zlib-bin-x64-2.9.tar.lzma +2022/10/30 | 299957 | systems/win32/miktex/tm/packages/next/miktex-zzdb1-2.9.tar.lzma +2022/10/30 | 1505326 | systems/win32/miktex/tm/packages/next/miktex-zzdb2-2.9.tar.lzma +2022/10/30 | 1384950 | systems/win32/miktex/tm/packages/next/miktex-zzdb3-2.9.tar.lzma +2022/10/30 | 14434 | systems/win32/miktex/tm/packages/next/miktex-zzip-bin-x64-2.9.tar.lzma 2019/03/12 | 1412 | systems/win32/miktex/tm/packages/nextpage.tar.lzma -2022/10/29 | 1172 | systems/win32/miktex/tm/packages/next/pr.ini +2022/10/30 | 1172 | systems/win32/miktex/tm/packages/next/pr.ini 2018/07/06 | 145915 | systems/win32/miktex/tm/packages/nexus-otf.tar.lzma 2017/03/30 | 191149 | systems/win32/miktex/tm/packages/nfssext-cfr.tar.lzma 2012/12/20 | 612251 | systems/win32/miktex/tm/packages/nicefilelist.tar.lzma @@ -304190,7 +304179,7 @@ 2022/02/22 | 6917 | systems/win32/miktex/tm/packages/preview.tar.lzma 2019/06/20 | 375963 | systems/win32/miktex/tm/packages/prftree.tar.lzma 2021/04/23 | 274028 | systems/win32/miktex/tm/packages/principia.tar.lzma -2022/10/29 | 990 | systems/win32/miktex/tm/packages/pr.ini +2022/10/30 | 990 | systems/win32/miktex/tm/packages/pr.ini 2010/09/27 | 248469 | systems/win32/miktex/tm/packages/printlen.tar.lzma 2008/06/17 | 77313 | systems/win32/miktex/tm/packages/proba.tar.lzma 2017/07/12 | 988486 | systems/win32/miktex/tm/packages/probsoln.tar.lzma @@ -306178,7 +306167,7 @@ 2014/07/05 | 611 | systems/win32/yandy/README 2014/07/05 | 1004628 | systems/win32/yandy/yandy-src.tar.xz 2014/07/05 | 1012416 | systems/win32/yandy.zip -2022/10/30 | 186 | timestamp +2022/10/31 | 186 | timestamp 2002/08/26 | 61898 | usergrps/dante/antrag.pdf 2002/08/26 | 118217 | usergrps/dante/antrag.ps 2022/02/28 | 917 | usergrps/dante/dtk/doc/beispiel.bib diff --git a/FILES.byname.gz b/FILES.byname.gz index 96c821b337..796645e5c3 100644 Binary files a/FILES.byname.gz and b/FILES.byname.gz differ diff --git a/FILES.last07days b/FILES.last07days index aac50e2d13..2917c62275 100644 --- a/FILES.last07days +++ b/FILES.last07days @@ -1,182 +1,491 @@ -2022/10/29 | 996929 | macros/latex/contrib/eolang.zip -2022/10/29 | 990 | systems/win32/miktex/tm/packages/pr.ini -2022/10/29 | 969068 | macros/latex/contrib/eolang/eolang.pdf -2022/10/29 | 95468 | systems/win32/miktex/tm/packages/next/miktex-bibtex8bit-bin-x64-2.9.tar.lzma -2022/10/29 | 88483 | systems/win32/miktex/tm/packages/next/miktex-png-bin-x64-2.9.tar.lzma -2022/10/29 | 8826 | systems/win32/miktex/tm/packages/next/miktex-md5-bin-x64-2.9.tar.lzma -2022/10/29 | 824996 | systems/win32/miktex/tm/packages/next/miktex-pdftex-bin-x64-2.9.tar.lzma -2022/10/29 | 81448 | systems/win32/miktex/tm/packages/next/miktex-freeglut-bin-x64-2.9.tar.lzma +2022/10/30 | 990 | systems/win32/miktex/tm/packages/pr.ini +2022/10/30 | 9860 | systems/texlive/tlnet/archive/huawei.source.r64848.tar.xz +2022/10/30 | 984 | macros/luatex/latex/luaoptions/luaoptionsmanual.cls +2022/10/30 | 9843 | support/latexindent/LatexIndent/Lines.pm +2022/10/30 | 983 | support/lyluatex/lyluatexmanual.cls +2022/10/30 | 97205 | support/lyluatex/lyluatex.tex +2022/10/30 | 95468 | systems/win32/miktex/tm/packages/next/miktex-bibtex8bit-bin-x64-2.9.tar.lzma +2022/10/30 | 941916 | systems/texlive/tlnet/archive/gillius.r64859.tar.xz +2022/10/30 | 933144 | graphics/pgf/contrib/bodeplot.zip +2022/10/30 | 9122 | macros/latex/contrib/ffcode/ffcode.dtx +2022/10/30 | 910334 | graphics/pgf/contrib/bodeplot/bodeplot.dtx +2022/10/30 | 88484 | systems/win32/miktex/tm/packages/next/miktex-png-bin-x64-2.9.tar.lzma +2022/10/30 | 8829 | support/latexindent/LatexIndent/IfElseFi.pm +2022/10/30 | 8826 | systems/win32/miktex/tm/packages/next/miktex-md5-bin-x64-2.9.tar.lzma +2022/10/30 | 881 | macros/luatex/latex/luaoptions/README.md +2022/10/30 | 880404 | systems/texlive/tlnet/archive/eolang.doc.r64847.tar.xz +2022/10/30 | 8700045 | support/latexindent/bin/windows/latexindent.exe +2022/10/30 | 8462 | support/latexindent/LatexIndent/FileExtension.pm +2022/10/30 | 8372 | systems/texlive/tlnet/archive/eolang.source.r64847.tar.xz +2022/10/30 | 836 | support/latexindent/LatexIndent/Version.pm +2022/10/30 | 8322 | macros/luatex/latex/luaoptions/luaoptions.tex +2022/10/30 | 827 | macros/luatex/latex/luaoptions/luaoptions.sty +2022/10/30 | 824996 | systems/win32/miktex/tm/packages/next/miktex-pdftex-bin-x64-2.9.tar.lzma +2022/10/30 | 81449 | systems/win32/miktex/tm/packages/next/miktex-freeglut-bin-x64-2.9.tar.lzma +2022/10/30 | 8139 | macros/latex/contrib/pkuthss/tex/pkuword.eps +2022/10/30 | 8078 | macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib +2022/10/30 | 79064 | systems/win32/miktex/tm/packages/next/miktex-fonts-bin-x64-2.9.tar.lzma +2022/10/30 | 7844 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt +2022/10/30 | 777678 | macros/xetex/latex/xepersian/xepersian.pdf +2022/10/30 | 777364 | systems/texlive/tlnet/archive/huawei.doc.r64848.tar.xz +2022/10/30 | 77212 | systems/win32/miktex/tm/packages/next/miktex-bibtex-bin-x64-2.9.tar.lzma +2022/10/30 | 769653 | systems/win32/miktex/tm/packages/next/miktex-ptex-bin-x64.tar.lzma +2022/10/30 | 74099 | systems/win32/miktex/tm/packages/next/miktex-lzma-bin-x64-2.9.tar.lzma +2022/10/30 | 73684 | systems/win32/miktex/tm/packages/next/miktex-web-bin-x64-2.9.tar.lzma +2022/10/30 | 7329 | support/latexindent/LatexIndent/BackUpFileProcedure.pm +2022/10/30 | 73264 | systems/win32/miktex/tm/packages/next/miktex-graphite2-bin-x64-2.9.tar.lzma +2022/10/30 | 72979 | systems/win32/miktex/tm/packages/next/miktex-ps2pk-bin-x64-2.9.tar.lzma +2022/10/30 | 7280 | support/latexindent/LatexIndent/MandatoryArgument.pm +2022/10/30 | 7161 | support/latexindent/documentation/figure-schematic.png +2022/10/30 | 71387 | macros/xetex/latex/xepersian/xepersian-doc-basics.ltx +2022/10/30 | 712 | systems/texlive/tlnet/archive/twemoji-colr.doc.r64854.tar.xz +2022/10/30 | 70939 | systems/win32/miktex/tm/packages/next/miktex-tex4ht-bin-x64-2.9.tar.lzma +2022/10/30 | 7065 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap1.tex +2022/10/30 | 6964 | support/latexindent/LatexIndent/TrailingComments.pm +2022/10/30 | 684 | macros/latex/contrib/pkuthss/README.txt +2022/10/30 | 682214 | systems/win32/miktex/tm/packages/next/miktex-lcdf-typetools-bin-x64-2.9.tar.lzma +2022/10/30 | 68147 | systems/win32/miktex/tm/packages/next/miktex-texify-bin-x64-2.9.tar.lzma +2022/10/30 | 6808 | support/latexindent/LatexIndent/Environment.pm +2022/10/30 | 6694 | support/latexindent/LatexIndent/Item.pm +2022/10/30 | 668296 | systems/win32/miktex/tm/packages/files.csv.lzma +2022/10/30 | 667232 | systems/win32/miktex/tm/packages/next/files.csv.lzma +2022/10/30 | 6522 | support/latexindent/LatexIndent/OptionalArgument.pm +2022/10/30 | 65130 | systems/win32/miktex/tm/packages/next/miktex-bibarts-bin-x64-2.9.tar.lzma +2022/10/30 | 6508 | systems/texlive/tlnet/archive/pdflscape.source.r64851.tar.xz +2022/10/30 | 65059 | support/latexindent/LatexIndent/AlignmentAtAmpersand.pm +2022/10/30 | 641 | macros/latex/contrib/eolang/eolang.bib +2022/10/30 | 6404764 | systems/texlive/tlnet/archive/jeuxcartes.doc.r64850.tar.xz +2022/10/30 | 6389393 | support/latexindent/bin/macos/latexindent +2022/10/30 | 63803 | systems/win32/miktex/tm/packages/next/miktex-tdsutil-bin-x64.tar.lzma +2022/10/30 | 6378 | macros/luatex/latex/luaoptions/luaoptions-lib.lua +2022/10/30 | 63241 | systems/win32/miktex/tm/packages/next/miktex-fmt-bin-x64-2.9.tar.lzma +2022/10/30 | 632099 | install/macros/latex/contrib/biblatex-contrib/biblatex-caspervector.tds.zip +2022/10/30 | 630555 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector.zip +2022/10/30 | 630437 | systems/win32/miktex/tm/packages/next/miktex-yap-bin-x64-2.9.tar.lzma +2022/10/30 | 6280 | macros/latex/contrib/pkuthss/tex/pkuword.pdf +2022/10/30 | 62360 | systems/win32/miktex/tm/packages/next/miktex-ttf2pk2-bin-x64-2.9.tar.lzma +2022/10/30 | 6159922 | support/latexindent/bin/linux/latexindent +2022/10/30 | 6023 | support/latexindent/LatexIndent/Else.pm +2022/10/30 | 599105 | systems/win32/miktex/tm/packages/next/miktex-libressl-bin-x64-2.9.tar.lzma +2022/10/30 | 58 | support/lyluatex/latexmkrc +2022/10/30 | 58 | macros/luatex/latex/luaoptions/latexmkrc +2022/10/30 | 58633 | systems/win32/miktex/tm/packages/next/miktex-psutils-bin-x64-2.9.tar.lzma +2022/10/30 | 5834574 | systems/texlive/tlnet/install-tl-unx.tar.gz +2022/10/30 | 581228 | systems/texlive/tlnet/archive/twemoji-colr.r64854.tar.xz +2022/10/30 | 5809 | support/latexindent/LatexIndent/UnNamedGroupingBracesBrackets.pm +2022/10/30 | 5804 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex +2022/10/30 | 57506 | systems/win32/miktex/tm/packages/next/miktex-cjkutils-bin-x64-2.9.tar.lzma +2022/10/30 | 57502 | systems/win32/miktex/tm/packages/next/miktex-xml2pmx-bin-x64.tar.lzma +2022/10/30 | 57318 | systems/win32/miktex/tm/packages/next/miktex-arctrl-bin-x64-2.9.tar.lzma +2022/10/30 | 565082 | systems/win32/miktex/tm/packages/next/miktex-harfbuzz-bin-x64-2.9.tar.lzma +2022/10/30 | 5642836 | systems/texlive/tlnet/archive/jeuxcartes.r64850.tar.xz +2022/10/30 | 5612 | systems/texlive/tlnet/archive/iexec.source.r64849.tar.xz +2022/10/30 | 55320 | systems/win32/miktex/tm/packages/next/miktex-mpmcli-bin-x64-2.9.tar.lzma +2022/10/30 | 5463 | macros/latex/contrib/pkuthss/doc/example/thesis.tex +2022/10/30 | 5447 | macros/xetex/latex/xepersian/xepersian-doc-envcs.ltx +2022/10/30 | 54383 | support/latexindent/documentation/latexindent-yaml-schema.json +2022/10/30 | 5430 | support/latexindent/LatexIndent/KeyEqualsValuesBraces.pm +2022/10/30 | 5390 | support/latexindent/LatexIndent/Check.pm +2022/10/30 | 532 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/README.txt +2022/10/30 | 5284 | systems/texlive/tlnet/archive/transparent.source.r64852.tar.xz +2022/10/30 | 527570 | systems/win32/miktex/tm/packages/next/miktex-log4cxx-bin-x64-2.9.tar.lzma +2022/10/30 | 52627 | systems/win32/miktex/tm/packages/next/miktex-synctex-bin-x64-2.9.tar.lzma +2022/10/30 | 52370 | systems/win32/miktex/tm/packages/next/miktex-m-tx-bin-x64-2.9.tar.lzma +2022/10/30 | 5206 | support/latexindent/documentation/contributors.bib +2022/10/30 | 52037 | systems/win32/miktex/tm/packages/next/miktex-dvicopy-bin-x64-2.9.tar.lzma +2022/10/30 | 518498 | install/macros/latex/contrib/pkuthss.tds.zip +2022/10/30 | 514814 | macros/latex/contrib/pkuthss.zip +2022/10/30 | 48 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 +2022/10/30 | 488622 | macros/latex/contrib/ffcode.zip +2022/10/30 | 48856 | support/latexindent/LatexIndent/GetYamlSettings.pm +2022/10/30 | 48852 | systems/win32/miktex/tm/packages/next/miktex-expat-bin-x64-2.9.tar.lzma +2022/10/30 | 487461 | macros/latex/contrib/ffcode/ffcode.pdf +2022/10/30 | 481893 | systems/win32/miktex/tm/packages/next/miktex-doc.tar.lzma +2022/10/30 | 4816 | support/latexindent/LatexIndent/BlankLines.pm +2022/10/30 | 48037 | systems/win32/miktex/tm/packages/next/miktex-mtprint-bin-x64-2.9.tar.lzma +2022/10/30 | 47687 | macros/latex/contrib/eolang/cactus.pdf +2022/10/30 | 461 | macros/latex/contrib/pkuthss/doc/example/latexmkrc +2022/10/30 | 461932 | systems/texlive/tlnet/archive/hep-reference.doc.r64853.tar.xz +2022/10/30 | 46052 | systems/texlive/tlnet/archive/linguisticspro.doc.r64858.tar.xz +2022/10/30 | 45795 | systems/win32/miktex/tm/packages/next/miktex-dvipng-bin-x64-2.9.tar.lzma +2022/10/30 | 455 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc +2022/10/30 | 455 | systems/texlive/tlnet/install-tl.zip.sha512.asc +2022/10/30 | 455 | systems/texlive/tlnet/install-tl-windows.exe.sha512.asc +2022/10/30 | 455 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512.asc +2022/10/30 | 454 | macros/xetex/latex/xepersian/xepersian-doc.ltx +2022/10/30 | 4468 | systems/texlive/tlnet/archive/hep-reference.source.r64853.tar.xz +2022/10/30 | 44673 | support/lyluatex/lyluatex.lua +2022/10/30 | 44096 | support/latexindent/documentation/logo.png +2022/10/30 | 4402 | support/latexindent/documentation/latex-indent.bib +2022/10/30 | 43890 | systems/win32/miktex/tm/packages/next/miktex-gsf2pk-bin-x64-2.9.tar.lzma +2022/10/30 | 4365 | support/latexindent/LatexIndent/RoundBrackets.pm +2022/10/30 | 43619 | systems/win32/miktex/tm/packages/next/miktex-mthelp-bin-x64-2.9.tar.lzma +2022/10/30 | 43528 | systems/win32/miktex/tm/packages/next/miktex-zlib-bin-x64-2.9.tar.lzma +2022/10/30 | 4340 | support/latexindent/LatexIndent/NamedGroupingBracesBrackets.pm +2022/10/30 | 422980 | systems/texlive/tlnet/archive/texlive-scripts.doc.r64843.tar.xz +2022/10/30 | 4188 | systems/texlive/tlnet/archive/association-matrix.r64845.tar.xz +2022/10/30 | 4149 | macros/xetex/latex/xepersian/xepersian-doc-preamble.ltx +2022/10/30 | 41192 | systems/win32/miktex/tm/packages/next/miktex-upmendex-bin-x64.tar.lzma +2022/10/30 | 41180 | systems/win32/miktex/tm/packages/next/miktex-patgen-bin-x64.tar.lzma +2022/10/30 | 410 | macros/xetex/latex/xepersian/xepersian-doc-boolean.ltx +2022/10/30 | 40 | macros/latex/contrib/ffcode/DEPENDS.txt +2022/10/30 | 408105 | support/latexindent/documentation/latexindent.tex +2022/10/30 | 4012760 | biblio/ctan-bibdata.zip +2022/10/30 | 3996 | systems/texlive/tlnet/archive/eolang.r64847.tar.xz +2022/10/30 | 39904 | macros/luatex/latex/luaoptions.zip +2022/10/30 | 3957 | macros/latex/contrib/pkuthss/tex/pkulogo.eps +2022/10/30 | 394144 | systems/win32/miktex/tm/packages/next/miktex-cairo-bin-x64-2.9.tar.lzma +2022/10/30 | 393884 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf +2022/10/30 | 38725 | macros/xetex/latex/xepersian/ftxe-0.12.py +2022/10/30 | 3775 | macros/latex/contrib/pkuthss/doc/example/chap/origin.tex +2022/10/30 | 37507 | systems/win32/miktex/tm/packages/next/miktex-posix-bin-x64-2.9.tar.lzma +2022/10/30 | 3747 | support/latexindent/LatexIndent/Replacement.pm +2022/10/30 | 3720 | macros/unicodetex/latex/bithesis/bithesis.ins +2022/10/30 | 37051 | systems/win32/miktex/tm/packages/next/miktex-chktex-bin-x64-2.9.tar.lzma +2022/10/30 | 368064 | systems/texlive/tlnet/archive/accanthis.r64844.tar.xz +2022/10/30 | 364 | macros/latex/contrib/pkuthss/doc/example/Make.bat +2022/10/30 | 3620853 | biblio/ctan-bibdata/ctan.pdf +2022/10/30 | 3530 | macros/latex/contrib/pkuthss/tex/pkulogo.pdf +2022/10/30 | 35265 | systems/win32/miktex/tm/packages/next/miktex-axohelp-bin-x64-2.9.tar.lzma +2022/10/30 | 352465 | systems/win32/miktex/tm/packages/next/miktex-xetex-bin-x64-2.9.tar.lzma +2022/10/30 | 35230 | systems/win32/miktex/tm/packages/next/miktex-mspack-bin-x64-2.9.tar.lzma +2022/10/30 | 348380 | macros/latex/contrib/pkuthss/doc/pkuthss.pdf +2022/10/30 | 3482 | support/latexindent/LatexIndent/HorizontalWhiteSpace.pm +2022/10/30 | 343317 | macros/xetex/latex/xepersian/xepersian.dtx +2022/10/30 | 3410 | support/latexindent/latexindent.pl +2022/10/30 | 33862 | systems/win32/miktex/tm/packages/next/miktex-uriparser-bin-x64-2.9.tar.lzma +2022/10/30 | 3339 | support/latexindent/LatexIndent/Tokens.pm +2022/10/30 | 3305 | macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex +2022/10/30 | 325 | support/lyluatex/Contributors.md +2022/10/30 | 325979 | systems/win32/miktex/tm/packages/next/miktex-dvipdfmx-bin-x64-2.9.tar.lzma +2022/10/30 | 325482 | systems/win32/miktex/tm/packages/next/miktex-mo-bin-x64-2.9.tar.lzma +2022/10/30 | 325444 | systems/texlive/tlnet/archive/iexec.doc.r64849.tar.xz +2022/10/30 | 320 | support/lyluatex/ly/fonts.ly +2022/10/30 | 32075 | systems/win32/miktex/tm/packages/next/miktex-makeindex-bin-x64-2.9.tar.lzma +2022/10/30 | 31587 | systems/win32/miktex/tm/packages/next/miktex-autosp-bin-x64-2.9.tar.lzma +2022/10/30 | 31563 | systems/win32/miktex/tm/packages/next/miktex-bzip2-bin-x64-2.9.tar.lzma +2022/10/30 | 314616 | systems/texlive/tlnet/archive/pdflscape.doc.r64851.tar.xz +2022/10/30 | 3099 | macros/xetex/latex/xepersian/xepersian-doc-captions.ltx +2022/10/30 | 3084 | systems/texlive/tlnet/archive/debate.source.r64846.tar.xz +2022/10/30 | 30571 | systems/win32/miktex/tm/packages/next/miktex-lacheck-bin-x64-2.9.tar.lzma +2022/10/30 | 3035 | macros/latex/contrib/pkuthss/doc/readme/ChangeLog-upto-1.3.txt +2022/10/30 | 300388 | systems/texlive/tlnet/archive/accanthis.doc.r64844.tar.xz +2022/10/30 | 299957 | systems/win32/miktex/tm/packages/next/miktex-zzdb1-2.9.tar.lzma +2022/10/30 | 299956 | systems/win32/miktex/tm/packages/miktex-zzdb1-2.9.tar.lzma +2022/10/30 | 2960 | support/lyluatex/README.md +2022/10/30 | 295945 | systems/win32/miktex/tm/packages/next/miktex-freetype2-bin-x64-2.9.tar.lzma +2022/10/30 | 294 | macros/latex/contrib/pkuthss/doc/example/thesis.bib +2022/10/30 | 288 | macros/latex/contrib/pkuthss/doc/example/chap/abs.tex +2022/10/30 | 286685 | systems/win32/miktex/tm/packages/next/miktex-metapost-bin-x64-2.9.tar.lzma +2022/10/30 | 28593 | macros/luatex/latex/luaoptions/luaoptions.pdf +2022/10/30 | 285712 | systems/texlive/tlnet/archive/debate.doc.r64846.tar.xz +2022/10/30 | 28511 | systems/win32/miktex/tm/packages/next/miktex-findtexmf-bin-x64-2.9.tar.lzma +2022/10/30 | 2821671 | systems/win32/miktex/tm/packages/next/miktex-texworks-bin-x64-2.9.tar.lzma +2022/10/30 | 27563 | macros/latex/contrib/eolang/eolang.dtx +2022/10/30 | 275336 | systems/texlive/tlnet/archive/transparent.doc.r64852.tar.xz +2022/10/30 | 27464 | systems/win32/miktex/tm/packages/next/miktex-teckit-bin-x64-2.9.tar.lzma +2022/10/30 | 2743007 | biblio/ctan-bibdata/ctan.bib +2022/10/30 | 27328 | support/latexindent/LatexIndent/Verbatim.pm +2022/10/30 | 2713 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex +2022/10/30 | 270466 | systems/win32/miktex/tm/packages/next/miktex-console-bin-x64-2.9.tar.lzma +2022/10/30 | 2701 | support/latexindent/LatexIndent/Switches.pm +2022/10/30 | 2700300 | systems/texlive/tlnet/archive/simpleicons.r64855.tar.xz +2022/10/30 | 2690 | support/latexindent/LatexIndent/Preamble.pm +2022/10/30 | 268584 | systems/texlive/tlnet/archive/association-matrix.doc.r64845.tar.xz +2022/10/30 | 2643 | macros/unicodetex/latex/bithesis/contributing-zh.md +2022/10/30 | 2628 | macros/latex/contrib/ffcode/ffcode.ins +2022/10/30 | 2628 | macros/latex/contrib/eolang/eolang.ins +2022/10/30 | 2612 | systems/texlive/tlnet/archive/pdflscape.r64851.tar.xz +2022/10/30 | 2609 | macros/xetex/latex/xepersian/xepersian-doc-intro.ltx +2022/10/30 | 260132 | systems/texlive/tlnet/archive/huawei.r64848.tar.xz +2022/10/30 | 25876 | macros/xetex/latex/xepersian/xepersian-doc-pkgs.ltx +2022/10/30 | 256 | macros/luatex/latex/luaoptions/Contributors.md +2022/10/30 | 25518528 | systems/texlive/tlnet/install-tl.zip +2022/10/30 | 2525 | fonts/gillius/latex/gillius.sty +2022/10/30 | 25119 | systems/win32/miktex/tm/packages/next/miktex-fribidixetex-bin-x64-2.9.tar.lzma +2022/10/30 | 251116 | systems/texlive/tlnet/archive/playfair.doc.r64857.tar.xz +2022/10/30 | 247207 | systems/win32/miktex/tm/packages/next/miktex-hitex-bin-x64.tar.lzma +2022/10/30 | 24633 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.bib +2022/10/30 | 245152 | systems/win32/miktex/tm/packages/next/miktex-pmx-bin-x64-2.9.tar.lzma +2022/10/30 | 24410 | support/latexindent/LatexIndent/Arguments.pm +2022/10/30 | 2423428 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz +2022/10/30 | 24212 | systems/win32/miktex/tm/packages/next/miktex-devnag-bin-x64-2.9.tar.lzma +2022/10/30 | 2416 | systems/texlive/tlnet/archive/iexec.r64849.tar.xz +2022/10/30 | 23969 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex +2022/10/30 | 239667 | graphics/pgf/contrib/bodeplot/bodeplot.ins +2022/10/30 | 23951 | systems/win32/miktex/tm/packages/next/miktex-popt-bin-x64-2.9.tar.lzma +2022/10/30 | 237 | macros/latex/contrib/pkuthss/doc/readme/latexmkrc +2022/10/30 | 236749 | macros/xetex/latex/xepersian/xepersian-doc.pdf +2022/10/30 | 2349 | macros/latex/contrib/pkuthss/doc/example/chap/copy.tex +2022/10/30 | 2349 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx +2022/10/30 | 2332 | macros/unicodetex/latex/bithesis/contributing.md +2022/10/30 | 2320 | support/latexindent/LatexIndent/Logger.pm +2022/10/30 | 231797 | graphics/pgf/contrib/bodeplot/README.md +2022/10/30 | 22818 | support/latexindent/LatexIndent/Document.pm +2022/10/30 | 227 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/latexmkrc +2022/10/30 | 2272 | systems/texlive/tlnet/archive/transparent.r64852.tar.xz +2022/10/30 | 2272 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.tex +2022/10/30 | 2224 | macros/latex/contrib/pkuthss/doc/example/ctex-fontset-pkuthss.def +2022/10/30 | 216008 | systems/texlive/tlnet/archive/gillius.doc.r64859.tar.xz +2022/10/30 | 21564 | support/latexindent/LatexIndent/Indent.pm +2022/10/30 | 213848 | systems/win32/miktex/tm/packages/next/miktex-omegaware-bin-x64-2.9.tar.lzma +2022/10/30 | 212575 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf +2022/10/30 | 2108 | macros/xetex/latex/xepersian/xepersian-doc-title.ltx +2022/10/30 | 209139 | systems/win32/miktex/tm/packages/next/miktex-metafont-bin-x64-2.9.tar.lzma +2022/10/30 | 20434885 | systems/texlive/tlnet/install-tl-windows.exe +2022/10/30 | 20388 | support/latexindent/LatexIndent/Sentence.pm +2022/10/30 | 203420 | systems/win32/miktex/tm/packages/next/miktex-pixman-bin-x64-2.9.tar.lzma +2022/10/30 | 2028732 | support/lyluatex/lyluatex.pdf +2022/10/30 | 2023133 | systems/win32/miktex/tm/packages/next/miktex-luatex-bin-x64-2.9.tar.lzma +2022/10/30 | 2006 | support/latexindent/README +2022/10/30 | 1994 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-ack.tex +2022/10/30 | 1993 | macros/unicodetex/latex/bithesis/README.md +2022/10/30 | 19920 | support/latexindent/defaultSettings.yaml +2022/10/30 | 1982104 | systems/texlive/tlnet/archive/simpleicons.doc.r64855.tar.xz +2022/10/30 | 196213 | systems/win32/miktex/tm/packages/next/miktex-curl-bin-x64-2.9.tar.lzma +2022/10/30 | 193944 | macros/unicodetex/latex/bithesis/bithesis.dtx +2022/10/30 | 1920 | systems/texlive/tlnet/archive/hep-reference.r64853.tar.xz +2022/10/30 | 1908612 | macros/generic/tracklang.zip +2022/10/30 | 18510 | systems/win32/miktex/tm/packages/next/miktex-tex2xindy-bin-x64-2.9.tar.lzma +2022/10/30 | 18383 | systems/win32/miktex/tm/packages/next/miktex-kpathsea-bin-x64-2.9.tar.lzma +2022/10/30 | 18321 | support/latexindent/LatexIndent/ModifyLineBreaks.pm +2022/10/30 | 18304 | macros/xetex/latex/xepersian/img/ireland.jpg +2022/10/30 | 181725 | systems/win32/miktex/tm/packages/next/miktex-mpfr-bin-x64-2.9.tar.lzma +2022/10/30 | 1804 | fonts/gillius/README +2022/10/30 | 17979 | support/latexindent/LatexIndent/Wrap.pm +2022/10/30 | 17800554 | systems/texlive/tlnet/tlpkg/texlive.tlpdb +2022/10/30 | 173177 | systems/win32/miktex/tm/packages/next/miktex-tex-bin-x64-2.9.tar.lzma +2022/10/30 | 172672 | systems/texlive/tlnet/archive/poiretone.r64856.tar.xz +2022/10/30 | 1721181 | install/fonts/gillius.tds.zip +2022/10/30 | 169678 | systems/win32/miktex/tm/packages/next/miktex-hunspell-bin-x64-2.9.tar.lzma +2022/10/30 | 1692229 | fonts/gillius.zip +2022/10/30 | 1688 | systems/texlive/tlnet/archive/debate.r64846.tar.xz +2022/10/30 | 1682 | macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def +2022/10/30 | 1679528 | systems/texlive/tlnet/archive/playfair.r64857.tar.xz +2022/10/30 | 1678 | biblio/ctan-bibdata/biblatex-ctan/ctan.bbx +2022/10/30 | 1664 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx +2022/10/30 | 16634 | macros/latex/contrib/pkuthss/tex/pkuthss.cls +2022/10/30 | 16627 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex +2022/10/30 | 1657005 | support/lyluatex.zip +2022/10/30 | 1636 | systems/texlive/tlnet/archive/collection-mathscience.r64853.tar.xz +2022/10/30 | 159 | macros/latex/contrib/eolang/DEPENDS.txt +2022/10/30 | 15976 | macros/xetex/latex/xepersian/dkun-0.3.py +2022/10/30 | 1593 | macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def +2022/10/30 | 158 | support/lyluatex/ly/eight-systems.ly +2022/10/30 | 15867 | macros/xetex/latex/xepersian/dkun-0.4.py +2022/10/30 | 1575 | macros/latex/contrib/pkuthss/tex/pkuthss.def +2022/10/30 | 1569 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-copy.tex +2022/10/30 | 1558 | support/latexindent/latexindent-module-installer.pl +2022/10/30 | 155433 | systems/win32/miktex/tm/packages/next/miktex-fontconfig-bin-x64-2.9.tar.lzma +2022/10/30 | 153 | systems/texlive/tlnet/install-tl-windows.exe.sha512 +2022/10/30 | 1531 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def +2022/10/30 | 152 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512 +2022/10/30 | 15217 | macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt +2022/10/30 | 1507162 | systems/win32/miktex/tm/packages/miktex-zzdb2-2.9.tar.lzma +2022/10/30 | 1505326 | systems/win32/miktex/tm/packages/next/miktex-zzdb2-2.9.tar.lzma +2022/10/30 | 1503055 | systems/win32/miktex/tm/packages/next/miktex-runtime-bin-x64-2.9.tar.lzma +2022/10/30 | 1500 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def +2022/10/30 | 14902 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def +2022/10/30 | 1489 | macros/latex/contrib/pkuthss/doc/example/spine.tex +2022/10/30 | 1485 | support/latexindent/LatexIndent/DoubleBackSlash.pm +2022/10/30 | 147 | macros/latex/contrib/pkuthss/doc/example/chap/chap3.tex +2022/10/30 | 14616 | macros/xetex/latex/xepersian/img/weather/rain.jpg +2022/10/30 | 145 | systems/texlive/tlnet/install-tl.zip.sha512 +2022/10/30 | 1458152 | systems/win32/miktex/tm/packages/next/miktex-dvisvgm-bin-x64-2.9.tar.lzma +2022/10/30 | 144 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 +2022/10/30 | 14434 | systems/win32/miktex/tm/packages/next/miktex-zzip-bin-x64-2.9.tar.lzma +2022/10/30 | 140012 | systems/win32/miktex/tm/packages/next/miktex-mktex-bin-x64-2.9.tar.lzma +2022/10/30 | 1390 | macros/xetex/latex/xepersian/README +2022/10/30 | 138 | macros/latex/contrib/pkuthss/doc/example/chap/chap1.tex +2022/10/30 | 13890 | support/latexindent/LatexIndent/Special.pm +2022/10/30 | 1386224 | systems/win32/miktex/tm/packages/miktex-zzdb3-2.9.tar.lzma +2022/10/30 | 1384950 | systems/win32/miktex/tm/packages/next/miktex-zzdb3-2.9.tar.lzma +2022/10/30 | 13804 | macros/xetex/latex/xepersian/undk-0.6.py +2022/10/30 | 1377940 | systems/texlive/tlnet/archive/linguisticspro.r64858.tar.xz +2022/10/30 | 1376 | macros/latex/contrib/ffcode/README.md +2022/10/30 | 135466 | systems/win32/miktex/tm/packages/next/miktex-dvips-bin-x64-2.9.tar.lzma +2022/10/30 | 1352 | macros/latex/contrib/eolang/README.md +2022/10/30 | 13420 | support/latexindent/LatexIndent/HiddenChildren.pm +2022/10/30 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/encl1.tex +2022/10/30 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/chap2.tex +2022/10/30 | 133 | macros/latex/contrib/pkuthss/doc/example/chap/ack.tex +2022/10/30 | 1323744 | systems/win32/miktex/tm/packages/next/miktex-poppler-bin-x64-2.9.tar.lzma +2022/10/30 | 13088 | macros/xetex/latex/xepersian/img/weather/clouds.jpg +2022/10/30 | 12964 | systems/texlive/tlnet/archive/poiretone.doc.r64856.tar.xz +2022/10/30 | 1290311 | install/macros/xetex/latex/xepersian.tds.zip +2022/10/30 | 12897 | support/latexindent/LatexIndent/LogFile.pm +2022/10/30 | 12646 | support/latexindent/LatexIndent/Braces.pm +2022/10/30 | 12348 | macros/xetex/latex/xepersian/unldk-0.2.py +2022/10/30 | 1219 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-abs.tex +2022/10/30 | 1172 | systems/win32/miktex/tm/packages/next/pr.ini +2022/10/30 | 1170 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-encl1.tex +2022/10/30 | 1161751 | systems/win32/miktex/tm/packages/next/miktex-asymptote-bin-x64-2.9.tar.lzma +2022/10/30 | 115 | macros/latex/contrib/pkuthss/doc/example/ctexopts.cfg +2022/10/30 | 115581 | systems/win32/miktex/tm/packages/next/miktex-gregorio-bin-x64-2.9.tar.lzma +2022/10/30 | 1143 | macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-concl.tex +2022/10/30 | 113684 | systems/texlive/tlnet/archive/texlive-scripts.r64843.tar.xz +2022/10/30 | 11300 | support/latexindent/LatexIndent/FileContents.pm +2022/10/30 | 112980 | systems/win32/miktex/tm/packages/next/miktex-epstopdf-bin-x64-2.9.tar.lzma +2022/10/30 | 112876 | systems/win32/miktex/tm/packages/next/miktex-gd-bin-x64-2.9.tar.lzma +2022/10/30 | 1124966 | macros/xetex/latex/xepersian.zip +2022/10/30 | 1119 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx +2022/10/30 | 11142 | support/latexindent/LatexIndent/Heading.pm +2022/10/30 | 1105 | support/lyluatex/lyluatexbase.cls +2022/10/30 | 1105223 | support/latexindent/documentation/latexindent.pdf +2022/10/30 | 11009879 | support/latexindent.zip +2022/10/30 | 1099 | macros/luatex/latex/luaoptions/LICENSE +2022/10/30 | 109650 | systems/win32/miktex/tm/packages/next/miktex-jpeg-bin-x64-2.9.tar.lzma +2022/10/30 | 1090 | support/lyluatex/LICENSE +2022/10/30 | 10896 | macros/xetex/latex/xepersian/img/weather/sun.jpg +2022/10/30 | 1083 | macros/latex/contrib/ffcode/LICENSE.txt +2022/10/30 | 1083 | macros/latex/contrib/eolang/LICENSE.txt +2022/10/30 | 107439 | systems/win32/miktex/tm/packages/next/miktex-texware-bin-x64-2.9.tar.lzma +2022/10/30 | 1073024 | macros/unicodetex/latex/bithesis.zip +2022/10/30 | 1066728 | graphics/pgf/contrib/bodeplot/bodeplot.pdf +2022/10/30 | 1063401 | macros/latex/contrib/eolang.zip +2022/10/30 | 10622 | support/latexindent/LatexIndent/Command.pm +2022/10/30 | 1061 | macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx +2022/10/30 | 104923 | systems/win32/miktex/tm/packages/next/miktex-mfware-bin-x64-2.9.tar.lzma +2022/10/30 | 1043619 | macros/unicodetex/latex/bithesis/bithesis.pdf +2022/10/30 | 1039 | macros/luatex/latex/luaoptions/luaoptionsbase.cls +2022/10/30 | 10371 | macros/latex/contrib/pkuthss/doc/readme/pkuthss-english.patch +2022/10/30 | 103719 | macros/latex/contrib/pkuthss/doc/example.pdf +2022/10/30 | 1036825 | macros/latex/contrib/eolang/eolang.pdf +2022/10/30 | 103599 | systems/win32/miktex/tm/packages/next/miktex-lua53-bin-x64-2.9.tar.lzma +2022/10/30 | 103246 | systems/win32/miktex/tm/packages/next/miktex-cweb-bin-x64-2.9.tar.lzma +2022/10/30 | 10254 | support/lyluatex/lyluatex.sty +2022/10/30 | 10161 | macros/luatex/latex/luaoptions/luaoptions.lua +2022/10/29 | 941 | macros/generic/tracklang/samples/regions/regions.sty +2022/10/29 | 930 | macros/generic/tracklang/README +2022/10/29 | 848 | macros/generic/tracklang/samples/animals/animals2.sty 2022/10/29 | 804104 | macros/latex/contrib/huawei/huawei.pdf -2022/10/29 | 79064 | systems/win32/miktex/tm/packages/next/miktex-fonts-bin-x64-2.9.tar.lzma -2022/10/29 | 77212 | systems/win32/miktex/tm/packages/next/miktex-bibtex-bin-x64-2.9.tar.lzma -2022/10/29 | 769652 | systems/win32/miktex/tm/packages/next/miktex-ptex-bin-x64.tar.lzma -2022/10/29 | 74099 | systems/win32/miktex/tm/packages/next/miktex-lzma-bin-x64-2.9.tar.lzma -2022/10/29 | 73685 | systems/win32/miktex/tm/packages/next/miktex-web-bin-x64-2.9.tar.lzma -2022/10/29 | 73264 | systems/win32/miktex/tm/packages/next/miktex-graphite2-bin-x64-2.9.tar.lzma -2022/10/29 | 72980 | systems/win32/miktex/tm/packages/next/miktex-ps2pk-bin-x64-2.9.tar.lzma -2022/10/29 | 70939 | systems/win32/miktex/tm/packages/next/miktex-tex4ht-bin-x64-2.9.tar.lzma -2022/10/29 | 682214 | systems/win32/miktex/tm/packages/next/miktex-lcdf-typetools-bin-x64-2.9.tar.lzma -2022/10/29 | 68147 | systems/win32/miktex/tm/packages/next/miktex-texify-bin-x64-2.9.tar.lzma +2022/10/29 | 784 | macros/generic/tracklang/samples/animals/animals.sty +2022/10/29 | 781 | macros/generic/tracklang/samples/sample-tracklang4.tex +2022/10/29 | 764697 | macros/generic/tracklang/tracklang-manual.pdf +2022/10/29 | 7362 | systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl +2022/10/29 | 689 | macros/generic/tracklang/samples/sample-tracklang5.tex +2022/10/29 | 6869 | macros/generic/tracklang/samples/sample-tracklang4.pdf 2022/10/29 | 680 | macros/latex/contrib/association-matrix/README.md -2022/10/29 | 668296 | systems/win32/miktex/tm/packages/files.csv.lzma -2022/10/29 | 667232 | systems/win32/miktex/tm/packages/next/files.csv.lzma 2022/10/29 | 65 | macros/latex/contrib/association-matrix/DEPENDS.txt -2022/10/29 | 65130 | systems/win32/miktex/tm/packages/next/miktex-bibarts-bin-x64-2.9.tar.lzma -2022/10/29 | 641 | macros/latex/contrib/eolang/eolang.bib -2022/10/29 | 63803 | systems/win32/miktex/tm/packages/next/miktex-tdsutil-bin-x64.tar.lzma -2022/10/29 | 63241 | systems/win32/miktex/tm/packages/next/miktex-fmt-bin-x64-2.9.tar.lzma -2022/10/29 | 630433 | systems/win32/miktex/tm/packages/next/miktex-yap-bin-x64-2.9.tar.lzma -2022/10/29 | 62359 | systems/win32/miktex/tm/packages/next/miktex-ttf2pk2-bin-x64-2.9.tar.lzma -2022/10/29 | 599105 | systems/win32/miktex/tm/packages/next/miktex-libressl-bin-x64-2.9.tar.lzma -2022/10/29 | 58632 | systems/win32/miktex/tm/packages/next/miktex-psutils-bin-x64-2.9.tar.lzma -2022/10/29 | 5834398 | systems/texlive/tlnet/install-tl-unx.tar.gz -2022/10/29 | 57506 | systems/win32/miktex/tm/packages/next/miktex-cjkutils-bin-x64-2.9.tar.lzma -2022/10/29 | 57501 | systems/win32/miktex/tm/packages/next/miktex-xml2pmx-bin-x64.tar.lzma -2022/10/29 | 57317 | systems/win32/miktex/tm/packages/next/miktex-arctrl-bin-x64-2.9.tar.lzma -2022/10/29 | 565082 | systems/win32/miktex/tm/packages/next/miktex-harfbuzz-bin-x64-2.9.tar.lzma +2022/10/29 | 630 | macros/generic/tracklang/samples/regions/sample-regions2-map.tex +2022/10/29 | 629107 | macros/generic/tracklang/tracklang-code.pdf +2022/10/29 | 562 | macros/generic/tracklang/samples/regions/sample-regions2-map2.tex 2022/10/29 | 556 | macros/latex/contrib/transparent/README.md -2022/10/29 | 55320 | systems/win32/miktex/tm/packages/next/miktex-mpmcli-bin-x64-2.9.tar.lzma -2022/10/29 | 527570 | systems/win32/miktex/tm/packages/next/miktex-log4cxx-bin-x64-2.9.tar.lzma -2022/10/29 | 52627 | systems/win32/miktex/tm/packages/next/miktex-synctex-bin-x64-2.9.tar.lzma -2022/10/29 | 52369 | systems/win32/miktex/tm/packages/next/miktex-m-tx-bin-x64-2.9.tar.lzma -2022/10/29 | 52037 | systems/win32/miktex/tm/packages/next/miktex-dvicopy-bin-x64-2.9.tar.lzma 2022/10/29 | 51 | macros/latex/contrib/iexec/DEPENDS.txt 2022/10/29 | 5003 | macros/latex/contrib/debate/debate.dtx -2022/10/29 | 48 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 -2022/10/29 | 48852 | systems/win32/miktex/tm/packages/next/miktex-expat-bin-x64-2.9.tar.lzma 2022/10/29 | 484 | macros/latex/contrib/huawei/DEPENDS.txt -2022/10/29 | 481894 | systems/win32/miktex/tm/packages/next/miktex-doc.tar.lzma -2022/10/29 | 48038 | systems/win32/miktex/tm/packages/next/miktex-mtprint-bin-x64-2.9.tar.lzma -2022/10/29 | 47687 | macros/latex/contrib/eolang/cactus.pdf -2022/10/29 | 45796 | systems/win32/miktex/tm/packages/next/miktex-dvipng-bin-x64-2.9.tar.lzma -2022/10/29 | 455 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc -2022/10/29 | 455 | systems/texlive/tlnet/install-tl.zip.sha512.asc -2022/10/29 | 455 | systems/texlive/tlnet/install-tl-windows.exe.sha512.asc -2022/10/29 | 455 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512.asc -2022/10/29 | 43890 | systems/win32/miktex/tm/packages/next/miktex-gsf2pk-bin-x64-2.9.tar.lzma -2022/10/29 | 43618 | systems/win32/miktex/tm/packages/next/miktex-mthelp-bin-x64-2.9.tar.lzma -2022/10/29 | 43527 | systems/win32/miktex/tm/packages/next/miktex-zlib-bin-x64-2.9.tar.lzma -2022/10/29 | 41190 | systems/win32/miktex/tm/packages/next/miktex-upmendex-bin-x64.tar.lzma -2022/10/29 | 41179 | systems/win32/miktex/tm/packages/next/miktex-patgen-bin-x64.tar.lzma +2022/10/29 | 4436 | macros/generic/tracklang/CHANGES 2022/10/29 | 40 | macros/latex/contrib/debate/DEPENDS.txt 2022/10/29 | 402 | macros/latex/contrib/pdflscape/README.md -2022/10/29 | 4012177 | biblio/ctan-bibdata.zip -2022/10/29 | 394144 | systems/win32/miktex/tm/packages/next/miktex-cairo-bin-x64-2.9.tar.lzma -2022/10/29 | 37507 | systems/win32/miktex/tm/packages/next/miktex-posix-bin-x64-2.9.tar.lzma -2022/10/29 | 37051 | systems/win32/miktex/tm/packages/next/miktex-chktex-bin-x64-2.9.tar.lzma -2022/10/29 | 3620091 | biblio/ctan-bibdata/ctan.pdf -2022/10/29 | 35265 | systems/win32/miktex/tm/packages/next/miktex-axohelp-bin-x64-2.9.tar.lzma -2022/10/29 | 352464 | systems/win32/miktex/tm/packages/next/miktex-xetex-bin-x64-2.9.tar.lzma -2022/10/29 | 35232 | systems/win32/miktex/tm/packages/next/miktex-mspack-bin-x64-2.9.tar.lzma -2022/10/29 | 33863 | systems/win32/miktex/tm/packages/next/miktex-uriparser-bin-x64-2.9.tar.lzma +2022/10/29 | 3823 | macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf +2022/10/29 | 3823 | macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf +2022/10/29 | 376 | macros/generic/tracklang/samples/regions/sample-regions2-map3.tex +2022/10/29 | 359 | macros/generic/tracklang/samples/regions/sample-regions2-nomap.tex +2022/10/29 | 3560 | macros/generic/tracklang/samples/animals/sample-animals-poly.pdf +2022/10/29 | 3559 | macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf 2022/10/29 | 331210 | macros/latex/contrib/iexec.zip +2022/10/29 | 327 | macros/generic/tracklang/samples/animals/sample-animals-babel.tex 2022/10/29 | 326484 | macros/latex/contrib/iexec/iexec.pdf -2022/10/29 | 325981 | systems/win32/miktex/tm/packages/next/miktex-dvipdfmx-bin-x64-2.9.tar.lzma -2022/10/29 | 325485 | systems/win32/miktex/tm/packages/next/miktex-mo-bin-x64-2.9.tar.lzma 2022/10/29 | 323238 | macros/latex/contrib/pdflscape/pdflscape.pdf -2022/10/29 | 32074 | systems/win32/miktex/tm/packages/next/miktex-makeindex-bin-x64-2.9.tar.lzma 2022/10/29 | 319157 | macros/latex/contrib/pdflscape.zip -2022/10/29 | 31588 | systems/win32/miktex/tm/packages/next/miktex-autosp-bin-x64-2.9.tar.lzma -2022/10/29 | 31562 | systems/win32/miktex/tm/packages/next/miktex-bzip2-bin-x64-2.9.tar.lzma -2022/10/29 | 30571 | systems/win32/miktex/tm/packages/next/miktex-lacheck-bin-x64-2.9.tar.lzma +2022/10/29 | 313 | macros/generic/tracklang/samples/animals/animals2-en-GB.ldf +2022/10/29 | 310 | macros/generic/tracklang/samples/animals/animals2-en-US.ldf +2022/10/29 | 310371 | macros/generic/tracklang/tracklang.dtx 2022/10/29 | 30081 | macros/latex/contrib/huawei/huawei.dtx -2022/10/29 | 299974 | systems/win32/miktex/tm/packages/miktex-zzdb1-2.9.tar.lzma -2022/10/29 | 299960 | systems/win32/miktex/tm/packages/next/miktex-zzdb1-2.9.tar.lzma -2022/10/29 | 295946 | systems/win32/miktex/tm/packages/next/miktex-freetype2-bin-x64-2.9.tar.lzma 2022/10/29 | 289051 | macros/latex/contrib/debate/debate.pdf 2022/10/29 | 288816 | macros/latex/contrib/debate.zip -2022/10/29 | 286685 | systems/win32/miktex/tm/packages/next/miktex-metapost-bin-x64-2.9.tar.lzma -2022/10/29 | 28510 | systems/win32/miktex/tm/packages/next/miktex-findtexmf-bin-x64-2.9.tar.lzma -2022/10/29 | 2821672 | systems/win32/miktex/tm/packages/next/miktex-texworks-bin-x64-2.9.tar.lzma 2022/10/29 | 281867 | macros/latex/contrib/transparent/transparent.pdf 2022/10/29 | 278320 | macros/latex/contrib/transparent.zip -2022/10/29 | 27464 | systems/win32/miktex/tm/packages/next/miktex-teckit-bin-x64-2.9.tar.lzma -2022/10/29 | 2742861 | biblio/ctan-bibdata/ctan.bib +2022/10/29 | 27666 | macros/generic/tracklang/samples/regions/sample-regions2-map.pdf +2022/10/29 | 27515 | macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf 2022/10/29 | 272228 | macros/latex/contrib/association-matrix.zip -2022/10/29 | 270466 | systems/win32/miktex/tm/packages/next/miktex-console-bin-x64-2.9.tar.lzma +2022/10/29 | 271 | macros/generic/tracklang/samples/animals/sample-animals2.tex +2022/10/29 | 27134 | macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf +2022/10/29 | 26590 | macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf 2022/10/29 | 264256 | macros/latex/contrib/association-matrix/association-matrix.pdf -2022/10/29 | 2628 | macros/latex/contrib/eolang/eolang.ins 2022/10/29 | 2628 | macros/latex/contrib/debate/debate.ins 2022/10/29 | 2626 | macros/latex/contrib/huawei/huawei.ins 2022/10/29 | 2625 | macros/latex/contrib/iexec/iexec.ins -2022/10/29 | 25518566 | systems/texlive/tlnet/install-tl.zip +2022/10/29 | 257 | macros/generic/tracklang/samples/regions/sample-regions.tex 2022/10/29 | 253724 | macros/latex/contrib/huawei/huawei-cover-picture.pdf -2022/10/29 | 25212 | macros/latex/contrib/eolang/eolang.dtx -2022/10/29 | 25119 | systems/win32/miktex/tm/packages/next/miktex-fribidixetex-bin-x64-2.9.tar.lzma -2022/10/29 | 247207 | systems/win32/miktex/tm/packages/next/miktex-hitex-bin-x64.tar.lzma -2022/10/29 | 245152 | systems/win32/miktex/tm/packages/next/miktex-pmx-bin-x64-2.9.tar.lzma -2022/10/29 | 2422448 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz -2022/10/29 | 24212 | systems/win32/miktex/tm/packages/next/miktex-devnag-bin-x64-2.9.tar.lzma -2022/10/29 | 23950 | systems/win32/miktex/tm/packages/next/miktex-popt-bin-x64-2.9.tar.lzma +2022/10/29 | 249 | macros/generic/tracklang/samples/animals/animals-english.ldf +2022/10/29 | 249 | macros/generic/tracklang/samples/animals/animals2-english.ldf +2022/10/29 | 246 | macros/generic/tracklang/samples/animals/animals-german.ldf +2022/10/29 | 246 | macros/generic/tracklang/samples/animals/animals2-german.ldf +2022/10/29 | 23587 | macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf 2022/10/29 | 23435 | macros/latex/contrib/pdflscape/pdflscape.dtx -2022/10/29 | 213847 | systems/win32/miktex/tm/packages/next/miktex-omegaware-bin-x64-2.9.tar.lzma -2022/10/29 | 209139 | systems/win32/miktex/tm/packages/next/miktex-metafont-bin-x64-2.9.tar.lzma +2022/10/29 | 232 | macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex +2022/10/29 | 226 | macros/generic/tracklang/samples/regions/regions-IM.ldf +2022/10/29 | 223 | macros/generic/tracklang/samples/animals/sample-animals.tex +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-US.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-GB.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-CA.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/regions/regions-BE.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/animals/animals-en-US.ldf +2022/10/29 | 221 | macros/generic/tracklang/samples/animals/animals-en-GB.ldf +2022/10/29 | 215 | macros/generic/tracklang/samples/animals/sample-animals2-poly.tex +2022/10/29 | 214 | macros/generic/tracklang/samples/animals/sample-animals-poly.tex +2022/10/29 | 210917 | macros/generic/tracklang/tracklang-manual.tex +2022/10/29 | 20758 | macros/generic/tracklang/samples/sample-tracklang3.pdf +2022/10/29 | 20747 | macros/generic/tracklang/samples/sample-tracklang2.pdf 2022/10/29 | 2067085 | systems/doc/luatex.zip -2022/10/29 | 20435279 | systems/texlive/tlnet/install-tl-windows.exe -2022/10/29 | 203420 | systems/win32/miktex/tm/packages/next/miktex-pixman-bin-x64-2.9.tar.lzma -2022/10/29 | 2023134 | systems/win32/miktex/tm/packages/next/miktex-luatex-bin-x64-2.9.tar.lzma -2022/10/29 | 196213 | systems/win32/miktex/tm/packages/next/miktex-curl-bin-x64-2.9.tar.lzma +2022/10/29 | 20388 | macros/generic/tracklang/samples/sample-tracklang.pdf +2022/10/29 | 19898 | macros/generic/tracklang/samples/sample-tracklang6.pdf +2022/10/29 | 194 | macros/generic/tracklang/samples/animals/sample-animals2-de4.tex +2022/10/29 | 1943892 | install/macros/generic/tracklang.tds.zip +2022/10/29 | 193 | macros/generic/tracklang/samples/regions/regions-manx.ldf 2022/10/29 | 19039 | macros/latex/contrib/association-matrix/LICENCE 2022/10/29 | 1903744 | systems/texlive/tlnet/archive/luatex.doc.r64839.tar.xz -2022/10/29 | 18511 | systems/win32/miktex/tm/packages/next/miktex-tex2xindy-bin-x64-2.9.tar.lzma -2022/10/29 | 18382 | systems/win32/miktex/tm/packages/next/miktex-kpathsea-bin-x64-2.9.tar.lzma -2022/10/29 | 181724 | systems/win32/miktex/tm/packages/next/miktex-mpfr-bin-x64-2.9.tar.lzma -2022/10/29 | 17795535 | systems/texlive/tlnet/tlpkg/texlive.tlpdb +2022/10/29 | 186 | macros/generic/tracklang/samples/regions/sample-regions2.tex +2022/10/29 | 178 | macros/generic/tracklang/samples/animals/sample-animals2-de3.tex +2022/10/29 | 17857 | macros/generic/tracklang/samples/sample-tracklang5.pdf 2022/10/29 | 17543 | macros/latex/contrib/transparent/transparent.dtx -2022/10/29 | 173177 | systems/win32/miktex/tm/packages/next/miktex-tex-bin-x64-2.9.tar.lzma -2022/10/29 | 169679 | systems/win32/miktex/tm/packages/next/miktex-hunspell-bin-x64-2.9.tar.lzma -2022/10/29 | 1678 | biblio/ctan-bibdata/biblatex-ctan/ctan.bbx +2022/10/29 | 173 | macros/generic/tracklang/samples/animals/sample-animals2-de.tex +2022/10/29 | 172 | macros/generic/tracklang/samples/animals/sample-animals-de.tex +2022/10/29 | 171 | macros/generic/tracklang/samples/regions/regions-german.ldf +2022/10/29 | 166 | macros/generic/tracklang/samples/animals/sample-animals2-de2.tex +2022/10/29 | 165 | macros/generic/tracklang/samples/regions/regions-dutch.ldf +2022/10/29 | 164 | macros/generic/tracklang/samples/regions/regions-french.ldf +2022/10/29 | 164 | macros/generic/tracklang/samples/regions/regions-english.ldf 2022/10/29 | 16338 | macros/latex/contrib/association-matrix/association-matrix.tex -2022/10/29 | 155431 | systems/win32/miktex/tm/packages/next/miktex-fontconfig-bin-x64-2.9.tar.lzma -2022/10/29 | 153 | systems/texlive/tlnet/install-tl-windows.exe.sha512 -2022/10/29 | 152 | systems/texlive/tlnet/install-tl-unx.tar.gz.sha512 +2022/10/29 | 158 | macros/generic/tracklang/samples/regions/sample-regions2-manx.tex +2022/10/29 | 15690 | macros/generic/tracklang/samples/animals/sample-animals-babel.pdf +2022/10/29 | 15551 | macros/generic/tracklang/samples/regions/sample-regions2.pdf +2022/10/29 | 1554 | macros/generic/tracklang/tracklang.ins +2022/10/29 | 153 | macros/generic/tracklang/samples/regions/regions-italian.ldf 2022/10/29 | 1513 | macros/latex/contrib/huawei/README.md 2022/10/29 | 1512 | macros/latex/contrib/iexec/README.md 2022/10/29 | 15116 | macros/latex/contrib/iexec/iexec.dtx -2022/10/29 | 1507333 | systems/win32/miktex/tm/packages/miktex-zzdb2-2.9.tar.lzma -2022/10/29 | 1506393 | systems/win32/miktex/tm/packages/next/miktex-zzdb2-2.9.tar.lzma -2022/10/29 | 1503054 | systems/win32/miktex/tm/packages/next/miktex-runtime-bin-x64-2.9.tar.lzma -2022/10/29 | 146 | macros/latex/contrib/eolang/DEPENDS.txt -2022/10/29 | 145 | systems/texlive/tlnet/install-tl.zip.sha512 -2022/10/29 | 1458151 | systems/win32/miktex/tm/packages/next/miktex-dvisvgm-bin-x64-2.9.tar.lzma -2022/10/29 | 144 | systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 -2022/10/29 | 14434 | systems/win32/miktex/tm/packages/next/miktex-zzip-bin-x64-2.9.tar.lzma +2022/10/29 | 1459 | macros/generic/tracklang/samples/sample-tracklang3.tex +2022/10/29 | 1454 | macros/generic/tracklang/samples/sample-tracklang.tex +2022/10/29 | 1454 | macros/generic/tracklang/samples/sample-tracklang2.tex +2022/10/29 | 14463 | macros/generic/tracklang/samples/animals/sample-animals-de.pdf +2022/10/29 | 14463 | macros/generic/tracklang/samples/animals/sample-animals2-de.pdf +2022/10/29 | 14463 | macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf +2022/10/29 | 14444 | macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf 2022/10/29 | 14366 | macros/latex/contrib/association-matrix/association-matrix.sty -2022/10/29 | 140012 | systems/win32/miktex/tm/packages/next/miktex-mktex-bin-x64-2.9.tar.lzma -2022/10/29 | 1385541 | systems/win32/miktex/tm/packages/next/miktex-zzdb3-2.9.tar.lzma -2022/10/29 | 1384033 | systems/win32/miktex/tm/packages/miktex-zzdb3-2.9.tar.lzma -2022/10/29 | 135465 | systems/win32/miktex/tm/packages/next/miktex-dvips-bin-x64-2.9.tar.lzma -2022/10/29 | 1352 | macros/latex/contrib/eolang/README.md -2022/10/29 | 1323743 | systems/win32/miktex/tm/packages/next/miktex-poppler-bin-x64-2.9.tar.lzma +2022/10/29 | 13996 | macros/generic/tracklang/samples/regions/sample-regions.pdf +2022/10/29 | 13489 | macros/generic/tracklang/samples/animals/sample-animals.pdf +2022/10/29 | 13489 | macros/generic/tracklang/samples/animals/sample-animals2.pdf 2022/10/29 | 12832 | systems/texlive/tlnet/archive/luatex.r64839.tar.xz 2022/10/29 | 1272 | macros/latex/contrib/debate/README.md 2022/10/29 | 12292663 | macros/latex/contrib/jeuxcartes.zip -2022/10/29 | 1172 | systems/win32/miktex/tm/packages/next/pr.ini -2022/10/29 | 1161751 | systems/win32/miktex/tm/packages/next/miktex-asymptote-bin-x64-2.9.tar.lzma -2022/10/29 | 115581 | systems/win32/miktex/tm/packages/next/miktex-gregorio-bin-x64-2.9.tar.lzma -2022/10/29 | 112979 | systems/win32/miktex/tm/packages/next/miktex-epstopdf-bin-x64-2.9.tar.lzma -2022/10/29 | 112879 | systems/win32/miktex/tm/packages/next/miktex-gd-bin-x64-2.9.tar.lzma -2022/10/29 | 109650 | systems/win32/miktex/tm/packages/next/miktex-jpeg-bin-x64-2.9.tar.lzma +2022/10/29 | 1124 | macros/generic/tracklang/samples/regions/regions2.sty 2022/10/29 | 1083 | macros/latex/contrib/iexec/LICENSE.txt 2022/10/29 | 1083 | macros/latex/contrib/huawei/LICENSE.txt -2022/10/29 | 1083 | macros/latex/contrib/eolang/LICENSE.txt 2022/10/29 | 1083 | macros/latex/contrib/debate/LICENSE.txt -2022/10/29 | 107438 | systems/win32/miktex/tm/packages/next/miktex-texware-bin-x64-2.9.tar.lzma -2022/10/29 | 104921 | systems/win32/miktex/tm/packages/next/miktex-mfware-bin-x64-2.9.tar.lzma 2022/10/29 | 1046327 | macros/latex/contrib/huawei.zip -2022/10/29 | 103597 | systems/win32/miktex/tm/packages/next/miktex-lua53-bin-x64-2.9.tar.lzma -2022/10/29 | 103246 | systems/win32/miktex/tm/packages/next/miktex-cweb-bin-x64-2.9.tar.lzma +2022/10/29 | 1041 | macros/generic/tracklang/samples/sample-tracklang6.tex +2022/10/29 | 1023122 | macros/generic/tracklang/tracklang-manual.html 2022/10/28 | 98590 | systems/doc/luatex/luatex-tex.tex 2022/10/28 | 944948 | systems/texlive/tlnet/archive/tex4ht.r64837.tar.xz 2022/10/28 | 9148 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-10T.png 2022/10/28 | 894360 | systems/texlive/tlnet/archive/beebe.r64816.tar.xz 2022/10/28 | 889172 | systems/texlive/tlnet/archive/l3backend.doc.r64836.tar.xz -2022/10/28 | 875488 | systems/texlive/tlnet/archive/eolang.doc.r64834.tar.xz 2022/10/28 | 8656 | systems/texlive/tlnet/archive/tikzmark.r64819.tar.xz 2022/10/28 | 8337 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-10P.png 2022/10/28 | 8152 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-8T.png 2022/10/28 | 8140 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-9T.png -2022/10/28 | 8008 | systems/texlive/tlnet/archive/eolang.source.r64834.tar.xz 2022/10/28 | 795249 | install/fonts/accanthis.tds.zip 2022/10/28 | 787 | macros/latex/contrib/fixdif/README.md 2022/10/28 | 785161 | fonts/accanthis.zip @@ -239,14 +548,12 @@ 2022/10/28 | 5583 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-3T.png 2022/10/28 | 5569 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-4T.png 2022/10/28 | 5519 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-5P.png -2022/10/28 | 5509864 | systems/texlive/tlnet/archive/jeuxcartes.doc.r64827.tar.xz 2022/10/28 | 55076 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-CC.png 2022/10/28 | 55019 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-CK.png 2022/10/28 | 55004 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-11AT.png 2022/10/28 | 54608 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-1AT.png 2022/10/28 | 54000 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-RC.png 2022/10/28 | 53517 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-VT.png -2022/10/28 | 5328884 | systems/texlive/tlnet/archive/jeuxcartes.r64827.tar.xz 2022/10/28 | 52917 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-14AT.png 2022/10/28 | 5270 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-7C.png 2022/10/28 | 52460 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-DP.png @@ -272,9 +579,7 @@ 2022/10/28 | 4369 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-3K.png 2022/10/28 | 4293 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-4C.png 2022/10/28 | 4236 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-4K.png -2022/10/28 | 422980 | systems/texlive/tlnet/archive/texlive-scripts.doc.r64830.tar.xz 2022/10/28 | 3982 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-2C.png -2022/10/28 | 3900 | systems/texlive/tlnet/archive/eolang.r64834.tar.xz 2022/10/28 | 3885 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-2K.png 2022/10/28 | 3880 | macros/latex/contrib/jeuxcartes/tex/CaJ-Tarot-AT.png 2022/10/28 | 37180 | systems/texlive/tlnet/archive/spath3.source.r64818.tar.xz @@ -321,7 +626,6 @@ 2022/10/28 | 2585 | fonts/gillius/latex/gillius2.sty 2022/10/28 | 2574 | fonts/simpleicons/enc/simpleiconsNine.enc 2022/10/28 | 25683 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-P4.png -2022/10/28 | 2559 | fonts/gillius/latex/gillius.sty 2022/10/28 | 25529 | macros/latex/contrib/jeuxcartes/tex/Caj-Uno-PTB.png 2022/10/28 | 25528 | systems/texlive/tlnet/archive/spath3.r64818.tar.xz 2022/10/28 | 254 | fonts/simpleicons/tex/usimpleiconsTwo.fd @@ -364,7 +668,6 @@ 2022/10/28 | 1809 | fonts/poiretone/latex/PoiretOne.sty 2022/10/28 | 18077 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-3V.png 2022/10/28 | 18072 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-2B.png -2022/10/28 | 1804 | fonts/gillius/README 2022/10/28 | 17926 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-5B.png 2022/10/28 | 17900 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-8B.png 2022/10/28 | 1786441 | systems/doc/luatex/luatex.pdf @@ -380,13 +683,11 @@ 2022/10/28 | 17298 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-9R.png 2022/10/28 | 17243 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-6R.png 2022/10/28 | 17239 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-7V.png -2022/10/28 | 1721197 | install/fonts/gillius.tds.zip 2022/10/28 | 17202 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-0J.png 2022/10/28 | 17086 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-7R.png 2022/10/28 | 17003 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-9B.png 2022/10/28 | 16962 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-4V.png 2022/10/28 | 16961 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-6B.png -2022/10/28 | 1692245 | fonts/gillius.zip 2022/10/28 | 16867 | macros/latex/contrib/fixdif/fixdif-zh-cn.tex 2022/10/28 | 16737 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-4R.png 2022/10/28 | 16733 | macros/latex/contrib/jeuxcartes/tex/CaJ-Uno-2J.png @@ -432,13 +733,11 @@ 2022/10/28 | 119992 | systems/texlive/tlnet/archive/polyglossia.r64826.tar.xz 2022/10/28 | 11952152 | systems/texlive/tlnet/archive/l3kernel.doc.r64836.tar.xz 2022/10/28 | 11746 | macros/latex/contrib/hep-reference/hep-reference-implementation.dtx -2022/10/28 | 113728 | systems/texlive/tlnet/archive/texlive-scripts.r64830.tar.xz 2022/10/28 | 1119 | fonts/simpleicons/map/simpleicons.map 2022/10/28 | 10888 | systems/texlive/tlnet/archive/frenchmath.source.r64823.tar.xz 2022/10/28 | 1036 | macros/latex/contrib/hep-reference/README.md 2022/10/27 | 97443 | macros/latex/contrib/fixdif/fixdif.pdf 2022/10/27 | 934063 | macros/latex/contrib/l3backend.zip -2022/10/27 | 7528 | systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl 2022/10/27 | 619023 | support/TeX4ht/source/tex4ht-html4.tex 2022/10/27 | 268342 | macros/latex/contrib/fixdif.zip 2022/10/27 | 23405 | macros/latex/contrib/fixdif/fixdif.dtx @@ -497,7 +796,6 @@ 2022/10/26 | 56004 | systems/texlive/tlnet/archive/penlight.doc.r64811.tar.xz 2022/10/26 | 557987 | macros/latex/contrib/l3kernel/l3doc.pdf 2022/10/26 | 555 | macros/latex/contrib/filehook/README.txt -2022/10/26 | 5548 | systems/texlive/tlnet/archive/iexec.source.r64810.tar.xz 2022/10/26 | 549 | macros/latex/contrib/l3backend/README.md 2022/10/26 | 5429 | macros/latex/contrib/l3kernel/l3news04.tex 2022/10/26 | 537655 | graphics/pgf/contrib/tikzmark.zip @@ -531,7 +829,6 @@ 2022/10/26 | 341266 | macros/latex/contrib/docshots.zip 2022/10/26 | 338306 | macros/latex/contrib/docshots/docshots.pdf 2022/10/26 | 33655 | macros/latex/contrib/l3kernel/l3sys.dtx -2022/10/26 | 325748 | systems/texlive/tlnet/archive/iexec.doc.r64810.tar.xz 2022/10/26 | 32429 | macros/latex/contrib/l3kernel/l3cctab.dtx 2022/10/26 | 322581 | macros/latex/contrib/filehook.zip 2022/10/26 | 316022 | macros/latex/contrib/filehook/filehook.pdf @@ -551,7 +848,6 @@ 2022/10/26 | 24841 | macros/latex/contrib/l3kernel/source3body.tex 2022/10/26 | 24673 | macros/latex/contrib/l3kernel/l3kernel-functions.dtx 2022/10/26 | 242838 | macros/latex/contrib/l3kernel/l3syntax-changes.pdf -2022/10/26 | 2412 | systems/texlive/tlnet/archive/iexec.r64810.tar.xz 2022/10/26 | 2390 | macros/latex/contrib/l3kernel/l3docstrip.dtx 2022/10/26 | 23866 | macros/latex/contrib/l3kernel/l3luatex.dtx 2022/10/26 | 235708 | macros/latex/contrib/newverbs.zip @@ -639,168 +935,39 @@ 2022/10/25 | 1043 | macros/latex/contrib/frenchmath/README.md 2022/10/25 | 1017204 | systems/texlive/tlnet/archive/bithesis.doc.r64804.tar.xz 2022/10/24 | 998 | macros/latex/contrib/biblatex-contrib/biblatex-publist/publist.dbx -2022/10/24 | 9920 | systems/texlive/tlnet/archive/chktex.r64797.tar.xz 2022/10/24 | 9639 | info/biblio/tugboat.def 2022/10/24 | 917348 | macros/latex/contrib/achemso.zip -2022/10/24 | 896 | macros/generic/lt3luabridge/README.md -2022/10/24 | 8892 | systems/texlive/tlnet/archive/unigrazpub.source.r64797.tar.xz -2022/10/24 | 87896 | systems/texlive/tlnet/archive/pstricks.r64797.tar.xz -2022/10/24 | 8752 | systems/texlive/tlnet/archive/sty2dtx.r64797.tar.xz 2022/10/24 | 8724 | macros/latex/contrib/biblatex-contrib/biblatex-publist/README -2022/10/24 | 871804 | systems/texlive/tlnet/archive/babel.doc.r64797.tar.xz 2022/10/24 | 863 | macros/latex/contrib/se2thesis/README.md 2022/10/24 | 85675 | macros/latex/contrib/se2thesis/se2thesis.dtx -2022/10/24 | 7872 | systems/texlive/tlnet/archive/piton.r64797.tar.xz -2022/10/24 | 7596068 | systems/texlive/tlnet/archive/pstricks.doc.r64797.tar.xz -2022/10/24 | 716104 | systems/texlive/tlnet/archive/babel.source.r64797.tar.xz 2022/10/24 | 7083 | macros/latex/contrib/achemso/achemso.ins -2022/10/24 | 65640 | systems/texlive/tlnet/archive/siunitx.r64797.tar.xz -2022/10/24 | 64580 | systems/texlive/tlnet/archive/njuthesis.source.r64797.tar.xz 2022/10/24 | 63183 | macros/latex/contrib/biblatex-contrib/biblatex-publist/publist.bbx 2022/10/24 | 60358 | macros/latex/contrib/biblatex-contrib/biblatex-publist/biblatex-publist.tex -2022/10/24 | 5952 | systems/texlive/tlnet/archive/unigrazpub.r64797.tar.xz 2022/10/24 | 59499 | macros/luatex/generic/penlight/penlight.pdf -2022/10/24 | 529764 | systems/texlive/tlnet/archive/tikz-ext.doc.r64797.tar.xz 2022/10/24 | 525672 | macros/latex/contrib/achemso/achemso.pdf 2022/10/24 | 5245 | macros/latex/contrib/achemso/achemso-demo.bib -2022/10/24 | 494475 | macros/generic/lt3luabridge/lt3luabridge.pdf 2022/10/24 | 492236 | macros/generic/lt3luabridge.zip 2022/10/24 | 464 | macros/latex/contrib/achemso/LICENSE.md -2022/10/24 | 440628 | systems/texlive/tlnet/archive/jobname-suffix.doc.r64797.tar.xz 2022/10/24 | 439729 | macros/latex/contrib/biblatex-contrib/biblatex-publist.zip -2022/10/24 | 425796 | systems/texlive/tlnet/archive/chktex.doc.r64797.tar.xz 2022/10/24 | 425636 | macros/luatex/generic/penlight/penlight.lua 2022/10/24 | 407139 | macros/latex/contrib/biblatex-contrib/biblatex-publist/biblatex-publist.pdf -2022/10/24 | 397012 | systems/texlive/tlnet/archive/piton.doc.r64797.tar.xz 2022/10/24 | 3842964 | info/biblio/tugboat.bib 2022/10/24 | 382966 | macros/latex/contrib/achemso/achemso-demo.pdf -2022/10/24 | 3720 | macros/unicodetex/latex/bithesis/bithesis.ins 2022/10/24 | 365712 | macros/latex/contrib/se2thesis/se2thesis.pdf 2022/10/24 | 3582 | info/biblio/tugboat.ltx 2022/10/24 | 3478 | macros/latex/contrib/biblatex-contrib/biblatex-publist/publist.cbx 2022/10/24 | 3340 | macros/luatex/generic/penlight/penlight.sty -2022/10/24 | 30484 | systems/texlive/tlnet/archive/srdp-mathematik.r64797.tar.xz -2022/10/24 | 2643 | macros/unicodetex/latex/bithesis/contributing-zh.md 2022/10/24 | 25612 | macros/luatex/generic/penlight/penlightextras.lua -2022/10/24 | 253 | macros/generic/lt3luabridge/lt3luabridge.ins 2022/10/24 | 2466 | macros/latex/contrib/se2thesis/se2thesis.ins -2022/10/24 | 23540 | systems/texlive/tlnet/archive/tikz-ext.r64797.tar.xz -2022/10/24 | 2352976 | systems/texlive/tlnet/archive/wargame.doc.r64797.tar.xz -2022/10/24 | 2332 | macros/unicodetex/latex/bithesis/contributing.md -2022/10/24 | 217 | macros/generic/lt3luabridge/example.latex -2022/10/24 | 1993 | macros/unicodetex/latex/bithesis/README.md -2022/10/24 | 194220 | systems/texlive/tlnet/archive/wargame.r64797.tar.xz -2022/10/24 | 19416 | systems/texlive/tlnet/archive/njuthesis.r64797.tar.xz -2022/10/24 | 192812 | systems/texlive/tlnet/archive/babel.r64797.tar.xz -2022/10/24 | 192811 | macros/unicodetex/latex/bithesis/bithesis.dtx 2022/10/24 | 19209 | macros/latex/contrib/achemso/CHANGELOG.md -2022/10/24 | 19105 | macros/generic/lt3luabridge/LICENSE -2022/10/24 | 184132 | systems/texlive/tlnet/archive/sty2dtx.doc.r64797.tar.xz -2022/10/24 | 181 | macros/generic/lt3luabridge/example.context -2022/10/24 | 1756 | systems/texlive/tlnet/archive/jobname-suffix.r64797.tar.xz 2022/10/24 | 1732 | macros/latex/contrib/se2thesis/se2thesis-master-thesis-example.tex -2022/10/24 | 167 | macros/generic/lt3luabridge/example.plaintex 2022/10/24 | 16202 | macros/latex/contrib/achemso/achemso-demo.tex -2022/10/24 | 16016 | systems/texlive/tlnet/archive/piton.source.r64797.tar.xz -2022/10/24 | 153572 | systems/texlive/tlnet/archive/wargame.source.r64797.tar.xz -2022/10/24 | 150860 | systems/texlive/tlnet/archive/srdp-mathematik.doc.r64797.tar.xz 2022/10/24 | 149476 | macros/latex/contrib/achemso/achemso.dtx 2022/10/24 | 1459228 | install/macros/latex/contrib/se2thesis.tds.zip 2022/10/24 | 1446588 | macros/latex/contrib/se2thesis.zip -2022/10/24 | 14380 | macros/generic/lt3luabridge/lt3luabridge.dtx -2022/10/24 | 1389 | macros/generic/lt3luabridge/docstrip.cfg -2022/10/24 | 134736 | systems/texlive/tlnet/archive/unigrazpub.doc.r64797.tar.xz 2022/10/24 | 1333 | macros/latex/contrib/achemso/README.md 2022/10/24 | 1296 | macros/luatex/generic/penlight/README.md -2022/10/24 | 1242984 | systems/texlive/tlnet/archive/siunitx.doc.r64797.tar.xz -2022/10/24 | 1189824 | systems/texlive/tlnet/archive/njuthesis.doc.r64797.tar.xz -2022/10/24 | 116788 | systems/texlive/tlnet/archive/siunitx.source.r64797.tar.xz 2022/10/24 | 1122920 | macros/latex/contrib/se2thesis/se2thesis-master-thesis-example.pdf -2022/10/24 | 1061972 | macros/unicodetex/latex/bithesis.zip 2022/10/24 | 1036 | macros/latex/contrib/se2thesis/CHANGELOG.md -2022/10/24 | 1033346 | macros/unicodetex/latex/bithesis/bithesis.pdf 2022/10/24 | 10321 | macros/luatex/generic/penlight/penlight.tex 2022/10/24 | 1027407 | install/macros/latex/contrib/achemso.tds.zip -2022/10/23 | 996 | macros/latex/contrib/siunitx/README.md -2022/10/23 | 9912 | macros/latex/contrib/siunitx/siunitx-symbol.dtx -2022/10/23 | 986 | macros/latex/contrib/srdp-mathematik/README.md -2022/10/23 | 971 | graphics/pgf/contrib/tikz-ext/README.md -2022/10/23 | 96716 | systems/texlive/tlnet/archive/pangram.doc.r64783.tar.xz -2022/10/23 | 93124 | graphics/pstricks/base/doc/pst-news22.pdf -2022/10/23 | 926456 | systems/texlive/tlnet/archive/chemobabel.doc.r64778.tar.xz -2022/10/23 | 9188 | systems/texlive/tlnet/archive/ucharclasses.r64782.tar.xz -2022/10/23 | 9091 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual-en-library-paths.ortho.tex -2022/10/23 | 885304 | macros/latex/required/babel/base/babel.pdf -2022/10/23 | 8798 | macros/latex/contrib/siunitx/siunitx-command.dtx -2022/10/23 | 86196 | systems/texlive/tlnet/archive/lutabulartools.doc.r64780.tar.xz -2022/10/23 | 839829 | macros/latex/required/babel/base/locale.zip -2022/10/23 | 8205 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual-en-main-body.tex -2022/10/23 | 8106386 | graphics/pstricks/base.zip -2022/10/23 | 8045 | graphics/pstricks/base/latex/pstricks.sty -2022/10/23 | 78837 | macros/latex/contrib/srdp-mathematik/srdp-mathematik.sty -2022/10/23 | 7869 | macros/latex/required/babel/base/babel.ins -2022/10/23 | 748005 | macros/latex/required/babel/base/babel.dtx -2022/10/23 | 6956 | systems/texlive/tlnet/archive/lutabulartools.r64780.tar.xz -2022/10/23 | 69555 | macros/luatex/latex/piton/piton.dtx -2022/10/23 | 69530 | macros/latex/contrib/siunitx/CHANGELOG.md -2022/10/23 | 6801 | support/TeX4ht/source/tex4ht-mathjax.tex -2022/10/23 | 6792 | systems/texlive/tlnet/archive/collection-latexextra.r64783.tar.xz -2022/10/23 | 666267 | macros/latex/contrib/siunitx/siunitx.pdf -2022/10/23 | 617655 | macros/latex/contrib/siunitx/siunitx-code.pdf -2022/10/23 | 614033 | graphics/pgf/contrib/tikz-ext.zip -2022/10/23 | 574442 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual.pdf -2022/10/23 | 5481 | macros/latex/contrib/siunitx/siunitx-locale.dtx -2022/10/23 | 50961 | macros/latex/contrib/siunitx/siunitx-table.dtx -2022/10/23 | 48433 | macros/latex/contrib/srdp-mathematik/srdp-mathematik.tex -2022/10/23 | 4764 | systems/texlive/tlnet/archive/pangram.source.r64783.tar.xz -2022/10/23 | 476329 | macros/luatex/latex/piton.zip -2022/10/23 | 4748 | macros/latex/contrib/siunitx/siunitx-abbreviations.cfg -2022/10/23 | 4603 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual-en-pgf-shapes-uncentered.tex -2022/10/23 | 4496 | systems/texlive/tlnet/archive/chemobabel.r64778.tar.xz -2022/10/23 | 4072 | graphics/pgf/contrib/tikz-ext/tex/generic/tikz-ext/pgfkeyslibraryext.pgfkeys-plus.code.tex -2022/10/23 | 407293 | macros/luatex/latex/piton/piton.pdf -2022/10/23 | 3948 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual-en-library-paths.arcto.tex -2022/10/23 | 3912 | graphics/pstricks/base/Changes -2022/10/23 | 38097 | macros/latex/contrib/siunitx/siunitx-complex.dtx -2022/10/23 | 3687 | macros/latex/contrib/siunitx/siunitx.ins -2022/10/23 | 35916 | macros/latex/contrib/siunitx/siunitx-print.dtx -2022/10/23 | 3526 | macros/latex/required/babel/base/bbidxglo.dtx -2022/10/23 | 33799 | macros/latex/contrib/siunitx/siunitx-compound.dtx -2022/10/23 | 32418 | macros/latex/contrib/siunitx/siunitx-emulation.dtx -2022/10/23 | 31738 | macros/latex/contrib/siunitx/siunitx-version-1.cfg -2022/10/23 | 3094 | macros/unicodetex/latex/njuthesis/njuthesis.ins -2022/10/23 | 3018925 | install/macros/latex/required/babel-base.tds.zip -2022/10/23 | 298140 | macros/unicodetex/latex/njuthesis/njuthesis.dtx -2022/10/23 | 2883 | macros/latex/contrib/siunitx/siunitx-binary.dtx -2022/10/23 | 27754 | macros/luatex/latex/piton/piton-french.tex -2022/10/23 | 273398 | macros/latex/contrib/siunitx/siunitx-v2.sty -2022/10/23 | 2620 | macros/latex/contrib/siunitx/siunitx-code.tex -2022/10/23 | 2331 | graphics/pstricks/base/doc/pst-news22.tex -2022/10/23 | 2277 | macros/latex/required/babel/base/README.md -2022/10/23 | 21890 | macros/latex/required/babel/base/bbcompat.dtx -2022/10/23 | 217579 | macros/luatex/latex/piton/piton-french.pdf -2022/10/23 | 21683 | macros/latex/contrib/siunitx/siunitx.dtx -2022/10/23 | 1922922 | macros/latex/required/babel/base.zip -2022/10/23 | 1920 | systems/texlive/tlnet/archive/pangram.r64783.tar.xz -2022/10/23 | 19105 | macros/unicodetex/latex/njuthesis/LICENSE -2022/10/23 | 190706 | macros/latex/contrib/srdp-mathematik.zip -2022/10/23 | 180259 | macros/latex/contrib/srdp-mathematik/srdp-mathematik.pdf -2022/10/23 | 1729 | macros/latex/contrib/siunitx/siunitx-binary.cfg -2022/10/23 | 16709 | macros/latex/contrib/siunitx/siunitx-angle.dtx -2022/10/23 | 16168 | systems/texlive/tlnet/archive/chemobabel.source.r64778.tar.xz -2022/10/23 | 158763 | macros/latex/contrib/siunitx/siunitx.tex -2022/10/23 | 15611 | macros/latex/contrib/siunitx/siunitx-quantity.dtx -2022/10/23 | 1514332 | install/macros/latex/contrib/siunitx.tds.zip -2022/10/23 | 15025 | graphics/pgf/contrib/tikz-ext/tex/generic/tikz-ext/pgfcalendar-ext.code.tex -2022/10/23 | 14799 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual.bib -2022/10/23 | 147297 | macros/latex/contrib/siunitx/siunitx-number.dtx -2022/10/23 | 1470100 | macros/latex/contrib/siunitx.zip -2022/10/23 | 143504 | systems/texlive/tlnet/archive/ucharclasses.doc.r64782.tar.xz -2022/10/23 | 13056 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual-en-main-preamble.tex -2022/10/23 | 1266830 | macros/unicodetex/latex/njuthesis.zip -2022/10/23 | 125369 | graphics/pstricks/base/generic/pstricks.tex -2022/10/23 | 1200264 | macros/unicodetex/latex/njuthesis/njuthesis.pdf -2022/10/23 | 11063 | graphics/pgf/contrib/tikz-ext/doc/tikz-ext-manual-en-library-misc.tex -2022/10/23 | 10812 | macros/latex/contrib/siunitx/siunitx-abbreviation.dtx -2022/10/23 | 1077 | macros/unicodetex/latex/njuthesis/README.md -2022/10/23 | 103909 | macros/latex/contrib/siunitx/siunitx-unit.dtx diff --git a/biblio/ctan-bibdata/ctan.bib b/biblio/ctan-bibdata/ctan.bib index c0c66d43ab..b2aa822c93 100644 --- a/biblio/ctan-bibdata/ctan.bib +++ b/biblio/ctan-bibdata/ctan.bib @@ -1,7 +1,7 @@ %% bib file of all CTAN packages %% (C) Herbert Voß %% -%% created at 30-10-2022, 02:01:07 +%% created at 31-10-2022, 02:01:30 %% %% This file is provided under the terms of the LPPL v1.3 or @@ -7158,8 +7158,8 @@ title = {The \texttt{biblatex-caspervector} package}, subtitle = {A simple citation style for Chinese users}, author = {Casper Ti. Vector}, - date = {2020-11-02}, - version = {0.3.5}, + date = {2022-10-30}, + version = {0.3.6}, license = {lppl1.3}, mirror = {https://mirror.ctan.org/macros/latex/contrib/biblatex-contrib/biblatex-caspervector}, url = {https://ctan.org/pkg/biblatex-caspervector}, @@ -8636,8 +8636,8 @@ title = {The \texttt{bithesis} package}, subtitle = {Templates for the Beijing Institute of Technology}, author = {Feng Kaiyu}, - date = {2022-10-24}, - version = {3.1.0}, + date = {2022-10-30}, + version = {3.1.1}, license = {lppl1.3c}, mirror = {https://mirror.ctan.org/macros/unicodetex/latex/bithesis}, url = {https://ctan.org/pkg/bithesis}, @@ -9040,12 +9040,12 @@ subtitle = {Draw Bode, Nyquist and Nichols plots with gnuplot or pgfplots}, author = {Rushikesh Kamalapurkar}, date = {2021-09-11}, - version = {1.1.1}, + version = {1.1.2}, license = {lppl1.3c}, mirror = {https://mirror.ctan.org/graphics/pgf/contrib/bodeplot}, url = {https://ctan.org/pkg/bodeplot}, annotation = {This is a \LaTeX{} package to plot Bode, Nichols, and Nyquist diagrams. - It provides added functionality over the similar + It provides added functionality over the similar package:}, } @@ -21791,8 +21791,8 @@ title = {The \texttt{eolang} package}, subtitle = {Formulas and graphs for the EO programming language}, author = {Yegor Bugayenko}, - date = {2022-10-29}, - version = {0.2.0}, + date = {2022-10-30}, + version = {0.3.0}, license = {mit}, mirror = {https://mirror.ctan.org/macros/latex/contrib/eolang}, url = {https://ctan.org/pkg/eolang}, @@ -24467,8 +24467,8 @@ title = {The \texttt{ffcode} package}, subtitle = {Fixed-font code blocks formatted nicely}, author = {Yegor Bugayenko}, - date = {2022-10-03}, - version = {0.5.0}, + date = {2022-10-30}, + version = {0.5.1}, license = {mit}, mirror = {https://mirror.ctan.org/macros/latex/contrib/ffcode}, url = {https://ctan.org/pkg/ffcode}, @@ -28272,7 +28272,7 @@ title = {The \texttt{gillius} package}, subtitle = {Gillius fonts with \LaTeX{} support}, author = {Bob Tennent}, - date = {2022-10-28}, + date = {2022-10-30}, version = {}, license = {gpl2+,lppl}, mirror = {https://mirror.ctan.org/fonts/gillius}, @@ -30692,7 +30692,7 @@ title = {The \texttt{hep-reference} package}, subtitle = {Adjustments for publications in High Energy Physics}, author = {Jan Hajer}, - date = {2022-10-28}, + date = {2022-10-30}, version = {1.1}, license = {lppl1.3c}, mirror = {https://mirror.ctan.org/macros/latex/contrib/hep-reference}, @@ -37435,8 +37435,8 @@ title = {The \texttt{latexindent} package}, subtitle = {Indent a \LaTeX{} document, highlighting the programming structure}, author = {Chris Hughes}, - date = {2022-06-13}, - version = {3.18}, + date = {2022-10-30}, + version = {3.19}, license = {gpl3}, mirror = {https://mirror.ctan.org/support/latexindent}, url = {https://ctan.org/pkg/latexindent}, @@ -40838,6 +40838,29 @@ url = {https://ctan.org/pkg/luamplib}, } +@manual{ctan-luaoptions, + title = {The \texttt{luaoptions} package}, + subtitle = {Option handling for Lua\LaTeX{} packages}, + author = {Jacques Peron}, + date = {2022-10-30}, + version = {0.8}, + license = {mit}, + mirror = {https://mirror.ctan.org/macros/luatex/latex/luaoptions}, + url = {https://ctan.org/pkg/luaoptions}, + annotation = {This Lua\LaTeX{} package provides extensive support for handling + , on package level and locally. + It allows the declaration of sets of options, along with defaults, + expected/allowed values and limited type checking. + These options can be enforced as package options, + changed at any point during a document, or overwritten locally + by optional macro arguments. + It is also possible to instantiate an Options object as an + independent Lua object, without linking it to a package. + can be used to enforce and prepopulate + options, or it can be used to simply handle the parsing of + optional arguments into proper Lua tables.}, +} + @manual{ctan-luaotfload, title = {The \texttt{luaotfload} package}, subtitle = {OpenType ‘loader’ for Plain \TeX{} and \LaTeX{}}, @@ -41212,8 +41235,8 @@ title = {The \texttt{lyluatex} package}, subtitle = {Commands to include lilypond scores within a (Lua)\LaTeX{} document}, author = {Jacques Peron and {The Gregorio Project}}, - date = {2019-05-28}, - version = {1.0f}, + date = {2022-10-30}, + version = {1.1}, license = {mit}, mirror = {https://mirror.ctan.org/support/lyluatex}, url = {https://ctan.org/pkg/lyluatex}, @@ -52203,8 +52226,8 @@ title = {The \texttt{pkuthss} package}, subtitle = {\LaTeX{} template for dissertations in Peking University}, author = {Casper Ti. Vector}, - date = {2022-05-04}, - version = {1.9.2}, + date = {2022-10-30}, + version = {1.9.3}, license = {lppl1.3,bsd,pd}, mirror = {https://mirror.ctan.org/macros/latex/contrib/pkuthss}, url = {https://ctan.org/pkg/pkuthss}, @@ -69691,8 +69714,8 @@ title = {The \texttt{tracklang} package}, subtitle = {Language and dialect tracker}, author = {Nicola Talbot}, - date = {2019-12-01}, - version = {1.4}, + date = {2022-10-30}, + version = {1.6}, license = {lppl1.3}, mirror = {https://mirror.ctan.org/macros/generic/tracklang}, url = {https://ctan.org/pkg/tracklang}, @@ -75118,8 +75141,8 @@ title = {The \texttt{XePersian} package}, subtitle = {Persian for \LaTeX{}, using XeTeX}, author = {Vafa Khalighi and {bidi-tex GitHub Organisation}}, - date = {2022-07-02}, - version = {24.7}, + date = {2022-10-30}, + version = {24.8}, license = {lppl1.3c}, mirror = {https://mirror.ctan.org/macros/xetex/latex/xepersian}, url = {https://ctan.org/pkg/xepersian}, diff --git a/biblio/ctan-bibdata/ctan.pdf b/biblio/ctan-bibdata/ctan.pdf index c1a80b40cb..b6e84cc6d1 100644 Binary files a/biblio/ctan-bibdata/ctan.pdf and b/biblio/ctan-bibdata/ctan.pdf differ diff --git a/fonts/gillius/README b/fonts/gillius/README index de3902c3ab..6993b6a03f 100644 --- a/fonts/gillius/README +++ b/fonts/gillius/README @@ -1,4 +1,4 @@ -This is the README for the gillius package, version 2022-10-28. +This is the README for the gillius package, version 2022-10-30. This package provides LaTeX, pdfLaTeX, XeLaTeX and LuaLaTeX support for the Gillius and Gillius No. 2 families of sans serif fonts and diff --git a/fonts/gillius/latex/gillius.sty b/fonts/gillius/latex/gillius.sty index 54c134a411..6118494c7c 100644 --- a/fonts/gillius/latex/gillius.sty +++ b/fonts/gillius/latex/gillius.sty @@ -1,6 +1,6 @@ \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{gillius} - [2022/10/28 (Bob Tennent) Supports Gillius fonts for all LaTeX engines.] + [2022/10/30 (Bob Tennent) Supports Gillius fonts for all LaTeX engines.] \RequirePackage{ifxetex,ifluatex,xkeyval,textcomp} @@ -34,7 +34,6 @@ \fi \ifgillius@otf - \ifxetex\XeTeXtracingfonts=1\fi \defaultfontfeatures{ Ligatures = TeX , Scale = \GilliusADF@scale , diff --git a/graphics/pgf/contrib/bodeplot/README.md b/graphics/pgf/contrib/bodeplot/README.md index 31ac7a132f..c08155898c 100644 --- a/graphics/pgf/contrib/bodeplot/README.md +++ b/graphics/pgf/contrib/bodeplot/README.md @@ -1,55 +1,2999 @@ -# bodeplot -LaTeX package to plot Bode, Nichols, and Nyquist diagrams. -Inspired by the `bodegraph` package. -*Version 1.0.8 and newer store `gnuplot` temporary files in the working directory. Use class option `declutter` to restore pre-v1.0.8 behavior. Option `declutter` can cause errors if used with a `tikzexternalize` prefix.* -Compilation instructions: -1) `latex bodeplot.ins` to generate `bodeplot.sty` -2) To compile documentation (needs `gnuplot` on system PATH): -``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bodeplot/README.md at main · rlkamalapurkar/bodeplot + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Skip to content + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+ + + + + +
+ + + + + + + + + +
+ + + + + + + + + + + + + + + + + + +
+ +
+ + + + rlkamalapurkar  /   + bodeplot  /   + +
+
+ + + +
+ + +
+
+ Clear Command Palette +
+
+ + + +
+
+ Tip: + Type # to search pull requests +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type # to search issues +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type # to search discussions +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type ! to search projects +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type @ to search teams +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type @ to search people and organizations +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type > to activate command mode +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Go to your accessibility settings to change your keyboard shortcuts +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type author:@me to search your content +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:pr to filter to pull requests +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:issue to filter to issues +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:project to filter to projects +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:open to filter to open content +
+
+ Type ? for help and tips +
+
+
+ +
+ +
+
+ We’ve encountered an error and some results aren't available at this time. Type a new search or try again later. +
+
+ + No results matched your search + + + + + + + + + + +
+ + + + + Search for issues and pull requests + + # + + + + Search for issues, pull requests, discussions, and projects + + # + + + + Search for organizations, repositories, and users + + @ + + + + Search for projects + + ! + + + + Search for files + + / + + + + Activate command mode + + > + + + + Search your issues, pull requests, and discussions + + # author:@me + + + + Search your issues, pull requests, and discussions + + # author:@me + + + + Filter to pull requests + + # is:pr + + + + Filter to issues + + # is:issue + + + + Filter to discussions + + # is:discussion + + + + Filter to projects + + # is:project + + + + Filter to open issues, pull requests, and discussions + + # is:open + + + + + + + + + + + + + + + + +
+
+
+ +
+ + + + + + + + + + +
+ + +
+
+
+ + + + + + + + + + +
+ +
+ +
+ +
+ + + + / + + bodeplot + + + Public +
+ + +
+ +
    + +
  • +
    +
    +
    +
  • + + +
  • + +
    + + + + + Unwatch + + + + + 1 + + + +
    +
    +

    Notifications

    + +
    + +
    +
    + + + + + + + + +
    + + +
    + + + + + Get push notifications on iOS or Android. + +
    +
    +
    +
    + + + + +
    +
    +
    + + + +
  • + +
  • +
    + Fork + 1 + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
  • + +
  • + + +
    +
    +
    + + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
    +
    +
    + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
    +
  • + + + +
+ +
+ +
+
+ + + + + + +
+ + + + +
+ Open in github.dev + Open in a new github.dev tab + + + + + + +
+ + +
+ + + + + + + + +Permalink + +
+ +
+
+ + + main + + + + +
+
+
+ Switch branches/tags + +
+ + + +
+ +
+ +
+ + +
+ +
+ + + + + + + + + + + + + + + + + +
+ + +
+
+
+
+ +
+ +
+ + +
+ +
+
+
+

Name already in use

+
+
+ +
+
+
+
+ +
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? +
+ +
+
+ + +
+
+ + + + Go to file + +
+ + + + +
+
+
+ + + + + + + + + +
+ +
+
+
 
+
+ +
+
 
+ Cannot retrieve contributors at this time +
+
+ + + + + + + + + + + + + +
+ +
+ + +
+ + 57 lines (50 sloc) + + 3.79 KB +
+ +
+ + + + + +
+ +
+
+
+
+ +
+ +
+
+
+ + + +
+ + + + + + + + + +
+ + +
+ +
+
+ +
+ +
+
+ + +
+

bodeplot

+

LaTeX package to plot Bode, Nichols, and Nyquist diagrams.

+

Inspired by the bodegraph package.

+

Version 1.0.8 and newer store gnuplot temporary files in the working directory. Use class option declutter to restore pre-v1.0.8 behavior. Option declutter can cause errors if used with a tikzexternalize prefix.

+

Compilation instructions:

+
    +
  1. latex bodeplot.ins to generate bodeplot.sty
  2. +
  3. To compile documentation (needs gnuplot on system PATH):
  4. +
+
pdflatex bodeplot.dtx --shell-escape
 makeindex -s gind.ist bodeplot.idx
 makeindex -s gglo.ist -o bodeplot.gls bodeplot.glo
 pdflatex bodeplot.dtx --shell-escape
 pdflatex bodeplot.dtx --shell-escape
-```
-Added functionality:
- - New `\BodeZPK` and `\BodeTF` commands to generate Bode plots of any transfer function given either poles, zeros, gain, and delay, or numerator and denominator coefficients and delay
- - Support for unstable poles and zeros.
- - Support for complex poles and zeros.
- - Support for general stable and unstable second order transfer functions.
- - Support for both `gnuplot` (default) and `pgfplots` (package option `pgf`).
- - Support for linear and asymptotic approximation of magnitude and phase plots of any transfer function given poles, zeros, and gain.
-
-Main Bode/Nyquist/Nichols commands:
-Given Zeros, Poles, Gain, and Delay (Bode plots support asymptotic and linear approximation for systems without delays):
- - `\BodeZPK[object1/type1/{options1},object2/type2/{options2},...]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}`
- - `\NicholsZPK[plot/{options},axes/{options}]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}`
- - `\NyquistZPK[plot/{options},axes/{options}]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}`
-
-Given Numerator and denominator coefficients and delay (does not support approximation yet):
- - `\BodeTF[object1/type1/{options1},object2/type2/{options2},...]{num/{coeff},den/{coeff},d/delay}{min-frequency}{max-frequency}`
- - `\NicholsTF[plot/{options},axes/{options}]{num/{coeff},den/{coeff},d/delay}`
- - `\NyquistTF[plot/{options},axes/{options}]{num/{coeff},den/{coeff},d/delay}`
- 
-Other new environments and associated commands:
- - `BodePlot` environment
-    - `\addBodeZPKPlots[{approximation1/{plot-options1}},{approximation2/{plot-options2}},...]{plot-type (phase or magnitude)}{z/{zeros},p/{poles},k/gain,d/delay}`
-    - `\addBodeTFPlot[plot-options]{plot-type (phase or magnitude)}{num/{coeff},den/{coeff},d/delay}`
-    - `\addBodeComponentPlot[plot-options]{basic_component_plot_command}`
-      - Basic component plot commands: ***(append `Lin` to get linear approximation and `Asymp` to get asymptotic approximation)*** ***(change `Pole` to `Zero` to get inverse plots)*** ***(change `Mag` to `Ph` to get phase plots)***
-      - `\MagK{a}` - Pure gain, G(s) = a.
-      - `\MagPole{a}{b}` - Single pole at s = a+bi, G(s) = 1/(s - a-bi).
-      - `\MagCSPoles{z}{w}` - Cannonical Second order system, G(s) = 1/(s^2 + 2zws + w^2).
-      - `\MagSOPoles{a}{b}` - Second Order system, G(s) = 1/(s^2 + as + b).
-      - `\MagDel{T}` - Pure delay, G(s) = exp(-Ts) (does not admit asymptotic approximation).
- - `NicholsChart` environment
-    - `\addNicholsZPKChart[plot-options]{z/{zeros},p/{poles},k/gain,d/delay}`
-    - `\addNicholsTFChart[plot-options]{num/{coeff},den/{coeff},d/delay}`
- - `NyquistPlot` environment
-    - `\addNyquistZPKPlot[plot-options]{z/{zeros},p/{poles},k/gain,d/delay}`
-    - `\addNyquistTFPlot[plot-options]{num/{coeff},den/{coeff},d/delay}`
-
-Limitation: TF commands are wrapped between 0 and 360 degrees in `pgf` mode.
+
+

Added functionality:

+
    +
  • New \BodeZPK and \BodeTF commands to generate Bode plots of any transfer function given either poles, zeros, gain, and delay, or numerator and denominator coefficients and delay
  • +
  • Support for unstable poles and zeros.
  • +
  • Support for complex poles and zeros.
  • +
  • Support for general stable and unstable second order transfer functions.
  • +
  • Support for both gnuplot (default) and pgfplots (package option pgf).
  • +
  • Support for rad/s (default) and Hz (package option Hz or pgf key frequency unit=Hz for per-plot change) frequency units.
  • +
  • Support for deg (default) and rad (package option rad or pgf key phase unit=rad for per-plot change) phase units.
  • +
  • Support for linear and asymptotic approximation of magnitude and phase plots of any transfer function given poles, zeros, and gain.
  • +
+

Main Bode/Nyquist/Nichols commands: +Given Zeros, Poles, Gain, and Delay (Bode plots support asymptotic and linear approximation for systems without delays):

+
    +
  • \BodeZPK[object1/type1/{options1},object2/type2/{options2},...]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}
  • +
  • \NicholsZPK[plot/{options},axes/{options}]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}
  • +
  • \NyquistZPK[plot/{options},axes/{options}]{z/{zeros},p/{poles},k/gain,d/delay}{min-frequency}{max-frequency}
  • +
+

Given Numerator and denominator coefficients and delay (does not support approximation yet):

+
    +
  • \BodeTF[object1/type1/{options1},object2/type2/{options2},...]{num/{coeff},den/{coeff},d/delay}{min-frequency}{max-frequency}
  • +
  • \NicholsTF[plot/{options},axes/{options}]{num/{coeff},den/{coeff},d/delay}
  • +
  • \NyquistTF[plot/{options},axes/{options}]{num/{coeff},den/{coeff},d/delay}
  • +
+

Other new environments and associated commands:

+
    +
  • BodePlot environment +
      +
    • \addBodeZPKPlots[{approximation1/{plot-options1}},{approximation2/{plot-options2}},...]{plot-type (phase or magnitude)}{z/{zeros},p/{poles},k/gain,d/delay}
    • +
    • \addBodeTFPlot[plot-options]{plot-type (phase or magnitude)}{num/{coeff},den/{coeff},d/delay}
    • +
    • \addBodeComponentPlot[plot-options]{basic_component_plot_command} +
        +
      • Basic component plot commands: (append Lin to get linear approximation and Asymp to get asymptotic approximation) (change Pole to Zero to get inverse plots) (change Mag to Ph to get phase plots)
      • +
      • \MagK{a} - Pure gain, G(s) = a.
      • +
      • \MagPole{a}{b} - Single pole at s = a+bi, G(s) = 1/(s - a-bi).
      • +
      • \MagCSPoles{z}{w} - Cannonical Second order system, G(s) = 1/(s^2 + 2zws + w^2).
      • +
      • \MagSOPoles{a}{b} - Second Order system, G(s) = 1/(s^2 + as + b).
      • +
      • \MagDel{T} - Pure delay, G(s) = exp(-Ts) (does not admit asymptotic approximation).
      • +
      +
    • +
    +
  • +
  • NicholsChart environment +
      +
    • \addNicholsZPKChart[plot-options]{z/{zeros},p/{poles},k/gain,d/delay}
    • +
    • \addNicholsTFChart[plot-options]{num/{coeff},den/{coeff},d/delay}
    • +
    +
  • +
  • NyquistPlot environment +
      +
    • \addNyquistZPKPlot[plot-options]{z/{zeros},p/{poles},k/gain,d/delay}
    • +
    • \addNyquistTFPlot[plot-options]{num/{coeff},den/{coeff},d/delay}
    • +
    +
  • +
+

Limitation: TF commands are wrapped between 0 and 360 degrees in pgf mode.

+
+
+ +
+ + + + +
+ + +
+ + +
+
+ + + +
+ +
+ + +
+ +
+ + +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + diff --git a/graphics/pgf/contrib/bodeplot/bodeplot.dtx b/graphics/pgf/contrib/bodeplot/bodeplot.dtx index aad1eb47d6..8b39af91e0 100644 --- a/graphics/pgf/contrib/bodeplot/bodeplot.dtx +++ b/graphics/pgf/contrib/bodeplot/bodeplot.dtx @@ -1,2118 +1,11546 @@ -% \iffalse meta-comment -% -% Copyright (C) 2021 by Rushikesh Kamalapurkar -% ----------------------------------------------------------- -% -% This file may be distributed and/or modified under the conditions of -% the LaTeX Project Public License, either version 1.3c of this license -% or (at your option) any later version. The latest version of this -% license is in: -% -% http://www.latex-project.org/lppl.txt -% -% and version 1.3c or later is part of all distributions of LaTeX -% version 2006/05/20 or later. -% -% \fi -% -% \iffalse -%\NeedsTeXFormat{LaTeX2e}[2006/05/20] -%\ProvidesPackage{bodeplot} -%\RequirePackage{pdftexcmds} -%\RequirePackage{ifplatform} -%\RequirePackage{pgfplots} -% \pgfplotsset{compat=1.18} -% \usepgfplotslibrary{groupplots} -% -%<*driver> -\documentclass{ltxdoc} -\usepackage{cprotect} -\usepackage[declutter]{bodeplot} -\usepackage[colorlinks]{hyperref} -\usepackage{iftex} - \iftutex % LuaTeX, XeTeX - \usepackage{fontspec} - \setmonofont{DejaVuSansMono}[Scale=MatchUppercase] - \else % old engines - \usepackage[T1]{fontenc} - \usepackage{lmodern} - \usepackage[scaled]{DejaVuSansMono} - \fi -\usepackage{showexpl} - \lstset{ - explpreset={numbers=none}, - language=[LaTeX]Tex, - basicstyle=\ttfamily\tiny, - commentstyle=\itshape\ttfamily\tiny, - showspaces=false, - showstringspaces=false, - breaklines=true, - backgroundcolor=\color{white!90!black}, - breakautoindent=true, - captionpos=t - } -\usepackage{geometry} - \geometry{lmargin=2in,rmargin=1in,tmargin=1in,bmargin=1in} -\usetikzlibrary{decorations.markings,arrows.meta,spy,backgrounds} -\usepackage[nottoc]{tocbibind} -\sloppy -\EnableCrossrefs -\CodelineIndex -\RecordChanges -\begin{document} - \DocInput{bodeplot.dtx} - \PrintChanges - \PrintIndex -\end{document} -% -% \fi -% -% \CheckSum{1723} -% -% \changes{v1.0}{2021/10/25}{Initial release} -% \changes{v1.0.4}{2021/11/05}{Fixed unintended optional argument macro expansion} -% \changes{v1.0.6}{2021/11/18}{Fixed issue \#3} -% \changes{v1.0.7}{2021/12/02}{Removed unnecessary semicolons} -% \changes{v1.0.7}{2022/01/18}{Updated documentation} -% \changes{v1.0.8}{2022/07/06}{Added a new class option `declutter'} -% \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode} -% \changes{v1.1.1}{2022/07/31}{Enable Hz and rad units} -% -% \GetFileInfo{bodeplot.sty} -% \DoNotIndex{\newcommand,\xdef,\gdef,\def,\edef,\addplot,\approx,\arabic,\opt,\typ,\obj,\else,\if@pgfarg,\if@Hzarg,\if@radarg,\if@declutterarg,\fi,\begin,\end,\feature,\footnotesize,\draw,\detokenize,\DeclareOption,\foreach,\ifdim,\ifodd,\Im,\Re,\let,\newif,\nextgroupplot,\noexpand,\expandafter,\unexpanded,\PackageError,\PackageWarning,\relax,\RequirePackage,\tikzset,\pgfmathsetmacro,\pgfmathtruncatemacro,\ProcessOptions} -% -% \title{The \textsf{bodeplot} package\\version 1.1.1} -% \author{Rushikesh Kamalapurkar \\ \texttt{rlkamalapurkar@gmail.com}} -% -% \maketitle -% \tableofcontents -% \clearpage -% \section{Introduction} -% -% Generate Bode, Nyquist, and Nichols plots for transfer functions in the canonical (TF) form \begin{equation}G(s) = e^{-Ts}\frac{b_ms^m+\cdots+b_1s+b_0}{a_ns^n+\cdots+a_1s+a_0}\label{eq:TF}\end{equation} and the zero-pole-gain (ZPK) form \begin{equation}G(s) = Ke^{-Ts}\frac{(s-z_1)(s-z_2)\cdots(s-z_m)}{(s-p_1)(s-p_2)\cdots(s-p_n)}.\label{eq:ZPK}\end{equation} In the equations above, $b_m,\cdots,b_0$ and $a_n,\cdots,a_0$ are real coefficients, $T\geq 0$ is the loop delay, $z_1,\cdots,z_m$ and $p_1,\cdots,p_n$ are complex zeros and poles of the transfer function, respectively, and $K\in \Re$ is the loop gain. -% -% For transfer functions in the ZPK format in (\ref{eq:ZPK}) \emph{with zero delay}, this package also supports linear and asymptotic approximation of Bode plots. -% -% By default, all phase plots use degrees as units. Use the |rad| package option or the optional argument |tikz/{phase unit=rad}| to generate plots in radians. The |phase unit| key accepts either |rad| or |deg| as inputs and needs to be added to the |tikzpicture| environment that contains the plots. -% -% By default, frequency inputs and outputs are in radians per second. Use the |Hz| package option or the optional argument |tikz/{frequency unit=Hz}| to generate plots in hertz. The |frequency unit| key accepts either |rad| or |Hz| as inputs and needs to be added to the |tikzpicture| environment that contains the plots. -% \subsection{External Dependencies} -% By default, the package uses |gnuplot| to do all the computations. If |gnuplot| is not available, the |pgf| package option can be used to do the calculations using the native |pgf| math engine. Compilation using the |pgf| math engine is typically slower, but the end result should be the identical (other than phase wrapping in the TF form, see limitations below). -%\subsection{Directory Structure} -% Since version 1.0.8, the |bodeplot| package places all |gnuplot| temporary files in the working directory. The package option |declutter| restores the original behavior where the temporary files are placed in a folder called |gnuplot|. -% \subsection{Limitations} -% \begin{itemize} -% \item In |pgf| mode, Bode phase plots and Nichols charts in TF form wrap angles so that they are always between 0 and 360$^\circ$ or 0 and $2\pi$ radian. As such, these plots will show phase wrapping discontinuities. Since v1.1.1, in |gnuplot| mode, the package uses the |smooth unwrap| filter to correct wrapping discontinuities. As of now, I have not found a way to do this in |pgf| mode, any merge requests or ideas you may have are welcome! -% \item Use of the |declutter| option with other directory management tools such as a |tikzexternalize| prefix is not recommended. -% \end{itemize} -% \clearpage -% \section{TL;DR} -% All Bode plots in this section are for the transfer function (with and without a transport delay) -% \begin{equation} -% G(s) = 10\frac{s(s+0.1+0.5\mathrm{i})(s+0.1-0.5\mathrm{i})}{(s+0.5+10\mathrm{i})(s+0.5-10\mathrm{i})} = \frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)}. -% \end{equation} -% \iffalse -%<*ignore> -% \fi - -\hrulefill - -{\centering Bode plot in ZPK format -\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth] -\BodeZPK{% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% -} -{0.01} -{100} -\end{LTXexample} - -\hrulefill - -Same Bode plot over the same frequency range but supplied in Hz, in TF format with arrow decoration, transport delay, unit, and color customization (the phase plot may show wrapping if the |pgf| package option is used) -\begin{LTXexample}[pos=r,width=0.5\textwidth] -\BodeTF[% - samples=1000, - plot/mag/{blue,thick}, - plot/ph/{green,thick}, - tikz/{% - >=latex, - phase unit=rad, - frequency unit=Hz% - }, - commands/mag/{ - \draw[->](axis cs:0.1,40) -- (axis cs:{10/(2*pi)},60); - \node at (axis cs: 0.08,30) {\tiny Resonant Peak}; - }% -] -{% - num/{10,2,2.6,0}, - den/{1,1,100.25}% -} -{0.01/(2*pi)} -{100/(2*pi)} -\end{LTXexample} - -\hrulefill -\clearpage -\hrulefill - -Linear approximation with customization -\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth] -\BodeZPK[% - plot/mag/{red,thick}, - plot/ph/{blue,thick}, - axes/mag/{ytick distance=40}, - axes/ph/{ytick distance=90}, - approx/linear% -]{% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% -} -{0.01} -{100} -\end{LTXexample} - -\hrulefill - -Plot with delay and customization -\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth] -\BodeZPK[% - plot/mag/{blue,thick}, - plot/ph/{green,thick}, - axes/mag/ytick distance=40, - axes/ph/ytick distance=90% -]{% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10, - d/0.01% -} -{0.01} -{100} -\end{LTXexample} - -\hrulefill -\clearpage -\hrulefill - -Individual gain and phase plots with more customization - -\begin{minipage}[t]{0.45\textwidth} -\begin{LTXexample}[pos=t,width=\columnwidth] -\begin{BodeMagPlot}[% - axes/{height=2cm, - width=4cm} -] -{0.01} -{100} - \addBodeZPKPlots[% - true/{black,thick}, - linear/{red,dashed,thick}, - asymptotic/{blue,dotted,thick}% - ] - {magnitude} - {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% - } -\end{BodeMagPlot} -\end{LTXexample} -\end{minipage}\hfill -\begin{minipage}[t]{0.45\textwidth} -\begin{LTXexample}[pos=t,width=\columnwidth] -\begin{BodePhPlot}[% - height=2cm, - width=4cm, - ytick distance=90 -] -{0.01} -{100} - \addBodeZPKPlots[% - true/{black,thick}, - linear/{red,dashed,thick}, - asymptotic/{blue,dotted,thick}% - ] - {phase} - {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% - } -\end{BodePhPlot} -\end{LTXexample} -\end{minipage} - -\hrulefill - -Nichols chart -\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth] -\NicholsZPK[samples=1000] -{% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10, - d/0.01% -} -{0.001} -{500} -\end{LTXexample} - -\hrulefill - -Same Nichols chart in TF format (may show wrapping in |pgf| mode) -\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth] -\NicholsTF[samples=1000] -{% - num/{10,2,2.6,0}, - den/{1,1,100.25}, - d/0.01% -} -{0.001} -{500} -\end{LTXexample} - -\hrulefill -\clearpage -\hrulefill - -Multiple Nichols charts with customization -\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth] -\begin{NicholsChart}[% - ytick distance=20, - xtick distance=30 -] -{0.001} -{100} - \addNicholsZPKChart [red,samples=1000] {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% - } - \addNicholsZPKChart [blue,samples=1000] {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/5% - } -\end{NicholsChart} -\end{LTXexample} - -\hrulefill - -Nyquist plot -\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth] -\NyquistZPK[plot/{red,thick,samples=1000}] -{% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% -} -{-30} -{30} -\end{LTXexample} - -\hrulefill - -Nyquist plot in TF format with arrows -\begin{LTXexample}[pos=l,width=0.5\textwidth] -\NyquistTF[% - plot/{% - samples=1000, - postaction=decorate, - decoration={% - markings, - mark=between positions 0.1 and 0.9 step 5em with {% - \arrow{Stealth [length=2mm, blue]} - } - } - }% -] -{% - num/{10,2,2.6,0}, - den/{1,1,100.25}% -} -{-30} -{30} -\end{LTXexample} - -\hrulefill -\clearpage -\hrulefill - -Multiple Nyquist plots with customization -\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth] -\begin{NyquistPlot}{-30}{30} - \addNyquistZPKPlot [red,samples=1000] {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/10% - } - \addNyquistZPKPlot [blue,samples=1000] {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/5% - } -\end{NyquistPlot} -\end{LTXexample} - -\hrulefill - -Nyquist plots with additional commands, using two different macros - -\begin{minipage}[t]{0.48\textwidth} -\begin{LTXexample}[pos=t,width=\columnwidth] -\begin{NyquistPlot}[% - tikz/{ - spy using outlines={% - circle, - magnification=3, - connect spies, - size=2cm - } - }% -] -{-30}{30} - \addNyquistZPKPlot [blue,samples=1000] {% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/0.5% - } - \coordinate (spyon) at (axis cs:0,0); - \coordinate (spyat) at (axis cs:-22,5); - \spy [green] on (spyon) in - node [fill=white] at (spyat); -\end{NyquistPlot} -\end{LTXexample} -\end{minipage}\hfill -\begin{minipage}[t]{0.48\textwidth} -\begin{LTXexample}[pos=t,width=\columnwidth] -\NyquistZPK[% - plot/{blue,samples=1000}, - tikz/{ - spy using outlines={% - circle, - magnification=3, - connect spies, - size=2cm - } - }, - commands/{ - \coordinate (spyon) at (axis cs:0,0); - \coordinate (spyat) at (axis cs:-22,5); - \spy [green] on (spyon) in - node [fill=white] at (spyat); - }% -] -{% - z/{0,{-0.1,-0.5},{-0.1,0.5}}, - p/{{-0.5,-10},{-0.5,10}}, - k/0.5% -} -{-30} -{30} -\end{LTXexample} -\end{minipage}} - -\hrulefill -\clearpage - -% \iffalse -% -% \fi -% -% \section{Usage} -% \noindent In all the macros described here, the frequency limits supplied by the user are assumed to be in |rad/s| unless either the |Hz| package option is used or the optional argument |tikz/{frequency unit=Hz}| is supplied to the |tikzpicture| environment. All phase plots are getenrated in degrees unless either the |rad| package option is used or the optional argument |tikz/{frequency unit=rad}| is supplied to the |tikzpicture| environment. -% -% \subsection{Bode plots} -% \DescribeMacro{\BodeZPK} -% |\BodeZPK| \oarg{obj1/typ1/\marg{opt1},obj2/typ2/\marg{opt2},...}\\ -% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\ -% \hspace*{2em}\marg{min-freq}\marg{max-freq} -% -% \noindent Plots the Bode plot of a transfer function given in ZPK format using the |groupplot| environment. The three mandatory arguments include: (1) a list of tuples, comprised of the zeros, the poles, the gain, and the transport delay of the transfer function, (2) the lower end of the frequency range for the $x-$axis, and (3) the higher end of the frequency range for the $x-$axis. The zeros and the poles are complex numbers, entered as a comma-separated list of comma-separated lists, of the form |{{real part 1,imaginary part 1},| |{real part 2,imaginary part 2},...}|. If the imaginary part is not provided, it is assumed to be zero. -% -% The optional argument is comprised of a comma separated list of tuples, either |obj/typ/{opt}|, or |obj/{opt}|, or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the group, the axes, and the plots according to: -% \begin{itemize} -% \item Tuples of the form |obj/typ/{opt}|: -% \begin{itemize} -% \item |plot/typ/{opt}|: modify plot properties by adding options |{opt}| to the |\addplot| macro for the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|. -% \item |axes/typ/{opt}|: modify axis properties by adding options |{opt}| to the |\nextgroupplot| macro for the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|. -% \item |commands/typ/{opt}|: add any valid TikZ commands (including the the parametric function generator macros in this package, such as |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|) to the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual. For example, a TikZ command is used in the description of the |\BodeTF| macro below to mark the gain crossover frequency on the Bode Magnitude plot. -% \end{itemize} -% \item Tuples of the form |obj/{opt}|: -% \begin{itemize} -% \item |plot/{opt}|: adds options |{opt}| to |\addplot| macros for both the magnitude and the phase plots. -% \item |axes/{opt}|: adds options |{opt}| to |\nextgroupplot| macros for both the magnitude and the phase plots. -% \item |group/{opt}|: adds options |{opt}| to the |groupplot| environment. -% \item |tikz/{opt}|: adds options |{opt}| to the |tikzpicture| environment. -% \item |approx/linear|: plots linear approximation. -% \item |approx/asymptotic|: plots asymptotic approximation. -% \end{itemize} -% \item Tuples of the form |{opt}| add all of the supplied options to |\addplot| macros for both the magnitude and the phase plots. -% \end{itemize} -% The options |{opt}| can be any |key=value| options that are supported by the |pgfplots| macros they are added to. - -% For example, given a transfer function \begin{equation}G(s) = 10\frac{s(s+0.1+0.5\mathrm{i})(s+0.1-0.5\mathrm{i})}{(s+0.5+10\mathrm{i})(s+0.5-10\mathrm{i})},\label{eq:ZPKExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using\\ -% |\BodeZPK [blue,thick]|\\ -% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\ -% | {0.01}{100}|\\ -% which generates the plot in Figure \ref{simpleBode}. If a delay is not specified, it is assumed to be zero. If a gain is not specified, it is assumed to be 1. By default, each of the axes, excluding ticks and labels, are 5cm wide and 2.5cm high. The width and the height, along with other properties of the plots, the axes, and the group can be customized using native |pgf| keys as shown in the example below. -% -% \begin{figure} -% \begin{center} -% \BodeZPK[blue,thick]{z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}{0.01}{100} -% \cprotect\caption{\label{simpleBode}Output of the default |\BodeZPK| macro.} -% \end{center} -% \end{figure} -% As demonstrated in this example, if a single comma-separated list of options is passed, it applies to both the magnitude and the phase plots. Without any optional arguments, we gets a thick black Bode plot. -% -% A linear approximation of the Bode plot with customization of the plots, the axes, and the group can be generated using\\ -% |\BodeZPK[plot/mag/{red,thick},plot/ph/{blue,thick},|\\ -% | axes/mag/{ytick distance=40,xmajorticks=true,|\\ -% | xlabel={Frequency (rad/s)}},axes/ph/{ytick distance=90},|\\ -% | group/{group style={group size=2 by 1,horizontal sep=2cm,|\\ -% | width=4cm,height=2cm}},approx/linear]|\\ -% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\ -% | {0.01}{100}|\\ -% which generates the plot in Figure \ref{customBode}. -% -% \begin{figure} -% \begin{center} -% \BodeZPK[plot/mag/{red,thick},plot/ph/{blue,thick},axes/mag/{ytick distance=40,xmajorticks=true,xlabel={Frequency (rad/s)}},axes/ph/{ytick distance=90},approx/linear,group/{group style={group size = 2 by 1,horizontal sep=2cm},width=4cm,height=2cm}] {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},g/10} {0.01} {100} -% \cprotect\caption{\label{customBode}Customization of the default |\BodeZPK| macro.} -% \end{center} -% \end{figure} -% -% \DescribeMacro{\BodeTF} -% |\BodeTF| \oarg{obj1/typ1/\marg{opt1},obj2/typ2/\marg{opt2},...}\\ -% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\ -% \hspace*{2em}\marg{min-freq}\marg{max-freq} \rmfamily -% -% \noindent Plots the Bode plot of a transfer function given in TF format. The three mandatory arguments include: (1) a list of tuples comprised of the coefficients in the numerator and the denominator of the transfer function and the transport delay, (2) the lower end of the frequency range for the $x-$ axis, and (3) the higher end of the frequency range for the $x-$axis. The coefficients are entered as a comma-separated list, in order from the highest degree of $s$ to the lowest, with zeros for missing degrees. The optional arguments are the same as |\BodeZPK|, except that linear/asymptotic approximation is not supported, so |approx/...| is ignored. -% -% For example, given the same transfer function as (\ref{eq:ZPKExample}) in TF form and with a small transport delay, \begin{equation}G(s) = e^{-0.01s}\frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)},\label{eq:TFExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using\\ -% |\BodeTF[commands/mag/{\node at (axis cs: 2.1,0) |\\ -% | [circle,fill,inner sep=0.05cm,label=below:{$\omega_{gc}$}]{};}]|\\ -% | {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}|\\ -% | {0.01}{100}|\\ -% which generates the plot in Figure \ref{simpleBodeTF}. Note the $0$ added to the numerator coefficients to account for the fact that the numerator does not have a constant term in it. Note the semicolon after the TikZ command passed to the |\commands| option. -% -% \begin{figure} -% \begin{center} -% \BodeTF[commands/mag/{\node at (axis cs: 2.1,0) [circle,fill,inner sep=0.05cm,label=below:{$\omega_{gc}$}] {};}]{num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}{0.01}{100} -% \cprotect\caption{\label{simpleBodeTF}Output of the |\BodeTF| macro with an optional TikZ command used to mark the gain crossover frequency.} -% \end{center} -% \end{figure} -% -% \DescribeEnv{BodeMagPlot} -% |\begin{BodeMagPlot}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\ -% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\ -% \hspace*{2em}|\addBode...|\\ -% \hspace*{1.5em}|\end{BodeMagPlot}|\\ -% The |BodeMagPlot| environment works in conjunction with the parametric function generator macros |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|, intended to be used for magnitude plots. The optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to: -% \begin{itemize} -% \item Tuples of the form |obj/{opt}|: -% \begin{itemize} -% \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment. -% \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |semilogaxis| environment. -% \item |commands/{opt}|: add any valid TikZ commands inside |semilogaxis| environment. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual. -% \end{itemize} -% \item Tuples of the form |{opt}| are passed directly to the |semilogaxis| environment. -% \end{itemize} -% The frequency limits are translated to the x-axis limits and the domain of the |semilogaxis| environment. Example usage in the description of |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|. -% -%\DescribeEnv{BodePhPlot} -% |\begin{BodePhPlot}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\ - % \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\ - % \hspace*{2em}|\addBode...|\\ - % \hspace*{1.5em}|\end{BodePhPlot}|\\ -% Intended to be used for phase plots, otherwise same as the |BodeMagPlot| environment -% -% \DescribeMacro{\addBodeZPKPlots} -% |\addBodeZPKPlots| \oarg{approx1/\marg{opt1},approx2/\marg{opt2},...}\\ -% \hspace*{2em}\marg{plot-type}\\ -% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}} -% -% \noindent Generates the appropriate parametric functions and supplies them to multiple |\addplot| macros, one for each |approx/{opt}| pair in the optional argument. If no optional argument is supplied, then a single |\addplot| command corresponding to a thick true Bode plot is generated. If an optional argument is supplied, it needs to be one of |true/{opt}|, |linear/{opt}|, or |asymptotic/{opt}|. This macro can be used inside any |semilogaxis| environment as long as a domain for the x-axis is supplied through either the |approx/{opt}| interface or directly in the optional argument of the |semilogaxis| environment. Use with the |BodePlot| environment supplied with this package is recommended. The second mandatory argument, |plot-type| is either |magnitude| or |phase|. If it is not equal to |phase|, it is assumed to be |magnitude|. The last mandatory argument is the same as |\BodeZPK|. -% -% For example, given the transfer function in (\ref{eq:ZPKExample}), its linear, asymptotic, and true Bode plots can be superimposed using -%\begin{verbatim} -%\begin{BodeMagPlot}[height=2cm,width=4cm] {0.01} {100} -% \addBodeZPKPlots[% -% true/{black,thick}, -% linear/{red,dashed,thick}, -% asymptotic/{blue,dotted,thick}] -% {magnitude} -% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10} -%\end{BodeMagPlot} -% -%\begin{BodePhPlot}[height=2cm, width=4cm, ytick distance=90] {0.01} {100} -% \addBodeZPKPlots[% -% true/{black,thick}, -% linear/{red,dashed,thick}, -% asymptotic/{blue,dotted,thick}] -% {phase} -% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10} -%\end{BodePhPlot} -%\end{verbatim} -% \begin{figure} -% \begin{center} -% \begin{BodeMagPlot}[height=2cm,width=4cm]{0.01}{100} -% \addBodeZPKPlots[% -% true/{black,thick}, -% linear/{red,dashed,thick}, -% asymptotic/{blue,dotted,thick}] -% {magnitude} -% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10} -% \end{BodeMagPlot} -% \begin{BodePhPlot}[height=2cm,width=4cm,ytick distance=90]{0.01}{100} -% \addBodeZPKPlots[% -% true/{black,thick}, -% linear/{red,dashed,thick}, -% asymptotic/{blue,dotted,thick}] -% {phase} -% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10} -% \end{BodePhPlot} -% \end{center} -% \caption{\label{multiBodeZPK}Superimposed approximate and true Bode plots using the \texttt{BodeMagPlot} and \texttt{BodePhPlot} environments and the \texttt{\textbackslash addBodeZPKPlots} macro.} -% \end{figure} -% which generates the plot in Figure \ref{multiBodeZPK}. -% -% \DescribeMacro{\addBodeTFPlot} -% |\addBodeTFPlot|\oarg{plot-options}\\ -% \hspace*{2em}\marg{plot-type}\\ -% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}} -% -% \noindent Generates a single parametric function for either Bode magnitude or phase plot of a transfer function in TF form. The generated parametric function is passed to the |\addplot| macro. This macro can be used inside any |semilogaxis| environment as long as a domain for the x-axis is supplied through either the |plot-options| interface or directly in the optional argument of the container |semilogaxis| environment. Use with the |BodePlot| environment supplied with this package is recommended. The second mandatory argument, |plot-type| is either magnitude or |phase|. If it is not equal to |phase|, it is assumed to be |magnitude|. The last mandatory argument is the same as |\BodeTF|. -% -% \DescribeMacro{\addBodeComponentPlot} -% |\addBodeComponentPlot|\oarg{plot-options}\marg{plot-command} -% -% \noindent Generates a single parametric function corresponding to the mandatory argument |plot-command| and passes it to the |\addplot| macro. The plot command can be any parametric function that uses |t| as the independent variable. The parametric function must be |gnuplot| compatible (or |pgfplots| compatible if the package is loaded using the |pgf| option). The intended use of this macro is to plot the parametric functions generated using the basic component macros described in Section \ref{sec:BasicComponents} below. -% -% \subsubsection{Basic components up to first order\label{sec:BasicComponents}} -% -% \DescribeMacro{\TypeFeatureApprox} -% |\TypeFeatureApprox|\marg{real-part}\marg{imaginary-part} -% -% \noindent This entry describes 20 different macros of the form |\TypeFeatureApprox| that take the real part and the imaginary part of a complex number as arguments. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Feature| in the macro name should be replaced by one of |K|, |Pole|, |Zero|, or |Del|, to generate the Bode plot of a gain, a complex pole, a complex zero, or a transport delay, respectively. If the |Feature| is set to either |K| or |Del|, the |imaginary-part| mandatory argument is ignored. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively. If the |Feature| is set to |Del|, then |Approx| has to be removed. For example, -% \begin{itemize} -% \item |\MagK{k}{0}| or |\MagK{k}{400}| generates a parametric function for the true Bode magnitude of $ G(s) = k $ -% \item |\PhPoleLin{a}{b}| generates a parametric function for the linear approximation of the Bode phase of $ G(s) = \frac{1}{s-a-\mathrm{i}b} $. -% \item |\PhDel{T}{200}| or |\PhDel{T}{0}| generates a parametric function for the Bode phase of $ G(s) = e^{-Ts} $. -% \end{itemize} -% All 20 of the macros defined by combinations of |Type|, |Feature|, and |Approx|, and any |gnuplot| (or |pgfplot| if the |pgf| class option is loaded) compatible function of the 20 macros can be used as |plot-command| in the |addBodeComponentPlot| macro. This is sufficient to generate the Bode plot of any rational transfer function with delay. For example, the Bode phase plot in Figure \ref{multiBodeZPK} can also be generated using: -%\begin{verbatim} -%\begin{BodePhPlot}[ytick distance=90]{0.01}{100} -% \addBodeComponentPlot[black,thick]{\PhZero{0}{0} + \PhZero{-0.1}{-0.5} + -% \PhZero{-0.1}{0.5} + \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} + -% \PhK{10}{0}} -% \addBodeComponentPlot[red,dashed,thick] {\PhZeroLin{0}{0} + -% \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} + -% \PhPoleLin{-0.5}{-10} + \PhPoleLin{-0.5}{10} + \PhKLin{10}{20}} -% \addBodeComponentPlot[blue,dotted,thick] {\PhZeroAsymp{0}{0} + -% \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} + -% \PhPoleAsymp{-0.5}{-10} + \PhPoleAsymp{-0.5}{10} + \PhKAsymp{10}{40}} -%\end{BodePhPlot} -%\end{verbatim} -%\begin{figure} -% \begin{center} -% \begin{BodePhPlot}[ytick distance=90]{0.01}{100} -% \addBodeComponentPlot[black,thick] {\PhZero{0}{0} + \PhZero{-0.1}{-0.5} + \PhZero{-0.1}{0.5} + \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} + \PhK{10}{0}} -% \addBodeComponentPlot[red,dashed,thick] {\PhZeroLin{0}{0} + \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} + \PhPoleLin{-0.5}{-10} + \PhPoleLin{-0.5}{10} + \PhKLin{10}{20}} -% \addBodeComponentPlot[blue,dotted,thick] {\PhZeroAsymp{0}{0} + \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} + \PhPoleAsymp{-0.5}{-10} + \PhPoleAsymp{-0.5}{10} + \PhKAsymp{10}{40}} -% \end{BodePhPlot} -% \end{center} -% \caption{\label{multiBodeComponents}Superimposed approximate and true Bode Phase plot using the \texttt{BodePhPlot} environment, the \texttt{\textbackslash addBodeComponentPlot} macro, and several macros of the \texttt{\textbackslash TypeFeatureApprox} form.} -%\end{figure} -% which gives us the plot in Figure \ref{multiBodeComponents}. -% -% \subsubsection{Basic components of the second order} -% -% \DescribeMacro{\TypeSOFeatureApprox} -% |\TypeSOFeatureApprox|\marg{a1}\marg{a0} -% -% \noindent This entry describes 12 different macros of the form |\TypeSOFeatureApprox| that take the coefficients $ a_1 $ and $ a_0 $ of a general second order system as inputs. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate the Bode plot of $G(s)=\frac{1}{s^2+a_1 s+a_0}$ or $G(s)=s^2+a_1 s+a_0$, respectively. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively. -% -% \DescribeMacro{\MagSOFeaturePeak} -% |\MagSOFeaturePeak|\oarg{draw-options}\marg{a1}\marg{a0} -% -% \noindent This entry describes 2 different macros of the form |\MagSOFeaturePeak| that take the the coefficients $ a_1 $ and $ a_0 $ of a general second order system as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively. For example, the command -%\begin{verbatim} -%\begin{BodeMagPlot}[xlabel={}]{0.1}{10} -% \addBodeComponentPlot[red,dashed,thick]{\MagSOPoles{0.2}{1}} -% \addBodeComponentPlot[black,thick]{\MagSOPolesLin{0.2}{1}} -% \MagSOPolesPeak[thick]{0.2}{1} -%\end{BodeMagPlot} -%\end{verbatim} -% generates the plot in Figure \ref{BodePeak}. -% -% \begin{figure} -% \begin{center} -% \begin{BodeMagPlot}[xlabel={}]{0.1}{10} -% \addBodeComponentPlot[red,dashed,thick]{\MagSOPoles{0.2}{1}} -% \addBodeComponentPlot[black,thick]{\MagSOPolesLin{0.2}{1}} -% \MagSOPolesPeak[very thick]{0.2}{1} -% \end{BodeMagPlot} -% \end{center} -% \cprotect\caption{\label{BodePeak} Resonant peak in asymptotic Bode plot using |\MagSOPolesPeak|.} -% \end{figure} -% -% \DescribeMacro{\TypeCSFeatureApprox} -% |\TypeCSFeatureApprox|\marg{zeta}\marg{omega-n} -% -% \noindent This entry describes 12 different macros of the form |\TypeCSFeatureApprox| that take the damping ratio, $ \zeta $, and the natural frequency, $ \omega_n $ of a canonical second order system as inputs. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate the Bode plot of $G(s)=\frac{1}{s^2+2\zeta\omega_n s+\omega_n^2}$ or $G(s)=s^2+2\zeta\omega_n s+\omega_n^2$, respectively. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively. -% -% \DescribeMacro{\MagCSFeaturePeak} -% |\MagCSFeaturePeak|\oarg{draw-options}\marg{zeta}\marg{omega-n} -% -% \noindent This entry describes 2 different macros of the form |\MagCSFeaturePeak| that take the damping ratio, $ \zeta $, and the natural frequency, $ \omega_n $ of a canonical second order system as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively. -% -% \DescribeMacro{\MagCCFeaturePeak} -% |\MagCCFeaturePeak|\oarg{draw-options}\marg{real-part}\marg{imaginary-part} -% -% \noindent This entry describes 2 different macros of the form |\MagCCFeaturePeak| that take the real and imaginary parts of a pair of complex conjugate poles or zeros as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively. -% -% \subsection{Nyquist plots} -% \DescribeMacro{\NyquistZPK} -% |\NyquistZPK| \oarg{plot/\marg{opt},axes/\marg{opt}}\\ -% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\ -% \hspace*{2em}\marg{min-freq}\marg{max-freq} -% -% \noindent Plots the Nyquist plot of a transfer function given in ZPK format with a thick red $+$ marking the critical point (-1,0). The mandatory arguments are the same as |\BodeZPK|. Since there is only one plot in a Nyquist diagram, the |\typ| specifier in the optional argument tuples is not needed. As such, the supported optional argument tuples are |plot/{opt}|, which passes |{opt}| to |\addplot|, |axes/{opt}|, which passes |{\opt}| to the |axis| environment, and |tikz/{opt}|, which passes |{\opt}| to the |tikzpicture| environment. Asymptotic/linear approximations are not supported in Nyquist plots. If just |{opt}| is provided as the optional argument, it is interpreted as |plot/{opt}|. Arrows to indicate the direction of increasing $\omega$ can be added by adding |\usetikzlibrary{decorations.markings}| and |\usetikzlibrary{arrows.meta}| to the preamble and then passing a tuple of the form\\ -%|plot/{postaction=decorate,decoration={markings,|\\ -%| mark=between positions 0.1 and 0.9 step 5em with|\\ -%| {\arrow{Stealth| |[length=2mm, blue]}}}}|\\ -%\textbf{Caution:} with a high number of samples, adding arrows in this way may cause the error message |! Dimension too big|. -% -% For example, the command\\ -% |\NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}]|\\ -% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\ -% | {-30}{30}|\\ -% generates the Nyquist plot in Figure \ref{simpleNyquistZPK}. -% -% \begin{figure} -% \begin{center} -% \NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}] {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10} {-30} {30} -% \cprotect\caption{\label{simpleNyquistZPK}Output of the |\NyquistZPK| macro.} -% \end{center} -% \end{figure} -% -% % \DescribeMacro{\NyquistTF} -% |\NyquistTF| \oarg{plot/\marg{opt},axes/\marg{opt}}\\ -% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\ -% \hspace*{2em}\marg{min-freq}\marg{max-freq} -% -% \noindent Nyquist plot of a transfer function given in TF format. Same mandatory arguments as |\BodeTF| and same optional arguments as |\NyquistZPK|. For example, the command\\ -% |\NyquistTF[plot/{green,thick,samples=500,postaction=decorate,|\\ -% | decoration={markings,|\\ -% | mark=between positions 0.1 and 0.9 step 5em|\\ -% | with{\arrow{Stealth[length=2mm, blue]}}}}]|\\ -% | {num/{10,2,2.6,0},den/{1,1,100.25}}|\\ -% | {-30}{30}|\\ -% generates the Nyquist plot in Figure \ref{simpleNyquistTF}. -% -% \begin{figure} -% \begin{center} -% \NyquistTF[plot/{green,thick,samples=500,postaction=decorate,decoration={markings,mark=between positions 0.1 and 0.9 step 5em with {\arrow{Stealth[length=2mm, blue]}}}}] {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01} {-30} {30} -% \cprotect\caption{\label{simpleNyquistTF}Output of the |\NyquistTF| macro with direction arrows. Increasing the number of samples can cause |decorations.markings| to throw errors.} -% \end{center} -% \end{figure} -% -% \DescribeEnv{NyquistPlot} -% |\begin{NyquistPlot}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\ -% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\ -% \hspace*{2em}|\addNyquist...|\\ -% \hspace*{1.5em}|\end{NyquistPlot}|\\ -% The |NyquistPlot| environment works in conjunction with the parametric function generator macros |\addNyquistZPKPlot| and |\addNyquistTFPlot|. The optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to: -% \begin{itemize} -% \item Tuples of the form |obj/{opt}|: -% \begin{itemize} -% \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment. -% \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |axis| environment. -% \item |commands/{opt}|: add any valid TikZ commands inside |axis| environment. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual. -% \end{itemize} -% \item Tuples of the form |{opt}| are passed directly to the |axis| environment. -% \end{itemize} -% The frequency limits are translated to the x-axis limits and the domain of the |axis| environment. -% -% \DescribeMacro{\addNyquistZPKPlot} -% |\addNyquistZPKPlot|\oarg{plot-options}\\ -% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}} -% -% \noindent Generates a twp parametric functions for the magnitude and the phase a transfer function in ZPK form. The generated magnitude and phase parametric functions are converted to real and imaginary part parametric functions and passed to the |\addplot| macro. This macro can be used inside any |axis| environment as long as a domain for the x-axis is supplied through either the |plot-options| interface or directly in the optional argument of the container |axis| environment. Use with the |NyquistPlot| environment supplied with this package is recommended. The mandatory argument is the same as |\BodeZPK|. -% -% \DescribeMacro{\addNyquistTFPlot} -% |\addNyquistTFPlot|\oarg{plot-options}\\ -% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}} -% -% \noindent Similar to |\addNyquistZPKPlot|, with a transfer function input in the TF form. -% -% \subsection{Nichols charts} -% \DescribeMacro{\NicholsZPK} -% |\NicholsZPK| \oarg{plot/\marg{opt},axes/\marg{opt}}\\ -% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\ -% \hspace*{2em}\marg{min-freq}\marg{max-freq} -% -% \noindent Nichols chart of a transfer function given in ZPK format. Same arguments as |\NyquistZPK|. -% -% \DescribeMacro{\NicholsTF} -% |\NicholsTF| \oarg{plot/\marg{opt},axes/\marg{opt}}\\ -% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\ -% \hspace*{2em}\marg{min-freq}\marg{max-freq} -% -% \noindent Nichols chart of a transfer function given in TF format. Same arguments as |\NyquistTF|. For example, the command\\ -% |\NicholsTF[plot/{green,thick,samples=2000}]|\\ -% | {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}|\\ -% | {0.001}{100}|\\ -% generates the Nichols chart in Figure \ref{simpleNicholsTF}. -% -% \begin{figure} -% \begin{center} -% \NicholsTF[plot/{green,thick,samples=2000}] {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01} {0.001} {100} -% \cprotect\caption{\label{simpleNicholsTF}Output of the |\NyquistZPK| macro.} -% \end{center} -% \end{figure} -% -% -% \DescribeEnv{NicholsChart} -% |\begin{NicholsChart}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\ -% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\ -% \hspace*{2em}|\addNichols...|\\ -% \hspace*{1.5em}|\end{NicholsChart}|\\ -% The |NicholsChart| environment works in conjunction with the parametric function generator macros |\addNicholsZPKChart| and |\addNicholsTFChart|. The optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to: -% \begin{itemize} -% \item Tuples of the form |obj/{opt}|: -% \begin{itemize} -% \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment. -% \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |axis| environment. -% \item |commands/{opt}|: add any valid TikZ commands inside |axis| environment. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual. -% \end{itemize} -% \item Tuples of the form |{opt}| are passed directly to the |axis| environment. -% \end{itemize} -% The frequency limits are translated to the x-axis limits and the domain of the |axis| environment. -% -% \DescribeMacro{\addNicholsZPKChart} -% |\addNicholsZPKChart|\oarg{plot-options}\\ -% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}} -% -% \noindent Generates a twp parametric functions for the magnitude and the phase a transfer function in ZPK form. The generated magnitude and phase parametric functions are passed to the |\addplot| macro. This macro can be used inside any |axis| environment as long as a domain for the x-axis is supplied through either the |plot-options| interface or directly in the optional argument of the container |axis| environment. Use with the |NicholsChart| environment supplied with this package is recommended. The mandatory argument is the same as |\BodeZPK|. -% -% \DescribeMacro{\addNicholsTFChart} -% |\addNicholsTFChart|\oarg{plot-options}\\ -% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}} -% -% \noindent Similar to |\addNicholsZPKChart|, with a transfer function input in the TF form. -% -% \StopEventually{\PrintIndex} -% \clearpage -% \section{Implementation} -% \subsection{Initialization} -% \begin{macro}{\n@mod} -% \begin{macro}{\n@pow} -% \begin{macro}{gnuplot@id} -% \begin{macro}{gnuplot@prefix} -% \changes{v1.0.3}{2021/11/03}{Added jobname to gnuplot prefix} -% \changes{v1.0.8}{2022/07/06}{Fixed issue \#6} -% This code is needed to support both |pgfplots| and |gnuplot| simultaneously. New macros are defined for the |pow| and |mod| functions to address differences between the two math engines. We start by processing the class options. -% \begin{macrocode} -\newif\if@pgfarg\@pgfargfalse -\DeclareOption{pgf}{ - \@pgfargtrue -} -\newif\if@declutterarg\@declutterargfalse -\DeclareOption{declutter}{ - \@declutterargtrue -} -\newif\if@radarg\@radargfalse -\DeclareOption{rad}{ - \@radargtrue -} -\newif\if@hzarg\@hzargfalse -\DeclareOption{Hz}{ - \@hzargtrue -} -\ProcessOptions\relax -% \end{macrocode} -% Then, we define two new macros to unify |pgfplots| and |gnuplot|. -% \begin{macrocode} -\newcommand{\n@mod}[2]{(#1)-(floor((#1)/(#2))*(#2))} -\if@pgfarg - \newcommand{\n@pow}[2]{(#1)^(#2)} - \pgfplotsset{ - trig format plots=rad - } -\else - \newcommand{\n@pow}[2]{(#1)**(#2)} -% \end{macrocode} -% Then, we create a counter so that a new data table is generated and for each new plot. If the plot macros have not changed, the tables, once generated, can be reused by |gnuplot|, which reduces compilation time. The |declutter| option is used to enable the |gnuplot| directory to declutter the working directory. -% \begin{macrocode} - \newcounter{gnuplot@id} - \setcounter{gnuplot@id}{0} - \if@declutterarg - \edef\bodeplot@prefix{gnuplot/\jobname} - \else - \edef\bodeplot@prefix{\jobname} - \fi - \tikzset{ - gnuplot@prefix/.style={ - id=\arabic{gnuplot@id}, - prefix=\bodeplot@prefix - } - } -% \end{macrocode} -% If the operating system is not Windows, and if the |declutter| option is not passed, we create the |gnuplot| folder if it does not already exist. \changes{v1.0.2}{2021/11/01}{Fixed issue \#1} -% \begin{macrocode} - \ifwindows\else - \if@declutterarg - \immediate\write18{mkdir -p gnuplot} - \fi - \fi -\fi -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \begin{macro}{bode@style} -% Default axis properties for all plot macros are collected in this |pgf| style. -% \begin{macrocode} -\pgfplotsset{ - bode@style/.style = { - label style={font=\footnotesize}, - tick label style={font=\footnotesize}, - grid=both, - major grid style={color=gray!80}, - minor grid style={color=gray!20}, - x label style={at={(ticklabel cs:0.5)},anchor=near ticklabel}, - y label style={at={(ticklabel cs:0.5)},anchor=near ticklabel}, - scale only axis, - samples=200, - width=5cm, - log basis x=10 - } -} -% \end{macrocode} -% \end{macro} -% \begin{macro}{freq@filter} -% \begin{macro}{freq@label} -% \begin{macro}{freq@scale} -% \begin{macro}{ph@scale} -% \begin{macro}{ph@x@label} -% \begin{macro}{ph@y@label} -% These macros handle the |Hz| and |rad| class options and two new |pgf| keys named |frequency unit| and |phase unit| for conversion of frequency and phase units, respectively. \changes{v1.1.1}{2022/07/31}{New macros to enable `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\pgfplotsset{freq@filter/.style = {}} -\def\freq@scale{1} -\pgfplotsset{freq@label/.style = {xlabel = {Frequency (rad/s)}}} -\pgfplotsset{ph@x@label/.style = {xlabel={Phase (deg)}}} -\pgfplotsset{ph@y@label/.style = {ylabel={Phase (deg)}}} -\def\ph@scale{180/pi} -\if@radarg - \pgfplotsset{ph@y@label/.style = {ylabel={Phase (rad)}}} - \pgfplotsset{ph@x@label/.style = {xlabel={Phase (rad)}}} - \def\ph@scale{1} -\fi -\if@hzarg - \def\freq@scale{2*pi} - \pgfplotsset{freq@label/.style = {xlabel = {Frequency (Hz)}}} - \if@pgfarg - \pgfplotsset{freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}} - \fi -\fi -\tikzset{ - phase unit/.initial={deg}, - phase unit/.default={deg}, - phase unit/.is choice, - phase unit/deg/.code={ - \renewcommand{\ph@scale}{180/pi} - \pgfplotsset{ph@x@label/.style = {xlabel={Phase (deg)}}} - \pgfplotsset{ph@y@label/.style = {ylabel={Phase (deg)}}} - }, - phase unit/rad/.code={ - \renewcommand{\ph@scale}{1} - \pgfplotsset{ph@y@label/.style = {ylabel={Phase (rad)}}} - \pgfplotsset{ph@x@label/.style = {xlabel={Phase (rad)}}} - }, - frequency unit/.initial={rad}, - frequency unit/.default={rad}, - frequency unit/.is choice, - frequency unit/Hz/.code={ - \renewcommand{\freq@scale}{2*pi} - \pgfplotsset{freq@label/.style = {xlabel = {Frequency (Hz)}}} - \if@pgfarg - \pgfplotsset{freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}} - \fi - }, - frequency unit/rad/.code={ - \renewcommand{\freq@scale}{1} - \pgfplotsset{freq@label/.style = {xlabel = {Frequency (rad/s)}}} - } -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \begin{macro}{get@interval@start} -% \begin{macro}{get@interval@end} -% Internal macros to extract start and end frequency limits from domain specifications.\changes{v1.1.1}{2022/07/31}{New macros to enable `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\def\get@interval@start#1:#2\@nil{#1} -\def\get@interval@end#1:#2\@nil{#2} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \subsection{Parametric function generators for poles, zeros, gains, and delays.} -% All calculations are carried out assuming that frequeny inputs are in |rad/s|. Magnitude outputs are in |dB| and phase outputs are in degrees or radians, depending on the value of |\ph@scale|. -% \begin{macro}{\MagK} -% \begin{macro}{\MagKAsymp} -% \begin{macro}{\MagKLin} -% \begin{macro}{\PhK} -% \begin{macro}{\PhKAsymp} -% \begin{macro}{\PhKLin} -% True, linear, and asymptotic magnitude and phase parametric functions for a pure gain $G(s)=k+0\mathrm{i}$. The macros take two arguments corresponding to real and imaginary part of the gain to facilitate code reuse between delays, gains, poles, and zeros, but only real gains are supported. The second argument, if supplied, is ignored. -% \begin{macrocode} -\newcommand*{\MagK}[2]{(20*log10(abs(#1)))} -\newcommand*{\MagKAsymp}{\MagK} -\newcommand*{\MagKLin}{\MagK} -\newcommand*{\PhK}[2]{((#1<0?-pi:0)*\ph@scale)} -\newcommand*{\PhKAsymp}{\PhK} -\newcommand*{\PhKLin}{\PhK} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \begin{macro}{\PhKAsymp} -% \begin{macro}{\PhKLin} -% True magnitude and phase parametric functions for a pure delay $G(s)=e^{-Ts}$. The macros take two arguments corresponding to real and imaginary part of the gain to facilitate code reuse between delays, gains, poles, and zeros, but only real gains are supported. The second argument, if supplied, is ignored. -% \begin{macrocode} -\newcommand*{\MagDel}[2]{0} -\newcommand*{\PhDel}[2]{(-#1*t*\ph@scale)} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \begin{macro}{\MagPole} -% \begin{macro}{\MagPoleAsymp} -% \begin{macro}{\MagPoleLin} -% \begin{macro}{\PhPole} -% \begin{macro}{\PhPoleAsymp} -% \begin{macro}{\PhPoleLin} -% These macros are the building blocks for most of the plotting functions provided by this package. We start with Parametric function for the true magnitude of a complex pole. -% \begin{macrocode} -\newcommand*{\MagPole}[2] - {(-20*log10(sqrt(\n@pow{#1}{2} + \n@pow{t - (#2)}{2})))} -% \end{macrocode} -% Parametric function for linear approximation of the magnitude of a complex pole. -% \begin{macrocode} -\newcommand*{\MagPoleLin}[2]{(t < sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) ? - -20*log10(sqrt(\n@pow{#1}{2} + \n@pow{#2}{2})) : - -20*log10(t) - )} -% \end{macrocode} -% Parametric function for asymptotic approximation of the magnitude of a complex pole, same as linear approximation. -% \begin{macrocode} -\newcommand*{\MagPoleAsymp}{\MagPoleLin} -% \end{macrocode} -% Parametric function for the true phase of a complex pole. -% \begin{macrocode} -\newcommand*{\PhPole}[2]{((#1 > 0 ? (#2 > 0 ? - (\n@mod{-atan2((t - (#2)),-(#1))}{2*pi}) : - (-atan2((t - (#2)),-(#1)))) : - (-atan2((t - (#2)),-(#1))))*\ph@scale)} -% \end{macrocode} -% Parametric function for linear approximation of the phase of a complex pole. -% \begin{macrocode} -\newcommand*{\PhPoleLin}[2]{ - ((abs(#1)+abs(#2) == 0 ? -pi/2 : - (t < (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) / - (\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + \n@pow{#2}{2}))})) ? - (-atan2(-(#2),-(#1))) : - (t >= (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) * - (\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + \n@pow{#2}{2}))})) ? - (#2>0?(#1>0?3*pi/2:-pi/2):-pi/2) : - (-atan2(-(#2),-(#1)) + (log10(t/(sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) / - (\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + - \n@pow{#2}{2}))}))))*((#2>0?(#1>0?3*pi/2:-pi/2):-pi/2) + atan2(-(#2),-(#1)))/ - (log10(\n@pow{10}{sqrt((4*\n@pow{#1}{2})/ - (\n@pow{#1}{2} + \n@pow{#2}{2}))}))))))*\ph@scale)} -% \end{macrocode} -% Parametric function for asymptotic approximation of the phase of a complex pole. -% \begin{macrocode} -\newcommand*{\PhPoleAsymp}[2]{((t < (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2})) ? - (-atan2(-(#2),-(#1))) : - (#2>0?(#1>0?3*pi/2:-pi/2):-pi/2))*\ph@scale)} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \begin{macro}{\MagZero} -% \begin{macro}{\MagZeroAsymp} -% \begin{macro}{\MagZeroLin} -% \begin{macro}{\PhZero} -% \begin{macro}{\PhZeroAsymp} -% \begin{macro}{\PhZeroLin} -% Plots of zeros are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3). -% \begin{macrocode} -\newcommand*{\MagZero}{0-\MagPole} -\newcommand*{\MagZeroLin}{0-\MagPoleLin} -\newcommand*{\MagZeroAsymp}{0-\MagPoleAsymp} -\newcommand*{\PhZero}{0-\PhPole} -\newcommand*{\PhZeroLin}{0-\PhPoleLin} -\newcommand*{\PhZeroAsymp}{0-\PhPoleAsymp} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \subsection{Second order systems.} -% Although second order systems can be dealt with using the macros defined so far, the following dedicated macros for second order systems involve less computation. -% \begin{macro}{\MagCSPoles} -% \begin{macro}{\MagCSPolesAsymp} -% \begin{macro}{\MagCSPolesLin} -% \begin{macro}{\PhCSPoles} -% \begin{macro}{\PhCSPolesAsymp} -% \begin{macro}{\PhCSPolesLin} -% \begin{macro}{\MagCSZeros} -% \begin{macro}{\MagCSZerosAsymp} -% \begin{macro}{\MagCSZerosLin} -% \begin{macro}{\PhCSZeros} -% \begin{macro}{\PhCSZerosAsymp} -% \begin{macro}{\PhCSZerosLin} -% Consider the canonical second order transfer function $G(s) = \frac{1}{s^2 + 2 \zeta w_n s + w_n^2}$. We start with true, linear, and asymptotic magnitude plots for this transfer function. -% \begin{macrocode} -\newcommand*{\MagCSPoles}[2]{(-20*log10(sqrt(\n@pow{\n@pow{#2}{2} - - \n@pow{t}{2}}{2} + \n@pow{2*#1*#2*t}{2})))} -\newcommand*{\MagCSPolesLin}[2]{(t < #2 ? -40*log10(#2) : - 40*log10(t))} -\newcommand*{\MagCSPolesAsymp}{\MagCSPolesLin} -% \end{macrocode} -% Then, we have true, linear, and asymptotic phase plots for the canonical second order transfer function. -% \begin{macrocode} -\newcommand*{\PhCSPoles}[2]{((-atan2((2*(#1)*(#2)*t),(\n@pow{#2}{2} - - \n@pow{t}{2})))*\ph@scale)} -\newcommand*{\PhCSPolesLin}[2]{((t < (#2 / (\n@pow{10}{abs(#1)})) ? - 0 : - (t >= (#2 * (\n@pow{10}{abs(#1)})) ? - (#1>0 ? -pi : pi) : - (#1>0 ? (-pi*(log10(t*(\n@pow{10}{#1})/#2))/(2*#1)) : - (pi*(log10(t*(\n@pow{10}{abs(#1)})/#2))/(2*abs(#1))))))*\ph@scale)} -\newcommand*{\PhCSPolesAsymp}[2]{((#1>0?(t<#2?0:-pi):(t<#2?0:pi))*\ph@scale)} -% \end{macrocode} -% Plots of the inverse function $G(s)=s^2+2\zeta\omega_n s+\omega_n^2$ are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3). -% \begin{macrocode} -\newcommand*{\MagCSZeros}{0-\MagCSPoles} -\newcommand*{\MagCSZerosLin}{0-\MagCSPolesLin} -\newcommand*{\MagCSZerosAsymp}{0-\MagCSPolesAsymp} -\newcommand*{\PhCSZeros}{0-\PhCSPoles} -\newcommand*{\PhCSZerosLin}{0-\PhCSPolesLin} -\newcommand*{\PhCSZerosAsymp}{0-\PhCSPolesAsymp} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \begin{macro}{\MagCSPolesPeak} -% \begin{macro}{\MagCSZerosPeak} -% These macros are used to add a resonant peak to linear and asymptotic plots of canonical second order poles and zeros. Since the plots are parametric, a separate |\draw| command is needed to add a vertical arrow. -% \begin{macrocode} -\newcommand*{\MagCSPolesPeak}[3][]{ - \draw[#1,->] (axis cs:{#3},{-40*log10(#3)}) -- - (axis cs:{#3},{-40*log10(#3)-20*log10(2*abs(#2))}) -} -\newcommand*{\MagCSZerosPeak}[3][]{ - \draw[#1,->] (axis cs:{#3},{40*log10(#3)}) -- - (axis cs:{#3},{40*log10(#3)+20*log10(2*abs(#2))}) -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \begin{macro}{\MagSOPoles} -% \begin{macro}{\MagSOPolesAsymp} -% \begin{macro}{\MagSOPolesLin} -% \begin{macro}{\PhSOPoles} -% \begin{macro}{\PhSOPolesAsymp} -% \begin{macro}{\PhSOPolesLin} -% \begin{macro}{\MagSOZeros} -% \begin{macro}{\MagSOZerosAsymp} -% \begin{macro}{\MagSOZerosLin} -% \begin{macro}{\PhSOZeros} -% \begin{macro}{\PhSOZerosAsymp} -% \begin{macro}{\PhSOZerosLin} -% Consider a general second order transfer function $G(s) = \frac{1}{s^2 + a s + b}$. We start with true, linear, and asymptotic magnitude plots for this transfer function. -% \begin{macrocode} -\newcommand*{\MagSOPoles}[2]{ - (-20*log10(sqrt(\n@pow{#2 - \n@pow{t}{2}}{2} + \n@pow{#1*t}{2})))} -\newcommand*{\MagSOPolesLin}[2]{ - (t < sqrt(abs(#2)) ? -20*log10(abs(#2)) : - 40*log10(t))} -\newcommand*{\MagSOPolesAsymp}{\MagSOPolesLin} -% \end{macrocode} -% Then, we have true, linear, and asymptotic phase plots for the general second order transfer function. -% \begin{macrocode} -\newcommand*{\PhSOPoles}[2]{((-atan2((#1)*t,((#2) - \n@pow{t}{2})))*\ph@scale)} -\newcommand*{\PhSOPolesLin}[2]{((#2>0 ? - \PhCSPolesLin{(#1/(2*sqrt(#2)))}{(sqrt(#2))} : - (#1>0 ? -pi : pi))*\ph@scale)} -\newcommand*{\PhSOPolesAsymp}[2]{((#2>0 ? - \PhCSPolesAsymp{(#1/(2*sqrt(#2)))}{(sqrt(#2))} : - (#1>0 ? -pi : pi))*\ph@scale)} -% \end{macrocode} -% Plots of the inverse function $G(s)=s^2+as+b$ are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3). -% \begin{macrocode} -\newcommand*{\MagSOZeros}{0-\MagSOPoles} -\newcommand*{\MagSOZerosLin}{0-\MagSOPolesLin} -\newcommand*{\MagSOZerosAsymp}{0-\MagSOPolesAsymp} -\newcommand*{\PhSOZeros}{0-\PhSOPoles} -\newcommand*{\PhSOZerosLin}{0-\PhSOPolesLin} -\newcommand*{\PhSOZerosAsymp}{0-\PhSOPolesAsymp} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% \begin{macro}{\MagSOPolesPeak} -% \begin{macro}{\MagSOZerosPeak} -% These macros are used to add a resonant peak to linear and asymptotic plots of general second order poles and zeros. Since the plots are parametric, a separate |\draw| command is needed to add a vertical arrow. -% \begin{macrocode} -\newcommand*{\MagSOPolesPeak}[3][]{ - \draw[#1,->] (axis cs:{sqrt(abs(#3))},{-20*log10(abs(#3))}) -- - (axis cs:{sqrt(abs(#3))},{-20*log10(abs(#3)) - - 20*log10(abs(#2/sqrt(abs(#3))))}); -} -\newcommand*{\MagSOZerosPeak}[3][]{ - \draw[#1,->] (axis cs:{sqrt(abs(#3))},{20*log10(abs(#3))}) -- - (axis cs:{sqrt(abs(#3))},{20*log10(abs(#3)) + - 20*log10(abs(#2/sqrt(abs(#3))))}); -} -% \end{macrocode} -% \end{macro} -% \end{macro} -% \subsection{Commands for Bode plots} -% \subsubsection{User macros} -% \begin{macro}{\BodeZPK} -% This macro takes lists of complex poles and zeros of the form |{re,im}|, and values of gain and delay as inputs and constructs parametric functions for the Bode magnitude and phase plots. This is done by adding together the parametric functions generated by the macros for individual zeros, poles, gain, and delay, described above. The parametric functions are then plotted in a |tikzpicture| environment using the |\addplot| macro. Unless the package is loaded with the option |pgf|, the parametric functions are evaluated using |gnuplot|. \changes{v1.0.1}{2021/10/29}{Pass arbitrary TikZ commands as options.} -% \begin{macrocode} -\newcommand{\BodeZPK}[4][approx/true]{ -% \end{macrocode} -% Most of the work is done by the |\parse@opt| and the |\build@ZPK@plot| macros, described in the 'Internal macros' section. The former is used to parse the optional arguments and the latter to extract poles, zeros, gain, and delay from the first mandatory argument and to generate macros |\func@mag| and |\func@ph| that hold the magnitude and phase parametric functions. The |\noexpand| macros below are needed to so that only the macro |\opt@group| is expanded. \changes{v1.0.3}{2021/11/03}{Added Tikz option}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} - \parse@opt{#1} - \gdef\func@mag{} - \gdef\func@ph{} - \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]} - \temp@cmd - \build@ZPK@plot{\func@mag}{\func@ph}{\opt@approx}{#2} - \edef\temp@cmd{\noexpand\begin{groupplot}[ - bode@style, - xmin=#3, - xmax=#4, - domain=#3*\freq@scale:#4*\freq@scale, - height=2.5cm, - xmode=log, - group style = {group size = 1 by 2,vertical sep=0.25cm}, - \opt@group - ]} - \temp@cmd -% \end{macrocode} -% To ensure frequency tick marks on magnitude and the phase plots are always aligned, we use the |groupplot| library. The |\noexpand| and |\unexpanded\expandafter| macros below are used to expand macros in the plot and group optional arguments. -% \begin{macrocode} - \edef\temp@mag@cmd{\noexpand\nextgroupplot [ylabel={Gain (dB)}, xmajorticks=false, \optmag@axes] - \noexpand\addplot [freq@filter, variable=t, thick, \optmag@plot]} - \edef\temp@ph@cmd{\noexpand\nextgroupplot [ph@y@label, freq@label, \optph@axes] - \noexpand\addplot [freq@filter, variable=t, thick, \optph@plot]} - \if@pgfarg - \temp@mag@cmd {\func@mag}; - \optmag@commands - \temp@ph@cmd {\func@ph}; - \optph@commands - \else -% \end{macrocode} -% In |gnuplot| mode, we increment the |gnuplot@id| counter before every plot to make sure that new and reusable |.gnuplot| and |.table| files are generated for every plot. We use |raw gnuplot| to make sure that the tables generated by |gnuplot| use the correct phase and frequency units as supplied by the user. -% \begin{macrocode} - \stepcounter{gnuplot@id} - \temp@mag@cmd gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set xrange [#3*\freq@scale:#4*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot \func@mag; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2); - }; - \optmag@commands - \stepcounter{gnuplot@id} - \temp@ph@cmd gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set xrange [#3*\freq@scale:#4*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot \func@ph; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2); - }; - \optph@commands - \fi - \end{groupplot} - \end{tikzpicture} -} -% \end{macrocode} -% \end{macro} -% \begin{macro}{\BodeTF} -% Implementation of this macro is very similar to the |\BodeZPK| macro above. The only difference is the lack of linear and asymptotic plots and slightly different parsing of the mandatory arguments. \changes{v1.0.3}{2021/11/03}{Added Tikz option} \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newcommand{\BodeTF}[4][]{ - \parse@opt{#1} - \gdef\func@mag{} - \gdef\func@ph{} - \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]} - \temp@cmd - \build@TF@plot{\func@mag}{\func@ph}{#2} - \edef\temp@cmd{\noexpand\begin{groupplot}[ - bode@style, - xmin=#3, - xmax=#4, - domain=#3*\freq@scale:#4*\freq@scale, - height=2.5cm, - xmode=log, - group style = {group size = 1 by 2,vertical sep=0.25cm}, - \opt@group - ]} - \temp@cmd - \edef\temp@mag@cmd{\noexpand\nextgroupplot [ylabel={Gain (dB)}, xmajorticks=false, \optmag@axes] - \noexpand\addplot [freq@filter, variable=t, thick, \optmag@plot]} - \edef\temp@ph@cmd{\noexpand\nextgroupplot [ph@y@label, freq@label, \optph@axes] - \noexpand\addplot [freq@filter, variable=t, thick, \optph@plot]} - \if@pgfarg - \temp@mag@cmd {\func@mag}; - \optmag@commands - \temp@ph@cmd {\n@mod{\func@ph}{2*pi*\ph@scale}}; - \optph@commands - \else - \stepcounter{gnuplot@id} - \temp@mag@cmd gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set xrange [#3*\freq@scale:#4*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot \func@mag; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2); - }; - \optmag@commands - \stepcounter{gnuplot@id} - \temp@ph@cmd gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set trange [#3*\freq@scale:#4*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot '+' using (t) : ((\func@ph)/(\ph@scale)) smooth unwrap; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2*\ph@scale); - }; - \optph@commands - \fi - \end{groupplot} - \end{tikzpicture} -} -% \end{macrocode} -% \end{macro} -% \begin{macro}{\addBodeZPKPlots} -% This macro is designed to issues multiple |\addplot| macros for the same set of poles, zeros, gain, and delay. All of the work is done by the |\build@ZPK@plot| macro. \changes{v1.0.1}{2021/10/29}{Improved optional argument handling.}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newcommand{\addBodeZPKPlots}[3][true/{}]{ - \foreach \approx/\opt in {#1} { - \gdef\plot@macro{} - \gdef\temp@macro{} - \ifnum\pdf@strcmp{#2}{phase}=0 - \build@ZPK@plot{\temp@macro}{\plot@macro}{\approx}{#3} - \else - \build@ZPK@plot{\plot@macro}{\temp@macro}{\approx}{#3} - \fi - \edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}} - \edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil} - \edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil} - \if@pgfarg - \edef\temp@cmd{\noexpand\addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, thick, \opt]} - \temp@cmd {\plot@macro}; - \else - \stepcounter{gnuplot@id} - \edef\temp@cmd{\noexpand\addplot [variable=t, thick, \opt]} - \temp@cmd gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set xrange [\domain@start*\freq@scale:\domain@end*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot \plot@macro; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2); - }; - \fi - } -} -% \end{macrocode} -%\end{macro} -% \begin{macro}{\addBodeTFPlot} -% This macro is designed to issues a single |\addplot| macros for the set of coefficients and delay. All of the work is done by the |\build@TF@plot| macro. \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newcommand{\addBodeTFPlot}[3][thick]{ - \gdef\plot@macro{} - \gdef\temp@macro{} - \ifnum\pdf@strcmp{#2}{phase}=0 - \build@TF@plot{\temp@macro}{\plot@macro}{#3} - \else - \build@TF@plot{\plot@macro}{\temp@macro}{#3} - \fi - \edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}} - \edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil} - \edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil} - \if@pgfarg - \ifnum\pdf@strcmp{#2}{phase}=0 - \addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1]{\n@mod{\plot@macro}{2*pi}}; - \else - \addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1]{\plot@macro}; - \fi - \else - \stepcounter{gnuplot@id} - \ifnum\pdf@strcmp{#2}{phase}=0 - \addplot [variable=t, #1] gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set trange [\domain@start*\freq@scale:\domain@end*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot '+' using (t) : ((\plot@macro)/(\ph@scale)) smooth unwrap; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2*\ph@scale); - }; - \else - \addplot [variable=t, #1] gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set xrange [\domain@start*\freq@scale:\domain@end*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot \plot@macro; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2); - }; - \fi - \fi -} -% \end{macrocode} -%\end{macro} -% \begin{macro}{\addBodeComponentPlot} -% This macro is designed to issue a single |\addplot| macro capable of plotting linear combinations of the basic components described in Section \ref{sec:BasicComponents}. The only work to do here is to handle the |pgf| package option.\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newcommand{\addBodeComponentPlot}[2][thick]{ - \edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}} - \edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil} - \edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil} - \if@pgfarg - \addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1] {#2}; - \else - \stepcounter{gnuplot@id} - \addplot [variable=t, #1] gnuplot [raw gnuplot, gnuplot@prefix] - { set table $meta; - set dummy t; - set logscale x 10; - set xrange [\domain@start*\freq@scale:\domain@end*\freq@scale]; - set samples \pgfkeysvalueof{/pgfplots/samples}; - plot #2; - set table "\bodeplot@prefix\arabic{gnuplot@id}.table"; - plot "$meta" using ($1/(\freq@scale)):($2); - }; - \fi -} -% \end{macrocode} -%\end{macro} -% \begin{environment}{BodePhPlot} -% An environment to host phase plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newenvironment{BodePhPlot}[3][]{ - \parse@env@opt{#1} - \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}] - \noexpand\begin{semilogxaxis}[ - ph@y@label, - freq@label, - bode@style, - xmin={#2}, - xmax={#3}, - domain=#2:#3, - height=2.5cm, - \unexpanded\expandafter{\opt@axes} - ] - } - \temp@cmd -}{ - \end{semilogxaxis} - \end{tikzpicture} -} -% \end{macrocode} -% \end{environment} -% \begin{environment}{BodeMagPlot} -% An environment to host magnitude plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newenvironment{BodeMagPlot}[3][]{ - \parse@env@opt{#1} - \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}] - \noexpand\begin{semilogxaxis}[ - bode@style, - freq@label, - xmin={#2}, - xmax={#3}, - domain=#2:#3, - height=2.5cm, - ylabel={Gain (dB)}, - \unexpanded\expandafter{\opt@axes} - ] - } - \temp@cmd -}{ - \end{semilogxaxis} - \end{tikzpicture} -} -% \end{macrocode} -% \end{environment} -% \begin{environment}{BodePlot} -% Same as |BodeMagPlot|. The |BodePlot| environment is deprecated as of v1.1.0, please use the |BodePhPlot| and |BodeMagPlot| environments instead.\changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.0}{2022/02/20}{Deprecated BodePlot environment}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newenvironment{BodePlot}[3][]{ - \parse@env@opt{#1} - \edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}] - \noexpand\begin{semilogxaxis}[ - bode@style, - freq@label, - xmin={#2}, - xmax={#3}, - domain=#2:#3, - height=2.5cm, - \unexpanded\expandafter{\opt@axes} - ] - } - \temp@cmd -}{ - \end{semilogxaxis} - \end{tikzpicture} -} -% \end{macrocode} -% \end{environment} -% \subsubsection{Internal macros} -% \begin{macro}{\add@feature} -% This is an internal macro to add a basic component (pole, zero, gain, or delay), described using one of the macros in Section \ref{sec:BasicComponents} (input |#2|), to a parametric function stored in a global macro (input |#1|). The basic component value (input |#3|) is a complex number of the form |{re,im}|. If the imaginary part is missing, it is assumed to be zero. Implementation made possible by \href{https://tex.stackexchange.com/a/619637/110602}{this StackExchange answer}. -% \begin{macrocode} -\newcommand*{\add@feature}[3]{ - \ifcat$\detokenize\expandafter{#1}$ - \xdef#1{\unexpanded\expandafter{#1 0+#2}} - \else - \xdef#1{\unexpanded\expandafter{#1+#2}} - \fi - \foreach \y [count=\n] in #3 { - \xdef#1{\unexpanded\expandafter{#1}{\y}} - \xdef\Last@LoopValue{\n} - } - \ifnum\Last@LoopValue=1 - \xdef#1{\unexpanded\expandafter{#1}{0}} - \fi -} -% \end{macrocode} -%\end{macro} -% \begin{macro}{\build@ZPK@plot} -% This is an internal macro to build parametric Bode magnitude and phase plots by concatenating basic component (pole, zero, gain, or delay) macros (Section \ref{sec:BasicComponents}) to global magnitude and phase macros (inputs |#1| and |#2|). The |\add@feature| macro is used to do the concatenation. The basic component macros are inferred from a |feature/{values}| list, where |feature| is one of |z|,|p|,|k|, and |d|, for zeros, poles, gain, and delay, respectively, and |{values}| is a comma separated list of comma separated lists (complex numbers of the form |{re,im}|). If the imaginary part is missing, it is assumed to be zero. -% \begin{macrocode} -\newcommand{\build@ZPK@plot}[4]{ - \foreach \feature/\values in {#4} { - \ifnum\pdf@strcmp{\feature}{z}=0 - \foreach \z in \values { - \ifnum\pdf@strcmp{#3}{linear}=0 - \add@feature{#2}{\PhZeroLin}{\z} - \add@feature{#1}{\MagZeroLin}{\z} - \else - \ifnum\pdf@strcmp{#3}{asymptotic}=0 - \add@feature{#2}{\PhZeroAsymp}{\z} - \add@feature{#1}{\MagZeroAsymp}{\z} - \else - \add@feature{#2}{\PhZero}{\z} - \add@feature{#1}{\MagZero}{\z} - \fi - \fi - } - \fi - \ifnum\pdf@strcmp{\feature}{p}=0 - \foreach \p in \values { - \ifnum\pdf@strcmp{#3}{linear}=0 - \add@feature{#2}{\PhPoleLin}{\p} - \add@feature{#1}{\MagPoleLin}{\p} - \else - \ifnum\pdf@strcmp{#3}{asymptotic}=0 - \add@feature{#2}{\PhPoleAsymp}{\p} - \add@feature{#1}{\MagPoleAsymp}{\p} - \else - \add@feature{#2}{\PhPole}{\p} - \add@feature{#1}{\MagPole}{\p} - \fi - \fi - } - \fi - \ifnum\pdf@strcmp{\feature}{k}=0 - \ifnum\pdf@strcmp{#3}{linear}=0 - \add@feature{#2}{\PhKLin}{\values} - \add@feature{#1}{\MagKLin}{\values} - \else - \ifnum\pdf@strcmp{#3}{asymptotic}=0 - \add@feature{#2}{\PhKAsymp}{\values} - \add@feature{#1}{\MagKAsymp}{\values} - \else - \add@feature{#2}{\PhK}{\values} - \add@feature{#1}{\MagK}{\values} - \fi - \fi - \fi - \ifnum\pdf@strcmp{\feature}{d}=0 - \ifnum\pdf@strcmp{#3}{linear}=0 - \PackageError {bodeplot} {Linear approximation for pure delays is not - supported.} {Plot the true Bode plot using `true' instead of `linear'.} - \else - \ifnum\pdf@strcmp{#3}{asymptotic}=0 - \PackageError {bodeplot} {Asymptotic approximation for pure delays is not - supported.} {Plot the true Bode plot using `true' instead of `asymptotic'.} - \else - \ifdim\values pt < 0pt - \PackageError {bodeplot} {Delay needs to be a positive number.} - \fi - \add@feature{#2}{\PhDel}{\values} - \add@feature{#1}{\MagDel}{\values} - \fi - \fi - \fi - } -} -% \end{macrocode} -%\end{macro} -% \begin{macro}{\build@TF@plot} -% This is an internal macro to build parametric Bode magnitude and phase functions by computing the magnitude and the phase given numerator and denominator coefficients and delay (input |#3|). The functions are assigned to user-supplied global magnitude and phase macros (inputs |#1| and |#2|). \changes{v1.0.8}{2022/07/05}{Included phase due to delay in wrapping.}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively} -% \begin{macrocode} -\newcommand{\build@TF@plot}[3]{ - \gdef\num@real{0} - \gdef\num@im{0} - \gdef\den@real{0} - \gdef\den@im{0} - \gdef\loop@delay{0} - \foreach \feature/\values in {#3} { - \ifnum\pdf@strcmp{\feature}{num}=0 - \foreach \numcoeff [count=\numpow] in \values { - \xdef\num@degree{\numpow} - } - \foreach \numcoeff [count=\numpow] in \values { - \pgfmathtruncatemacro{\currentdegree}{\num@degree-\numpow} - \ifnum\currentdegree = 0 - \xdef\num@real{\num@real+\numcoeff} - \else - \ifodd\currentdegree - \xdef\num@im{\num@im+(\numcoeff*(\n@pow{-1}{(\currentdegree-1)/2})*% - (\n@pow{t}{\currentdegree}))} - \else - \xdef\num@real{\num@real+(\numcoeff*(\n@pow{-1}{(\currentdegree)/2})*% - (\n@pow{t}{\currentdegree}))} - \fi - \fi - } - \fi - \ifnum\pdf@strcmp{\feature}{den}=0 - \foreach \dencoeff [count=\denpow] in \values { - \xdef\den@degree{\denpow} - } - \foreach \dencoeff [count=\denpow] in \values { - \pgfmathtruncatemacro{\currentdegree}{\den@degree-\denpow} - \ifnum\currentdegree = 0 - \xdef\den@real{\den@real+\dencoeff} - \else - \ifodd\currentdegree - \xdef\den@im{\den@im+(\dencoeff*(\n@pow{-1}{(\currentdegree-1)/2})*% - (\n@pow{t}{\currentdegree}))} - \else - \xdef\den@real{\den@real+(\dencoeff*(\n@pow{-1}{(\currentdegree)/2})*% - (\n@pow{t}{\currentdegree}))} - \fi - \fi + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bodeplot/bodeplot.dtx at main · rlkamalapurkar/bodeplot + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Skip to content + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+ + + + + +
+ + + + + + + + + +
+ + + + + + + + + + + + + + + + + + +
+ +
+ + + + rlkamalapurkar  /   + bodeplot  /   + +
+
+ + + +
+ + +
+
+ Clear Command Palette +
+
+ + + +
+
+ Tip: + Type # to search pull requests +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type # to search issues +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type # to search discussions +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type ! to search projects +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type @ to search teams +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type @ to search people and organizations +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type > to activate command mode +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Go to your accessibility settings to change your keyboard shortcuts +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type author:@me to search your content +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:pr to filter to pull requests +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:issue to filter to issues +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:project to filter to projects +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:open to filter to open content +
+
+ Type ? for help and tips +
+
+
+ +
+ +
+
+ We’ve encountered an error and some results aren't available at this time. Type a new search or try again later. +
+
+ + No results matched your search + + + + + + + + + + +
+ + + + + Search for issues and pull requests + + # + + + + Search for issues, pull requests, discussions, and projects + + # + + + + Search for organizations, repositories, and users + + @ + + + + Search for projects + + ! + + + + Search for files + + / + + + + Activate command mode + + > + + + + Search your issues, pull requests, and discussions + + # author:@me + + + + Search your issues, pull requests, and discussions + + # author:@me + + + + Filter to pull requests + + # is:pr + + + + Filter to issues + + # is:issue + + + + Filter to discussions + + # is:discussion + + + + Filter to projects + + # is:project + + + + Filter to open issues, pull requests, and discussions + + # is:open + + + + + + + + + + + + + + + + +
+
+
+ +
+ + + + + + + + + + +
+ + +
+
+
+ + + + + + + + + + +
+ +
+ +
+ +
+ + + + / + + bodeplot + + + Public +
+ + +
+ +
    + +
  • +
    +
    +
    +
  • + + +
  • + +
    + + + + + Unwatch + + + + + 1 + + + +
    +
    +

    Notifications

    + +
    + +
    +
    + + + + + + + + +
    + + +
    + + + + + Get push notifications on iOS or Android. + +
    +
    +
    +
    + + + + +
    +
    +
    + + + +
  • + +
  • +
    + Fork + 1 + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
  • + +
  • + + +
    +
    +
    + + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
    +
    +
    + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
    +
  • + + + +
+ +
+ +
+
+ + + + + + +
+ + + + +
+ Open in github.dev + Open in a new github.dev tab + + + + + + +
+ + +
+ + + + + + + + +Permalink + +
+ +
+
+ + + main + + + + +
+
+
+ Switch branches/tags + +
+ + + +
+ +
+ +
+ + +
+ +
+ + + + + + + + + + + + + + + + + +
+ + +
+
+
+
+ +
+ +
+ + +
+ +
+
+
+

Name already in use

+
+
+ +
+
+
+
+ +
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? +
+ +
+
+ + +
+
+ + + + Go to file + +
+ + + + +
+
+
+ + + + + + + + + +
+ +
+
+ + + +
+ + + + + + +
+
+ + Latest commit + 3746d16 + Oct 30, 2022 + + + + + + History + + +
+
+ +
+ +
+
+ + + 1 + + contributor + + +
+ +

+ Users who have contributed to this file +

+
+ + + + + + +
+
+
+
+ + + + + + + + + + + + + +
+ +
+ + +
+ + 2120 lines (2091 sloc) + + 95.6 KB +
+ +
+ + + + +
+ +
+
+
+
+ +
+ +
+
+
+ + + +
+ + + + + + + + + +
+ + +
+ +
+
+ +
+ +
+
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
% \iffalse meta-comment
%
% Copyright (C) 2021 by Rushikesh Kamalapurkar <rlkamalapurkar@gmail.com>
% -----------------------------------------------------------
%
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3c of this license
% or (at your option) any later version. The latest version of this
% license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2006/05/20 or later.
%
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[2006/05/20]
%<package>\ProvidesPackage{bodeplot}
%<package>\RequirePackage{pdftexcmds}
%<package>\RequirePackage{ifplatform}
%<package>\RequirePackage{environ}
%<package>\RequirePackage{pgfplots}
%<package> \pgfplotsset{compat=1.18}
%<package> \usepgfplotslibrary{groupplots}
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{cprotect}
\usepackage[declutter]{bodeplot}
\usepackage[colorlinks]{hyperref}
\usepackage{iftex}
\iftutex % LuaTeX, XeTeX
\usepackage{fontspec}
\setmonofont{DejaVuSansMono}[Scale=MatchUppercase]
\else % old engines
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[scaled]{DejaVuSansMono}
\fi
\usepackage{showexpl}
\lstset{
explpreset={numbers=none},
language=[LaTeX]Tex,
basicstyle=\ttfamily\tiny,
commentstyle=\itshape\ttfamily\tiny,
showspaces=false,
showstringspaces=false,
breaklines=true,
backgroundcolor=\color{white!90!black},
breakautoindent=true,
captionpos=t
}
\usepackage{geometry}
\geometry{lmargin=2in,rmargin=1in,tmargin=1in,bmargin=1in}
\usetikzlibrary{decorations.markings,arrows.meta,spy,backgrounds}
\usepackage[nottoc]{tocbibind}
\sloppy
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{bodeplot.dtx}
\PrintChanges
\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{1726}
%
% \changes{v1.0}{2021/10/25}{Initial release}
% \changes{v1.0.4}{2021/11/05}{Fixed unintended optional argument macro expansion}
% \changes{v1.0.6}{2021/11/18}{Fixed issue \#3}
% \changes{v1.0.7}{2021/12/02}{Removed unnecessary semicolons}
% \changes{v1.0.7}{2022/01/18}{Updated documentation}
% \changes{v1.0.8}{2022/07/06}{Added a new class option `declutter'}
% \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}
% \changes{v1.1.1}{2022/07/31}{Enable Hz and rad units}
%
% \GetFileInfo{bodeplot.sty}
% \DoNotIndex{\newcommand,\xdef,\gdef,\def,\edef,\addplot,\approx,\arabic,\opt,\typ,\obj,\else,\if@pgfarg,\if@Hzarg,\if@radarg,\if@declutterarg,\fi,\begin,\end,\feature,\footnotesize,\draw,\detokenize,\DeclareOption,\foreach,\ifdim,\ifodd,\Im,\Re,\let,\newif,\nextgroupplot,\noexpand,\expandafter,\unexpanded,\PackageError,\PackageWarning,\relax,\RequirePackage,\tikzset,\pgfmathsetmacro,\pgfmathtruncatemacro,\ProcessOptions}
%
% \title{The \textsf{bodeplot} package\\version 1.1.2}
% \author{Rushikesh Kamalapurkar \\ \texttt{rlkamalapurkar@gmail.com}}
%
% \maketitle
% \tableofcontents
% \clearpage
% \section{Introduction}
%
% Generate Bode, Nyquist, and Nichols plots for transfer functions in the canonical (TF) form \begin{equation}G(s) = e^{-Ts}\frac{b_ms^m+\cdots+b_1s+b_0}{a_ns^n+\cdots+a_1s+a_0}\label{eq:TF}\end{equation} and the zero-pole-gain (ZPK) form \begin{equation}G(s) = Ke^{-Ts}\frac{(s-z_1)(s-z_2)\cdots(s-z_m)}{(s-p_1)(s-p_2)\cdots(s-p_n)}.\label{eq:ZPK}\end{equation} In the equations above, $b_m,\cdots,b_0$ and $a_n,\cdots,a_0$ are real coefficients, $T\geq 0$ is the loop delay, $z_1,\cdots,z_m$ and $p_1,\cdots,p_n$ are complex zeros and poles of the transfer function, respectively, and $K\in \Re$ is the loop gain.
%
% For transfer functions in the ZPK format in (\ref{eq:ZPK}) \emph{with zero delay}, this package also supports linear and asymptotic approximation of Bode plots.
%
% By default, all phase plots use degrees as units. Use the |rad| package option or the optional argument |tikz/{phase unit=rad}| to generate plots in radians. The |phase unit| key accepts either |rad| or |deg| as inputs and needs to be added to the |tikzpicture| environment that contains the plots.
%
% By default, frequency inputs and outputs are in radians per second. Use the |Hz| package option or the optional argument |tikz/{frequency unit=Hz}| to generate plots in hertz. The |frequency unit| key accepts either |rad| or |Hz| as inputs and needs to be added to the |tikzpicture| environment that contains the plots.
% \subsection{External Dependencies}
% By default, the package uses |gnuplot| to do all the computations. If |gnuplot| is not available, the |pgf| package option can be used to do the calculations using the native |pgf| math engine. Compilation using the |pgf| math engine is typically slower, but the end result should be the identical (other than phase wrapping in the TF form, see limitations below).
%\subsection{Directory Structure}
% Since version 1.0.8, the |bodeplot| package places all |gnuplot| temporary files in the working directory. The package option |declutter| restores the original behavior where the temporary files are placed in a folder called |gnuplot|.
% \subsection{Limitations}
% \begin{itemize}
% \item In |pgf| mode, Bode phase plots and Nichols charts in TF form wrap angles so that they are always between 0 and 360$^\circ$ or 0 and $2\pi$ radian. As such, these plots will show phase wrapping discontinuities. Since v1.1.1, in |gnuplot| mode, the package uses the |smooth unwrap| filter to correct wrapping discontinuities. As of now, I have not found a way to do this in |pgf| mode, any merge requests or ideas you may have are welcome!
% \item Use of the |declutter| option with other directory management tools such as a |tikzexternalize| prefix is not recommended.
% \end{itemize}
% \clearpage
% \section{TL;DR}
% All Bode plots in this section are for the transfer function (with and without a transport delay)
% \begin{equation}
% G(s) = 10\frac{s(s+0.1+0.5\mathrm{i})(s+0.1-0.5\mathrm{i})}{(s+0.5+10\mathrm{i})(s+0.5-10\mathrm{i})} = \frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)}.
% \end{equation}
% \iffalse
%<*ignore>
% \fi
+
\hrulefill
+
{\centering Bode plot in ZPK format
\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
\BodeZPK{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
{0.01}
{100}
\end{LTXexample}
+
\hrulefill
+
Same Bode plot over the same frequency range but supplied in Hz, in TF format with arrow decoration, transport delay, unit, and color customization (the phase plot may show wrapping if the |pgf| package option is used)
\begin{LTXexample}[pos=r,width=0.5\textwidth]
\BodeTF[%
samples=1000,
plot/mag/{blue,thick},
plot/ph/{green,thick},
tikz/{%
>=latex,
phase unit=rad,
frequency unit=Hz%
},
commands/mag/{
\draw[->](axis cs:0.1,40) -- (axis cs:{10/(2*pi)},60);
\node at (axis cs: 0.08,30) {\tiny Resonant Peak};
}%
]
{%
num/{10,2,2.6,0},
den/{1,1,100.25}%
}
{0.01/(2*pi)}
{100/(2*pi)}
\end{LTXexample}
+
\hrulefill
\clearpage
\hrulefill
+
Linear approximation with customization
\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
\BodeZPK[%
plot/mag/{red,thick},
plot/ph/{blue,thick},
axes/mag/{ytick distance=40},
axes/ph/{ytick distance=90},
approx/linear%
]{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
{0.01}
{100}
\end{LTXexample}
+
\hrulefill
+
Plot with delay and customization
\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
\BodeZPK[%
plot/mag/{blue,thick},
plot/ph/{green,thick},
axes/mag/ytick distance=40,
axes/ph/ytick distance=90%
]{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10,
d/0.01%
}
{0.01}
{100}
\end{LTXexample}
+
\hrulefill
\clearpage
\hrulefill
+
Individual gain and phase plots with more customization
+
\begin{minipage}[t]{0.45\textwidth}
\begin{LTXexample}[pos=t,width=\columnwidth]
\begin{BodeMagPlot}[%
axes/{height=2cm,
width=4cm}
]
{0.01}
{100}
\addBodeZPKPlots[%
true/{black,thick},
linear/{red,dashed,thick},
asymptotic/{blue,dotted,thick}%
]
{magnitude}
{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
\end{BodeMagPlot}
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.45\textwidth}
\begin{LTXexample}[pos=t,width=\columnwidth]
\begin{BodePhPlot}[%
height=2cm,
width=4cm,
ytick distance=90
]
{0.01}
{100}
\addBodeZPKPlots[%
true/{black,thick},
linear/{red,dashed,thick},
asymptotic/{blue,dotted,thick}%
]
{phase}
{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
\end{BodePhPlot}
\end{LTXexample}
\end{minipage}
+
\hrulefill
+
Nichols chart
\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
\NicholsZPK[samples=1000]
{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10,
d/0.01%
}
{0.001}
{500}
\end{LTXexample}
+
\hrulefill
+
Same Nichols chart in TF format (may show wrapping in |pgf| mode)
\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
\NicholsTF[samples=1000]
{%
num/{10,2,2.6,0},
den/{1,1,100.25},
d/0.01%
}
{0.001}
{500}
\end{LTXexample}
+
\hrulefill
\clearpage
\hrulefill
+
Multiple Nichols charts with customization
\begin{LTXexample}[pos=l,hsep=20pt,width=0.5\textwidth]
\begin{NicholsChart}[%
ytick distance=20,
xtick distance=30
]
{0.001}
{100}
\addNicholsZPKChart [red,samples=1000] {%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
\addNicholsZPKChart [blue,samples=1000] {%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/5%
}
\end{NicholsChart}
\end{LTXexample}
+
\hrulefill
+
Nyquist plot
\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
\NyquistZPK[plot/{red,thick,samples=1000}]
{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
{-30}
{30}
\end{LTXexample}
+
\hrulefill
+
Nyquist plot in TF format with arrows
\begin{LTXexample}[pos=l,width=0.5\textwidth]
\NyquistTF[%
plot/{%
samples=1000,
postaction=decorate,
decoration={%
markings,
mark=between positions 0.1 and 0.9 step 5em with {%
\arrow{Stealth [length=2mm, blue]}
}
}
}%
]
{%
num/{10,2,2.6,0},
den/{1,1,100.25}%
}
{-30}
{30}
\end{LTXexample}
+
\hrulefill
\clearpage
\hrulefill
+
Multiple Nyquist plots with customization
\begin{LTXexample}[pos=r,hsep=20pt,width=0.5\textwidth]
\begin{NyquistPlot}{-30}{30}
\addNyquistZPKPlot [red,samples=1000] {%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/10%
}
\addNyquistZPKPlot [blue,samples=1000] {%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/5%
}
\end{NyquistPlot}
\end{LTXexample}
+
\hrulefill
+
Nyquist plots with additional commands, using two different macros
+
\begin{minipage}[t]{0.48\textwidth}
\begin{LTXexample}[pos=t,width=\columnwidth]
\begin{NyquistPlot}[%
tikz/{
spy using outlines={%
circle,
magnification=3,
connect spies,
size=2cm
}
}%
]
{-30}{30}
\addNyquistZPKPlot [blue,samples=1000] {%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/0.5%
}
\coordinate (spyon) at (axis cs:0,0);
\coordinate (spyat) at (axis cs:-22,5);
\spy [green] on (spyon) in
node [fill=white] at (spyat);
\end{NyquistPlot}
\end{LTXexample}
\end{minipage}\hfill
\begin{minipage}[t]{0.48\textwidth}
\begin{LTXexample}[pos=t,width=\columnwidth]
\NyquistZPK[%
plot/{blue,samples=1000},
tikz/{
spy using outlines={%
circle,
magnification=3,
connect spies,
size=2cm
}
},
commands/{
\coordinate (spyon) at (axis cs:0,0);
\coordinate (spyat) at (axis cs:-22,5);
\spy [green] on (spyon) in
node [fill=white] at (spyat);
}%
]
{%
z/{0,{-0.1,-0.5},{-0.1,0.5}},
p/{{-0.5,-10},{-0.5,10}},
k/0.5%
}
{-30}
{30}
\end{LTXexample}
\end{minipage}}
+
\hrulefill
\clearpage
+
% \iffalse
%</ignore>
% \fi
%
% \section{Usage}
% \noindent In all the macros described here, the frequency limits supplied by the user are assumed to be in |rad/s| unless either the |Hz| package option is used or the optional argument |tikz/{frequency unit=Hz}| is supplied to the |tikzpicture| environment. All phase plots are getenrated in degrees unless either the |rad| package option is used or the optional argument |tikz/{frequency unit=rad}| is supplied to the |tikzpicture| environment.
%
% \subsection{Bode plots}
% \DescribeMacro{\BodeZPK}
% |\BodeZPK| \oarg{obj1/typ1/\marg{opt1},obj2/typ2/\marg{opt2},...}\\
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
% \noindent Plots the Bode plot of a transfer function given in ZPK format using the |groupplot| environment. The three mandatory arguments include: (1) a list of tuples, comprised of the zeros, the poles, the gain, and the transport delay of the transfer function, (2) the lower end of the frequency range for the $x-$axis, and (3) the higher end of the frequency range for the $x-$axis. The zeros and the poles are complex numbers, entered as a comma-separated list of comma-separated lists, of the form |{{real part 1,imaginary part 1},| |{real part 2,imaginary part 2},...}|. If the imaginary part is not provided, it is assumed to be zero.
%
% The optional argument is comprised of a comma separated list of tuples, either |obj/typ/{opt}|, or |obj/{opt}|, or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the group, the axes, and the plots according to:
% \begin{itemize}
% \item Tuples of the form |obj/typ/{opt}|:
% \begin{itemize}
% \item |plot/typ/{opt}|: modify plot properties by adding options |{opt}| to the |\addplot| macro for the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|.
% \item |axes/typ/{opt}|: modify axis properties by adding options |{opt}| to the |\nextgroupplot| macro for the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|.
% \item |commands/typ/{opt}|: add any valid TikZ commands (including the the parametric function generator macros in this package, such as |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|) to the magnitude plot if |typ| is |mag| and the phase plot if |typ| is |ph|. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual. For example, a TikZ command is used in the description of the |\BodeTF| macro below to mark the gain crossover frequency on the Bode Magnitude plot.
% \end{itemize}
% \item Tuples of the form |obj/{opt}|:
% \begin{itemize}
% \item |plot/{opt}|: adds options |{opt}| to |\addplot| macros for both the magnitude and the phase plots.
% \item |axes/{opt}|: adds options |{opt}| to |\nextgroupplot| macros for both the magnitude and the phase plots.
% \item |group/{opt}|: adds options |{opt}| to the |groupplot| environment.
% \item |tikz/{opt}|: adds options |{opt}| to the |tikzpicture| environment.
% \item |approx/linear|: plots linear approximation.
% \item |approx/asymptotic|: plots asymptotic approximation.
% \end{itemize}
% \item Tuples of the form |{opt}| add all of the supplied options to |\addplot| macros for both the magnitude and the phase plots.
% \end{itemize}
% The options |{opt}| can be any |key=value| options that are supported by the |pgfplots| macros they are added to.
+
% For example, given a transfer function \begin{equation}G(s) = 10\frac{s(s+0.1+0.5\mathrm{i})(s+0.1-0.5\mathrm{i})}{(s+0.5+10\mathrm{i})(s+0.5-10\mathrm{i})},\label{eq:ZPKExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using\\
% |\BodeZPK [blue,thick]|\\
% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\
% | {0.01}{100}|\\
% which generates the plot in Figure \ref{simpleBode}. If a delay is not specified, it is assumed to be zero. If a gain is not specified, it is assumed to be 1. By default, each of the axes, excluding ticks and labels, are 5cm wide and 2.5cm high. The width and the height, along with other properties of the plots, the axes, and the group can be customized using native |pgf| keys as shown in the example below.
%
% \begin{figure}
% \begin{center}
% \BodeZPK[blue,thick]{z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}{0.01}{100}
% \cprotect\caption{\label{simpleBode}Output of the default |\BodeZPK| macro.}
% \end{center}
% \end{figure}
% As demonstrated in this example, if a single comma-separated list of options is passed, it applies to both the magnitude and the phase plots. Without any optional arguments, we gets a thick black Bode plot.
%
% A linear approximation of the Bode plot with customization of the plots, the axes, and the group can be generated using\\
% |\BodeZPK[plot/mag/{red,thick},plot/ph/{blue,thick},|\\
% | axes/mag/{ytick distance=40,xmajorticks=true,|\\
% | xlabel={Frequency (rad/s)}},axes/ph/{ytick distance=90},|\\
% | group/{group style={group size=2 by 1,horizontal sep=2cm,|\\
% | width=4cm,height=2cm}},approx/linear]|\\
% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\
% | {0.01}{100}|\\
% which generates the plot in Figure \ref{customBode}.
%
% \begin{figure}
% \begin{center}
% \BodeZPK[plot/mag/{red,thick},plot/ph/{blue,thick},axes/mag/{ytick distance=40,xmajorticks=true,xlabel={Frequency (rad/s)}},axes/ph/{ytick distance=90},approx/linear,group/{group style={group size = 2 by 1,horizontal sep=2cm},width=4cm,height=2cm}] {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},g/10} {0.01} {100}
% \cprotect\caption{\label{customBode}Customization of the default |\BodeZPK| macro.}
% \end{center}
% \end{figure}
%
% \DescribeMacro{\BodeTF}
% |\BodeTF| \oarg{obj1/typ1/\marg{opt1},obj2/typ2/\marg{opt2},...}\\
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq} \rmfamily
%
% \noindent Plots the Bode plot of a transfer function given in TF format. The three mandatory arguments include: (1) a list of tuples comprised of the coefficients in the numerator and the denominator of the transfer function and the transport delay, (2) the lower end of the frequency range for the $x-$ axis, and (3) the higher end of the frequency range for the $x-$axis. The coefficients are entered as a comma-separated list, in order from the highest degree of $s$ to the lowest, with zeros for missing degrees. The optional arguments are the same as |\BodeZPK|, except that linear/asymptotic approximation is not supported, so |approx/...| is ignored.
%
% For example, given the same transfer function as (\ref{eq:ZPKExample}) in TF form and with a small transport delay, \begin{equation}G(s) = e^{-0.01s}\frac{s(10s^2+2s+2.6)}{(s^2+s+100.25)},\label{eq:TFExample}\end{equation} its Bode plot over the frequency range $[0.01,100]$ can be generated using\\
% |\BodeTF[commands/mag/{\node at (axis cs: 2.1,0) |\\
% | [circle,fill,inner sep=0.05cm,label=below:{$\omega_{gc}$}]{};}]|\\
% | {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}|\\
% | {0.01}{100}|\\
% which generates the plot in Figure \ref{simpleBodeTF}. Note the $0$ added to the numerator coefficients to account for the fact that the numerator does not have a constant term in it. Note the semicolon after the TikZ command passed to the |\commands| option.
%
% \begin{figure}
% \begin{center}
% \BodeTF[commands/mag/{\node at (axis cs: 2.1,0) [circle,fill,inner sep=0.05cm,label=below:{$\omega_{gc}$}] {};}]{num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}{0.01}{100}
% \cprotect\caption{\label{simpleBodeTF}Output of the |\BodeTF| macro with an optional TikZ command used to mark the gain crossover frequency.}
% \end{center}
% \end{figure}
%
% \DescribeEnv{BodeMagPlot}
% |\begin{BodeMagPlot}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\
% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\
% \hspace*{2em}|\addBode...|\\
% \hspace*{1.5em}|\end{BodeMagPlot}|\\
% The |BodeMagPlot| environment works in conjunction with the parametric function generator macros |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|, intended to be used for magnitude plots. The optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to:
% \begin{itemize}
% \item Tuples of the form |obj/{opt}|:
% \begin{itemize}
% \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment.
% \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |semilogaxis| environment.
% \item |commands/{opt}|: add any valid TikZ commands inside |semilogaxis| environment. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual.
% \end{itemize}
% \item Tuples of the form |{opt}| are passed directly to the |semilogaxis| environment.
% \end{itemize}
% The frequency limits are translated to the x-axis limits and the domain of the |semilogaxis| environment. Example usage in the description of |\addBodeZPKPlots|, |\addBodeTFPlot|, and |\addBodeComponentPlot|.
%
%\DescribeEnv{BodePhPlot}
% |\begin{BodePhPlot}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\
% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\
% \hspace*{2em}|\addBode...|\\
% \hspace*{1.5em}|\end{BodePhPlot}|\\
% Intended to be used for phase plots, otherwise same as the |BodeMagPlot| environment
%
% \DescribeMacro{\addBodeZPKPlots}
% |\addBodeZPKPlots| \oarg{approx1/\marg{opt1},approx2/\marg{opt2},...}\\
% \hspace*{2em}\marg{plot-type}\\
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}
%
% \noindent Generates the appropriate parametric functions and supplies them to multiple |\addplot| macros, one for each |approx/{opt}| pair in the optional argument. If no optional argument is supplied, then a single |\addplot| command corresponding to a thick true Bode plot is generated. If an optional argument is supplied, it needs to be one of |true/{opt}|, |linear/{opt}|, or |asymptotic/{opt}|. This macro can be used inside any |semilogaxis| environment as long as a domain for the x-axis is supplied through either the |approx/{opt}| interface or directly in the optional argument of the |semilogaxis| environment. Use with the |BodePlot| environment supplied with this package is recommended. The second mandatory argument, |plot-type| is either |magnitude| or |phase|. If it is not equal to |phase|, it is assumed to be |magnitude|. The last mandatory argument is the same as |\BodeZPK|.
%
% For example, given the transfer function in (\ref{eq:ZPKExample}), its linear, asymptotic, and true Bode plots can be superimposed using
%\begin{verbatim}
%\begin{BodeMagPlot}[height=2cm,width=4cm] {0.01} {100}
% \addBodeZPKPlots[%
% true/{black,thick},
% linear/{red,dashed,thick},
% asymptotic/{blue,dotted,thick}]
% {magnitude}
% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
%\end{BodeMagPlot}
%
%\begin{BodePhPlot}[height=2cm, width=4cm, ytick distance=90] {0.01} {100}
% \addBodeZPKPlots[%
% true/{black,thick},
% linear/{red,dashed,thick},
% asymptotic/{blue,dotted,thick}]
% {phase}
% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
%\end{BodePhPlot}
%\end{verbatim}
% \begin{figure}
% \begin{center}
% \begin{BodeMagPlot}[height=2cm,width=4cm]{0.01}{100}
% \addBodeZPKPlots[%
% true/{black,thick},
% linear/{red,dashed,thick},
% asymptotic/{blue,dotted,thick}]
% {magnitude}
% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
% \end{BodeMagPlot}
% \begin{BodePhPlot}[height=2cm,width=4cm,ytick distance=90]{0.01}{100}
% \addBodeZPKPlots[%
% true/{black,thick},
% linear/{red,dashed,thick},
% asymptotic/{blue,dotted,thick}]
% {phase}
% {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}
% \end{BodePhPlot}
% \end{center}
% \caption{\label{multiBodeZPK}Superimposed approximate and true Bode plots using the \texttt{BodeMagPlot} and \texttt{BodePhPlot} environments and the \texttt{\textbackslash addBodeZPKPlots} macro.}
% \end{figure}
% which generates the plot in Figure \ref{multiBodeZPK}.
%
% \DescribeMacro{\addBodeTFPlot}
% |\addBodeTFPlot|\oarg{plot-options}\\
% \hspace*{2em}\marg{plot-type}\\
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}
%
% \noindent Generates a single parametric function for either Bode magnitude or phase plot of a transfer function in TF form. The generated parametric function is passed to the |\addplot| macro. This macro can be used inside any |semilogaxis| environment as long as a domain for the x-axis is supplied through either the |plot-options| interface or directly in the optional argument of the container |semilogaxis| environment. Use with the |BodePlot| environment supplied with this package is recommended. The second mandatory argument, |plot-type| is either magnitude or |phase|. If it is not equal to |phase|, it is assumed to be |magnitude|. The last mandatory argument is the same as |\BodeTF|.
%
% \DescribeMacro{\addBodeComponentPlot}
% |\addBodeComponentPlot|\oarg{plot-options}\marg{plot-command}
%
% \noindent Generates a single parametric function corresponding to the mandatory argument |plot-command| and passes it to the |\addplot| macro. The plot command can be any parametric function that uses |t| as the independent variable. The parametric function must be |gnuplot| compatible (or |pgfplots| compatible if the package is loaded using the |pgf| option). The intended use of this macro is to plot the parametric functions generated using the basic component macros described in Section \ref{sec:BasicComponents} below.
%
% \subsubsection{Basic components up to first order\label{sec:BasicComponents}}
%
% \DescribeMacro{\TypeFeatureApprox}
% |\TypeFeatureApprox|\marg{real-part}\marg{imaginary-part}
%
% \noindent This entry describes 20 different macros of the form |\TypeFeatureApprox| that take the real part and the imaginary part of a complex number as arguments. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Feature| in the macro name should be replaced by one of |K|, |Pole|, |Zero|, or |Del|, to generate the Bode plot of a gain, a complex pole, a complex zero, or a transport delay, respectively. If the |Feature| is set to either |K| or |Del|, the |imaginary-part| mandatory argument is ignored. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively. If the |Feature| is set to |Del|, then |Approx| has to be removed. For example,
% \begin{itemize}
% \item |\MagK{k}{0}| or |\MagK{k}{400}| generates a parametric function for the true Bode magnitude of $ G(s) = k $
% \item |\PhPoleLin{a}{b}| generates a parametric function for the linear approximation of the Bode phase of $ G(s) = \frac{1}{s-a-\mathrm{i}b} $.
% \item |\PhDel{T}{200}| or |\PhDel{T}{0}| generates a parametric function for the Bode phase of $ G(s) = e^{-Ts} $.
% \end{itemize}
% All 20 of the macros defined by combinations of |Type|, |Feature|, and |Approx|, and any |gnuplot| (or |pgfplot| if the |pgf| class option is loaded) compatible function of the 20 macros can be used as |plot-command| in the |addBodeComponentPlot| macro. This is sufficient to generate the Bode plot of any rational transfer function with delay. For example, the Bode phase plot in Figure \ref{multiBodeZPK} can also be generated using:
%\begin{verbatim}
%\begin{BodePhPlot}[ytick distance=90]{0.01}{100}
% \addBodeComponentPlot[black,thick]{\PhZero{0}{0} + \PhZero{-0.1}{-0.5} +
% \PhZero{-0.1}{0.5} + \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} +
% \PhK{10}{0}}
% \addBodeComponentPlot[red,dashed,thick] {\PhZeroLin{0}{0} +
% \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} +
% \PhPoleLin{-0.5}{-10} + \PhPoleLin{-0.5}{10} + \PhKLin{10}{20}}
% \addBodeComponentPlot[blue,dotted,thick] {\PhZeroAsymp{0}{0} +
% \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} +
% \PhPoleAsymp{-0.5}{-10} + \PhPoleAsymp{-0.5}{10} + \PhKAsymp{10}{40}}
%\end{BodePhPlot}
%\end{verbatim}
%\begin{figure}
% \begin{center}
% \begin{BodePhPlot}[ytick distance=90]{0.01}{100}
% \addBodeComponentPlot[black,thick] {\PhZero{0}{0} + \PhZero{-0.1}{-0.5} + \PhZero{-0.1}{0.5} + \PhPole{-0.5}{-10} + \PhPole{-0.5}{10} + \PhK{10}{0}}
% \addBodeComponentPlot[red,dashed,thick] {\PhZeroLin{0}{0} + \PhZeroLin{-0.1}{-0.5} + \PhZeroLin{-0.1}{0.5} + \PhPoleLin{-0.5}{-10} + \PhPoleLin{-0.5}{10} + \PhKLin{10}{20}}
% \addBodeComponentPlot[blue,dotted,thick] {\PhZeroAsymp{0}{0} + \PhZeroAsymp{-0.1}{-0.5} + \PhZeroAsymp{-0.1}{0.5} + \PhPoleAsymp{-0.5}{-10} + \PhPoleAsymp{-0.5}{10} + \PhKAsymp{10}{40}}
% \end{BodePhPlot}
% \end{center}
% \caption{\label{multiBodeComponents}Superimposed approximate and true Bode Phase plot using the \texttt{BodePhPlot} environment, the \texttt{\textbackslash addBodeComponentPlot} macro, and several macros of the \texttt{\textbackslash TypeFeatureApprox} form.}
%\end{figure}
% which gives us the plot in Figure \ref{multiBodeComponents}.
%
% \subsubsection{Basic components of the second order}
%
% \DescribeMacro{\TypeSOFeatureApprox}
% |\TypeSOFeatureApprox|\marg{a1}\marg{a0}
%
% \noindent This entry describes 12 different macros of the form |\TypeSOFeatureApprox| that take the coefficients $ a_1 $ and $ a_0 $ of a general second order system as inputs. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate the Bode plot of $G(s)=\frac{1}{s^2+a_1 s+a_0}$ or $G(s)=s^2+a_1 s+a_0$, respectively. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively.
%
% \DescribeMacro{\MagSOFeaturePeak}
% |\MagSOFeaturePeak|\oarg{draw-options}\marg{a1}\marg{a0}
%
% \noindent This entry describes 2 different macros of the form |\MagSOFeaturePeak| that take the the coefficients $ a_1 $ and $ a_0 $ of a general second order system as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively. For example, the command
%\begin{verbatim}
%\begin{BodeMagPlot}[xlabel={}]{0.1}{10}
% \addBodeComponentPlot[red,dashed,thick]{\MagSOPoles{0.2}{1}}
% \addBodeComponentPlot[black,thick]{\MagSOPolesLin{0.2}{1}}
% \MagSOPolesPeak[thick]{0.2}{1}
%\end{BodeMagPlot}
%\end{verbatim}
% generates the plot in Figure \ref{BodePeak}.
%
% \begin{figure}
% \begin{center}
% \begin{BodeMagPlot}[xlabel={}]{0.1}{10}
% \addBodeComponentPlot[red,dashed,thick]{\MagSOPoles{0.2}{1}}
% \addBodeComponentPlot[black,thick]{\MagSOPolesLin{0.2}{1}}
% \MagSOPolesPeak[very thick]{0.2}{1}
% \end{BodeMagPlot}
% \end{center}
% \cprotect\caption{\label{BodePeak} Resonant peak in asymptotic Bode plot using |\MagSOPolesPeak|.}
% \end{figure}
%
% \DescribeMacro{\TypeCSFeatureApprox}
% |\TypeCSFeatureApprox|\marg{zeta}\marg{omega-n}
%
% \noindent This entry describes 12 different macros of the form |\TypeCSFeatureApprox| that take the damping ratio, $ \zeta $, and the natural frequency, $ \omega_n $ of a canonical second order system as inputs. The |Type| in the macro name should be replaced by either |Mag| or |Ph| to generate a parametric function corresponding to the magnitude or the phase plot, respectively. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate the Bode plot of $G(s)=\frac{1}{s^2+2\zeta\omega_n s+\omega_n^2}$ or $G(s)=s^2+2\zeta\omega_n s+\omega_n^2$, respectively. The |Approx| in the macro name should either be removed, or it should be replaced by |Lin| or |Asymp| to generate the true Bode plot, the linear approximation, or the asymptotic approximation, respectively.
%
% \DescribeMacro{\MagCSFeaturePeak}
% |\MagCSFeaturePeak|\oarg{draw-options}\marg{zeta}\marg{omega-n}
%
% \noindent This entry describes 2 different macros of the form |\MagCSFeaturePeak| that take the damping ratio, $ \zeta $, and the natural frequency, $ \omega_n $ of a canonical second order system as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively.
%
% \DescribeMacro{\MagCCFeaturePeak}
% |\MagCCFeaturePeak|\oarg{draw-options}\marg{real-part}\marg{imaginary-part}
%
% \noindent This entry describes 2 different macros of the form |\MagCCFeaturePeak| that take the real and imaginary parts of a pair of complex conjugate poles or zeros as inputs, and draw a resonant peak using the |\draw| TikZ macro. The |Feature| in the macro name should be replaced by either |Poles| or |Zeros| to generate a peak for poles and a valley for zeros, respectively.
%
% \subsection{Nyquist plots}
% \DescribeMacro{\NyquistZPK}
% |\NyquistZPK| \oarg{plot/\marg{opt},axes/\marg{opt}}\\
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
% \noindent Plots the Nyquist plot of a transfer function given in ZPK format with a thick red $+$ marking the critical point (-1,0). The mandatory arguments are the same as |\BodeZPK|. Since there is only one plot in a Nyquist diagram, the |\typ| specifier in the optional argument tuples is not needed. As such, the supported optional argument tuples are |plot/{opt}|, which passes |{opt}| to |\addplot|, |axes/{opt}|, which passes |{\opt}| to the |axis| environment, and |tikz/{opt}|, which passes |{\opt}| to the |tikzpicture| environment. Asymptotic/linear approximations are not supported in Nyquist plots. If just |{opt}| is provided as the optional argument, it is interpreted as |plot/{opt}|. Arrows to indicate the direction of increasing $\omega$ can be added by adding |\usetikzlibrary{decorations.markings}| and |\usetikzlibrary{arrows.meta}| to the preamble and then passing a tuple of the form\\
%|plot/{postaction=decorate,decoration={markings,|\\
%| mark=between positions 0.1 and 0.9 step 5em with|\\
%| {\arrow{Stealth| |[length=2mm, blue]}}}}|\\
%\textbf{Caution:} with a high number of samples, adding arrows in this way may cause the error message |! Dimension too big|.
%
% For example, the command\\
% |\NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}]|\\
% | {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10}|\\
% | {-30}{30}|\\
% generates the Nyquist plot in Figure \ref{simpleNyquistZPK}.
%
% \begin{figure}
% \begin{center}
% \NyquistZPK[plot/{red,thick,samples=2000},axes/{blue,thick}] {z/{0,{-0.1,-0.5},{-0.1,0.5}},p/{{-0.5,-10},{-0.5,10}},k/10} {-30} {30}
% \cprotect\caption{\label{simpleNyquistZPK}Output of the |\NyquistZPK| macro.}
% \end{center}
% \end{figure}
%
% % \DescribeMacro{\NyquistTF}
% |\NyquistTF| \oarg{plot/\marg{opt},axes/\marg{opt}}\\
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
% \noindent Nyquist plot of a transfer function given in TF format. Same mandatory arguments as |\BodeTF| and same optional arguments as |\NyquistZPK|. For example, the command\\
% |\NyquistTF[plot/{green,thick,samples=500,postaction=decorate,|\\
% | decoration={markings,|\\
% | mark=between positions 0.1 and 0.9 step 5em|\\
% | with{\arrow{Stealth[length=2mm, blue]}}}}]|\\
% | {num/{10,2,2.6,0},den/{1,1,100.25}}|\\
% | {-30}{30}|\\
% generates the Nyquist plot in Figure \ref{simpleNyquistTF}.
%
% \begin{figure}
% \begin{center}
% \NyquistTF[plot/{green,thick,samples=500,postaction=decorate,decoration={markings,mark=between positions 0.1 and 0.9 step 5em with {\arrow{Stealth[length=2mm, blue]}}}}] {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01} {-30} {30}
% \cprotect\caption{\label{simpleNyquistTF}Output of the |\NyquistTF| macro with direction arrows. Increasing the number of samples can cause |decorations.markings| to throw errors.}
% \end{center}
% \end{figure}
%
% \DescribeEnv{NyquistPlot}
% |\begin{NyquistPlot}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\
% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\
% \hspace*{2em}|\addNyquist...|\\
% \hspace*{1.5em}|\end{NyquistPlot}|\\
% The |NyquistPlot| environment works in conjunction with the parametric function generator macros |\addNyquistZPKPlot| and |\addNyquistTFPlot|. The optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to:
% \begin{itemize}
% \item Tuples of the form |obj/{opt}|:
% \begin{itemize}
% \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment.
% \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |axis| environment.
% \item |commands/{opt}|: add any valid TikZ commands inside |axis| environment. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual.
% \end{itemize}
% \item Tuples of the form |{opt}| are passed directly to the |axis| environment.
% \end{itemize}
% The frequency limits are translated to the x-axis limits and the domain of the |axis| environment.
%
% \DescribeMacro{\addNyquistZPKPlot}
% |\addNyquistZPKPlot|\oarg{plot-options}\\
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}
%
% \noindent Generates a twp parametric functions for the magnitude and the phase a transfer function in ZPK form. The generated magnitude and phase parametric functions are converted to real and imaginary part parametric functions and passed to the |\addplot| macro. This macro can be used inside any |axis| environment as long as a domain for the x-axis is supplied through either the |plot-options| interface or directly in the optional argument of the container |axis| environment. Use with the |NyquistPlot| environment supplied with this package is recommended. The mandatory argument is the same as |\BodeZPK|.
%
% \DescribeMacro{\addNyquistTFPlot}
% |\addNyquistTFPlot|\oarg{plot-options}\\
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}
%
% \noindent Similar to |\addNyquistZPKPlot|, with a transfer function input in the TF form.
%
% \subsection{Nichols charts}
% \DescribeMacro{\NicholsZPK}
% |\NicholsZPK| \oarg{plot/\marg{opt},axes/\marg{opt}}\\
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
% \noindent Nichols chart of a transfer function given in ZPK format. Same arguments as |\NyquistZPK|.
%
% \DescribeMacro{\NicholsTF}
% |\NicholsTF| \oarg{plot/\marg{opt},axes/\marg{opt}}\\
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}\\
% \hspace*{2em}\marg{min-freq}\marg{max-freq}
%
% \noindent Nichols chart of a transfer function given in TF format. Same arguments as |\NyquistTF|. For example, the command\\
% |\NicholsTF[plot/{green,thick,samples=2000}]|\\
% | {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01}|\\
% | {0.001}{100}|\\
% generates the Nichols chart in Figure \ref{simpleNicholsTF}.
%
% \begin{figure}
% \begin{center}
% \NicholsTF[plot/{green,thick,samples=2000}] {num/{10,2,2.6,0},den/{1,1,100.25},d/0.01} {0.001} {100}
% \cprotect\caption{\label{simpleNicholsTF}Output of the |\NyquistZPK| macro.}
% \end{center}
% \end{figure}
%
%
% \DescribeEnv{NicholsChart}
% |\begin{NicholsChart}|\oarg{obj1/\marg{opt1},obj2/\marg{opt2},...}\\
% \hspace*{3em}\marg{min-frequency}\marg{max-frequency}\\
% \hspace*{2em}|\addNichols...|\\
% \hspace*{1.5em}|\end{NicholsChart}|\\
% The |NicholsChart| environment works in conjunction with the parametric function generator macros |\addNicholsZPKChart| and |\addNicholsTFChart|. The optional argument is comprised of a comma separated list of tuples, either |obj/{opt}| or just |{opt}|. Each tuple passes options to different |pgfplots| macros that generate the axes and the plots according to:
% \begin{itemize}
% \item Tuples of the form |obj/{opt}|:
% \begin{itemize}
% \item |tikz/{opt}|: modify picture properties by adding options |{opt}| to the |tikzpicture| environment.
% \item |axes/{opt}|: modify axis properties by adding options |{opt}| to the |axis| environment.
% \item |commands/{opt}|: add any valid TikZ commands inside |axis| environment. The commands passed to |opt| need to be valid TikZ commands, separated by semicolons as usual.
% \end{itemize}
% \item Tuples of the form |{opt}| are passed directly to the |axis| environment.
% \end{itemize}
% The frequency limits are translated to the x-axis limits and the domain of the |axis| environment.
%
% \DescribeMacro{\addNicholsZPKChart}
% |\addNicholsZPKChart|\oarg{plot-options}\\
% \hspace*{2em}\marg{z/\marg{zeros},p/\marg{poles},k/\marg{gain},d/\marg{delay}}
%
% \noindent Generates a twp parametric functions for the magnitude and the phase a transfer function in ZPK form. The generated magnitude and phase parametric functions are passed to the |\addplot| macro. This macro can be used inside any |axis| environment as long as a domain for the x-axis is supplied through either the |plot-options| interface or directly in the optional argument of the container |axis| environment. Use with the |NicholsChart| environment supplied with this package is recommended. The mandatory argument is the same as |\BodeZPK|.
%
% \DescribeMacro{\addNicholsTFChart}
% |\addNicholsTFChart|\oarg{plot-options}\\
% \hspace*{2em}\marg{num/\marg{coeffs},den/\marg{coeffs},d/\marg{delay}}
%
% \noindent Similar to |\addNicholsZPKChart|, with a transfer function input in the TF form.
%
% \StopEventually{\PrintIndex}
% \clearpage
% \section{Implementation}
% \subsection{Initialization}
% \begin{macro}{\n@mod}
% \begin{macro}{\n@pow}
% \begin{macro}{gnuplot@id}
% \begin{macro}{gnuplot@prefix}
% \changes{v1.0.3}{2021/11/03}{Added jobname to gnuplot prefix}
% \changes{v1.0.8}{2022/07/06}{Fixed issue \#6}
% This code is needed to support both |pgfplots| and |gnuplot| simultaneously. New macros are defined for the |pow| and |mod| functions to address differences between the two math engines. We start by processing the class options.
% \begin{macrocode}
\newif\if@pgfarg\@pgfargfalse
\DeclareOption{pgf}{
\@pgfargtrue
}
\newif\if@declutterarg\@declutterargfalse
\DeclareOption{declutter}{
\@declutterargtrue
}
\newif\if@radarg\@radargfalse
\DeclareOption{rad}{
\@radargtrue
}
\newif\if@hzarg\@hzargfalse
\DeclareOption{Hz}{
\@hzargtrue
}
\ProcessOptions\relax
% \end{macrocode}
% Then, we define two new macros to unify |pgfplots| and |gnuplot|.
% \begin{macrocode}
\newcommand{\n@mod}[2]{(#1)-(floor((#1)/(#2))*(#2))}
\if@pgfarg
\newcommand{\n@pow}[2]{(#1)^(#2)}
\pgfplotsset{
trig format plots=rad
}
\else
\newcommand{\n@pow}[2]{(#1)**(#2)}
% \end{macrocode}
% Then, we create a counter so that a new data table is generated and for each new plot. If the plot macros have not changed, the tables, once generated, can be reused by |gnuplot|, which reduces compilation time. The |declutter| option is used to enable the |gnuplot| directory to declutter the working directory.
% \begin{macrocode}
\newcounter{gnuplot@id}
\setcounter{gnuplot@id}{0}
\if@declutterarg
\edef\bodeplot@prefix{gnuplot/\jobname}
\else
\edef\bodeplot@prefix{\jobname}
\fi
\tikzset{
gnuplot@prefix/.style={
id=\arabic{gnuplot@id},
prefix=\bodeplot@prefix
}
}
% \end{macrocode}
% If the operating system is not Windows, and if the |declutter| option is not passed, we create the |gnuplot| folder if it does not already exist. \changes{v1.0.2}{2021/11/01}{Fixed issue \#1}
% \begin{macrocode}
\ifwindows\else
\if@declutterarg
\immediate\write18{mkdir -p gnuplot}
\fi
\fi
\fi
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{bode@style}
% Default axis properties for all plot macros are collected in this |pgf| style.
% \begin{macrocode}
\pgfplotsset{
bode@style/.style = {
label style={font=\footnotesize},
tick label style={font=\footnotesize},
grid=both,
major grid style={color=gray!80},
minor grid style={color=gray!20},
x label style={at={(ticklabel cs:0.5)},anchor=near ticklabel},
y label style={at={(ticklabel cs:0.5)},anchor=near ticklabel},
scale only axis,
samples=200,
width=5cm,
log basis x=10
}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{freq@filter}
% \begin{macro}{freq@label}
% \begin{macro}{freq@scale}
% \begin{macro}{ph@scale}
% \begin{macro}{ph@x@label}
% \begin{macro}{ph@y@label}
% These macros handle the |Hz| and |rad| class options and two new |pgf| keys named |frequency unit| and |phase unit| for conversion of frequency and phase units, respectively. \changes{v1.1.1}{2022/07/31}{New macros to enable `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\pgfplotsset{freq@filter/.style = {}}
\def\freq@scale{1}
\pgfplotsset{freq@label/.style = {xlabel = {Frequency (rad/s)}}}
\pgfplotsset{ph@x@label/.style = {xlabel={Phase (deg)}}}
\pgfplotsset{ph@y@label/.style = {ylabel={Phase (deg)}}}
\def\ph@scale{180/pi}
\if@radarg
\pgfplotsset{ph@y@label/.style = {ylabel={Phase (rad)}}}
\pgfplotsset{ph@x@label/.style = {xlabel={Phase (rad)}}}
\def\ph@scale{1}
\fi
\if@hzarg
\def\freq@scale{2*pi}
\pgfplotsset{freq@label/.style = {xlabel = {Frequency (Hz)}}}
\if@pgfarg
\pgfplotsset{freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}}
\fi
\fi
\tikzset{
phase unit/.initial={deg},
phase unit/.default={deg},
phase unit/.is choice,
phase unit/deg/.code={
\renewcommand{\ph@scale}{180/pi}
\pgfplotsset{ph@x@label/.style = {xlabel={Phase (deg)}}}
\pgfplotsset{ph@y@label/.style = {ylabel={Phase (deg)}}}
},
phase unit/rad/.code={
\renewcommand{\ph@scale}{1}
\pgfplotsset{ph@y@label/.style = {ylabel={Phase (rad)}}}
\pgfplotsset{ph@x@label/.style = {xlabel={Phase (rad)}}}
},
frequency unit/.initial={rad},
frequency unit/.default={rad},
frequency unit/.is choice,
frequency unit/Hz/.code={
\renewcommand{\freq@scale}{2*pi}
\pgfplotsset{freq@label/.style = {xlabel = {Frequency (Hz)}}}
\if@pgfarg
\pgfplotsset{freq@filter/.style = {x filter/.expression={x-log10(2*pi)}}}
\fi
},
frequency unit/rad/.code={
\renewcommand{\freq@scale}{1}
\pgfplotsset{freq@label/.style = {xlabel = {Frequency (rad/s)}}}
}
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{get@interval@start}
% \begin{macro}{get@interval@end}
% Internal macros to extract start and end frequency limits from domain specifications.\changes{v1.1.1}{2022/07/31}{New macros to enable `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\def\get@interval@start#1:#2\@nil{#1}
\def\get@interval@end#1:#2\@nil{#2}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \subsection{Parametric function generators for poles, zeros, gains, and delays.}
% All calculations are carried out assuming that frequeny inputs are in |rad/s|. Magnitude outputs are in |dB| and phase outputs are in degrees or radians, depending on the value of |\ph@scale|.
% \begin{macro}{\MagK}
% \begin{macro}{\MagKAsymp}
% \begin{macro}{\MagKLin}
% \begin{macro}{\PhK}
% \begin{macro}{\PhKAsymp}
% \begin{macro}{\PhKLin}
% True, linear, and asymptotic magnitude and phase parametric functions for a pure gain $G(s)=k+0\mathrm{i}$. The macros take two arguments corresponding to real and imaginary part of the gain to facilitate code reuse between delays, gains, poles, and zeros, but only real gains are supported. The second argument, if supplied, is ignored.
% \begin{macrocode}
\newcommand*{\MagK}[2]{(20*log10(abs(#1)))}
\newcommand*{\MagKAsymp}{\MagK}
\newcommand*{\MagKLin}{\MagK}
\newcommand*{\PhK}[2]{((#1<0?-pi:0)*\ph@scale)}
\newcommand*{\PhKAsymp}{\PhK}
\newcommand*{\PhKLin}{\PhK}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\PhKAsymp}
% \begin{macro}{\PhKLin}
% True magnitude and phase parametric functions for a pure delay $G(s)=e^{-Ts}$. The macros take two arguments corresponding to real and imaginary part of the gain to facilitate code reuse between delays, gains, poles, and zeros, but only real gains are supported. The second argument, if supplied, is ignored.
% \begin{macrocode}
\newcommand*{\MagDel}[2]{0}
\newcommand*{\PhDel}[2]{(-#1*t*\ph@scale)}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\MagPole}
% \begin{macro}{\MagPoleAsymp}
% \begin{macro}{\MagPoleLin}
% \begin{macro}{\PhPole}
% \begin{macro}{\PhPoleAsymp}
% \begin{macro}{\PhPoleLin}
% These macros are the building blocks for most of the plotting functions provided by this package. We start with Parametric function for the true magnitude of a complex pole.
% \begin{macrocode}
\newcommand*{\MagPole}[2]
{(-20*log10(sqrt(\n@pow{#1}{2} + \n@pow{t - (#2)}{2})))}
% \end{macrocode}
% Parametric function for linear approximation of the magnitude of a complex pole.
% \begin{macrocode}
\newcommand*{\MagPoleLin}[2]{(t < sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) ?
-20*log10(sqrt(\n@pow{#1}{2} + \n@pow{#2}{2})) :
-20*log10(t)
)}
% \end{macrocode}
% Parametric function for asymptotic approximation of the magnitude of a complex pole, same as linear approximation.
% \begin{macrocode}
\newcommand*{\MagPoleAsymp}{\MagPoleLin}
% \end{macrocode}
% Parametric function for the true phase of a complex pole.
% \begin{macrocode}
\newcommand*{\PhPole}[2]{((#1 > 0 ? (#2 > 0 ?
(\n@mod{-atan2((t - (#2)),-(#1))}{2*pi}) :
(-atan2((t - (#2)),-(#1)))) :
(-atan2((t - (#2)),-(#1))))*\ph@scale)}
% \end{macrocode}
% Parametric function for linear approximation of the phase of a complex pole.
% \begin{macrocode}
\newcommand*{\PhPoleLin}[2]{
((abs(#1)+abs(#2) == 0 ? -pi/2 :
(t < (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) /
(\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + \n@pow{#2}{2}))})) ?
(-atan2(-(#2),-(#1))) :
(t >= (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) *
(\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} + \n@pow{#2}{2}))})) ?
(#2>0?(#1>0?3*pi/2:-pi/2):-pi/2) :
(-atan2(-(#2),-(#1)) + (log10(t/(sqrt(\n@pow{#1}{2} + \n@pow{#2}{2}) /
(\n@pow{10}{sqrt(\n@pow{#1}{2}/(\n@pow{#1}{2} +
\n@pow{#2}{2}))}))))*((#2>0?(#1>0?3*pi/2:-pi/2):-pi/2) + atan2(-(#2),-(#1)))/
(log10(\n@pow{10}{sqrt((4*\n@pow{#1}{2})/
(\n@pow{#1}{2} + \n@pow{#2}{2}))}))))))*\ph@scale)}
% \end{macrocode}
% Parametric function for asymptotic approximation of the phase of a complex pole.
% \begin{macrocode}
\newcommand*{\PhPoleAsymp}[2]{((t < (sqrt(\n@pow{#1}{2} + \n@pow{#2}{2})) ?
(-atan2(-(#2),-(#1))) :
(#2>0?(#1>0?3*pi/2:-pi/2):-pi/2))*\ph@scale)}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\MagZero}
% \begin{macro}{\MagZeroAsymp}
% \begin{macro}{\MagZeroLin}
% \begin{macro}{\PhZero}
% \begin{macro}{\PhZeroAsymp}
% \begin{macro}{\PhZeroLin}
% Plots of zeros are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3).
% \begin{macrocode}
\newcommand*{\MagZero}{0-\MagPole}
\newcommand*{\MagZeroLin}{0-\MagPoleLin}
\newcommand*{\MagZeroAsymp}{0-\MagPoleAsymp}
\newcommand*{\PhZero}{0-\PhPole}
\newcommand*{\PhZeroLin}{0-\PhPoleLin}
\newcommand*{\PhZeroAsymp}{0-\PhPoleAsymp}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \subsection{Second order systems.}
% Although second order systems can be dealt with using the macros defined so far, the following dedicated macros for second order systems involve less computation.
% \begin{macro}{\MagCSPoles}
% \begin{macro}{\MagCSPolesAsymp}
% \begin{macro}{\MagCSPolesLin}
% \begin{macro}{\PhCSPoles}
% \begin{macro}{\PhCSPolesAsymp}
% \begin{macro}{\PhCSPolesLin}
% \begin{macro}{\MagCSZeros}
% \begin{macro}{\MagCSZerosAsymp}
% \begin{macro}{\MagCSZerosLin}
% \begin{macro}{\PhCSZeros}
% \begin{macro}{\PhCSZerosAsymp}
% \begin{macro}{\PhCSZerosLin}
% Consider the canonical second order transfer function $G(s) = \frac{1}{s^2 + 2 \zeta w_n s + w_n^2}$. We start with true, linear, and asymptotic magnitude plots for this transfer function.
% \begin{macrocode}
\newcommand*{\MagCSPoles}[2]{(-20*log10(sqrt(\n@pow{\n@pow{#2}{2}
- \n@pow{t}{2}}{2} + \n@pow{2*#1*#2*t}{2})))}
\newcommand*{\MagCSPolesLin}[2]{(t < #2 ? -40*log10(#2) : - 40*log10(t))}
\newcommand*{\MagCSPolesAsymp}{\MagCSPolesLin}
% \end{macrocode}
% Then, we have true, linear, and asymptotic phase plots for the canonical second order transfer function.
% \begin{macrocode}
\newcommand*{\PhCSPoles}[2]{((-atan2((2*(#1)*(#2)*t),(\n@pow{#2}{2}
- \n@pow{t}{2})))*\ph@scale)}
\newcommand*{\PhCSPolesLin}[2]{((t < (#2 / (\n@pow{10}{abs(#1)})) ?
0 :
(t >= (#2 * (\n@pow{10}{abs(#1)})) ?
(#1>0 ? -pi : pi) :
(#1>0 ? (-pi*(log10(t*(\n@pow{10}{#1})/#2))/(2*#1)) :
(pi*(log10(t*(\n@pow{10}{abs(#1)})/#2))/(2*abs(#1))))))*\ph@scale)}
\newcommand*{\PhCSPolesAsymp}[2]{((#1>0?(t<#2?0:-pi):(t<#2?0:pi))*\ph@scale)}
% \end{macrocode}
% Plots of the inverse function $G(s)=s^2+2\zeta\omega_n s+\omega_n^2$ are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3).
% \begin{macrocode}
\newcommand*{\MagCSZeros}{0-\MagCSPoles}
\newcommand*{\MagCSZerosLin}{0-\MagCSPolesLin}
\newcommand*{\MagCSZerosAsymp}{0-\MagCSPolesAsymp}
\newcommand*{\PhCSZeros}{0-\PhCSPoles}
\newcommand*{\PhCSZerosLin}{0-\PhCSPolesLin}
\newcommand*{\PhCSZerosAsymp}{0-\PhCSPolesAsymp}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\MagCSPolesPeak}
% \begin{macro}{\MagCSZerosPeak}
% These macros are used to add a resonant peak to linear and asymptotic plots of canonical second order poles and zeros. Since the plots are parametric, a separate |\draw| command is needed to add a vertical arrow.
% \begin{macrocode}
\newcommand*{\MagCSPolesPeak}[3][]{
\draw[#1,->] (axis cs:{#3},{-40*log10(#3)}) --
(axis cs:{#3},{-40*log10(#3)-20*log10(2*abs(#2))})
}
\newcommand*{\MagCSZerosPeak}[3][]{
\draw[#1,->] (axis cs:{#3},{40*log10(#3)}) --
(axis cs:{#3},{40*log10(#3)+20*log10(2*abs(#2))})
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\MagSOPoles}
% \begin{macro}{\MagSOPolesAsymp}
% \begin{macro}{\MagSOPolesLin}
% \begin{macro}{\PhSOPoles}
% \begin{macro}{\PhSOPolesAsymp}
% \begin{macro}{\PhSOPolesLin}
% \begin{macro}{\MagSOZeros}
% \begin{macro}{\MagSOZerosAsymp}
% \begin{macro}{\MagSOZerosLin}
% \begin{macro}{\PhSOZeros}
% \begin{macro}{\PhSOZerosAsymp}
% \begin{macro}{\PhSOZerosLin}
% Consider a general second order transfer function $G(s) = \frac{1}{s^2 + a s + b}$. We start with true, linear, and asymptotic magnitude plots for this transfer function.
% \changes{v1.1.2}{2022/10/29}{Fix scaling bug introduced in v1.1.1}
% \begin{macrocode}
\newcommand*{\MagSOPoles}[2]{
(-20*log10(sqrt(\n@pow{#2 - \n@pow{t}{2}}{2} + \n@pow{#1*t}{2})))}
\newcommand*{\MagSOPolesLin}[2]{
(t < sqrt(abs(#2)) ? -20*log10(abs(#2)) : - 40*log10(t))}
\newcommand*{\MagSOPolesAsymp}{\MagSOPolesLin}
% \end{macrocode}
% Then, we have true, linear, and asymptotic phase plots for the general second order transfer function.
% \begin{macrocode}
\newcommand*{\PhSOPoles}[2]{((-atan2((#1)*t,((#2) - \n@pow{t}{2})))*\ph@scale)}
\newcommand*{\PhSOPolesLin}[2]{((#2>0 ?
\PhCSPolesLin{(#1/(2*sqrt(#2)))}{(sqrt(#2))} :
(#1>0 ? -pi : pi)))}
\newcommand*{\PhSOPolesAsymp}[2]{((#2>0 ?
\PhCSPolesAsymp{(#1/(2*sqrt(#2)))}{(sqrt(#2))} :
(#1>0 ? -pi : pi)))}
% \end{macrocode}
% Plots of the inverse function $G(s)=s^2+as+b$ are defined to be negative of plots of poles. The |0-| is necessary due to a bug in |gnuplot| (fixed in version 5.4, patchlevel 3).
% \begin{macrocode}
\newcommand*{\MagSOZeros}{0-\MagSOPoles}
\newcommand*{\MagSOZerosLin}{0-\MagSOPolesLin}
\newcommand*{\MagSOZerosAsymp}{0-\MagSOPolesAsymp}
\newcommand*{\PhSOZeros}{0-\PhSOPoles}
\newcommand*{\PhSOZerosLin}{0-\PhSOPolesLin}
\newcommand*{\PhSOZerosAsymp}{0-\PhSOPolesAsymp}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\MagSOPolesPeak}
% \begin{macro}{\MagSOZerosPeak}
% These macros are used to add a resonant peak to linear and asymptotic plots of general second order poles and zeros. Since the plots are parametric, a separate |\draw| command is needed to add a vertical arrow.
% \begin{macrocode}
\newcommand*{\MagSOPolesPeak}[3][]{
\draw[#1,->] (axis cs:{sqrt(abs(#3))},{-20*log10(abs(#3))}) --
(axis cs:{sqrt(abs(#3))},{-20*log10(abs(#3)) -
20*log10(abs(#2/sqrt(abs(#3))))});
}
\newcommand*{\MagSOZerosPeak}[3][]{
\draw[#1,->] (axis cs:{sqrt(abs(#3))},{20*log10(abs(#3))}) --
(axis cs:{sqrt(abs(#3))},{20*log10(abs(#3)) +
20*log10(abs(#2/sqrt(abs(#3))))});
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \subsection{Commands for Bode plots}
% \subsubsection{User macros}
% \begin{macro}{\BodeZPK}
% This macro takes lists of complex poles and zeros of the form |{re,im}|, and values of gain and delay as inputs and constructs parametric functions for the Bode magnitude and phase plots. This is done by adding together the parametric functions generated by the macros for individual zeros, poles, gain, and delay, described above. The parametric functions are then plotted in a |tikzpicture| environment using the |\addplot| macro. Unless the package is loaded with the option |pgf|, the parametric functions are evaluated using |gnuplot|. \changes{v1.0.1}{2021/10/29}{Pass arbitrary TikZ commands as options.}
% \begin{macrocode}
\newcommand{\BodeZPK}[4][approx/true]{
% \end{macrocode}
% Most of the work is done by the |\parse@opt| and the |\build@ZPK@plot| macros, described in the 'Internal macros' section. The former is used to parse the optional arguments and the latter to extract poles, zeros, gain, and delay from the first mandatory argument and to generate macros |\func@mag| and |\func@ph| that hold the magnitude and phase parametric functions. The |\noexpand| macros below are needed to so that only the macro |\opt@group| is expanded. \changes{v1.0.3}{2021/11/03}{Added Tikz option}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\parse@opt{#1}
\gdef\func@mag{}
\gdef\func@ph{}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
\temp@cmd
\build@ZPK@plot{\func@mag}{\func@ph}{\opt@approx}{#2}
\edef\temp@cmd{\noexpand\begin{groupplot}[
bode@style,
xmin=#3,
xmax=#4,
domain=#3*\freq@scale:#4*\freq@scale,
height=2.5cm,
xmode=log,
group style = {group size = 1 by 2,vertical sep=0.25cm},
\opt@group
]}
\temp@cmd
% \end{macrocode}
% To ensure frequency tick marks on magnitude and the phase plots are always aligned, we use the |groupplot| library. The |\noexpand| and |\unexpanded\expandafter| macros below are used to expand macros in the plot and group optional arguments.
% \begin{macrocode}
\edef\temp@mag@cmd{\noexpand\nextgroupplot [ylabel={Gain (dB)}, xmajorticks=false, \optmag@axes]
\noexpand\addplot [freq@filter, variable=t, thick, \optmag@plot]}
\edef\temp@ph@cmd{\noexpand\nextgroupplot [ph@y@label, freq@label, \optph@axes]
\noexpand\addplot [freq@filter, variable=t, thick, \optph@plot]}
\if@pgfarg
\temp@mag@cmd {\func@mag};
\optmag@commands
\temp@ph@cmd {\func@ph};
\optph@commands
\else
% \end{macrocode}
% In |gnuplot| mode, we increment the |gnuplot@id| counter before every plot to make sure that new and reusable |.gnuplot| and |.table| files are generated for every plot. We use |raw gnuplot| to make sure that the tables generated by |gnuplot| use the correct phase and frequency units as supplied by the user.
% \begin{macrocode}
\stepcounter{gnuplot@id}
\temp@mag@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set xrange [#3*\freq@scale:#4*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot \func@mag;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2);
};
\optmag@commands
\stepcounter{gnuplot@id}
\temp@ph@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set xrange [#3*\freq@scale:#4*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot \func@ph;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2);
};
\optph@commands
\fi
\end{groupplot}
\end{tikzpicture}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\BodeTF}
% Implementation of this macro is very similar to the |\BodeZPK| macro above. The only difference is the lack of linear and asymptotic plots and slightly different parsing of the mandatory arguments. \changes{v1.0.3}{2021/11/03}{Added Tikz option} \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\BodeTF}[4][]{
\parse@opt{#1}
\gdef\func@mag{}
\gdef\func@ph{}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
\temp@cmd
\build@TF@plot{\func@mag}{\func@ph}{#2}
\edef\temp@cmd{\noexpand\begin{groupplot}[
bode@style,
xmin=#3,
xmax=#4,
domain=#3*\freq@scale:#4*\freq@scale,
height=2.5cm,
xmode=log,
group style = {group size = 1 by 2,vertical sep=0.25cm},
\opt@group
]}
\temp@cmd
\edef\temp@mag@cmd{\noexpand\nextgroupplot [ylabel={Gain (dB)}, xmajorticks=false, \optmag@axes]
\noexpand\addplot [freq@filter, variable=t, thick, \optmag@plot]}
\edef\temp@ph@cmd{\noexpand\nextgroupplot [ph@y@label, freq@label, \optph@axes]
\noexpand\addplot [freq@filter, variable=t, thick, \optph@plot]}
\if@pgfarg
\temp@mag@cmd {\func@mag};
\optmag@commands
\temp@ph@cmd {\n@mod{\func@ph}{2*pi*\ph@scale}};
\optph@commands
\else
\stepcounter{gnuplot@id}
\temp@mag@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set xrange [#3*\freq@scale:#4*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot \func@mag;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2);
};
\optmag@commands
\stepcounter{gnuplot@id}
\temp@ph@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set trange [#3*\freq@scale:#4*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot '+' using (t) : ((\func@ph)/(\ph@scale)) smooth unwrap;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2*\ph@scale);
};
\optph@commands
\fi
\end{groupplot}
\end{tikzpicture}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\addBodeZPKPlots}
% This macro is designed to issues multiple |\addplot| macros for the same set of poles, zeros, gain, and delay. All of the work is done by the |\build@ZPK@plot| macro. \changes{v1.0.1}{2021/10/29}{Improved optional argument handling.}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\addBodeZPKPlots}[3][true/{}]{
\foreach \approx/\opt in {#1} {
\gdef\plot@macro{}
\gdef\temp@macro{}
\ifnum\pdf@strcmp{#2}{phase}=0
\build@ZPK@plot{\temp@macro}{\plot@macro}{\approx}{#3}
\else
\build@ZPK@plot{\plot@macro}{\temp@macro}{\approx}{#3}
\fi
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\edef\temp@cmd{\noexpand\addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, thick, \opt]}
\temp@cmd {\plot@macro};
\else
\stepcounter{gnuplot@id}
\edef\temp@cmd{\noexpand\addplot [variable=t, thick, \opt]}
\temp@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set xrange [\domain@start*\freq@scale:\domain@end*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot \plot@macro;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2);
};
\fi
}
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\addBodeTFPlot}
% This macro is designed to issues a single |\addplot| macros for the set of coefficients and delay. All of the work is done by the |\build@TF@plot| macro. \changes{v1.1.0}{2022/07/06}{Fixed phase wrapping in gnuplot mode}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\addBodeTFPlot}[3][thick]{
\gdef\plot@macro{}
\gdef\temp@macro{}
\ifnum\pdf@strcmp{#2}{phase}=0
\build@TF@plot{\temp@macro}{\plot@macro}{#3}
\else
\build@TF@plot{\plot@macro}{\temp@macro}{#3}
\fi
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\ifnum\pdf@strcmp{#2}{phase}=0
\addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1]{\n@mod{\plot@macro}{2*pi}};
\else
\addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1]{\plot@macro};
\fi
\else
\stepcounter{gnuplot@id}
\ifnum\pdf@strcmp{#2}{phase}=0
\addplot [variable=t, #1] gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set trange [\domain@start*\freq@scale:\domain@end*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot '+' using (t) : ((\plot@macro)/(\ph@scale)) smooth unwrap;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2*\ph@scale);
};
\else
\addplot [variable=t, #1] gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set xrange [\domain@start*\freq@scale:\domain@end*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot \plot@macro;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2);
};
\fi
\fi
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\addBodeComponentPlot}
% This macro is designed to issue a single |\addplot| macro capable of plotting linear combinations of the basic components described in Section \ref{sec:BasicComponents}. The only work to do here is to handle the |pgf| package option.\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\addBodeComponentPlot}[2][thick]{
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\addplot [freq@filter, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1] {#2};
\else
\stepcounter{gnuplot@id}
\addplot [variable=t, #1] gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set dummy t;
set logscale x 10;
set xrange [\domain@start*\freq@scale:\domain@end*\freq@scale];
set samples \pgfkeysvalueof{/pgfplots/samples};
plot #2;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($1/(\freq@scale)):($2);
};
\fi
}
% \end{macrocode}
%\end{macro}
% \begin{environment}{BodePhPlot}
% An environment to host phase plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}
% \begin{macrocode}
\NewEnviron{BodePhPlot}[3][]{
\parse@env@opt{#1}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
\noexpand\begin{semilogxaxis}[
ph@y@label,
freq@label,
bode@style,
xmin={#2},
xmax={#3},
domain=#2:#3,
height=2.5cm,
\unexpanded\expandafter{\opt@axes}
]
}
\temp@cmd
\BODY
\end{semilogxaxis}
\end{tikzpicture}
}
% \end{macrocode}
% \end{environment}
% \begin{environment}{BodeMagPlot}
% An environment to host magnitude plot macros that pass parametric functions to |\addplot| macros. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |semilogaxis| environments.\changes{v1.1.0}{2022/07/20}{Added separate environments for phase and magnitude plots}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}
% \begin{macrocode}
\NewEnviron{BodeMagPlot}[3][]{
\parse@env@opt{#1}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
\noexpand\begin{semilogxaxis}[
bode@style,
freq@label,
xmin={#2},
xmax={#3},
domain=#2:#3,
height=2.5cm,
ylabel={Gain (dB)},
\unexpanded\expandafter{\opt@axes}
]
}
\temp@cmd
\BODY
\end{semilogxaxis}
\end{tikzpicture}
}
% \end{macrocode}
% \end{environment}
% \begin{environment}{BodePlot}
% Same as |BodeMagPlot|. The |BodePlot| environment is deprecated as of v1.1.0, please use the |BodePhPlot| and |BodeMagPlot| environments instead.\changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.0}{2022/02/20}{Deprecated BodePlot environment}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEnviron' command from the `environ' package to fix conflicts with externalization}
% \begin{macrocode}
\NewEnviron{BodePlot}[3][]{
\parse@env@opt{#1}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
\noexpand\begin{semilogxaxis}[
bode@style,
freq@label,
xmin={#2},
xmax={#3},
domain=#2:#3,
height=2.5cm,
\unexpanded\expandafter{\opt@axes}
]
}
\temp@cmd
\BODY
\end{semilogxaxis}
\end{tikzpicture}
}
% \end{macrocode}
% \end{environment}
% \subsubsection{Internal macros}
% \begin{macro}{\add@feature}
% This is an internal macro to add a basic component (pole, zero, gain, or delay), described using one of the macros in Section \ref{sec:BasicComponents} (input |#2|), to a parametric function stored in a global macro (input |#1|). The basic component value (input |#3|) is a complex number of the form |{re,im}|. If the imaginary part is missing, it is assumed to be zero. Implementation made possible by \href{https://tex.stackexchange.com/a/619637/110602}{this StackExchange answer}.
% \begin{macrocode}
\newcommand*{\add@feature}[3]{
\ifcat$\detokenize\expandafter{#1}$
\xdef#1{\unexpanded\expandafter{#1 0+#2}}
\else
\xdef#1{\unexpanded\expandafter{#1+#2}}
\fi
\foreach \y [count=\n] in #3 {
\xdef#1{\unexpanded\expandafter{#1}{\y}}
\xdef\Last@LoopValue{\n}
}
\ifnum\Last@LoopValue=1
\xdef#1{\unexpanded\expandafter{#1}{0}}
\fi
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\build@ZPK@plot}
% This is an internal macro to build parametric Bode magnitude and phase plots by concatenating basic component (pole, zero, gain, or delay) macros (Section \ref{sec:BasicComponents}) to global magnitude and phase macros (inputs |#1| and |#2|). The |\add@feature| macro is used to do the concatenation. The basic component macros are inferred from a |feature/{values}| list, where |feature| is one of |z|,|p|,|k|, and |d|, for zeros, poles, gain, and delay, respectively, and |{values}| is a comma separated list of comma separated lists (complex numbers of the form |{re,im}|). If the imaginary part is missing, it is assumed to be zero.
% \begin{macrocode}
\newcommand{\build@ZPK@plot}[4]{
\foreach \feature/\values in {#4} {
\ifnum\pdf@strcmp{\feature}{z}=0
\foreach \z in \values {
\ifnum\pdf@strcmp{#3}{linear}=0
\add@feature{#2}{\PhZeroLin}{\z}
\add@feature{#1}{\MagZeroLin}{\z}
\else
\ifnum\pdf@strcmp{#3}{asymptotic}=0
\add@feature{#2}{\PhZeroAsymp}{\z}
\add@feature{#1}{\MagZeroAsymp}{\z}
\else
\add@feature{#2}{\PhZero}{\z}
\add@feature{#1}{\MagZero}{\z}
\fi
\fi
}
\fi
\ifnum\pdf@strcmp{\feature}{p}=0
\foreach \p in \values {
\ifnum\pdf@strcmp{#3}{linear}=0
\add@feature{#2}{\PhPoleLin}{\p}
\add@feature{#1}{\MagPoleLin}{\p}
\else
\ifnum\pdf@strcmp{#3}{asymptotic}=0
\add@feature{#2}{\PhPoleAsymp}{\p}
\add@feature{#1}{\MagPoleAsymp}{\p}
\else
\add@feature{#2}{\PhPole}{\p}
\add@feature{#1}{\MagPole}{\p}
\fi
\fi
}
\fi
\ifnum\pdf@strcmp{\feature}{k}=0
\ifnum\pdf@strcmp{#3}{linear}=0
\add@feature{#2}{\PhKLin}{\values}
\add@feature{#1}{\MagKLin}{\values}
\else
\ifnum\pdf@strcmp{#3}{asymptotic}=0
\add@feature{#2}{\PhKAsymp}{\values}
\add@feature{#1}{\MagKAsymp}{\values}
\else
\add@feature{#2}{\PhK}{\values}
\add@feature{#1}{\MagK}{\values}
\fi
\fi
\fi
\ifnum\pdf@strcmp{\feature}{d}=0
\ifnum\pdf@strcmp{#3}{linear}=0
\PackageError {bodeplot} {Linear approximation for pure delays is not
supported.} {Plot the true Bode plot using `true' instead of `linear'.}
\else
\ifnum\pdf@strcmp{#3}{asymptotic}=0
\PackageError {bodeplot} {Asymptotic approximation for pure delays is not
supported.} {Plot the true Bode plot using `true' instead of `asymptotic'.}
\else
\ifdim\values pt < 0pt
\PackageError {bodeplot} {Delay needs to be a positive number.}
\fi
\add@feature{#2}{\PhDel}{\values}
\add@feature{#1}{\MagDel}{\values}
\fi
\fi
\fi
}
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\build@TF@plot}
% This is an internal macro to build parametric Bode magnitude and phase functions by computing the magnitude and the phase given numerator and denominator coefficients and delay (input |#3|). The functions are assigned to user-supplied global magnitude and phase macros (inputs |#1| and |#2|). \changes{v1.0.8}{2022/07/05}{Included phase due to delay in wrapping.}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\build@TF@plot}[3]{
\gdef\num@real{0}
\gdef\num@im{0}
\gdef\den@real{0}
\gdef\den@im{0}
\gdef\loop@delay{0}
\foreach \feature/\values in {#3} {
\ifnum\pdf@strcmp{\feature}{num}=0
\foreach \numcoeff [count=\numpow] in \values {
\xdef\num@degree{\numpow}
}
\foreach \numcoeff [count=\numpow] in \values {
\pgfmathtruncatemacro{\currentdegree}{\num@degree-\numpow}
\ifnum\currentdegree = 0
\xdef\num@real{\num@real+\numcoeff}
\else
\ifodd\currentdegree
\xdef\num@im{\num@im+(\numcoeff*(\n@pow{-1}{(\currentdegree-1)/2})*%
(\n@pow{t}{\currentdegree}))}
\else
\xdef\num@real{\num@real+(\numcoeff*(\n@pow{-1}{(\currentdegree)/2})*%
(\n@pow{t}{\currentdegree}))}
\fi
\fi
}
\fi
\ifnum\pdf@strcmp{\feature}{den}=0
\foreach \dencoeff [count=\denpow] in \values {
\xdef\den@degree{\denpow}
}
\foreach \dencoeff [count=\denpow] in \values {
\pgfmathtruncatemacro{\currentdegree}{\den@degree-\denpow}
\ifnum\currentdegree = 0
\xdef\den@real{\den@real+\dencoeff}
\else
\ifodd\currentdegree
\xdef\den@im{\den@im+(\dencoeff*(\n@pow{-1}{(\currentdegree-1)/2})*%
(\n@pow{t}{\currentdegree}))}
\else
\xdef\den@real{\den@real+(\dencoeff*(\n@pow{-1}{(\currentdegree)/2})*%
(\n@pow{t}{\currentdegree}))}
\fi
\fi
}
\fi
\ifnum\pdf@strcmp{\feature}{d}=0
\xdef\loop@delay{\values}
\fi
}
\xdef#2{((atan2((\num@im),(\num@real))-atan2((\den@im),%
(\den@real))-\loop@delay*t)*(\ph@scale))}
\xdef#1{(20*log10(sqrt((\n@pow{\num@real}{2})+(\n@pow{\num@im}{2})))-%
20*log10(sqrt((\n@pow{\den@real}{2})+(\n@pow{\den@im}{2}))))}
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\parse@opt}
% Parses options supplied to the main Bode macros. A |for| loop over tuples of the form |\obj/\typ/\opt| with a long list of nested if-else statements does the job. If the input |\obj| is |plot|, |axes|, |group|, |approx|, or |tikz| the corresponding |\opt| are passed, unexpanded, to the |\addplot| macro, the |\nextgroupplot| macro, the |groupplot| environment, the |\build@ZPK@plot| macro, and the |tikzpicture| environment, respectively. If |\obj| is |commands|, the corresponding |\opt| are stored, unexpanded, in the macros |\optph@commands| and |\optmag@commands|, to be executed in appropriate |axis| environments. \changes{v1.0.3}{2021/11/03}{Added Tikz option} \changes{v1.0.5}{2021/11/15}{Fixed a bug}
% \begin{macrocode}
\newcommand{\parse@opt}[1]{
\gdef\optmag@axes{}
\gdef\optph@axes{}
\gdef\optph@plot{}
\gdef\optmag@plot{}
\gdef\opt@group{}
\gdef\opt@approx{}
\gdef\optph@commands{}
\gdef\optmag@commands{}
\gdef\opt@tikz{}
\foreach \obj/\typ/\opt in {#1} {
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{plot}=0
\ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{mag}=0
\xdef\optmag@plot{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{ph}=0
\xdef\optph@plot{\unexpanded\expandafter{\opt}}
\else
\xdef\optmag@plot{\unexpanded\expandafter{\opt}}
\xdef\optph@plot{\unexpanded\expandafter{\opt}}
\fi
\fi
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{axes}=0
\ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{mag}=0
\xdef\optmag@axes{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{ph}=0
\xdef\optph@axes{\unexpanded\expandafter{\opt}}
\else
\xdef\optmag@axes{\unexpanded\expandafter{\opt}}
\xdef\optph@axes{\unexpanded\expandafter{\opt}}
\fi
\fi
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{group}=0
\xdef\opt@group{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{approx}=0
\xdef\opt@approx{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{commands}=0
\ifnum\pdf@strcmp{\unexpanded\expandafter{\typ}}{ph}=0
\xdef\optph@commands{\unexpanded\expandafter{\opt}}
\else
\xdef\optmag@commands{\unexpanded\expandafter{\opt}}
\fi
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{tikz}=0
\xdef\opt@tikz{\unexpanded\expandafter{\opt}}
\else
\xdef\optmag@plot{\unexpanded\expandafter{\optmag@plot},
\unexpanded\expandafter{\obj}}
\xdef\optph@plot{\unexpanded\expandafter{\optph@plot},
\unexpanded\expandafter{\obj}}
\fi
\fi
\fi
\fi
\fi
\fi
}
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\parse@env@opt}
% Parses options supplied to the Bode, Nyquist, and Nichols environments. A |for| loop over tuples of the form |\obj/\opt|, processed using nested if-else statements does the job. The input |\obj| should either be |axes| or |tikz|, and the corresponding |\opt| are passed, unexpanded, to the |axis| environment and the |tikzpicture| environment, respectively. \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}
% \begin{macrocode}
\newcommand{\parse@env@opt}[1]{
\gdef\opt@axes{}
\gdef\opt@tikz{}
\foreach \obj/\opt in {#1} {
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{axes}=0
\xdef\opt@axes{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{tikz}=0
\xdef\opt@tikz{\unexpanded\expandafter{\opt}}
\else
\xdef\opt@axes{\unexpanded\expandafter{\opt@axes},
\unexpanded\expandafter{\obj}}
\fi
\fi
}
}
% \end{macrocode}
% \end{macro}
% \subsection{Nyquist plots}
% \subsubsection{User macros}
% \begin{macro}{\NyquistZPK}
% Converts magnitude and phase parametric functions built using |\build@ZPK@plot| into real part and imaginary part parametric functions. A plot of these is the Nyquist plot. The parametric functions are then plotted in a |tikzpicture| environment using the |\addplot| macro. Unless the package is loaded with the option |pgf|, the parametric functions are evaluated using |gnuplot|. A large number of samples is typically needed to get a smooth plot because frequencies near 0 result in plot points that are very close to each other. Linear frequency sampling is unnecessarily fine near zero and very coarse for large $\omega$. Logarithmic sampling makes it worse, perhaps inverse logarithmic sampling will help, pull requests to fix that are welcome! \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\NyquistZPK}[4][]{
\parse@N@opt{#1}
\gdef\func@mag{}
\gdef\func@ph{}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
\temp@cmd
\build@ZPK@plot{\func@mag}{\func@ph}{}{#2}
\edef\temp@cmd{\noexpand\begin{axis}[
bode@style,
domain=#3*\freq@scale:#4*\freq@scale,
height=5cm,
xlabel={$\Re$},
ylabel={$\Im$},
samples=500,
\unexpanded\expandafter{\opt@axes}
]}
\temp@cmd
\addplot [only marks,mark=+,thick,red] (-1 , 0);
\edef\temp@cmd{\noexpand\addplot [variable=t, thick, \unexpanded\expandafter{\opt@plot}]}
\if@pgfarg
\temp@cmd ( {\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale))},
{\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))} );
\opt@commands
\else
\stepcounter{gnuplot@id}
\temp@cmd gnuplot [parametric, gnuplot@prefix] {
\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale)),
\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))
};
\opt@commands
\fi
\end{axis}
\end{tikzpicture}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\NyquistTF}
% Implementation of this macro is very similar to the |\NyquistZPK| macro above. The only difference is a slightly different parsing of the mandatory arguments via |\build@TF@plot|. \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\NyquistTF}[4][]{
\parse@N@opt{#1}
\gdef\func@mag{}
\gdef\func@ph{}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
\temp@cmd
\build@TF@plot{\func@mag}{\func@ph}{#2}
\edef\temp@cmd{\noexpand\begin{axis}[
bode@style,
domain=#3*\freq@scale:#4*\freq@scale,
height=5cm,
xlabel={$\Re$},
ylabel={$\Im$},
samples=500,
\unexpanded\expandafter{\opt@axes}
]}
\temp@cmd
\addplot [only marks, mark=+, thick, red] (-1 , 0);
\edef\temp@cmd{\noexpand\addplot [variable=t, thick, \unexpanded\expandafter{\opt@plot}]}
\if@pgfarg
\temp@cmd ( {\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale))},
{\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))} );
\opt@commands
\else
\stepcounter{gnuplot@id}
\temp@cmd gnuplot [parametric, gnuplot@prefix] {
\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale)),
\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))
};
\opt@commands
\fi
\end{axis}
\end{tikzpicture}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\addNyquistZPKPlot}
% Adds Nyquist plot of a transfer function in ZPK form. This macro is designed to pass two parametric function to an |\addplot| macro. The parametric functions for phase (|\func@ph|) and magnitude (|\func@mag|) are built using the |\build@ZPK@plot| macro, converted to real and imaginary parts and passed to |\addplot| commands.\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\addNyquistZPKPlot}[2][]{
\gdef\func@mag{}
\gdef\func@ph{}
\build@ZPK@plot{\func@mag}{\func@ph}{}{#2}
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\addplot [domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1] ( {\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale))},
{\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))} );
\else
\stepcounter{gnuplot@id}
\addplot [domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1] gnuplot [parametric, gnuplot@prefix] {
\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale)),
\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))
};
\fi
}
% \end{macrocode}
%\end{macro}
% \begin{macro}{\addNyquistTFPlot}
% Adds Nyquist plot of a transfer function in TF form. This macro is designed to pass two parametric function to an |\addplot| macro. The parametric functions for phase (|\func@ph|) and magnitude (|\func@mag|) are built using the |\build@TF@plot| macro, converted to real and imaginary parts and passed to |\addplot| commands.\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\addNyquistTFPlot}[2][]{
\gdef\func@mag{}
\gdef\func@ph{}
\build@TF@plot{\func@mag}{\func@ph}{#2}
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\addplot [domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1] ( {\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale))},
{\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))} );
\else
\stepcounter{gnuplot@id}
\addplot [domain=\domain@start*\freq@scale:\domain@end*\freq@scale, variable=t, #1] gnuplot [parametric, gnuplot@prefix]{
\n@pow{10}{((\func@mag)/20)}*cos((\func@ph)/(\ph@scale)),
\n@pow{10}{((\func@mag)/20)}*sin((\func@ph)/(\ph@scale))
};
\fi
}
% \end{macrocode}
%\end{macro}
%\begin{macro}{NyquistPlot}
% An environment to host |\addNyquist...| macros that pass parametric functions to |\addplot|. Uses the defaults specified in |bode@style| to create a shortcut that includes the |tikzpicture| and |axis| environments. \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEniron' command from the `environ' package to fix conflicts with externalization}
% \begin{macrocode}
\NewEnviron{NyquistPlot}[3][]{
\parse@env@opt{#1}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
\noexpand\begin{axis}[
bode@style,
height=5cm,
domain=#2:#3,
xlabel={$\Re$},
ylabel={$\Im$},
\unexpanded\expandafter{\opt@axes}
]
}
\temp@cmd
\addplot [only marks,mark=+,thick,red] (-1 , 0);
\BODY
\end{axis}
\end{tikzpicture}
}
% \end{macrocode}
%\end{macro}
% \subsubsection{Internal commands\label{sec:NInternal}}
% \begin{macro}{\parse@N@opt}
% Parses options supplied to the main Nyquist and Nichols macros. A |for| loop over tuples of the form |\obj/\opt|, processed using nested if-else statements does the job. If the input |\obj| is |plot|, |axes|, or |tikz| then the corresponding |\opt| are passed, unexpanded, to the |\addplot| macro, the |axis| environment, and the |tikzpicture| environment, respectively. \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}
% \begin{macrocode}
\newcommand{\parse@N@opt}[1]{
\gdef\opt@axes{}
\gdef\opt@plot{}
\gdef\opt@commands{}
\gdef\opt@tikz{}
\foreach \obj/\opt in {#1} {
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{axes}=0
\xdef\opt@axes{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{plot}=0
\xdef\opt@plot{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{commands}=0
\xdef\opt@commands{\unexpanded\expandafter{\opt}}
\else
\ifnum\pdf@strcmp{\unexpanded\expandafter{\obj}}{tikz}=0
\xdef\opt@tikz{\unexpanded\expandafter{\opt}}
\else
\xdef\opt@plot{\unexpanded\expandafter{\opt@plot},
\unexpanded\expandafter{\obj}}
\fi
\fi
\fi
\fi
}
}
% \end{macrocode}
% \end{macro}
% \subsection{Nichols charts}
% \begin{macro}{\NicholsZPK}
% \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}
% \begin{macro}{\NicholsTF}
% \changes{v1.0.3}{2021/11/03}{Added commands and tikz options}
% \begin{macro}{NicholsChart}
% \changes{v1.0.3}{2021/11/03}{Added tikz option to environments}\changes{v1.1.2}{2022/10/29}{Defined using the `NewEniron' command from the `environ' package to fix conflicts with externalization}
% \begin{macro}{\addNicholsZPKChart}
% \begin{macro}{\addNicholsTFChart}
% These macros and the |NicholsChart| environment generate Nichols charts, and they are implemented similar to their Nyquist counterparts.\changes{v1.1.1}{2022/07/31}{Enabled `Hz' and `rad' units for frequency and phase, respectively}
% \begin{macrocode}
\newcommand{\NicholsZPK}[4][]{
\parse@N@opt{#1}
\gdef\func@mag{}
\gdef\func@ph{}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
\temp@cmd
\build@ZPK@plot{\func@mag}{\func@ph}{}{#2}
\edef\temp@cmd{\noexpand\begin{axis}[
ph@x@label,
bode@style,
domain=#3*\freq@scale:#4*\freq@scale,
height=5cm,
ylabel={Gain (dB)},
samples=500,
\unexpanded\expandafter{\opt@axes}
]}
\temp@cmd
\edef\temp@cmd{\noexpand\addplot [variable=t,thick,\opt@plot]}
\if@pgfarg
\temp@cmd ( {\func@ph} , {\func@mag} );
\opt@commands
\else
\stepcounter{gnuplot@id}
\temp@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set logscale x 10;
set dummy t;
set samples \pgfkeysvalueof{/pgfplots/samples};
set trange [#3*\freq@scale:#4*\freq@scale];
plot '+' using (\func@mag) : ((\func@ph)/(\ph@scale));
unset logscale x;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($2*\ph@scale):($1);
};
\opt@commands
\fi
\end{axis}
\end{tikzpicture}
}
\newcommand{\NicholsTF}[4][]{
\parse@N@opt{#1}
\gdef\func@mag{}
\gdef\func@ph{}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]}
\temp@cmd
\build@TF@plot{\func@mag}{\func@ph}{#2}
\edef\temp@cmd{\noexpand\begin{axis}[
ph@x@label,
bode@style,
domain=#3*\freq@scale:#4*\freq@scale,
height=5cm,
ylabel={Gain (dB)},
samples=500,
\unexpanded\expandafter{\opt@axes}
]}
\temp@cmd
\edef\temp@cmd{\noexpand\addplot [variable=t,thick, \opt@plot]}
\if@pgfarg
\temp@cmd ( {\n@mod{\func@ph}{2*pi*\ph@scale}} , {\func@mag} );
\opt@commands
\else
\stepcounter{gnuplot@id}
\temp@cmd gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta1;
set logscale x 10;
set dummy t;
set samples \pgfkeysvalueof{/pgfplots/samples};
set trange [#3*\freq@scale:#4*\freq@scale];
plot '+' using (\func@mag) : ((\func@ph)/(\ph@scale));
unset logscale x;
set table $meta2;
plot "$meta1" using ($1):($2) smooth unwrap;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta2" using ($2*\ph@scale):($1);
};
\opt@commands
\fi
\end{axis}
\end{tikzpicture}
}
\NewEnviron{NicholsChart}[3][]{
\parse@env@opt{#1}
\edef\temp@cmd{\noexpand\begin{tikzpicture} [\unexpanded\expandafter{\opt@tikz}]
\noexpand\begin{axis}[
ph@x@label,
bode@style,
domain=#2:#3,
height=5cm,
ylabel={Gain (dB)},
\unexpanded\expandafter{\opt@axes}
]
}
\temp@cmd
\BODY
\end{axis}
\end{tikzpicture}
}
\newcommand{\addNicholsZPKChart}[2][]{
\gdef\func@mag{}
\gdef\func@ph{}
\build@ZPK@plot{\func@mag}{\func@ph}{}{#2}
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\addplot [variable=t, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, #1] ( {\func@ph} , {\func@mag} );
\else
\stepcounter{gnuplot@id}
\addplot [#1] gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta;
set logscale x 10;
set dummy t;
set samples \pgfkeysvalueof{/pgfplots/samples};
set trange [\domain@start*\freq@scale:\domain@end*\freq@scale];
plot '+' using (\func@mag) : ((\func@ph)/(\ph@scale));
unset logscale x;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta" using ($2*\ph@scale):($1);
};
\fi
}
\newcommand{\addNicholsTFChart}[2][]{
\gdef\func@mag{}
\gdef\func@ph{}
\build@TF@plot{\func@mag}{\func@ph}{#2}
\edef\supplied@domain{\pgfkeysvalueof{/pgfplots/domain}}
\edef\domain@start{\expandafter\get@interval@start\supplied@domain\@nil}
\edef\domain@end{\expandafter\get@interval@end\supplied@domain\@nil}
\if@pgfarg
\addplot [variable=t, domain=\domain@start*\freq@scale:\domain@end*\freq@scale, #1] ( {\n@mod{\func@ph}{2*pi*\ph@scale}} , {\func@mag} );
\else
\stepcounter{gnuplot@id}
\addplot [#1] gnuplot [raw gnuplot, gnuplot@prefix]
{ set table $meta1;
set logscale x 10;
set dummy t;
set samples \pgfkeysvalueof{/pgfplots/samples};
set trange [\domain@start*\freq@scale:\domain@end*\freq@scale];
plot '+' using (\func@mag) : ((\func@ph)/(\ph@scale));
unset logscale x;
set table $meta2;
plot "$meta1" using ($1):($2) smooth unwrap;
set table "\bodeplot@prefix\arabic{gnuplot@id}.table";
plot "$meta2" using ($2*\ph@scale):($1);
};
\fi
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \Finale
\endinput
+
+ + + +
+ +
+ + + + +
+ + +
+ + +
+
+ + + +
+ +
+ + +
+ +
+ + +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + diff --git a/graphics/pgf/contrib/bodeplot/bodeplot.ins b/graphics/pgf/contrib/bodeplot/bodeplot.ins index 1a80024f83..88209ac674 100644 --- a/graphics/pgf/contrib/bodeplot/bodeplot.ins +++ b/graphics/pgf/contrib/bodeplot/bodeplot.ins @@ -1,41 +1,3138 @@ -%% -%% Copyright (C) 2021 by Rushikesh Kamalapurkar -%% -%% This file may be distributed and/or modified under the -%% conditions of the LaTeX Project Public License, either -%% version 1.3c of this license or (at your option) any later -%% version. The latest version of this license is in: -%% -%% http://www.latex-project.org/lppl.txt -%% -%% and version 1.3c or later is part of all distributions of -%% LaTeX version 2006/05/20 or later. -%% -\input docstrip.tex -\keepsilent -\usedir{tex/latex/bodeplot} -\preamble -This is a generated file. -Copyright (C) 2021 by Rushikesh Kamalapurkar -This file may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either -version 1.3c of this license or (at your option) any later -version. The latest version of this license is in: -http://www.latex-project.org/lppl.txt -and version 1.3c or later is part of all distributions of -LaTeX version 2006/05/20 or later. -\endpreamble -\generate{\file{bodeplot.sty}{\from{bodeplot.dtx}{package}}} -\Msg{*********************************************************} -\Msg{*} -\Msg{* To finish the installation you have to move the} -\Msg{* following file into a directory searched by TeX:} -\Msg{*} -\Msg{* bodeplot.sty} -\Msg{*} -\Msg{* To produce the documentation run the file bodeplot.dtx} -\Msg{* through LaTeX.} -\Msg{*} -\Msg{* Happy TeXing!} -\Msg{*********************************************************} -\endbatchfile \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bodeplot/bodeplot.ins at main · rlkamalapurkar/bodeplot + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Skip to content + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+ + + + + +
+ + + + + + + + + +
+ + + + + + + + + + + + + + + + + + +
+ +
+ + + + rlkamalapurkar  /   + bodeplot  /   + +
+
+ + + +
+ + +
+
+ Clear Command Palette +
+
+ + + +
+
+ Tip: + Type # to search pull requests +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type # to search issues +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type # to search discussions +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type ! to search projects +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type @ to search teams +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type @ to search people and organizations +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type > to activate command mode +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Go to your accessibility settings to change your keyboard shortcuts +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type author:@me to search your content +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:pr to filter to pull requests +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:issue to filter to issues +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:project to filter to projects +
+
+ Type ? for help and tips +
+
+
+ +
+
+ Tip: + Type is:open to filter to open content +
+
+ Type ? for help and tips +
+
+
+ +
+ +
+
+ We’ve encountered an error and some results aren't available at this time. Type a new search or try again later. +
+
+ + No results matched your search + + + + + + + + + + +
+ + + + + Search for issues and pull requests + + # + + + + Search for issues, pull requests, discussions, and projects + + # + + + + Search for organizations, repositories, and users + + @ + + + + Search for projects + + ! + + + + Search for files + + / + + + + Activate command mode + + > + + + + Search your issues, pull requests, and discussions + + # author:@me + + + + Search your issues, pull requests, and discussions + + # author:@me + + + + Filter to pull requests + + # is:pr + + + + Filter to issues + + # is:issue + + + + Filter to discussions + + # is:discussion + + + + Filter to projects + + # is:project + + + + Filter to open issues, pull requests, and discussions + + # is:open + + + + + + + + + + + + + + + + +
+
+
+ +
+ + + + + + + + + + +
+ + +
+
+
+ + + + + + + + + + +
+ +
+ +
+ +
+ + + + / + + bodeplot + + + Public +
+ + +
+ +
    + +
  • +
    +
    +
    +
  • + + +
  • + +
    + + + + + Unwatch + + + + + 1 + + + +
    +
    +

    Notifications

    + +
    + +
    +
    + + + + + + + + +
    + + +
    + + + + + Get push notifications on iOS or Android. + +
    +
    +
    +
    + + + + +
    +
    +
    + + + +
  • + +
  • +
    + Fork + 1 + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
  • + +
  • + + +
    +
    +
    + + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
    +
    +
    + +
    + + + +
    + +
    +
    + + + + + + + +
    + +
    +
    +
    +
    +
    +
  • + + + +
+ +
+ +
+
+ + + + + + +
+ + + + +
+ Open in github.dev + Open in a new github.dev tab + + + + + + +
+ + +
+ + + + + + + + +Permalink + +
+ +
+
+ + + main + + + + +
+
+
+ Switch branches/tags + +
+ + + +
+ +
+ +
+ + +
+ +
+ + + + + + + + + + + + + + + + + +
+ + +
+
+
+
+ +
+ +
+ + +
+ +
+
+
+

Name already in use

+
+
+ +
+
+
+
+ +
A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? +
+ +
+
+ + +
+
+ + + + Go to file + +
+ + + + +
+
+
+ + + + + + + + + +
+ +
+
+
 
+
+ +
+
 
+ Cannot retrieve contributors at this time +
+
+ + + + + + + + + + + + + +
+ +
+ + +
+ + 41 lines (41 sloc) + + 1.38 KB +
+ +
+ + + + +
+ +
+
+
+
+ +
+ +
+
+
+ + + +
+ + + + + + + + + +
+ + +
+ +
+
+ +
+ +
+
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
%%
%% Copyright (C) 2021 by Rushikesh Kamalapurkar
%%
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
%% version 1.3c of this license or (at your option) any later
%% version. The latest version of this license is in:
%%
%% http://www.latex-project.org/lppl.txt
%%
%% and version 1.3c or later is part of all distributions of
%% LaTeX version 2006/05/20 or later.
%%
\input docstrip.tex
\keepsilent
\usedir{tex/latex/bodeplot}
\preamble
This is a generated file.
Copyright (C) 2021 by Rushikesh Kamalapurkar
This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
version 1.3c of this license or (at your option) any later
version. The latest version of this license is in:
http://www.latex-project.org/lppl.txt
and version 1.3c or later is part of all distributions of
LaTeX version 2006/05/20 or later.
\endpreamble
\generate{\file{bodeplot.sty}{\from{bodeplot.dtx}{package}}}
\Msg{*********************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the}
\Msg{* following file into a directory searched by TeX:}
\Msg{*}
\Msg{* bodeplot.sty}
\Msg{*}
\Msg{* To produce the documentation run the file bodeplot.dtx}
\Msg{* through LaTeX.}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*********************************************************}
\endbatchfile
+
+ + + +
+ +
+ + + + +
+ + +
+ + +
+
+ + + +
+ +
+ + +
+ +
+ + +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + diff --git a/graphics/pgf/contrib/bodeplot/bodeplot.pdf b/graphics/pgf/contrib/bodeplot/bodeplot.pdf index e47b655740..f866f3ba55 100644 Binary files a/graphics/pgf/contrib/bodeplot/bodeplot.pdf and b/graphics/pgf/contrib/bodeplot/bodeplot.pdf differ diff --git a/macros/generic/tracklang/CHANGES b/macros/generic/tracklang/CHANGES index 8725ee915d..a873a80927 100644 --- a/macros/generic/tracklang/CHANGES +++ b/macros/generic/tracklang/CHANGES @@ -1,3 +1,9 @@ +v1.6 (2022-10-29); + + * Replaced \x with \@tracklang@x + + * Added check for polyglossia's \xpg@bcp@loaded and \mainbabelname + v1.5 (2020-06-30): * Removed redundant code and added debug message to diff --git a/macros/generic/tracklang/README b/macros/generic/tracklang/README index caac438bc4..be053cda76 100644 --- a/macros/generic/tracklang/README +++ b/macros/generic/tracklang/README @@ -1,6 +1,6 @@ -Generic TeX Bundle : tracklang v1.5 +Generic TeX Bundle : tracklang v1.6 -Last Modified : 2020-06-30 +Last Modified : 2022-10-29 Author : Nicola Talbot (dickimaw-books.com/contact) @@ -9,7 +9,7 @@ Licence: This material is subject to the LaTeX Project Public License. See http://www.ctan.org/license/lppl1.3 for the details of that license. -Copyright 2014-2020 Nicola Talbot +Copyright 2014-2022 Nicola Talbot Description: diff --git a/macros/generic/tracklang/samples/animals/sample-animals-babel.pdf b/macros/generic/tracklang/samples/animals/sample-animals-babel.pdf index 35cb126385..eaae49c629 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals-babel.pdf and b/macros/generic/tracklang/samples/animals/sample-animals-babel.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf b/macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf index 73ce65645d..978dca7662 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf and b/macros/generic/tracklang/samples/animals/sample-animals-de-poly.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex b/macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex index bb96c76cd4..1d8335e411 100644 --- a/macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex +++ b/macros/generic/tracklang/samples/animals/sample-animals-de-poly.tex @@ -3,6 +3,7 @@ \usepackage{polyglossia} \setmainlanguage{german} +\setotherlanguage[variant=uk]{english} \usepackage{animals} diff --git a/macros/generic/tracklang/samples/animals/sample-animals-de.pdf b/macros/generic/tracklang/samples/animals/sample-animals-de.pdf index 6ee9ea4efa..2b8babf868 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals-de.pdf and b/macros/generic/tracklang/samples/animals/sample-animals-de.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals-poly.pdf b/macros/generic/tracklang/samples/animals/sample-animals-poly.pdf index 19144645ce..ab30068b06 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals-poly.pdf and b/macros/generic/tracklang/samples/animals/sample-animals-poly.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals-sr-poly.pdf b/macros/generic/tracklang/samples/animals/sample-animals-sr-poly.pdf deleted file mode 100644 index 7e746cba6a..0000000000 Binary files a/macros/generic/tracklang/samples/animals/sample-animals-sr-poly.pdf and /dev/null differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals.pdf b/macros/generic/tracklang/samples/animals/sample-animals.pdf index 89632f165a..a041ee1c86 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals.pdf and b/macros/generic/tracklang/samples/animals/sample-animals.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals2-de.pdf b/macros/generic/tracklang/samples/animals/sample-animals2-de.pdf index 5f22dca624..fe493b0128 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals2-de.pdf and b/macros/generic/tracklang/samples/animals/sample-animals2-de.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf b/macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf index b2277b8b98..f49bedd70e 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf and b/macros/generic/tracklang/samples/animals/sample-animals2-de2.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf b/macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf index 069a48e10c..ca3fd6436c 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf and b/macros/generic/tracklang/samples/animals/sample-animals2-de3.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf b/macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf index ce6a514e5c..147cebfa75 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf and b/macros/generic/tracklang/samples/animals/sample-animals2-de4.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf b/macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf index 8809c66b85..34a77bb8af 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf and b/macros/generic/tracklang/samples/animals/sample-animals2-poly.pdf differ diff --git a/macros/generic/tracklang/samples/animals/sample-animals2.pdf b/macros/generic/tracklang/samples/animals/sample-animals2.pdf index fbd7a234d6..3569a4e0a7 100644 Binary files a/macros/generic/tracklang/samples/animals/sample-animals2.pdf and b/macros/generic/tracklang/samples/animals/sample-animals2.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions.pdf b/macros/generic/tracklang/samples/regions/sample-regions.pdf index fab8f6977b..1ce67099c9 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions.pdf and b/macros/generic/tracklang/samples/regions/sample-regions.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf b/macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf index 93f3428fb3..30857213d9 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf and b/macros/generic/tracklang/samples/regions/sample-regions2-manx.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions2-map.pdf b/macros/generic/tracklang/samples/regions/sample-regions2-map.pdf index db87696734..5584b2cbbb 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions2-map.pdf and b/macros/generic/tracklang/samples/regions/sample-regions2-map.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf b/macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf index 4784228ed8..0f1bbdee0f 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf and b/macros/generic/tracklang/samples/regions/sample-regions2-map2.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf b/macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf index 90546af2b0..033e92230f 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf and b/macros/generic/tracklang/samples/regions/sample-regions2-map3.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf b/macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf index 167a38fcf7..317868d773 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf and b/macros/generic/tracklang/samples/regions/sample-regions2-nomap.pdf differ diff --git a/macros/generic/tracklang/samples/regions/sample-regions2.pdf b/macros/generic/tracklang/samples/regions/sample-regions2.pdf index d7393715ff..beff20b615 100644 Binary files a/macros/generic/tracklang/samples/regions/sample-regions2.pdf and b/macros/generic/tracklang/samples/regions/sample-regions2.pdf differ diff --git a/macros/generic/tracklang/samples/sample-tracklang.pdf b/macros/generic/tracklang/samples/sample-tracklang.pdf index 6d5a7dbf53..673ab5eca0 100644 Binary files a/macros/generic/tracklang/samples/sample-tracklang.pdf and b/macros/generic/tracklang/samples/sample-tracklang.pdf differ diff --git a/macros/generic/tracklang/samples/sample-tracklang2.pdf b/macros/generic/tracklang/samples/sample-tracklang2.pdf index d2f16a3e3e..a30b727c2f 100644 Binary files a/macros/generic/tracklang/samples/sample-tracklang2.pdf and b/macros/generic/tracklang/samples/sample-tracklang2.pdf differ diff --git a/macros/generic/tracklang/samples/sample-tracklang3.pdf b/macros/generic/tracklang/samples/sample-tracklang3.pdf index 8966ec23fa..bf447bd2c1 100644 Binary files a/macros/generic/tracklang/samples/sample-tracklang3.pdf and b/macros/generic/tracklang/samples/sample-tracklang3.pdf differ diff --git a/macros/generic/tracklang/samples/sample-tracklang4.pdf b/macros/generic/tracklang/samples/sample-tracklang4.pdf index b65563f2fd..814a359e94 100644 Binary files a/macros/generic/tracklang/samples/sample-tracklang4.pdf and b/macros/generic/tracklang/samples/sample-tracklang4.pdf differ diff --git a/macros/generic/tracklang/samples/sample-tracklang5.pdf b/macros/generic/tracklang/samples/sample-tracklang5.pdf index 3446d96ec5..eb7216d024 100644 Binary files a/macros/generic/tracklang/samples/sample-tracklang5.pdf and b/macros/generic/tracklang/samples/sample-tracklang5.pdf differ diff --git a/macros/generic/tracklang/samples/sample-tracklang6.pdf b/macros/generic/tracklang/samples/sample-tracklang6.pdf index 1f3cce82ec..f99105384c 100644 Binary files a/macros/generic/tracklang/samples/sample-tracklang6.pdf and b/macros/generic/tracklang/samples/sample-tracklang6.pdf differ diff --git a/macros/generic/tracklang/tracklang-code.pdf b/macros/generic/tracklang/tracklang-code.pdf new file mode 100644 index 0000000000..919ae64212 Binary files /dev/null and b/macros/generic/tracklang/tracklang-code.pdf differ diff --git a/macros/generic/tracklang/tracklang-manual.html b/macros/generic/tracklang/tracklang-manual.html new file mode 100644 index 0000000000..e45ec14494 --- /dev/null +++ b/macros/generic/tracklang/tracklang-manual.html @@ -0,0 +1,6522 @@ + + + + + + tracklang.sty v1.6: +tracking language options + + + +
+
tracklang.sty v1.6: tracking language options
Nicola L.C. Talbot
+ Dickimaw Books
+ dickimaw-books.com
2022-10-29

+

+ +

Abstract
+ The tracklang package is provided for package developers who want a simple interface to find out which languages the user has requested through packages such as babel and polyglossia. This package doesn’t provide any translations. Its purpose is simply to track which languages have been requested by the user. Generic TeX code is in tracklang.tex for non-LaTeX users.

+If the shell escape is enabled or \directlua is available, this package may also be used to query the LC_ALL or LANG environment variable (see §6). Windows users, who don’t have the locale stored in environment variables, can use texosquery in combination with tracklang. (Similarly if LC_ALL or LANG don’t contain sufficient information.) In order to use texosquery through the restricted shell escape, you must have at least Java 8 and set up texosquery.cfg appropriately. (See the texosquery manual for further details.)

+

+The fundamental aim of this generic package is to be able to effectively say:

The user (that is, the document author) wants to use dialects xx-XX, yy-YY-Scrp, etc in their document. Any packages used by their document that provide multilingual or region-dependent support should do whatever is required to activate the settings for those languages and regions (or warn the user that there’s no support).
Naturally, this is only of use if the locale-sensitive packages use tracklang to pick up this information, which is entirely up to the package authors, but at the moment there’s no standard method for packages to detect the required language and region. The aim of tracklang is to provide that method. In particular, the emphasis is on using ISO language and region codes rather than hard-coding the various language labels used by different language packages.

+Related articles: “Localisation of TeX documents: tracklang.” TUGboat, Volume 37 (2016), No. 3, Localisation with tracklang.tex, and tracklang FAQ.

+

+ + +
+

List of Tables

+

+ +

+ +
+
I. User Guide
+

+ +

+ +
+

1. Introduction

+

+When I’m developing a package that provides multilingual support (for example, glossaries) it’s cumbersome trying to work out if the user has requested translations for fixed text. This usually involves checking if babel or translator or polyglossia has been loaded and, if so, what language settings have been used. The result can be a tangled mass of conditional code. The alternative is to tell users to add the language as a document class option, which they may or may not want to do, or to tell them to supply the language settings to every package they load that provides multilingual support, which users are even less likely to want to do.

+The tracklang package tries to neaten this up by working out as much of this information as possible for you and providing a command that iterates through the loaded languages. This way, you can just iterate through the list of tracked languages and, for each language, either define the translations or warn the user that there’s no translation for that language.

+This package works best with ngerman and german (since it’s a simple test to determine if they have been loaded) and recent versions of polyglossia (which conveniently provides \xpg@bcp@loaded) or when the language options are specified in the document class option list. It works fairly well with translator but will additionally assume the root language was also requested when a dialect is specified. So, for example,

\usepackage[british]{translator}
+\usepackage{tracklang}
+
is equivalent to
\usepackage[british]{translator}
+\usepackage[english,british]{tracklang}
+
This means that \ForEachTrackedDialect will iterate through the list english,british instead of just british, which can result in some redundancy.

+Unfortunately I can’t find any way of detecting a list of languages loaded through babel’s new \babelprovide command. As far as I can tell, the only stored list is in \bbl@loaded which only contains the languages loaded through package options.

+If the ngerman package has been loaded, tracklang effectively does:

\TrackPredefinedDialect{ngerman}
+
Similarly, if the german package has been loaded, tracklang effectively does
\TrackPredefinedDialect{german}
+

+If any document class or package options are passed to tracklang, then tracklang won’t bother checking for babel, translator, ngerman, german or polyglossia. So, if the above example is changed to:

\documentclass[british]{article}
+\usepackage{translator}
+\usepackage{tracklang}
+
then the dialect list will just consist of british rather than english,british. This does, however, mean that if the user mixes class and package options, only the class options will be detected. For example:
\documentclass[british]{article}
+\usepackage[french]{babel}
+\usepackage{tracklang}
+
In this case, only the british option will be detected. The user can therefore use the document class option (or tracklang package option) to override the dialect and set the country code (where provided). For example:
\documentclass[es-MX]{article}
+\usepackage[spanish]{babel}
+\usepackage{tracklang}
+
This sets the dialect to mexicanspanish and the root language to spanish.

+Predefined dialects are listed in Tables 1.1, 1.2 & 1.3. These may be passed in the document class options or used in \TrackPredefinedDialect, as illustrated above.

2 provides brief examples of use for those who want a general overview before reading the more detailed sections. §3 describes generic commands for identifying the document languages. §5 is for package writers who want to add multilingual support to their package and need to know which settings the user has requested through language packages like babel. §6 is for developers of language definition packages who want to help other package writers to detect what languages have been requested.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1: Predefined ISO Language-Region Dialects. (ISO tag or dialect label may be used as a package option or with \TrackPredefinedDialect)
ISO TagDialect LabelISO TagDialect Label
cy-GBGBwelsh +de-ATaustrian
de-AT-1996naustrian +de-BEbelgiangerman
de-CHswissgerman +de-CH-1996nswissgerman
de-DEgermanDE +de-DE-1996ngermanDE
en-AUaustralian +en-CAcanadian
en-GBbritish +en-GGguernseyenglish
en-IEIEenglish +en-IMisleofmanenglish
en-JEjerseyenglish +en-MTmaltaenglish
en-NZnewzealand +en-USamerican
es-ARargentinespanish +es-BObolivianspanish
es-CLchilianspanish +es-COcolumbianspanish
es-CRcostaricanspanish +es-CUcubanspanish
es-DOdominicanspanish +es-ECecudorianspanish
es-ESspainspanish +es-GTguatemalanspanish
es-HNhonduranspanish +es-MXmexicanspanish
es-NInicaraguanspanish +es-PApanamaspanish
es-PEperuvianspanish +es-PRpuertoricospanish
es-PYparaguayspanish +es-SVelsalvadorspanish
es-UYuruguayspanish +es-VEvenezuelanspanish
fr-BEbelgique +fr-CAcanadien
fr-CHswissfrench +fr-FRfrance
fr-GGguernseyfrench +fr-JEjerseyfrench
ga-GBGBirish +ga-IEIEirish
gd-GBGBscottish +hr-HRcroatia
hu-HUhungarian +id-INbahasa
it-CHswissitalian +it-HRistriacountyitalian
it-ITitaly +it-SIsloveneistriaitalian
it-SMsanmarino +it-VAvatican
ms-MYmalay +mt-MTmaltamaltese
nl-BEflemish +nl-NLnetherlands
pt-BRbrazilian +pt-PTportugal
rm-CHswissromansh +sl-SIslovenia
Other combinations need to be set with \TrackLocale or \TrackLanguageTag
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 2: Predefined Root Languages. (Has an associated territory.) The corresponding tag obtained with \GetTrackedLanguageTag{dialect} is shown in parentheses
abkhaz (ab) +afar (aa) +afrikaans (af)
akan (ak) +albanian (sq) +amharic (am-ET)
anglosaxon (ang) +apache (apa) +arabic (ar)
aragonese (an-ES) +armenian (hy) +assamese (as)
asturian (ast) +avaric (av) +avestan (ae)
aymara (ay) +azerbaijani (az) +bahasai (id-IN)
bahasam (ms-MY) +bambara (bm-ML) +bashkir (ba)
basque (eu) +belarusian (be) +bengali (bn)
berber (ber) +bihari (bh) +bislama (bi-VU)
bokmal (nb-NO) +bosnian (bs) +breton (br-FR)
bulgarian (bg) +burmese (my) +catalan (ca)
chamorro (ch) +chechen (ce) +chichewa (ny)
chinese (zh) +churchslavonic (cu) +chuvash (cv-RU)
coptic (cop) +cornish (kw-GB) +corsican (co)
cree (cr) +croatian (hr) +czech (cs)
danish (da) +divehi (dv-MV) +dutch (nl)
dzongkha (dz-BT) +easternpunjabi (pa-IN) +english (en)
esperanto (eo) +estonian (et) +ewe (ee)
faroese (fo) +farsi (fa) +fijian (fj-FJ)
finnish (fi) +french (fr) +friulan (fur-IT)
fula (ff) +galician (gl) +ganda (lg-UG)
georgian (ka) +german (de) +greek (el)
guarani (gn) +gujarati (gu) +haitian (ht-HT)
hausa (ha) +hebrew (he) +herero (hz)
hindi (hi) +hirimotu (ho-PG) +icelandic (is-IS)
ido (io) +igbo (ig) +interlingua (ia)
interlingue (ie) +inuktitut (iu) +inupiaq (ik)
irish (ga) +italian (it) +japanese (ja)
javanese (jv) +kalaallisut (kl) +kannada (kn-IN)
kanuri (kr) +kashmiri (ks-IN) +kazakh (kk)
khmer (km) +kikuyu (ki) +kinyarwanda (rw)
kirundi (rn) +komi (kv-RU) +kongo (kg)
korean (ko) +kurdish (ku) +kwanyama (kj)
kyrgyz (ky) +lao (lo) +latin (la)
latvian (lv) +limburgish (li) +lingala (ln)
lithuanian (lt) +lsorbian (dsb-DE) +lubakatanga (lu-CD)
luxembourgish (lb) +macedonian (mk) +magyar (hu)
malagasy (mg) +malayalam (ml-IN) +maltese (mt)
manx (gv-IM) +maori (mi-NZ) +marathi (mr-IN)
marshallese (mh-MH) +mongolian (mn) +nauruan (na-NR)
navajo (nv-US) +ndonga (ng) +nepali (ne)
nko (nqo) +norsk (no) +northernndebele (nd)
northernsotho (nso) +nuosu (ii-CN) +nynorsk (nn-NO)
occitan (oc) +ojibwe (oj) +oriya (or)
oromo (om) +ossetian (os) +pali (pi)
pashto (ps) +piedmontese (pms-IT) +polish (pl)
portuges (pt) +quechua (qu) +romanian (ro)
romansh (rm-CH) +russian (ru) +samin (se)
samoan (sm) +sango (sg) +sanskrit (sa)
sardinian (sc-IT) +scottish (gd) +serbian (sr)
shona (sn) +sindhi (sd) +sinhalese (si-LK)
slovak (sk) +slovene (sl) +somali (so)
southernndebele (nr-ZA) +southernsotho (st) +spanish (es)
sudanese (su) +swahili (sw) +swati (ss)
swedish (sv) +syriac (syr) +tagalog (tl-PH)
tahitian (ty-PF) +tai (tai) +tajik (tg)
tamil (ta) +tatar (tt) +telugu (te-IN)
thai (th-TH) +tibetan (bo) +tigrinya (ti)
tonga (to-TO) +tsonga (ts) +tswana (tn)
turkish (tr) +turkmen (tk) +twi (tw-GH)
ukrainian (uk-UA) +undetermined (und) +urdu (ur)
usorbian (hsb-DE) +uyghur (ug-CN) +uzbek (uz)
venda (ve-ZA) +vietnamese (vi) +volapuk (vo)
walloon (wa) +welsh (cy) +westernfrisian (fy-NL)
wolof (wo) +xhosa (xh) +yiddish (yi)
yoruba (yo) +zhuang (za-CN) +zulu (zu)
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3: Predefined Non-ISO Dialects. (Has an associated territory.) The corresponding language tag obtained with \GetTrackedLanguageTag{dialect} is shown in parentheses. If the dialect has a corresponding mapping for the closest matching non-root language \captionsdialect or \datedialect, this is also included after the tag following a slash.
acadian (fr) +american (en-US) +argentinespanish (es-AR)
australian (en-AU) +austrian (de-AT) +bahasa (id-IN)
belgiangerman (de-BE) +belgique (fr-BE) +bolivianspanish (es-BO)
brazil (pt-BR) +brazilian (pt-BR) +british (en-GB)
canadian (en-CA) +canadien (fr-CA) +chilianspanish (es-CL)
columbianspanish (es-CO) +costaricanspanish (es-CR) +croatia (hr-HR)
cubanspanish (es-CU) +cymraeg (cy) +deutsch (de)
dominicanspanish (es-DO) +ecudorianspanish (es-EC) +elsalvadorspanish (es-SV)
flemish (nl-BE) +francais (fr) +france (fr-FR)
frenchb (fr) +friulano (fur-IT) +friulian (fur-IT)
furlan (fur-IT) +gaeilge (ga) +gaelic (gd)
galicien (gl) +GBirish (ga-GB) +GBscottish (gd-GB)
GBwelsh (cy-GB) +germanb (de) +germanDE (de-DE)
guatemalanspanish (es-GT) +guernseyenglish (en-GG / british) +guernseyfrench (fr-GG)
honduranspanish (es-HN) +hungarian (hu-HU) +IEenglish (en-IE / british)
IEirish (ga-IE) +indon (id-IN) +indonesian (id-IN)
isleofmanenglish (en-IM / british) +istriacountycroatian (hr-HR) +istriacountyitalian (it-HR)
italy (it-IT) +jerseyenglish (en-JE / british) +jerseyfrench (fr-JE)
kurmanji (ku) +latein (la) +lowersorbian (dsb-DE)
malay (ms-MY) +maltaenglish (en-MT / british) +maltamaltese (mt-MT)
mexicanspanish (es-MX) +meyalu (ms-MY) +naustrian (de-AT-1996)
nbelgiangerman (de-BE-1996 / ngerman) +netherlands (nl-NL) +newzealand (en-NZ)
ngerman (de-1996) +ngermanb (de-1996 / ngerman) +ngermanDE (de-DE-1996 / ngerman)
nicaraguanspanish (es-NI) +nil (und) +norwegian (no-NO)
nswissgerman (de-CH-1996 / ngerman) +panamaspanish (es-PA) +paraguayspanish (es-PY)
persian (fa) +peruvianspanish (es-PE) +piemonteis (pms-IT)
polutoniko (el) +polutonikogreek (el) +portugal (pt-PT)
portuguese (pt) +puertoricospanish (es-PR) +romanche (rm-CH)
romansch (rm-CH) +rumantsch (rm-CH) +russianb (ru)
sanmarino (it-SM) +serbianc (sr-Cyrl) +serbianl (sr-Latn)
sloveneistriaitalian (it-SI) +sloveneistriaslovenian (sl-SI / slovenian) +slovenia (sl-SI / slovenian)
slovenian (sl) +spainspanish (es-ES) +swissfrench (fr-CH)
swissgerman (de-CH) +swissitalian (it-CH) +swissromansh (rm-CH)
UKenglish (en-GB) +ukraine (uk-UA) +ukraineb (uk-UA)
uppersorbian (hsb-DE) +uruguayspanish (es-UY) +USenglish (en-US)
valencian (ca) +valencien (ca) +vatican (it-VA)
venezuelanspanish (es-VE)
+

+ +

+ +
+

2. Summary of Use

+

+There are three levels of use: +

    +
  1. 1.document level (code used by document authors);

    +

  2. 2.locale-sensitive package level (code for package authors who need to know what languages or locale the document is using, such as glossaries to translate commands like \descriptionname or datetime2 to provide localised formats or time zone information);

    +

  3. 3.language set-up level (code for packages that set up the document languages, such as babel or polyglossia). +
+

+ +

+ +
+

2.1. Document Level

+

+Document level use can be divided into generic TeX use (§2.1.1) and LaTeX-specific use (§2.1.2).

+ +

+ +
+

2.1.1. Generic TeX

+

+This section is for generic TeX use. The tracklang files are loaded with \input. See §2.1.2 for LaTeX use.

+A Unix-like user wants the locale information picked up from the locale environment variable (the tex extension may be omitted):

\input tracklang.tex % v1.3
+\TrackLangFromEnv
+% load packages that use tracklang for localisation
+

+A Windows user wants the locale information picked up from the operating system (again the tex extension may be omitted):

\input texosquery.tex
+\input tracklang.tex % v1.3
+\TrackLangFromEnv
+% load packages that use tracklang for localisation
+
Or (texosquery v1.2)
\input texosquery.tex % v1.2
+\input tracklang.tex % v1.3
+
+\TeXOSQueryLangTag{\langtag}
+\TrackLanguageTag{\langtag}
+% load packages that use tracklang for localisation
+
A Unix-like user who may or may not have texosquery setup to run in the shell escape:
\input texosquery.tex
+\input tracklang.tex % v1.3
+
+\ifx\TeXOSQueryLangTag\undefined
+ \TrackLangFromEnv
+\else
+ \TeXOSQueryLangTag{\langtag}
+ \TrackLanguageTag{\langtag}
+\fi
+% load packages that use tracklang for localisation
+

+A user is writing in Italy in Armenian with a Latin script (Latn) and the arevela variant:

\input tracklang.tex % v1.3
+\TrackLanguageTag{hy-Latn-IT-arevela}
+% load packages that use tracklang for localisation
+

+A user is writing in English in the UK:

\input tracklang.tex
+\TrackPredefinedDialect{british}
+% load packages that use tracklang for localisation
+

+Find out information about the current language (supplied in \languagename):

\SetCurrentTrackedDialect{\languagename}
+Dialect: \CurrentTrackedDialect.
+Language: \CurrentTrackedLanguage.
+ISO Code: \CurrentTrackedIsoCode.
+Region: \CurrentTrackedRegion.
+Modifier: \CurrentTrackedDialectModifier.
+Variant: \CurrentTrackedDialectVariant.
+Script: \CurrentTrackedDialectScript.
+Sub-Lang: \CurrentTrackedDialectSubLang.
+Additional: \CurrentTrackedDialectAdditional.
+Language Tag: \CurrentTrackedLanguageTag.
+
Additional information about the script can be obtained by also loading tracklang-scripts:
\input tracklang-scripts.tex
+
The name, numeric code and direction can now be obtained:
Name: \TrackLangScriptAlphaToName{\CurrentTrackedDialectScript}.
+Numeric: 
+\TrackLangScriptAlphaToNumeric{\CurrentTrackedDialectScript}.
+Direction: 
+\TrackLangScriptAlphaToDir{\CurrentTrackedDialectScript}.
+
Test for a specific script (in this case Latn):
Latin?
+\ifx\CurrentTrackedDialectScript\TrackLangScriptLatn
+ Yes
+\else
+ No
+\fi
+

+ +

+ +
+

2.1.2. LaTeX

+

+This section is for LaTeX use. See §2.1.1 for generic TeX use.

+With newer versions of polyglossia, where \xpg@bcp@loaded is defined, you just need to make sure the languages are set before tracklang is loaded:

\documentclass{article}
+\usepackage{polyglossia}
+\setmainlanguage[variant=uk]{english}
+% load packages that use tracklang for localisation
+
For older versions of polyglossia where the regional information is required, use recognised class options:
\documentclass[en-GB]{article}
+\usepackage{polyglossia}
+\setmainlanguage[variant=uk]{english}
+% load packages that use tracklang for localisation
+

+For babel users where the supplied babel dialect label is sufficient, and is passed either through the document class or package options, there’s no need to do anything special:

\documentclass[british,canadien]{article}
+\usepackage[T1]{fontenc}
+\usepackage{babel}
+% load packages that use tracklang for localisation
+
If the region is important but there’s no babel dialect that represents it, there are several options. The first method is to use the class options recognised by tracklang and the root language labels when loading babel:
\documentclass[en-IE,ga-IE]{article}
+\usepackage[english,irish]{babel}
+% load packages that use tracklang for localisation
+

+Another method with babel is to use \TrackLanguageTag and map the new dialect label to the nearest matching \captionsdialect:

\documentclass{article}
+
+\usepackage{tracklang}% v1.3
+\TrackLanguageTag{en-MT}
+\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish}
+
+\usepackage[UKenglish]{babel}
+% load packages that use tracklang for localisation
+
This ensures that the \captionsUKenglish hook is detected by the localisation packages. This mapping isn’t needed for polyglossia as the caption hooks use the root language label. This mapping also isn’t needed if british is used instead of UKenglish since the en-MT (maltaenglish) predefined dialect automatically sets up a mapping to british. (The default mappings are shown in Table 1.3.)

+There’s no support for \babelprovide. If you are using \babelprovide, you will need to use the class option or \TrackLanguageTag as above.

+ +

+ +
+

2.2. Locale-Sensitive Packages

+

+Let’s suppose you are developing a package called mypackage.sty or mypackage.tex and you want to find out what languages the document author has requested. (See also: Using tracklang.tex in Packages with Localisation Features.)

+Generic TeX use (the tex extension may be omitted):

\input tracklang.tex
+
(Most of the commands used in this section require at least tracklang version 1.3 but 1.4 is better if you want to include the script tag in the ldf files.) Note that tracklang.tex has a check to determine if it’s already been loaded, so you don’t need to worry about that.

+LaTeX use:

\RequirePackage{tracklang}[2019/11/30]% at least v1.4
+
This will picked up any language options supplied in the document class options and will also detect if babel or polyglossia have been loaded.

+(LaTeX) If you want to allow the user to set the locale in the package options:

\DeclareOption*{\TrackLanguageTag{\CurrentOption}}
+
This means the user can do, say,
\usepackage[hy-Latn-IT-arevela]{mypackage}
+
With at least version 1.4, it’s better to use \TrackIfKnownLanguage:
\DeclareOption*{% 
+ \TrackIfKnownLanguage{\CurrentOption}% 
+ {% successful
+  \PackageInfo{mypackage}{Tracking language `\CurrentOption'}% 
+ }% 
+ {% failed
+  \PackageError{mypackage}% 
+  {Unknown language specification `\CurrentOption'}% 
+  {You need to supply either a known dialect label 
+   or a valid language tag}% 
+ }% 
+}
+

+

+The rest of the example package in this section uses generic code. If you are using LaTeX, it’s better to replace \def and \ifx with more appropriate LaTeX commands.
+

+If you want to fetch the locale information from the operating system when the user hasn’t requested a language:

\AnyTrackedLanguages
+{}
+{% fetch locale information from the operating system
+  \ifx\TeXOSQueryLangTag\undefined
+    % texosquery v1.2 not available
+    \TrackLangFromEnv
+  \else
+    % texosquery v1.2 available
+    \TeXOSQueryLangTag{\langtag}
+    \TrackLanguageTag{\langtag}
+  \fi
+}
+

+Set up the defaults if necessary:

\def\fooname{Foo}
+\def\barname{Bar}
+

+Now load the resource files:

\AnyTrackedLanguages
+{% 
+  \ForEachTrackedDialect{\thisdialect}{% 
+    \TrackLangRequireDialect{mypackage}{\thisdialect}% 
+  }% 
+}
+{}% no tracked languages, default already set up
+

+Each resource file has the naming scheme prefix-localeid.ldf. In this example, the prefix is mypackage. The localeid part may be the language or dialect label (for example, english or british) or a combination of the ISO language and region codes (for example, en-GB or en or GB). As from version 1.4, localeid may also include the script or variant. (See the definition of \IfTrackedLanguageFileExists below for further details.)

+The simplest scheme is to use the root language label (not the dialect label) for the base language settings and use the ISO codes for regional support.

+For example, the file mypackage-english.ldf:

% identify this file:
+\TrackLangProvidesResource{english}[2016/10/06 v1.0]
+
+\TrackLangAddToCaptions{% 
+  \def\fooname{Foo}% 
+  \def\barname{Bar}% 
+}
+
This sets up appropriate the \captionsdialect hook (if it’s found). For other hooks, such as \datedialect, use \TrackLangAddToHook or \TrackLangRedefHook instead.

+With pre-v1.4 versions of tracklang, the script isn’t included in the file search. If it’s needed then either require at least v1.4 or have a base ldf file that tries to load a version for the particular script (which can be accessed with \CurrentTrackedDialectScript). Here’s an example for a language with different writing systems. The resource file for Serbian mypackage-serbian.ldf:

% identify file:
+\TrackLangProvidesResource{serbian}[2016/10/06 v1.0]
+
+\TrackLangRequestResource{serbian-\CurrentTrackedDialectScript}
+{}% file not found, do something sensible here
+
The file mypackage-serbian-Latn.ldf sets up the Latin script (Latn):
\TrackLangProvidesResource{serbian-Latn}[2016/10/06 v1.0]
+
+\TrackLangAddToCaptions{% 
+  \def\fooname{...}% provide appropriate Latin translations
+  \def\barname{...}% 
+}
+
The file mypackage-serbian-Cyrl.ldf sets up the Cyrillic script (Cyrl):
\TrackLangProvidesResource{serbian-Cyrl}[2016/10/06 v1.0]
+
+\TrackLangAddToCaptions{% 
+  \def\fooname{...}% provide appropriate Cyrillic translations
+  \def\barname{...}% 
+}
+
With v1.4+ you just need mypackage-sr-Latn.ldf and mypackage-sr-Cyrl.ldf for the regionless versions.

+ +

+ +
+

2.3. Language Packages

+

+Let’s suppose now you’re the developer of a package that sets up the language, hyphenation patterns and so on. It would be really helpful to the locale-sensitive packages in §2.2 to know what languages the document author has requested. You can use the tracklang package to identify this information by tracking the requested localisation, so that other packages can have a consistent way of querying it. (See also: Integrating tracklang.tex into Language Packages.)

+Generic use:

\input tracklang
+
Alternative LaTeX use:
\RequirePackage{tracklang}[2019/11/30]% v1.4
+
Unlike \input, \RequirePackage will allow tracklang to pick up the document class options, but using \RequirePackage will also trigger the tests for known language packages. (If you want to find out if tracklang has already been loaded and locales have already been tracked, you can use the same code as in the previous section.)

+When a user requests a particular language through your package, the simplest way of letting tracklang know about it is to use \TrackPredefinedDialect or \TrackLanguageTag. For example, if the user requests british, that’s a predefined dialect so you can just do:

\TrackPredefinedDialect{british}
+
Alternatively
\TrackLanguageTag{en-GB}
+
If your package uses caption hooks, then you can set up a mapping between tracklang’s internal dialect label and your caption label. For example, let’s suppose the closest match to English used in Malta (en-MT) is the dialect UKenglish (for example, the date format is similar between GB and MT):
\TrackLanguageTag{en-MT}
+\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish}
+\def\captionsUKenglish{% 
+  \def\contentsname{Contents}% 
+  % ...
+}
+
(The predefined maltaenglish option provided by tracklang automatically sets the mapping to british, but the above method will change that mapping to UKenglish.)

+This now means that \TrackLangAddToHook and \TrackLangRedefHook commands can find your language hooks. You don’t need the map if your dialect label is the same as tracklang’s root language label for that locale. For example:

\TrackLanguageTag{en-MT}
+\def\captionsenglish{% 
+  \def\contentsname{Contents}% 
+  % ...
+}
+

+When the user switches language through commands like \selectlanguage it would be useful to also use \SetCurrentTrackedDialect{dialect} to make it easier for the document author or locale-sensitive packages to pick up the current locale. The dialect argument may be tracklang’s internal dialect label or the dialect label you assigned with \SetTrackedDialectLabelMap. It may also be the root language label, in which case tracklang will search for the last dialect to be tracked with that language. For example:

\def\selectlanguage#1{% 
+  \SetCurrentTrackedDialect{#1}% 
+  % set up hyphenation patterns etc
+}
+
See the example in §2.1 or the example in Integrating tracklang.tex into Language Packages.

+ +

+ +
+

3. Generic Use

+

+For plain TeX you can input tracklang.tex:

\input tracklang
+
or for TeX formats that have an argument form for \input:
\input{tracklang}
+
As from version 1.3, you don’t need to change the category code of @ before loading tracklang.tex as it will automatically be changed to 11 and switched back at the end (if required).

+The LaTeX package tracklang.sty inputs the generic TeX code in tracklang.tex, but before it does so it defines

+\@tracklang@declareoption{dialect}
+ to
\DeclareOption{dialect}{\TrackPredefinedDialect{dialect}}
+
If \@tracklang@declareoption isn’t defined when tracklang.tex is input, it will be defined to ignore its argument.

+This means that all the predefined languages and dialects (Tables 1.1, 1.2 & 1.3) automatically become package options, so the tracklang.sty package can pick up document class options and add them to tracklang’s internal list of tracked document languages.

+If you’re not using LaTeX, this option isn’t available although you can redefine \@tracklang@declareoption to use something analogous to \DeclareOption, if appropriate. Otherwise, the document languages need to be explicitly identified (using any of the following commands) so that tracklang knows about them.

+

+\TrackPredefinedDialect{dialect label}
+ This will add the predefined dialect and its associated ISO codes to the list of tracked document languages. The dialect label may be any of those listed in Tables 1.1, 1.2 & 1.3.

+For example:

\input tracklang
+\TrackPredefinedDialect{british}
+
is the Plain TeX alternative to:
\documentclass[british]{article}
+\usepackage{tracklang}
+

+Note that it’s impractical to define every possible language and region combination as it would significantly slow the time taken to load tracklang so, after version 1.3, I don’t intend adding any new predefined dialects. As from version 1.3, if you want to track a dialect that’s not predefined by tracklang, then you can use:

+\TrackLocale{locale}
+ If locale is a recognised dialect, this is equivalent to using \TrackPredefinedDialect, otherwise locale needs to be in one the following formats: +
    +
  • ISO lang
  • ISO lang@modifier
  • ISO lang-ISO country
  • ISO lang-ISO country@modifier +
+ where ISO lang is the ISO 639-1 or 639-2 code identifying the language (lower case), ISO country is the 3166-1 ISO code identifying the territory (upper case) and modifier is the modifier or variant. The hyphen (-) may be replaced by an underscore character (_). Code-set information in the form .codeset may optionally appear before the modifier. For example, de-DE.utf8@new (modifier is new) or en-GB.utf8 (modifier is missing). The code-set will be ignored if present, but it won’t interfere with the parsing.

+For example:

\TrackLocale{de-NA@new}
+
indicates German in Namibia using the new spelling.

+

+If a language has different ISO 639-2 (T) and 639-2 (B) codes, then the “T” form should be used. (So for the above example, deu may be used instead of de, but ger won’t be recognised.)
+

+Alternatively, you can use

+\TrackLanguageTag{tag}
+ where tag is a regular, well-formed language tag or a recognised dialect label. (Irregular grandfather tags aren’t recognised.) This command will fully expand tag. A warning is issued if the tag is empty.

+If you want to first check that tag includes a valid language code, then you can instead use:

+\TrackIfKnownLanguage{tag}{success code}{fail code}
+ This will only track tag (and then do success code) if tag starts with a valid language code (or is a predefined dialect) otherwise it will do fail code. Both \TrackLanguageTag and \TrackIfKnownLanguage will check if tag is a predefined option. (This saves parsing the tag if it’s recognised.)

+For example:

\TrackLanguageTag{hy-Latn-IT-arevela}
+Latn-ME: \TrackIfKnownLanguage{Latn-ME}{success}{fail}.
+brazilian: \TrackIfKnownLanguage{brazilian}{success}{fail}.
+
This will track hy-Latn-IT-arevela and brazilian (pt-BR) but not Latn-ME (because it doesn’t contain a valid language code) even though it’s a valid script and country code. The above is just for illustrative purposes. Typically the language tracking isn’t performed within the document text.

+The datetime2 package assumes that any unknown package option is a language identifier. It could simply do:

\TrackLanguageTag{\CurrentOption}
+
but users can make mistakes sometimes and this won’t provide any helpful information if they, for example, misspelt a package option or forgot the key=” part of a key=value setting. Instead (as from v1.5.5) datetime2 now does:
\TrackIfKnownLanguage{\CurrentOption}
+{...}% known language
+{\PackageError{...}{...}{...}}
+
This will now give the user some guidance.

+If tag contains a sub-language tag, this will be set as the 639-3 code for the dialect label. Note that this is different to the root language codes which are set using the language label. For example:

\TrackLanguageTag{zh-cmn-Hans-CN}
+
creates a new dialect with the label zhcmnHansCN. The root language chinese has the 639-1 code zh and the dialect zhcmnHansCN has the ISO 639-3 code cmn.
ISO 639-1: \TrackedIsoCodeFromLanguage{639-1}{chinese}.
+ISO 639-3: \TrackedIsoCodeFromLanguage{639-3}{zhcmnHansCN}.
+

+Version 1.2 of texosquery provides the command \TeXOSQueryLangTag, which may be used to fetch the operating system’s regional information as a language tag. These commands can be used as follows:

\input tracklang % v1.3
+\input texosquery % v1.2
+
+\TeXOSQueryLangTag{\langtag}
+\TrackLanguageTag{\langtag}
+
(If the shell escape is disabled, \langtag will be empty, which will trigger a warning but no errors.)

+Some of the predefined root language options listed in Table 1.2 have an associated region (denoted by ). If \TrackLocale is used with just the language ISO code, no region is tracked for that language. For example

\TrackLocale{manx}
+
will track the IM (Isle of Man) ISO 3166-1 code but
\TrackLocale{gv}
+
won’t track the region. Similarly for \TrackLanguageTag.

+(New to version 1.3.) There’s a similar command to \TrackLocale that doesn’t take an argument:

+\TrackLangFromEnv
+ If the shell escape has been enabled or \directlua is available, this will try to get the language information from the system environment variables LC_ALL or LANG and, if successful, track that.

+Since tracklang is neither able to look up the POSIX locale tables nor interpret file locales, if the result is C or POSIX or starts with a forward slash / then the locale value is treated as empty.

+

+Not all operating systems use environment variables for the system locale information. For example, Windows stores the locale information in the registry. In which case, consider using texosquery.
+

+If the operating system locale can’t be obtained from environment variables, then tracklang will use \TeXOSQueryLocale as a fallback if texosquery has been loaded. Since texosquery requires both the shell escape and the Java runtime environment, tracklang doesn’t automatically load it.

+Plain TeX example:

\input texosquery
+\input tracklang
+\TrackLangFromEnv
+
Document build:
etex --shell-escape filename
+

+LaTeX example:

\usepackage{texosquery}
+\usepackage{tracklang}
+\TrackLangFromEnv
+
Document build:
pdflatex --shell-escape filename
+

+If the locale can’t be determined, there will be warning messages. These can be suppressed using

+\TrackLangShowWarningsfalse
+ or switched back on again using
+\TrackLangShowWarningstrue
+

+For example, I have the environment variable LANG set to en_GB.utf8 on my Linux system so instead of

\TrackPredefinedDialect{british}
+
I can use
\TrackLangFromEnv
+

+With LaTeX documents I can do

\documentclass{article}
+\usepackage{tracklang}
+\TrackLangFromEnv
+
However, this only helps subsequently loaded packages that use tracklang to determine the required regional settings. For example:
\documentclass{article}
+\usepackage{tracklang}
+\TrackLangFromEnv
+\usepackage[useregional]{datetime2}
+
In my case, with the LANG environment variable set to en_GB.utf8 and the shell escape enabled, this automatically switches on the en-GB date style. Naturally this doesn’t help locale-sensitive packages that don’t use tracklang.

+The \TrackLangFromEnv command also incidentally sets \TrackLangEnv to the value of the environment variable or empty if the query was unsuccessful (for example, the shell escape is unavailable).

+If the command:

+\TrackLangEnv

+

user defined
+
+ is already defined before \TrackLangFromEnv is used, then the environment variable won’t be queried and the value of \TrackLangEnv will be parsed instead.

+

+The parser which splits the locale string into its component parts first tries splitting on the underscore _ with its usual category code 8, then tries splitting on a hyphen - with category code 12, and then tries splitting on the underscore _ with category code 12.
+

+For example:

\def\TrackLangEnv{en-GB}
+\TrackLangFromEnv
+
This doesn’t perform a shell escape since \TrackLangEnv is already defined. In this case, you may just as well use:
\TrackLocale{en-GB}
+
(unless you happen to additionally require the component commands that are set by \TrackLangFromEnv, see below.)

+If the shell escape is unavailable (for example, your TeX installation prohibits it), you can set this value when you invoke TeX. For example, if the document file is called myDoc.tex (and it’s in Plain TeX):

tex "\\def\\TrackLangEnv{$LANG}\\input myDoc"
+

+The \TrackLangFromEnv command also happens to store the component parts of the environment variable value in the following commands. (These aren’t provided by \TrackLocale.) If the information is unavailable, the relevant commands will be set to empty.

+The language code is stored in:

+\TrackLangEnvLang
+

+The territory (if present) is stored in:

+\TrackLangEnvTerritory
+

+The code-set (if present) is stored in:

+\TrackLangEnvCodeSet
+

+The modifier (if present) is stored in:

+\TrackLangEnvModifier
+

+If you want to query the language environment, but don’t want to track the result, you can just use:

+\TrackLangQueryEnv
+ This only tries to fetch the value of the language environment variable (and use texosquery as a fallback, if it has been loaded). It doesn’t try to parse the result. The result is stored in \TrackLangEnv (empty if unsuccessful). Unlike \TrackLangFromEnv, this doesn’t check if \TrackLangEnv already exists. A warning will occur if the shell escape is unavailable. For systems that store the locale information in environment variables, this is more efficient than using texosquery’s \TeXOSQueryLocale command (which is what’s used as the fallback).

+The above queries LC_ALL and, if that is unsuccessful, then queries LANG (before optionally falling back on texosquery). If you want another environment variable tried after LC_ALL and before LANG, you can instead use:

+\TrackLangQueryOtherEnv{env-name}
+ For example, to also query LC_MONETARY:
\TrackLangQueryOtherEnv{LC_MONETARY}
+

+Since this sets \TrackLangEnv, you can use it before \TrackLangFromEnv. For example:

\TrackLangQueryOtherEnv{LC_MONETARY}
+\TrackLangFromEnv
+
Remember that if you only want to do the shell escape if \TrackLangEnv hasn’t already been defined, you can test for this first:
\ifx\TrackLangEnv\undefined
+  \TrackLangQueryOtherEnv{LC_MONETARY}
+\fi
+\TrackLangFromEnv
+

+It’s also possible to just parse the value of \TrackLangEnv without tracking the result using:

+\TrackLangParseFromEnv
+ This is like \TrackLangFromEnv but assumes that \TrackLangEnv has already been set and doesn’t track the result. The component parts are stored as for \TrackLangFromEnv.

+Example (Plain TeX):

\input tracklang
+
+\def\TrackLangEnv{fr-BE.utf8@euro}
+
+\TrackLangParseFromEnv
+
+Language: \TrackLangEnvLang.
+Territory: \TrackLangEnvTerritory.
+Codeset: \TrackLangEnvCodeSet.
+Modifier: \TrackLangEnvModifier.
+Any tracked languages? \AnyTrackedLanguages{Yes}{No}.
+
This produces:
+Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. Any tracked languages? No.
+

+Compare this with:

\input tracklang
+
+\def\TrackLangEnv{fr-BE.utf8@euro}
+
+\TrackLangFromEnv
+
+Language: \TrackLangEnvLang.
+Territory: \TrackLangEnvTerritory.
+Codeset: \TrackLangEnvCodeSet.
+Modifier: \TrackLangEnvModifier.
+Any tracked languages? \AnyTrackedLanguages{Yes}{No}.
+Tracked dialect(s):% 
+\ForEachTrackedDialect{\thisdialect}{\space\thisdialect}.
+
This produces:

+

+Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. Any tracked languages? Yes. Tracked dialect(s): belgique.
+

+If \TrackLangFromEnv doesn’t recognise the given language and territory combination, it will define a new dialect and add that.

+For example, tracklang doesn’t recognise en-BE, so the sample document below defines a new dialect labelled enBEeuro:

\input tracklang
+
+\def\TrackLangEnv{en-BE.utf8@euro}
+
+\TrackLangFromEnv
+
+Language: \TrackLangEnvLang.
+Territory: \TrackLangEnvTerritory.
+Codeset: \TrackLangEnvCodeSet.
+Modifier: \TrackLangEnvModifier.
+Any tracked languages? \AnyTrackedLanguages{Yes}{No}.
+Tracked dialect(s):% 
+\ForEachTrackedDialect{\thisdialect}{\space\thisdialect}.
+
This now produces:
+Language: en. Territory: BE. Codeset: utf8. Modifier: euro. Any tracked languages? Yes. Tracked dialect(s): enBEeuro.
+

+ +

+ +
+

4. Supplementary Packages

+

+In addition to the main tracklang.tex file and tracklang.sty LaTeX wrapper, the tracklang package also provides supplementary files for region and script mappings.

+

tracklang-region-codes.tex
+ This file is only loaded if a mapping is required between numeric and alphabetic region codes. If \TrackLanguageTag encounters a numeric region code, it will automatically input tracklang-region-codes.tex, if it hasn’t already been input. This file provides the following commands.

+

+\TrackLangAlphaIIToNumericRegion{alpha-2 code}
+ Expands to the numeric code corresponding to the given alpha-2 code or empty if no mapping has been supplied.

+

+\TrackLangNumericToAlphaIIRegion{numeric code}
+ Expands to the alpha-2 code corresponding to the given numeric code or empty if no mapping has been supplied.

+

+\TrackLangIfKnownAlphaIIRegion{alpha-2 code}{true}{false}
+ Expands to true if there’s an alpha-2 to numeric region code mapping, otherwise expands to false.

+

+\TrackLangIfKnownNumericRegion{numeric code}{true}{false}
+ Expands to true if there’s a numeric to alpha-2 region code mapping, otherwise expands to false.

+

+\TrackLangAlphaIIIToNumericRegion{alpha-3 code}
+ Expands to the numeric code corresponding to the given alpha-3 code or empty if no mapping has been supplied.

+

+\TrackLangNumericToAlphaIIIRegion{numeric code}
+ Expands to the alpha-3 code corresponding to the given numeric code or empty if no mapping has been supplied.

+

+\TrackLangIfKnownAlphaIIIRegion{alpha-3 code}{true}{false}
+ Expands to true if there’s an alpha-3 to numeric region code mapping, otherwise expands to false.

+Mappings are established with:

+\TrackLangRegionMap{numeric}{alpha-2}{alpha-3}
+ Predefined mappings are listed in Table A.1.

+When tracklang-region-codes.tex is input, it can load additional files that provide supplementary mappings.

+

+\TrackLangAddExtraRegionFile{file}
+ This command adds the supplied file to the list of extra region code files that should be input by tracklang-region-codes.tex, unless tracklang-region-codes.tex has already been input, in which case file will be input straight away.

+

tracklang-scripts.tex
+ The tracklang-scripts package provides information about ISO 15924 scripts. The file isn’t automatically loaded. If you want to use any of the commands provided in it you need to input it.

+Plain TeX:

\input tracklang-scripts
+
There’s a simple wrapper package tracklang-scripts.sty for LaTeX users:
\usepackage{tracklang-scripts}
+

+

+\TrackLangScriptMap{letter code}{numeric code}{script name}{direction}{parent script}
+ Defines a mapping. The first argument is the four letter alpha code, such as Latn or Cyrl. The second argument is the numeric code. The third argument is the script’s name, for example “Imperial Aramaic”. The fourth argument is the direction, which may be one of: LR (left-to-right), RL (right-to-left), TB (top-to-bottom), varies or inherited. The parent argument is for the parent writing system, which may be left blank (currently unsupported).

+This command defines:

+\TrackLangScriptCode
+ which expands to Code for use with \IfTrackedDialectIsScriptCs.

+See Table A.2 for a summary of all the mappings that are provided by the file tracklang-scripts.tex.

+

+\TrackLangScriptAlphaToNumeric{alpha code}
+ Expands to the numeric code corresponding to the given alpha code or empty if no mapping.

+

+\TrackLangScriptIfKnownAlpha{alpha code}{true}{false}
+ Expands to true if there is a known alpha to numeric mapping or false otherwise.

+

+\TrackLangScriptNumericToAlpha{numeric code}
+ Expands to the alpha code corresponding to the given numeric code or empty if no mapping.

+

+\TrackLangScriptIfKnownNumeric{numeric code}{true}{false}
+ Expands to true if there is a known numeric to alpha mapping or false otherwise.

+

+\TrackLangScriptAlphaToName{alpha code}
+ Expands to the name corresponding to the given alpha code or empty if no mapping.

+

+\TrackLangScriptAlphaToDir{alpha code}
+ Expands to the direction corresponding to the given alpha code or empty if no mapping.

+

+\TrackLangScriptSetParent{alpha code}{parent alpha code}
+ Sets the parent for the given alpha code.

+

+\TrackLangScriptGetParent{alpha code}
+ Expands to the parent for the given alpha code or empty if no mapping.

+

+\TrackLangScriptIfHasParent{alpha code}{true}{false}
+ Expands to true if the given alpha code has a parent or to false otherwise. Note that if a parent is explicitly set to empty with \TrackLangScriptSetParent then it will be considered defined, but if the parent argument was empty in \TrackLangScriptMap, then it will be undefined.

+

+\TrackLangAddExtraScriptFile{file}
+ This command adds file to the list of extra script files that should be input by tracklang-scripts.tex, unless tracklang-scripts.tex has already been input, in which case file will be input straight away.

+ +

+ +
+

5. Detecting the User’s Requested Languages

+

+The tracklang package tries to track the loaded languages and the option names used to identify those languages. For want of a better term, the language option names are referred to as dialects even if they’re only a synonym for the language rather than an actual dialect. For example, if the user has requested british, the root language label is english and the dialect is british, whereas if the user requested UKenglish, the root language label is english and the dialect is UKenglish. The exceptions to this are the tracklang package options that have been specified in the form iso lang-iso country (listed in Table 1.2). For example, the package option en-GB behaves as though the user requested the package option british.

+If \TrackLocale or \TrackLangFromEnv are used and the locale isn’t recognised a new dialect is created with the label formed from the ISO codes (and modifier, if present). Similarly for \TrackLanguageTag a new dialect is created with a label that’s essentially the language tag without the hyphen separators. For example,

\TrackLocale{xx-YY}
+
will add a new dialect with the label xxYY,
\TrackLocale{xx-YY@mod}
+
will add a new dialect with the label xxYYmod and
\TrackLanguageTag{xx-Latn-YY}
+
will add a new dialect with the label xxLatnYY.

+

+If \TrackLocale or \TrackLangFromEnv find a modifier, the value will be sanitized to allow it to be used as a label. If the modifier is set explicitly using \SetTrackedDialectModifier, no sanitization is performed.
+

+In addition to the root language label and the dialect identifier, many of the language options also have corresponding ISO codes. In most cases there is an ISO 639-1 or an ISO 639-2 code (or both), and in some cases there is an ISO 3166-1 code identifying the dialect region. Where a language has different ISO 639-2 (T) and 639-2 (B) codes, the “T” version is assumed.

+When the tracklang.sty LaTeX package is loaded, it first attempts to find the language options through the package options supplied to tracklang. This means that any languages that have been supplied in the document class options should get identified (provided that the document class has used the standard option declaration mechanism). If no languages have been supplied in this way, tracklang.sty then attempts to identify language settings in the following order: +

    +
  1. 1.if \bbl@loaded is defined (babel), tracklang will iterate over each label in that command definition;

    +

  2. 2.if \trans@languages is defined (translator), tracklang will iterate over each label in that command definition;

    +

  3. 3.if ngerman has been loaded, the ngerman dialect will be tracked;

    +

  4. 4.if german has been loaded, the german root language will be tracked;

    +

  5. 5.if polyglossia has been loaded:

    + +

      +
    1. (a)if \xpg@bcp@loaded has been defined, tracklang will iterate over the BCP 47 tags in that command definition;

      +

    2. (b)if \xpg@loaded has been defined, tracklang will iterate over each language label in that command definition;

      +

    3. (c)tracklang will iterate over all tracklang options and test if the root language has been loaded. +
    +

    + +

+ Note that this references internal commands provided by other packages. Of these, only the polyglossia commands are documented in the package manual, and so are the only ones that can be relied on.

+Each identified language and dialect is added to the tracked language and tracked dialect lists. Note that the tracked language and tracked dialect are labels rather than proper nouns. If a dialect label is identical to its root language label, the label will appear in both lists.

+You can check whether or not any languages have been detected using:

+\AnyTrackedLanguages{true}{false}
+ This will do true if one or more languages have been tracked otherwise it will do false. (Each detected dialect will automatically have the root language label added to the tracked language list, if it’s not already present.)

+If you want to find out if any of the tracked dialects matches a particular language tag, you can use:

+\GetTrackedDialectFromLanguageTag{tag}{cs}
+ If successful, the supplied control sequence cs is set to the dialect label, otherwise cs is set to empty. The test is for an exact match on the root language, script, sub-language, variant and region. The control sequence cs will be empty if none of the tracked dialects matches all five of those elements. (If the script isn’t given explicitly, the default for that language is assumed.) In the event that cs is empty, you can now (as from v1.3.6) get the closest match with:
+\TrackedDialectClosestSubMatch
+ (which is set by \GetTrackedDialectFromLanguageTag). This will be empty if no tracked dialects match on the root language or if there’s a tracked dialect label that exactly matches the label formed by concatenating the language code, sub-language, script, region, modifier and variant.

+For example (Plain TeX):

\input tracklang
+\TrackLanguageTag{en-826}
+Has en-Latn-GB been tracked?
+\GetTrackedDialectFromLanguageTag{en-Latn-GB}{\thisdialect}% 
+\ifx\thisdialect\empty
+ No!
+\else
+ Yes! Dialect label: \thisdialect.
+\fi
+\bye
+
This matches because the territory code 826 is recognised as equivalent to the code GB, and the default script for english is Latn. In this case, the dialect label is british. Note that this doesn’t require the use of \TrackLanguageTag to track the dialect. It also works if the dialect has been tracked using other commands, such as \TrackLocale.

+Here’s an example that doesn’t have an exact match, but does have a partial match:

\input tracklang
+\TrackLanguageTag{de-CH-1996}
+Has de-DE-1996 been tracked?
+\GetTrackedDialectFromLanguageTag{de-DE-1996}{\thisdialect}% 
+\ifx\thisdialect\empty
+ No!
+  \ifx\TrackedDialectClosestSubMatch\empty
+    No match on root language.
+  \else
+    Closest match: \TrackedDialectClosestSubMatch.
+  \fi
+\else
+ Yes! Dialect label: \thisdialect.
+\fi
+\bye
+
In this case the result is:
+Has de-DE-1996 been tracked? No! Closest match: nswissgerman.
+

+You can iterate through each tracked dialect using:

+\ForEachTrackedDialect{cs}{body}
+ At the start of each iteration, this sets the control sequence cs to the tracked dialect and does body.

+You can iterate through each tracked language using:

+\ForEachTrackedLanguage{cs}{body}
+ At the start of each iteration, this sets the control sequence cs to the tracked language and does body.

+The above for-loops use the same internal mechanism as LaTeX’s \@for loop. Since this isn’t defined by TeX, a similar command (\@tracklang@for) will be defined that works in the same way.

+The provided control sequence cs is updated at the start of each iteration to the current element. The loop is terminated when this control sequence is set to \@nil. This special control sequence should never been used as it’s just a marker and isn’t actually defined. If you get an error message stating that \@nil is undefined, then it’s most likely due to a loop control sequence being used outside the loop. This can occur if the loop contains code that isn’t expanded until later. For example, if the loop code includes \AtBeginDocument, you need to ensure that the loop control sequence is expanded before being added to the hook.

+You can test if a root language has been detected using:

+\IfTrackedLanguage{language-label}{true}{false}
+ where language-label is the language label. If true, this does true otherwise it does false.

+You can test if a particular dialect has been detected using:

+\IfTrackedDialect{dialect-label}{true}{false}
+ where dialect-label is the dialect label. If the root language was explicitly specified, then it will also be detected as a dialect.

+For example:

\documentclass[british,dutch]{article}
+
+\usepackage{tracklang}
+
+\begin{document}
+``english'' \IfTrackedDialect{english}{has}{hasn't} been specified.
+
+``british'' \IfTrackedDialect{british}{has}{hasn't} been specified.
+
+``flemish'' \IfTrackedDialect{flemish}{has}{hasn't} been specified.
+
+``dutch'' \IfTrackedDialect{dutch}{has}{hasn't} been specified.
+
+``english'' or an English variant 
+\IfTrackedLanguage{english}{has}{hasn't} been specified.
+\end{document}
+
This produces:
+“english’’ hasn’t been specified.

+“british’’ has been specified.

+“flemish’’ hasn’t been specified.

+“dutch’’ has been specified.

+“english’’ or an English variant has been specified.

+

+You can find the root language label for a given tracked dialect using:

+\TrackedLanguageFromDialect{dialect}
+ If dialect hasn’t been defined this does nothing otherwise it expands to the root language label.

+You can find the tracked dialects from a given root language using:

+\TrackedDialectsFromLanguage{root language label}
+ This will expand to a comma-separated list of dialect labels if the root language label has been defined, otherwise it does nothing.

+You can test if a language or dialect has a corresponding ISO code using:

+\IfTrackedLanguageHasIsoCode{code type}{label}{true}{false}
+ where code type is the type of ISO code (for example, 639-1 for root languages or 3166-1 for regional dialects), and label is the language or dialect label. Note that the 639-3 may be set for the dialect rather than root language for sub-languages parsed using \TrackLanguageTag.

+Alternatively, you can test if a particular ISO code has been defined using:

+\IfTrackedIsoCode{code type}{code}{true}{false}
+ where code type is again the type of ISO code (for example, 639-1 or 3166-1), and code is the particular code (for example, en for ISO 639-1 or GB for ISO 3166-1).

+You can fetch the language (or dialect) label associated with a given ISO code using:

+\TrackedLanguageFromIsoCode{code type}{code}
+ This does nothing if the given code for the given ISO code type has not been defined, otherwise it expands a comma-separated list of language or dialect labels.

+You can fetch the ISO code for a given code type using:

+\TrackedIsoCodeFromLanguage{code type}{label}
+ where label is the language or dialect label and code type is the ISO code type (for example, 639-1 or 3166-1). Unlike \TrackedLanguageFromIsoCode, this command only expands to a single label rather than a comma-separated list.

+The above commands do nothing in the event of an unknown code or code type, so if you accidentally get the wrong code type, you won’t get an error. If you’re unsure of the code type, you can use the following commands:

+\TwoLetterIsoCountryCode
+ This expands to 3166-1 and is used for the two-letter country codes.

+

+\TwoLetterIsoLanguageCode
+ This expands to 639-1 and is used for the two-letter root language codes.

+

+\ThreeLetterIsoLanguageCode
+ This expands to 639-2 and is used for the three-letter root language codes.

+

+\ThreeLetterExtIsoLanguageCode
+ This expands to 639-3. This code is only used for a root language if there’s no 639-1 or 639-2 code. It may also be used for a dialect if a sub-language part has been set in the language tag parsed by \TrackLanguageTag.

+The \Get… commands below are designed to be expandable. If the supplied dialect is unrecognised they expand to empty. Remember that the dialect must first be identified as a tracked language for it to be recognised.

+As from v1.3, the language tag for a given dialect can be obtained using:

+\GetTrackedLanguageTag{dialect}
+ where dialect is the label identifying the dialect. Uses the und (undetermined) code for unknown languages.

+As from v1.3, each tracked dialect may also have an associated modifier, which can be fetched using:

+\GetTrackedDialectModifier{dialect}
+ where dialect is the label identifying the dialect. This value is typically obtained by parsing a POSIX locale identifier with \TrackLocale or \TrackLangFromEnv but may be set explicitly. (See §6 for setting this value. Likewise for the following commands.)

+You can test if a dialect has an associated modifier using:

+\IfHasTrackedDialectModifier{dialect}{true}{false}
+ If the dialect has an associated modifier this does true otherwise it does false.

+For example:

\documentclass[british,francais,american,canadian,canadien,dutch]{article}
+
+\usepackage{tracklang}
+
+\begin{document}
+Languages:
+\ForEachTrackedLanguage{\ThisLanguage}{\ThisLanguage\space
+(ISO \TwoLetterIsoLanguageCode: 
+``\TrackedIsoCodeFromLanguage{\TwoLetterIsoLanguageCode}{\ThisLanguage}''). }
+
+Dialects:
+\ForEachTrackedDialect{\ThisDialect}{\ThisDialect\space 
+(\IfTrackedLanguageHasIsoCode{\TwoLetterIsoCountryCode}{\ThisDialect}% 
+ {ISO \TwoLetterIsoCountryCode: 
+  ``\TrackedIsoCodeFromLanguage{\TwoLetterIsoCountryCode}{\ThisDialect}''} {no specific region};
+root: \TrackedLanguageFromDialect{\ThisDialect}). }
+
+Language for ISO \TwoLetterIsoCountryCode\ ``GB'':
+\TrackedLanguageFromIsoCode{\TwoLetterIsoCountryCode}{GB}.
+
+Language for ISO \TwoLetterIsoCountryCode\ ``CA'': 
+\TrackedLanguageFromIsoCode{\TwoLetterIsoCountryCode}{CA}.
+
+Country ISO \TwoLetterIsoCountryCode\ code for ``canadian'':
+\TrackedIsoCodeFromLanguage{\TwoLetterIsoCountryCode}{canadian}.
+\end{document}
+
This produces:
+Languages: english (ISO 639-1: “en’’). french (ISO 639-1: “fr’’). dutch (ISO 639-1: “nl’’).

+Dialects: american (ISO 3166-1: “US’’; root: english). british (ISO 3166-1: “GB’’; root: english). canadian (ISO 3166-1: “CA’’; root: english). canadien (ISO 3166-1: “CA’’; root: french). dutch (no specific region; root: dutch). francais (no specific region; root: french).

+Language for ISO 3166-1 “GB’’: british.

+Language for ISO 3166-1 “CA’’: canadian,canadien.

+Country ISO 3166-1 code for “canadian’’: CA.

+

+As from v1.3, each tracked dialect may also have an associated variant, which can be fetched using:

+\GetTrackedDialectVariant{dialect}
+ where dialect is the label identifying the dialect. This value is typically obtained by parsing a language tag with \TrackLanguageTag but may be set explicitly.

+You can test if a dialect has an associated variant using:

+\IfHasTrackedDialectVariant{dialect}{true}{false}
+

+As from v1.3, each tracked dialect may also have an associated script, which can be fetched using:

+\GetTrackedDialectScript{dialect}
+ where dialect is the label identifying the dialect.

+You can test if a dialect has an associated script using:

+\IfHasTrackedDialectScript{dialect}{true}{false}
+ If the dialect has an associated script this does true otherwise it does false. This information is provided for language packages that need to know what script is required, but there’s no guarantee that the script will actually be set in the document. Similarly for all the other attributes described here.

+Note that the script should be a recognised four-letter ISO 15924 code, such as Latn or Cyrl. If a dialect doesn’t have an associated script then the default for the root language should be assumed. For example, Latn for English dialects or Cyrl for Russian dialects. The default script for known languages can be obtained using:

+\TrackLangGetDefaultScript{language}
+ Most root languages have a default script, but there are a few without one as it may depend on region, politics or ideology.

+There’s a convenient expandable command for testing the script:

+\IfTrackedDialectIsScriptCs{dialect}{cs}{true}{false}
+ This tests if the given tracked dialect has an associated script and compares the value with the replacement text of cs. If the dialect hasn’t been explicitly assigned a script, then test is performed against the default script for the root language.

+The supplementary package tracklang-scripts provides some additional commands relating to writing systems, including commands in the form \TrackLangScriptCode where Code is the ISO 15924 four-letter code. If the dialect doesn’t have an associated script, false is done. This package isn’t loaded automatically, so you’ll need to explicitly load it. The generic code is in tracklang-scripts.tex:

\input tracklang-scripts
+
There’s a convenient LaTeX wrapper tracklang-scripts.sty:
\usepackage{tracklang-scripts}
+
See §4 for further details of that package.

+For example, the following defines a command to check if the given dialect should use a Latin script:

\input tracklang-scripts
+\def\islatin#1#2#3{% 
+  \IfTrackedDialectIsScriptCs{#1}{\TrackLangScriptLatn}{#2}{#3}% 
+}
+

+

+Note that the script value doesn’t mean that the document is actually using that script. It means that this is the user’s desired script, but whether that script is actually set relies on the appropriate settings in the relevant language package (such as polyglossia’s script key).
+

+As from v1.3, each tracked dialect may also have a sub-language identifier (for example, arevela), which can be fetched using:

+\GetTrackedDialectSubLang{dialect}
+ where dialect is the label identifying the dialect.

+You can test if a dialect has an associated sub-tag using:

+\IfHasTrackedDialectSubLang{dialect}{true}{false}
+ If the dialect has an associated sub-tag this does true otherwise it does false.

+As from v1.3, each tracked dialect may also have additional information, which can be fetched using:

+\GetTrackedDialectAdditional{dialect}
+ where dialect is the label identifying the dialect.

+You can test if a dialect has additional information using:

+\IfHasTrackedDialectAdditional{dialect}{true}{false}
+ If the dialect has additional information this does true otherwise it does false.

+Most packages that implement multilingual support have a set of language definition files for each supported language or dialect. It may be that only the root language is needed, if there are no variations between that language’s dialect (for the purposes of that package), or it may be that separate definition files are required for each dialect. However it can be awkward trying to map the requested dialect or language label to the file name. Should, say, the file containing the French code be called prefix-french-suffix or prefix-frenchb-suffix or prefix-francais-suffix? Should, say, the file containing the British English code be called prefix-british-suffix or prefix-UKenglish-suffix? If you want to modularise the language support for your package so that each language module has a different maintainer will the maintainers know what tag to use for their language?

+To help with this, tracklang provides:

+\IfTrackedLanguageFileExists{dialect}{prefix}{suffix}{true code}{false code}
+ This attempts to find the file called prefixlocaleidsuffix where localeid is determined from dialect (see below). If the file is found then
+\CurrentTrackedTag
+ is set to localeid and true code is done, otherwise false code is done. If this command is empty, then the dialect hasn’t been detected. If the dialect has been detected, but no file can be found, then \CurrentTrackedTag is set to the final attempt at determining localeid.

+There’s a convenient shortcut command new to version 1.3:

+\TrackLangRequireDialect[load code]{pkgname}{dialect}
+ which uses \IfTrackedLanguageFileExists to input the resource file if found. The prefix is given by pkgname- and the suffix is .ldf. A warning is issued if no resource file is found. Note that while it makes sense for pkgname to be the same as the base name of the package that uses these resource files, they don’t have to be the same. This command additionally defines:
+\TrackLangRequireDialectPrefix
+ to pkgname, which allows the prefix to be picked up by resource file commands, such as \TrackLangProvidesResource and \TrackLangRequireResource. (See below.)

+The optional argument load code is the code that actually inputs the required file. This defaults to

\TrackLangRequireResource{\CurrentTrackedTag}
+

+The \IfTrackedLanguageFileExists command sets up the current tracked dialect with:

\SetCurrentTrackedDialect{dialect}
+
which enables the following commands that may be used within true code or false code:
+\CurrentTrackedDialect
+ Expands to the dialect label.

+

+\CurrentTrackedLanguage
+ If the dialect hasn’t been detected, this command will be empty, otherwise it will expand to the root language label (which may be the same as the dialect label).

+

+\CurrentTrackedRegion
+ If the dialect hasn’t been detected, this command will be empty. If the dialect has been assigned an ISO 3166-1 code, \CurrentTrackedRegion will expand to that code, otherwise it will be empty.

+

+\CurrentTrackedIsoCode
+ If the dialect hasn’t been detected, this command will be empty. Otherwise it may be empty or it may expand to the ISO 639-1 or ISO 639-2 or ISO 639-3 code.

+

+\CurrentTrackedDialectModifier
+ The dialect’s modifier or empty if not set. (This is set but not used in the set of possible localeid values.)

+

+\CurrentTrackedDialectVariant
+ The dialect’s variant or empty if not set.

+

+\CurrentTrackedDialectSubLang
+ The dialect’s sub-language code or empty if not set.

+

+\CurrentTrackedDialectAdditional
+ The dialect’s additional information or empty if not set.

+

+\CurrentTrackedLanguageTag
+ The dialect’s language tag. Take care not to confuse this with \CurrentTrackedTag.

+

+\CurrentTrackedDialectScript
+ The dialect’s script. If the dialect doesn’t have the script set, the default script for the language is used instead.

+\IfTrackedLanguageFileExists behaves as follows: +

    +
  • If no dialect with the given label has been detected, the condition evaluates to false and \CurrentTrackedTag is empty.

    +

  • If a dialect with the given label has been detected, then: +
      +
    • For each possible localeid in an ordered set of tags determined by the dialect label (see below), the first file matching prefixlocaleidsuffix that’s found on TeX’s path results in the condition evaluating to true and \CurrentTrackedTag is set to the current localeid in the set. The rest of the set of possible values of localeid is skipped.

      +

    • If no file matching prefixlocaleidsuffix is found on TeX’s path, then the condition evaluates to false and \CurrentTrackedTag is set to the final localeid in the set (the language label). +
    + +
+

+The ordered set of possible values of localeid is determined from the given dialect.

+The ordering has changed in version 1.4, which now also includes the script and variant. This new ordering should typically make the more common combinations closer to the start of the search.
+ The possible values of localeid are listed below in the order of priority used by \IfTrackedLanguageFileExists. Note that the set may contain repetitions (for example, if the dialect label is the same as the root language label). If an item contains an element that hasn’t been set (such as the ISO 639-3 code or a sub-language sublang or variant) then that item is skipped. +
    +
  1. 1.localeid is just the value of \CurrentTrackedLanguageTag.

    +

  2. 2.localeid is just the dialect label.

    +

  3. 3.localeid is ISO 639-1-sublang-script-region.

    +

  4. 4.localeid is ISO 639-1-script-region.

    +

  5. 5.localeid is ISO 639-1-sublang-region (if there’s no script or if the script is the default for the given language). ISO 639-1-region (if there’s no script or if the script is the default for the given language).

    +

  6. 6.localeid is ISO 639-1-sublang-script.

    +

  7. 7.localeid is ISO 639-1-script.

    +

  8. 8.localeid is ISO 639-1-sublang.

    +

  9. 9.localeid is just ISO 639-1.

    +

  10. 10.localeid is ISO 639-2-sublang-script-region.

    +

  11. 11.localeid is ISO 639-2-script-region.

    +

  12. 12.localeid is ISO 639-2-sublang-region (if there’s no script or if the script is the default for the given language). ISO 639-2-region (if there’s no script or if the script is the default for the given language).

    +

  13. 13.localeid is ISO 639-2-sublang-script.

    +

  14. 14.localeid is ISO 639-2-script.

    +

  15. 15.localeid is ISO 639-2-sublang.
  16. 16.localeid is just ISO 639-2.

    +

  17. 17.localeid is ISO 639-3-sublang-script-region.

    +

  18. 18.localeid is ISO 639-3-script-region.

    +

  19. 19.localeid is ISO 639-3-sublang-region (if there’s no script or if the script is the default for the given language). ISO 639-3-region (if there’s no script or if the script is the default for the given language).

    +

  20. 20.localeid is ISO 639-3-sublang-script.

    +

  21. 21.localeid is ISO 639-3-script.

    +

  22. 22.localeid is ISO 639-3-sublang.

    +

  23. 23.localeid is just ISO 639-3.

    +

  24. 24.localeid is just region.

    +

  25. 25.localeid is ISO 639-1-sublang-variant or ISO 639-1-variant if sublang is missing.

    +

  26. 26.localeid is ISO 639-2-sublang-variant or ISO 639-2-variant if sublang is missing.

    +

  27. 27.localeid is ISO 639-3-sublang-variant or ISO 639-3-variant if sublang is missing.

    +

  28. 28.localeid is just the value of \CurrentTrackedLanguage (the root language label). +
+

+For example (pre v1.3):

\AnyTrackedLanguages
+{% 
+  \ForEachTrackedDialect{\ThisDialect}% 
+  {% try to load the language file for this dialect
+    \IfTrackedLanguageFileExists{\ThisDialect}% 
+    {mypackage-}% file prefix
+    {.ldf}% file suffix
+    {\input mypackage-\CurrentTrackedTag.ldf}% file found
+    {% file not found
+      \PackageWarning{mypackage}{No support for language
+       `\ThisDialect'}% 
+    }% 
+  }% 
+}
+{% no languages detected so use defaults
+}
+
With version 1.3 onwards, this can be written more concisely as:
\AnyTrackedLanguages
+{% 
+  \ForEachTrackedDialect{\ThisDialect}% 
+  {% try to load the language file for this dialect
+    \TrackLangRequireDialect{mypackage}{\ThisDialect}% 
+  }% 
+}
+{% no languages detected so use defaults
+}
+
which additionally enables the tracklang version 1.3 commands described below, such as \TrackLangRequireResource.

+If, for example, \ThisDialect is british, then the file search will be in the order: +

    +
  1. 1.mypackage-en-GB.ldf (language tag)
  2. 2.mypackage-british.ldf (dialect label)

    +

  3. 3.mypackage-en-Latn-GB.ldf (639-1 language code, script, region)
  4. 4.mypackage-en-GB.ldf (639-1 language code, region)
  5. 5.mypackage-en-Latn.ldf (639-1 language code, script)
  6. 6.mypackage-en.ldf (639-1 language code)

    +

  7. 7.mypackage-eng-Latn-GB.ldf (639-2 language code, script, region)
  8. 8.mypackage-eng-GB.ldf (639-2 language code, region)
  9. 9.mypackage-eng-Latn.ldf (639-2 language code, script)
  10. 10.mypackage-eng.ldf (639-2 language code)

    +

  11. 11.mypackage-GB.ldf (region)
  12. 12.mypackage-english.ldf (language label) +
+

+If, for example, \ThisDialect is naustrian, then the file search will be in the order: +

    +
  1. 1.mypackage-de-AT-1996.ldf (language tag)
  2. 2.mypackage-naustrian.ldf (dialect label)

    +

  3. 3.mypackage-de-Latn-AT.ldf (639-1 language code, script, region)
  4. 4.mypackage-de-AT.ldf (639-1 language code, region)
  5. 5.mypackage-de-Latn.ldf (639-1 language code, script)
  6. 6.mypackage-de.ldf (639-1 language code)

    +

  7. 7.mypackage-deu-Latn-AT.ldf (639-2 language code, script, region)
  8. 8.mypackage-deu-AT.ldf (639-2 language code, region)
  9. 9.mypackage-deu-Latn.ldf (639-2 language code, script)
  10. 10.mypackage-deu.ldf (639-2 language code)

    +

  11. 11.mypackage-AT.ldf (region)

    +

  12. 12.mypackage-de-1996.ldf (639-1 language code, variant)
  13. 13.mypackage-deu-1996.ldf (639-2 language code, variant)

    +

  14. 14.mypackage-german.ldf (language label) +
+

+If, for example, \ThisDialect is francais, then the file search will be in the order: +

    +
  1. 1.mypackage-fr.ldf (language tag)
  2. 2.mypackage-francais.ldf (dialect label)
  3. 3.mypackage-fr-Latn.ldf (639-1 language code, script)
  4. 4.mypackage-fr.ldf (639-1 language code)
  5. 5.mypackage-fra-Latn.ldf (639-2 language code, script)
  6. 6.mypackage-fra.ldf (639-2 language code)
  7. 7.mypackage-french.ldf (language) +
+ This is because the predefined francais option has no region assigned to it. Be careful if the dialect label is the actual root language. For example, if \ThisDialect is french, then the file search will be in the order: +
    +
  1. 1.mypackage-fr.ldf (language tag)
  2. 2.mypackage-french.ldf (dialect label)
  3. 3.mypackage-fr-Latn.ldf (639-1 language code, script)
  4. 4.mypackage-fr.ldf (639-1 language code)
  5. 5.mypackage-fra-Latn.ldf (639-2 language code, script)
  6. 6.mypackage-fra.ldf (639-2 language code)
  7. 7.mypackage-french.ldf (language) +
+ Note that the last try will always fail in this case since if the file exists, it will be found on the second try.

+If the dialect label is identical to the root language label then it means that all associated information is the default for that language. For example, in the above case of french, the script is Latn and the region is unspecified. The root language label can therefore be used as the fallback in the event of no other match but for the specific case where the dialect is identical to the root language then all unnecessary file name checks can be skipped.

+If you’re only providing support for the root languages (pre v1.3):

\AnyTrackedLanguages
+{% 
+  \ForEachTrackedLanguage{\ThisLanguage}% 
+  {% try to load the language file for this root language
+    \IfTrackedLanguageFileExists{\ThisLanguage}% 
+    {mypackage-}% file prefix
+    {.ldf}% file suffix
+    {\input mypackage-\CurrentTrackedTag.ldf}% file found
+    {% file not found
+      \PackageWarning{mypackage}{No support for language
+       `\ThisLanguage'}% 
+    }% 
+  }% 
+}
+{% no languages detected so use defaults
+}
+
With version 1.3 onwards, this can be written more concisely as:
\AnyTrackedLanguages
+{% 
+  \ForEachTrackedLanguage{\ThisLanguage}% 
+  {% try to load the language file for this root language
+    \TrackLangRequireDialect{mypackage}{\ThisLanguage}% 
+  }% 
+}
+{% no languages detected so use defaults
+}
+
which additionally enables the commands described below. Note that in this case, if more than one dialect for the same language has been tracked, only the hooks for the last dialect for that language will be adjusted, so it’s usually best to iterate over the dialects.

+The following \TrackLang…Resource… commands may only be used in resource files that are loaded using \TrackLangRequireDialect. An error will occur if the file is input through some other method.

+Within the resource file pkgname-localeid.ldf, you can identify the file using (new to version 1.3):

+\TrackLangProvidesResource{tag}{version info}
+ where tag is the locale identifier.

+If \ProvidesFile is defined (through the LaTeX kernel) this is used, otherwise a simplified generic alternative is used that’s suitable for other TeX formats.

+The resource file can load another resource file pkgname-tag.ldf, using (new to version 1.3):

+\TrackLangRequireResource{tag}
+ For example, the dialect file foo-en-GB.ldf might need to load the root language resource file foo-english.ldf:
% (In file foo-en-GB.ldf)
+% Declare this regional file:
+\TrackLangProvidesResource{en-GB}
+% load root language file foo-english.ldf:
+\TrackLangRequireResource{english}
+
If foo-english.ldf is also identified with \TrackLangProvidesResource, this will ensure that it’s only loaded once.

+If you require the resource file and want to perform code1 if it’s loaded at this point or code2 if it’s already been loaded then you can use:

+\TrackLangRequireResourceOrDo{tag}{code1}{code2}
+

+If you want to load a resource file if it exists (without an error if it doesn’t exist), then you can use

+\TrackLangRequestResource{tag}{not found code}
+ If the file doesn’t exist, not found code is done.

+

+Note that these \…Resource… commands are only permitted within the resource files. They are internally enabled through \TrackLangRequireDialect.
+

+The above restriction on the resource files loaded through \TrackLangRequireDialect, and the fact that it internally uses \IfTrackedLanguageFileExists, means that commands like \CurrentTrackedLanguage or \CurrentTrackedDialect may be used in those files. This means that the name of the captions hook can be obtained through them. (Remember that the file foo-en-GB.ldf might have been loaded with, say, the british dialect or with the synonymous UKenglish dialect or with a dialect label that doesn’t have a corresponding caption hook, such as enGBLatn.)

+The polyglossia package has language caption hooks in the form \captionslanguage (where language is the root language label) whereas babel has dialect captions hooks in the form \captionsdialect (where dialect is the dialect label). This leads to a rather cumbersome set of conditionals:

\ifcsundef{captions\CurrentTrackedLanguage}
+{% 
+  \ifcsundef{captions\CurrentTrackedDialect}% 
+  {}% 
+  {% 
+    \csgappto{captions\CurrentTrackedDialect}{% 
+      % code to append to hook
+    }% 
+  }% 
+}% 
+{% 
+  \csgappto{captions\CurrentTrackedLanguage}{% 
+    % code to append to hook
+  }% 
+}
+% do code now to initialise
+
Note that the above has been simplified through the use of etoolbox commands, which isn’t suitable for generic use. It also doesn’t query the mapping from tracklang’s dialect label to the closest matching babel dialect label.

+Instead, tracklang provides a command to perform this set of conditionals using generic code:

+\TrackLangAddToHook{code}{type}
+ where code is the code to append to the type hook. This always performs code after testing for the hook in case the hook is undefined or has already been called (for example, ngerman uses \captionsngerman when the package is loaded, not at the start of the document).

+Note that this command is enabled through \TrackLangRequireDialect so should only be used inside resource files.

+Since captions is a commonly used hook type, there’s a shortcut command provided:

+\TrackLangAddToCaptions{code}
+ This is equivalent to
\TrackLangAddToHook{code}{captions}
+

+There may be some hooks, such as \datedialect, that need redefining rather than appending to, so there’s an analogous command:

+\TrackLangRedefHook{code}{type}
+ which will redefined the hook to do code.

+Note that no expansion is performed on code when appending or redefining a hook.

+ +

+ +
+

5.1. Examples

+

+The examples in this section illustrate the above commands.

+ +

+ +
+

5.1.1. animals.sty

+

+This example is for a trivial package called animals.sty that defines three textual commands: \catname, \dogname and \ladybirdname. The default values are: “cat”, “dog” and “bishy-barney-bee”.1 The supported languages are defined in files animals-localeid.ldf.

+Here’s the code for animals.sty:

% Example package animals.sty
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{animals}
+
+\RequirePackage{tracklang}[2019/11/30]% v1.4
+
+% Any undeclared options are language settings:
+
+\DeclareOption*{% 
+ \TrackIfKnownLanguage{\CurrentOption}% 
+ {% successful
+  \PackageInfo{animals}{Tracking language `\CurrentOption'}% 
+ }% 
+ {% failed
+   \PackageError{animals}% 
+   {Unknown language specification `\CurrentOption'}% 
+   {You need to supply either a known dialect label 
+    or a valid language tag}% 
+ }% 
+}
+
+\ProcessOptions
+
+% Default definitions
+\newcommand\catname{cat}
+\newcommand\dogname{dog}
+\newcommand\ladybirdname{bishy-barney-bee}
+
+\AnyTrackedLanguages
+{% 
+  \ForEachTrackedDialect{\this@dialect}{% 
+    \TrackLangRequireDialect{animals}{\this@dialect}% 
+  }% 
+}
+{% no tracked languages, default already set up
+}
+
+\endinput
+
Here’s a Plain TeX version that picks up the language from the locale environment variable:
\input tracklang
+
+\TrackLangFromEnv
+
+% Default definitions
+\def\catname{cat}
+\def\dogname{dog}
+\def\ladybirdname{bishy-barney-bee}
+
+\AnyTrackedLanguages
+{% 
+  \ForEachTrackedDialect{\thisdialect}{% 
+    \TrackLangRequireDialect{animals}{\thisdialect}% 
+  }% 
+}
+{% no tracked languages, default already set up
+}
+
In the event that a user or supplementary package for some reason wants to load a resource file for a language that hasn’t been tracked, it might be worth providing a command for this purpose:
\newcommand*{\RequireAnimalsDialect}[1]{% 
+  \TrackLangRequireDialect{animals}{#1}% 
+}
+
The loop can then be changed to:
\ForEachTrackedDialect{\this@dialect}{% 
+  \RequireAnimalsDialect\this@dialect
+}% 
+

+The animals-english.ldf file valid for both the Plain TeX and LaTeX formats contains:

\TrackLangProvidesResource{english}
+
+\def\englishanimals{% 
+  \def\catname{cat}% 
+  \def\dogname{dog}% 
+  \def\ladybirdname{bishy-barney-bee}% 
+}
+
+\TrackLangAddToCaptions{\englishanimals}
+
The animals-en-GB.ldf file contains:
\TrackLangProvidesResource{en-GB}
+\TrackLangRequireResource{english}
+
+\def\enGBanimals{% 
+  \englishanimals
+  \def\ladybirdname{ladybird}% 
+}
+\TrackLangAddToCaptions{\enGBanimals}
+
The animals-en-US.ldf file contains:
\TrackLangProvidesResource{en-US}
+\TrackLangRequireResource{english}
+
+\def\enUSanimals{% 
+  \englishanimals
+  \def\ladybirdname{ladybug}% 
+}
+\TrackLangAddToCaptions{\enUSanimals}
+
Here’s a German version in the file animals-german.ldf:
\TrackLangProvidesResource{german}
+
+\def\germananimals{% 
+  \def\catname{Katze}% 
+  \def\dogname{Hund}% 
+  \def\ladybirdname{Marienk\"afer}% 
+}
+
+\TrackLangAddToCaptions{\germananimals}
+

+This means that if babel or polyglossia are loaded, the redefinitions are automatically performed whenever the language is changed, but if there’s no caption mechanism the user can switch the fixed names using the \…animals commands.

+Here’s an example LaTeX document that doesn’t have any caption hooks:

\documentclass[english,german]{article}
+
+\usepackage{animals}
+
+\begin{document}
+\englishanimals
+
+\catname.
+\dogname.
+\ladybirdname.
+
+\germananimals
+
+\catname.
+\dogname.
+\ladybirdname.
+\end{document}
+
Here’s a babel example document:
\documentclass[american,german,british]{article}
+
+\usepackage{babel}
+\usepackage{animals}
+
+\begin{document}
+\selectlanguage{american}
+
+\catname.
+\dogname.
+\ladybirdname.
+
+\selectlanguage{german}
+
+\catname.
+\dogname.
+\ladybirdname.
+
+\selectlanguage{british}
+
+\catname.
+\dogname.
+\ladybirdname.
+\end{document}
+

+There is some redundancy with the above resource files. Consider the babel example above. The american dialect is the first option, so in that case animals-en-US.ldf is loaded followed by animals-english.ldf. This means that the \captionsamerican hook now includes

\englishanimals
+\enUSanimals
+
Since \enUSanimals includes \englishanimals, there is redundant code. However, when the british dialect is processed, this loads the file animals-en-GB.ldf but not the file animals-english.ldf (since it’s already been loaded). This means that \captionsbritish contains \enGBanimals but not \englishanimals.

+If this redundancy is an issue (for example, there are so many redefinitions needed that it significantly slows the document build process), then it can be addressed with the following modifications. The animals-en-GB.ldf file is now:

\TrackLangProvidesResource{en-GB}
+
+\def\enGBanimals{% 
+  \englishanimals
+  \def\ladybirdname{ladybird}% 
+}
+
+\TrackLangRequireResourceOrDo{english}% 
+{
+  \TrackLangAddToCaptions{% 
+    \def\ladybirdname{ladybird}% 
+  }% 
+}
+{
+  \TrackLangAddToCaptions{\enGBanimals}
+}
+
The animals-en-US.ldf file is now:
\TrackLangProvidesResource{en-US}
+
+\providecommand*{\enUSanimals}{% 
+  \englishanimals
+  \renewcommand*{\ladybirdname}{ladybug}% 
+}
+
+\TrackLangRequireResourceOrDo{english}
+{
+  \TrackLangAddToCaptions{% 
+    \renewcommand*{\ladybirdname}{ladybird}% 
+  }% 
+}
+{
+  \TrackLangAddToCaptions{\enUSanimals}
+}
+
This means that the document that has the dialects listed in the order american, british now has
\englishanimals
+\def\ladybirdname{ladybird}
+
in the \captionsbritish hook and just \enUSanimals in the \captionsamerican hook, which has removed most of the redundancy.

+Note that polyglossia has a \captionsenglish hook but not \captionsamerican or \captionsbritish, so this code doesn’t allow for switching between variants of the same language with polyglossia.

+ +

+ +
+

5.1.2. regions.sty

+

+Earlier, I mentioned the search order for \IfTrackedLanguageFileExists where if, for example, the dialect is british, the file search (v1.4+) will be: +

    +
  1. 1.mypackage-en-GB.ldf (language tag)
  2. 2.mypackage-british.ldf (dialect label)

    +

  3. 3.mypackage-en-Latn-GB.ldf (639-1 language code, script, region)
  4. 4.mypackage-en-GB.ldf (639-1 language code, region)
  5. 5.mypackage-en-Latn.ldf (639-1 language code, script)
  6. 6.mypackage-en.ldf (639-1 language code)

    +

  7. 7.mypackage-eng-Latn-GB.ldf (639-2 language code, script, region)
  8. 8.mypackage-eng-GB.ldf (639-2 language code, region)
  9. 9.mypackage-eng-Latn.ldf (639-2 language code, script)
  10. 10.mypackage-eng.ldf (639-2 language code)

    +

  11. 11.mypackage-GB.ldf (region)
  12. 12.mypackage-english.ldf (language label) +
+ You may have wondered why mypackage-GB.ldf is included in the search given that some countries have multiple official languages, which means that the country code on its own may not indicate the language.

+The reason for including just the country code as the localeid in the file search is to allow for region rather than language dependent settings. For example, suppose I want to write a package that needs to know whether to use imperial or metric measurements in the document, but I also want to provide multilingual support. The language alone won’t tell me whether to use imperial or metric (for example, the US uses imperial and the UK uses metric for most product attributes). I could provide ldf files for every language and region combination, but this would result in a lot redundancy.

+\TrackLangRequireDialect has an optional argument for adjusting the way the resource files are loaded. Suppose I have regions-localeid.ldf resource files, then

\TrackLangRequireDialect{regions}{\this@dialect}
+
loads the resource file for the dialect given by \this@dialect using:
\TrackLangRequireResource{\CurrentTrackedTag}
+
I can use the optional argument to also load the resource file for the root language as well:
% custom file loader for regions.sty
+\newcommand*{\RequireRegionsDialect}[1]{% 
+ \TrackLangRequireDialect
+   [\TrackLangRequireResource{\CurrentTrackedTag}% 
+    \TrackLangRequireResource{\CurrentTrackedLanguage}% 
+   ]% 
+   {regions}{#1}% 
+}
+
Now the dialect british can load both regions-GB.ldf and regions-english.ldf.

+The example package (regions.sty) below illustrates this.

% Example package regions.sty
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{regions}
+
+\RequirePackage{tracklang}[2016/10/07]% v1.3+
+
+\DeclareOption*{\TrackLanguageTag{\CurrentOption}}
+\ProcessOptions
+
+\newcommand*{\weightunit}{kg}
+\newcommand*{\lengthunit}{mm}
+\newcommand*{\currencyunit}{EUR}
+
+\newcommand*{\unitname}{units}
+
+\newcommand*{\RequireRegionsDialect}[1]{% 
+ \TrackLangRequireDialect
+  [\TrackLangRequireResource{\CurrentTrackedTag}% 
+   \TrackLangRequireResource{\CurrentTrackedLanguage}% 
+  ]% 
+  {regions}{#1}% 
+}
+
+\AnyTrackedLanguages
+{% 
+ \ForEachTrackedDialect{\this@dialect}{% 
+   \RequireRegionsDialect\this@dialect
+ }% 
+}
+{% no tracked languages, default already set up
+}
+
+\endinput
+
There are separate ldf files for region and language. First are the regions.

+ +

+ Now the language files:

+ +

+

+Here’s an example document that uses this package:

\documentclass[canadien]{article}
+
+\usepackage{regions}
+
+\begin{document}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\end{document}
+

+This works because the localeid search looks for the country code before the root language label. However, this will fail if the dialect label is the same as a root language label that has an associated territory, marked with in Table 1.2, as then it will be picked up before the country code.

+In the above example, regions-CA.ldf is matched rather than regions-french.ldf, so regions-CA.ldf is loaded by

\TrackLangRequireResource{\CurrentTrackedTag}
+
After this, the language file regions-french.ldf is then loaded:
\TrackLangRequireResource{\CurrentTrackedLanguage}
+

+This assumes that there’s a country code ldf file available. This example needs a little modification to use default units in case the region is missing:

% Modified example package regions.sty
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{regions}
+
+% Pass all options to tracklang.sty:
+\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{tracklang}}
+\ProcessOptions
+
+\RequirePackage{tracklang}
+
+\newcommand*{\weightunit}{kg}
+\newcommand*{\lengthunit}{mm}
+\newcommand*{\currencyunit}{EUR}
+
+\newcommand*{\unitname}{units}
+
+\newcommand*{\defaultunits}{% 
+  \renewcommand*{\weightunit}{kg}% 
+  \renewcommand*{\lengthunit}{mm}% 
+  \renewcommand*{\currencyunit}{EUR}% 
+}
+
+\newcommand*{\RequireRegionsDialect}[1]{% 
+  \TrackLangRequireDialect
+   [\TrackLangRequireResource{\CurrentTrackedTag}% 
+     \ifx\CurrentTrackedTag\CurrentTrackedLanguage
+       \TrackLangAddToCaptions{\defaultunits}% 
+     \else
+       \TrackLangRequireResource{\CurrentTrackedLanguage}% 
+     \fi
+   ]% 
+   {regions}{#1}% 
+}
+
+\AnyTrackedLanguages
+{% 
+  \ForEachTrackedDialect{\this@dialect}% 
+    \RequireRegionsDialect\this@dialect
+  % 
+}
+{% no tracked languages, default already set up
+}
+
+\endinput
+
Note that we still have a problem for dialect labels that are identical to root language labels with an associated territory (such as manx). This case can be checked with the following adjustment:
\newcommand*{\RequireRegionsDialect}[1]{% 
+  \TrackLangRequireDialect
+  [\TrackLangRequireResource{\CurrentTrackedTag}% 
+   \ifx\CurrentTrackedTag\CurrentTrackedLanguage
+     \ifx\CurrentTrackedRegion\empty
+       \TrackLangAddToCaptions{\defaultunits}% 
+     \else
+       \TrackLangRequireResource{\CurrentTrackedRegion}% 
+     \fi
+   \else
+     \TrackLangRequireResource{\CurrentTrackedLanguage}% 
+   \fi
+  ]% 
+  {regions}{#1}% 
+}
+
In the case where both the dialect and root language label are manx with the resource files regions-manx.ldf and regions-IM.ldf, then \CurrentTrackedTag will be manx (the dialect label) so regions-manx.ldf will be loaded with:
\TrackLangRequireResource{\CurrentTrackedTag}
+
In this case \CurrentTrackedRegion is IM (that is, it’s not empty) so then regions-IM.ldf will be loaded with:
\TrackLangRequireResource{\CurrentTrackedRegion}
+

+Here’s another document that sets up dialects with tracklang labels that aren’t recognised by babel. This means that there’s no corresponding \captionsdialect hook for either the dialect label or the root language label, so mappings need to be defined from the tracklang dialect label to the matching babel dialect label.

+

\documentclass{article}
+
+\usepackage{tracklang}
+
+\TrackLanguageTag{de-US-1996}
+\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{ngerman}
+
+\TrackLanguageTag{en-MT}
+\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish}
+
+\usepackage[main=ngerman,UKenglish]{babel}
+\usepackage{regions}
+
+\begin{document}
+\selectlanguage{ngerman}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\selectlanguage{UKenglish}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\end{document}
+
This produces:
+Maßeinheiten: lb, in, USD.

+units: kg, mm, EUR.

+ Compare this with:
\documentclass{article}
+
+\usepackage[main=ngerman,UKenglish]{babel}
+\usepackage{regions}
+
+\begin{document}
+\selectlanguage{ngerman}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\selectlanguage{UKenglish}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\end{document}
+
which produces:
+Maßeinheiten: kg, mm, EUR.

+units: kg, mm, GBP.

+

+Note that these mappings aren’t needed if babel is loaded with the root language labels instead. For example:

\documentclass{article}
+
+\usepackage{tracklang}
+
+\TrackLanguageTag{de-US-1996}
+\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{ngerman}
+
+\TrackLanguageTag{en-MT}
+
+\usepackage[main=ngerman,english]{babel}
+\usepackage{regions}
+
+\begin{document}
+\selectlanguage{ngerman}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\selectlanguage{english}
+
+\unitname: \weightunit, \lengthunit, \currencyunit.
+
+\end{document}
+
No mapping is required for the en-MT locale as it can pick up \captionsenglish when \TrackLangAddToHook (used by \TrackLangAddToCaptions) queries the root language label after failing to find the language hook from the dialect label.

+Some of the predefined tracklang dialects come with a mapping to the closest matching babel dialect label. For example, the option ngermanDE listed in Table 1.3 automatically provides a mapping to ngerman. Since a tracklang dialect label can only map to one babel label, this can be problematic for synonymous labels such as british/UKenglish or american/USenglish. The default mappings used by tracklang are shown in Table 1.3.

+ +

+ +
+

6. Adding Support for Language Tracking

+

+If you are writing a package that sets up the document languages (rather than a package that provides multilingual support if the user has already loaded a language package) then you can load tracklang and use the commands below to help other packages track your provided languages. (See also: Integrating tracklang.tex into Language Packages.)

+The tracklang package can be loaded using

\input tracklang
+
or (LaTeX only)
\RequirePackage{tracklang}
+

+When using LaTeX, there’s a difference between the two. The first case prevents tracklang from picking up the document class options but skips the check for known language packages. This check is redundant since your package is the language package, so you need to decide whether or not to allow the user to set up the localisation information through the document class options.

+There’s a hook that, if defined, is performed by tracklang.sty after the package options have been loaded but before known language packages are checked:

+\@tracklang@prelangpkgcheck@hook
+

+If you prefer \RequirePackage over \input but you want to make tracklang.sty skip the check for known language packages then (as from v1.3.8) define the pre-language package check hook as follows:

\providecommand\@tracklang@prelangpkgcheck@hook{\endinput}
+\RequirePackage{tracklang}[2019/10/06]% v1.3.8+
+
This will still pick up languages supplied through the document class options.

+If you just use \input, there’s a test at the start of tracklang.tex to determine if it’s already been loaded, so you don’t need to worry if the document has already input it.

+To integrate tracklang into your language package, you need to consider the following steps: +

    +
  1. 1.Does tracklang define your supported ISO 15924 language scripts in the tracklang-scripts.tex file?

    +If yes, then skip this step. Otherwise create a file with the relevant \TrackLangScriptMap command for each unknown script and identify this new file with \TrackLangAddExtraScriptFile (see §6.3). This usually won’t be necessary unless you have a custom script or a child script (a script that’s a sub-category of another script).

    +

  2. 2.Does tracklang recognise the root language?

    +If yes, then skip this step.

    +If your package is setting up a language that tracklang doesn’t recognise then you will need to define the root language using \TrackLangNewLanguage (see §6.5).

    +This usually won’t be the case as tracklang should support all languages that have an official ISO 639-1 alpha-2 code.

    +If you simply have a different label from tracklang identifying the root language, then you can just set up your label as a dialect using \TrackLangProvidePredefinedDialect.

    +

  3. 3.Does tracklang define the relevant ISO 3166-1 region codes in the tracklang-region-codes.tex file?

    +If yes, then skip this step. Otherwise create a file with the relevant \TrackLangRegionMap command for each new region and identify this new file with \TrackLangAddExtraRegionFile (see §6.4). This usually won’t be necessary as tracklang should recognise all countries that have an alpha-2 region code, but you may require it if you need a broader region, such as EU.

    +

  4. 4.Do you want to define some convenient dialect labels that can be used with \TrackPredefinedDialect?

    +If no, then skip this step. Otherwise you can use \TrackLangProvidePredefinedLanguage for root languages and \TrackLangProvidePredefinedDialect for dialects with additional information, such as a region, sub-language or script (see §6.6).

    +

  5. 5.In your language initialisation code, add the tracklang code to track the particular dialect (for example, use \TrackPredefinedDialect for recognised dialect labels or use the \AddTrackedXxx set of commands). See §6.1.

    +

  6. 6.In your language selection code (such as \selectlanguage), add \SetCurrentTrackedDialect{label} to allow the document author to easily query the current localisation settings (such as the region). See §6.2. +
+

+ +

+ +
+

6.1. Initialising a New Language or Dialect

+

+When the user requests a particular dialect through your language package, you can notify tracklang of this choice using

\TrackPredefinedDialect{dialect label}
+
provided the dialect label is recognised by tracklang (all those listed in Tables 1.1, 1.2 & 1.3).

+If there’s no matching dialect predefined by tracklang, you can just use \TrackLocale or \TrackLanguageTag (described in §3) with the appropriate ISO codes if you’re not providing caption hooks.

+If you are providing a captions hook mechanism in the form \captionsdialect, then if dialect doesn’t match the corresponding tracklang dialect label, you can provide a mapping using \SetTrackedDialectLabelMap, described below.

+ +

+ +
+

6.2. Switching Language or Dialect

+

+When the document author switches to a different language or dialect, the current localisation information can be set with:

+\SetCurrentTrackedDialect{dialect}
+ where dialect may the tracklang dialect label, or the mapped label previously set through \SetTrackedDialectLabelMap, described below, or the language label (in which case the last dialect to be tracked with that root language will be assumed).

+This will make the following commands available which may be of use to other packages: +

+ (Without this automated use of \SetCurrentTrackedDialect, the same information can be picked up using commands like \GetTrackedDialectScript, but that’s less convenient, especially if \languagename needs to be converted to dialect. See the accompanying sample file sample-setlang.tex for an example.)

+ +

+ +
+

6.3. Defining New Scripts

+

+The tracklang-scripts.tex file isn’t automatically loaded, but if it is then, as from v1.4, it contains a hook at the end of the file that can be used to load additional files that define supplementary scripts. This entails creating a file called, say, mypackage-scripts.tex that contains:

\TrackLangScriptMap{alpha code}{numeric code}{name}{direction}{parent script}
+
The first argument alpha code is the four-letter ISO 15924 code (such as Latn), the second argument is the numeric code (such as 215), the third argument name is the name of the script (such as Latin), the fourth argument is the direction (such as LR for left-to-right) and the final argument is the parent script (leave blank if there’s no parent). Note that this command will override any previous mapping for those codes. No check is performed to determine if they have already been defined.

+The supplementary file should be identified with:

\TrackLangAddExtraScriptFile{filename}
+

+Additional information can be found in §4.

+ +

+ +
+

6.4. Defining New Regions

+

+The tracklang-region-codes.tex file isn’t automatically loaded, but if it is then, as from v1.4, it contains a hook at the end of the file that can be used to load additional files that define supplementary regions. This entails creating a file called, say, mypackage-regions.tex that contains:

\TrackLangRegionMap{numeric code}{alpha-2 code}{alpha-3 code}
+
where the first argument is the numeric region code (such as 826), the second argument is the alpha-2 region code (such as GB) and the third argument is the alpha-3 region code (such as GBR). Note that this command will override any previous mapping for those codes. No check is performed to determine if they have already been defined.

+The supplementary file should be identified with:

\TrackLangAddExtraRegionFile{filename}
+

+Additional information can be found in §4.

+ +

+ +
+

6.5. Defining a New Language

+

+(New to version 1.3.) If the root language isn’t recognised by tracklang (not listed in Table 1.2), then it can be defined (but not tracked at this point) using:

+\TrackLangNewLanguage{language label}{639-1 code}{639-2 (T)}{639-2 (B)}{639-3}{3166-1}{default script}
+ where language label is the root language label, 639-1 code is the ISO 639-1 code for that language (may be empty if there isn’t one), 639-2 (T) is the ISO 639-2 (T) code for that language (may be empty if there isn’t one), 639-2 (B) is the ISO 639-2 (B) code for that language (may be empty if it’s the same as 639-2 (T)), 639-3 is the ISO 639-3 code for that language (empty if the same as the 639-2 code), 3166-1 is the territory ISO 3166-1 code for languages that are only spoken in one territory (should be empty if the language is spoken in multiple territories), and default script is the default script (empty if disputed or varies according to region).

+You can then track this language using:

+\AddTrackedDialect{dialect label}{root language label}
+ for dialects (where dialect label is the dialect label and root language label is the root language label) or, if no regional variant is needed, you can instead use:
+\AddTrackedLanguage{root language label}
+ This is equivalent to
\AddTrackedDialect{root language label}{root language label}
+
Note that \AddTrackedDialect defines:
+\TrackLangLastTrackedDialect
+ to the dialect label, which makes it easier to reference the last dialect to be tracked.

+ +

+ +
+

6.6. Defining New tracklang Labels

+

+A dialect label may be predefined with associated information that allows that particular combination to be easily tracked with \TrackPredefinedDialect. In the case of a dialect label that only requires the information provided in \TrackLangNewLanguage you can use:

+\TrackLangProvidePredefinedLanguage{language label}
+ where language label corresponds to the language label used in \TrackLangNewLanguage. This allows
\TrackPredefinedDialect{label}
+
to not only track the root language but also the associated ISO codes.

+If the dialect label doesn’t match the root language label then use:

+\TrackLangProvidePredefinedDialect{dialect label}{root language label}{3166-1 code}{modifier}{variant}{map}{script}
+ where dialect label is the new tracklang dialect label, {root language label} is the tracklang root language label, region is the ISO 3166-1 region code (may be empty), modifier is the modifier (may be empty), variant is the variant information (may be empty), map is your package’s language label that corresponds to the tracklang dialect label supplied in the first argument (may be empty if identical), and script is the ISO 15924 alpha-4 script code (may be empty if it’s the same as the default script for the root language).

+For compatibility with pre version 1.3, if the dialect isn’t predefined by tracklang, then you can use:

\AddTrackedDialect{dialect}{root language label}
+
where root language label is the label for the dialect’s root language (Table 1.2) and dialect matches the captions hook. If the dialect is already in the tracked dialect list, it won’t be added again. If the root language is already in the tracked language list, it won’t be added again. As from version 1.3 this additionally defines \TrackLangLastTrackedDialect to dialect for convenient reference if required. Note that \AddTrackedDialect is internally used by commands like \TrackPredefinedDialect, \TrackLocale and \TrackLanguageTag.

+(New to version 1.3.) Many of the tracklang dialect labels don’t have a corresponding match in various language packages. For example, tracklang provides ngermanDE but the closest match in babel is ngerman. This means that the caption hook \captionsngerman can’t be accessed through:

\csname captions\CurrentTrackedDialect\endcsname
+
in the resource files. In this case, a mapping may be defined between the tracklang dialect label and the closest matching label used by the language hooks. This is done through
+\SetTrackedDialectLabelMap{tracklang-label}{hook-label}
+ where tracklang-label is the tracklang label and hook-label is the language hook label. For example:
\TrackLanguageTag{de-AR-1996}
+\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{ngerman}
+
Since \TrackLanguageTag internally uses \AddTrackedDialect the dialect label created by tracklang can be accessed using \TrackLangLastTrackedDialect. This means that \TrackLangAddToCaptions can now find the \captionsngerman hook even though the tracklang dialect label isn’t ngerman.

+(New to version 1.3.) If the root language label is recognised by tracklang, you can add the ISO codes using:

+\AddTrackedLanguageIsoCodes{root language label}
+

+As from v1.3, you can also provide a modifier for a given dialect using:

+\SetTrackedDialectModifier{dialect}{value}
+ where dialect is the dialect label and value is the modifier value. For example:
\AddTrackedDialect{oldgerman}{german}
+\AddTrackedLanguageIsoCodes{german}
+\SetTrackedDialectModifier{oldgerman}{old}
+

+Note that no sanitization is performed on value when the modifier is set explicitly through \SetTrackedDialectModifier, since it’s assumed that any package that specifically sets the modifier in this way is using a sensible labelling system. If the modifier is obtained through commands like \TrackLocale, then the modifier is sanitized as the value may have been obtained from the operating system and there’s no guarantee that it won’t contain problematic characters.

+The modifier is typically obtained by parsing locale information in POSIX format.

language[_territory][.codeset][@modifier]
+
whereas the variant is typically obtained by parsing the language tag.

+The information provided in the commands below (such as the script) are typically obtained by parsing the language tag. For example, with Serbian in the Latin alphabet the modifier would be latin whereas the script would be Latn:

\AddTrackedDialect{serbianlatin}{serbian}
+\AddTrackedLanguageIsoCodes{serbian}
+\SetTrackedDialectModifier{serbianlatin}{latin}
+\SetTrackedDialectScript{serbianlatin}{Latn}
+

+As from v1.3, you can provide a script (for example, Latn or Cyrl) using:

+\SetTrackedDialectScript{dialect}{value}
+ where dialect is the dialect label and value is the ISO 15924 alpha-4 script identifier. For example:
\AddTrackedDialect{serbiancyrl}{serbian}
+\AddTrackedLanguageIsoCodes{serbian}
+\SetTrackedDialectScript{serbiancyrl}{Cyrl}
+

+As from v1.3, you can provide a variant for a given dialect using:

+\SetTrackedDialectVariant{dialect}{value}
+ For example:
\AddTrackedDialect{german1901}{german}
+\SetTrackedDialectVariant{german1901}{1901}
+

+As from v1.3, you can also provide a sub-language using:

+\SetTrackedDialectSubLang{dialect}{value}
+ where dialect is the dialect label and value is the code. For example:
\AddTrackedDialect{mandarin}{chinese}
+\AddTrackedLanguageIsoCodes{chinese}
+\SetTrackedDialectSubLang{mandarin}{cmn}
+\AddTrackedIsoLanguage{639-3}{cmn}{mandarin}
+

+As from v1.3, you can also provide additional information using:

+\SetTrackedDialectAdditional{dialect}{value}
+ where dialect is the dialect label and value is the additional information.

+ +

+ +
+

6.7. Example (alien.sty)

+

+Suppose I want to create a language package alien.sty that defines the martian language with regional dialects lowermartian and uppermartian. First, let’s suppose that tracklang recognises the root language martian:

\ProvidesPackage{alien}
+
+\inputtracklang% v1.3
+
+\DeclareOption{martian}{% 
+ \TrackPredefinedDialect{martian}
+}
+\DeclareOption{lowermartian}{% 
+ \AddTrackedDialect{lowermartian}{martian}
+ \AddTrackedLanguageIsoCodes{martian}
+ \AddTrackedIsoLanguage{3166-1}{YY}{lowermartian}
+ % other attributes such as
+ % \SetTrackedDialectVariant{lowermartian}{...}
+}
+\DeclareOption{uppermartian}{% 
+ \AddTrackedDialect{uppermartian}{martian}
+ \AddTrackedLanguageIsoCodes{martian}
+ \AddTrackedIsoLanguage{3166-1}{XX}{uppermartian}
+ % other attributes such as
+ % \SetTrackedDialectVariant{uppermartian}{...}
+}
+
+\ProcessOptions
+
+\newcommand*{\selectlanguage}[1]{% 
+ \def\languagename{#1}% 
+ % other stuff
+ \SetCurrentTrackedDialect{#1}%  
+}
+
+\AnyTrackedLanguages
+{
+ \ForEachTrackedDialect{\thisdialect}
+ {% 
+  \TrackLangRequireDialect{alien}{\thisdialect}
+ }
+}
+
The caption commands and language set up are in the files alien-localeid.ldf as in the examples from §5.1. This allows for the user having already loaded tracklang before alien and used \TrackLangFromEnv to pick up the locale from the operating system’s environment variables. (For example, they may have LANG set to xx_YY.)

+The resource files may need to set the mapping between the tracklang dialect label and the alien dialect label. For example, in alien-xx-YY.ldf:

\TrackLangProvidesResource{xx-YY}
+
+\TrackLangRequireResource{martian}% load common elements
+
+\newcommand{\captionslowermartian}{% 
+ \captionsmartian
+ \def\contentsname{X'flurp}% regional variation
+}
+
+\SetTrackedDialectLabelMap{\CurrentTrackedDialect}{lowermartian}
+

+Now let’s consider the case where tracklang doesn’t know about the martian language. In this case the user can’t track the dialect until the root language has been defined, so the user can’t use \TrackLangFromEnv before using the alien package.

+With tracklang v1.3. The new root language can be defined with a minor adjustment to the above code:

\ProvidesPackage{alien}
+
+\input{tracklang}% needs v1.3
+
+\TrackLangIfKnownLang{martian}
+{}% tracklang already knows about the martian language
+{
+ % tracklang doesn't known about the martian language, so define it
+ % with ISO 639-1 (xx) and ISO 639-2 (xxx) codes:
+ \TrackLangNewLanguage{martian}{xx}{xxx}{}{}{}{Latn}
+}
+
The rest is as before.

+Now other package writers who want to provide support for the Martian dialects can easily detect which language options the user requested through my package, without needing to know anything about my alien package.

+ +

+ +
+
II. Summaries
+

+

+ +

+ +
+

A. Region and Script Mappings

+

+Region mappings are listed in Table A.1, and script mappings are listed in Table A.2.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4: Region Mappings
Alpha-2Alpha-3NumericAlpha-2Alpha-3Numeric
ADAND020 +AEARE784
AFAFG004 +AGATG028
AIAIA660 +ALALB008
AMARM051 +AOAGO024
AQATA010 +ARARG032
ASASM016 +ATAUT040
AUAUS036 +AWABW533
AXALA248 +AZAZE031
BABIH070 +BBBRB052
BDBGD050 +BEBEL056
BFBFA854 +BGBGR100
BHBHR048 +BIBDI108
BJBEN204 +BLBLM652
BMBMU060 +BNBRN096
BOBOL068 +BQBES535
BRBRA076 +BSBHS044
BTBTN064 +BVBVT074
BWBWA072 +BYBLR112
BZBLZ084 +CACAN124
CCCCK166 +CDCOD180
CFCAF140 +CGCOG178
CHCHE756 +CICIV384
CKCOK184 +CLCHL152
CMCMR120 +CNCHN156
COCOL170 +CRCRI188
CUCUB192 +CVCPV132
CWCUW531 +CXCXR162
CYCYP196 +CZCZE203
DEDEU276 +DJDJI262
DKDNK208 +DMDMA212
DODOM214 +DZDZA012
ECECU218 +EEEST233
EGEGY818 +EHESH732
ERERI232 +ESESP724
ETETH231 +FIFIN246
FJFJI242 +FKFLK238
FMFSM583 +FOFRO234
FRFRA250 +GAGAB266
GBGBR826 +GDGRD308
GEGEO268 +GFGUF254
GGGGY831 +GHGHA288
GIGIB292 +GLGRL304
GMGMB270 +GNGIN324
GPGLP312 +GQGNQ226
GRGRC300 +GSSGS239
GTGTM320 +GUGUM316
GWGNB624 +GYGUY328
HKHKG344 +HMHMD334
HNHND340 +HRHRV191
HTHTI332 +HUHUN348
IDIDN360 +IEIRL372
ILISR376 +IMIMN833
ININD356 +IOIOT086
IQIRQ368 +IRIRN364
ISISL352 +ITITA380
JEJEY832 +JMJAM388
JOJOR400 +JPJPN392
KEKEN404 +KGKGZ417
KHKHM116 +KIKIR296
KMCOM174 +KNKNA659
KPPRK408 +KRKOR410
KWKWT414 +KYCYM136
KZKAZ398 +LALAO418
LBLBN422 +LCLCA662
LILIE438 +LKLKA144
LRLBR430 +LSLSO426
LTLTU440 +LULUX442
LVLVA428 +LYLBY434
MAMAR504 +MCMCO492
MDMDA498 +MEMNE499
MFMAF663 +MGMDG450
MHMHL584 +MKMKD807
MLMLI466 +MMMMR104
MNMNG496 +MOMAC446
MPMNP580 +MQMTQ474
MRMRT478 +MSMSR500
MTMLT470 +MUMUS480
MVMDV462 +MWMWI454
MXMEX484 +MYMYS458
MZMOZ508 +NANAM516
NCNCL540 +NENER562
NFNFK574 +NGNGA566
NINIC558 +NLNLD528
NONOR578 +NPNPL524
NRNRU520 +NUNIU570
NZNZL554 +OMOMN512
PAPAN591 +PEPER604
PFPYF258 +PGPNG598
PHPHL608 +PKPAK586
PLPOL616 +PMSPM666
PNPCN612 +PRPRI630
PSPSE275 +PTPRT620
PWPLW585 +PYPRY600
QAQAT634 +REREU638
ROROU642 +RSSRB688
RURUS643 +RWRWA646
SASAU682 +SBSLB090
SCSYC690 +SDSDN729
SESWE752 +SGSGP702
SHSHN654 +SISVN705
SJSJM744 +SKSVK703
SLSLE694 +SMSMR674
SNSEN686 +SOSOM706
SRSUR740 +SSSSD728
STSTP678 +SVSLV222
SXSXM534 +SYSYR760
SZSWZ748 +TCTCA796
TDTCD148 +TFATF260
TGTGO768 +THTHA764
TJTJK762 +TKTKL772
TLTLS626 +TMTKM795
TNTUN788 +TOTON776
TRTUR792 +TTTTO780
TVTUV798 +TWTWN158
TZTZA834 +UAUKR804
UGUGA800 +UMUMI581
USUSA840 +UYURY858
UZUZB860 +VAVAT336
VCVCT670 +VEVEN862
VGVGB092 +VIVIR850
VNVNM704 +VUVUT548
WFWLF876 +WSWSM882
YEYEM887 +YTMYT175
ZAZAF710 +ZMZMB894
ZWZWE716
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5: Script Mappings
Alpha-2NumericDirectionDescription
Adlm166RLAdlam.
Afak439variesAfaka.
Aghb239LRCaucasian Albanian.
Ahom338LRAhom, Tai Ahom.
Arab160RLArabic.
Aran161RLArabic (Nastaliq variant).
Armi124RLImperial Aramaic.
Armn230LRArmenian.
Avst134RLAvestan.
Bali360LRBalinese.
Bamu435LRBamum.
Bass259LRBassa Vah.
Batk365LRBatak.
Beng334LRBhaiksuki.
Blis550variesBlissymbols.
Bopo285LRBopomofo.
Brah300LRBrahmi.
Brai570LRBraille.
Bugi367LRBuginese.
Buhd372LRBuhid.
Cakm349LRChakma.
Cans440LRUnified Canadian Aboriginal Syllabics.
Cari201LRCarian.
Cham358LRCham.
Cher445LRCherokee.
Cirt291variesCirth.
Copt204LRCoptic.
Cprt403RLCypriot.
Cyrl220LRCyrillic.
Cyrs221variesCyrillic (Old Church Slavonic variant).
Deva315LRDevanagari (Nagari).
Dsrt250LRDeseret (Mormon).
Dupl755LRDuployan shorthand, Duployan stenography.
Egyd070RLEgyptian demotic.
Egyh060RLEgyptian hieratic.
Egyp050LREgyptian hieroglyphs.
Elba226LRElbasan.
Ethi430LREthiopic (Ge’ez).
Geok241LRKhutsuri (Asomtavruli and Nuskhuri).
Geor240LRGeorgian (Mkhedruli).
Glag225LRGlagolitic.
Goth206LRGothic.
Gran343LRGrantha.
Grek200LRGreek.
Gujr320LRGujarati.
Guru310LRGurmukhi.
Hanb503LRHan with Bopomofo (alias for Han + Bopomofo).
Hang286LRHangul.
Hani500LRHan (Hanzi, Kanji, Hanja).
Hano371LRHanunoo.
Hans501variesHan (Simplified variant).
Hant502variesHan (Traditional variant).
Hatr127RLHatran.
Hebr125RLHebrew.
Hira410LRHiragana.
Hluw080LRAnatolian Hieroglyphs (Luwian Hieroglyphs, Hittite Hieroglyphs).
Hmng450LRPahawh Hmong.
Hrkt412variesJapanese syllabaries (alias for Hiragana + Katakana).
Hung176RLOld Hungarian (Hungarian Runic).
Inds610RLIndus (Harappan).
Ital210LROld Italic (Etruscan, Oscan, etc.)
Jamo284LRJamo (alias for Jamo subset of Hangul).
Java361LRJavanese.
Jpan413variesJapanese (alias for Han + Hiragana + Katakana).
Jurc510LRJurchen.
Kali357LRKayah Li.
Kana411LRKatakana.
Khar305RLKharoshthi.
Khmr355LRKhmer.
Khoj322LRKhojki.
Kitl505LRKhitan large script.
Kits288TBKhitan small script.
Knda345LRKannada.
Kore287LRKorean (alias for Hangul + Han).
Kpel436LRKpelle.
Kthi317LRKaithi.
Lana351LRTai Tham (Lanna).
Laoo356LRLao.
Latf217variesLatin (Fraktur variant).
Latg216LRLatin (Gaelic variant).
Latn215LRLatin.
Leke364LRLeke.
Lepc335LRLepcha.
Limb336LRLimbu.
Lina400LRLinear A.
Linb401LRLinear B.
Lisu399LRLisu (Fraser).
Loma437LRLoma.
Lyci202LRLycian.
Lydi116RLLydian.
Mahj314LRMahajani.
Mand140RLMandaic, Mandaean.
Mani139RLManichaean.
Marc332LRMarchen.
Maya090variesMayan hieroglyphs.
Mend438RLMende Kikakui.
Merc101RLMeroitic Cursive.
Mero100RLMeroitic Hieroglyphs.
Mlym347LRMalayalam.
Modi324LRModi.
Mong145TBMongolian.
Moon218variesMoon (Moon code, Moon script, Moon type).
Mroo199LRMro, Mru.
Mtei337LRMeitei Mayek (Meithei, Meetei).
Mult323LRMultani.
Mymr350LRMyanmar (Burmese).
Narb106RLOld North Arabian (Ancient North Arabian).
Nbat159RLNabataean.
Newa333LRNewa, Newar, Newari.
Nkgb420LRNakhi Geba.
Nkoo165RLN’Ko.
Nshu499LRNushu.
Ogam212variesOgham.
Olck261LROl Chiki.
Orkh175RLOld Turkic, Orkhon Runic.
Orya327LROriya.
Osge219LROsage.
Osma260LROsmanya.
Palm126RLPalmyrene.
Pauc263LRPau Cin Hau.
Perm227LROld Permic.
Phag331TBPhags-pa.
Phli131RLInscriptional Pahlavi.
Phlp132RLPsalter Pahlavi.
Phlv133RLBook Pahlavi.
Phnx115RLPhoenician.
Piqd293LRKlingon (KLI plqaD).
Plrd282LRMiao (Pollard).
Prti130RLInscriptional Parthian.
Qaaa900variesReserved for private use (start).
Qaai908variesPrivate use.
Qabx949variesReserved for private use (end).
Rjng363LRRejang (Redjang, Kaganga).
Roro620variesRongorongo.
Runr211LRRunic.
Samr123RLSamaritan.
Sara292variesSarati.
Sarb105RLOld South Arabian.
Saur344LRSaurashtra.
Sgnw095TBSignWriting.
Shaw281LRShavian (Shaw).
Shrd319LRSharada.
Sidd302LRSiddham.
Sind318LRKhudawadi, Sindhi.
Sinh348LRSinhala.
Sora398LRSora Sompeng.
Sund362LRSundanese.
Sylo316LRSyloti Nagri.
Syrc135RLSyriac.
Syre138RLSyriac (Estrangelo variant).
Syrj137RLSyriac (Western variant).
Syrn136RLSyriac (Eastern variant).
Tagb373LRTagbanwa.
Takr321LRTakri.
Tale353LRTai Le.
Talu354LRNew Tai Lue.
Taml346LRTamil.
Tang520LRTangut.
Tavt359LRTai Viet.
Telu340LRTelugu.
Teng290LRTengwar.
Tfng120LRTifinagh (Berber).
Tglg370LRTagalog (Baybayin, Alibata).
Thaa170RLThaana.
Thai352LRThai.
Tibt330LRTibetan.
Tirh326LRTirhuta.
Ugar040LRUgaritic.
Vaii470LRVai.
Visp280LRVisible Speech.
Wara262LRWarang Citi (Varang Kshiti).
Wole480RLWoleai.
Xpeo030LROld Persian.
Xsux020LRCuneiform, Sumero-Akkadian.
Yiii460LRYi.
Zinh994inheritedInherited script.
Zmth995LRMathematical notation.
Zsye993variesSymbols (emoji variant).
Zsym996variesSymbols.
Zxxx997variesUnwritten documents.
Zyyy998variesUndetermined script.
Zzzz999variesUncoded script.
+

+ +

+ +
+

Symbols

+ +
+
📌
+
The syntax and usage of a command, environment or option etc.
+
+
An important message.
+
🛈
+
Prominent information.
+
🖹
+
LaTeX code to insert into your document.
+
🖺
+
How the example code should appear in the PDF.
+
〉_
+
A command-line application invocation that needs to be entered into a terminal or command prompt.
+ +
+ +
+ +
+

Glossary

+ +
+
Command-line interface (CLI)
+
An application that doesn’t have a graphical user interface. That is, an application that doesn’t have any windows, buttons or menus and can be run in a command prompt or terminal.
+
Shell escape
+
TeX has the ability to run CLI applications while it’s typesetting a document. Whilst this is a convenient way of using tools to help build the document, it’s a security risk. To help protect users from arbitrary―and potentially dangerous―code from begin executed, TeX has a restricted mode, where only trusted applications are allowed to run. This is usually the default mode, but your TeX installation may be set up so that the shell escape is disabled by default. The unrestricted mode allows you to run any application from the shell escape. Take care about enabling this option. If you receive a document or package from an untrusted source, first run TeX with the shell escape disabled or in restricted mode and search the log file for “runsystem” before using the unrestricted mode. Note that LuaLaTeX additionally requires the shellesc package.
+ +
+ +
+ +
+

Command Summary

+ +
+ +
+

@

+ +

+Provided by tracklang.sty to declare dialect as a package option that tracks dialect. Provided by tracklang.tex, if not already defined, to ignore its argument. §3; 19

+

\@tracklang@forcs:=list\do{body}tracklang.tex v1.0+
+

+As LaTeX’s \@for. §5; 37

+

+

+If defined before tracklang.sty v1.3.8+ is loaded, this command will be done after package options have been processed but before the check for language packages, such as babel and polyglossia. §6; 71

+ +

+ +
+

A

+
\AddTrackedCountryIsoCode{language}tracklang.tex v1.3+
+

+Adds the ISO 3166-1 code.

+

\AddTrackedDialect{dialect label}{root language label}tracklang.tex v1.0+
+

+Tracks a dialect. This command defines \TrackLangLastTrackedDialect to provide a convenient way to reference the last dialect to be tracked. §6.5; 75

+

\AddTrackedIsoLanguage{code type}{code}{language}tracklang.tex v1.0+
+

+Adds a mapping between the given ISO code and language name.

+

\AddTrackedLanguage{root language label}tracklang.tex v1.0+
+

+Shortcut for \AddTrackedDialect{root language label}{root language label}. §6.5; 75

+

\AddTrackedLanguageIsoCodes{root language label}tracklang.tex v1.3+
+

+Adds the ISO 639-1, 639-2 and 639-3 codes, which must have previously been declared using \TrackLangNewLanguage. §6.6; 77

+

\AnyTrackedLanguages{true}{false}tracklang.tex v1.0+
+

+Expands to true if there are any tracked languages, otherwise expands to false. §5; 35

+ +

+ +
+

C

+ +

+Defined by \SetCurrentTrackedDialect to the dialect label, which may be the supplied dialect label or the mapped label or, if dialect is a root language label, the last tracked dialect for the given root language. §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the additional part associated with the dialect (may be empty). §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the associated modifier (may be empty). §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the script associated with the dialect, or to the default script for the language. §5; 47

+

+

+Defined by \SetCurrentTrackedDialect to the sub language associated with the dialect (may be empty). §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the associated variant (may be empty). §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the ISO 639-1 or 639-2 or 639-3 language code (may be empty). §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the associated root language label. §5; 46

+

+

+Defined by \SetCurrentTrackedDialect to the language tag that identifies the dialect or und if no match. §5; 47

+

+

+Defined by \SetCurrentTrackedDialect to the ISO 3166-1 region code associated with the dialect (may be empty). §5; 46

+

+

+Expands to the current tracked tag. §5; 45

+ +

+ +
+

F

+
\ForEachTrackedDialect{cs}{body}tracklang.tex v1.0+
+

+Iterates through the list of tracked dialects. On each iteration cs is set to the dialect tag and body is performed. §5; 37

+

\ForEachTrackedLanguage{cs}{body}tracklang.tex v1.0+
+

+Iterates through the list of tracked languages. On each iteration cs is set to the language tag and body is performed. §5; 37

+ +

+ +
+

G

+ +

+Expands to the extra information for dialect. §5; 44

+

+

+Finds the tracked dialect that matches the given language tag and stores the dialect label in cs. If no match found, cs will be empty. §5; 36

+

+

+Expands to the modifier for the given dialect. §5; 40

+

+

+Expands to the script for dialect. §5; 42

+

+

+Expands to the sub-language for dialect. §5; 44

+

+

+Expands to the modifier for dialect. §5; 42

+

+

+Gets the language tag for dialect. §5; 40

+ +

+ +
+

I

+
\IfHasTrackedDialectAdditional{dialect}{true}{false}tracklang.tex v1.3+
+

+Expands to true if there’s extra information for dialect, otherwise expands to false. §5; 44

+

\IfHasTrackedDialectModifier{dialect}{true}{false}tracklang.tex v1.3+
+

+Expands to true if there’s a modifier for the given dialect, otherwise expands to false. §5; 41

+

\IfHasTrackedDialectScript{dialect}{true}{false}tracklang.tex v1.3+
+

+Expands to true if there’s a script for dialect, otherwise expands to false. §5; 42

+

\IfHasTrackedDialectSubLang{dialect}{true}{false}tracklang.tex v1.3+
+

+Expands to true if there’s a sub-language for dialect, otherwise expands to false. §5; 44

+

\IfHasTrackedDialectVariant{dialect}{true}{false}tracklang.tex v1.3+
+

+Expands to true if there’s a modifier for dialect, otherwise expands to false. §5; 42

+

\IfTrackedDialect{dialect-label}{true}{false}tracklang.tex v1.0+
+

+Does true if the dialect identified by dialect-label has been tracked, otherwise does false. §5; 38

+

\IfTrackedDialectIsScriptCs{dialect}{cs}{true}{false}tracklang.tex v1.3+
+

+If the given tracked dialect has an associated script and that script code matches the replacement text for the control sequence cs then do true otherwise to false. If the tracked dialect doesn’t have an associated script then the default script for the root language is tested. §5; 43

+

\IfTrackedIsoCode{code type}{code}{true}{false}tracklang.tex v1.0+
+

+Does true if the given ISO code has been defined otherwise does false. §5; 39

+

\IfTrackedLanguage{language-label}{true}{false}tracklang.tex v1.0+
+

+Does true if the language identified by language-label has been tracked, otherwise does false. §5; 38

+

\IfTrackedLanguageFileExists{dialect}{prefix}{suffix}{true code}{false code}tracklang.tex v1.0+
+

+Does \SetCurrentTrackedDialect{dialect} and if the dialect is recognised, then determines if the file prefixtagsuffix exists. If it does, \CurrentTrackedTag is set to tag and true is done, otherwise false is done. §5; 45

+

\IfTrackedLanguageHasIsoCode{code type}{label}{true}{false}tracklang.tex v1.0+
+

+Does true if the given language or dialect has a corresponding ISO code of the given type, otherwise does false. §5; 39

+

\ifTrackLangShowInfo true\else false\fiinitial: \iftrue; tracklang.tex v1.3+
+

+Conditional that indicates whether or not to show information messages.

+

\ifTrackLangShowVerbose true\else false\fiinitial: \iffalse; tracklang.tex v1.4+
+

+Conditional that indicates whether or not to show verbose messages.

+

\ifTrackLangShowWarnings true\else false\fiinitial: \iftrue; tracklang.tex v1.3+
+

+Conditional that indicates whether or not to show warnings.

+ +

+ +
+

S

+ +

+Sets the current tracked dialect. §6.2; 73

+

\SetTrackedDialectAdditional{dialect}{value}tracklang.tex v1.3+
+

+Sets the extra information for dialect to value. §6.6; 79

+

\SetTrackedDialectLabelMap{tracklang-label}{hook-label}tracklang.tex v1.3+
+

+Defines a mapping between a tracklang dialect label and the corresponding dialect label used by a language hook, such as \captionsdialect. §6.6; 77

+

\SetTrackedDialectModifier{dialect}{value}tracklang.tex v1.3+
+

+Sets the modifier for the given dialect to value. §6.6; 77

+

\SetTrackedDialectScript{dialect}{value}tracklang.tex v1.3+
+

+Sets the script for dialect to value. §6.6; 78

+

\SetTrackedDialectSubLang{dialect}{value}tracklang.tex v1.3+
+

+Sets the sub-language for dialect to value. §6.6; 79

+

\SetTrackedDialectVariant{dialect}{value}tracklang.tex v1.3+
+

+Sets the modifier for dialect to value. §6.6; 78

+ +

+ +
+

T

+ +

+Expands to 639-3 (should not be redefined). §5; 40

+

+

+Expands to 639-2 (should not be redefined). §5; 40

+

+

+Defined by \GetTrackedDialectFromLanguageTag to the closest match. §5; 36

+

\TrackedDialectsFromLanguage{root language label}tracklang.tex v1.0+
+

+Expands to a comma-separated list of the tracked dialects with the given language. §5; 39

+

\TrackedIsoCodeFromLanguage{code type}{label}tracklang.tex v1.0+
+

+Expands to the code associated with the given language or dialect identified by label. §5; 39

+

+

+Expands to the language from the given dialect. §5; 39

+

\TrackedLanguageFromIsoCode{code type}{code}tracklang.tex v1.0+
+

+Expands to a comma-separated list of language or dialect labels associated with the given code. §5; 39

+

\TrackIfKnownLanguage{tag}{success code}{fail code}tracklang.tex v1.3.9+
+

+As \TrackLanguageTag but does fail code if the tag doesn’t contain a valid language code. If successful, does success code after tracking the language. §3; 21

+

+

+Adds file to the list of extra region code files that should be input by tracklang-region-codes.tex. §4; 31

+

+

+Adds file to the list of files that should be input by tracklang-scripts.tex. §4; 33

+

+

+A shortcut that just does \TrackLangAddToHook{code}{captions}. §5; 54

+

\TrackLangAddToHook{code}{type}tracklang.tex v1.3+
+

+For use within resource files, this can be used to add code to the appropriate hook. §5; 54

+

+

+Expands to the numeric code corresponding to the given alpha-3 code. §4; 30

+

+

+Expands to the numeric code corresponding to the given alpha-2 code. §4; 30

+

\TrackLangDeclareDialectOption{dialect}{root language}{3166-1 code}{modifier}{variant}{map}{script}tracklang.tex v1.3+
+

+Defines a predefined dialect label that can be used by \TrackPredefinedDialect.

+

\TrackLangDeclareLanguageOption{language name}{639-1 code}{639-2 (T)}{639-2 (B)}{639-3}{3166-1}{default script}tracklang.tex v1.3+
+

+Defines a new root language that’s declared as an option.

+

\TrackLangEnv

+

(user defined)
+
+

+May be defined using the same format as LC_ALL before using \TrackLangParseFromEnv to skip the environment variable query. §3; 25

+

+

+Set by \TrackLangParseFromEnv to the code-set. §3; 26

+

+

+Set by \TrackLangParseFromEnv to the language code. §3; 26

+

+

+Set by \TrackLangParseFromEnv to the modifier. §3; 26

+

+

+Set by \TrackLangParseFromEnv to the territory. §3; 26

+

+

+Queries environment variable if \TrackLangEnv not already set, parses \TrackLangEnv if it has been set, and adds the dialect if it’s recognised. §3; 23

+

+

+Expands to the default script for the given language. §5; 43

+

\TrackLangGetKnownCountry{language}tracklang.tex v1.3+
+

+Expands to the ISO 3166-1 country code for the given language.

+

\TrackLangGetKnownIsoThreeLetterLang{language}tracklang.tex v1.3+
+

+Expands to the ISO 639-2 language code associated with language.

+

\TrackLangGetKnownIsoThreeLetterLangB{language}tracklang.tex v1.3+
+

+Expands to the ISO 639-2 (B) language code associated with language.

+

\TrackLangGetKnownIsoTwoLetterLang{language}tracklang.tex v1.3+
+

+Expands to the ISO 639-1 language code associated with language.

+

\TrackLangGetKnownLangFromIso{ISO code}tracklang.tex v1.3+
+

+Expands to the root language label from the given ISO code (639-1 or 639-2 or 639-3).

+

\TrackLangIfAlphaNumericChar{tag}{true}{false}tracklang.tex v1.3+
+

+Does true if the argument is a single alphanumeric character otherwise does false.

+

\TrackLangIfHasDefaultScript{language}{true}{false}tracklang.tex v1.3+
+

+Does true if the given language has a default script (but is not necessarily tracked), otherwise does false.

+

\TrackLangIfHasKnownCountry{language}{true}{false}tracklang.tex v1.3+
+

+Does true if the given language has an ISO 3166-1 country code (but is not necessarily tracked), otherwise does false.

+

\TrackLangIfKnownAlphaIIIRegion{alpha-3 code}{true}{false}tracklang-region-codes.tex v1.3+
+

+Expands to true if there’s a known mapping for the given alpha-3 code, otherwise expands to false. §4; 31

+

\TrackLangIfKnownAlphaIIRegion{alpha-2 code}{true}{false}tracklang-region-codes.tex v1.3+
+

+Expands to true if there’s a known mapping for the given alpha-2 region code, otherwise expands to false. §4; 30

+

\TrackLangIfKnownIsoThreeLetterLang{language}{true}{false}tracklang.tex v1.3+
+

+Does true if language has an ISO 639-2 code (but is not necessarily tracked), otherwise does false.

+

\TrackLangIfKnownIsoThreeLetterLangB{language}{true}{false}tracklang.tex v1.3+
+

+Does true if language has an ISO 639-2 (B) code (but is not necessarily tracked), otherwise does false.

+

\TrackLangIfKnownIsoTwoLetterLang{language}{true}{false}tracklang.tex v1.3+
+

+Does true if language has an ISO 639-1 code (but is not necessarily tracked), otherwise does false.

+

\TrackLangIfKnownLang{language}{true}{false}tracklang.tex v1.3+
+

+Does true if language is known (but not necessarily tracked), otherwise does false.

+

\TrackLangIfKnownLangFromIso{ISO code}{true}{false}tracklang.tex v1.3+
+

+Does true if the given language code (639-1 or 639-2 or 639-3) is recognised (but not necessarily tracked), otherwise does false.

+

\TrackLangIfKnownNumericRegion{numeric code}{true}{false}tracklang-region-codes.tex v1.3+
+

+Expands to true if there’s a known mapping for the given numeric region code, otherwise expands to false. §4; 30

+

\TrackLangIfLanguageTag{tag}{true}{false}tracklang.tex v1.3+
+

+Does true if the argument is a language tag otherwise does false.

+

\TrackLangIfRegionTag{tag}{true}{false}tracklang.tex v1.3+
+

+Does true if the argument is a region tag otherwise does false.

+

\TrackLangIfScriptTag{tag}{true}{false}tracklang.tex v1.3+
+

+Does true if the argument is a script tag otherwise does false.

+

\TrackLangIfVariantTag{tag}{true}{false}tracklang.tex v1.3+
+

+Does true if the argument is a variant tag otherwise does false.

+

+

+Expands to the label of the last tracked dialect. §6.5; 76

+

\TrackLangNewLanguage{language label}{639-1 code}{639-2 (T)}{639-2 (B)}{639-3}{3166-1}{default script}tracklang.tex v1.3+
+

+Identifies a new language that may be tracked. Apart from language label, the other arguments may be empty if the information is unavailable. §6.5; 75

+

+

+Expands to the alpha-3 code corresponding to the given numeric code. §4; 31

+

+

+Expands to the alpha-2 code corresponding to the given numeric code. §4; 30

+

+

+Attempts to obtain locale information from the expansion of \TrackLangEnv. §3; 27

+

\TrackLangProvidePredefinedDialect{dialect label}{root language label}{3166-1 code}{modifier}{variant}{map}{script}tracklang.tex v1.4+
+

+Defines a predefined dialect label that can be used by \TrackPredefinedDialect. §6.6; 76

+

+

+Sets up a language label for use with \TrackPredefinedDialect. §6.6; 76

+

\TrackLangProvidesResource{tag}{version info}tracklang.tex v1.3+
+

+Analogous to \ProvidesFile. §5; 52

+

+

+Attempts to obtain locale information from the LC_ALL environment variable via the shell escape or, with LuaTeX, \directlua. §3; 26

+

+

+Attempts to obtain locale information from the LC_ALL environment variable and then by the env-name environment variable via the shell escape or, with LuaTeX, \directlua. §3; 26

+

\TrackLangRedefHook{code}{type}tracklang.tex v1.4+
+

+Similar to \TrackLangAddToHook but redefines the hook rather than appending to it. §5; 55

+

\TrackLangRegionMap{numeric}{alpha-2}{alpha-3}tracklang-region-codes.tex v1.3+
+

+Establishes a mapping between a numeric region code and alpha-2 and alpha-3 codes. §4; 31

+

\TrackLangRequestResource{tag}{not found code}tracklang.tex v1.3+
+

+As \TrackLangRequireResource but does not found code if the file doesn’t exist. §5; 53

+

\TrackLangRequireDialect[load code]{pkgname}{dialect}tracklang.tex v1.3+
+

+Loads the dialect for the given package. §5; 45

+

+

+Defined by \TrackLangRequireDialect. §5; 45

+

+

+Loads the appropriate ldf file if it hasn’t already been loaded. §5; 53

+

\TrackLangRequireResourceOrDo{tag}{code1}{code2}tracklang.tex v1.3+
+

+As \TrackLangRequireResource but does code1 if the file is now loaded or code2 if the file has already been loaded. §5; 53

+

+

+Expands to the direction associated with the given alpha script code. §4; 33

+

+

+Expands to the name associated with the given alpha script code. §4; 32

+

+

+Expands to the numeric script code corresponding to the given alpha code. §4; 32

+

+

+Set by \TrackLangScriptMap to the associated alpha code Code. §4; 32

+

+

+Expands to the parent of the given alpha script code. §4; 33

+

\TrackLangScriptIfHasParent{alpha code}{true}{false}tracklang-scripts.tex v1.3+
+

+Expands to true if the given alpha script code has a parent otherwise expands to false. §4; 33

+

\TrackLangScriptIfKnownAlpha{alpha code}{true}{false}tracklang-scripts.tex v1.3+
+

+Expands to true if there’s a known mapping for the given alpha script code otherwise expands to false. §4; 32

+

\TrackLangScriptIfKnownNumeric{numeric code}{true}{false}tracklang-scripts.tex v1.3+
+

+Expands to true if there’s a known mapping for the given numeric script code otherwise expands to false. §4; 32

+

\TrackLangScriptMap{letter code}{numeric code}{script name}{direction}{parent script}tracklang-scripts.tex v1.3+
+

+Defines a mapping between an alpha code and a numeric code. §4; 32

+

+

+Expands to the alpha script code corresponding to the given numeric code. §4; 32

+

\TrackLangScriptSetParent{alpha code}{parent alpha code}tracklang-scripts.tex v1.3+
+

+Sets the parent for the given alpha script code. §4; 33

+

+

+Sets \ifTrackLangShowWarnings to false. §3; 24

+

+

+Sets \ifTrackLangShowWarnings to true. §3; 24

+

+

+Parse tag, which should be a regular, well-formed RFC 5646 language tag (not an irregular grandfather tag) and track the dialect. §3; 21

+

\TrackLocale{locale}tracklang.tex v1.3+
+

+Tracks the dialect identified by the given locale, which may either be a predefined language/dialect or in the same format as \TrackLangEnv. §3; 20

+

\TrackPredefinedDialect{dialect label}tracklang.tex v1.0+
+

+Tracks a predefined language or dialect. §3; 19

+

+

+Expands to 3166-1 (should not be redefined). §5; 40

+

+

+Expands to 639-1 (should not be redefined). §5; 40

+

+ +

+ +
+

Index

+
Symbols @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
+ +
+ +
+

Symbols

+
_ (separator)20, 24, 25, 7880
+
. (code-set)20, 2478
+
\\ (escaped backslash)25
+
$ (environment variable)25
+
- (separator)2025
+
--shell-escape2324
+ +
+ +
+

@

+
@ (catcode 11)19
+
@ (modifier)2078
+
\@for3794
+
\@nil37
+ + + + +
+ +
+

A

+
aa (ISO code)
see afar
+
+
ab (ISO code)
see abkhaz
+
+ + + + + + + + + + +
ae (ISO code) +
+ +
af (ISO code) +
+ + + + + + + +
ak (ISO code)
see akan
+
+ + + +
alien.sty7981
+
alien package +
+ +
am (ISO code) +
+ + +
an (ISO code) +
+
ang (ISO code) +
+ +
animals.sty55
+ + +
apa (ISO code)
see apache
+
+ + + +
ar (ISO code)
see arabic
+
+ + + + + + + + + +
as (ISO code) +
+ +
ast (ISO code) +
+ + +
\AtBeginDocument37
+ + + +
av (ISO code)
see avaric
+
+ + + + + +
ay (ISO code)
see aymara
+
+ + +
az (ISO code) +
+ + +
+ +
+

B

+ +
ba (ISO code) +
+
babel packagea, 2, 3, 9, 12, 13, 35, 53, 54, 58, 59, 6870, 7794
+
\babelprovide213
+ + + + + + + + + + + +
\bbl@loaded235
+
BCP 4735
+ + +
be (ISO code) +
+ + + + + +
ber (ISO code)
see berber
+
+ + + +
bg (ISO code) +
+ +
bh (ISO code)
see bihari
+
+ +
bi (ISO code) +
+ + + + + + +
bm (ISO code) +
+ +
bn (ISO code) +
+ +
bo (ISO code) +
+ + + + + + +
br (ISO code)
see breton
+
+ + + + + + + +
bs (ISO code) +
+ + + + + + + + + + +
+ +
+

C

+ +
ca (ISO code) +
+ + + + +
\captionsdialectTable 1.3; 12, 13, 15, 53, 54, 59, 61, 68, 70, 73, 77, 80, 81101
+ + + + +
ce (ISO code) +
+ + + +
ch (ISO code) +
+ + + + + + + + + + + + + +
CLI93
+ + + +
co (ISO code) +
+
code-set20, 26104
+ +
cop (ISO code)
see coptic
+
+ + + + + + + +
cr (ISO code)
see cree
+
+ + + +
cs (ISO code)
see czech
+
+ +
cu (ISO code) +
+ + + + + + + + + + + + + +
cv (ISO code) +
+ + + + +
cy (ISO code)
see welsh
+
+ + + + + + +
+ +
+

D

+
da (ISO code)
see danish
+
+ +
\datedialectTable 1.3; 1555
+
datetime2 package921
+ + + + + + + + +
de (ISO code)
see german
+
+
\DeclareOption1319
+ + +
\directluaa, 23109
+ + + + + + +
dsb (ISO code) +
+ + + +
dv (ISO code)
see divehi
+
+ +
dz (ISO code) +
+ + +
+ +
+

E

+ + + + +
ee (ISO code)
see ewe
+
+ + + + + +
el (ISO code)
see greek
+
+ + + + + + + + + + + + +
en (ISO code) +
+ +
environment variables
+
LANGa, 232680
+
LC_ALLa, 23, 26, 104109
+
LC_MONETARY26
+
eo (ISO code) +
+ + + + + + + + + + + + + + + + + + + + + + +
es (ISO code) +
+ + + +
et (ISO code) +
+
etex (application)23
+ +
etoolbox package54
+
eu (ISO code)
see basque
+
+ + +
+ +
+

F

+
fa (ISO code)
see farsi
+
+ + +
ff (ISO code)
see fula
+
+ +
fi (ISO code) +
+ +
file formats
+
ldf13, 15, 4562
+
log93
+
tex9
+ + +
fj (ISO code)
see fijian
+
+ + + + +
fo (ISO code) +
+ + + + + + + + + +
fr (ISO code)
see french
+
+ + + + + + + + +
fur (ISO code) +
+ +
fy (ISO code) +
+ +
+ +
+

G

+ + + +
ga (ISO code)
see irish
+
+ + + + + + + + + + + +
gd (ISO code) +
+ + + + + +
german package2, 335
+ + + + + + + + + + + + + + +
gl (ISO code) +
+ +
glossaries package29
+ + +
gn (ISO code) +
+ + + + + + + + + + +
gu (ISO code) +
+ + + + + + + +
gv (ISO code)
see manx
+
+ + + +
+ +
+

H

+
ha (ISO code)
see hausa
+
+ + + + + + + + + +
he (ISO code)
see hebrew
+
+ + + +
hi (ISO code)
see hindi
+
+ + + + + + + + +
ho (ISO code) +
+ + + +
hr (ISO code) +
+ +
hsb (ISO code) +
+ +
ht (ISO code) +
+ + +
hu (ISO code)
see magyar
+
+ + +
hy (ISO code) +
+
hz (ISO code)
see herero
+
+ +
+ +
+

I

+
ia (ISO code) +
+ + + +
id (ISO code) +
+ + +
ie (ISO code) +
+ + + + + + + + + + + + + + + + +
ig (ISO code)
see igbo
+
+ +
ii (ISO code)
see nuosu
+
+
ik (ISO code) +
+ + + + + + +
\input911, 13, 17, 19, 25, 71, 7281
+ + + + + +
io (ISO code)
see ido
+
+ + + + +
is (ISO code) +
+ +
ISO (International Organization for Standardization)Table 1.1; b, 1539
+
ISO 1592431, 42, 43, 72, 7678
+
ISO 3166-120, 22, 35, 39, 40, 46, 72, 7476, 94, 97, 105, 106113
+
ISO 639-120, 22, 34, 39, 40, 46, 50, 51, 61, 72, 74, 75, 81, 95, 96, 105, 107113
+
ISO 639-220, 34, 40, 46, 50, 51, 61, 74, 75, 81, 95, 96, 102, 105107
+
ISO 639-2 (B)21, 35, 75, 105106
+
ISO 639-2 (T)21, 3575
+
ISO 639-322, 39, 40, 46, 47, 74, 75, 95, 96, 101, 105107
+ + + + + + + + + +
it (ISO code) +
+ + + +
iu (ISO code) +
+ +
+ +
+

J

+
ja (ISO code) +
+ + + + + + + + + + + + +
jv (ISO code) +
+ +
+ +
+

K

+
ka (ISO code) +
+ + + + + + + + + +
kg (ISO code)
see kongo
+
+ + + + + + +
ki (ISO code)
see kikuyu
+
+ + + + + +
kj (ISO code) +
+
kk (ISO code)
see kazakh
+
+
kl (ISO code) +
+ +
km (ISO code)
see khmer
+
+ +
kn (ISO code) +
+ +
ko (ISO code)
see korean
+
+ + + + + + +
kpsewhich (application)
+ +
kr (ISO code)
see kanuri
+
+
ks (ISO code) +
+ +
ku (ISO code) +
+ + +
kv (ISO code)
see komi
+
+ +
kw (ISO code) +
+ + +
ky (ISO code)
see kyrgyz
+
+ + + +
+ +
+

L

+ +
la (ISO code)
see latin
+
+ +
\languagename1074
+ + + + + + + + + +
lb (ISO code) +
+ + + +
lg (ISO code)
see ganda
+
+ +
li (ISO code) +
+ + + + + + + + +
ln (ISO code) +
+
lo (ISO code)
see lao
+
+ + + + + + +
lt (ISO code) +
+ +
lu (ISO code) +
+ + + +
lv (ISO code) +
+ + + + +
+ +
+

M

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mg (ISO code) +
+ +
mh (ISO code) +
+
mi (ISO code)
see maori
+
+ +
mk (ISO code) +
+ +
ml (ISO code) +
+ + + +
mn (ISO code) +
+ + +
modifier20, 26, 34, 36, 41, 76, 78104
+ + + + + + +
mr (ISO code) +
+ + + +
ms (ISO code) +
+ + +
mt (ISO code) +
+ + + + + + + +
my (ISO code) +
+ + + +
+ +
+

N

+ +
na (ISO code) +
+ + + + +
nb (ISO code)
see bokmal
+
+ + + +
nd (ISO code) +
+ + +
ne (ISO code)
see nepali
+
+ + + + + + +
ng (ISO code)
see ndonga
+
+ +
ngerman package2, 3, 3554
+ + + + + + + + + + + +
nl (ISO code)
see dutch
+
+
nn (ISO code) +
+ +
no (ISO code)
see norsk
+
+ + + + + +
nqo (ISO code)
see nko
+
+ +
nr (ISO code) +
+ +
nso (ISO code) +
+ + + +
nv (ISO code)
see navajo
+
+
ny (ISO code) +
+ + + +
+ +
+

O

+
oc (ISO code) +
+ + +
oj (ISO code)
see ojibwe
+
+ + + +
om (ISO code)
see oromo
+
+
or (ISO code)
see oriya
+
+ + + + +
os (ISO code) +
+ + + + +
+ +
+

P

+ +
pa (ISO code) +
+ + + + + + +
pdflatex (application)24
+ + + + + + + + + + + + +
pi (ISO code)
see pali
+
+ + + + + +
pl (ISO code)
see polish
+
+ + +
pms (ISO code) +
+ + + + +
polyglossia packagea, 2, 3, 9, 1113, 35, 44, 53, 58, 6194
+ + + +
POSIX (Portable Operating System Interface)23, 4078
+ +
prefix-localeid.ldf15, 16, 4953, 55, 5766, 6880
+
\ProvidesFile52109
+ + +
ps (ISO code)
see pashto
+
+ + + +
pt (ISO code) +
+ + + + +
+ +
+

Q

+ + + + +
qu (ISO code) +
+ + +
+ +
+

R

+ +
region +
+
regions.sty6162
+
\RequirePackage13, 1771
+ + +
rm (ISO code) +
+
rn (ISO code) +
+ +
ro (ISO code) +
+ + + + + + + +
ru (ISO code) +
+ + + + + +
rw (ISO code) +
+ +
+ +
+

S

+ +
sa (ISO code) +
+ + + + + + + + + + + + +
sc (ISO code) +
+ +
script10, 11, 13, 15, 16, 21, 36, 43, 47, 50, 5161
+ +
sd (ISO code)
see sindhi
+
+ +
se (ISO code)
see samin
+
+
\selectlanguage1772
+ + + + + + + + + + + +
sg (ISO code)
see sango
+
+ + + +
shell escapea, 10, 2225, 27, 93109
+
shellesc package93
+ + + +
si (ISO code) +
+ + + + + + + +
sk (ISO code)
see slovak
+
+ + +
sl (ISO code) +
+ + + + + + + +
sm (ISO code)
see samoan
+
+ +
sn (ISO code)
see shona
+
+ +
so (ISO code)
see somali
+
+ + + + + + +
sq (ISO code) +
+ +
sr (ISO code) +
+ +
ss (ISO code)
see swati
+
+ +
st (ISO code) +
+
su (ISO code) +
+ + + +
sv (ISO code) +
+
sw (ISO code) +
+ + + + + + + + + + +
syr (ISO code)
see syriac
+
+ + + + + + + +
+ +
+

T

+
ta (ISO code)
see tamil
+
+ + + + + + + + + + + + + + + +
te (ISO code)
see telugu
+
+ + + +
territory20, 26, 30, 31, 35, 36, 50, 61, 104, 106, 107109
+
tex (application)25
+
texosquery.cfga
+
texosquery.tex910
+
texosquery (application)a10
+
texosquery package10, 22, 2326
+
\TeXOSQueryLangTag10, 1422
+
\TeXOSQueryLocale2326
+ + + +
tg (ISO code)
see tajik
+
+ + +
th (ISO code)
see thai
+
+ + + + + +
ti (ISO code) +
+ + + + + + +
tk (ISO code) +
+ +
tl (ISO code) +
+ + +
tn (ISO code)
see tswana
+
+ +
to (ISO code)
see tonga
+
+ + +
tr (ISO code) +
+ + + + + + +
tracklang.sty +
+
tracklang.texa, 9, 10, 13, 19, 30, 72, 94110, 112113
+ +
tracklang-scripts.sty +
+ +
tracklang-scripts package11, 31, 4373
+
tracklang packagea, 9, 19, 30, 35, 7194
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
\trans@languages35
+
translator package2, 335
+
ts (ISO code)
see tsonga
+
+ + + +
tt (ISO code)
see tatar
+
+ + + + +
tw (ISO code)
see twi
+
+ + + +
ty (ISO code) +
+ + +
+ +
+

U

+ + +
ug (ISO code)
see uyghur
+
+ +
uk (ISO code) +
+ + + + + +
und (ISO code) +
+ + +
ur (ISO code)
see urdu
+
+ + + + + + + + +
uz (ISO code)
see uzbek
+
+ + +
+ +
+

V

+ + + + +
variant10, 15, 20, 36, 47, 50, 7678
+ + + +
ve (ISO code)
see venda
+
+ + + + +
vi (ISO code) +
+ + + +
vo (ISO code) +
+ + + +
+ +
+

W

+
wa (ISO code) +
+ + + + + +
wo (ISO code)
see wolof
+
+ + + + +
+ +
+

X

+
xh (ISO code)
see xhosa
+
+ + +
\xpg@bcp@loaded2, 1135
+
\xpg@loaded35
+ + +
+ +
+

Y

+ +
yi (ISO code) +
+ + +
yo (ISO code)
see yoruba
+
+ + + +
+ +
+

Z

+ +
za (ISO code)
see zhuang
+
+
zh (ISO code) +
+ + + + + + +
zu (ISO code)
see zulu
+
+ + + + + +

+ +

+


+1Thass Broad Norfolk, my bewties :-P

+ + diff --git a/macros/generic/tracklang/tracklang-manual.pdf b/macros/generic/tracklang/tracklang-manual.pdf new file mode 100644 index 0000000000..0677e13b85 Binary files /dev/null and b/macros/generic/tracklang/tracklang-manual.pdf differ diff --git a/macros/generic/tracklang/tracklang-manual.tex b/macros/generic/tracklang/tracklang-manual.tex new file mode 100644 index 0000000000..a141ea906b --- /dev/null +++ b/macros/generic/tracklang/tracklang-manual.tex @@ -0,0 +1,5641 @@ +% arara: lualatex +% arara: bib2gls: { group: on, options: [ "--replace-quotes" ] } +% arara: lualatex +% arara: bib2gls: { group: on, options: [ "--replace-quotes" ] } if found ("log", "Glossary entry `sym.") +% arara: lualatex +% arara: lualatex if found ("log", "Rerun to") + +% This document requires glossaries v4.51, glossaries-extra v1.50 +% and nlctuserguide.sty v1.09. If they haven't already +% been uploaded to CTAN, they will be in a few days. + +\documentclass[titlepage=false,oneside, + fontsize=12pt,captions=tableheading]{scrbook} + +\usepackage + [ + floats, + %debug=showwrgloss + ] + {nlctuserguide} + +\usepackage{glossary-table} + +\glsxtrnewgls{opt.envvar.}{\envvar} +\defsemanticcmd[style2]{\envvarfmt}{\texttt}{} +\defsemanticcmd[style1]{\langtagfmt}{\texttt}{} + +\glsaddstoragekey{dialect}{}{\dialect} +\glsaddstoragekey{isotag}{}{\isotag} +\glsaddstoragekey{langtag}{}{\langtag} +\glsxtrprovidestoragekey{tags}{}{} +\glsxtrprovidestoragekey{region}{}{} +\glsaddstoragekey{numeric}{}{\numerictag} +\glsxtrprovidestoragekey{alpha3}{}{} + +\newcommand{\optisotag}[1]{\isotag{opt.#1}} +\newcommand{\iso}[1]{\glslink{opt.#1}{\optfmt{\optisotag{#1}}}} +\newcommand{\numericcode}[1]{\glslink{opt.#1}{\glsxtrusefield{opt.#1}{numeric}}} + +\newcommand{\tklscript}[1]{\glslink{TrackLangScriptCode}{\csfmt{TrackLangScript#1}}} +\newcommand{\tklcaptions}[1]{\glslink{captionsdialect}{\csfmt{captions#1}}} +\newcommand{\tkldate}[1]{\glslink{datedialect}{\csfmt{date#1}}} + +\newcommand{\ldf}[2]{% + \glslink{file.prefix-localeid.ldf}{\filefmt{#1\dhyphen #2.ldf}}} +\newcommand{\localefile}[1]{% + \glslink{file.prefix-localeid.ldf}{\metafilefmt{#1\dhyphen}{localeid}{.ldf}}} +\newcommand{\localemetafile}[1]{% + \glslink{file.prefix-localeid.ldf}{\metametafilefmt{}{#1}{\dhyphen}{localeid}{.ldf}}} +\newcommand{\localemetametafile}[2]{% + \glslink{file.prefix-localeid.ldf}{\metametafilefmt{}{#1}{\dhyphen}{#2}{.ldf}}} + +\newcommand{\fnregion}{\fnsym*{2}} + +\renewcommand{\filetag}[1]{} + +\renewcommand{\nlctuserguidecustomentryaliases}{% + isolangregion=index, + rootlang=index, + noniso=index, + isocode=index, + region=index, + script=index +} + +\nlctuserguidegls[selection=all] +{ + \def\genvvar#1#2{% + \glsbibwriteentry{option}{opt.envvar.#1}{% + \field{name}{\envvarfmt{#1}}\parent{idx.envvar}#2}}% + \gidxpl{envvar}{\field{text}{environment variable}} + % predefined ISO language-region tags + % \gisolangtag{xx}{XX}{dialect}{options} + \def\gisolangtag#1#2#3#4{% + \glsbibwriteentry{isolangregion}{opt.#1-#2}{% + \name{\optfmt{#1-#2}}% + \field{langtag}{#1}\field{region}{#2}% + \field{isotag}{#1-#2}% + \field{dialect}{#3}#4}% + }% + % \gisolangtagwithvar{xx}{XX}{variant}{dialect}{options} + \def\gisolangtagwithvar#1#2#3#4#5{% + \glsbibwriteentry{isolangregion}{opt.#1-#2-#3}{% + \name{\optfmt{#1-#2-#3}}% + \field{langtag}{#1}\field{region}{#2}% + \field{isotag}{#1-#2-#3}% + \field{dialect}{#4}#5}% + }% + % predefined root language labels + % \grootlangtag{language}{iso tag}{options} + \def\grootlangtag#1#2#3{% + \glsbibwriteentry{rootlang}{opt.#1}{% + \name{\optfmt{#1}}% + \field{dialect}{#1}% + \field{langtag}{#2}% + \field{isotag}{#2}#3}% + \glsbibwriteentry{isocode}{opt.#2}{\name{\optfmt{#2}}\field{alias}{opt.#1}}% + }% + % \grootlangsametag{language}{options} + \def\grootlangsametag#1#2{% + \glsbibwriteentry{rootlang}{opt.#1}{% + \name{\optfmt{#1}}% + \field{dialect}{#1}% + \field{langtag}{#1}% + \field{isotag}{#1}#2}% + }% + % \grootlangtagwithreg{language}{lang}{region}{options} + \def\grootlangtagwithreg#1#2#3#4{% + \glsbibwriteentry{rootlang}{opt.#1}{% + \field{name}{\optfmt{#1}\fnregion} + \field{text}{\optfmt{#1}} + \field{region}{#3} + \field{dialect}{#1}% + \field{langtag}{#2} + \field{isotag}{#2-#3}#4}% + \glsbibwriteentry{isocode}{opt.#2}{\name{\optfmt{#2}}\field{alias}{opt.#1}}% + } + % predefined non-iso dialects + % \gdialecttag{dialect}{tag}{options} + \def\gdialecttag#1#2#3{% + \glsbibwriteentry{noniso}{opt.#1}{% + \name{\optfmt{#1}}% + \field{dialect}{#1}% + \field{isotag}{\optisotag{#2}}% + \field{tags}{\optfmt{\optisotag{#2}}}#3}% + }% + % \gdialecttagsuppl{dialect}{tag}{suppl}{options} + \def\gdialecttagsuppl#1#2#3#4{% + \glsbibwriteentry{noniso}{opt.#1}{% + \name{\optfmt{#1}}% + \field{dialect}{#1}% + \field{isotag}{\optisotag{#2}-#3}% + \field{tags}{\optfmt{\optisotag{#2}-#3}}#4}% + }% + % \gdialecttagwithmap{dialect}{tag}{mapped}{options} + \def\gdialecttagwithmap#1#2#3#4{% + \glsbibwriteentry{noniso}{opt.#1}{% + \field{dialect}{#1}% + \field{isotag}{\optisotag{#2}}% + \field{tags}{\optfmt{\optisotag{#2}} / \optfmt{#3}}#4}% + }% + % \gdialecttagsupplwithmap{dialect}{tag}{suppl}{mapped}{options} + \def\gdialecttagsupplwithmap#1#2#3#4#5{% + \glsbibwriteentry{noniso}{opt.#1}{% + \name{\optfmt{#1}}% + \field{dialect}{#1}% + \field{isotag}{\optisotag{#2}-#3}% + \field{tags}{\optfmt{\optisotag{#2}-#3} / \opt{#4}}#5}% + }% + % \gdialecttagwithreg{dialect}{lang}{region}{options} + \def\gdialecttagwithreg#1#2#3#4{% + \glsbibwriteentry{noniso}{opt.#1}{% + \field{name}{\optfmt{#1}\fnregion } + \field{text}{\optfmt{#1}} + \field{region}{#3} + \field{dialect}{#1}% + \field{isotag}{\langtag{opt.#2}-#3}% + \field{tags}{\optfmt{\langtag{opt.#2}-#3}}#4 + }% + }% + % \gdialecttagwithmapandreg{dialect}{tag}{region}{mapped}{options} + \def\gdialecttagwithmapandreg#1#2#3#4#5{% + \glsbibwriteentry{noniso}{opt.#1}{% + \field{name}{\optfmt{#1}\fnregion } + \field{text}{\optfmt{#1}} + \field{region}{#3} + \field{dialect}{#1}% + \field{isotag}{\optisotag{#2}-#3}% + \field{tags}{\optfmt{\langtag{opt.#2}-#3} / \opt{#4}}#5}% + }% + % \gregion{numeric}{2-alpha}{3-alpha}{options} + \def\gregion#1#2#3#4{% + \glsbibwriteentry{region}{opt.#2}{% + \field{name}{\optfmt{#2}} + \field{numeric}{#1}\field{alpha3}{#3} + #4}% + }% + % \gscript{alpha}{numeric}{name}{direction}{parent}{options} + \def\gscript#1#2#3#4#5#6{% + \glsbibwriteentry{script}{opt.#1}{% + \field{name}{\optfmt{#1}} + \field{numeric}{#2}\field{user2}{#4}\field{description}{#3} + #6}% + }% + % COMMANDS + % \AnyTrackedLanguages + \gcmd{Any\-Track\-ed\-Lan\-guages} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{true}\margm{false}} + \desc{expands to \meta{true} if there are any tracked languages, + otherwise expands to \meta{false}} + } + % \IfTrackedLanguage + \gcmd{If\-Track\-ed\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{language-label}\margm{true}\margm{false}} + \desc{does \meta{true} if the language identified by + \meta{language-label} has been tracked, + otherwise does \meta{false}} + } + % \IfTrackedDialect + \gcmd{If\-Track\-ed\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{dialect-label}\margm{true}\margm{false}} + \desc{does \meta{true} if the dialect identified by + \meta{dialect-label} has been tracked, + otherwise does \meta{false}} + } + % \IfTrackedLanguageFileExists + \gcmd{If\-Track\-ed\-Lan\-guage\-File\-Exists} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{dialect}\margm{prefix}\margm{suffix}\margm{true +code}\margm{false code}} + \desc{does \code{\gls{SetCurrentTrackedDialect}\margm{dialect}} + and if the dialect is recognised, then determines if the file + \filefmt{\meta{prefix}\meta{tag}\meta{suffix}} exists. If it does, + \gls{CurrentTrackedTag} is set to \meta{tag} and \meta{true} is + done, otherwise \meta{false} is done} + } + % \CurrentTrackedTag + \gcmd{Current\-Track\-ed\-Tag} + { + \providedby{\file{tracklang.tex} v1.0+} + \desc{expands to the current tracked tag} + } + % \ifTrackLangShowWarnings + \gcond{if\-Track\-Lang\-Show\-Warnings} + { + \initval{\cmd{iftrue}} + \providedby{\file{tracklang.tex} v1.3+} + \desc{conditional that indicates whether or not to show warnings} + } + % \TrackLangShowWarningsfalse + \gcmd{Track\-Lang\-Show\-Warnings\-false} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{sets \gls{ifTrackLangShowWarnings} to false} + } + % \TrackLangShowWarningstrue + \gcmd{Track\-Lang\-Show\-Warnings\-true} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{sets \gls{ifTrackLangShowWarnings} to true} + } + % \ifTrackLangShowInfo + \gcond{if\-Track\-Lang\-Show\-Info} + { + \initval{\cmd{iftrue}} + \providedby{\file{tracklang.tex} v1.3+} + \desc{conditional that indicates whether or not to show +information messages} + } + % \ifTrackLangShowVerbose + \gcond{if\-Track\-Lang\-Show\-Verbose} + { + \initval{\cmd{iffalse}} + \providedby{\file{tracklang.tex} v1.4+} + \desc{conditional that indicates whether or not to show +verbose messages} + } + % \TrackLangQueryEnv + \gcmd{Track\-Lang\-Query\-Env} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{attempts to obtain locale information from the + \envvar{LCALL} environment variable via the \idx{shellescape} + or, with \LuaTeX, \gls{directlua}} + } + % \TrackLangQueryOtherEnv + \gcmd{Track\-Lang\-Query\-Other\-Env} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{env-name}} + \desc{attempts to obtain locale information from the + \envvar{LCALL} environment variable and then by the + \meta{env-name} environment variable via the \idx{shellescape} + or, with \LuaTeX, \gls{directlua}} + } + % \TrackLangParseFromEnv + \gcmd{Track\-Lang\-Parse\-From\-Env} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{attempts to obtain locale information from the + expansion of \gls{TrackLangEnv}} + } + % \TrackLangEnv + \gcmd{Track\-Lang\-Env} + { + \note{user defined} + \desc{may be defined using the same format as \envvar{LCALL} + before using \gls{TrackLangParseFromEnv} to skip the environment + variable query} + } + % \TrackLangEnvLang + \gcmd{Track\-Lang\-Env\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{set by \gls{TrackLangParseFromEnv} to the language code} + } + % \TrackLangEnvTerritory + \gcmd{Track\-Lang\-Env\-Territory} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{set by \gls{TrackLangParseFromEnv} to the \idx{territory}} + } + % \TrackLangEnvCodeSet + \gcmd{Track\-Lang\-Env\-Code\-Set} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{set by \gls{TrackLangParseFromEnv} to the \idx{code-set}} + } + % \TrackLangEnvModifier + \gcmd{Track\-Lang\-Env\-Modifier} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{set by \gls{TrackLangParseFromEnv} to the \idx{modifier}} + } + % \ForEachTrackedLanguage + \gcmd{For\-Each\-Track\-ed\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{cs}\margm{body}} + \desc{iterates through the list of tracked languages. On each + iteration \meta{cs} is set to the language tag and \meta{body} is + performed} + } + % \ForEachTrackedDialect + \gcmd{For\-Each\-Track\-ed\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{cs}\margm{body}} + \desc{iterates through the list of tracked dialects. On each + iteration \meta{cs} is set to the dialect tag and \meta{body} is + performed} + } + % \TrackLangNewLanguage + \gcmd{Track\-Lang\-New\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language label}\margm{639-1 code}\margm{639-2 (T)}% + \margm{639-2 (B)}\margm{639-3}\margm{3166-1}\margm{default script}} + \desc{identifies a new language that may be tracked. Apart from + \meta{language label}, the other arguments may be empty if + the information is unavailable} + } + % \TrackLangIfKnownLang + \gcmd{Track\-Lang\-If\-Known\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}\margm{true}\margm{false}} + \desc{does \meta{true} if \meta{language} is known + (but not necessarily tracked), otherwise does \meta{false}} + } + % \TrackLangIfKnownIsoTwoLetterLang + \gcmd{Track\-Lang\-If\-Known\-Iso\-Two\-Letter\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}\margm{true}\margm{false}} + \desc{does \meta{true} if \meta{language} has an \idxn{639-1} code + (but is not necessarily tracked), otherwise does \meta{false}} + } + % \TrackLangGetKnownIsoTwoLetterLang + \gcmd{Track\-Lang\-Get\-Known\-Iso\-Two\-Letter\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}} + \desc{expands to the \idxn{639-1} language code associated with + \meta{language}} + } + % \TrackLangIfKnownIsoThreeLetterLang + \gcmd{Track\-Lang\-If\-Known\-Iso\-Three\-Letter\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}\margm{true}\margm{false}} + \desc{does \meta{true} if \meta{language} has an \idxn{639-2} code + (but is not necessarily tracked), otherwise does \meta{false}} + } + % \TrackLangGetKnownIsoThreeLetterLang + \gcmd{Track\-Lang\-Get\-Known\-Iso\-Three\-Letter\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}} + \desc{expands to the \idxn{639-2} language code associated with + \meta{language}} + } + % \TrackLangIfKnownIsoThreeLetterLangB + \gcmd{Track\-Lang\-If\-Known\-Iso\-Three\-Letter\-LangB} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}\margm{true}\margm{false}} + \desc{does \meta{true} if \meta{language} has an \idxn{639-2B} code + (but is not necessarily tracked), otherwise does \meta{false}} + } + % \TrackLangGetKnownIsoThreeLetterLangB + \gcmd{Track\-Lang\-Get\-Known\-Iso\-Three\-Letter\-LangB} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}} + \desc{expands to the \idxn{639-2B} language code associated with + \meta{language}} + } + % \IfTrackedLanguageHasIsoCode + \gcmd{If\-Track\-ed\-Lan\-guage\-Has\-Iso\-Code} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{code type}\margm{label}\margm{true}\margm{false}} + \desc{does \meta{true} if the given language or dialect has a + corresponding \idx{ISO} code of the given type, otherwise does + \meta{false}} + } + % \IfTrackedIsoCode + \gcmd{If\-Track\-ed\-Iso\-Code} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{code type}\margm{code}\margm{true}\margm{false}} + \desc{does \meta{true} if the given \idx{ISO} code has been defined + otherwise does \meta{false}} + } + % \TrackLangIfKnownLangFromIso + \gcmd{Track\-Lang\-If\-Known\-Lang\-From\-Iso} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{ISO code}\margm{true}\margm{false}} + \desc{does \meta{true} if the given language code (\idx{639-1} or + \idx{639-2} or \idx{639-3}) is + recognised (but not necessarily tracked), otherwise does \meta{false}} + } + % \TrackLangGetKnownLangFromIso + \gcmd{Track\-Lang\-Get\-Known\-Lang\-From\-Iso} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{ISO code}} + \desc{expands to the root language label from the + given \idx{ISO} code (\idx{639-1} or \idx{639-2} or \idx{639-3})} + } + % \TrackLangIfHasKnownCountry + \gcmd{Track\-Lang\-If\-Has\-Known\-Coun\-try} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}\margm{true}\margm{false}} + \desc{does \meta{true} if the given language has an \idxn{3166-1} + country code (but is not necessarily tracked), otherwise does \meta{false}} + } + % \TrackLangGetKnownCountry + \gcmd{Track\-Lang\-Get\-Known\-Coun\-try} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}} + \desc{expands to the \idxn{3166-1} country code for the given language} + } + % \TrackLangGetDefaultScript + \gcmd{Track\-Lang\-Get\-Default\-Script} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}} + \desc{expands to the default script for the given language} + } + % \TrackLangIfHasDefaultScript + \gcmd{Track\-Lang\-If\-Has\-Default\-Script} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}\margm{true}\margm{false}} + \desc{does \meta{true} if the given language has a default + script (but is not necessarily tracked), otherwise does \meta{false}} + } + % \AddTrackedDialect + \gcmd{Add\-Track\-ed\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{dialect label}\margm{root language label}} + \desc{tracks a dialect. This command defines +\gls{TrackLangLastTrackedDialect} to provide a convenient way to +reference the last dialect to be tracked} + } + % \AddTrackedLanguage + \gcmd{Add\-Track\-ed\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{root language label}} + \desc{shortcut for \code{\gls{AddTrackedDialect}\margm{root language +label}\margm{root language label}}} + } + % \AddTrackedIsoLanguage + \gcmd{Add\-Track\-ed\-Iso\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{code type}\margm{code}\margm{language}} + \desc{adds a mapping between the given \idx{ISO} code and language name} + } + % \TrackedLanguageFromIsoCode + \gcmd{Tracked\-Lan\-guage\-From\-Iso\-Code} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{code type}\margm{code}} + \desc{expands to a comma-separated list of language or + dialect labels associated with the given code} + } + % \TrackedIsoCodeFromLanguage + \gcmd{Track\-ed\-Iso\-Code\-From\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{code type}\margm{label}} + \desc{expands to the code associated with the given language or +dialect identified by \meta{label}} + } + % \TrackedLanguageFromDialect + \gcmd{Track\-ed\-Lan\-guage\-From\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{dialect}} + \desc{expands to the language from the given dialect} + } + % \TrackedDialectsFromLanguage + \gcmd{Tracked\-Di\-alects\-From\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{root language label}} + \desc{expands to a comma-separated list of the tracked dialects with the given language} + } + % \TwoLetterIsoCountryCode + \gcmd{Two\-Letter\-Iso\-Coun\-try\-Code} + { + \providedby{\file{tracklang.tex} v1.0+} + \desc{expands to \idx{3166-1} (should not be redefined)} + } + % \TwoLetterIsoLanguageCode + \gcmd{Two\-Letter\-Iso\-Lan\-guage\-Code} + { + \providedby{\file{tracklang.tex} v1.0+} + \desc{expands to \idx{639-1} (should not be redefined)} + } + % \ThreeLetterIsoLanguageCode + \gcmd{Three\-Letter\-Iso\-Lan\-guage\-Code} + { + \providedby{\file{tracklang.tex} v1.0+} + \desc{expands to \idx{639-2} (should not be redefined)} + } + % \ThreeLetterExtIsoLanguageCode + \gcmd{Three\-Letter\-Ext\-Iso\-Lan\-guage\-Code} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{expands to \idx{639-3} (should not be redefined)} + } + % \SetTrackedDialectModifier + \gcmd{Set\-Track\-ed\-Di\-alect\-Mod\-i\-fier} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{value}} + \desc{sets the modifier for the given \meta{dialect} to +\meta{value}} + } + % \GetTrackedDialectModifier + \gcmd{Get\-Track\-ed\-Di\-alect\-Mod\-i\-fier} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{expands to the modifier for the given dialect} + } + % \IfHasTrackedDialectModifier + \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Mod\-i\-fier} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a modifier for the given +dialect, otherwise expands to \meta{false}} + } + % \SetTrackedDialectScript + \gcmd{Set\-Track\-ed\-Di\-alect\-Script} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{value}} + \desc{sets the script for \meta{dialect} to \meta{value}} + } + % \GetTrackedDialectScript + \gcmd{Get\-Track\-ed\-Di\-alect\-Script} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{expands to the script for \meta{dialect}} + } + % \IfHasTrackedDialectScript + \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Script} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a script for + \meta{dialect}, otherwise expands to \meta{false}} + } + % \IfTrackedDialectIsScriptCs + \gcmd{If\-Track\-ed\-Di\-alect\-Is\-Script\-Cs} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{cs}\margm{true}\margm{false}} + \desc{if the given tracked dialect has an associated script and that + script code matches the replacement text for the control sequence + \meta{cs} then do \meta{true} otherwise to \meta{false}. If the + tracked dialect doesn't have an associated script then the default + script for the root language is tested} + } + % \SetTrackedDialectVariant + \gcmd{Set\-Track\-ed\-Di\-alect\-Vari\-ant} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{value}} + \desc{sets the modifier for \meta{dialect} to \meta{value}} + } + % \GetTrackedDialectVariant + \gcmd{Get\-Track\-ed\-Di\-alect\-Vari\-ant} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{expands to the modifier for \meta{dialect}} + } + % \IfHasTrackedDialectVariant + \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Vari\-ant} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a modifier for + \meta{dialect}, otherwise expands to \meta{false}} + } + % \SetTrackedDialectSubLang + \gcmd{Set\-Track\-ed\-Di\-alect\-Sub\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{value}} + \desc{sets the sub-language for \meta{dialect} to \meta{value}} + } + % \GetTrackedDialectSubLang + \gcmd{Get\-Track\-ed\-Di\-alect\-Sub\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{expands to the sub-language for \meta{dialect}} + } + % \IfHasTrackedDialectSubLang + \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Sub\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a sub-language for + \meta{dialect}, otherwise expands to \meta{false}} + } + % \SetTrackedDialectAdditional + \gcmd{Set\-Track\-ed\-Di\-alect\-Ad\-di\-tional} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{value}} + \desc{sets the extra information for \meta{dialect} to \meta{value}} + } + % \GetTrackedDialectAdditional + \gcmd{Get\-Track\-ed\-Di\-alect\-Ad\-di\-tional} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{expands to the extra information for \meta{dialect}} + } + % \IfHasTrackedDialectAdditional + \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Ad\-di\-tional} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's extra information for + \meta{dialect}, otherwise expands to \meta{false}} + } + % \GetTrackedLanguageTag + \gcmd{Get\-Track\-ed\-Lan\-guage\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{gets the language tag for \meta{dialect}} + } + % \SetCurrentTrackedDialect + \gcmd{Set\-Current\-Track\-ed\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}} + \desc{sets the current tracked dialect} + } + % \CurrentTrackedDialect + \gcmd{Current\-Track\-ed\-Dialect} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + dialect label, which may be the supplied \meta{dialect} label + or the mapped label or, if \meta{dialect} is a root language label, + the last tracked dialect for the given root language} + } + % \CurrentTrackedLanguage + \gcmd{Current\-Track\-ed\-Language} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + associated root language label} + } + % \CurrentTrackedDialectModifier + \gcmd{Current\-Track\-ed\-Di\-alect\-Modifier} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + associated modifier (may be empty)} + } + % \CurrentTrackedDialectVariant + \gcmd{Current\-Track\-ed\-Di\-alect\-Variant} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + associated variant (may be empty)} + } + % \CurrentTrackedDialectScript + \gcmd{Current\-Track\-ed\-Di\-alect\-Script} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + script associated with the dialect, or to the default script for the language} + } + % \CurrentTrackedDialectSubLang + \gcmd{Current\-Track\-ed\-Di\-alect\-Sub\-Lang} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the sub + language associated with the dialect (may be empty)} + } + % \CurrentTrackedDialectAdditional + \gcmd{Current\-Track\-ed\-Di\-alect\-Ad\-di\-tional} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + additional part associated with the dialect (may be empty)} + } + % \CurrentTrackedLanguageTag + \gcmd{Current\-Track\-ed\-Lan\-guage\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the language + tag that identifies the dialect or \iso{undetermined} if no match} + } + % \CurrentTrackedRegion + \gcmd{Current\-Track\-ed\-Region} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + \idxn{3166-1} region code associated with the dialect (may be empty)} + } + % \CurrentTrackedIsoCode + \gcmd{Current\-Track\-ed\-Iso\-Code} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{SetCurrentTrackedDialect} to the + \idxn{639-1} or \idx{639-2} or \idx{639-3} language code (may be empty)} + } + % \AddTrackedLanguageIsoCodes + \gcmd{Add\-Track\-ed\-Lan\-guage\-Iso\-Codes} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{root language label}} + \desc{adds the \idxn{639-1}, \idx{639-2} and \idx{639-3} codes, which must have + previously been declared using \gls{TrackLangNewLanguage}} + } + % \AddTrackedCountryIsoCode + \gcmd{Add\-Track\-ed\-Coun\-try\-Iso\-Code} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language}} + \desc{adds the \idxn{3166-1} code} + } + % \GetTrackedDialectFromLanguageTag + \gcmd{Get\-Track\-ed\-Di\-alect\-From\-Lan\-guage\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{cs}} + \desc{finds the tracked dialect that matches the given language + tag and stores the dialect label in \meta{cs}. If no match found, + \meta{cs} will be empty} + } + % \TrackedDialectClosestSubMatch + \gcmd{Track\-ed\-Dialect\-Closest\-Sub\-Match} + { + \providedby{\file{tracklang.tex} v1.3.6+} + \desc{defined by \gls{GetTrackedDialectFromLanguageTag} to the + closest match} + } + % \TrackPredefinedDialect + \gcmd{Track\-Pre\-de\-fined\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\margm{dialect label}} + \desc{tracks a predefined language or dialect} + } + % \TrackLangIfAlphaNumericChar + \gcmd{Track\-Lang\-If\-Alpha\-Numeric\-Char} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{true}\margm{false}} + \desc{does \meta{true} if the argument is a single alphanumeric character + otherwise does \meta{false}} + } + % \TrackLangIfLanguageTag + \gcmd{Track\-Lang\-If\-Lan\-guage\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{true}\margm{false}} + \desc{does \meta{true} if the argument is a language tag + otherwise does \meta{false}} + } + % \TrackLangIfRegionTag + \gcmd{Track\-Lang\-If\-Region\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{true}\margm{false}} + \desc{does \meta{true} if the argument is a region tag + otherwise does \meta{false}} + } + % \TrackLangIfScriptTag + \gcmd{Track\-Lang\-If\-Script\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{true}\margm{false}} + \desc{does \meta{true} if the argument is a script tag + otherwise does \meta{false}} + } + % \TrackLangIfVariantTag + \gcmd{Track\-Lang\-If\-Vari\-ant\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{true}\margm{false}} + \desc{does \meta{true} if the argument is a variant tag + otherwise does \meta{false}} + } + % \TrackLanguageTag + \gcmd{Track\-Lan\-guage\-Tag} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}} + \desc{parse \meta{tag}, which should be a regular, well-formed + RFC 5646 language tag (not an irregular grandfather tag) and track the dialect} + } + % \TrackIfKnownLanguage + \gcmd{Track\-If\-Known\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.3.9+} + \syntax{\margm{tag}\margm{success code}\margm{fail code}} + \desc{as \gls{TrackLanguageTag} but does \meta{fail code} + if the tag doesn't contain a valid language code. If successful, does + \meta{success code} after tracking the language} + } + % \TrackLangAddExtraRegionFile + \gcmd{Track\-Lang\-Add\-Extra\-Region\-File} + { + \providedby{\file{tracklang.tex} v1.4+} + \syntax{\margm{file}} + \desc{adds \meta{file} to the list of extra region code files that should + be input by \file{tracklang-region-codes.tex}} + } + % \TrackLangAddExtraScriptFile + \gcmd{Track\-Lang\-Add\-Extra\-Script\-File} + { + \providedby{\file{tracklang.tex} v1.4+} + \syntax{\margm{file}} + \desc{adds \meta{file} to the list of files that should + be input by \file{tracklang-scripts.tex}} + } + % \TrackLangFromEnv + \gcmd{Track\-Lang\-From\-Env} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{queries environment variable if \gls{TrackLangEnv} not + already set, parses \gls{TrackLangEnv} if it has been set, and + adds the dialect if it's recognised} + } + % \TrackLocale + \gcmd{Track\-Locale} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{locale}} + \desc{tracks the dialect identified by the given \meta{locale}, which + may either be a predefined language\slash dialect or in the same format as + \gls{TrackLangEnv}} + } + % \TrackLangProvidePredefinedLanguage + \gcmd{Track\-Lang\-Provide\-Pre\-de\-fined\-Lan\-guage} + { + \providedby{\file{tracklang.tex} v1.4+} + \syntax{\margm{language label}} + \desc{sets up a language label for use with \gls{TrackPredefinedDialect}} + } + % \TrackLangDeclareLanguageOption + \gcmd{Track\-Lang\-Declare\-Lan\-guage\-Op\-tion} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{language name}\margm{639-1 code}\margm{639-2 (T)}\margm{639-2 +(B)}\margm{639-3}\margm{3166-1}\margm{default script}} + \desc{defines a new root language that's declared as an option} + } + % \TrackLangProvidePredefinedDialect + \gcmd{Track\-Lang\-Provide\-Pre\-de\-fined\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.4+} + \syntax{\margm{dialect label}\margm{root +language label}\margm{3166-1 code}\margm{modifier}\margm{variant}\margm{map}\margm{script}} + \desc{defines a predefined dialect label that can be used +by \gls{TrackPredefinedDialect}} + } + % \TrackLangDeclareDialectOption + \gcmd{Track\-Lang\-Declare\-Di\-alect\-Op\-tion} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{dialect}\margm{root +language}\margm{3166-1 +code}\margm{modifier}\margm{variant}\margm{map}\margm{script}} + \desc{defines a predefined dialect label that can be used +by \gls{TrackPredefinedDialect}} + } + % \TrackLangProvidesResource + \gcmd{Track\-Lang\-Provides\-Resource} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{version info}} + \desc{analogous to \gls{ProvidesFile}} + } + % \TrackLangAddToHook + \gcmd{Track\-Lang\-Add\-To\-Hook} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{code}\margm{type}} + \desc{for use within resource files, this can be used to add +\meta{code} to the appropriate hook} + } + % \TrackLangAddToCaptions + \gcmd{Track\-Lang\-Add\-To\-Captions} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{code}} + \desc{a shortcut that just does + \code{\gls{TrackLangAddToHook}\margm{code}\marg{captions}}} + } + % \TrackLangRedefHook + \gcmd{Track\-Lang\-Re\-def\-Hook} + { + \providedby{\file{tracklang.tex} v1.4+} + \syntax{\margm{code}\margm{type}} + \desc{similar to \gls{TrackLangAddToHook} but redefines the hook + rather than appending to it} + } + % \TrackLangRequireResource + \gcmd{Track\-Lang\-Require\-Resource} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}} + \desc{loads the appropriate \ext{ldf} file if it hasn't already +been loaded} + } + % \TrackLangRequireResourceOrDo + \gcmd{Track\-Lang\-Require\-Resource\-Or\-Do} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{code1}\margm{code2}} + \desc{as \gls{TrackLangRequireResource} but does \meta{code1} + if the file is now loaded or \meta{code2} + if the file has already been loaded} + } + % \TrackLangRequestResource + \gcmd{Track\-Lang\-Request\-Resource} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tag}\margm{not found code}} + \desc{as \gls{TrackLangRequireResource} but does \meta{not found code} +if the file doesn't exist} + } + % \TrackLangRequireDialect + \gcmd{Track\-Lang\-Require\-Di\-alect} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\oargm{load code}\margm{pkgname}\margm{dialect}} + \desc{loads the dialect for the given package} + } + % \TrackLangRequireDialectPrefix + \gcmd{Track\-Lang\-Require\-Di\-alect\-Prefix} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{defined by \gls{TrackLangRequireDialect}} + } + % \SetTrackedDialectLabelMap + \gcmd{Set\-Track\-ed\-Di\-alect\-Label\-Map} + { + \providedby{\file{tracklang.tex} v1.3+} + \syntax{\margm{tracklang-label}\margm{hook-label}} + \desc{defines a mapping between a \sty{tracklang} dialect label + and the corresponding dialect label used by a language hook, such as + \gls{captionsdialect}} + } + % \TrackLangLastTrackedDialect + \gcmd{Track\-Lang\-Last\-Track\-ed\-Dialect} + { + \providedby{\file{tracklang.tex} v1.3+} + \desc{expands to the label of the last tracked dialect} + } + % COMMANDS: INTERNAL + % \@tracklang@declareoption + \gcmd{@track\-lang\-@\-declare\-option} + { + \providedby{\sty{tracklang} v1.1+} + \syntax{\margm{dialect}} + \desc{provided by \file{tracklang.sty} to declare \meta{dialect} + as a package option that tracks \meta{dialect}. Provided by + \file{tracklang.tex}, if not already defined, to ignore its argument} + } + % \@tracklang@for + \gcmd{@track\-lang\-@\-for} + { + \providedby{\file{tracklang.tex} v1.0+} + \syntax{\meta{cs}:=\meta{list}\cmd{do}\margm{body}} + \desc{as \LaTeX's \gls{@for}} + } + % \@tracklang@prelangpkgcheck@hook + \gcmd{@track\-lang\-@\-pre\-lang\-pkg\-check\-@\-hook} + { + \desc{if defined before \file{tracklang.sty} v1.3.8+ is loaded, this + command will be done after package options have been processed but + before the check for language packages, such as \sty{babel} and + \sty{polyglossia}} + } + % COMMANDS: tracklang-region-codes.tex + % \TrackLangAlphaIIToNumericRegion + \gcmd{Track\-Lang\-Alpha\-II\-To\-Numeric\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{alpha-2 code}} + \desc{expands to the numeric code corresponding to the given +alpha-2 code} + } + % \TrackLangNumericToAlphaIIRegion + \gcmd{Track\-Lang\-Numeric\-To\-Alpha\-II\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{numeric code}} + \desc{expands to the alpha-2 code corresponding to the given +numeric code} + } + % \TrackLangIfKnownAlphaIIRegion + \gcmd{Track\-Lang\-If\-Known\-Alpha\-II\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{alpha-2 code}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a known mapping for the +given alpha-2 \idx{region} code, otherwise expands to \meta{false}} + } + % \TrackLangIfKnownNumericRegion + \gcmd{Track\-Lang\-If\-Known\-Numeric\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{numeric code}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a known mapping for the +given numeric \idx{region} code, otherwise expands to \meta{false}} + } + % \TrackLangAlphaIIIToNumericRegion + \gcmd{Track\-Lang\-Alpha\-III\-To\-Numeric\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{alpha-3 code}} + \desc{expands to the numeric code corresponding to the given +alpha-3 code} + } + % \TrackLangNumericToAlphaIIIRegion + \gcmd{Track\-Lang\-Numeric\-To\-Alpha\-III\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{numeric code}} + \desc{expands to the alpha-3 code corresponding to the given +numeric code} + } + % \TrackLangIfKnownAlphaIIIRegion + \gcmd{Track\-Lang\-If\-Known\-Alpha\-III\-Region} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{alpha-3 code}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a known mapping for the +given \meta{alpha-3 code}, otherwise expands to \meta{false}} + } + % \TrackLangRegionMap + \gcmd{Track\-Lang\-Region\-Map} + { + \providedby{\file{tracklang-region-codes.tex} v1.3+} + \syntax{\margm{numeric}\margm{alpha-2}\margm{alpha-3}} + \desc{establishes a mapping between a numeric \idx{region} code + and alpha-2 and alpha-3 codes} + } + % COMMANDS: tracklang-scripts.tex + % \TrackLangScriptMap + \gcmd{Track\-Lang\-Script\-Map} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{letter code}\margm{numeric code}\margm{script name}\margm{direction}\margm{parent script}} + \desc{defines a mapping between an alpha code and a numeric code} + } + % \TrackLangScriptAlphaToNumeric + \gcmd{Track\-Lang\-Script\-Alpha\-To\-Numeric} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}} + \desc{expands to the numeric script code corresponding to the given alpha code} + } + % \TrackLangScriptIfKnownAlpha + \gcmd{Track\-Lang\-Script\-If\-Known\-Alpha} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a known mapping for the + given alpha script code otherwise expands to \meta{false}} + } + % \TrackLangScriptNumericToAlpha + \gcmd{Track\-Lang\-Script\-Numeric\-To\-Alpha} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{numeric code}} + \desc{expands to the alpha script code corresponding to the + given numeric code} + } + % \TrackLangScriptIfKnownNumeric + \gcmd{Track\-Lang\-Script\-If\-Known\-Numeric} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{numeric code}\margm{true}\margm{false}} + \desc{expands to \meta{true} if there's a known mapping for the + given numeric script code otherwise expands to \meta{false}} + } + % \TrackLangScriptAlphaToName + \gcmd{Track\-Lang\-Script\-Alpha\-To\-Name} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}} + \desc{expands to the name associated with the given alpha script + code} + } + % \TrackLangScriptAlphaToDir + \gcmd{Track\-Lang\-Script\-Alpha\-To\-Dir} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}} + \desc{expands to the direction associated with the given alpha script + code} + } + % \TrackLangScriptSetParent + \gcmd{Track\-Lang\-Script\-Set\-Parent} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}\margm{parent alpha code}} + \desc{sets the parent for the given alpha script code} + } + % \TrackLangScriptGetParent + \gcmd{Track\-Lang\-Script\-Get\-Parent} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}} + \desc{expands to the parent of the given alpha script code} + } + % \TrackLangScriptIfHasParent + \gcmd{Track\-Lang\-Script\-If\-Has\-Parent} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \syntax{\margm{alpha code}\margm{true}\margm{false}} + \desc{expands to \meta{true} if the given alpha script code has + a parent otherwise expands to \meta{false}} + } + % \TrackLangScript + \gcmdmeta{Track\-Lang\-Script}{Code}{} + { + \providedby{\file{tracklang-scripts.tex} v1.3+} + \desc{set by \gls{TrackLangScriptMap} to the associated alpha code \meta{Code}} + } + % FILES + \gfile{track\-lang.tex}{}% tracklang.tex + \gfile{track\-lang.sty}% tracklang.sty + {\field{alias}{pkg.tracklang}}% + \gfile{track\-lang\dhyphen scripts.sty}% tracklang-scripts.sty + {\field{alias}{pkg.tracklang-scripts}}% + \gfile{tracklang\dhyphen region\dhyphen codes.tex}{}% tracklang-region-codes.tex + \gfile{tracklang\dhyphen scripts.tex}{}% tracklang-scripts.tex + \gfile{tex\-os\-query.tex}{}% texosquery.tex + \gfile{tex\-os\-query.cfg}{}% texosquery.cfg + \gfilemetameta{}{prefix}{\dhyphen}{localeid}{.ldf}{} % -.ldf + % FILE EXTENSIONS + \gext{tex}{}% .tex + \gext{ldf}{}% .ldf + \gext{log}{}% .log + % PACKAGES + \gpkg{track\-lang}{\common}% tracklang + \gpkg{track\-lang\dhyphen scripts}{}% tracklang-scripts + \gpkg{tex\-os\-query}{}% texosquery + \gpkg{poly\-glossia}{}% polyglossia.sty + \gpkg{babel}{}% babel.sty + \gpkg{translator}{}% translator.sty + \gpkg{shell\-esc}{}% shellesc.sty + \gpkg{ngerman}{}% ngerman.sty + \gpkg{german}{}% german.sty + \gpkg{glossaries}{}% glossaries.sty + \gpkg{etool\-box}{}% etoolbox.sty + \gpkg{date\-time2}{}% datetime2.sty + % Example packages + \gfile{animals.sty}{}% animals.sty + \gfile{regions.sty}{}% regions.sty + \gfile{alien.sty}{}% alien.sty + \gpkg{alien}{\field{alias}{file.alien.sty}} + % environment variables + \genvvar{LC\dsb ALL}{}% LC_ALL + \genvvar{LANG}{}% LANG + \genvvar{LC\dsb MONETARY}{}% LC_MONETARY + % TERMS + \gterm{shellescape} + { + \name{shell escape} + \desc{\TeX\ has the ability to run \idx{cli} applications while + it's typesetting a document. Whilst this is a convenient way + of using tools to help build the document, it's a security + risk. To help protect users from arbitrary\dash and + potentially dangerous\dash code from begin executed, \TeX\ has + a restricted mode, where only trusted applications are allowed to + run. This is usually the default mode, but your \TeX\ + installation may be set up so that the shell escape is disabled by + default. The unrestricted mode allows you to run any + application from the shell escape. Take care about + enabling this option. If you receive a document or package + from an untrusted source, first run \TeX\ with the shell escape + disabled or in restricted mode and search the \ext+{log} file for + \qt{runsystem} before using the unrestricted mode. Note that + \LuaLaTeX\ additionally requires the \sty{shellesc} package} + } + \gtermacr{cli}{CLI}{command-line interface}% + {% + \desc{an application that doesn't have a graphical user + interface. That is, an application that doesn't have any windows, + buttons or menus and can be run in + \dickimawhref{latex/novices/html/terminal.html}{a command + prompt or terminal}}% + }% + % INDEX ONLY + % COMMANDS - GENERAL + \gcmd{direct\-lua}{}% \directlua + \gcmd{babel\-provide}{}% \babelprovide + \gcmd{bbl\-@\-loaded}{}% \bbl@loaded + \gcmd{select\-language}{}% \selectlanguage + \gcmd{input}{}% \input + \gcmd{Require\-Package}{}% \RequirePackage + \gcmd{Declare\-Option}{}% \DeclareOption + \gcmdmeta{captions}{dialect}{}{}% \captions + \gcmdmeta{date}{dialect}{}{}% \date + \gcmd{Provides\-File}{}% \ProvidesFile + \gcmd{xpg\-@\-bcp\-@\-loaded}{}% \xpg@bcp@loaded + \gcmd{xpg\-@\-loaded}{}% \xpg@loaded + \gcmd{trans\-@\-languages}{}% \trans@languages + \gcmd{lan\-guage\-name}{}% \languagename + \gcmd{TeX\-OS\-Query\-Lang\-Tag}{}% \TeXOSQueryLangTag + \gcmd{TeX\-OS\-Query\-Locale}{}% \TeXOSQueryLocale + \gcmd{@for}{} + \gcmd{@nil}{} + \gcmd{At\-Begin\-Doc\-u\-ment}{}% \AtBeginDocument + % APPLICATIONS + \gapp{tex\-os\-query}{}% texosquery + \gapp{kpse\-which}{}% kpsewhich + \gapp{etex}{}% etex + \gapp{tex}{}% tex + \gapp{pdflatex}{}% pdflatex + % PUNCTUATION + \gpunc{atletter}% @ as a letter + {\name{\code{@} (catcode 11)}\field{text}{\code{@}}}% + \gpunc{atmod}% @ separates modifier + {\name{\code{@} (modifier)}\field{text}{\code{@}}}% + \gpunc{hyphensep}% - in tag + {\name{\code{-} (separator)}\field{text}{\code{-}}}% + \gpunc{underscoresep}% _ in tag + {\name{\code{\_} (separator)}\field{text}{\code{\_}}}% + \gpunc{dotsep}% . separates code-set + {\name{\code{.}\ (code-set)}\field{text}{\code{.}}}% + \gpunc{dollarenv}% ${ENV VAR} + {\name{\code{\$} (environment variable)}\field{text}{\code{\$}}} + \gpunc{escbsl}% \\ + {\name{\code{\glsbackslash\glsbackslash} (escaped backslash)} + \field{text}{\code{\glsbackslash\glsbackslash}} + } + % INDEX ONLY TERMS + \gidx{code-set}{} + \gidx{modifier}{} + \gidx{variant}{} + \gidx{territory}{} + \gidx{region}{\field{alias}{idx.territory}} + \gidx{script}{} + \gidx{BCP47}{\name{BCP~47}} + % ISO CODES + \gidx{639-1}{\name{ISO \mbox{639-1}}\field{text}{\mbox{639-1}}} + \gidx{639-2}{\name{ISO \mbox{639-2}}\field{text}{\mbox{639-2}}} + \gidx{639-2B}{\parent{idx.639-2}% + \name{ISO \mbox{639-2} (B)}% + \field{text}{\mbox{639-2} (B)}} + \gidx{639-2T}{\parent{idx.639-2}% + \name{ISO \mbox{639-2} (T)}% + \field{text}{\mbox{639-2} (T)}} + \gidx{639-3}{\name{ISO \mbox{639-3}}\field{text}{\mbox{639-3}}} + \gidx{3166-1}{\name{ISO \mbox{3166-1}}\field{text}{\mbox{3166-1}}} + \gidx{15924}{\name{ISO 15924}\field{text}{15924}} + % ABBREVIATIONS + \gacr{ISO}{ISO}{International Organization for Standardization}{\common} + \gacr{POSIX}{POSIX}{Portable Operating System Interface}{} + % SWITCHES + \glongswitchpunc{shell\dhyphen escape}{} + % PREDEFINED ISO LANGUAGE-REGION TAGS + \gisolangtag{en}{US}{american}{} + \gisolangtag{en}{GB}{british}{} + \gisolangtag{en}{AU}{australian}{} + \gisolangtag{en}{NZ}{newzealand}{} + \gisolangtag{en}{CA}{canadian}{} + \gisolangtag{fr}{CA}{canadien}{} + \gisolangtag{fr}{BE}{belgique}{} + \gisolangtag{pt}{BR}{brazilian}{} + \gisolangtag{it}{HR}{istriacountyitalian}{} + \gisolangtag{nl}{BE}{flemish}{} + \gisolangtag{fr}{FR}{france}{} + \gisolangtag{de}{DE}{germanDE}{} + \gisolangtag{de}{BE}{belgiangerman}{} + \gisolangtag{en}{GG}{guernseyenglish}{} + \gisolangtag{fr}{GG}{guernseyfrench}{} + \gisolangtag{it}{IT}{italy}{} + \gisolangtag{mt}{MT}{maltamaltese}{} + \gisolangtag{en}{MT}{maltaenglish}{} + \gisolangtag{en}{IM}{isleofmanenglish}{} + \gisolangtag{en}{JE}{jerseyenglish}{} + \gisolangtag{fr}{JE}{jerseyfrench}{} + \gisolangtag{nl}{NL}{netherlands}{} + \gisolangtag{pt}{PT}{portugal}{} + \gisolangtag{it}{SM}{sanmarino}{} + \gisolangtag{sl}{SI}{slovenia}{} + \gisolangtag{it}{SI}{sloveneistriaitalian}{} + \gisolangtag{es}{ES}{spainspanish}{} + \gisolangtag{es}{AR}{argentinespanish}{} + \gisolangtag{es}{BO}{bolivianspanish}{} + \gisolangtag{es}{CL}{chilianspanish}{} + \gisolangtag{es}{CO}{columbianspanish}{} + \gisolangtag{es}{CR}{costaricanspanish}{} + \gisolangtag{es}{CU}{cubanspanish}{} + \gisolangtag{es}{DO}{dominicanspanish}{} + \gisolangtag{es}{EC}{ecudorianspanish}{} + \gisolangtag{es}{SV}{elsalvadorspanish}{} + \gisolangtag{es}{GT}{guatemalanspanish}{} + \gisolangtag{es}{HN}{honduranspanish}{} + \gisolangtag{es}{MX}{mexicanspanish}{} + \gisolangtag{es}{NI}{nicaraguanspanish}{} + \gisolangtag{es}{PA}{panamaspanish}{} + \gisolangtag{es}{PY}{paraguayspanish}{} + \gisolangtag{es}{PE}{peruvianspanish}{} + \gisolangtag{es}{PR}{puertoricospanish}{} + \gisolangtag{es}{UY}{uruguayspanish}{} + \gisolangtag{es}{VE}{venezuelanspanish}{} + \gisolangtag{de}{CH}{swissgerman}{} + \gisolangtag{fr}{CH}{swissfrench}{} + \gisolangtag{it}{CH}{swissitalian}{} + \gisolangtag{rm}{CH}{swissromansh}{} + \gisolangtag{it}{VA}{vatican}{} + \gisolangtag{ga}{IE}{IEirish}{} + \gisolangtag{ga}{GB}{GBirish}{} + \gisolangtag{en}{IE}{IEenglish}{} + \gisolangtagwithvar{de}{AT}{1996}{naustrian}{} + \gisolangtag{de}{AT}{austrian}{} + \gisolangtag{id}{IN}{bahasa}{} + \gisolangtag{ms}{MY}{malay}{} + \gisolangtag{hr}{HR}{croatia}{} + \gisolangtagwithvar{de}{DE}{1996}{ngermanDE}{} + \gisolangtagwithvar{de}{CH}{1996}{nswissgerman}{} + \gisolangtag{hu}{HU}{hungarian}{} + \gisolangtag{gd}{GB}{GBscottish}{} + \gisolangtag{cy}{GB}{GBwelsh}{} + % PREDEFINED ROOT LANGUAGE TAGS + \grootlangtag{abkhaz}{ab}{} + \grootlangtag{afar}{aa}{} + \grootlangtag{afrikaans}{af}{} + \grootlangtag{akan}{ak}{} + \grootlangtag{albanian}{sq}{} + \grootlangtagwithreg{amharic}{am}{ET}{} + \grootlangtag{anglosaxon}{ang}{} + \grootlangtag{apache}{apa}{} + \grootlangtag{arabic}{ar}{} + \grootlangtagwithreg{aragonese}{an}{ES}{} + \grootlangtag{armenian}{hy}{} + \grootlangtag{assamese}{as}{} + \grootlangtag{asturian}{ast}{} + \grootlangtag{avaric}{av}{} + \grootlangtag{avestan}{ae}{} + \grootlangtag{aymara}{ay}{} + \grootlangtag{azerbaijani}{az}{} + \grootlangtagwithreg{bahasai}{id}{IN}{} + \grootlangtagwithreg{bahasam}{ms}{MY}{} + \grootlangtagwithreg{bambara}{bm}{ML}{} + \grootlangtag{bashkir}{ba}{} + \grootlangtag{basque}{eu}{} + \grootlangtag{belarusian}{be}{} + \grootlangtag{bengali}{bn}{} + \grootlangtag{berber}{ber}{} + \grootlangtag{bihari}{bh}{} + \grootlangtagwithreg{bislama}{bi}{VU}{} + \grootlangtagwithreg{bokmal}{nb}{NO}{} + \grootlangtag{bosnian}{bs}{} + \grootlangtagwithreg{breton}{br}{FR}{} + \grootlangtag{bulgarian}{bg}{} + \grootlangtag{burmese}{my}{} + \grootlangtag{catalan}{ca}{} + \grootlangtag{chamorro}{ch}{} + \grootlangtag{chechen}{ce}{} + \grootlangtag{chichewa}{ny}{} + \grootlangtag{chinese}{zh}{} + \grootlangtag{churchslavonic}{cu}{} + \grootlangtagwithreg{chuvash}{cv}{RU}{} + \grootlangtag{coptic}{cop}{} + \grootlangtagwithreg{cornish}{kw}{GB}{} + \grootlangtag{corsican}{co}{} + \grootlangtag{cree}{cr}{} + \grootlangtag{croatian}{hr}{} + \grootlangtag{czech}{cs}{} + \grootlangtag{danish}{da}{} + \grootlangtagwithreg{divehi}{dv}{MV}{} + \grootlangtag{dutch}{nl}{} + \grootlangtagwithreg{dzongkha}{dz}{BT}{} + \grootlangtagwithreg{easternpunjabi}{pa}{IN}{} + \grootlangtag{english}{en}{} + \grootlangtag{esperanto}{eo}{} + \grootlangtag{estonian}{et}{} + \grootlangtag{ewe}{ee}{} + \grootlangtag{faroese}{fo}{} + \grootlangtag{farsi}{fa}{} + \grootlangtagwithreg{fijian}{fj}{FJ}{} + \grootlangtag{finnish}{fi}{} + \grootlangtag{french}{fr}{} + \grootlangtagwithreg{friulan}{fur}{IT}{} + \grootlangtag{fula}{ff}{} + \grootlangtag{galician}{gl}{} + \grootlangtagwithreg{ganda}{lg}{UG}{} + \grootlangtag{georgian}{ka}{} + \grootlangtag{german}{de}{} + \grootlangtag{greek}{el}{} + \grootlangtag{guarani}{gn}{} + \grootlangtag{gujarati}{gu}{} + \grootlangtagwithreg{haitian}{ht}{HT}{} + \grootlangtag{hausa}{ha}{} + \grootlangtag{hebrew}{he}{} + \grootlangtag{herero}{hz}{} + \grootlangtag{hindi}{hi}{} + \grootlangtagwithreg{hirimotu}{ho}{PG}{} + \grootlangtagwithreg{icelandic}{is}{IS}{} + \grootlangtag{ido}{io}{} + \grootlangtag{igbo}{ig}{} + \grootlangtag{interlingua}{ia}{} + \grootlangtag{interlingue}{ie}{} + \grootlangtag{inuktitut}{iu}{} + \grootlangtag{inupiaq}{ik}{} + \grootlangtag{irish}{ga}{} + \grootlangtag{italian}{it}{} + \grootlangtag{japanese}{ja}{} + \grootlangtag{javanese}{jv}{} + \grootlangtag{kalaallisut}{kl}{} + \grootlangtagwithreg{kannada}{kn}{IN}{} + \grootlangtag{kanuri}{kr}{} + \grootlangtagwithreg{kashmiri}{ks}{IN}{} + \grootlangtag{kazakh}{kk}{} + \grootlangtag{khmer}{km}{} + \grootlangtag{kikuyu}{ki}{} + \grootlangtag{kinyarwanda}{rw}{} + \grootlangtag{kirundi}{rn}{} + \grootlangtagwithreg{komi}{kv}{RU}{} + \grootlangtag{kongo}{kg}{} + \grootlangtag{korean}{ko}{} + \grootlangtag{kurdish}{ku}{} + \grootlangtag{kwanyama}{kj}{} + \grootlangtag{kyrgyz}{ky}{} + \grootlangtag{lao}{lo}{} + \grootlangtag{latin}{la}{} + \grootlangtag{latvian}{lv}{} + \grootlangtag{limburgish}{li}{} + \grootlangtag{lingala}{ln}{} + \grootlangtag{lithuanian}{lt}{} + \grootlangtagwithreg{lsorbian}{dsb}{DE}{} + \grootlangtagwithreg{lubakatanga}{lu}{CD}{} + \grootlangtag{luxembourgish}{lb}{} + \grootlangtag{macedonian}{mk}{} + \grootlangtag{magyar}{hu}{} + \grootlangtag{malagasy}{mg}{} + \grootlangtagwithreg{malayalam}{ml}{IN}{} + \grootlangtag{maltese}{mt}{} + \grootlangtagwithreg{manx}{gv}{IM}{} + \grootlangtagwithreg{maori}{mi}{NZ}{} + \grootlangtagwithreg{marathi}{mr}{IN}{} + \grootlangtagwithreg{marshallese}{mh}{MH}{} + \grootlangtag{mongolian}{mn}{} + \grootlangtagwithreg{nauruan}{na}{NR}{} + \grootlangtagwithreg{navajo}{nv}{US}{} + \grootlangtag{ndonga}{ng}{} + \grootlangtag{nepali}{ne}{} + \grootlangtag{nko}{nqo}{} + \grootlangtag{northernndebele}{nd}{} + \grootlangtagwithreg{nynorsk}{nn}{NO}{} + \grootlangtag{norsk}{no}{} + \grootlangtag{northernsotho}{nso}{} + \grootlangtagwithreg{nuosu}{ii}{CN}{} + \grootlangtag{occitan}{oc}{} + \grootlangtag{ojibwe}{oj}{} + \grootlangtag{oromo}{om}{} + \grootlangtag{oriya}{or}{} + \grootlangtag{ossetian}{os}{} + \grootlangtag{pali}{pi}{} + \grootlangtag{pashto}{ps}{} + \grootlangtagwithreg{piedmontese}{pms}{IT}{} + \grootlangtag{polish}{pl}{} + \grootlangtag{portuges}{pt}{} + \grootlangtag{quechua}{qu}{} + \grootlangtag{romanian}{ro}{} + \grootlangtagwithreg{romansh}{rm}{CH}{} + \grootlangtag{russian}{ru}{} + \grootlangtag{samin}{se}{} + \grootlangtag{sanskrit}{sa}{} + \grootlangtag{samoan}{sm}{} + \grootlangtag{sango}{sg}{} + \grootlangtagwithreg{sardinian}{sc}{IT}{} + \grootlangtag{scottish}{gd}{} + \grootlangtag{serbian}{sr}{} + \grootlangtag{shona}{sn}{} + \grootlangtag{sindhi}{sd}{} + \grootlangtagwithreg{sinhalese}{si}{LK}{} + \grootlangtag{slovak}{sk}{} + \grootlangtag{slovene}{sl}{} + \grootlangtag{somali}{so}{} + \grootlangtagwithreg{southernndebele}{nr}{ZA}{} + \grootlangtag{southernsotho}{st}{} + \grootlangtag{spanish}{es}{} + \grootlangtag{sudanese}{su}{} + \grootlangtag{swahili}{sw}{} + \grootlangtag{swati}{ss}{} + \grootlangtag{swedish}{sv}{} + \grootlangtag{syriac}{syr}{} + \grootlangtagwithreg{tagalog}{tl}{PH}{} + \grootlangtagwithreg{tahitian}{ty}{PF}{} + \grootlangsametag{tai}{} + \grootlangtag{tajik}{tg}{} + \grootlangtag{tamil}{ta}{} + \grootlangtag{tatar}{tt}{} + \grootlangtagwithreg{telugu}{te}{IN}{} + \grootlangtagwithreg{thai}{th}{TH}{} + \grootlangtag{tibetan}{bo}{} + \grootlangtag{tigrinya}{ti}{} + \grootlangtagwithreg{tonga}{to}{TO}{} + \grootlangtag{tsonga}{ts}{} + \grootlangtag{tswana}{tn}{} + \grootlangtag{turkish}{tr}{} + \grootlangtag{turkmen}{tk}{} + \grootlangtagwithreg{twi}{tw}{GH}{} + \grootlangtagwithreg{ukrainian}{uk}{UA}{} + \grootlangtag{undetermined}{und}{} + \grootlangtag{urdu}{ur}{} + \grootlangtagwithreg{usorbian}{hsb}{DE}{} + \grootlangtagwithreg{uyghur}{ug}{CN}{} + \grootlangtag{uzbek}{uz}{} + \grootlangtagwithreg{venda}{ve}{ZA}{} + \grootlangtag{vietnamese}{vi}{} + \grootlangtag{volapuk}{vo}{} + \grootlangtag{walloon}{wa}{} + \grootlangtag{welsh}{cy}{} + \grootlangtagwithreg{westernfrisian}{fy}{NL}{} + \grootlangtag{wolof}{wo}{} + \grootlangtag{xhosa}{xh}{} + \grootlangtag{yiddish}{yi}{} + \grootlangtag{yoruba}{yo}{} + \grootlangtagwithreg{zhuang}{za}{CN}{} + \grootlangtag{zulu}{zu}{} + % PREDEFINED NON-ISO DIALECTS + \gdialecttag{acadian}{french}{} + \gdialecttagwithreg{american}{english}{US}{} + \gdialecttagwithreg{australian}{english}{AU}{} + \gdialecttagwithreg{austrian}{german}{AT}{} + \gdialecttagwithreg{naustrian}{german}{AT-1996}{} + \gdialecttagwithreg{bahasa}{bahasai}{IN}{} + \gdialecttagwithreg{brazil}{portuges}{BR}{} + \gdialecttagwithreg{brazilian}{portuges}{BR}{} + \gdialecttagwithreg{british}{english}{GB}{} + \gdialecttagwithreg{canadian}{english}{CA}{} + \gdialecttagwithreg{canadien}{french}{CA}{} + \gdialecttagwithreg{croatia}{croatian}{HR}{} + \gdialecttagwithreg{istriacountycroatian}{croatian}{HR}{} + \gdialecttagwithreg{istriacountyitalian}{italian}{HR}{} + \gdialecttagwithreg{netherlands}{dutch}{NL}{} + \gdialecttag{persian}{farsi}{} + \gdialecttagwithreg{flemish}{dutch}{BE}{} + \gdialecttag{francais}{french}{} + \gdialecttag{frenchb}{french}{} + \gdialecttagwithreg{france}{french}{FR}{} + \gdialecttagwithreg{belgique}{french}{BE}{} + \gdialecttagwithreg{belgiangerman}{german}{BE}{} + \gdialecttagwithmapandreg{nbelgiangerman}{german}{BE-1996}{ngerman}{} + \gdialecttagwithreg{friulian}{friulan}{IT}{} + \gdialecttagwithreg{friulano}{friulan}{IT}{} + \gdialecttagwithreg{furlan}{friulan}{IT}{} + \gdialecttag{kurmanji}{kurdish}{} + \gdialecttag{galicien}{galician}{} + \gdialecttag{deutsch}{german}{} + \gdialecttagsuppl{ngerman}{german}{1996}{} + \gdialecttagsupplwithmap{ngermanb}{german}{1996}{ngerman}{} + \gdialecttag{germanb}{german}{} + \gdialecttagwithmapandreg{ngermanDE}{german}{DE-1996}{ngerman}{} + \gdialecttagwithreg{germanDE}{german}{DE}{} + \gdialecttagwithreg{hungarian}{magyar}{HU}{} + \gdialecttagwithreg{indon}{bahasai}{IN}{} + \gdialecttagwithreg{indonesian}{bahasai}{IN}{} + \gdialecttag{gaeilge}{irish}{} + \gdialecttagwithreg{IEirish}{irish}{IE}{} + \gdialecttagwithreg{GBirish}{irish}{GB}{} + \gdialecttagwithmapandreg{IEenglish}{english}{IE}{british}{} + \gdialecttagwithreg{italy}{italian}{IT}{} + \gdialecttagwithreg{vatican}{italian}{VA}{} + \gdialecttagwithreg{sanmarino}{italian}{SM}{} + \gdialecttagwithreg{sloveneistriaitalian}{italian}{SI}{} + \gdialecttagwithmapandreg{jerseyenglish}{english}{JE}{british}{} + \gdialecttagwithreg{jerseyfrench}{french}{JE}{} + \gdialecttagwithmapandreg{guernseyenglish}{english}{GG}{british}{} + \gdialecttagwithreg{guernseyfrench}{french}{GG}{} + \gdialecttag{latein}{latin}{} + \gdialecttagwithreg{lowersorbian}{lsorbian}{DE}{} + \gdialecttagwithreg{malay}{bahasam}{MY}{} + \gdialecttagwithreg{meyalu}{bahasam}{MY}{} + \gdialecttagwithreg{maltamaltese}{maltese}{MT}{} + \gdialecttagwithmapandreg{maltaenglish}{english}{MT}{british}{} + \gdialecttagwithreg{newzealand}{english}{NZ}{} + \gdialecttagwithmapandreg{isleofmanenglish}{english}{IM}{british}{} + \gdialecttagwithreg{norwegian}{norsk}{NO}{} + \gdialecttagwithreg{piemonteis}{piedmontese}{IT}{} + \gdialecttag{polutonikogreek}{greek}{} + \gdialecttag{polutoniko}{greek}{} + \gdialecttag{portuguese}{portuges}{} + \gdialecttagwithreg{portugal}{portuges}{PT}{} + \gdialecttag{romansch}{romansh}{} + \gdialecttag{rumantsch}{romansh}{} + \gdialecttag{romanche}{romansh}{} + \gdialecttag{russianb}{russian}{} + \gdialecttag{gaelic}{scottish}{} + \gdialecttagwithreg{GBscottish}{scottish}{GB}{} + \gdialecttagsuppl{serbianc}{serbian}{Cyrl}{} + \gdialecttagsuppl{serbianl}{serbian}{Latn}{} + \gdialecttag{slovenian}{slovene}{} + \gdialecttagwithmapandreg{slovenia}{slovene}{SI}{slovenian}{} + \gdialecttagwithmapandreg{sloveneistriaslovenian}{slovene}{SI}{slovenian}{} + \gdialecttagwithreg{spainspanish}{spanish}{ES}{} + \gdialecttagwithreg{argentinespanish}{spanish}{AR}{} + \gdialecttagwithreg{bolivianspanish}{spanish}{BO}{} + \gdialecttagwithreg{chilianspanish}{spanish}{CL}{} + \gdialecttagwithreg{columbianspanish}{spanish}{CO}{} + \gdialecttagwithreg{costaricanspanish}{spanish}{CR}{} + \gdialecttagwithreg{cubanspanish}{spanish}{CU}{} + \gdialecttagwithreg{dominicanspanish}{spanish}{DO}{} + \gdialecttagwithreg{ecudorianspanish}{spanish}{EC}{} + \gdialecttagwithreg{elsalvadorspanish}{spanish}{SV}{} + \gdialecttagwithreg{guatemalanspanish}{spanish}{GT}{} + \gdialecttagwithreg{honduranspanish}{spanish}{HN}{} + \gdialecttagwithreg{mexicanspanish}{spanish}{MX}{} + \gdialecttagwithreg{nicaraguanspanish}{spanish}{NI}{} + \gdialecttagwithreg{panamaspanish}{spanish}{PA}{} + \gdialecttagwithreg{paraguayspanish}{spanish}{PY}{} + \gdialecttagwithreg{peruvianspanish}{spanish}{PE}{} + \gdialecttagwithreg{puertoricospanish}{spanish}{PR}{} + \gdialecttagwithreg{uruguayspanish}{spanish}{UY}{} + \gdialecttagwithreg{venezuelanspanish}{spanish}{VE}{} + \gdialecttagwithreg{swissgerman}{german}{CH}{} + \gdialecttagwithmapandreg{nswissgerman}{german}{CH-1996}{ngerman}{} + \gdialecttagwithreg{swissfrench}{french}{CH}{} + \gdialecttagwithreg{swissitalian}{italian}{CH}{} + \gdialecttagwithreg{swissromansh}{romansh}{CH}{} + \gdialecttagwithreg{UKenglish}{english}{GB}{} + \gdialecttagwithreg{ukraineb}{ukrainian}{UA}{} + \gdialecttagwithreg{ukraine}{ukrainian}{UA}{} + \gdialecttagwithreg{uppersorbian}{usorbian}{DE}{} + \gdialecttagwithreg{USenglish}{english}{US}{} + \gdialecttag{valencian}{catalan}{} + \gdialecttag{valencien}{catalan}{} + \gdialecttag{cymraeg}{welsh}{} + \gdialecttagwithreg{GBwelsh}{welsh}{GB}{} + \gdialecttag{nil}{undetermined}{} + % PREDEFINED REGIONS + \gregion{004}{AF}{AFG}{}% + \gregion{248}{AX}{ALA}{}% + \gregion{008}{AL}{ALB}{}% + \gregion{012}{DZ}{DZA}{}% + \gregion{016}{AS}{ASM}{}% + \gregion{020}{AD}{AND}{}% + \gregion{024}{AO}{AGO}{}% + \gregion{660}{AI}{AIA}{}% + \gregion{010}{AQ}{ATA}{}% + \gregion{028}{AG}{ATG}{}% + \gregion{032}{AR}{ARG}{}% + \gregion{051}{AM}{ARM}{}% + \gregion{533}{AW}{ABW}{}% + \gregion{036}{AU}{AUS}{}% + \gregion{040}{AT}{AUT}{}% + \gregion{031}{AZ}{AZE}{}% + \gregion{044}{BS}{BHS}{}% + \gregion{048}{BH}{BHR}{}% + \gregion{050}{BD}{BGD}{}% + \gregion{052}{BB}{BRB}{}% + \gregion{112}{BY}{BLR}{}% + \gregion{056}{BE}{BEL}{}% + \gregion{084}{BZ}{BLZ}{}% + \gregion{204}{BJ}{BEN}{}% + \gregion{060}{BM}{BMU}{}% + \gregion{064}{BT}{BTN}{}% + \gregion{068}{BO}{BOL}{}% + \gregion{535}{BQ}{BES}{}% + \gregion{070}{BA}{BIH}{}% + \gregion{072}{BW}{BWA}{}% + \gregion{074}{BV}{BVT}{}% + \gregion{076}{BR}{BRA}{}% + \gregion{086}{IO}{IOT}{}% + \gregion{096}{BN}{BRN}{}% + \gregion{100}{BG}{BGR}{}% + \gregion{854}{BF}{BFA}{}% + \gregion{108}{BI}{BDI}{}% + \gregion{132}{CV}{CPV}{}% + \gregion{116}{KH}{KHM}{}% + \gregion{120}{CM}{CMR}{}% + \gregion{124}{CA}{CAN}{}% + \gregion{136}{KY}{CYM}{}% + \gregion{140}{CF}{CAF}{}% + \gregion{148}{TD}{TCD}{}% + \gregion{152}{CL}{CHL}{}% + \gregion{156}{CN}{CHN}{}% + \gregion{162}{CX}{CXR}{}% + \gregion{166}{CC}{CCK}{}% + \gregion{170}{CO}{COL}{}% + \gregion{174}{KM}{COM}{}% + \gregion{180}{CD}{COD}{}% + \gregion{178}{CG}{COG}{}% + \gregion{184}{CK}{COK}{}% + \gregion{188}{CR}{CRI}{}% + \gregion{384}{CI}{CIV}{}% + \gregion{191}{HR}{HRV}{}% + \gregion{192}{CU}{CUB}{}% + \gregion{531}{CW}{CUW}{}% + \gregion{196}{CY}{CYP}{}% + \gregion{203}{CZ}{CZE}{}% + \gregion{208}{DK}{DNK}{}% + \gregion{262}{DJ}{DJI}{}% + \gregion{212}{DM}{DMA}{}% + \gregion{214}{DO}{DOM}{}% + \gregion{218}{EC}{ECU}{}% + \gregion{818}{EG}{EGY}{}% + \gregion{222}{SV}{SLV}{}% + \gregion{226}{GQ}{GNQ}{}% + \gregion{232}{ER}{ERI}{}% + \gregion{233}{EE}{EST}{}% + \gregion{231}{ET}{ETH}{}% + \gregion{238}{FK}{FLK}{}% + \gregion{234}{FO}{FRO}{}% + \gregion{242}{FJ}{FJI}{}% + \gregion{246}{FI}{FIN}{}% + \gregion{250}{FR}{FRA}{}% + \gregion{254}{GF}{GUF}{}% + \gregion{258}{PF}{PYF}{}% + \gregion{260}{TF}{ATF}{}% + \gregion{266}{GA}{GAB}{}% + \gregion{270}{GM}{GMB}{}% + \gregion{268}{GE}{GEO}{}% + \gregion{276}{DE}{DEU}{}% + \gregion{288}{GH}{GHA}{}% + \gregion{292}{GI}{GIB}{}% + \gregion{300}{GR}{GRC}{}% + \gregion{304}{GL}{GRL}{}% + \gregion{308}{GD}{GRD}{}% + \gregion{312}{GP}{GLP}{}% + \gregion{316}{GU}{GUM}{}% + \gregion{320}{GT}{GTM}{}% + \gregion{831}{GG}{GGY}{}% + \gregion{324}{GN}{GIN}{}% + \gregion{624}{GW}{GNB}{}% + \gregion{328}{GY}{GUY}{}% + \gregion{332}{HT}{HTI}{}% + \gregion{334}{HM}{HMD}{}% + \gregion{336}{VA}{VAT}{}% + \gregion{340}{HN}{HND}{}% + \gregion{344}{HK}{HKG}{}% + \gregion{348}{HU}{HUN}{}% + \gregion{352}{IS}{ISL}{}% + \gregion{356}{IN}{IND}{}% + \gregion{360}{ID}{IDN}{}% + \gregion{364}{IR}{IRN}{}% + \gregion{368}{IQ}{IRQ}{}% + \gregion{372}{IE}{IRL}{}% + \gregion{833}{IM}{IMN}{}% + \gregion{376}{IL}{ISR}{}% + \gregion{380}{IT}{ITA}{}% + \gregion{388}{JM}{JAM}{}% + \gregion{392}{JP}{JPN}{}% + \gregion{832}{JE}{JEY}{}% + \gregion{400}{JO}{JOR}{}% + \gregion{398}{KZ}{KAZ}{}% + \gregion{404}{KE}{KEN}{}% + \gregion{296}{KI}{KIR}{}% + \gregion{408}{KP}{PRK}{}% + \gregion{410}{KR}{KOR}{}% + \gregion{414}{KW}{KWT}{}% + \gregion{417}{KG}{KGZ}{}% + \gregion{418}{LA}{LAO}{}% + \gregion{428}{LV}{LVA}{}% + \gregion{422}{LB}{LBN}{}% + \gregion{426}{LS}{LSO}{}% + \gregion{430}{LR}{LBR}{}% + \gregion{434}{LY}{LBY}{}% + \gregion{438}{LI}{LIE}{}% + \gregion{440}{LT}{LTU}{}% + \gregion{442}{LU}{LUX}{}% + \gregion{446}{MO}{MAC}{}% + \gregion{807}{MK}{MKD}{}% + \gregion{450}{MG}{MDG}{}% + \gregion{454}{MW}{MWI}{}% + \gregion{458}{MY}{MYS}{}% + \gregion{462}{MV}{MDV}{}% + \gregion{466}{ML}{MLI}{}% + \gregion{470}{MT}{MLT}{}% + \gregion{584}{MH}{MHL}{}% + \gregion{474}{MQ}{MTQ}{}% + \gregion{478}{MR}{MRT}{}% + \gregion{480}{MU}{MUS}{}% + \gregion{175}{YT}{MYT}{}% + \gregion{484}{MX}{MEX}{}% + \gregion{583}{FM}{FSM}{}% + \gregion{498}{MD}{MDA}{}% + \gregion{492}{MC}{MCO}{}% + \gregion{496}{MN}{MNG}{}% + \gregion{499}{ME}{MNE}{}% + \gregion{500}{MS}{MSR}{}% + \gregion{504}{MA}{MAR}{}% + \gregion{508}{MZ}{MOZ}{}% + \gregion{104}{MM}{MMR}{}% + \gregion{516}{NA}{NAM}{}% + \gregion{520}{NR}{NRU}{}% + \gregion{524}{NP}{NPL}{}% + \gregion{528}{NL}{NLD}{}% + \gregion{540}{NC}{NCL}{}% + \gregion{554}{NZ}{NZL}{}% + \gregion{558}{NI}{NIC}{}% + \gregion{562}{NE}{NER}{}% + \gregion{566}{NG}{NGA}{}% + \gregion{570}{NU}{NIU}{}% + \gregion{574}{NF}{NFK}{}% + \gregion{580}{MP}{MNP}{}% + \gregion{578}{NO}{NOR}{}% + \gregion{512}{OM}{OMN}{}% + \gregion{586}{PK}{PAK}{}% + \gregion{585}{PW}{PLW}{}% + \gregion{275}{PS}{PSE}{}% + \gregion{591}{PA}{PAN}{}% + \gregion{598}{PG}{PNG}{}% + \gregion{600}{PY}{PRY}{}% + \gregion{604}{PE}{PER}{}% + \gregion{608}{PH}{PHL}{}% + \gregion{612}{PN}{PCN}{}% + \gregion{616}{PL}{POL}{}% + \gregion{620}{PT}{PRT}{}% + \gregion{630}{PR}{PRI}{}% + \gregion{634}{QA}{QAT}{}% + \gregion{638}{RE}{REU}{}% + \gregion{642}{RO}{ROU}{}% + \gregion{643}{RU}{RUS}{}% + \gregion{646}{RW}{RWA}{}% + \gregion{652}{BL}{BLM}{}% + \gregion{654}{SH}{SHN}{}% + \gregion{659}{KN}{KNA}{}% + \gregion{662}{LC}{LCA}{}% + \gregion{663}{MF}{MAF}{}% + \gregion{666}{PM}{SPM}{}% + \gregion{670}{VC}{VCT}{}% + \gregion{882}{WS}{WSM}{}% + \gregion{674}{SM}{SMR}{}% + \gregion{678}{ST}{STP}{}% + \gregion{682}{SA}{SAU}{}% + \gregion{686}{SN}{SEN}{}% + \gregion{688}{RS}{SRB}{}% + \gregion{690}{SC}{SYC}{}% + \gregion{694}{SL}{SLE}{}% + \gregion{702}{SG}{SGP}{}% + \gregion{534}{SX}{SXM}{}% + \gregion{703}{SK}{SVK}{}% + \gregion{705}{SI}{SVN}{}% + \gregion{090}{SB}{SLB}{}% + \gregion{706}{SO}{SOM}{}% + \gregion{710}{ZA}{ZAF}{}% + \gregion{239}{GS}{SGS}{}% + \gregion{728}{SS}{SSD}{}% + \gregion{724}{ES}{ESP}{}% + \gregion{144}{LK}{LKA}{}% + \gregion{729}{SD}{SDN}{}% + \gregion{740}{SR}{SUR}{}% + \gregion{744}{SJ}{SJM}{}% + \gregion{748}{SZ}{SWZ}{}% + \gregion{752}{SE}{SWE}{}% + \gregion{756}{CH}{CHE}{}% + \gregion{760}{SY}{SYR}{}% + \gregion{158}{TW}{TWN}{}% + \gregion{762}{TJ}{TJK}{}% + \gregion{834}{TZ}{TZA}{}% + \gregion{764}{TH}{THA}{}% + \gregion{626}{TL}{TLS}{}% + \gregion{768}{TG}{TGO}{}% + \gregion{772}{TK}{TKL}{}% + \gregion{776}{TO}{TON}{}% + \gregion{780}{TT}{TTO}{}% + \gregion{788}{TN}{TUN}{}% + \gregion{792}{TR}{TUR}{}% + \gregion{795}{TM}{TKM}{}% + \gregion{796}{TC}{TCA}{}% + \gregion{798}{TV}{TUV}{}% + \gregion{800}{UG}{UGA}{}% + \gregion{804}{UA}{UKR}{}% + \gregion{784}{AE}{ARE}{}% + \gregion{826}{GB}{GBR}{}% + \gregion{581}{UM}{UMI}{}% + \gregion{840}{US}{USA}{}% + \gregion{858}{UY}{URY}{}% + \gregion{860}{UZ}{UZB}{}% + \gregion{548}{VU}{VUT}{}% + \gregion{862}{VE}{VEN}{}% + \gregion{704}{VN}{VNM}{}% + \gregion{092}{VG}{VGB}{}% + \gregion{850}{VI}{VIR}{}% + \gregion{876}{WF}{WLF}{}% + \gregion{732}{EH}{ESH}{}% + \gregion{887}{YE}{YEM}{}% + \gregion{894}{ZM}{ZMB}{}% + \gregion{716}{ZW}{ZWE}{}% + % PREDEFINED SCRIPTS + \gscript{Adlm}{166}{Adlam}{RL}{}{} + \gscript{Afak}{439}{Afaka}{varies}{}{} + \gscript{Aghb}{239}{Caucasian Albanian}{LR}{}{} + \gscript{Ahom}{338}{Ahom, Tai Ahom}{LR}{}{} + \gscript{Arab}{160}{Arabic}{RL}{}{} + \gscript{Aran}{161}{Arabic (Nastaliq variant)}{RL}{}{} + \gscript{Armi}{124}{Imperial Aramaic}{RL}{}{} + \gscript{Armn}{230}{Armenian}{LR}{}{} + \gscript{Avst}{134}{Avestan}{RL}{}{} + \gscript{Bali}{360}{Balinese}{LR}{}{} + \gscript{Bamu}{435}{Bamum}{LR}{}{} + \gscript{Bass}{259}{Bassa Vah}{LR}{}{} + \gscript{Batk}{365}{Batak}{LR}{}{} + \gscript{Beng}{334}{Bhaiksuki}{LR}{}{} + \gscript{Blis}{550}{Blissymbols}{varies}{}{} + \gscript{Bopo}{285}{Bopomofo}{LR}{}{} + \gscript{Brah}{300}{Brahmi}{LR}{}{} + \gscript{Brai}{570}{Braille}{LR}{}{} + \gscript{Bugi}{367}{Buginese}{LR}{}{} + \gscript{Buhd}{372}{Buhid}{LR}{}{} + \gscript{Cakm}{349}{Chakma}{LR}{}{} + \gscript{Cans}{440}{Unified Canadian Aboriginal Syllabics}{LR}{}{} + \gscript{Cari}{201}{Carian}{LR}{}{} + \gscript{Cham}{358}{Cham}{LR}{}{} + \gscript{Cher}{445}{Cherokee}{LR}{}{} + \gscript{Cirt}{291}{Cirth}{varies}{}{} + \gscript{Copt}{204}{Coptic}{LR}{}{} + \gscript{Cprt}{403}{Cypriot}{RL}{}{} + \gscript{Cyrl}{220}{Cyrillic}{LR}{}{} + \gscript{Cyrs}{221}{Cyrillic (Old Church Slavonic variant)}{varies}{}{} + \gscript{Deva}{315}{Devanagari (Nagari)}{LR}{}{} + \gscript{Dsrt}{250}{Deseret (Mormon)}{LR}{}{} + \gscript{Dupl}{755}{Duployan shorthand, Duployan stenography}{LR}{}{} + \gscript{Egyd}{070}{Egyptian demotic}{RL}{}{} + \gscript{Egyh}{060}{Egyptian hieratic}{RL}{}{} + \gscript{Egyp}{050}{Egyptian hieroglyphs}{LR}{}{} + \gscript{Elba}{226}{Elbasan}{LR}{}{} + \gscript{Ethi}{430}{Ethiopic (Ge'ez)}{LR}{}{} + \gscript{Geok}{241}{Khutsuri (Asomtavruli and Nuskhuri)}{LR}{}{} + \gscript{Geor}{240}{Georgian (Mkhedruli)}{LR}{}{} + \gscript{Glag}{225}{Glagolitic}{LR}{}{} + \gscript{Goth}{206}{Gothic}{LR}{}{} + \gscript{Gran}{343}{Grantha}{LR}{}{} + \gscript{Grek}{200}{Greek}{LR}{}{} + \gscript{Gujr}{320}{Gujarati}{LR}{}{} + \gscript{Guru}{310}{Gurmukhi}{LR}{}{} + \gscript{Hanb}{503}{Han with Bopomofo (alias for Han + Bopomofo)}{LR}{}{} + \gscript{Hang}{286}{Hangul}{LR}{}{} + \gscript{Hani}{500}{Han (Hanzi, Kanji, Hanja)}{LR}{}{} + \gscript{Hano}{371}{Hanunoo}{LR}{}{} + \gscript{Hans}{501}{Han (Simplified variant)}{varies}{}{} + \gscript{Hant}{502}{Han (Traditional variant)}{varies}{}{} + \gscript{Hatr}{127}{Hatran}{RL}{}{} + \gscript{Hebr}{125}{Hebrew}{RL}{}{} + \gscript{Hira}{410}{Hiragana}{LR}{}{} + \gscript{Hluw}{080}{Anatolian Hieroglyphs (Luwian Hieroglyphs, Hittite Hieroglyphs)}{LR}{}{} + \gscript{Hmng}{450}{Pahawh Hmong}{LR}{}{} + \gscript{Hrkt}{412}{Japanese syllabaries (alias for Hiragana + Katakana)}{varies}{}{} + \gscript{Hung}{176}{Old Hungarian (Hungarian Runic)}{RL}{}{} + \gscript{Inds}{610}{Indus (Harappan)}{RL}{}{} + \gscript{Ital}{210}{Old Italic (Etruscan, Oscan, etc.)}{LR}{}{} + \gscript{Jamo}{284}{Jamo (alias for Jamo subset of Hangul)}{LR}{}{} + \gscript{Java}{361}{Javanese}{LR}{}{} + \gscript{Jpan}{413}{Japanese (alias for Han + Hiragana + Katakana)}{varies}{}{} + \gscript{Jurc}{510}{Jurchen}{LR}{}{} + \gscript{Kali}{357}{Kayah Li}{LR}{}{} + \gscript{Kana}{411}{Katakana}{LR}{}{} + \gscript{Khar}{305}{Kharoshthi}{RL}{}{} + \gscript{Khmr}{355}{Khmer}{LR}{}{} + \gscript{Khoj}{322}{Khojki}{LR}{}{} + \gscript{Kitl}{505}{Khitan large script}{LR}{}{} + \gscript{Kits}{288}{Khitan small script}{TB}{}{} + \gscript{Knda}{345}{Kannada}{LR}{}{} + \gscript{Kore}{287}{Korean (alias for Hangul + Han)}{LR}{}{} + \gscript{Kpel}{436}{Kpelle}{LR}{}{} + \gscript{Kthi}{317}{Kaithi}{LR}{}{} + \gscript{Lana}{351}{Tai Tham (Lanna)}{LR}{}{} + \gscript{Laoo}{356}{Lao}{LR}{}{} + \gscript{Latf}{217}{Latin (Fraktur variant)}{varies}{}{} + \gscript{Latg}{216}{Latin (Gaelic variant)}{LR}{}{} + \gscript{Latn}{215}{Latin}{LR}{}{} + \gscript{Leke}{364}{Leke}{LR}{}{} + \gscript{Lepc}{335}{Lepcha}{LR}{}{} + \gscript{Limb}{336}{Limbu}{LR}{}{} + \gscript{Lina}{400}{Linear A}{LR}{}{} + \gscript{Linb}{401}{Linear B}{LR}{}{} + \gscript{Lisu}{399}{Lisu (Fraser)}{LR}{}{} + \gscript{Loma}{437}{Loma}{LR}{}{} + \gscript{Lyci}{202}{Lycian}{LR}{}{} + \gscript{Lydi}{116}{Lydian}{RL}{}{} + \gscript{Mahj}{314}{Mahajani}{LR}{}{} + \gscript{Mand}{140}{Mandaic, Mandaean}{RL}{}{} + \gscript{Mani}{139}{Manichaean}{RL}{}{} + \gscript{Marc}{332}{Marchen}{LR}{}{} + \gscript{Maya}{090}{Mayan hieroglyphs}{varies}{}{} + \gscript{Mend}{438}{Mende Kikakui}{RL}{}{} + \gscript{Merc}{101}{Meroitic Cursive}{RL}{}{} + \gscript{Mero}{100}{Meroitic Hieroglyphs}{RL}{}{} + \gscript{Mlym}{347}{Malayalam}{LR}{}{} + \gscript{Modi}{324}{Modi}{LR}{}{} + \gscript{Mong}{145}{Mongolian}{TB}{}{} + \gscript{Moon}{218}{Moon (Moon code, Moon script, Moon type)}{varies}{}{} + \gscript{Mroo}{199}{Mro, Mru}{LR}{}{} + \gscript{Mtei}{337}{Meitei Mayek (Meithei, Meetei)}{LR}{}{} + \gscript{Mult}{323}{Multani}{LR}{}{} + \gscript{Mymr}{350}{Myanmar (Burmese)}{LR}{}{} + \gscript{Narb}{106}{Old North Arabian (Ancient North Arabian)}{RL}{}{} + \gscript{Nbat}{159}{Nabataean}{RL}{}{} + \gscript{Newa}{333}{Newa, Newar, Newari}{LR}{}{} + \gscript{Nkgb}{420}{Nakhi Geba}{LR}{}{} + \gscript{Nkoo}{165}{N'Ko}{RL}{}{} + \gscript{Nshu}{499}{Nushu}{LR}{}{} + \gscript{Ogam}{212}{Ogham}{varies}{}{} + \gscript{Olck}{261}{Ol Chiki}{LR}{}{} + \gscript{Orkh}{175}{Old Turkic, Orkhon Runic}{RL}{}{} + \gscript{Orya}{327}{Oriya}{LR}{}{} + \gscript{Osge}{219}{Osage}{LR}{}{} + \gscript{Osma}{260}{Osmanya}{LR}{}{} + \gscript{Palm}{126}{Palmyrene}{RL}{}{} + \gscript{Pauc}{263}{Pau Cin Hau}{LR}{}{} + \gscript{Perm}{227}{Old Permic}{LR}{}{} + \gscript{Phag}{331}{Phags-pa}{TB}{}{} + \gscript{Phli}{131}{Inscriptional Pahlavi}{RL}{}{} + \gscript{Phlp}{132}{Psalter Pahlavi}{RL}{}{} + \gscript{Phlv}{133}{Book Pahlavi}{RL}{}{} + \gscript{Phnx}{115}{Phoenician}{RL}{}{} + \gscript{Piqd}{293}{Klingon (KLI plqaD)}{LR}{}{} + \gscript{Plrd}{282}{Miao (Pollard)}{LR}{}{} + \gscript{Prti}{130}{Inscriptional Parthian}{RL}{}{} + \gscript{Qaaa}{900}{Reserved for private use (start)}{varies}{}{} + \gscript{Qaai}{908}{Private use}{varies}{}{} + \gscript{Qabx}{949}{Reserved for private use (end)}{varies}{}{} + \gscript{Rjng}{363}{Rejang (Redjang, Kaganga)}{LR}{}{} + \gscript{Roro}{620}{Rongorongo}{varies}{}{} + \gscript{Runr}{211}{Runic}{LR}{}{} + \gscript{Samr}{123}{Samaritan}{RL}{}{} + \gscript{Sara}{292}{Sarati}{varies}{}{} + \gscript{Sarb}{105}{Old South Arabian}{RL}{}{} + \gscript{Saur}{344}{Saurashtra}{LR}{}{} + \gscript{Sgnw}{095}{SignWriting}{TB}{}{} + \gscript{Shaw}{281}{Shavian (Shaw)}{LR}{}{} + \gscript{Shrd}{319}{Sharada}{LR}{}{} + \gscript{Sidd}{302}{Siddham}{LR}{}{} + \gscript{Sind}{318}{Khudawadi, Sindhi}{LR}{}{} + \gscript{Sinh}{348}{Sinhala}{LR}{}{} + \gscript{Sora}{398}{Sora Sompeng}{LR}{}{} + \gscript{Sund}{362}{Sundanese}{LR}{}{} + \gscript{Sylo}{316}{Syloti Nagri}{LR}{}{} + \gscript{Syrc}{135}{Syriac}{RL}{}{} + \gscript{Syre}{138}{Syriac (Estrangelo variant)}{RL}{}{} + \gscript{Syrj}{137}{Syriac (Western variant)}{RL}{}{} + \gscript{Syrn}{136}{Syriac (Eastern variant)}{RL}{}{} + \gscript{Tagb}{373}{Tagbanwa}{LR}{}{} + \gscript{Takr}{321}{Takri}{LR}{}{} + \gscript{Tale}{353}{Tai Le}{LR}{}{} + \gscript{Talu}{354}{New Tai Lue}{LR}{}{} + \gscript{Taml}{346}{Tamil}{LR}{}{} + \gscript{Tang}{520}{Tangut}{LR}{}{} + \gscript{Tavt}{359}{Tai Viet}{LR}{}{} + \gscript{Telu}{340}{Telugu}{LR}{}{} + \gscript{Teng}{290}{Tengwar}{LR}{}{} + \gscript{Tfng}{120}{Tifinagh (Berber)}{LR}{}{} + \gscript{Tglg}{370}{Tagalog (Baybayin, Alibata)}{LR}{}{} + \gscript{Thaa}{170}{Thaana}{RL}{}{} + \gscript{Thai}{352}{Thai}{LR}{}{} + \gscript{Tibt}{330}{Tibetan}{LR}{}{} + \gscript{Tirh}{326}{Tirhuta}{LR}{}{} + \gscript{Ugar}{040}{Ugaritic}{LR}{}{} + \gscript{Vaii}{470}{Vai}{LR}{}{} + \gscript{Visp}{280}{Visible Speech}{LR}{}{} + \gscript{Wara}{262}{Warang Citi (Varang Kshiti)}{LR}{}{} + \gscript{Wole}{480}{Woleai}{RL}{}{} + \gscript{Xpeo}{030}{Old Persian}{LR}{}{} + \gscript{Xsux}{020}{Cuneiform, Sumero-Akkadian}{LR}{}{} + \gscript{Yiii}{460}{Yi}{LR}{}{} + \gscript{Zinh}{994}{Inherited script}{inherited}{}{} + \gscript{Zmth}{995}{Mathematical notation}{LR}{}{} + \gscript{Zsym}{996}{Symbols}{varies}{}{} + \gscript{Zsye}{993}{Symbols (emoji variant)}{varies}{}{} + \gscript{Zxxx}{997}{Unwritten documents}{varies}{}{} + \gscript{Zyyy}{998}{Undetermined script}{varies}{}{} + \gscript{Zzzz}{999}{Uncoded script}{varies}{}{} +} + +\title{tracklang.sty v1.6: +tracking language options} +\author{Nicola L.C. Talbot\\[10pt] +Dickimaw Books\\ +\href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}} +\date{2022-10-29 +} + +\newcommand{\refoptstables}{\tablesref{tab:isoopts,tab:rootlangopts,tab:nonisoopts}} + +\begin{document} +\maketitle + +\htmlavailable + +\begin{abstract} +The \sty+{tracklang} package is provided for package developers +who want a simple interface to find out which languages the user has +requested through packages such as \sty{babel} and +\sty{polyglossia}. \emph{This package doesn't provide any +translations.} +Its purpose is simply to track which languages have been requested by the +user. Generic \TeX\ code is in \file{tracklang.tex} for +non-\LaTeX\ users. + +If the \idx{shellescape} is enabled or \gls{directlua} is available, +this package may also be used to query the \envvar{LCALL} +or \envvar{LANG} environment variable (see +\sectionref{sec:langsty}). Windows users, who don't have the locale +stored in environment variables, can use \app{texosquery} +in combination with \sty{tracklang}. (Similarly if \envvar{LCALL} +or \envvar{LANG} don't contain sufficient information.) In order to +use \app{texosquery} through the restricted \idx{shellescape}, you must +have at least Java~8 and set up \file{texosquery.cfg} +appropriately. (See the \app{texosquery} manual for further details.) +\end{abstract} + +The fundamental aim of this generic package is to be able to +effectively say: +\begin{quote} +The user (that is, the \emph{document} author) wants to use +dialects \langtagfmt{xx-XX}, \langtagfmt{yy-YY-Scrp}, etc in their +document. Any packages used by their document that provide +multilingual or region-dependent support should do whatever is +required to activate the settings for those languages and regions +(or warn the user that there's no support). +\end{quote} +Naturally, this is only of use if the locale-sensitive packages use +\sty{tracklang} to pick up this information, which is entirely up +to the package authors, but at the moment there's no standard method +for packages to detect the required language and region. The aim of +\sty{tracklang} is to provide that method. In particular, the +emphasis is on using \idx+{ISO} language and region codes rather than +hard-coding the various language labels used by different language +packages. + +Related articles: +\tugboat{Localisation of \TeX\ documents: \styfmt{tracklang}.} +{2016}{37}{3}{http://www.tug.org/TUGboat/tb37-3/tb117talbot.pdf}, +\dickimawhref{latex/tracklang}{Localisation with \filefmt{tracklang.tex}}, +and \faqspkg{tracklang}. + +\frontmatter +\tableofcontents +\listoftables + +\mainmatter +\part{User Guide} + +\chapter{Introduction} +\label{sec:intro} + +When I'm developing a package that provides multilingual support +(for example, \sty{glossaries}) it's cumbersome trying to work out +if the user has requested translations for fixed text. This usually +involves checking if \sty{babel} or \sty{translator} or +\sty{polyglossia} has been loaded and, if so, what language settings +have been used. The result can be a tangled mass of conditional +code. The alternative is to tell users to add the language as +a~document class option, which they may or may not want to do, or to +tell them to supply the language settings to every package they load +that provides multilingual support, which users are even less likely +to want to do. + +The \sty{tracklang} package tries to neaten this up by working out +as much of this information as possible for you and providing a +command that iterates through the loaded languages. This way, you +can just iterate through the list of tracked languages and, for each +language, either define the translations or warn the user that +there's no translation for that language. + +This package works best with \sty{ngerman} and \sty{german} (since +it's a simple test to determine if they have been loaded) and recent versions +of \sty{polyglossia} (which conveniently provides \gls{xpg@bcp@loaded}) or +when the language options are specified +in the document class option list. It works fairly well with +\sty{translator} but will additionally assume the root language was +also requested when a dialect is specified. So, for example, +\begin{codebox} +\cmd{usepackage}[\opt{british}]\marg{translator} +\cmd{usepackage}\marg{tracklang} +\end{codebox} +is equivalent to +\begin{compactcodebox} +\cmd{usepackage}[\opt{british}]\marg{translator} +\cmd{usepackage}[\opt{english},\opt{british}]\marg{tracklang} +\end{compactcodebox} +This means that \gls{ForEachTrackedDialect} will iterate +through the list \qt{\opt{english},\opt{british}} instead of just +\qt{\opt{british}}, which can result in some redundancy. + +Unfortunately I can't find any way of detecting a list of languages loaded +through \sty{babel}['s] new \gls{babelprovide} command. As far as I +can tell, the only stored list is in \gls{bbl@loaded} which only +contains the languages loaded through package options. + +If the \sty{ngerman} package has been loaded, \sty{tracklang} +effectively does: +\begin{compactcodebox} +\gls{TrackPredefinedDialect}\marg{\opt{ngerman}} +\end{compactcodebox} +Similarly, if the \sty{german} package has been loaded, +\sty{tracklang} effectively does +\begin{compactcodebox} +\gls{TrackPredefinedDialect}\marg{\opt{german}} +\end{compactcodebox} + +If any document class or package options are passed to +\sty{tracklang}, then \sty{tracklang} won't bother checking +for \sty{babel}, \sty{translator}, \sty{ngerman}, \sty{german} or +\sty{polyglossia}. So, if the above example is changed to: +\begin{codebox} +\cmd{documentclass}[\opt{british}]\marg{article} +\cmd{usepackage}\marg{translator} +\cmd{usepackage}\marg{tracklang} +\end{codebox} +then the dialect list will just consist of \qt{\opt{british}} rather than +\qt{\opt{english},\opt{british}}. This does, however, mean that if the user mixes +class and package options, only the class options will be detected. +For example: +\begin{codebox} +\cmd{documentclass}[\opt{british}]\marg{article} +\cmd{usepackage}[\opt{french}]\marg{babel} +\cmd{usepackage}\marg{tracklang} +\end{codebox} +In this case, only the \opt{british} option will be detected. The user +can therefore use the document class option (or \sty{tracklang} +package option) to override the dialect and set the country code +(where provided). For example: +\begin{codebox} +\cmd{documentclass}[\opt{es-MX}]\marg{article} +\cmd{usepackage}[\opt{spanish}]\marg{babel} +\cmd{usepackage}\marg{tracklang} +\end{codebox} +This sets the dialect to \opt{mexicanspanish} and the root language to +\opt{spanish}. + +Predefined dialects are listed in \refoptstables. These may be +passed in the document class options or +used in \gls{TrackPredefinedDialect}, as illustrated above. + +\Sectionref{sec:summary} provides brief examples of use for those +who want a general overview before reading the more detailed +sections. +\Sectionref{sec:generic} describes generic commands for +identifying the document languages. +\Sectionref{sec:user} is for package writers who want to +add multilingual support to their package and need to know which +settings the user has requested through language packages like +\sty{babel}. \Sectionref{sec:langsty} is for +developers of language definition packages who want to help other +package writers to detect what languages have been requested. + +\printunsrttable +[ + type=index, + block-style=name-other, + other=dialect, + toctitle={Predefined ISO Language-Region Dialects}, + title={Predefined \idx+{ISO} Language-Region Dialects. (\idx{ISO} tag or + dialect label may be used as a + package option or with \gls{TrackPredefinedDialect})}, + label={tab:isoopts}, + postamble={Other combinations need to be set with \gls{TrackLocale} + or \gls{TrackLanguageTag}}, + init={% + \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% + \let\glstableOtherFmt\optfmt + \renewcommand{\glstablenameheader}{ISO Tag}% + \renewcommand{\glstableotherheader}{Dialect Label}% + \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{isolangregion}{##3}{##2}}% + } +] + +\printunsrttable +[ + type=index, + header=false,rules=false,blocksep={},clearpage, + block-style=name,blocks=3, + other=isotag, + toctitle={Predefined Root Languages}, + title={Predefined Root Languages. (\fnregion Has an associated + territory.) The corresponding tag obtained with + \code{\gls{GetTrackedLanguageTag}\margm{dialect}} is shown in + parentheses}, + label={tab:rootlangopts}, + init={\let\glstableOtherFmt\optfmt + \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% + \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{rootlang}{##3}{##2}}% + } +] + +\printunsrttable +[ + type=index, + block-style=name,rules=false,header=false,blocksep={},clearpage, + other=tags,par=ragged, + toctitle={Predefined Non-ISO Dialects}, + title={Predefined Non-ISO Dialects. (\fnregion Has an + associated territory.) The corresponding +language tag obtained with +\code{\gls{GetTrackedLanguageTag}\margm{dialect}} +is shown in parentheses. If the dialect has a corresponding mapping +for the closest matching non-root language \gls{captionsdialect} or +\gls{datedialect}, this is also included after the tag following a +slash.}, + label={tab:nonisoopts}, + init={% + \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{noniso}{##3}{##2}}% + \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% + } +] + +\chapter{Summary of Use} +\label{sec:summary} + +There are three levels of use: +\begin{enumerate} +\item document level (code used by document authors); + +\item locale-sensitive package level +(code for package authors who need to +know what languages or locale the document is +using, such as \sty{glossaries} to translate commands like +\cmd{descriptionname} or \sty{datetime2} to provide localised +formats or time zone information); + +\item language set-up level (code for packages that set up +the document languages, such as \sty{babel} or \sty{polyglossia}). +\end{enumerate} + +\section{Document Level} +\label{sec:summary-doc} + +Document level use can be divided into generic \TeX\ use +(\sectionref{sec:tex}) and \LaTeX-specific use (\sectionref{sec:latex}). + +\subsection{Generic \texorpdfstring{\TeX}{TeX}} +\label{sec:tex} + +This section is for generic \TeX\ use. The \sty+{tracklang} files are +loaded with \gls{input}. See \sectionref{sec:latex} for \LaTeX\ use. + +A Unix-like user wants the locale information picked up from the +locale environment variable (the \ext+{tex} extension may be omitted): +\begin{codebox*} +\gls{input} \file{tracklang.tex} \comment{v1.3} +\gls{TrackLangFromEnv} +\comment{load packages that use tracklang for localisation} +\end{codebox*} + +A Windows user wants the locale information picked up from the +operating system (again the \ext{tex} extension may be omitted): +\begin{codebox*} +\gls{input} \file{texosquery.tex} +\gls{input} \file{tracklang.tex} \comment{v1.3} +\gls{TrackLangFromEnv} +\comment{load packages that use tracklang for localisation} +\end{codebox*} +Or (\sty{texosquery} v1.2) +\begin{codebox*} +\gls{input} \file{texosquery.tex} \comment{v1.2} +\gls{input} \file{tracklang.tex} \comment{v1.3} +\codepar +\gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} +\gls{TrackLanguageTag}\marg{\cmd{langtag}} +\comment{load packages that use tracklang for localisation} +\end{codebox*} +A Unix-like user who may or may not have \app{texosquery} setup to run in the +\idx{shellescape}: +\begin{codebox*} +\gls{input} \file{texosquery.tex} +\gls{input} \file{tracklang.tex} \comment{v1.3} +\codepar +\cmd{ifx}\gls{TeXOSQueryLangTag}\cmd{undefined} + \gls{TrackLangFromEnv} +\cmd{else} + \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} + \gls{TrackLanguageTag}\marg{\cmd{langtag}} +\cmd{fi} +\comment{load packages that use tracklang for localisation} +\end{codebox*} + +A user is writing in Italy in Armenian with a Latin +\idx{script} (\opt{Latn}) and the arevela \idx{variant}: +\begin{codebox*} +\gls{input} \file{tracklang.tex} \comment{v1.3} +\gls{TrackLanguageTag}\marg{hy-Latn-IT-arevela} +\comment{load packages that use tracklang for localisation} +\end{codebox*} + +A user is writing in English in the UK: +\begin{codebox*} +\gls{input} \file{tracklang.tex} +\gls{TrackPredefinedDialect}\marg{british} +\comment{load packages that use tracklang for localisation} +\end{codebox*} + +Find out information about the current language (supplied +in \gls{languagename}): +\begin{codebox*} +\gls{SetCurrentTrackedDialect}\marg{\gls{languagename}} +Dialect: \gls{CurrentTrackedDialect}. +Language: \gls{CurrentTrackedLanguage}. +ISO Code: \gls{CurrentTrackedIsoCode}. +Region: \gls{CurrentTrackedRegion}. +Modifier: \gls{CurrentTrackedDialectModifier}. +Variant: \gls{CurrentTrackedDialectVariant}. +Script: \gls{CurrentTrackedDialectScript}. +Sub-Lang: \gls{CurrentTrackedDialectSubLang}. +Additional: \gls{CurrentTrackedDialectAdditional}. +Language Tag: \gls{CurrentTrackedLanguageTag}. +\end{codebox*} +Additional information about the \idx{script} can be obtained by +also loading \sty{tracklang-scripts}: +\begin{codebox*} +\gls{input} \file{tracklang-scripts.tex} +\end{codebox*} +The name, numeric code and direction can now be obtained: +\begin{codebox*} +Name: \gls{TrackLangScriptAlphaToName}\marg{\gls{CurrentTrackedDialectScript}}. +Numeric: +\gls{TrackLangScriptAlphaToNumeric}\marg{\gls{CurrentTrackedDialectScript}}. +Direction: +\gls{TrackLangScriptAlphaToDir}\marg{\gls{CurrentTrackedDialectScript}}. +\end{codebox*} +Test for a specific \idx{script} (in this case \opt{Latn}): +\begin{codebox*} +Latin? +\cmd{ifx}\gls{CurrentTrackedDialectScript}\tklscript{Latn} + Yes +\cmd{else} + No +\cmd{fi} +\end{codebox*} + +\subsection{\texorpdfstring{\LaTeX}{LaTeX}} +\label{sec:latex} + +This section is for \LaTeX\ use. See \sectionref{sec:tex} for generic \TeX\ use. + +With newer versions of \sty{polyglossia}, where \gls{xpg@bcp@loaded} +is defined, you just need to make sure the languages are set before +\sty{tracklang} is loaded: +\begin{codebox*} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\marg{polyglossia} +\cmd{setmainlanguage}[variant=uk]\marg{english} +\comment{load packages that use tracklang for localisation} +\end{codebox*} +For older versions of \sty{polyglossia} where the regional +information is required, use recognised class options: +\begin{codebox*} +\cmd{documentclass}[\opt{en-GB}]\marg{article} +\cmd{usepackage}\marg{polyglossia} +\cmd{setmainlanguage}[variant=uk]\marg{english} +\comment{load packages that use tracklang for localisation} +\end{codebox*} + +For \sty{babel} users where the supplied \sty{babel} dialect +label is sufficient, and is passed either through the document class +or package options, there's no need to do anything special: +\begin{codebox*} +\cmd{documentclass}[\opt{british},\opt{canadien}]\marg{article} +\cmd{usepackage}[T1]\marg{fontenc} +\cmd{usepackage}\marg{babel} +\comment{load packages that use tracklang for localisation} +\end{codebox*} +If the region is important but there's no \sty{babel} dialect that +represents it, there are several options. +The first method is to use the class options recognised by \sty{tracklang} +and the root language labels when loading \sty{babel}: +\begin{codebox*} +\cmd{documentclass}[\opt{en-IE},\opt{ga-IE}]\marg{article} +\cmd{usepackage}[english,irish]\marg{babel} +\comment{load packages that use tracklang for localisation} +\end{codebox*} + +Another method with \sty{babel} is to use \gls{TrackLanguageTag} and map the new +dialect label to the nearest matching \gls{captionsdialect}: +\begin{codebox*} +\cmd{documentclass}\marg{article} +\codepar +\cmd{usepackage}\marg{tracklang}\comment{v1.3} +\gls{TrackLanguageTag}\marg{\opt{en-MT}} +\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{\opt{UKenglish}} +\codepar +\cmd{usepackage}[UKenglish]\marg{babel} +\comment{load packages that use tracklang for localisation} +\end{codebox*} +This ensures that the \tklcaptions{UKenglish} hook is detected +by the localisation packages. This mapping isn't needed +for \sty{polyglossia} as the caption hooks use the root language +label. This mapping also isn't needed if \opt{british} is used +instead of \opt{UKenglish} since the \opt{en-MT} +(\opt{maltaenglish}) +predefined dialect automatically sets up a mapping to +\opt{british}. (The default mappings are shown in +\tableref{tab:nonisoopts}.) + +There's no support for \gls{babelprovide}. If you are using +\gls{babelprovide}, you will need to use the class option or +\gls{TrackLanguageTag} as above. + +\section{Locale-Sensitive Packages} +\label{sec:summary-localepkg} + +Let's suppose you are developing a package called +\filefmt{mypackage.sty} or \filefmt{mypackage.tex} and you want +to find out what languages the document author has requested. (See also: +\dickimawhref{latex/tracklang/otherpkg.shtml}{Using +\filefmt{tracklang.tex} in Packages with Localisation Features}.) + +Generic \TeX\ use (the \ext{tex} extension may be omitted): +\begin{codebox*} +\gls{input} \file{tracklang.tex} +\end{codebox*} +(Most of the commands used in this section require at least +\sty{tracklang} version 1.3 but 1.4 is better if you want to +include the \idx{script} tag in the \ext+{ldf} files.) +Note that \file{tracklang.tex} has a check to determine if +it's already been loaded, so you don't need to worry about that. + +\LaTeX\ use: +\begin{codebox*} +\gls{RequirePackage}\marg{tracklang}[2019/11/30]\comment{at least v1.4} +\end{codebox*} +This will picked up any language options supplied in the document +class options and will also detect if \sty{babel} or +\sty{polyglossia} have been loaded. + +(\LaTeX) If you want to allow the user to set the locale in the +package options: +\begin{codebox*} +\gls{DeclareOption}*\marg{\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}} +\end{codebox*} +This means the user can do, say, +\begin{codebox} +\cmd{usepackage}[hy-Latn-IT-arevela]\marg{mypackage} +\end{codebox} +With at least version 1.4, it's better to use \gls{TrackIfKnownLanguage}: +\begin{codebox} +\gls{DeclareOption}*\marg{\comment{} + \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}\comment{} + \marg{\comment{successful} + \cmd{PackageInfo}\marg{mypackage}\marg{Tracking language `\cmd{CurrentOption}'}\comment{} + }\comment{} + \marg{\comment{failed} + \cmd{PackageError}\marg{mypackage}\comment{} + \marg{Unknown language specification `\cmd{CurrentOption}'}\comment{} + \marg{You need to supply either a known dialect label + or a valid language tag}\comment{} + }\comment{} +} +\end{codebox} + +\begin{information} +The rest of the example package in this section uses generic code. +If you are using \LaTeX, it's better to replace \cmd{def} and +\cmd{ifx} with more appropriate \LaTeX\ commands. +\end{information} + +If you want to fetch the locale information from the operating +system when the user hasn't requested a language: +\begin{codebox*} +\gls{AnyTrackedLanguages} +\marg{} +\marg{\comment{fetch locale information from the operating system} + \cmd{ifx}\gls{TeXOSQueryLangTag}\cmd{undefined} + \comment{texosquery v1.2 not available} + \gls{TrackLangFromEnv} + \cmd{else} + \comment{texosquery v1.2 available} + \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} + \gls{TrackLanguageTag}\marg{\cmd{langtag}} + \cmd{fi} +} +\end{codebox*} + +Set up the defaults if necessary: +\begin{codebox} +\cmd{def}\cmd{fooname}\marg{Foo} +\cmd{def}\cmd{barname}\marg{Bar} +\end{codebox} + +Now load the resource files: +\begin{codebox*} +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\comment{} + \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{thisdialect}}\comment{} + }\comment{} +} +\marg{}\comment{no tracked languages, default already set up} +\end{codebox*} + +Each resource file has the naming scheme \file{prefix-localeid.ldf}\glsadd{ext.ldf}. +In this example, the \meta{prefix} is \filefmt{mypackage}. The +\meta{localeid} part may be the language or dialect label (for +example, \opt{english} or \opt{british}) or a combination of the +\idx{ISO} language and region codes (for example, \opt{en-GB} or +\iso{english} or \optfmt{GB}). As from version 1.4, \meta{localeid} +may also include the \idx{script} or \idx{variant}. (See the definition of +\gls{IfTrackedLanguageFileExists} \pref{pg:filesearch} for further +details.) + +The simplest scheme is to use the root language label (not the +dialect label) for the base language settings and use the \idx+{ISO} +codes for regional support. + +For example, the file \ldf{mypackage}{english}: +\begin{codebox*} +\comment{identify this file:} +\gls{TrackLangProvidesResource}\marg{english}[2016/10/06 v1.0] +\codepar +\gls{TrackLangAddToCaptions}\marg{\comment{} + \cmd{def}\cmd{fooname}\marg{Foo}\comment{} + \cmd{def}\cmd{barname}\marg{Bar}\comment{} +} +\end{codebox*} +This sets up appropriate the \gls{captionsdialect} hook (if it's +found). For other hooks, such as \gls{datedialect}, use +\gls{TrackLangAddToHook} or \gls{TrackLangRedefHook} instead. + +With pre-v1.4 versions of \sty{tracklang}, the \idx{script} isn't included +in the file search. If it's needed then either require at least v1.4 +or have a base \ext{ldf} file that tries to load a version for the +particular \idx{script} (which can be accessed with +\gls{CurrentTrackedDialectScript}). +Here's an example for a language with different writing systems. +The resource file for Serbian \ldf{mypackage}{serbian}: +\begin{codebox*} +\comment{identify file:} +\gls{TrackLangProvidesResource}\marg{serbian}[2016/10/06 v1.0] +\codepar +\gls{TrackLangRequestResource}\marg{serbian-\gls{CurrentTrackedDialectScript}} +\marg{}\comment{file not found, do something sensible here} +\end{codebox*} +The file \ldf{mypackage}{serbian-Latn} sets up +the Latin \idx{script} (\opt{Latn}): +\begin{codebox*} +\gls{TrackLangProvidesResource}\marg{serbian-Latn}[2016/10/06 v1.0] +\codepar +\gls{TrackLangAddToCaptions}\marg{\comment{} + \cmd{def}\cmd{fooname}\marg{...}\comment{provide appropriate Latin translations} + \cmd{def}\cmd{barname}\marg{...}\comment{} +} +\end{codebox*} +The file \ldf{mypackage}{serbian-Cyrl} sets up +the Cyrillic \idx{script} (\opt{Cyrl}): +\begin{codebox*} +\gls{TrackLangProvidesResource}\marg{serbian-Cyrl}[2016/10/06 v1.0] +\codepar +\gls{TrackLangAddToCaptions}\marg{\comment{} + \cmd{def}\cmd{fooname}\marg{...}\comment{provide appropriate Cyrillic translations} + \cmd{def}\cmd{barname}\marg{...}\comment{} +} +\end{codebox*} +With v1.4+ you just need \ldf{mypackage}{sr-Latn} and +\ldf{mypackage}{sr-Cyrl} for the regionless versions. + +\section{Language Packages} +\label{sec:summary-langpkg} + +Let's suppose now you're the developer of a package that +sets up the language, hyphenation patterns and so on. +It would be really helpful to the locale-sensitive packages +in \sectionref{sec:summary-localepkg} to know what languages +the document author has requested. You can use the +\sty{tracklang} package to identify this information +by tracking the requested localisation, so that other packages +can have a consistent way of querying it. (See also: +\dickimawhref{latex/tracklang/langpkg.shtml}{Integrating +\filefmt{tracklang.tex} into Language Packages}.) + +Generic use: +\begin{codebox} +\gls{input} tracklang +\end{codebox} +Alternative \LaTeX\ use: +\begin{codebox} +\gls{RequirePackage}\marg{tracklang}[2019/11/30]\comment{v1.4} +\end{codebox} +Unlike \gls{input}, \gls{RequirePackage} will allow \sty{tracklang} +to pick up the document class options, but using \gls{RequirePackage} +will also trigger the tests for known language packages. +(If you want to find out if \sty{tracklang} has already been +loaded and locales have already been tracked, you can use the +same code as in the previous section.) + +When a user requests a particular language through your package, +the simplest way of letting \sty{tracklang} know about it +is to use \gls{TrackPredefinedDialect} or \gls{TrackLanguageTag}. +For example, if the user requests \opt{british}, that's a +predefined dialect so you can just do: +\begin{codebox} +\gls{TrackPredefinedDialect}\marg{\opt{british}} +\end{codebox} +Alternatively +\begin{codebox} +\gls{TrackLanguageTag}\marg{\opt{en-GB}} +\end{codebox} +If your package uses caption hooks, then you can set up +a mapping between \sty{tracklang}'s internal dialect label +and your caption label. For example, let's suppose the +closest match to English used in Malta (\opt{en-MT}) is the +dialect \opt{UKenglish} (for example, the date format is +similar between GB and MT): +\begin{codebox} +\gls{TrackLanguageTag}\marg{\opt{en-MT}} +\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{\opt{UKenglish}} +\cmd{def}\tklcaptions{UKenglish}\marg{\comment{} + \cmd{def}\cmd{contentsname}\marg{Contents}\comment{} + \comment{...} +} +\end{codebox} +(The predefined \opt{maltaenglish} option provided by +\sty{tracklang} automatically sets the mapping to +\opt{british}, but the above method will change that mapping +to \opt{UKenglish}.) + +This now means that \gls{TrackLangAddToHook} and \gls{TrackLangRedefHook} commands can +find your language hooks. You don't need the map if your dialect +label is the same as \sty{tracklang}'s root language label +for that locale. For example: +\begin{codebox} +\gls{TrackLanguageTag}\marg{\opt{en-MT}} +\cmd{def}\tklcaptions{english}\marg{\comment{} + \cmd{def}\cmd{contentsname}\marg{Contents}\comment{} + \comment{...} +} +\end{codebox} + +When the user switches language through commands like +\gls{selectlanguage} it would be useful to also use +\code{\gls{SetCurrentTrackedDialect}\margm{dialect}} to make it easier +for the document author or locale-sensitive packages to pick +up the current locale. The \meta{dialect} argument may be +\sty{tracklang}'s internal dialect label or the dialect +label you assigned with \gls{SetTrackedDialectLabelMap}. It +may also be the root language label, in which case +\sty{tracklang} will search for the last dialect to be +tracked with that language. For example: +\begin{codebox} +\cmd{def}\gls{selectlanguage}\#1\marg{\comment{} + \gls{SetCurrentTrackedDialect}\marg{\#1}\comment{} + \comment{set up hyphenation patterns etc} +} +\end{codebox} +See the example in \sectionref{sec:summary-doc} or the example in +\dickimawhref{latex/tracklang/langpkg.shtml}{Integrating +\filefmt{tracklang.tex} into Language Packages}. + +\chapter{Generic Use} +\label{sec:generic} + +For plain \TeX\ you can input \file{tracklang.tex}: +\begin{codebox} +\gls{input} tracklang +\end{codebox} +or for \TeX\ formats that have an argument form for \gls{input}: +\begin{codebox} +\gls{input}\marg{tracklang} +\end{codebox} +As from version 1.3, you don't need to change the category +code of \idx{atletter} before loading \file{tracklang.tex} +as it will automatically be changed to 11 and switched +back at the end (if required). + +The \LaTeX\ package \file{tracklang.sty} +inputs the generic \TeX\ code in \file{tracklang.tex}, but before +it does so it defines +\cmddef{@tracklang@declareoption} +to +\begin{compactcodebox*} +\gls{DeclareOption}\margm{dialect}\marg{\gls{TrackPredefinedDialect}\margm{dialect}} +\end{compactcodebox*} +If \gls{@tracklang@declareoption} isn't defined when +\file{tracklang.tex} is input, it will be defined to ignore its +argument. + +This means that all the predefined languages and dialects +(\refoptstables) automatically become package options, so +the \file{tracklang.sty} package can pick up document class +options and add them to \sty{tracklang}'s internal list of tracked +document languages. + +If you're not using \LaTeX, this option isn't available +although you can redefine +\gls{@tracklang@declareoption} +to use something analogous to \gls{DeclareOption}, if appropriate. +Otherwise, the document languages need +to be explicitly identified (using any of the following commands) +so that \sty{tracklang} knows about them. + +\cmddef{TrackPredefinedDialect} +This will add the predefined dialect and its associated \idx{ISO} codes to the list +of tracked document languages. The \meta{dialect label} may be any +of those listed in \refoptstables. + +For example: +\begin{codebox} +\gls{input} tracklang +\gls{TrackPredefinedDialect}\marg{\opt{british}} +\end{codebox} +is the Plain \TeX\ alternative to: +\begin{codebox} +\cmd{documentclass}[\opt{british}]\marg{article} +\cmd{usepackage}\marg{tracklang} +\end{codebox} + +Note that it's impractical to define every possible language +and region combination as it would significantly slow the +time taken to load \sty{tracklang} so, after version~1.3, +I don't intend adding any new predefined dialects. As from version +1.3, if you want to track a dialect that's not predefined by +\sty{tracklang}, then you can use: +\cmddef{TrackLocale} +If \meta{locale} is a recognised dialect, this is equivalent to +using \gls{TrackPredefinedDialect}, otherwise \meta{locale} +needs to be in one the following formats: +\begin{itemize} +\item \meta{\idx{ISO} lang} +\item \meta{\idx{ISO} lang}\idx{atmod}\meta{modifier} +\item \meta{\idx{ISO} lang}\idx{hyphensep}\meta{\idx{ISO} country} +\item \meta{\idx{ISO} lang}\idx{hyphensep}\meta{\idx{ISO} country}\idx{atmod}\meta{modifier} +\end{itemize} +where \meta{\idx{ISO} lang} is the \idxn{639-1} or \idx{639-2} code identifying +the language (lower case), \meta{\idx{ISO} country} is the \idx{3166-1} +\idx{ISO} code identifying the \idx{territory} (upper case) and +\meta{modifier} is the \idx{modifier} or \idx{variant}. The hyphen +(\idx{hyphensep}) may be replaced by an underscore character +(\idx{underscoresep}). \Idx{code-set} information in the +form \code{\idx{dotsep}\meta{codeset}} may optionally appear before the +\idx{modifier}. For example, +\code{de\idx{hyphensep}DE\idx{dotsep}utf8\idx{atmod}new} (\idx{modifier} is +\optfmt{new}) or \code{en\idx{hyphensep}GB\idx{dotsep}utf8} (\idx{modifier} is missing). +The \idx{code-set} will be ignored if present, but it won't interfere +with the parsing. + +For example: +\begin{codebox} +\gls{TrackLocale}\marg{de\idx{hyphensep}NA\idx{atmod}new} +\end{codebox} +indicates German in Namibia using the new spelling. + +\begin{important} +If a language has different \idxn{639-2T} and \idx{639-2B} codes, then +the \qt{T} form should be used. (So for the above example, +\code{deu} may be used instead of \code{de}, but \code{ger} +won't be recognised.) +\end{important} + +Alternatively, you can use +\cmddef{TrackLanguageTag} +where \meta{tag} is a regular, well-formed language tag or a recognised dialect +label. (Irregular grandfather tags aren't recognised.) +This command will fully expand \meta{tag}. +A warning is issued if the tag is empty. + +If you want to first check that \meta{tag} includes a valid language +code, then you can instead use: +\cmddef{TrackIfKnownLanguage} +This will only track \meta{tag} (and then do \meta{success code}) if +\meta{tag} starts with a valid language code (or is a predefined +dialect) otherwise it will do \meta{fail code}. Both +\gls{TrackLanguageTag} and \gls{TrackIfKnownLanguage} will check if +\meta{tag} is a predefined option. (This saves parsing the tag if +it's recognised.) + +For example: +\begin{codebox} +\gls{TrackLanguageTag}\marg{hy-Latn-IT-arevela} +Latn-ME: \gls{TrackIfKnownLanguage}\marg{Latn-ME}\marg{success}\marg{fail}. +brazilian: \gls{TrackIfKnownLanguage}\marg{brazilian}\marg{success}\marg{fail}. +\end{codebox} +This will track \optfmt{hy-Latn-IT-arevela} and \opt{brazilian} +(\optfmt{pt-BR}) but not \optfmt{Latn-ME} (because it doesn't contain a +valid language code) even though it's a valid \idx{script} and country +code. The above is just for illustrative purposes. Typically the +language tracking isn't performed within the document text. + +The \sty{datetime2} package assumes that any unknown package option is a +language identifier. It could simply do: +\begin{compactcodebox} +\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}} +\end{compactcodebox} +but users can make mistakes sometimes and this won't provide any +helpful information if they, for example, misspelt a package option +or forgot the \qt{\meta{key}=} part of a \keyval\ +setting. Instead (as from v1.5.5) \sty{datetime2} now does: +\begin{compactcodebox} +\gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}} +\marg{...}\comment{known language} +\marg{\cmd{PackageError}\marg{...}\marg{...}\marg{...}} +\end{compactcodebox} +This will now give the user some guidance. + +If \meta{tag} contains a sub-language tag, this will be set +as the \idx{639-3} code for the \emph{dialect} label. Note that this is +different to the root language codes which are set using the +language label. For example: +\begin{codebox} +\gls{TrackLanguageTag}\marg{zh-cmn-Hans-CN} +\end{codebox} +creates a new dialect with the label \code{zh\-cmn\-Hans\-CN}. +The root language \opt{chinese} has the \idx{639-1} code +\optfmt{zh} and the dialect \code{zh\-cmn\-Hans\-CN} has the +\idxn{639-3} code \optfmt{cmn}. +\begin{codebox} +ISO 639-1: \gls{TrackedIsoCodeFromLanguage}\marg{639-1}\marg{chinese}. +ISO 639-3: \gls{TrackedIsoCodeFromLanguage}\marg{639-3}\marg{zhcmnHansCN}. +\end{codebox} + +Version 1.2 of \sty{texosquery} provides the command \gls{TeXOSQueryLangTag}, +which may be used to fetch the operating system's regional +information as a language tag. These commands can be used as +follows: +\begin{codebox} +\gls{input} tracklang \comment{v1.3} +\gls{input} texosquery \comment{v1.2} +\codepar +\gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} +\gls{TrackLanguageTag}\marg{\cmd{langtag}} +\end{codebox} +(If the \idx{shellescape} is disabled, \cmd{langtag} will be empty, which +will trigger a~warning but no errors.) + +Some of the predefined root language options listed +in \tableref{tab:rootlangopts} have an associated region +(denoted by \fnregion). +If \gls{TrackLocale} is used with just the language \idx{ISO} code, +no region is tracked for that language. For example +\begin{codebox} +\gls{TrackLocale}\marg{\opt{manx}} +\end{codebox} +will track the \optfmt{IM} (Isle of Man) \idxn{3166-1} code but +\begin{codebox} +\gls{TrackLocale}\marg{gv} +\end{codebox} +won't track the region. +Similarly for \gls{TrackLanguageTag}. + +(New to version 1.3.) +There's a similar command to \gls{TrackLocale} that doesn't take an argument: +\cmddef{TrackLangFromEnv} +If the \idx{shellescape} has been enabled or \gls{directlua} is +available, this will try to get the language information from the +system environment variables \envvar{LCALL} or \envvar{LANG} and, if +successful, track that. + +Since \sty{tracklang} is neither able to look up the \idx{POSIX} locale +tables nor interpret file locales, if the result is \code{C} or +\code{POSIX} or starts with a forward slash \code{/} then +the locale value is treated as empty. + +\begin{important} +Not all operating systems use environment variables for +the system locale information. For example, Windows stores the +locale information in the registry. In which case, consider +using \sty{texosquery}. +\end{important} + +If the operating system locale can't be obtained from environment variables, then +\sty{tracklang} will use \gls{TeXOSQueryLocale} as a fallback if +\sty{texosquery} has been loaded. Since \sty{texosquery} requires +both the \idx{shellescape} and the Java runtime environment, +\sty{tracklang} doesn't automatically load it. + +Plain \TeX\ example: +\begin{codebox} +\gls{input} texosquery +\gls{input} tracklang +\gls{TrackLangFromEnv} +\end{codebox} +Document build: +\begin{terminal} +\app{etex} \switch{shell-escape} \meta{filename} +\end{terminal} + +\LaTeX\ example: +\begin{codebox} +\cmd{usepackage}\marg{texosquery} +\cmd{usepackage}\marg{tracklang} +\gls{TrackLangFromEnv} +\end{codebox} +Document build: +\begin{terminal} +\app{pdflatex} \switch{shell-escape} \meta{filename} +\end{terminal} + +If the locale can't be determined, there will be warning messages. +These can be suppressed using +\cmddef{TrackLangShowWarningsfalse} +or switched back on again using +\cmddef{TrackLangShowWarningstrue} + +For example, I have the environment variable \envvar{LANG} set to +\code{en\idx{underscoresep}GB\idx{dotsep}utf8} on my Linux system so instead of +\begin{codebox} +\gls{TrackPredefinedDialect}\marg{\opt{british}} +\end{codebox} +I can use +\begin{codebox} +\gls{TrackLangFromEnv} +\end{codebox} + +With \LaTeX\ documents I can do +\begin{codebox} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\marg{tracklang} +\gls{TrackLangFromEnv} +\end{codebox} +However, this only helps subsequently loaded packages that +use \sty{tracklang} to determine the required regional +settings. For example: +\begin{codebox} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\marg{tracklang} +\gls{TrackLangFromEnv} +\cmd{usepackage}[useregional]\marg{datetime2} +\end{codebox} +In my case, with the \envvar{LANG} environment variable set to +\code{en\idx{underscoresep}GB\idx{dotsep}utf8} and the +\idx{shellescape} enabled, this automatically switches on the +\opt{en-GB} date style. +Naturally this doesn't help locale-sensitive packages that don't use +\sty{tracklang}. + +The \gls{TrackLangFromEnv} command also incidentally sets +\gls{TrackLangEnv} +to the value of the environment variable or empty if the +query was unsuccessful (for example, the \idx{shellescape} is +unavailable). + +If the command: +\cmddef{TrackLangEnv} +is already defined before \gls{TrackLangFromEnv} is used, then the +environment variable won't be queried and the value of +\gls{TrackLangEnv} will be parsed instead. + +\begin{important} +The parser which splits the locale string into +its component parts first tries splitting on the underscore +\idx{underscoresep} with its usual category code~8, then tries splitting +on a hyphen \idx{hyphensep} with category code~12, and then tries +splitting on the underscore \idx{underscoresep} with category code~12. +\end{important} + +For example: +\begin{codebox} +\cmd{def}\gls{TrackLangEnv}\marg{en-GB} +\gls{TrackLangFromEnv} +\end{codebox} +This doesn't perform a \idx{shellescape} since \gls{TrackLangEnv} +is already defined. In this case, you may just as well use: +\begin{codebox} +\gls{TrackLocale}\marg{en-GB} +\end{codebox} +(unless you happen to additionally require the component +commands that are set by \gls{TrackLangFromEnv}, see below.) + +If the \idx{shellescape} is unavailable +(for example, your \TeX\ installation prohibits it), you +can set this value when you invoke \TeX. For example, +if the document file is called \filefmt{myDoc.tex} (and it's +in Plain \TeX): +\begin{terminal} +\app{tex} "\idx{escbsl}def\idx{escbsl}\glscsname{TrackLangEnv}\marg{\idx{dollarenv}\envvar{LANG}}\idx{escbsl}\glscsname{input} myDoc" +\end{terminal} + +The \gls{TrackLangFromEnv} command also happens to store the +component parts of the environment variable value in the +following commands. (These aren't provided by \gls{TrackLocale}.) +If the information is unavailable, the relevant commands will be set +to empty. + +The language code is stored in: +\cmddef{TrackLangEnvLang} + +The \idx{territory} (if present) is stored in: +\cmddef{TrackLangEnvTerritory} + +The \idx{code-set} (if present) is stored in: +\cmddef{TrackLangEnvCodeSet} + +The \idx{modifier} (if present) is stored in: +\cmddef{TrackLangEnvModifier} + +If you want to query the language environment, but don't +want to track the result, you can just use: +\cmddef{TrackLangQueryEnv} +This only tries to fetch the value of the +language environment variable (and use \sty{texosquery} as +a fallback, if it has been loaded). It doesn't try to parse the +result. The result is stored in \gls{TrackLangEnv} (empty if +unsuccessful). Unlike \gls{TrackLangFromEnv}, this doesn't check if +\gls{TrackLangEnv} already exists. A warning will occur if the shell +escape is unavailable. For systems that store the locale information in +environment variables, this is more efficient than using +\sty{texosquery}'s \gls{TeXOSQueryLocale} command (which is what's +used as the fallback). + +The above queries \envvar{LCALL} and, if that is unsuccessful, +then queries \envvar{LANG} (before optionally falling back on +\sty{texosquery}). If you want another environment +variable tried after \envvar{LCALL} and before \envvar{LANG}, +you can instead use: +\cmddef{TrackLangQueryOtherEnv} +For example, to also query \envvar{LCMONETARY}: +\begin{codebox} +\gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}} +\end{codebox} + +Since this sets \gls{TrackLangEnv}, you can use it before +\gls{TrackLangFromEnv}. For example: +\begin{codebox} +\gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}} +\gls{TrackLangFromEnv} +\end{codebox} +Remember that if you only want to do the \idx{shellescape} if +\gls{TrackLangEnv} hasn't already been defined, you can test for this +first: +\begin{codebox} +\cmd{ifx}\gls{TrackLangEnv}\cmd{undefined} + \gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}} +\cmd{fi} +\gls{TrackLangFromEnv} +\end{codebox} + +It's also possible to just parse the value of \gls{TrackLangEnv} +without tracking the result using: +\cmddef{TrackLangParseFromEnv} +This is like \gls{TrackLangFromEnv} but assumes that +\gls{TrackLangEnv} has already been set and doesn't track the +result. The component parts are stored as for \gls{TrackLangFromEnv}. + +Example (Plain \TeX): +\begin{codebox} +\gls{input} tracklang +\codepar +\cmd{def}\gls{TrackLangEnv}\marg{fr\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro} +\codepar +\gls{TrackLangParseFromEnv} +\codepar +Language: \gls{TrackLangEnvLang}. +Territory: \gls{TrackLangEnvTerritory}. +Codeset: \gls{TrackLangEnvCodeSet}. +Modifier: \gls{TrackLangEnvModifier}. +Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}. +\end{codebox} +This produces: +\begin{resultbox} +Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. +Any tracked languages? No. +\end{resultbox} + +Compare this with: +\begin{codebox} +\gls{input} tracklang +\codepar +\cmd{def}\gls{TrackLangEnv}\marg{fr\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro} +\codepar +\gls{TrackLangFromEnv} +\codepar +Language: \gls{TrackLangEnvLang}. +Territory: \gls{TrackLangEnvTerritory}. +Codeset: \gls{TrackLangEnvCodeSet}. +Modifier: \gls{TrackLangEnvModifier}. +Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}. +Tracked dialect(s):\comment{} +\gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\cmd{space}\cmd{thisdialect}}. +\end{codebox} +This produces: + +\begin{resultbox} +Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. +Any tracked languages? Yes. +Tracked dialect(s): belgique. +\end{resultbox} + +If \gls{TrackLangFromEnv} doesn't recognise the given language and +territory combination, it will define a new dialect and add that. + +For example, \sty{tracklang} doesn't recognise \code{en-BE}, so +the sample document below defines a new dialect labelled +\code{enBEeuro}: +\begin{codebox} +\gls{input} tracklang +\codepar +\cmd{def}\gls{TrackLangEnv}\marg{en\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro} +\codepar +\gls{TrackLangFromEnv} +\codepar +Language: \gls{TrackLangEnvLang}. +Territory: \gls{TrackLangEnvTerritory}. +Codeset: \gls{TrackLangEnvCodeSet}. +Modifier: \gls{TrackLangEnvModifier}. +Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}. +Tracked dialect(s):\comment{} +\gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\cmd{space}\cmd{thisdialect}}. +\end{codebox} +This now produces: +\begin{resultbox} +Language: en. Territory: BE. Codeset: utf8. Modifier: euro. +Any tracked languages? Yes. +Tracked dialect(s): enBEeuro. +\end{resultbox} + +\chapter{Supplementary Packages} +\label{sec:supplpkgs} + +In addition to the main \file{tracklang.tex} file and +\file{tracklang.sty} \LaTeX\ wrapper, the \sty{tracklang} package +also provides supplementary files for region and script mappings. + +\filedef{tracklang-region-codes.tex} +This file is only loaded if a mapping is required between numeric +and alphabetic \idx{region} codes. If \gls{TrackLanguageTag} +encounters a numeric \idx{region} code, it will automatically input +\file{tracklang-region-codes.tex}, if it hasn't already been input. +This file provides the following commands. + +\cmddef{TrackLangAlphaIIToNumericRegion} +Expands to the numeric code corresponding to the given alpha-2 code or +empty if no mapping has been supplied. + +\cmddef{TrackLangNumericToAlphaIIRegion} +Expands to the alpha-2 code corresponding to the given numeric code or +empty if no mapping has been supplied. + +\cmddef{TrackLangIfKnownAlphaIIRegion} +Expands to \meta{true} if there's an alpha-2 to numeric \idx{region} +code mapping, otherwise expands to \meta{false}. + +\cmddef{TrackLangIfKnownNumericRegion} +Expands to \meta{true} if there's a numeric to alpha-2 \idx{region} +code mapping, otherwise expands to \meta{false}. + +\cmddef{TrackLangAlphaIIIToNumericRegion} +Expands to the numeric code corresponding to the given alpha-3 code or +empty if no mapping has been supplied. + +\cmddef{TrackLangNumericToAlphaIIIRegion} +Expands to the alpha-3 code corresponding to the given numeric code or +empty if no mapping has been supplied. + +\cmddef{TrackLangIfKnownAlphaIIIRegion} +Expands to \meta{true} if there's an alpha-3 to numeric \idx{region} +code mapping, otherwise expands to \meta{false}. + +Mappings are established with: +\cmddef{TrackLangRegionMap} +Predefined mappings are listed in \tableref{tab:regionmappings}. + +When \file{tracklang-region-codes.tex} is input, it can load +additional files that provide supplementary mappings. + +\cmddef{TrackLangAddExtraRegionFile} +This command adds the supplied \meta{file} to the list of extra +region code files that should be input by +\file{tracklang-region-codes.tex}, unless +\file{tracklang-region-codes.tex} has already been input, in which +case \meta{file} will be input straight away. + +\filedef{tracklang-scripts.tex} +The \sty{tracklang-scripts} package provides information about +\idxn{15924} scripts. The file isn't automatically loaded. If +you want to use any of the commands provided in it you need to input +it. + +Plain \TeX: +\begin{codebox} +\gls{input} tracklang-scripts +\end{codebox} +There's a simple wrapper package \file{tracklang-scripts.sty} for +\LaTeX\ users: +\begin{codebox} +\cmd{usepackage}\marg{tracklang-scripts} +\end{codebox} + +\cmddef{TrackLangScriptMap} +Defines a mapping. The first argument is the four letter alpha code, +such as \opt{Latn} or \opt{Cyrl}. The second argument is the numeric +code. The third argument is the script's name, for example +\qt{Imperial Aramaic}. The fourth argument is the direction, which +may be one of: \optfmt{LR} (left-to-right), \optfmt{RL} (right-to-left), +\optfmt{TB} (top-to-bottom), \optfmt{varies} or \optfmt{inherited}. +The \meta{parent} argument is for the parent writing system, which +may be left blank (currently unsupported). + +This command defines: +\cmddef{TrackLangScriptCode} +which expands to \meta{Code} for use with \gls{IfTrackedDialectIsScriptCs}. + +See \tableref{tab:scriptmappings} for a summary of all the mappings +that are provided by the file \file{tracklang-scripts.tex}. + +\cmddef{TrackLangScriptAlphaToNumeric} +Expands to the numeric code corresponding to the given alpha code or +empty if no mapping. + +\cmddef{TrackLangScriptIfKnownAlpha} +Expands to \meta{true} if there is a known alpha to numeric mapping +or \meta{false} otherwise. + +\cmddef{TrackLangScriptNumericToAlpha} +Expands to the alpha code corresponding to the given numeric code or +empty if no mapping. + +\cmddef{TrackLangScriptIfKnownNumeric} +Expands to \meta{true} if there is a known numeric to alpha mapping +or \meta{false} otherwise. + +\cmddef{TrackLangScriptAlphaToName} +Expands to the name corresponding to the given alpha code or +empty if no mapping. + +\cmddef{TrackLangScriptAlphaToDir} +Expands to the direction corresponding to the given alpha code or +empty if no mapping. + +\cmddef{TrackLangScriptSetParent} +Sets the parent for the given alpha code. + +\cmddef{TrackLangScriptGetParent} +Expands to the parent for the given alpha code or empty if no +mapping. + +\cmddef{TrackLangScriptIfHasParent} +Expands to \meta{true} if the given alpha code has a parent +or to \meta{false} otherwise. Note that if a parent is explicitly +set to empty with \gls{TrackLangScriptSetParent} then it will be +considered defined, but if the \meta{parent} argument was empty in +\gls{TrackLangScriptMap}, then it will be undefined. + +\cmddef{TrackLangAddExtraScriptFile} +This command adds \meta{file} to the list of extra script files that should +be input by \file{tracklang-scripts.tex}, unless +\file{tracklang-scripts.tex} has already been input, in which +case \meta{file} will be input straight away. + + +\chapter{Detecting the User's Requested Languages} +\label{sec:user} + +The \sty{tracklang} package tries to track the loaded languages and +the option names used to identify those languages. For want of a better +term, the language option names are referred to as dialects even if +they're only a synonym for the language rather than an actual +dialect. For example, if the user +has requested \opt{british}, the \emph{root language} label is +\opt{english} and the dialect is \opt{british}, whereas if the +user requested \opt{UKenglish}, the root language label is +\opt{english} and the dialect is \opt{UKenglish}. The +exceptions to this are the \sty{tracklang} package options that have been +specified in the form \meta{iso lang}-\meta{iso country} (listed +in \tableref{tab:rootlangopts}). For +example, the package option \iso{british} behaves as though the +user requested the package option \opt{british}. + +If \gls{TrackLocale} or \gls{TrackLangFromEnv} are used and the locale +isn't recognised a new dialect is created with the label formed from +the \idx{ISO} codes (and \idx{modifier}, if present). +Similarly for \gls{TrackLanguageTag} a new +dialect is created with a label that's essentially the language tag +without the hyphen separators. For example, +\begin{codebox} +\gls{TrackLocale}\marg{xx\idx{hyphensep}YY} +\end{codebox} +will add a new dialect with the label \code{xxYY}, +\begin{codebox} +\gls{TrackLocale}\marg{xx\idx{hyphensep}YY\idx{atmod}mod} +\end{codebox} +will add a new dialect with the label \code{xxYYmod} and +\begin{codebox} +\gls{TrackLanguageTag}\marg{xx-Latn-YY} +\end{codebox} +will add a new dialect with the label \code{xxLatnYY}. + +\begin{important} +If \gls{TrackLocale} or \gls{TrackLangFromEnv} find a \idx{modifier}, the +value will be sanitized to allow it to be used as a label. If the +modifier is set explicitly using \gls{SetTrackedDialectModifier}, +no sanitization is performed. +\end{important} + +In addition to the root language label and the dialect identifier, +many of the language options also have corresponding \idx{ISO} codes. In +most cases there is an \idxn{639-1} or an \idxn{639-2} code (or both), and in some +cases there is an \idxn{3166-1} code identifying the dialect \idx{region}. +Where a language has different \idxn{639-2T} and \idx{639-2B} codes, +the \qt{T} version is assumed. + +When the \file{tracklang.sty} \LaTeX\ package is loaded, it first attempts to find the +language options through the package options supplied to +\sty{tracklang}. This means that any languages that have been +supplied in the document class options should get identified +(provided that the document class has used the standard option +declaration mechanism). If no languages have been supplied in this +way, \file{tracklang.sty} then attempts to identify language settings in +the following order: +\begin{enumerate} +\item if \gls{bbl@loaded} is defined (\sty{babel}), \sty{tracklang} +will iterate over each label in that command definition; + +\item if \gls{trans@languages} is defined (\sty{translator}), +\sty{tracklang} will iterate over each label in that command +definition; + +\item if \sty{ngerman} has been loaded, the \opt{ngerman} dialect +will be tracked; + +\item if \sty{german} has been loaded, the \opt{german} root +language will be tracked; + +\item if \sty{polyglossia} has been loaded: + + \begin{enumerate} + \item if \gls{xpg@bcp@loaded} has been defined, \sty{tracklang} +will iterate over the \idx{BCP47} tags in that command definition; + + \item if \gls{xpg@loaded} has been defined, \sty{tracklang} will +iterate over each language label in that command definition; + + \item \sty{tracklang} will iterate over all \sty{tracklang} options +and test if the root language has been loaded. + \end{enumerate} + +\end{enumerate} +Note that this references internal commands provided by other +packages. Of these, only the \sty{polyglossia} commands are +documented in the package manual, and so are the only ones that can +be relied on. + +Each identified language and dialect is added to the \emph{tracked +language} and \emph{tracked dialect} lists. Note that the tracked +language and tracked dialect are labels rather than proper nouns. +If a~dialect label is identical to its root language label, the +label will appear in both lists. + +You can check whether or not any languages have been detected using: +\cmddef{AnyTrackedLanguages} +This will do \meta{true} if one or more languages have been +tracked otherwise it will do \meta{false}. (Each detected +dialect will automatically have the root language label added +to the tracked language list, if it's not already present.) + +If you want to find out if any of the tracked dialects +matches a particular language tag, you can use: +\cmddef{GetTrackedDialectFromLanguageTag} +If successful, the supplied control sequence \meta{cs} is set to the +dialect label, otherwise \meta{cs} is set to empty. The test is for an exact +match on the root language, \idx{script}, sub-language, \idx{variant} and +\idx{region}. The control sequence \meta{cs} will be empty if none of the +tracked dialects matches all five of those elements. (If the script +isn't given explicitly, the default for that language is assumed.) +In the event that \meta{cs} is empty, you can now (as from v1.3.6) +get the closest match with: +\cmddef{TrackedDialectClosestSubMatch} +(which is set by \gls{GetTrackedDialectFromLanguageTag}). +This will be empty if no tracked dialects match on the root +language or if there's a tracked dialect label that exactly matches +the label formed by concatenating the language code, sub-language, +\idx{script}, \idx{region}, \idx{modifier} and \idx{variant}. + +For example (Plain \TeX): +\begin{codebox} +\gls{input} tracklang +\gls{TrackLanguageTag}\marg{en-826} +Has en-Latn-GB been tracked? +\gls{GetTrackedDialectFromLanguageTag}\marg{en-Latn-GB}\marg{\cmd{thisdialect}}\comment{} +\cmd{ifx}\cmd{thisdialect}\cmd{empty} + No! +\cmd{else} + Yes! Dialect label: \cmd{thisdialect}. +\cmd{fi} +\cmd{bye} +\end{codebox} +This matches because the \idx{territory} code \numericcode{GB} is recognised as +equivalent to the code \opt{GB}, and the default \idx{script} for +\opt{english} is \opt{Latn}. In this case, the dialect +label is \opt{british}. Note that this doesn't require +the use of \gls{TrackLanguageTag} to track the dialect. +It also works if the dialect has been tracked using other commands, +such as \gls{TrackLocale}. + +Here's an example that doesn't have an exact match, but does have a +partial match: +\begin{codebox} +\gls{input} tracklang +\gls{TrackLanguageTag}\marg{de-CH-1996} +Has de-DE-1996 been tracked? +\gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{thisdialect}}\comment{} +\cmd{ifx}\cmd{thisdialect}\cmd{empty} + No! + \cmd{ifx}\gls{TrackedDialectClosestSubMatch}\cmd{empty} + No match on root language. + \cmd{else} + Closest match: \gls{TrackedDialectClosestSubMatch}. + \cmd{fi} +\cmd{else} + Yes! Dialect label: \cmd{thisdialect}. +\cmd{fi} +\cmd{bye} +\end{codebox} +In this case the result is: +\begin{resultbox} +Has de-DE-1996 been tracked? No! Closest match: nswissgerman. +\end{resultbox} + +You can iterate through each tracked dialect using: +\cmddef{ForEachTrackedDialect} +At the start of each iteration, this sets the control sequence +\meta{cs} to the tracked dialect and does \meta{body}. + +You can iterate through each tracked language using: +\cmddef{ForEachTrackedLanguage} +At the start of each iteration, this sets the control sequence \meta{cs} to the +tracked language and does \meta{body}. + +The above for-loops use the same internal mechanism as \LaTeX's +\gls{@for} loop. Since this isn't defined by \TeX, a similar command +(\inlineglsdef{@tracklang@for}) will be defined that works in the same way. + +The provided control sequence \meta{cs} is updated at the +start of each iteration to the current element. The loop is +terminated when this control sequence is set to \gls{@nil}. This +special control sequence should never been used as it's just a +marker and isn't actually defined. If you get an error message +stating that \gls{@nil} is undefined, then it's most likely due to a +loop control sequence being used outside the loop. This can occur if +the loop contains code that isn't expanded until later. For example, +if the loop code includes \gls{AtBeginDocument}, you need to ensure +that the loop control sequence is expanded before being added to the +hook. + +You can test if a root language has been detected using: +\cmddef{IfTrackedLanguage} +where \meta{language-label} is the language label. If +true, this does \meta{true} otherwise it does \meta{false}. + +You can test if a particular dialect has been detected using: +\cmddef{IfTrackedDialect} +where \meta{dialect-label} is the dialect label. If the root +language was explicitly specified, then it will also be detected as +a dialect. + +For example: +\begin{codebox} +\cmd{documentclass}[\opt{british},\opt{dutch}]\marg{article} +\codepar +\cmd{usepackage}\marg{tracklang} +\codepar +\cbeg{document} +``english'' \gls{IfTrackedDialect}\marg{english}\marg{has}\marg{hasn't} been specified. +\codepar +``british'' \gls{IfTrackedDialect}\marg{british}\marg{has}\marg{hasn't} been specified. +\codepar +``flemish'' \gls{IfTrackedDialect}\marg{flemish}\marg{has}\marg{hasn't} been specified. +\codepar +``dutch'' \gls{IfTrackedDialect}\marg{dutch}\marg{has}\marg{hasn't} been specified. +\codepar +``english'' or an English variant +\gls{IfTrackedLanguage}\marg{english}\marg{has}\marg{hasn't} been specified. +\cend{document} +\end{codebox} +This produces: +\begin{resultbox} +``english'' hasn't been specified. + +``british'' has been specified. + +``flemish'' hasn't been specified. + +``dutch'' has been specified. + +``english'' or an English variant has been specified. +\end{resultbox} + +You can find the root language label for a given tracked dialect +using: +\cmddef{TrackedLanguageFromDialect} +If \meta{dialect} hasn't been defined this does nothing otherwise it +expands to the root language label. + +You can find the tracked dialects from a given root language +using: +\cmddef{TrackedDialectsFromLanguage} +This will expand to a~comma-separated list of dialect labels +if the root language label has been defined, otherwise it +does nothing. + +You can test if a language or dialect has a corresponding \idx+{ISO} code using: +\cmddef{IfTrackedLanguageHasIsoCode} +where \meta{code type} is the type of \idx{ISO} code (for example, +\idx{639-1} for root languages or \idx{3166-1} for regional +dialects), and \meta{label} is the language or dialect label. +Note that the \idx{639-3} may be set for the dialect +rather than root language for sub-languages parsed using +\gls{TrackLanguageTag}. + +Alternatively, you can test if a particular \idx{ISO} code has been +defined using: +\cmddef{IfTrackedIsoCode} +where \meta{code type} is again the type of \idx{ISO} code (for example, +\idx{639-1} or \idx{3166-1}), and \meta{code} is the +particular code (for example, \opt{en} for \idxn{639-1} or +\opt{GB} for \idxn{3166-1}). + +You can fetch the language (or dialect) label associated with a +given \idx{ISO} code using: +\cmddef{TrackedLanguageFromIsoCode} +This does nothing if the given \meta{code} for the given \idx{ISO} +\meta{code type} has not been defined, otherwise it expands +a~comma-separated list of language or dialect labels. + +You can fetch the \idx{ISO} code for a given code type using: +\cmddef{TrackedIsoCodeFromLanguage} +where \meta{label} is the language or dialect label and \meta{code +type} is the \idx{ISO} code type (for example, \idx{639-1} or +\idx{3166-1}). Unlike \gls{TrackedLanguageFromIsoCode}, this +command only expands to a single label rather than a~comma-separated +list. + +The above commands do nothing in the event of an unknown code or +code type, +so if you accidentally get the wrong code type, you won't get an error. +If you're unsure of the code type, you can use the following commands: +\cmddef{TwoLetterIsoCountryCode} +This expands to \idx{3166-1} and is used for the two-letter country codes. + +\cmddef{TwoLetterIsoLanguageCode} +This expands to \idx{639-1} and is used for the two-letter root language codes. + +\cmddef{ThreeLetterIsoLanguageCode} +This expands to \idx{639-2} and is used for the three-letter root language +codes. + +\cmddef{ThreeLetterExtIsoLanguageCode} +This expands to \idx{639-3}. This code is only used for a root language if +there's no \idx{639-1} or \idx{639-2} code. It may also be used for a +dialect if a sub-language part has been set in the language +tag parsed by \gls{TrackLanguageTag}. + +The \cmd{Get\ldots} commands below are designed to be expandable. +If the supplied \meta{dialect} is unrecognised they expand to empty. +Remember that the dialect must first be identified as a tracked +language for it to be recognised. + +As from v1.3, the language tag for a given dialect can be obtained +using: +\cmddef{GetTrackedLanguageTag} +where \meta{dialect} is the label identifying the dialect. +Uses the \opt{und} (undetermined) code for unknown languages. + +As from v1.3, each tracked dialect may also have an associated +modifier, which can be fetched using: +\cmddef{GetTrackedDialectModifier} +where \meta{dialect} is the label identifying the dialect. +This value is typically obtained by parsing a \idx{POSIX} locale identifier +with \gls{TrackLocale} or \gls{TrackLangFromEnv} but may be set explicitly. +(See \sectionref{sec:langsty} for setting this value. Likewise for +the following commands.) + +You can test if a dialect has an associated \idx{modifier} using: +\cmddef{IfHasTrackedDialectModifier} +If the dialect has an associated \idx{modifier} this does \meta{true} +otherwise it does \meta{false}. + +For example: +\begin{codebox} +\cmd{documentclass}[\opt{british},\opt{francais},\opt{american},\opt{canadian},\opt{canadien},\opt{dutch}]\marg{article} +\codepar +\cmd{usepackage}\marg{tracklang} +\codepar +\cbeg{document} +Languages: +\gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\marg{\cmd{ThisLanguage}\cmd{space} +(ISO \gls{TwoLetterIsoLanguageCode}: +``\gls{TrackedIsoCodeFromLanguage}\marg{\gls{TwoLetterIsoLanguageCode}}\marg{\cmd{ThisLanguage}}''). } +\codepar +Dialects: +\gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\marg{\cmd{ThisDialect}\cmd{space} +(\gls{IfTrackedLanguageHasIsoCode}\marg{\gls{TwoLetterIsoCountryCode}}\marg{\cmd{ThisDialect}}\comment{} + \marg{ISO \gls{TwoLetterIsoCountryCode}: + ``\gls{TrackedIsoCodeFromLanguage}\marg{\gls{TwoLetterIsoCountryCode}}\marg{\cmd{ThisDialect}}''}% + \marg{no specific region}; +root: \gls{TrackedLanguageFromDialect}\marg{\cmd{ThisDialect}}). } +\codepar +Language for ISO \gls{TwoLetterIsoCountryCode}\cmd{ }``GB'': +\gls{TrackedLanguageFromIsoCode}\marg{\gls{TwoLetterIsoCountryCode}}\marg{GB}. +\codepar +Language for ISO \gls{TwoLetterIsoCountryCode}\cmd{ }``CA'': +\gls{TrackedLanguageFromIsoCode}\marg{\gls{TwoLetterIsoCountryCode}}\marg{CA}. +\codepar +Country ISO \gls{TwoLetterIsoCountryCode}\cmd{ }code for ``canadian'': +\gls{TrackedIsoCodeFromLanguage}\marg{\gls{TwoLetterIsoCountryCode}}\marg{canadian}. +\cend{document} +\end{codebox} +This produces: +\begin{resultbox} +Languages: english (ISO 639-1: ``en''). french (ISO 639-1: ``fr''). +dutch (ISO 639-1: ``nl''). + +Dialects: american (ISO 3166-1: ``US''; root: english). +british (ISO 3166-1: ``GB''; root: english). +canadian (ISO 3166-1: ``CA''; root: english). +canadien (ISO 3166-1: ``CA''; root: french). +dutch (no specific region; root: dutch). +francais (no specific region; root: french). + +Language for ISO 3166-1 ``GB'': british. + +Language for ISO 3166-1 ``CA'': canadian,canadien. + +Country ISO 3166-1 code for ``canadian'': CA. +\end{resultbox} + +As from v1.3, each tracked dialect may also have an associated +variant, which can be fetched using: +\cmddef{GetTrackedDialectVariant} +where \meta{dialect} is the label identifying the dialect. +This value is typically obtained by parsing a language tag +with \gls{TrackLanguageTag} but may be set explicitly. + +You can test if a dialect has an associated variant using: +\cmddef{IfHasTrackedDialectVariant} + +As from v1.3, each tracked dialect may also have an associated +script, which can be fetched using: +\cmddef{GetTrackedDialectScript} +where \meta{dialect} is the label identifying the dialect. + +You can test if a dialect has an associated script using: +\cmddef{IfHasTrackedDialectScript} +If the dialect has an associated script this does \meta{true} +otherwise it does \meta{false}. This information is provided +for language packages that need to know what script is required, +but there's no guarantee that the script will actually be set +in the document. Similarly for all the other attributes described +here. + +Note that the script should be a recognised four-letter \idxn{15924} +code, such as \opt{Latn} or \opt{Cyrl}. If a~dialect +doesn't have an associated script then the default for the root +language should be assumed. For example, \opt{Latn} for English dialects or +\opt{Cyrl} for Russian dialects. The default script for +known languages can be obtained using: +\cmddef{TrackLangGetDefaultScript} +Most root languages have a default script, but there +are a few without one as it may depend on region, politics +or ideology. + +There's a convenient expandable command for testing the script: +\cmddef{IfTrackedDialectIsScriptCs} +This tests if the given tracked dialect has an associated script and +compares the value with the replacement text of \meta{cs}. +If the dialect hasn't been explicitly assigned a script, +then test is performed against the default script for the root +language. + +The supplementary package \sty{tracklang-scripts} provides some +additional commands relating to writing systems, including commands +in the form \gls{TrackLangScriptCode} where +\meta{Code} is the \idxn{15924} four-letter code. If the dialect +doesn't have an associated script, \meta{false} is done. +This package isn't +loaded automatically, so you'll need to explicitly load it. The +generic code is in \file{tracklang-scripts.tex}: +\begin{codebox} +\gls{input} tracklang-scripts +\end{codebox} +There's a convenient \LaTeX\ wrapper \file{tracklang-scripts.sty}: +\begin{codebox} +\cmd{usepackage}\marg{tracklang-scripts} +\end{codebox} +See \sectionref{sec:supplpkgs} for further details of +that package. + +For example, the following defines a command to check if +the given dialect should use a Latin \idx{script}: +\begin{codebox} +\gls{input} tracklang-scripts +\cmd{def}\cmd{islatin}\#1\#2\#3\marg{\comment{} + \gls{IfTrackedDialectIsScriptCs}\marg{\#1}\marg{\tklscript{Latn}}\marg{\#2}\marg{\#3}\comment{} +} +\end{codebox} + +\begin{important} +Note that the \idx{script} value doesn't mean that the document is +actually using that script. It means that this is the user's +\emph{desired} script, but whether that \idx{script} is actually set relies +on the appropriate settings in the relevant language package (such +as \sty{polyglossia}['s] \optfmt{script} key). +\end{important} + +As from v1.3, each tracked dialect may also have a sub-language +identifier (for example, \optfmt{arevela}), which can be fetched +using: +\cmddef{GetTrackedDialectSubLang} +where \meta{dialect} is the label identifying the dialect. + +You can test if a dialect has an associated sub-tag using: +\cmddef{IfHasTrackedDialectSubLang} +If the dialect has an associated sub-tag this does \meta{true} +otherwise it does \meta{false}. + +As from v1.3, each tracked dialect may also have additional +information, which can be fetched using: +\cmddef{GetTrackedDialectAdditional} +where \meta{dialect} is the label identifying the dialect. + +You can test if a dialect has additional information using: +\cmddef{IfHasTrackedDialectAdditional} +If the dialect has additional information this does \meta{true} +otherwise it does \meta{false}. + +Most packages that implement multilingual support have a~set of +language definition files for each supported language or dialect. +It may be that only the root language is needed, if there are no +variations between that language's dialect (for the purposes of that +package), or it may be that separate definition files are required +for each dialect. However it can be awkward trying to map the +requested dialect or language label to the file name. Should, say, +the file containing the French code be called +\metametafilefmt{}{prefix}{\dhyphen french\dhyphen }{suffix}{} or +\metametafilefmt{}{prefix}{\dhyphen frenchb\dhyphen }{suffix}{} or +\metametafilefmt{}{prefix}{\dhyphen francais\dhyphen}{suffix}{}? +Should, say, the file containing the British English code be called +\metametafilefmt{}{prefix}{\dhyphen british\dhyphen }{suffix}{} or +\metametafilefmt{}{prefix}{\dhyphen UKenglish\dhyphen }{suffix}{}? +If you want to modularise the language support for your package so +that each language module has a different maintainer will the +maintainers know what tag to use for their language? + +\label{pg:filesearch}To help with this, \sty{tracklang} provides: +\cmddef{IfTrackedLanguageFileExists} +This attempts to find the file called +\meta{prefix}\meta{localeid}\meta{suffix} where \meta{localeid} is determined +from \meta{dialect} (see below). If the file is found then +\cmddef{CurrentTrackedTag} +is set to \meta{localeid} and \meta{true code} is done, otherwise +\meta{false code} is done. If this command +is empty, then the dialect hasn't been detected. If the dialect +has been detected, but no file can be found, then +\gls{CurrentTrackedTag} is set to the final attempt at determining +\meta{localeid}. + +There's a convenient shortcut command new to version 1.3: +\cmddef{TrackLangRequireDialect} +which uses \gls{IfTrackedLanguageFileExists} to input the resource +file if found. The prefix is given by \meta{pkgname}\code{-} and +the suffix is \code{.\ext+{ldf}}. A warning is issued if no resource file +is found. Note that while it makes sense for \meta{pkgname} +to be the same as the base name of the package that uses these +resource files, they don't have to be the same. This command +additionally defines: +\cmddef{TrackLangRequireDialectPrefix} +to \meta{pkgname}, which allows the prefix to be picked up by +resource file commands, such as \gls{TrackLangProvidesResource} +and \gls{TrackLangRequireResource}. (See below.) + +The optional argument \meta{load code} is the code that actually +inputs the required file. This defaults to +\begin{codebox} +\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} +\end{codebox} + +The \gls{IfTrackedLanguageFileExists} command sets up the current +tracked dialect with: +\begin{compactcodebox*} +\gls{SetCurrentTrackedDialect}\marg{dialect} +\end{compactcodebox*} +which enables the following commands that may be used within +\meta{true code} or \meta{false code}: +\cmddef{CurrentTrackedDialect} +Expands to the dialect label. + +\cmddef{CurrentTrackedLanguage} +If the dialect hasn't been detected, this command will be empty, +otherwise it will expand to the root language label (which may +be the same as the dialect label). + +\cmddef{CurrentTrackedRegion} +If the dialect hasn't been detected, this command will be empty. +If the dialect has been assigned an \idxn{3166-1} code, +\gls{CurrentTrackedRegion} will expand to that code, otherwise it +will be empty. + +\cmddef{CurrentTrackedIsoCode} +If the dialect hasn't been detected, this command will be empty. +Otherwise it may be empty or it may expand to the +\idxn{639-1} or \idxn{639-2} or \idxn{639-3} code. + +\cmddef{CurrentTrackedDialectModifier} +The dialect's modifier or empty if not set. (This is set but not +used in the set of possible \meta{localeid} values.) + +\cmddef{CurrentTrackedDialectVariant} +The dialect's variant or empty if not set. + +\cmddef{CurrentTrackedDialectSubLang} +The dialect's sub-language code or empty if not set. + +\cmddef{CurrentTrackedDialectAdditional} +The dialect's additional information or empty if not set. + +\cmddef{CurrentTrackedLanguageTag} +The dialect's language tag. Take care not to confuse this +with \gls{CurrentTrackedTag}. + +\cmddef{CurrentTrackedDialectScript} +The dialect's script. If the dialect doesn't have the script set, +the default script for the language is used instead. + +\gls{IfTrackedLanguageFileExists} behaves as follows: +\begin{itemize} + \item If no dialect with the given label has been + detected, the condition evaluates to \emph{false} and + \gls{CurrentTrackedTag} is empty. + + \item If a dialect with the given label has been detected, then: + \begin{itemize} + \item For each possible \meta{localeid} in an ordered set of tags determined by + the dialect label (see below), the first file matching + \meta{prefix}\meta{localeid}\meta{suffix} that's found on + \TeX's path results in the condition evaluating to \emph{true} and + \gls{CurrentTrackedTag} is set to the current \meta{localeid} in the + set. The rest of the set of possible values of \meta{localeid} is skipped. + + \item If no file matching \meta{prefix}\meta{localeid}\meta{suffix} is + found on \TeX's path, then the condition evaluates to \emph{false} + and \gls{CurrentTrackedTag} is set to the final \meta{localeid} in the + set (the language label). + \end{itemize} +\end{itemize} + +The ordered set of possible values of \meta{localeid} is determined from +the given dialect. +\begin{important} +The ordering has changed in version 1.4, which now also includes the +\idx{script} and \idx{variant}. This new ordering should typically make the more +common combinations closer to the start of the search. +\end{important} +The possible values of \meta{localeid} are listed below in the order of priority used +by \gls{IfTrackedLanguageFileExists}. Note that the set may contain +repetitions (for example, if the dialect label is the same as the +root language label). If an item contains an element that hasn't +been set (such as the \idxn{639-3} code or a sub-language +\meta{sublang} or \idx{variant}) then +that item is skipped. +\begin{enumerate} +\item \meta{localeid} is just the value of \gls{CurrentTrackedLanguageTag}. + +\item \meta{localeid} is just the dialect label. + +\item \meta{localeid} is +\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-1}\code{-}\meta{script}\code{-}\meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{region} (if there's no script or if +the script is the default for the given language). +\meta{ISO~639-1}\code{-}\meta{region} (if there's no script or if +the script is the default for the given language). + +\item \meta{localeid} is +\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{script}. + +\item \meta{localeid} is +\meta{ISO~639-1}\code{-}\meta{script}. + +\item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}. + +\item \meta{localeid} is just \meta{ISO~639-1}. + +\item \meta{localeid} is +\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-2}\code{-}\meta{script}\code{-}\meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\code{region} (if there's no script or if +the script is the default for the given language). +\meta{ISO~639-2}\code{-}\meta{region} (if there's no script or if +the script is the default for the given language). + +\item \meta{localeid} is +\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{script}. + +\item \meta{localeid} is +\meta{ISO~639-2}\code{-}\meta{script}. + +\item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}. +\item \meta{localeid} is just \meta{ISO~639-2}. + +\item \meta{localeid} is +\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-3}\code{-}\meta{script}\code{-}\meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{region} (if there's no script or if +the script is the default for the given language). +\meta{ISO~639-3}\code{-}\meta{region} (if there's no script or if +the script is the default for the given language). + +\item \meta{localeid} is +\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{script}. + +\item \meta{localeid} is +\meta{ISO~639-3}\code{-}\meta{script}. + +\item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}. + +\item \meta{localeid} is just \meta{ISO~639-3}. + +\item \meta{localeid} is just \meta{region}. + +\item \meta{localeid} is +\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{variant} +or \meta{ISO~639-1}\code{-}\meta{variant} if \meta{sublang} is missing. + +\item \meta{localeid} is +\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{variant} +or \meta{ISO~639-2}\code{-}\meta{variant} if \meta{sublang} is missing. + +\item \meta{localeid} is +\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{variant} +or \meta{ISO~639-3}\code{-}\meta{variant} if \meta{sublang} is missing. + +\item \meta{localeid} is just the value of \gls{CurrentTrackedLanguage} +(the root language label). +\end{enumerate} + +For example (pre v1.3): +\begin{codebox} +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\comment{} + \marg{\comment{try to load the language file for this dialect} + \gls{IfTrackedLanguageFileExists}\marg{\cmd{ThisDialect}}\comment{} + \marg{mypackage-}\comment{file prefix} + \marg{.ldf}\comment{file suffix} + \marg{\gls{input} mypackage-\gls{CurrentTrackedTag}.ldf}\comment{file found} + \marg{\comment{file not found} + \cmd{PackageWarning}\marg{mypackage}\marg{No support for language + `\cmd{ThisDialect}'}\comment{} + }\comment{} + }\comment{} +} +\marg{\comment{no languages detected so use defaults} +} +\end{codebox} +With version 1.3 onwards, this can be written more concisely as: +\begin{codebox} +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\comment{} + \marg{\comment{try to load the language file for this dialect} + \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{ThisDialect}}\comment{} + }\comment{} +} +\marg{\comment{no languages detected so use defaults} +} +\end{codebox} +which additionally enables the \sty{tracklang} version 1.3 commands described below, +such as \gls{TrackLangRequireResource}. + +\plabel{pg.britishfilesearch}% +If, for example, \cmd{ThisDialect} is \opt{british}, then the file search will +be in the order: +\begin{enumerate} +\item \ldf{mypackage}{en-GB} (language tag) +\item \ldf{mypackage}{british} (dialect label) + +\item \ldf{mypackage}{en-Latn-GB} (\idx{639-1} language code, +\idx{script}, \idx{region}) +\item \ldf{mypackage}{en-GB} (\idx{639-1} language code, +\idx{region}) +\item \ldf{mypackage}{en-Latn} (\idx{639-1} language code, +\idx{script}) +\item \ldf{mypackage}{en} (\idx{639-1} language code) + +\item \ldf{mypackage}{eng-Latn-GB} (\idx{639-2} language +code, \idx{script}, \idx{region}) +\item \ldf{mypackage}{eng-GB} (\idx{639-2} language code, +\idx{region}) +\item \ldf{mypackage}{eng-Latn} (\idx{639-2} language code, +\idx{script}) +\item \ldf{mypackage}{eng} (\idx{639-2} language code) + +\item \ldf{mypackage}{GB} (\idx{region}) +\item \ldf{mypackage}{english} (language label) +\end{enumerate} + +If, for example, \cmd{ThisDialect} is \opt{naustrian}, then the file search will +be in the order: +\begin{enumerate} +\item \ldf{mypackage}{de-AT-1996} (language tag) +\item \ldf{mypackage}{naustrian} (dialect label) + +\item \ldf{mypackage}{de-Latn-AT} (\idx{639-1} language code, +\idx{script}, \idx{region}) +\item \ldf{mypackage}{de-AT} (\idx{639-1} language code, +\idx{region}) +\item \ldf{mypackage}{de-Latn} (\idx{639-1} language code, +\idx{script}) +\item \ldf{mypackage}{de} (\idx{639-1} language code) + +\item \ldf{mypackage}{deu-Latn-AT} (\idx{639-2} language +code, \idx{script}, \idx{region}) +\item \ldf{mypackage}{deu-AT} (\idx{639-2} language code, +\idx{region}) +\item \ldf{mypackage}{deu-Latn} (\idx{639-2} language code, +\idx{script}) +\item \ldf{mypackage}{deu} (\idx{639-2} language code) + +\item \ldf{mypackage}{AT} (\idx{region}) + +\item \ldf{mypackage}{de-1996} (\idx{639-1} language code, +\idx{variant}) +\item \ldf{mypackage}{deu-1996} (\idx{639-2} language code, +\idx{variant}) + +\item \ldf{mypackage}{german} (language label) +\end{enumerate} + +If, for example, \cmd{ThisDialect} is \opt{francais}, then the file search will +be in the order: +\begin{enumerate} +\item \ldf{mypackage}{fr} (language tag) +\item \ldf{mypackage}{francais} (dialect label) +\item \ldf{mypackage}{fr-Latn} (\idx{639-1} language code, +\idx{script}) +\item \ldf{mypackage}{fr} (\idx{639-1} language code) +\item \ldf{mypackage}{fra-Latn} (\idx{639-2} language code, +\idx{script}) +\item \ldf{mypackage}{fra} (\idx{639-2} language code) +\item \ldf{mypackage}{french} (language) +\end{enumerate} +This is because the predefined \opt{francais} option has no +region assigned to it. Be careful if the dialect label is the actual +root language. For example, if \cmd{ThisDialect} is \opt{french}, +then the file search will be in the order: +\begin{enumerate} +\item \ldf{mypackage}{fr} (language tag) +\item \ldf{mypackage}{french} (dialect label) +\item \ldf{mypackage}{fr-Latn} (\idx{639-1} language code, +\idx{script}) +\item \ldf{mypackage}{fr} (\idx{639-1} language code) +\item \ldf{mypackage}{fra-Latn} (\idx{639-2} language code, +\idx{script}) +\item \ldf{mypackage}{fra} (\idx{639-2} language code) +\item \ldf{mypackage}{french} (language) +\end{enumerate} +Note that the last try will always fail in this case since if the +file exists, it will be found on the second try. + +If the dialect label is identical to the root language label then it +means that all associated information is the default +for that language. For example, in the above case of \opt{french}, +the script is \opt{Latn} and the region is unspecified. The root +language label can therefore be used as the fallback in the event of +no other match but for the specific case where the dialect is +identical to the root language then all unnecessary file name checks +can be skipped. + +If you're only providing support for the root languages (pre v1.3): +\begin{codebox} +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\comment{} + \marg{\comment{try to load the language file for this root language} + \gls{IfTrackedLanguageFileExists}\marg{\cmd{ThisLanguage}}\comment{} + \marg{mypackage-}\comment{file prefix} + \marg{.ldf}\comment{file suffix} + \marg{\gls{input} mypackage-\gls{CurrentTrackedTag}.ldf}\comment{file found} + \marg{\comment{file not found} + \cmd{PackageWarning}\marg{mypackage}\marg{No support for language + `\cmd{ThisLanguage}'}\comment{} + }\comment{} + }\comment{} +} +\marg{\comment{no languages detected so use defaults} +} +\end{codebox} +With version 1.3 onwards, this can be written more concisely as: +\begin{codebox} +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\comment{} + \marg{\comment{try to load the language file for this root language} + \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{ThisLanguage}}\comment{} + }\comment{} +} +\marg{\comment{no languages detected so use defaults} +} +\end{codebox} +which additionally enables the commands described below. +Note that in this case, if more than one dialect for the same +language has been tracked, only the hooks for the last dialect for +that language will be adjusted, so it's usually best to iterate over +the dialects. + +The following \cmd{TrackLang\ldots Resource\ldots} commands may +only be used in resource files that are loaded using +\gls{TrackLangRequireDialect}. An error will occur if the file is +input through some other method. + +Within the resource file \localemetafile{pkgname}, +you can identify the file using (new to version 1.3): +\cmddef{TrackLangProvidesResource} +where \meta{tag} is the locale identifier. + +If \gls{ProvidesFile} is defined (through the \LaTeX\ kernel) this is +used, otherwise a simplified generic alternative is used that's +suitable for other \TeX\ formats. + +The resource file can load another resource file +\localemetametafile{pkgname}{tag}, +using (new to version 1.3): +\cmddef{TrackLangRequireResource} +For example, the dialect file \ldf{foo}{en-GB} might need to +load the root language resource file \ldf{foo}{english}: +\begin{codebox} +\comment{(In file \ldf{foo}{en-GB})} +\comment{Declare this regional file:} +\gls{TrackLangProvidesResource}\marg{en-GB} +\comment{load root language file \ldf{foo}{english}:} +\gls{TrackLangRequireResource}\marg{english} +\end{codebox} +If \ldf{foo}{english} is also identified with +\gls{TrackLangProvidesResource}, this will ensure that it's only +loaded once. + +If you require the resource file and want to perform +\meta{code1} if it's loaded at this point or \meta{code2} if it's +already been loaded then you can use: +\cmddef{TrackLangRequireResourceOrDo} + +If you want to load a resource file if it exists (without an +error if it doesn't exist), then you can use +\cmddef{TrackLangRequestResource} +If the file doesn't exist, \meta{not found code} is done. + +\begin{important} +Note that these \cmd{\ldots Resource\ldots} commands are only +permitted within the resource files. They are internally enabled +through \gls{TrackLangRequireDialect}. +\end{important} + +The above restriction on the resource files loaded through +\gls{TrackLangRequireDialect}, and the fact that it internally uses +\gls{IfTrackedLanguageFileExists}, means that commands like +\gls{CurrentTrackedLanguage} or \gls{CurrentTrackedDialect} may be +used in those files. This means that the name of the captions hook +can be obtained through them. (Remember that the file +\ldf{foo}{en-GB} might have been loaded with, say, the +\opt{british} dialect or with the synonymous \opt{UKenglish} +dialect or with a dialect label that doesn't have a corresponding +caption hook, such as \optfmt{enGBLatn}.) + +The \sty{polyglossia} package has language caption hooks in the form +\tklcaptions{\meta{language}} (where \meta{language} is the root language +label) whereas \sty{babel} has dialect captions hooks +in the form \gls{captionsdialect} (where \meta{dialect} is the +dialect label). This leads to a rather +cumbersome set of conditionals: +\begin{compactcodebox} +\cmd{ifcsundef}\marg{captions\gls{CurrentTrackedLanguage}} +\marg{\comment{} + \cmd{ifcsundef}\marg{captions\gls{CurrentTrackedDialect}}\comment{} + \marg{}\comment{} + \marg{\comment{} + \cmd{csgappto}\marg{captions\gls{CurrentTrackedDialect}}\marg{\comment{} + \comment{code to append to hook} + }\comment{} + }\comment{} +}\comment{} +\marg{\comment{} + \cmd{csgappto}\marg{captions\gls{CurrentTrackedLanguage}}\marg{\comment{} + \comment{code to append to hook} + }\comment{} +} +\comment{do code now to initialise} +\end{compactcodebox} +Note that the above has been simplified through the use of +\sty{etoolbox} commands, which isn't suitable for generic use. +It also doesn't query the mapping from \sty{tracklang}['s] dialect +label to the closest matching \sty{babel} dialect label. + +Instead, \sty{tracklang} provides a command +to perform this set of conditionals using generic code: +\cmddef{TrackLangAddToHook} +where \meta{code} is the code to append to the \meta{type} hook. +This always performs \meta{code} after testing for the hook in case +the hook is undefined or has already been called (for example, \sty{ngerman} uses +\tklcaptions{ngerman} when the package is loaded, not at the start of +the document). + +Note that this command is enabled through +\gls{TrackLangRequireDialect} so should only be used inside resource +files. + +Since \optfmt{captions} is a commonly used hook type, there's +a~shortcut command provided: +\cmddef{TrackLangAddToCaptions} +This is equivalent to +\begin{compactcodebox} +\gls{TrackLangAddToHook}\margm{code}\marg{captions} +\end{compactcodebox} + +There may be some hooks, such as \gls{datedialect}, that need +redefining rather than appending to, so there's an +analogous command: +\cmddef{TrackLangRedefHook} +which will redefined the hook to do \meta{code}. + +Note that no expansion is performed on \meta{code} when appending or +redefining a hook. + +\section{Examples} +\label{sec:examples} + +The examples in this section illustrate the above commands. + +\subsection{\filefmt{animals.sty}} +\label{sec:animals} + +This example is for a trivial package called \file{animals.sty} +that defines three textual commands: \cmd{catname}, \cmd{dogname} +and \cmd{ladybirdname}. The default values are: \qt{cat}, \qt{dog} and +\qt{bishy-barney-bee}.\footnote{Thass Broad Norfolk, my bewties +\code{:-P}} +The supported languages are defined in files +\localefile{animals}. + +Here's the code for \file{animals.sty}: +\begin{codebox} +\comment{Example package animals.sty} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{animals} +\codepar +\cmd{RequirePackage}\marg{tracklang}[2019/11/30]\comment{v1.4} +\codepar +\comment{Any undeclared options are language settings:} +\codepar +\cmd{DeclareOption}*\marg{\comment{} + \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}\comment{} + \marg{\comment{successful} + \cmd{PackageInfo}\marg{animals}\marg{Tracking language `\cmd{CurrentOption}'}\comment{} + }\comment{} + \marg{\comment{failed} + \cmd{PackageError}\marg{animals}\comment{} + \marg{Unknown language specification `\cmd{CurrentOption}'}\comment{} + \marg{You need to supply either a known dialect label + or a valid language tag}\comment{} + }\comment{} +} +\codepar +\cmd{ProcessOptions} +\codepar +\comment{Default definitions} +\cmd{newcommand}\cmd{catname}\marg{cat} +\cmd{newcommand}\cmd{dogname}\marg{dog} +\cmd{newcommand}\cmd{ladybirdname}\marg{bishy-barney-bee} +\codepar +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{} + \gls{TrackLangRequireDialect}\marg{animals}\marg{\cmd{this@dialect}}\comment{} + }\comment{} +} +\marg{\comment{no tracked languages, default already set up} +} +\codepar +\cmd{endinput} +\end{codebox} +Here's a Plain \TeX\ version that picks up the language from the +locale environment variable: +\begin{codebox} +\gls{input} tracklang +\codepar +\gls{TrackLangFromEnv} +\codepar +\comment{Default definitions} +\cmd{def}\cmd{catname}\marg{cat} +\cmd{def}\cmd{dogname}\marg{dog} +\cmd{def}\cmd{ladybirdname}\marg{bishy-barney-bee} +\codepar +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\comment{} + \gls{TrackLangRequireDialect}\marg{animals}\marg{\cmd{thisdialect}}\comment{} + }\comment{} +} +\marg{\comment{no tracked languages, default already set up} +} +\end{codebox} +In the event that a user or supplementary package for some +reason wants to load a resource +file for a language that hasn't been tracked, it might be worth +providing a command for this purpose: +\begin{codebox} +\cmd{newcommand}*\marg{\cmd{RequireAnimalsDialect}}[1]\marg{\comment{} + \gls{TrackLangRequireDialect}\marg{animals}\marg{\#1}\comment{} +} +\end{codebox} +The loop can then be changed to: +\begin{codebox} +\gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{} + \cmd{RequireAnimalsDialect}\cmd{this@dialect} +}\comment{} +\end{codebox} + +The \ldf{animals}{english} file valid for both the Plain \TeX\ +and \LaTeX\ formats contains: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{english} +\codepar +\cmd{def}\cmd{englishanimals}\marg{\comment{} + \cmd{def}\cmd{catname}\marg{cat}\comment{} + \cmd{def}\cmd{dogname}\marg{dog}\comment{} + \cmd{def}\cmd{ladybirdname}\marg{bishy-barney-bee}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{englishanimals}} +\end{codebox} +The \ldf{animals}{en-GB} file contains: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{en-GB} +\gls{TrackLangRequireResource}\marg{english} +\codepar +\cmd{def}\cmd{enGBanimals}\marg{\comment{} + \cmd{englishanimals} + \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{} +} +\gls{TrackLangAddToCaptions}\marg{\cmd{enGBanimals}} +\end{codebox} +The \ldf{animals}{en-US} file contains: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{en-US} +\gls{TrackLangRequireResource}\marg{english} +\codepar +\cmd{def}\cmd{enUSanimals}\marg{\comment{} + \cmd{englishanimals} + \cmd{def}\cmd{ladybirdname}\marg{ladybug}\comment{} +} +\gls{TrackLangAddToCaptions}\marg{\cmd{enUSanimals}} +\end{codebox} +Here's a German version in the file \ldf{animals}{german}: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{german} +\codepar +\cmd{def}\cmd{germananimals}\marg{\comment{} + \cmd{def}\cmd{catname}\marg{Katze}\comment{} + \cmd{def}\cmd{dogname}\marg{Hund}\comment{} + \cmd{def}\cmd{ladybirdname}\marg{Marienk\cmd{"}afer}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{germananimals}} +\end{codebox} + +This means that if \sty{babel} or \sty{polyglossia} are loaded, the +redefinitions are automatically performed whenever the language is +changed, but if there's no caption mechanism the user can switch +the fixed names using the \cmd{\ldots animals} commands. + +Here's an example \LaTeX\ document that doesn't have any caption +hooks: +\begin{codebox} +\cmd{documentclass}[\opt{english},\opt{german}]\marg{article} +\codepar +\cmd{usepackage}\marg{animals} +\codepar +\cbeg{document} +\cmd{englishanimals} +\codepar +\cmd{catname}. +\cmd{dogname}. +\cmd{ladybirdname}. +\codepar +\cmd{germananimals} +\codepar +\cmd{catname}. +\cmd{dogname}. +\cmd{ladybirdname}. +\cend{document} +\end{codebox} +Here's a \sty{babel} example document: +\begin{codebox} +\cmd{documentclass}[\opt{american},\opt{german},\opt{british}]\marg{article} +\codepar +\cmd{usepackage}\marg{babel} +\cmd{usepackage}\marg{animals} +\codepar +\cbeg{document} +\cmd{selectlanguage}\marg{american} +\codepar +\cmd{catname}. +\cmd{dogname}. +\cmd{ladybirdname}. +\codepar +\cmd{selectlanguage}\marg{german} +\codepar +\cmd{catname}. +\cmd{dogname}. +\cmd{ladybirdname}. +\codepar +\cmd{selectlanguage}\marg{british} +\codepar +\cmd{catname}. +\cmd{dogname}. +\cmd{ladybirdname}. +\cend{document} +\end{codebox} + +There is some redundancy with the above resource files. Consider the +\sty{babel} example above. The \opt{american} dialect is the +first option, so in that case \ldf{animals}{en-US} is loaded +followed by \ldf{animals}{english}. This means that the +\tklcaptions{american} hook now includes +\begin{codebox} +\cmd{englishanimals} +\cmd{enUSanimals} +\end{codebox} +Since \cmd{enUSanimals} includes \cmd{englishanimals}, there is +redundant code. However, when the \opt{british} dialect is +processed, this loads the file \ldf{animals}{en-GB} but not +the file \ldf{animals}{english} (since it's already been loaded). This +means that \tklcaptions{british} contains \cmd{enGBanimals} but not +\cmd{englishanimals}. + +If this redundancy is an issue (for example, there are so many +redefinitions needed that it significantly slows the document build +process), then it can be addressed with the following modifications. +The \ldf{animals}{en-GB} file is now: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{en-GB} +\codepar +\cmd{def}\cmd{enGBanimals}\marg{\comment{} + \cmd{englishanimals} + \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{} +} +\codepar +\gls{TrackLangRequireResourceOrDo}\marg{english}\comment{} +\marg{ + \gls{TrackLangAddToCaptions}\marg{\comment{} + \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{} + }\comment{} +} +\marg{ + \gls{TrackLangAddToCaptions}\marg{\cmd{enGBanimals}} +} +\end{codebox} +The \ldf{animals}{en-US} file is now: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{en-US} +\codepar +\cmd{providecommand}*\marg{\cmd{enUSanimals}}\marg{\comment{} + \cmd{englishanimals} + \cmd{renewcommand}*\marg{\cmd{ladybirdname}}\marg{ladybug}\comment{} +} +\codepar +\gls{TrackLangRequireResourceOrDo}\marg{english} +\marg{ + \gls{TrackLangAddToCaptions}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{ladybirdname}}\marg{ladybird}\comment{} + }\comment{} +} +\marg{ + \gls{TrackLangAddToCaptions}\marg{\cmd{enUSanimals}} +} +\end{codebox} +This means that the document that has the dialects listed in the +order \opt{american}, \opt{british} now has +\begin{codebox} +\cmd{englishanimals} +\cmd{def}\cmd{ladybirdname}\marg{ladybird} +\end{codebox} +in the \tklcaptions{british} hook and just \cmd{enUSanimals} in the +\tklcaptions{american} hook, which has removed most of the redundancy. + +Note that \sty{polyglossia} has a \tklcaptions{english} hook but not +\tklcaptions{american} or \tklcaptions{british}, so this code doesn't +allow for switching between variants of the same language with +\sty{polyglossia}. + +\subsection{\filefmt{regions.sty}} +\label{sec:regions} + +\glsadd{file.regions.sty}% +\phyperref{Earlier}{pg.britishfilesearch}, I~mentioned the search order for +\gls{IfTrackedLanguageFileExists} where if, for example, the dialect +is \opt{british}, the file search (v1.4+) will be: +\begin{enumerate} +\item \ldf{mypackage}{en-GB} (language tag) +\item \ldf{mypackage}{british} (dialect label) + +\item \ldf{mypackage}{en-Latn-GB} (\idx{639-1} language code, +\idx{script}, \idx{region}) +\item \ldf{mypackage}{en-GB} (\idx{639-1} language code, +\idx{region}) +\item \ldf{mypackage}{en-Latn} (\idx{639-1} language code, +\idx{script}) +\item \ldf{mypackage}{en} (\idx{639-1} language code) + +\item \ldf{mypackage}{eng-Latn-GB} (\idx{639-2} language +code, \idx{script}, \idx{region}) +\item \ldf{mypackage}{eng-GB} (\idx{639-2} language code, +\idx{region}) +\item \ldf{mypackage}{eng-Latn} (\idx{639-2} language code, +\idx{script}) +\item \ldf{mypackage}{eng} (\idx{639-2} language code) + +\item \ldf{mypackage}{GB} (\idx{region}) +\item \ldf{mypackage}{english} (language label) +\end{enumerate} +You may have wondered why +\ldf{mypackage}{GB} is included in the search given that some +countries have multiple official languages, which means that the country code on its +own may not indicate the language. + +The reason for including just the country code as the \meta{localeid} in the +file search is to allow for region rather than language dependent +settings. For example, suppose I~want to write a package that needs +to know whether to use imperial or metric measurements in the +document, but I also want to provide multilingual support. The +language alone won't tell me whether to use imperial or metric (for +example, the US uses imperial and the UK uses metric for most +product attributes). I could provide \ext+{ldf} files for every +language and region combination, but this would result in a lot +redundancy. + +\gls{TrackLangRequireDialect} has an optional argument for adjusting +the way the resource files are loaded. Suppose I have +\localefile{regions} resource files, then +\begin{codebox} +\gls{TrackLangRequireDialect}\marg{regions}\marg{\cmd{this@dialect}} +\end{codebox} +loads the resource file for the dialect given by \cmd{this@dialect} +using: +\begin{compactcodebox} +\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} +\end{compactcodebox} +I can use the optional argument to also load the resource file for the +root language as well: +\begin{codebox}% +\comment{custom file loader for regions.sty} +\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} + \gls{TrackLangRequireDialect} + \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} + \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} + }\comment{} + \marg{regions}\marg{\#1}\comment{} +} +\end{codebox} +Now the dialect \opt{british} can load both +\ldf{regions}{GB} and \ldf{regions}{english}. + +The example package (\file{regions.sty}) below illustrates this. +\begin{codebox} +\comment{Example package regions.sty} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{regions} +\codepar +\gls{RequirePackage}\marg{tracklang}[2016/10/07]\comment{v1.3+} +\codepar +\cmd{DeclareOption}*\marg{\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}} +\cmd{ProcessOptions} +\codepar +\cmd{newcommand}*\marg{\cmd{weightunit}}\marg{kg} +\cmd{newcommand}*\marg{\cmd{lengthunit}}\marg{mm} +\cmd{newcommand}*\marg{\cmd{currencyunit}}\marg{EUR} +\codepar +\cmd{newcommand}*\marg{\cmd{unitname}}\marg{units} +\codepar +\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} + \gls{TrackLangRequireDialect} + \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} + \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} + }\comment{} + \marg{regions}\marg{\#1}\comment{} +} +\codepar +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{} + \cmd{RequireRegionsDialect}\cmd{this@dialect} + }\comment{} +} +\marg{\comment{no tracked languages, default already set up} +} +\codepar +\cmd{endinput} +\end{codebox} +There are separate \ext{ldf} files for region and language. +First are the regions. + +\begin{itemize} +\item \ldf{regions}{BE} (Belgium): +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{BE} +\codepar +\cmd{providecommand}*\marg{\cmd{BEunits}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} + \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} + \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{EUR}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{BEunits}} +\end{codebox} + +\item \ldf{regions}{CA} (Canada): +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{CA} +\codepar +\cmd{providecommand}*\marg{\cmd{CAunits}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} + \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} + \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{CAD}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{CAunits}} +\end{codebox} + +\item \ldf{regions}{GB} (Great Britain): +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{GB} +\codepar +\cmd{providecommand}*\marg{\cmd{GBunits}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} + \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} + \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{GBP}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{GBunits}} +\end{codebox} + +\item \ldf{regions}{US} (USA): +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{US} +\codepar +\cmd{providecommand}*\marg{\cmd{USunits}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{lb}\comment{} + \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{in}\comment{} + \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{USD}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{USunits}} +\end{codebox} +\end{itemize} +Now the language files: + +\begin{itemize} +\item \ldf{regions}{dutch}: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{dutch} +\codepar +\cmd{providecommand}*\marg{\cmd{dutchnames}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{meeteenheden}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{dutchnames}} +\end{codebox} + +\item \ldf{regions}{english}: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{english} +\codepar +\cmd{providecommand}*\marg{\cmd{englishnames}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{units}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{englishnames}} +\end{codebox} + +\item \ldf{regions}{french}: +\begin{codebox} +\cmd{TrackLangProvidesResource}\marg{french} +\codepar +\cmd{providecommand}*\marg{\cmd{frenchnames}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{unit\cmd{'}es}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{frenchnames}} +\end{codebox} + +\item \ldf{regions}{german}: +\begin{codebox} +\gls{TrackLangProvidesResource}\marg{french} +\codepar +\cmd{providecommand}*\marg{\cmd{germannames}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{Ma\cmd{ss} einheiten}\comment{} +} +\codepar +\gls{TrackLangAddToCaptions}\marg{\cmd{germannames}} +\end{codebox} +\end{itemize} + +Here's an example document that uses this package: +\begin{codebox} +\cmd{documentclass}[\opt{canadien}]\marg{article} +\codepar +\cmd{usepackage}\marg{regions} +\codepar +\cbeg{document} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\cend{document} +\end{codebox} + +This works because the \meta{localeid} search looks for the +country code before the root language label. However, this will fail if +the dialect label is the same as a root language label that has an +associated territory, marked with \fnregion\ in +\tableref{tab:rootlangopts}, as then it will be picked up before the +country code. + +In the above example, +\ldf{regions}{CA} is matched rather than +\ldf{regions}{french}, so \ldf{regions}{CA} is loaded by +\begin{compactcodebox} +\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} +\end{compactcodebox} +After this, the language file \ldf{regions}{french} is then loaded: +\begin{compactcodebox} +\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}} +\end{compactcodebox} + +This assumes that there's a country code \ext{ldf} file +available. This example needs a little modification to use default +units in case the region is missing: +\begin{codebox} +\comment{Modified example package regions.sty} +\cmd{NeedsTeXFormat}\marg{LaTeX2e} +\cmd{ProvidesPackage}\marg{regions} +\codepar +\comment{Pass all options to \file{tracklang.sty}:} +\cmd{DeclareOption}*\marg{\cmd{PassOptionsToPackage}\marg{\cmd{CurrentOption}}\marg{tracklang}} +\cmd{ProcessOptions} +\codepar +\gls{RequirePackage}\marg{tracklang} +\codepar +\cmd{newcommand}*\marg{\cmd{weightunit}}\marg{kg} +\cmd{newcommand}*\marg{\cmd{lengthunit}}\marg{mm} +\cmd{newcommand}*\marg{\cmd{currencyunit}}\marg{EUR} +\codepar +\cmd{newcommand}*\marg{\cmd{unitname}}\marg{units} +\codepar +\cmd{newcommand}*\marg{\cmd{defaultunits}}\marg{\comment{} + \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} + \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} + \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{EUR}\comment{} +} +\codepar +\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} + \gls{TrackLangRequireDialect} + \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} + \cmd{ifx}\gls{CurrentTrackedTag}\gls{CurrentTrackedLanguage} + \gls{TrackLangAddToCaptions}\marg{\cmd{defaultunits}}\comment{} + \cmd{else} + \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} + \cmd{fi} + }\comment{} + \marg{regions}\marg{\#1}\comment{} +} +\codepar +\gls{AnyTrackedLanguages} +\marg{\comment{} + \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}{\comment{} + \cmd{RequireRegionsDialect}\cmd{this@dialect} + }\comment{} +} +\marg{\comment{no tracked languages, default already set up} +} +\codepar +\cmd{endinput} +\end{codebox} +Note that we still have a problem for dialect labels that are +identical to root language labels with an associated territory (such +as \opt{manx}). This case can be checked with the following +adjustment: +\begin{codebox} +\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} + \gls{TrackLangRequireDialect} + \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} + \cmd{ifx}\gls{CurrentTrackedTag}\gls{CurrentTrackedLanguage} + \cmd{ifx}\gls{CurrentTrackedRegion}\cmd{empty} + \gls{TrackLangAddToCaptions}\marg{\cmd{defaultunits}}\comment{} + \cmd{else} + \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedRegion}}\comment{} + \cmd{fi} + \cmd{else} + \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} + \cmd{fi} + }\comment{} + \marg{regions}\marg{\#1}\comment{} +} +\end{codebox} +In the case where both the dialect and root language label are +\opt{manx} with the resource files \ldf{regions}{manx} +and \ldf{regions}{IM}, then \gls{CurrentTrackedTag} will be +\opt{manx} (the dialect label) so \ldf{regions}{manx} will +be loaded with: +\begin{compactcodebox} +\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} +\end{compactcodebox} +In this case \gls{CurrentTrackedRegion} is \code{IM} (that is, it's +not empty) so then \ldf{regions}{IM} will be loaded with: +\begin{compactcodebox} +\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedRegion}} +\end{compactcodebox} + +Here's another document that sets up dialects with +\sty{tracklang} labels that aren't recognised by \sty{babel}. +This means that there's no corresponding \gls{captionsdialect} hook +for either the dialect label or the root language label, +so mappings need to be defined from the \sty{tracklang} dialect +label to the matching \sty{babel} dialect label. + +\begin{codebox} +\cmd{documentclass}\marg{article} +\codepar +\cmd{usepackage}\marg{tracklang} +\codepar +\gls{TrackLanguageTag}\marg{de-US-1996} +\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman} +\codepar +\gls{TrackLanguageTag}\marg{en-MT} +\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{UKenglish} +\codepar +\cmd{usepackage}[main=ngerman,UKenglish]\marg{babel} +\cmd{usepackage}\marg{regions} +\codepar +\cbeg{document} +\gls{selectlanguage}\marg{ngerman} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\gls{selectlanguage}\marg{UKenglish} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\cend{document} +\end{codebox} +This produces: +\begin{resultbox} +Ma\ss einheiten: lb, in, USD. + +units: kg, mm, EUR. +\end{resultbox} +Compare this with: +\begin{codebox} +\cmd{documentclass}\marg{article} +\codepar +\cmd{usepackage}[main=ngerman,UKenglish]\marg{babel} +\cmd{usepackage}\marg{regions} +\codepar +\cbeg{document} +\gls{selectlanguage}\marg{ngerman} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\gls{selectlanguage}\marg{UKenglish} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\cend{document} +\end{codebox} +which produces: +\begin{resultbox} +Ma\ss einheiten: kg, mm, EUR. + +units: kg, mm, GBP. +\end{resultbox} + +Note that these mappings aren't needed if \sty{babel} +is loaded with the root language labels instead. For example: +\begin{codebox} +\cmd{documentclass}\marg{article} +\codepar +\cmd{usepackage}\marg{tracklang} +\codepar +\gls{TrackLanguageTag}\marg{de-US-1996} +\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman} +\codepar +\gls{TrackLanguageTag}\marg{en-MT} +\codepar +\cmd{usepackage}[main=ngerman,english]\marg{babel} +\cmd{usepackage}\marg{regions} +\codepar +\cbeg{document} +\gls{selectlanguage}\marg{ngerman} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\gls{selectlanguage}\marg{english} +\codepar +\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. +\codepar +\cend{document} +\end{codebox} +No mapping is required for the \opt{en-MT} locale as +it can pick up \tklcaptions{english} when \gls{TrackLangAddToHook} +(used by \gls{TrackLangAddToCaptions}) +queries the root language label after failing to find the +language hook from the dialect label. + +Some of the predefined \sty{tracklang} dialects come with +a mapping to the closest matching \sty{babel} dialect label. +For example, the option \opt{ngermanDE} listed in +\tableref{tab:nonisoopts} automatically provides a mapping +to \opt{ngerman}. Since a \sty{tracklang} dialect label +can only map to one \sty{babel} label, this can be problematic +for synonymous labels such as +\opt{british}\slash\opt{UKenglish} or +\opt{american}\slash\opt{USenglish}. The default mappings used +by \sty{tracklang} are shown in \tableref{tab:nonisoopts}. + +\chapter{Adding Support for Language Tracking} +\label{sec:langsty} + +If you are writing a package that \emph{sets up} the document languages (rather +than a package that provides multilingual support if the user has +already loaded a language package) then you can load \sty{tracklang} +and use the commands below to help other packages track your +provided languages. (See also: +\dickimawhref{latex/tracklang/langpkg.shtml}{Integrating +\filefmt{tracklang.tex} into Language Packages}.) + +The \sty{tracklang} package can be loaded using +\begin{codebox} +\gls{input} tracklang +\end{codebox} +or (\LaTeX\ only) +\begin{codebox} +\gls{RequirePackage}\marg{tracklang} +\end{codebox} + +When using \LaTeX, there's a difference between the two. +The first case prevents \sty{tracklang} from picking up +the document class options but skips the check for known +language packages. This check is redundant since your package is +the language package, so you need to decide whether or +not to allow the user to set up the localisation information +through the document class options. + +There's a hook that, if defined, is performed by +\file{tracklang.sty} after the package options have been loaded but +before known language packages are checked: +\cmddef{@tracklang@prelangpkgcheck@hook} + +If you prefer \gls{RequirePackage} over \gls{input} but you want to make +\file{tracklang.sty} skip the check for known +language packages then (as from v1.3.8) define the pre-language +package check hook as follows: +\begin{codebox} +\cmd{providecommand}\gls{@tracklang@prelangpkgcheck@hook}\marg{\cmd{endinput}} +\gls{RequirePackage}\marg{tracklang}[2019/10/06]\comment{v1.3.8+} +\end{codebox} +This will still pick up languages supplied through the +document class options. + +If you just use \gls{input}, there's a test at the start of +\file{tracklang.tex} to determine if it's already been loaded, so +you don't need to worry if the document has already input it. + +To integrate \sty{tracklang} into your language package, you need +to consider the following steps: +\begin{enumerate} +\item Does \sty{tracklang} define your supported \idxn{15924} language +scripts in the \file{tracklang-scripts.tex} file? + +If yes, then skip this step. Otherwise create a file with the +relevant \gls{TrackLangScriptMap} command for each unknown script and identify +this new file with \gls{TrackLangAddExtraScriptFile} (see +\sectionref{sec:newscripts}). This usually +won't be necessary unless you have a custom script or a child script +(a script that's a sub-category of another script). + +\item Does \sty{tracklang} recognise the root language? + +If yes, then skip this step. + +If your package is setting up a language that \sty{tracklang} +doesn't recognise then you will need to define the root language +using \gls{TrackLangNewLanguage} (see \sectionref{sec:newlanguages}). + +This usually won't be the case as \sty{tracklang} should support all +languages that have an official \idxn{639-1} alpha-2 code. + +If you simply have a different label from \sty{tracklang} +identifying the root language, then you can just set up your label +as a dialect using \gls{TrackLangProvidePredefinedDialect}. + +\item Does \sty{tracklang} define the relevant \idxn{3166-1} region codes +in the \file{tracklang-region-codes.tex} file? + +If yes, then skip this step. Otherwise create a file with the +relevant \gls{TrackLangRegionMap} command for each new region and +identify this new file with \gls{TrackLangAddExtraRegionFile} (see +\sectionref{sec:newregions}). This usually won't be necessary as +\sty{tracklang} should recognise all countries that have an alpha-2 +region code, but you may require it if you need a broader region, +such as EU. + +\item Do you want to define some convenient dialect labels that can +be used with \gls{TrackPredefinedDialect}? + +If no, then skip this step. Otherwise you can use +\gls{TrackLangProvidePredefinedLanguage} for root languages +and \gls{TrackLangProvidePredefinedDialect} for dialects with +additional information, such as a region, sub-language or script +(see \sectionref{sec:definelabels}). + +\item In your language initialisation code, add the \sty{tracklang} +code to track the particular dialect (for example, use +\gls{TrackPredefinedDialect} for recognised dialect labels or +use the \csmetafmt{AddTracked}{Xxx}{} set of commands). See +\sectionref{sec:initnewlang}. + +\item In your language selection code (such as \gls{selectlanguage}), add +\gls{SetCurrentTrackedDialect}\margm{label} to allow the document +author to easily query the current localisation settings (such as +the region). See \sectionref{sec:selectlanguage}. +\end{enumerate} + +\section{Initialising a New Language or Dialect} +\label{sec:initnewlang} + +When the user requests a particular dialect through your language +package, you can notify \sty{tracklang} of this choice using +\begin{compactcodebox*} +\gls{TrackPredefinedDialect}\margm{dialect label} +\end{compactcodebox*} +provided the dialect label is recognised by \sty{tracklang} (all those +listed in \refoptstables). + +If there's no matching dialect predefined by \sty{tracklang}, you +can just use \gls{TrackLocale} or \gls{TrackLanguageTag} +(described in \sectionref{sec:generic}) +with the appropriate \idx{ISO} codes \emph{if you're not providing caption +hooks}. + +If you are providing a captions hook mechanism +in the form \gls{captionsdialect}, then if \meta{dialect} +doesn't match the corresponding \sty{tracklang} dialect label, +you can provide a mapping using +\gls{SetTrackedDialectLabelMap}, described below. + +\section{Switching Language or Dialect} +\label{sec:selectlanguage} + +When the document author switches to a different language or +dialect, the current localisation information can be set with: +\cmddef{SetCurrentTrackedDialect} +where \meta{dialect} may the \sty{tracklang} dialect label, +or the mapped label previously set through \gls{SetTrackedDialectLabelMap}, +described below, or the language label (in which case the +last dialect to be tracked with that root language will +be assumed). + +This will make the following commands available which may be +of use to other packages: +\begin{itemize} +\item\gls{CurrentTrackedDialect} The dialect label recognised +by \sty{tracklang} (which may not be the same as \meta{dialect}). + +\item\gls{CurrentTrackedLanguage} +The root language label used by \sty{tracklang}. + +\item\gls{CurrentTrackedDialectModifier} The dialect modifier. + +\item\gls{CurrentTrackedDialectVariant} The dialect variant. + +\item\gls{CurrentTrackedDialectScript} The dialect script. +Note that if \sty{tracklang-scripts} is also loaded, this allows the +script direction to be accessed using +\begin{codebox} +\gls{TrackLangScriptAlphaToDir}\marg{\gls{CurrentTrackedDialectScript}} +\end{codebox} +See \sectionref{sec:supplpkgs} for further details. + +\item\gls{CurrentTrackedDialectSubLang} The dialect sub-language +code. + +\item\gls{GetTrackedDialectAdditional} The dialect's additional +information. + +\item\gls{CurrentTrackedIsoCode} The dialect's root language +\idx{ISO} code. (The first found in the sequence \idx{639-1}, +\idx{639-2}, \idx{639-3}.) + +\item\gls{CurrentTrackedRegion} The dialect's \idxn{3166-1} region +code. + +\item\gls{CurrentTrackedLanguageTag} The dialect's language tag. + +\end{itemize} +(Without this automated use of \gls{SetCurrentTrackedDialect}, +the same information can be picked up using commands +like \gls{GetTrackedDialectScript}, but that's less convenient, +especially if \gls{languagename} needs to be converted +to \meta{dialect}. See the accompanying sample file +\filefmt{sample-setlang.tex} for an example.) + +\section{Defining New Scripts} +\label{sec:newscripts} + +The \file{tracklang-scripts.tex} file isn't automatically loaded, +but if it is then, as from v1.4, it contains a hook at the end of +the file that can be used to load additional files that define +supplementary scripts. This entails creating a file called, say, +\filefmt{mypackage-scripts.tex} that contains: +\begin{compactcodebox*} +\gls{TrackLangScriptMap}\margm{alpha code}\margm{numeric code}\margm{name}\margm{direction}\margm{parent script} +\end{compactcodebox*} +The first argument \meta{alpha code} is the four-letter ISO~15924 code (such as +\opt{Latn}), the second argument is the numeric code (such as +215), the third argument \meta{name} is the name of the script (such +as \optfmt{Latin}), the fourth argument is the direction (such as +\optfmt{LR} for left-to-right) and the final argument is the parent +script (leave blank if there's no parent). Note that this command will override any previous +mapping for those codes. No check is performed to determine if they +have already been defined. + +The supplementary file should be identified with: +\begin{compactcodebox*} +\gls{TrackLangAddExtraScriptFile}\margm{filename} +\end{compactcodebox*} + +Additional information can be found in \sectionref{sec:supplpkgs}. + +\section{Defining New Regions} +\label{sec:newregions} + +The \file{tracklang-region-codes.tex} file isn't automatically loaded, +but if it is then, as from v1.4, it contains a hook at the end of +the file that can be used to load additional files that define +supplementary regions. This entails creating a file called, say, +\filefmt{mypackage-regions.tex} that contains: +\begin{compactcodebox*} +\gls{TrackLangRegionMap}\margm{numeric code}\margm{alpha-2 +code}\margm{alpha-3 code} +\end{compactcodebox*} +where the first argument is the numeric region code (such as 826), +the second argument is the alpha-2 region code (such as \code{GB}) +and the third argument is the alpha-3 region code (such as +\code{GBR}). Note that this command will override any previous +mapping for those codes. No check is performed to determine if they +have already been defined. + +The supplementary file should be identified with: +\begin{compactcodebox*} +\gls{TrackLangAddExtraRegionFile}\margm{filename} +\end{compactcodebox*} + +Additional information can be found in \sectionref{sec:supplpkgs}. + +\section{Defining a New Language} +\label{sec:newlanguages} + +(New to version 1.3.) +If the root language isn't recognised by \sty{tracklang} +(not listed in \tableref{tab:rootlangopts}), then +it can be defined (but not tracked at this point) using: +\cmddef{TrackLangNewLanguage} +where \meta{language label} is the root language label, +\meta{639-1 code} is the \idxn{639-1} code for that language (may be +empty if there isn't one), \meta{639-2 (T)} is the \idxn{639-2T} +code for that language (may be empty if there isn't one), +\meta{639-2 (B)} is the \idxn{639-2B} code for that language (may be +empty if it's the same as \meta{639-2 (T)}), \meta{639-3} is the +\idxn{639-3} code for that language (empty if the same as the +\idx{639-2} code), \meta{3166-1} is the territory \idxn{3166-1} code for +languages that are only spoken in one territory (should be empty if +the language is spoken in multiple territories), and \meta{default +script} is the default script (empty if disputed or varies according +to region). + +You can then track this language using: +\cmddef{AddTrackedDialect} +for dialects (where \meta{dialect label} is the dialect label and +\meta{root language label} is the root language label) or, if +no regional variant is needed, you can instead use: +\cmddef{AddTrackedLanguage} +This is equivalent to +\begin{compactcodebox} +\gls{AddTrackedDialect}\margm{root language label}\margm{root language label} +\end{compactcodebox} +Note that \gls{AddTrackedDialect} defines: +\cmddef{TrackLangLastTrackedDialect} +to the dialect label, which makes it easier to reference the last +dialect to be tracked. + +\section{Defining New \styfmt{tracklang} Labels} +\label{sec:definelabels} + +A dialect label may be predefined with associated information that +allows that particular combination to be easily tracked with +\gls{TrackPredefinedDialect}. In the case of a dialect label that +only requires the information provided in \gls{TrackLangNewLanguage} +you can use: +\cmddef{TrackLangProvidePredefinedLanguage} +where \meta{language label} corresponds to the language label used in +\gls{TrackLangNewLanguage}. This allows +\begin{compactcodebox*} +\gls{TrackPredefinedDialect}\margm{label} +\end{compactcodebox*} +to not only track the root language but also the associated ISO codes. + +If the dialect label doesn't match the root language label then use: +\cmddef{TrackLangProvidePredefinedDialect} +where \meta{dialect label} is the new \sty{tracklang} dialect label, +\marg{root language label} is the \sty{tracklang} root language label, +\meta{region} is the \idxn{3166-1} region code (may be empty), +\meta{modifier} is the \idx{modifier} (may be empty), \meta{variant} +is the \idx{variant} information (may be empty), \meta{map} is your +package's language label that corresponds to the \sty{tracklang} +dialect label supplied in the first argument (may be empty if +identical), and \meta{script} is the \idxn{15924} alpha-4 script code +(may be empty if it's the same as the default script for the root +language). + +For compatibility with pre version 1.3, +if the dialect isn't predefined by +\sty{tracklang}, then you can use: +\begin{compactcodebox*} +\gls{AddTrackedDialect}\marg{dialect}\marg{root language label} +\end{compactcodebox*} +where \meta{root language label} is the label for the dialect's root +language (\tableref{tab:rootlangopts}) and \meta{dialect} matches +the captions hook. If the dialect is already in the tracked dialect +list, it won't be added again. If the root language is already in +the tracked language list, it won't be added again. As from version +1.3 this additionally defines +\gls{TrackLangLastTrackedDialect} +to \meta{dialect} for convenient reference if required. +Note that \gls{AddTrackedDialect} is internally used by commands like +\gls{TrackPredefinedDialect}, \gls{TrackLocale} and +\gls{TrackLanguageTag}. + +(New to version 1.3.) Many of the \sty{tracklang} dialect +labels don't have a corresponding match in various language packages. For +example, \sty{tracklang} provides \opt{ngermanDE} but the +closest match in \sty{babel} is \opt{ngerman}. This means that +the caption hook \tklcaptions{ngerman} can't be accessed +through: +\begin{compactcodebox} +\cmd{csname} captions\gls{CurrentTrackedDialect}\cmd{endcsname} +\end{compactcodebox} +in the resource files. In this case, a mapping may be defined +between the \sty{tracklang} dialect label and the closest +matching label used by the language hooks. This is done through +\cmddef{SetTrackedDialectLabelMap} +where \meta{tracklang-label} is the \sty{tracklang} label and +\meta{hook-label} is the language hook label. For example: +\begin{compactcodebox*} +\gls{TrackLanguageTag}\marg{de-AR-1996} +\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman} +\end{compactcodebox*} +Since \gls{TrackLanguageTag} internally uses \gls{AddTrackedDialect} +the dialect label created by \sty{tracklang} can be accessed +using \gls{TrackLangLastTrackedDialect}. This means that +\gls{TrackLangAddToCaptions} can now find the \tklcaptions{ngerman} +hook even though the \sty{tracklang} dialect label isn't \opt{ngerman}. + +(New to version 1.3.) +If the root language label is recognised by \sty{tracklang}, you +can add the \idx{ISO} codes using: +\cmddef{AddTrackedLanguageIsoCodes} + +As from v1.3, you can also provide a modifier for a given +dialect using: +\cmddef{SetTrackedDialectModifier} +where \meta{dialect} is the dialect label and \meta{value} +is the modifier value. For example: +\begin{compactcodebox*} +\gls{AddTrackedDialect}\marg{oldgerman}\marg{\opt{german}} +\gls{AddTrackedLanguageIsoCodes}\marg{german} +\gls{SetTrackedDialectModifier}\marg{oldgerman}\marg{old} +\end{compactcodebox*} + +Note that no sanitization is performed on \meta{value} when the +modifier is set explicitly through \gls{SetTrackedDialectModifier}, +since it's assumed that any package that specifically sets the +modifier in this way is using a sensible labelling system. If the +modifier is obtained through commands like \gls{TrackLocale}, then +the modifier is sanitized as the value may have been obtained from +the operating system and there's no guarantee that it won't contain +problematic characters. + +The \idx{modifier} is typically obtained by parsing locale information in +\idx{POSIX} format. +\begin{compactcodebox*} +\meta{language}[\idx{underscoresep}\meta{territory}][\idx{dotsep}\meta{codeset}][\idx{atmod}\meta{modifier}] +\end{compactcodebox*} +whereas the \idx{variant} is typically obtained by parsing the language +tag. + +The information provided in the commands below (such as the script) +are typically obtained by parsing the language tag. For example, +with Serbian in the Latin alphabet the modifier would be \optfmt{latin} +whereas the script would be \opt{Latn}: +\begin{codebox*} +\gls{AddTrackedDialect}\marg{serbianlatin}\marg{\opt{serbian}} +\gls{AddTrackedLanguageIsoCodes}\marg{\opt{serbian}} +\gls{SetTrackedDialectModifier}\marg{serbianlatin}\marg{latin} +\gls{SetTrackedDialectScript}\marg{serbianlatin}\marg{\opt{Latn}} +\end{codebox*} + +As from v1.3, you can provide a script (for example, +\opt{Latn} or \opt{Cyrl}) using: +\cmddef{SetTrackedDialectScript} +where \meta{dialect} is the dialect label and \meta{value} is the +\idxn{15924} alpha-4 script identifier. For example: +\begin{codebox*} +\gls{AddTrackedDialect}\marg{serbiancyrl}\marg{\opt{serbian}} +\gls{AddTrackedLanguageIsoCodes}\marg{serbian} +\gls{SetTrackedDialectScript}\marg{serbiancyrl}\marg{\opt{Cyrl}} +\end{codebox*} + +As from v1.3, you can provide a variant for a given +dialect using: +\cmddef{SetTrackedDialectVariant} +For example: +\begin{codebox*} +\gls{AddTrackedDialect}\marg{german1901}\marg{german} +\gls{SetTrackedDialectVariant}\marg{german1901}\marg{1901} +\end{codebox*} + +As from v1.3, you can also provide a sub-language using: +\cmddef{SetTrackedDialectSubLang} +where \meta{dialect} is the dialect label and \meta{value} is the +code. For example: +\begin{codebox*} +\gls{AddTrackedDialect}\marg{mandarin}\marg{\opt{chinese}} +\gls{AddTrackedLanguageIsoCodes}\marg{\opt{chinese}} +\gls{SetTrackedDialectSubLang}\marg{mandarin}\marg{cmn} +\gls{AddTrackedIsoLanguage}\marg{639-3}\marg{cmn}\marg{mandarin} +\end{codebox*} + +As from v1.3, you can also provide additional information using: +\cmddef{SetTrackedDialectAdditional} +where \meta{dialect} is the dialect label and \meta{value} is the +additional information. + +\section{Example (\filefmt{alien.sty})} +\label{sec:examplenewlang} + +Suppose I want to create a language package \file{alien.sty} that defines the +\optfmt{martian} language with regional dialects +\optfmt{lowermartian} and \optfmt{uppermartian}. First, let's +suppose that \sty{tracklang} recognises the root language +\optfmt{martian}: +\begin{codebox} +\cmd{ProvidesPackage}\marg{alien} +\codepar +\gls{input}{tracklang}\comment{v1.3} +\codepar +\cmd{DeclareOption}\marg{martian}\marg{\comment{} + \gls{TrackPredefinedDialect}\marg{martian} +} +\cmd{DeclareOption}\marg{lowermartian}\marg{\comment{} + \gls{AddTrackedDialect}\marg{lowermartian}\marg{martian} + \gls{AddTrackedLanguageIsoCodes}\marg{martian} + \gls{AddTrackedIsoLanguage}\marg{3166-1}\marg{YY}\marg{lowermartian} + \comment{other attributes such as} + \comment{\gls{SetTrackedDialectVariant}\marg{lowermartian}\marg{...}} +} +\cmd{DeclareOption}\marg{uppermartian}\marg{\comment{} + \gls{AddTrackedDialect}\marg{uppermartian}\marg{martian} + \gls{AddTrackedLanguageIsoCodes}\marg{martian} + \gls{AddTrackedIsoLanguage}\marg{3166-1}\marg{XX}\marg{uppermartian} + \comment{other attributes such as} + \comment{\gls{SetTrackedDialectVariant}\marg{uppermartian}\marg{...}} +} +\codepar +\cmd{ProcessOptions} +\codepar +\cmd{newcommand}*\marg{\gls{selectlanguage}}[1]\marg{\comment{} + \cmd{def}\gls{languagename}\marg{\#1}\comment{} + \comment{other stuff} + \gls{SetCurrentTrackedDialect}\marg{\#1}\comment{} +} +\codepar +\gls{AnyTrackedLanguages} +\marg{ + \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}} + \marg{\comment{} + \gls{TrackLangRequireDialect}\marg{alien}\marg{\cmd{thisdialect}} + } +} +\end{codebox} +The caption commands and language set up are in the files +\localefile{alien} as in the examples from +\sectionref{sec:examples}. This allows for the user having already +loaded \sty{tracklang} before \sty{alien} and used \gls{TrackLangFromEnv} to pick up +the locale from the operating system's environment variables. +(For example, they may have \envvar{LANG} set to +\code{xx\idx{underscoresep}YY}.) + +The resource files may need to set the mapping between the +\sty{tracklang} dialect label and the \sty{alien} dialect +label. For example, in \ldf{alien}{xx-YY}: +\begin{codebox*} +\gls{TrackLangProvidesResource}\marg{xx-YY} +\codepar +\gls{TrackLangRequireResource}\marg{martian}\comment{load common elements} +\codepar +\cmd{newcommand}\marg{\tklcaptions{lowermartian}}\marg{\comment{} + \tklcaptions{martian} + \cmd{def}\cmd{contentsname}\marg{X'flurp}\comment{regional variation} +} +\codepar +\gls{SetTrackedDialectLabelMap}\marg{\gls{CurrentTrackedDialect}}\marg{lowermartian} +\end{codebox*} + +Now let's consider the case where \sty{tracklang} doesn't know +about the \optfmt{martian} language. In this case the user can't +track the dialect until the root language has been defined, so the +user can't use \gls{TrackLangFromEnv} before using the \sty{alien} +package. + +With \sty{tracklang} v1.3. The new root language can be defined +with a minor adjustment to the above code: +\begin{codebox*} +\cmd{ProvidesPackage}\marg{alien} +\codepar +\gls{input}\marg{tracklang}\comment{needs v1.3} +\codepar +\gls{TrackLangIfKnownLang}\marg{martian} +\marg{}\comment{tracklang already knows about the martian language} +\marg{ + \comment{tracklang doesn't known about the martian language, so define it} + \comment{with \idxn{639-1} (xx) and \idxn{639-2} (xxx) codes:} + \gls{TrackLangNewLanguage}\marg{martian}\marg{xx}\marg{xxx}\marg{}\marg{}\marg{}\marg{\opt{Latn}} +} +\end{codebox*} +The rest is as before. + +Now other package writers who want to provide support +for the Martian dialects can easily detect which language options +the user requested through my package, \emph{without needing to know +anything about my \sty{alien} package}. + +\part{Summaries} +\appendix + +\chapter{Region and Script Mappings} +\label{sec:regscriptmappings} + +Region mappings are listed in \tableref{tab:regionmappings}, and +script mappings are listed in \tableref{tab:scriptmappings}. + +\printunsrttable[type=index, + title={Region Mappings},other={alpha3},blocks=2, + block-style={name-other-desc},label={tab:regionmappings}, + init={% + \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% + \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{region}{##3}{##2}}% + \renewcommand{\glstablenameheader}{Alpha-2}% + \renewcommand{\glstableotherheader}{Alpha-3}% + \renewcommand{\glstabledescheader}{Numeric}% + \renewcommand{\glstableDesc}{\numerictag}% +} +] + +\printunsrttable[type=index,clearpage,par=ragged, + title={Script Mappings},other=userii,blocks=1, + block-style={name-symbol-other-desc},label={tab:scriptmappings}, + init={% + \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% + \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{script}{##3}{##2}}% + \renewcommand{\glstablenameheader}{Alpha-2}% + \renewcommand{\glstablesymbolheader}{Numeric}% + \renewcommand{\glstableSymbol}{\numerictag}% + \renewcommand{\glstableotherheader}{Direction}% +} +] + +\backmatter +\printterms +\printsummary + +\renewcommand{\fnregion}{}% +\glsdefpostname{isolangregion}{ (option)}% +\glsdefpostname{rootlang}{ (root language)}% +\glsdefpostname{isocode}{ (\idx{ISO} code)}% +\glsdefpostname{noniso}{ (option)}% +\glsdefpostname{region}{ (region)}% +\glsdefpostname{script}{ (script)}% +\glsdefpostname{application}{ (application)}% +\printuserguideindex + +\end{document} diff --git a/macros/generic/tracklang/tracklang.dtx b/macros/generic/tracklang/tracklang.dtx index 22dd36860e..a36ec15205 100644 --- a/macros/generic/tracklang/tracklang.dtx +++ b/macros/generic/tracklang/tracklang.dtx @@ -1,3576 +1,112 @@ %\iffalse % tracklang.dtx generated using makedtx version 1.2 (c) Nicola Talbot % Command line args: -% -src "tracklang.sty\Z=>tracklang.sty" -% -src "tracklang.tex\Z=>tracklang.tex" -% -src "tracklang-region-codes.tex\Z=>tracklang-region-codes.tex" -% -src "tracklang-scripts.sty\Z=>tracklang-scripts.sty" -% -src "tracklang-scripts.tex\Z=>tracklang-scripts.tex" -% -author "Nicola Talbot" -% -doc "tracklang-manual.tex" -% -section "chapter" -% tracklang -% Created on 2020/6/30 11:55 -%\fi -%\iffalse -%<*package> -%% \CharacterTable -%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z -%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z -%% Digits \0\1\2\3\4\5\6\7\8\9 -%% Exclamation \! Double quote \" Hash (number) \# -%% Dollar \$ Percent \% Ampersand \& -%% Acute accent \' Left paren \( Right paren \) -%% Asterisk \* Plus \+ Comma \, -%% Minus \- Point \. Solidus \/ -%% Colon \: Semicolon \; Less than \< -%% Equals \= Greater than \> Question mark \? -%% Commercial at \@ Left bracket \[ Backslash \\ -%% Right bracket \] Circumflex \^ Underscore \_ -%% Grave accent \` Left brace \{ Vertical bar \| -%% Right brace \} Tilde \~} -%
-%\fi -% \iffalse -% Doc-Source file to use with LaTeX2e -% Copyright (C) 2020 Nicola Talbot, all rights reserved. -% \fi -% \iffalse -%<*driver> -\documentclass[report,inlinetitle]{nlctdoc} - -\DeleteShortVerb{|} - -\usepackage[a4paper,marginpar=2in,marginparsep=10pt, - left=2in,right=.5in]{geometry} -\usepackage{graphicx} -\usepackage[utf8]{inputenc} -\usepackage[T1]{fontenc} -\usepackage{tracklang} -\usepackage{etoolbox} -\usepackage{longtable} -\usepackage{datatool-base}[2016/07/20] -\let\orgtheindex\theindex -\let\orgendtheindex\endtheindex -\usepackage{imakeidx} -\usepackage[colorlinks, - bookmarks, - hyperindex=false, - pdfauthor={Nicola L.C. Talbot}, - pdftitle={tracklang: tracking language options}]{hyperref} - -\CheckSum{6210} - -\appto\MacroFont{\scriptsize} -\renewcommand*{\usage}[1]{\textit{\hyperpage{#1}}} -\renewcommand*{\main}[1]{\underline{\hyperpage{#1}}} -\PageIndex -\setcounter{IndexColumns}{2} -\newcommand*{\PrintCodeIndex}{% - \bgroup - \let\theindex\orgtheindex - \let\endtheindex\orgendtheindex - \PrintIndex - \egroup -} -\IndexPrologue{% -\clearpage\phantomsection -\addcontentsline{toc}{chapter}{Code Index}% -\chapter*{Code Index}\markboth{Code Index}{Code Index}% -} - -\makeindex[name=user,title=Main Index,intoc] -\renewcommand{\iapp}[1]{\index[user]{#1@\appfmt{#1}|hyperpage}} -\renewcommand{\iterm}[1]{\index[user]{#1|hyperpage}} -\renewcommand{\ics}[1]{\cs{#1}\index[user]{#1@\protect\cs{#1}|hyperpage}} -\renewcommand*{\ipkgopt}[2][]{% - \ifstrempty{#1}% - {\index[user]{package options:!#2@\pkgoptfmt{#2}|hyperpage}}% - {\index[user]{package options:!#2@\pkgoptfmt{#2}!#1@\pkgoptfmt{#1}|hyperpage}}% -} -\renewcommand*{\pkgopt}[2][]{% - \pkgoptfmt{#2}\ifstrempty{#1}% - {\index[user]{package options:!#2@\pkgoptfmt{#2}|hyperpage}}% - {\index[user]{package options:!#2@\pkgoptfmt{#2}!#1@\pkgoptfmt{#1}|hyperpage}}% -} -\renewcommand*{\isty}[1]{% - \index[user]{#1 package@\styfmt{#1} package|hyperpage}} - -\newcommand*{\envvar}[1]{% - \texttt{#1}% - \index[user]{#1@\texttt{#1}}} - -\newcommand*{\isopkgopts}{} -\newcommand*{\nonisopkgopts}{} -\newcommand*{\rootlangopts}{} - -\makeatletter -\renewcommand*{\changes@}[3]{% - \protected@edef\@tempa{\noexpand\glossary{#1 (#2)\levelchar - \ifx\saved@macroname\@empty - \space - \actualchar - \generalname - \else - \expandafter\@gobble - \saved@macroname - \actualchar - \string\verb\quotechar*% - \verbatimchar\saved@macroname - \verbatimchar - \fi - :\levelchar #3\encapchar hyperpage}}% - \@tempa\endgroup\@esphack} - - -\ifdim\overfullrule=0pt\relax % final mode - \typeout{Sorting available options. This may take a while.}% - \newcommand{\addopt}[3]{% - \expandafter\dtlinsertinto\expandafter{#1}{#2}{#3}% - }% -\else - \newcommand{\addopt}[3]{% - \ifdefempty{#2}{\edef#2{#1}}{\eappto{#2}{,#1}} - } -\fi - - -\@for\thisdialect:=\@tracklang@declaredoptions\do{% - \ifdefempty\thisdialect - {}% - {% - \typeout{\thisdialect}% - \ifnum\pdfmatch {[a-z]{2,3}-[A-Z]{2}}{\thisdialect}=1\relax - \addopt{\thisdialect}{\isopkgopts}{\dtlcompare}% - \else - \TrackLangIfKnownLang{\thisdialect} - {% - \addopt{\thisdialect}{\rootlangopts}{\dtlcompare}% - }% - {% - \addopt{\thisdialect}{\nonisopkgopts}{\dtlicompare}% - }% - \fi - }% -} - -\newcommand*{\isopkgoptstab}{\begin{table}[p] -\caption[Predefined ISO Language-Region Dialects]% -{Predefined ISO Language-Region Dialects. (May be used as a package -option or with \cs{TrackPredefinedDialect}.)}\label{tab:isoopts} -\medskip -\centering -\begin{tabular}{llll}% -} - -\newcommand*{\fnregion}{\textsuperscript{\textdagger}} - -\newcommand*{\rootlangoptstab}{\begin{longtable}{lll} -\caption[Predefined Root Languages]{Predefined Root Languages. -(\fnregion Has an associated territory.) -The corresponding -language tag obtained with \cs{GetTrackedLanguageTag}\marg{dialect} -is shown in parentheses.}\label{tab:rootlangopts}\\\endfirsthead -\caption[]{Predefined Root Languages Continued.}\\\endhead -} - -\newcommand*{\nonisopkgoptstab}{\begin{longtable}{ll} -\caption[Predefined Non-ISO Dialects]{Predefined Non-ISO Dialects. -(\fnregion Has an associated territory.) -The corresponding -language tag obtained with \cs{GetTrackedLanguageTag}\marg{dialect} -is shown in parentheses. If the dialect has a corresponding mapping -for the closest matching non-root language \cs{caption\ldots} or -\cs{date\ldots}, this is also include after the tag following a -slash.}% -\label{tab:nonisoopts}\\\endfirsthead -\caption[]{Predefined Non-ISO Dialects Continued}\\\endhead -} - -\newcount\tmpctr - -\@for\thisdialect:=\isopkgopts\do{% - \advance\tmpctr by 1\relax - \eappto\isopkgoptstab{\noexpand\pkgoptfmt{\thisdialect}&}% - {%locally track this dialect to pick up information - \TrackPredefinedDialect\thisdialect - \xappto\isopkgoptstab{\space - {\noexpand\small(\noexpand\texttt{% - \csname @tracklang@dialect\endcsname})}}% - }% - \ifnum\tmpctr>1 - \tmpctr = 0\relax - \appto\isopkgoptstab{\\}% - \else - \appto\isopkgoptstab{&}% - \fi -} - -\appto\isopkgoptstab{\end{tabular}\par -\medskip -Other combinations need to be set with \cs{TrackLocale} or -\cs{TrackLanguageTag}. -\end{table}} - -\tmpctr=0\relax - -\@for\thisdialect:=\nonisopkgopts\do{% - \advance\tmpctr by 1\relax - \eappto\nonisopkgoptstab{\noexpand\pkgoptfmt{\thisdialect}}% - {%locally track this dialect to pick up information - \TrackPredefinedDialect\thisdialect - \IfTrackedLanguageHasIsoCode{3166-1}{\thisdialect}% - {\gappto\nonisopkgoptstab{\fnregion}}% - {}% - \IfTrackedDialectHasMapping\thisdialect - {\def\nonisopkgmap{ / - \noexpand\texttt{\GetTrackedDialectToMapping\thisdialect}}}% - {\def\nonisopkgmap{}}% - \xappto\nonisopkgoptstab{\space - {\noexpand\small(\noexpand\texttt{\GetTrackedLanguageTag\thisdialect}% - \nonisopkgmap)}}% - }% - \ifnum\tmpctr>1 - \tmpctr = 0\relax - \appto\nonisopkgoptstab{\\}% - \else - \appto\nonisopkgoptstab{&}% - \fi -} - -\appto\nonisopkgoptstab{\end{longtable}} - -\tmpctr=0\relax - -\@for\thisdialect:=\rootlangopts\do{% - \advance\tmpctr by 1\relax - \eappto\rootlangoptstab{\noexpand\pkgoptfmt{\thisdialect}}% - \TrackLangIfHasKnownCountry{\thisdialect}% - {% - \appto\rootlangoptstab{\fnregion}% - }% - {}% - {%locally track this language to pick up information - \TrackPredefinedDialect\thisdialect - \xappto\rootlangoptstab{\space - {\noexpand\small(\noexpand\texttt{\GetTrackedLanguageTag\thisdialect})}}% - }% - \ifnum\tmpctr>2 - \tmpctr = 0\relax - \appto\rootlangoptstab{\\}% - \else - \appto\rootlangoptstab{&}% - \fi -} - -\appto\rootlangoptstab{\end{longtable}} - -\makeatother - -\newcommand*{\refoptstables}{tables~\ref{tab:isoopts}, \ref{tab:rootlangopts} -and~\ref{tab:nonisoopts}} - -\begin{document} -\DocInput{tracklang.dtx} -\end{document} -% -%\fi -% -%\MakeShortVerb{"} -% -%\title{tracklang v1.5: -%tracking language options} -%\author{Nicola L. C. Talbot\\\url{http://www.dickimaw-books.com/}} -% -%\date{2020-06-30} -%\maketitle -% -%\begin{abstract} -%The \styfmt{tracklang} package is provided for package developers -%who want a simple interface to find out which languages the user has -%requested through packages such as \sty{babel} and -%\sty{polyglossia}. \emph{This package doesn't provide any -%translations.} -%Its purpose is simply to track which languages have been requested by the -%user. Generic \TeX\ code is in \texttt{tracklang.tex} for -%non-\LaTeX\ users. -% -%If the shell escape is enabled or \ics{directlua} is available, -%this package may also be used to query the \envvar{LC\_ALL} -%or \envvar{LANG} environment variable (see -%\sectionref{sec:langsty}). Windows users, who don't have the locale -%stored in environment variables, can use \app{texosquery} -%in combination with \styfmt{tracklang}. (Similarly if \envvar{LC\_ALL} -%or \envvar{LANG} don't contain sufficient information.) In order to -%use \app{texosquery} through the restricted shell escape, you must -%have at least Java~8 and set up \texttt{texosquery.cfg} -%appropriately. (See the \app{texosquery} manual for further details.) -%\end{abstract} -% -%The fundamental aim of this generic package is to be able to -%effectively say: -%\begin{quote} -%The user (that is, the \emph{document} author) wants to use -%dialects \texttt{xx-XX}, \texttt{yy-YY-Scrp}, etc in their -%document. Any packages used by their document that provide -%multilingual or region-dependent support should do whatever is -%required to activate the settings for those languages and regions -%(or warn the user that there's no support). -%\end{quote} -%Naturally, this is only of use if the locale-sensitive packages use -%\styfmt{tracklang} to pick up this information, which is entirely up -%to the package authors, but at the moment there's no standard method -%for packages to detect the required language and region. The aim of -%\styfmt{tracklang} is to provide that method. In particular, the -%emphasis is on using ISO language and region codes rather than -%hard-coding the various language labels used by different language -%packages. -% -%Related articles: \qt{Localisation of \TeX\ documents: -%\styfmt{tracklang}.} TUGBoat, Volume~37 (2016), No.~3 -%(\url{http://www.tug.org/TUGboat/tb37-3/tb117talbot.pdf}), -%\href{https://www.dickimaw-books.com/latex/tracklang}{Localisation -%with \texttt{tracklang.tex}}, -%and -%\href{https://www.dickimaw-books.com/faq.php?action=view&category=tracklang}{\texttt{tracklang} -%FAQ}. -% -%\clearpage -%\tableofcontents -%\clearpage\phantomsection -%\pdfbookmark{Tables}{lot}% -%\listoftables -% -%\chapter{Introduction} -%\label{sec:intro} -% -%When I'm developing a package that provides multilingual support -%(for example, \styfmt{glossaries}) it's cumbersome trying to work out -%if the user has requested translations for fixed text. This usually -%involves checking if \sty{babel} or \sty{ngerman} or -%\sty{translator} or \sty{polyglossia} has been loaded and, if so, -%what language settings have been used. The result can be a tangled -%mass of conditional code. The alternative is to tell users to add -%the language as a~document class option, which they may or may not -%want to do, or to tell them to supply the language settings to every -%package they load that provides multilingual support, which users -%are even less likely to want to do. -% -%The \styfmt{tracklang} package tries to neaten this up by working out -%as much of this information as possible for you and providing a -%command that iterates through the loaded languages. This way, you -%can just iterate through the list of tracked languages and, for each -%language, either define the translations or warn the user that -%there's no translation for that language. -% -%This package works best with \sty{ngerman} or with recent versions -%of \sty{babel} or when the language options are specified -%in the document class option list. It works fairly well with -%\sty{translator} but will additionally assume the root language was -%also requested when a dialect is specified. So, for example, -%\begin{verbatim} -%\usepackage[british]{translator} -%\usepackage{tracklang} -%\end{verbatim} -%is equivalent to -%\begin{verbatim} -%\usepackage[british]{translator} -%\usepackage[english,british]{tracklang} -%\end{verbatim} -%This means that \ics{ForEachTrackedDialect} will iterate -%through the list \qt{english,british} instead of just -%\qt{british}, which can result in some redundancy. -% -%Unfortunately I can't work out how to pick up the language variant -%or script from \sty{polyglossia}, so only the root languages are detected, -%which is suboptimal but at least provides some information. -%(\sty{polyglossia} now provides \cs{xpg@loaded}, which -%\sty{tracklang} uses to track the root languages, but the language variant -%command \cs{xpg@loaded} only seems to be set when the language -%changes, which doesn't occur until the start of the \env{document} -%environment.) -% -%I also can't find any way of detecting a list of languages loaded -%through \sty{babel}'s new \ics{babelprovide} command. As far as I -%can tell, the only stored list is in \cs{bbl@loaded} which only -%contains the languages loaded through package options. -% -%If the \sty{ngerman} package has been loaded, \styfmt{tracklang} -%effectively does -%\begin{verbatim} -%\TrackPredefinedDialect{ngerman} -%\end{verbatim} -%Similarly, if the \sty{german} package has been loaded, -%\styfmt{tracklang} effectively does -%\begin{verbatim} -%\TrackPredefinedDialect{german} -%\end{verbatim} -% -%If any document class or package options are passed to -%\styfmt{tracklang}, then \styfmt{tracklang} won't bother checking -%for \sty{babel}, \sty{translator}, \sty{ngerman}, \sty{german} or -%\sty{polyglossia}. So, if the above example is changed to: -%\begin{verbatim} -%\documentclass[british]{article} -%\usepackage{translator} -%\usepackage{tracklang} -%\end{verbatim} -%then the dialect list will just consist of \qt{british} rather than -%\qt{english,british}. This does, however, mean that if the user mixes -%class and package options, only the class options will be detected. -%For example: -%\begin{verbatim} -%\documentclass[british]{article} -%\usepackage[french]{babel} -%\usepackage{tracklang} -%\end{verbatim} -%In this case, only the \qt{british} option will be detected. The user -%can therefore use the document class option (or \styfmt{tracklang} -%package option) to override the dialect and set the country code -%(where provided). For example: -%\begin{verbatim} -%\documentclass[es-MX]{article} -%\usepackage[spanish]{babel} -%\usepackage{tracklang} -%\end{verbatim} -%This sets the dialect to \qt{mexicanspanish} and the root language to -%\qt{spanish}. -% -%Predefined dialects are listed in \refoptstables. These may be -%passed in the document class options or -%used in \ics{TrackPredefinedDialect}, as illustrated above. -% -%\sectionref{sec:summary} provides brief examples of use for those -%who want a general overview before reading the more detailed -%sections. -%\sectionref{sec:generic} describes generic commands for -%identifying the document languages. -%\sectionref{sec:user} is for package writers who want to -%add multilingual support to their package and need to know which -%settings the user has requested through language packages like -%\sty{babel}. \sectionref{sec:langsty} is for -%developers of language definition packages who want to help other -%package writers to detect what languages have been requested. -% -%\isopkgoptstab -% -%\clearpage -% -%\rootlangoptstab -% -%\clearpage -% -%\nonisopkgoptstab -% -%\chapter{Summary of Use} -%\label{sec:summary} -% -%There are three levels of use: -%\begin{enumerate} -%\item document level (code used by document authors); -%\item locale-sensitive package level -%(code for package authors who need to -%know what languages or locale the document is -%using, such as \styfmt{glossaries} to translate commands like -%\cs{descriptionname} or \styfmt{datetime2} to provide localised -%formats or time zone information); -%\item language set-up level (code for packages that set up -%the document languages, such as \sty{babel} or \sty{polyglossia}). -%\end{enumerate} -% -%\section{Document Level} -%\label{sec:summary-doc} -% -%\subsection{Generic \texorpdfstring{\TeX}{TeX}} -%Unix user wants the locale information picked up from the -%locale environment variable: -%\begin{verbatim} -%\input tracklang % v1.3 -%\TrackLangFromEnv -%% load packages that use tracklang for localisation -%\end{verbatim} -% -%Windows user wants the locale information picked up from the -%operating system: -%\begin{verbatim} -%\input texosquery -%\input tracklang % v1.3 -%\TrackLangFromEnv -%% load packages that use tracklang for localisation -%\end{verbatim} -%Or (\sty{texosquery} v1.2) -%\begin{verbatim} -%\input texosquery % v1.2 -%\input tracklang % v1.3 -% -%\TeXOSQueryLangTag{\langtag} -%\TrackLanguageTag{\langtag} -%% load packages that use tracklang for localisation -%\end{verbatim} -%Linux user who may or may not have \app{texosquery} setup to run in the -%shell escape: -%\begin{verbatim} -%\input texosquery -%\input tracklang % v1.3 -% -%\ifx\TeXOSQueryLangTag\undefined -% \TrackLangFromEnv -%\else -% \TeXOSQueryLangTag{\langtag} -% \TrackLanguageTag{\langtag} -%\fi -%% load packages that use tracklang for localisation -%\end{verbatim} -% -%User is writing in Italy in Armenian with a Latin -%script and the arevela variant: -%\begin{verbatim} -%\input tracklang % v1.3 -%\TrackLanguageTag{hy-Latn-IT-arevela} -%% load packages that use tracklang for localisation -%\end{verbatim} -% -%User is writing in English in the UK: -%\begin{verbatim} -%\input tracklang -%\TrackPredefinedDialect{british} -%% load packages that use tracklang for localisation -%\end{verbatim} -% -%Find out information about the current language (supplied -%in \cs{languagename}): -%\begin{verbatim} -%\SetCurrentTrackedDialect{\languagename} -%Dialect: \CurrentTrackedDialect. -%Language: \CurrentTrackedLanguage. -%ISO Code: \CurrentTrackedIsoCode. -%Region: \CurrentTrackedRegion. -%Modifier: \CurrentTrackedDialectModifier. -%Variant: \CurrentTrackedDialectVariant. -%Script: \CurrentTrackedDialectScript. -%Sub-Lang: \CurrentTrackedDialectSubLang. -%Additional: \CurrentTrackedDialectAdditional. -%Language Tag: \CurrentTrackedLanguageTag. -%\end{verbatim} -%Additional information about the script can be obtained by -%also loading \sty{tracklang-scripts}: -%\begin{verbatim} -%\input tracklang-scripts -%\end{verbatim} -%The name, numeric code and direction can now be obtained: -%\begin{verbatim} -%Name: \TrackLangScriptAlphaToName{\CurrentTrackedDialectScript}. -%Numeric: \TrackLangScriptAlphaToNumeric{\CurrentTrackedDialectScript}. -%Dir: \TrackLangScriptAlphaToDir{\CurrentTrackedDialectScript}. -%\end{verbatim} -%Test for a specific script: -%\begin{verbatim} -%Latin? -%\ifx\CurrentTrackedDialectScript\TrackLangScriptLatn -% Yes -%\else -% No -%\fi -%\end{verbatim} -% -%\subsection{\texorpdfstring{\LaTeX}{LaTeX}} -% -%For \sty{babel} users where the supplied \sty{babel} dialect -%label is sufficient, there's no need to do anything special: -%\begin{verbatim} -%\documentclass[british,canadien]{article} -%\usepackage[T1]{fontenc} -%\usepackage{babel} -%% load packages that use tracklang for localisation -%\end{verbatim} -%If the region is important but there's no \sty{babel} dialect -%that represents it, there are several options. -% -%Use the class options recognised by \styfmt{tracklang} -%and the root language labels when loading \sty{babel}: -%\begin{verbatim} -%\documentclass[en-IE,ga-IE]{article} -%\usepackage[english,irish]{babel} -%% load packages that use tracklang for localisation -%\end{verbatim} -% -%This method is needed for \sty{polyglossia} where the regional -%information is required. For example -%\begin{verbatim} -%\documentclass[en-GB]{article} -%\usepackage{polyglossia} -%\setmainlanguage[variant=uk]{english} -%% load packages that use tracklang for localisation -%\end{verbatim} -% -%Another method with \sty{babel} is to -%use \cs{TrackLanguageTag} and map the new dialect label to -%\sty{babel}'s nearest matching label: -%\begin{verbatim} -%\documentclass{article} -% -%\usepackage{tracklang}% v1.3 -%\TrackLanguageTag{en-MT} -%\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish} -% -%\usepackage[UKenglish]{babel} -%% load packages that use tracklang for localisation -%\end{verbatim} -%This ensures that the \cs{captionsUKenglish} hook is detected -%by the localisation packages. This mapping isn't needed -%for \sty{polyglossia} as the caption hooks use the root language -%label. This mapping also isn't needed if \texttt{british} is used -%instead of \texttt{UKenglish} since the \pkgopt{en-MT} -%(\pkgopt{maltaenglish}) -%predefined dialect automatically sets up a mapping to -%\texttt{british}. (The default mappings are shown in -%\tableref{tab:nonisoopts}.) -% -%\section{Locale-Sensitive Packages} -%\label{sec:summary-localepkg} -% -%Let's suppose you are developing a package called -%\texttt{mypackage.sty} or \texttt{mypackage.tex} and you want -%to find out what languages the document author has requested. (See also: -%\href{https://www.dickimaw-books.com/latex/tracklang/otherpkg.shtml}{Using -%\texttt{tracklang.tex} in Packages with Localisation Features}.) -% -%Generic use: -%\begin{verbatim} -%\input tracklang -%\end{verbatim} -%(Most of the commands used in this section require at least -%\styfmt{tracklang} version 1.3 but 1.4 is better if you want to -%include the script tag in the ldf files.) -%Note that \texttt{tracklang.tex} has a check to determine if -%it's already been loaded, so you don't need to worry about that. -% -%\LaTeX\ use: -%\begin{verbatim} -%\RequirePackage{tracklang}[2019/11/30]% at least v1.4 -%\end{verbatim} -%This will picked up any language options supplied in the document -%class options and will also detect if \sty{babel} or -%\sty{polyglossia} have been loaded. -% -%(\LaTeX) If you want to allow the user to set the locale in the -%package options: -%\begin{verbatim} -%\DeclareOption*{\TrackLanguageTag{\CurrentOption}} -%\end{verbatim} -%This means the user can do, say, -%\begin{verbatim} -%\usepackage[hy-Latn-IT-arevela]{mypackage} -%\end{verbatim} -%With at least version 1.4, it's better to use \ics{TrackIfKnownLanguage}: -%\begin{verbatim} -%\DeclareOption*{% -% \TrackIfKnownLanguage{\CurrentOption}% -% {\PackageInfo{mypackage}{Tracking language `\CurrentOption'}}% successful -% {% failed -% \PackageError{mypackage}% -% {Unknown language specification `\CurrentOption'}% -% {You need to supply either a known dialect label or a valid language tag}% -% }% -%} -%\end{verbatim} -% -%The rest of the example package in this section uses generic code. -% -%If you want to fetch the locale information from the operating -%system when the user hasn't requested a language: -%\begin{verbatim} -%\AnyTrackedLanguages -%{} -%{% fetch locale information from the operating system -% \ifx\TeXOSQueryLangTag\undefined -% % texosquery v1.2 not available -% \TrackLangFromEnv -% \else -% % texosquery v1.2 available -% \TeXOSQueryLangTag{\langtag} -% \TrackLanguageTag{\langtag} -% \fi -%} -%\end{verbatim} -% -%Set up the defaults if necessary: -%\begin{verbatim} -%\def\fooname{Foo} -%\def\barname{Bar} -%\end{verbatim} -% -%Now load the resource files: -%\begin{verbatim} -%\AnyTrackedLanguages -%{% -% \ForEachTrackedDialect{\thisdialect}{% -% \TrackLangRequireDialect{mypackage}{\thisdialect}% -% }% -%} -%{}% no tracked languages, default already set up -%\end{verbatim} -% -%Each resource file has the naming scheme \meta{prefix}\texttt{-} -%\meta{localeid}\texttt{.ldf}. In this example, the \meta{prefix} is -%\texttt{mypackage}. The \meta{localeid} part may be the language or dialect label -%(for example, \texttt{english} or \texttt{british}) or a combination of the ISO -%language and region codes (for example, \texttt{en-GB} or -%\texttt{en} or \texttt{GB}). As from version 1.4, \meta{localeid} may -%also include the script or variant. (See the definition of -%\ics{IfTrackedLanguageFileExists} on page~\pageref{pg:filesearch} -%for further details.) -% -%The simplest scheme is to use the root language label (not the -%dialect label) for the base language settings and use the ISO -%codes for regional support. -% -%For example, the file \texttt{mypackage-english.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{english}[2016/10/06 v1.0]% identify this file -% -%\TrackLangAddToCaptions{% -% \def\fooname{Foo}% -% \def\barname{Bar}% -%} -%\end{verbatim} -%This sets up appropriate the \cs{captions\ldots} hook (if it's -%found). For other hooks, such as \cs{date\ldots}, use -%\ics{TrackLangAddToHook}\marg{code}\marg{hook type} instead. -% -%With pre-v1.4 versions of \sty{tracklang}, the script isn't included -%in the file search. If it's needed then either require at least v1.4 -%or have a base ldf file that tries to load a version for the -%particular script (which can be accessed with -%\cs{CurrentTrackedScript}). -%Here's an example for a language with different writing systems. -%The resource file for Serbian \texttt{mypackage-serbian.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{serbian}[2016/10/06 v1.0]% identify file -% -%\TrackLangRequestResource{serbian-\CurrentTrackedScript} -%{}% file not found, do something sensible here -%\end{verbatim} -%The file \texttt{mypackage-serbian-Latn.ldf} sets up -%the Latin script: -%\begin{verbatim} -%\TrackLangProvidesResource{serbian-Latn}[2016/10/06 v1.0] -% -%\TrackLangAddToCaptions{% -% \def\fooname{...}% provide appropriate Latin translations -% \def\barname{...}% -%} -%\end{verbatim} -%The file \texttt{mypackage-serbian-Cyrl.ldf} sets up -%the Cyrllic script: -%\begin{verbatim} -%\TrackLangProvidesResource{serbian-Cyrl}[2016/10/06 v1.0] -% -%\TrackLangAddToCaptions{% -% \def\fooname{...}% provide appropriate Cyrllic translations -% \def\barname{...}% -%} -%\end{verbatim} -% -%With v1.4+ you would just need \texttt{mypackage-sr-Latn.ldf}, -%\texttt{mypackage-sr-Cyrl.ldf} for the regionless versions. -% -%\section{Language Packages} -%\label{sec:summary-langpkg} -% -%Let's suppose now you're the developer of a package that -%sets up the language, hyphenation patterns and so on. -%It would be really helpful to the locale-sensitive packages -%in \sectionref{sec:summary-localepkg} to know what languages -%the document author has requested. You can use the -%\styfmt{tracklang} package to identify this information -%by tracking the requested localisation, so that other packages -%can have a consistent way of querying it. (See also: -%\href{https://www.dickimaw-books.com/latex/tracklang/langpkg.shtml}{Integrating -%\texttt{tracklang.tex} into Language Packages}.) -% -%Generic use: -%\begin{verbatim} -%\input tracklang -%\end{verbatim} -%Alternative \LaTeX\ use: -%\begin{verbatim} -%\RequirePackage{tracklang}[2019/11/30] % v1.4 -%\end{verbatim} -%Unlike \cs{input}, \cs{RequirePackage} will allow \styfmt{tracklang} -%to pick up the document class options, but using \cs{RequirePackage} -%will also trigger the tests for known language packages. -%(If you want to find out if \styfmt{tracklang} has already been -%loaded and locales have already been tracked, you can use the -%same code as in the previous section.) -% -%When a user requests a particular language through your package, -%the simplest way of letting \styfmt{tracklang} know about it -%is to use \cs{TrackPredefinedDialect} or \cs{TrackLanguageTag}. -%For example, if the user requests \texttt{british}, that's a -%predefined dialect so you can just do: -%\begin{verbatim} -%\TrackPredefinedDialect{british} -%\end{verbatim} -%Alternatively -%\begin{verbatim} -%\TrackLanguageTag{en-GB} -%\end{verbatim} -%If your package uses caption hooks, then you can set up -%a mapping between \styfmt{tracklang}'s internal dialect label -%and your caption label. For example, let's suppose the -%closest match to English used in Malta (\texttt{en-MT}) is the -%dialect \texttt{UKenglish} (for example, the date format is -%similar between GB and MT): -%\begin{verbatim} -%\TrackLanguageTag{en-MT} -%\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish} -%\def\captionsUKenglish{% -% \def\contentsname{Contents}% -% %... -%} -%\end{verbatim} -%(The predefined \pkgopt{maltaenglish} option provided by -%\styfmt{tracklang} automatically sets the mapping to -%\texttt{british}, but the above method will change that mapping -%to \texttt{UKenglish}.) -% -%This now means that \cs{TrackLangAddToHook} and \cs{TrackLangRedefHook} commands can -%find your language hooks. You don't need the map if your dialect -%label is the same as \styfmt{tracklang}'s root language label -%for that locale. For example: -%\begin{verbatim} -%\TrackLanguageTag{en-MT} -%\def\captionsenglish{% -% \def\contentsname{Contents}% -% %... -%} -%\end{verbatim} -% -%When the user switches language through commands like -%\ics{selectlanguage} it would be useful to also use -%\ics{SetCurrentTrackedDialect}\marg{dialect} to make it easier -%for the document author or locale-sensitive packages to pick -%up the current locale. The \meta{dialect} argument may be -%\styfmt{tracklang}'s internal dialect label or the dialect -%label you assigned with \cs{SetTrackedDialectLabelMap}. It -%may also be the root language label, in which case -%\styfmt{tracklang} will search for the last dialect to be -%tracked with that language. For example: -%\begin{verbatim} -%\def\selectlanguage#1{% -% \SetCurrentTrackedDialect{#1}% -% % set up hyphenation patterns etc -%} -%\end{verbatim} -%See the example in \sectionref{sec:summary-doc} or the example in -%\href{https://www.dickimaw-books.com/latex/tracklang/langpkg.shtml}{Integrating -%\texttt{tracklang.tex} into Language Packages}. -% -%\chapter{Generic Use} -%\label{sec:generic} -% -%For plain \TeX\ you can input \texttt{tracklang.tex}: -%\begin{verbatim} -%\input tracklang -%\end{verbatim} -%or for \TeX\ formats that have an argument form for \ics{input}: -%\begin{verbatim} -%\input{tracklang} -%\end{verbatim} -%As from version 1.3, you don't need to change the category -%code of \texttt{@} before loading \texttt{tracklang.tex} -%as it will automatically be changed to 11 and switched -%back at the end (if required). -% -%The \LaTeX\ package \texttt{tracklang.sty} -%inputs the generic \TeX\ code in \texttt{tracklang.tex}, but before -%it does so it defines -%\begin{definition} -%\cs{@tracklang@declareoption}\marg{name} -%\end{definition} -%to -%\begin{definition} -%\cs{DeclareOption}\marg{name}\{\cs{TrackPredefinedDialect}\marg{name}\} -%\end{definition} -% -%This means that all the predefined languages and dialects -%(\refoptstables) automatically become package options, so -%the \styfmt{tracklang} package can pick up document class -%options and add them to \styfmt{tracklang}'s internal list of tracked -%document languages. -% -%If you're not using \LaTeX, this option isn't available -%(although you could redefine the internal command -%\cs{@tracklang@declareoption} -%to use something analogous to \cs{DeclareOption}). -%Instead, the document languages need -%to be explicitly identified (using any of the following commands) -%so that \styfmt{tracklang} knows about them. -% -%\begin{definition}[\DescribeMacro\TrackPredefinedDialect] -%\ics{TrackPredefinedDialect}\marg{dialect label} -%\end{definition} -%This will add the predefined dialect and its associated ISO codes to the list -%of tracked document languages. The \meta{dialect label} may be any -%of those listed in \refoptstables. -%(See also \sectionref{sec:predefinedlang} and \sectionref{sec:predefined}.) -% -%For example: -%\begin{verbatim} -%\input tracklang -%\TrackPredefinedDialect{british} -%\end{verbatim} -%is the Plain \TeX\ alternative to -%\begin{verbatim} -%\documentclass[british]{article} -%\usepackage{tracklang} -%\end{verbatim} -% -%Note that it's impractical to define every possible language -%and region combination as it would significantly slow the -%time taken to load \styfmt{tracklang} so, after version~1.3, -%I don't intend adding any new predefined dialects. As from version -%1.3, if you want to track a dialect that's not predefined by -%\styfmt{tracklang}, then you can use: -%\begin{definition}[\DescribeMacro\TrackLocale] -%\cs{TrackLocale}\marg{locale} -%\end{definition} -%If \meta{locale} is a recognised dialect, this is equivalent to -%using \cs{TrackPredefinedDialect}, otherwise \meta{locale} -%needs to be in one the following formats: -%\begin{itemize} -%\item \meta{ISO lang} -%\item \meta{ISO lang}\texttt{@}\meta{modifier} -%\item \meta{ISO lang}\texttt{-}\meta{ISO country} -%\item \meta{ISO lang}\texttt{-}\meta{ISO country}\texttt{@}\meta{modifier} -%\end{itemize} -%where \meta{ISO lang} is the ISO~639-1 or 639-2 code identifying -%the language (lower case), \meta{ISO country} is the 3166-1 -%ISO code identifying the territory (upper case) and -%\meta{modifier} is the modifier or variant. The hyphen may be -%replaced by an underscore character. Code set information in the -%form \texttt{.}\meta{codeset} may optionally appear before the -%modifier. For example, \texttt{de-DE.utf8@new} (modifier is -%\texttt{new}) or \texttt{en-GB.utf8} (modifier is missing). -%The codeset will be ignored if present, but it won't interfere -%with the parsing. -% -%For example: -%\begin{verbatim} -%\TrackLocale{de-NA@new} -%\end{verbatim} -%indicates German in Namibia using the new spelling. -% -%\begin{important} -%If a language has different \qt{T} and \qt{B} ISO~639-2 codes, then -%the \qt{T} form should be used. (So for the above example, -%\texttt{deu} may be used instead of \texttt{de}, but \texttt{ger} -%won't be recognised.) -%\end{important} -% -%Alternatively, you can use -%\begin{definition}[\DescribeMacro\TrackLanguageTag] -%\cs{TrackLanguageTag}\marg{tag} -%\end{definition} -%where \meta{tag} is a regular, well-formed language tag or a recognised dialect -%label. (Irregular grandfather tags aren't recognised.) -%This command will fully expand \meta{tag}. -%A warning is issued if the tag is empty. -% -%If you want to first check that \meta{tag} includes a valid language -%code, then you can instead use: -%\begin{definition}[\DescribeMacro\TrackIfKnownLanguage] -%\cs{TrackIfKnownLanguage}\marg{tag}\marg{success code}\marg{fail code} -%\end{definition} -%This will only track \meta{tag} (and then do \meta{success code}) if -%\meta{tag} starts with a valid language code (or is a predefined -%dialect) otherwise it will do \meta{fail code}. Both -%\cs{TrackLanguageTag} and \cs{TrackIfKnownLanguage} will check if -%\meta{tag} is a predefined option. (This saves parsing the tag if -%it's recognised.) -% -%For example: -%\begin{verbatim} -%\TrackLanguageTag{hy-Latn-IT-arevela} -%Latn-ME: \TrackIfKnownLanguage{Latn-ME}{success}{fail}. -%brazilian: \TrackIfKnownLanguage{brazilian}{success}{fail}. -%\end{verbatim} -%This will track hy-Latn-IT-arevela and brazilian (pt-BR) but not -%Latn-ME (because it doesn't contain a valid language code) even -%though it's a valid script and country code. The above is just for -%illustrative purposes. Typically the language tracking isn't -%performed within the document text. -% -%The \sty{datetime2} package assumes that any unknown package option is a -%language identifier. It could simply do: -%\begin{verbatim} -%\TrackLanguageTag{\CurrentOption} -%\end{verbatim} -%but users can make mistakes sometimes and this won't provide any -%helpful information if they, for example, misspelt a package option -%or forgot the ``\meta{key}='' part of a \meta{key}=\meta{value} -%setting. Instead (as from v1.5.5) it does: -%\begin{verbatim} -%\TrackIfKnownLanguage{\CurrentOption}{...}{\PackageError{...}{...}{...}} -%\end{verbatim} -%This will now give the user some guidance. -% -%If \meta{tag} contains a sub-language tag, this will be set -%as the 639-3 code for the \emph{dialect} label. Note that this is -%different to the root language codes which are set using the -%language label. For example -%\begin{verbatim} -%\TrackLanguageTag{zh-cmn-Hans-CN} -%\end{verbatim} -%creates a new dialect with the label \texttt{zhcmnHansCN}. -%The root language \texttt{chinese} has the ISO 639-1 code -%\texttt{zh} and the dialect \texttt{zhcmnHansCN} has the -%ISO 639-3 code \texttt{cmn}. -%\begin{verbatim} -%ISO 639-1: \TrackedIsoCodeFromLanguage{639-1}{chinese}. -%ISO 639-3: \TrackedIsoCodeFromLanguage{639-3}{zhcmnHansCN}. -%\end{verbatim} -% -%Version 1.2 of \sty{texosquery} provides the command \ics{TeXOSQueryLangTag}, -%which may be used to fetch the operating system's regional -%information as a language tag. These commands can be used as -%follows: -%\begin{verbatim} -%\input tracklang % v1.3 -%\input texosquery % v1.2 -% -%\TeXOSQueryLangTag{\langtag} -%\TrackLanguageTag{\langtag} -%\end{verbatim} -%(If the shell escape is disabled, \cs{langtag} will be empty, which -%will trigger a~warning but no errors.) -% -%Some of the predefined root language options listed -%in \tableref{tab:rootlangopts} have an associated region -%(denoted by \fnregion). -%If \cs{TrackLocale} is used with just the language ISO code, -%no region is tracked for that language. For example -%\begin{verbatim} -%\TrackLocale{manx} -%\end{verbatim} -%will track the \qt{IM} ISO~3166-1 code but -%\begin{verbatim} -%\TrackLocale{gv} -%\end{verbatim} -%won't track the region. -%Similarly for \cs{TrackLanguageTag}. -% -%(New to version 1.3.) -%There's a similar command to \cs{TrackLocale} that doesn't take an argument: -%\begin{definition}[\DescribeMacro\TrackLangFromEnv] -%\cs{TrackLangFromEnv} -%\end{definition} -%If the shell escape has been enabled or -%\ics{directlua} is available, this will try to get the language -%information from the system environment variables -%\envvar{LC\_ALL} or \envvar{LANG} -%and, if successful, track that. -% -%Since \styfmt{tracklang} is neither able to look up the POSIX locale -%tables nor interpret file locales, if the result is \texttt{C} or -%\texttt{POSIX} or starts with a forward slash \texttt{/} then -%the locale value is treated as empty. -% -%\begin{important} -%Not all operating systems use environment variables for -%the system locale information. For example, Windows stores the -%locale information in the registry. In which case, consider -%using \styfmt{texosquery}. -%\end{important} -% -%If the operating system locale can't be obtained from environment variables, then -%\styfmt{tracklang} will use \ics{TeXOSQueryLocale} as a fallback if -%\styfmt{texosquery} has been loaded. Since \sty{texosquery} requires -%both the shell escape and the Java runtime environment, -%\styfmt{tracklang} doesn't automatically load it. -% -%Plain \TeX\ example: -%\begin{verbatim} -%\input texosquery -%\input tracklang -%\TrackLangFromEnv -%\end{verbatim} -%with \texttt{etex -{}-shell-escape }\meta{filename} -% -%\LaTeX\ example: -%\begin{verbatim} -%\usepackage{texosquery} -%\usepackage{tracklang} -%\TrackLangFromEnv -%\end{verbatim} -%with \texttt{latex -{}-shell-escape }\meta{filename} -% -%If the locale can't be determined, there will be warning messages. -%These can be suppressed using -%\begin{definition}[\DescribeMacro\TrackLangShowWarningsfalse] -%\cs{TrackLangShowWarningsfalse} -%\end{definition} -%or switched back on again using -%\begin{definition}[\DescribeMacro\TrackLangShowWarningstrue] -%\cs{TrackLangShowWarningstrue} -%\end{definition} -% -%For example, I have the environment variable \envvar{LANG} set to -%\texttt{en\_GB.utf8} on my Linux system so instead of -%\begin{verbatim} -%\TrackPredefinedDialect{british} -%\end{verbatim} -%I can use -%\begin{verbatim} -%\TrackLangFromEnv -%\end{verbatim} -% -%With \LaTeX\ documents I can do -%\begin{verbatim} -%\documentclass{article} -%\usepackage{tracklang} -%\TrackLangFromEnv -%\end{verbatim} -%However, this only helps subsequently loaded packages that -%use \styfmt{tracklang} to determine the required regional -%settings. For example: -%\begin{verbatim} -%\documentclass{article} -%\usepackage{tracklang} -%\TrackLangFromEnv -%\usepackage[useregional]{datetime2} -%\end{verbatim} -%In my case, with \envvar{LANG} set to \texttt{en\_GB.utf8} and -%shell escape enabled, this automatically switches on the -%\texttt{en-GB} date style. -%Naturally this doesn't help locale-sensitive packages that don't use -%\styfmt{tracklang}. -% -%The \cs{TrackLangFromEnv} command also incidentally sets -%\begin{definition}[\DescribeMacro\TrackLangEnv] -%\cs{TrackLangEnv} -%\end{definition} -%to the value of the environment variable or empty if the -%query was unsuccessful (for example, the shell escape is -%unavailable). -% -%If \cs{TrackLangEnv} is already defined before -%\cs{TrackLangFromEnv} is used, then the environment variable -%won't be queried and the value of \cs{TrackLangEnv} will be -%parsed instead. -% -%\begin{important} -%The parser which splits the locale string into -%its component parts first tries splitting on the underscore -%\texttt{\_} with its usual category code~8, then tries splitting -%on a hyphen \texttt{-} with category code~12, and then tries -%splitting on the underscore \texttt{\_} with category code~12. -%\end{important} -% -%For example: -%\begin{verbatim} -%\def\TrackLangEnv{en-GB} -%\TrackLangFromEnv -%\end{verbatim} -%This doesn't perform a shell escape since \cs{TrackLangEnv} -%is already defined. In this case, you may just as well use -%\begin{verbatim} -%\TrackLocale{en-GB} -%\end{verbatim} -%(unless you happen to additionally require the component -%commands that are set by \cs{TrackLangFromEnv}, see below.) -% -%If the shell escape is unavailable -%(for example, your \TeX\ installation prohibits it), you -%can set this value when you invoke \TeX. For example, -%if the document file is called \texttt{myDoc.tex} (and it's -%in Plain \TeX): -%\begin{verbatim} -%tex "\\def\TrackLangEnv{$LANG}\\input myDoc" -%\end{verbatim} -% -%The \cs{TrackLangFromEnv} command also happens to store the -%component parts of the environment variable value in the -%following commands. (These aren't provided by -%\cs{TrackLocale}.) -% -%The language code is stored in: -%\begin{definition}[\DescribeMacro\TrackLangEnvLang] -%\cs{TrackLangEnvLang} -%\end{definition} -% -%The territory (if present) is stored in: -%\begin{definition}[\DescribeMacro\TrackLangEnvTerritory] -%\cs{TrackLangEnvTerritory} -%\end{definition} -%(Defined to empty if not present.) -% -%The codeset (if present) is stored in: -%\begin{definition}[\DescribeMacro\TrackLangEnvCodeSet] -%\cs{TrackLangEnvCodeSet} -%\end{definition} -%(Defined to empty if not present.) -% -%The modifier (if present) is stored in: -%\begin{definition}[\DescribeMacro\TrackLangEnvModifier] -%\cs{TrackLangEnvModifier} -%\end{definition} -%(Defined to empty if not present.) -% -%If you want to query the language environment, but don't -%want to track the result, you can just use: -%\begin{definition}[\DescribeMacro\TrackLangQueryEnv] -%\cs{TrackLangQueryEnv} -%\end{definition} -%This only tries to fetch the value of the -%language environment variable (and use \sty{texosquery} as -%a fallback, if it has been loaded). It doesn't try to parse the -%result. The result is stored in \cs{TrackLangEnv} (empty if -%unsuccessful). Unlike \cs{TrackLangFromEnv}, this doesn't check if -%\cs{TrackLangEnv} already exists. A warning will occur if the shell -%escape is unavailable. For systems that store the locale information in -%environment variables, this is more efficient than using -%\sty{texosquery}'s \cs{TeXOSQueryLocale} command (which is what's -%used as the fallback). -% -%The above queries \envvar{LC\_ALL} and, if that is unsuccessful, -%then queries \envvar{LANG} (before optionally falling back on -%\sty{texosquery}). If you want another environment -%variable tried after \envvar{LC\_ALL} and before \envvar{LANG}, -%you can instead use: -%\begin{definition}[\DescribeMacro\TrackLangQueryOtherEnv] -%\cs{TrackLangQueryOtherEnv}\marg{name} -%\end{definition} -%For example, to also query \envvar{LC\_MONETARY}: -%\begin{verbatim} -%\TrackLangQueryOtherEnv{LC_MONETARY} -%\end{verbatim} -% -%Since this sets \cs{TrackLangEnv}, you can use it before -%\cs{TrackLangFromEnv}. For example: -%\begin{verbatim} -%\TrackLangQueryOtherEnv{LC_MONETARY} -%\TrackLangFromEnv -%\end{verbatim} -%Remember that if you only want to do the shell escape if -%\cs{TrackLangEnv} hasn't already been defined, you can test for this -%first: -%\begin{verbatim} -%\ifx\TrackLangEnv\undefined -% \TrackLangQueryOtherEnv{LC_MONETARY} -%\fi -%\TrackLangFromEnv -%\end{verbatim} -% -%It's also possible to just parse the value of \cs{TrackLangEnv} -%without tracking the result using: -%\begin{definition}[\DescribeMacro\TrackLangParseFromEnv] -%\cs{TrackLangParseFromEnv} -%\end{definition} -%This is like \cs{TrackLangFromEnv} but assumes that -%\cs{TrackLangEnv} has already been set and doesn't track the -%result. The component parts are stored as for \cs{TrackLangFromEnv}. -% -%Example (Plain \TeX): -%\begin{verbatim} -%\input tracklang -% -%\def\TrackLangEnv{fr-BE.utf8@euro} -% -%\TrackLangParseFromEnv -% -%Language: \TrackLangEnvLang. -%Territory: \TrackLangEnvTerritory. -%Codeset: \TrackLangEnvCodeSet. -%Modifier: \TrackLangEnvModifier. -%Any tracked languages? \AnyTrackedLanguages{Yes}{No}. -% -%\end{verbatim} -%This produces: -% -%\medskip -% -%Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. -%Any tracked languages? No. -% -%\medskip -% -%Compare this with: -%\begin{verbatim} -%\input tracklang -% -%\def\TrackLangEnv{fr-BE.utf8@euro} -% -%\TrackLangFromEnv -% -%Language: \TrackLangEnvLang. -%Territory: \TrackLangEnvTerritory. -%Codeset: \TrackLangEnvCodeSet. -%Modifier: \TrackLangEnvModifier. -%Any tracked languages? \AnyTrackedLanguages{Yes}{No}. -%Tracked dialect(s):% -%\ForEachTrackedDialect{\thisdialect}{\space\thisdialect}. -%\end{verbatim} -%This produces: -% -%\medskip -% -%Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. -%Any tracked languages? Yes. -%Tracked dialect(s): belgique. -% -%\medskip -% -%If \cs{TrackLangFromEnv} doesn't recognise the given language and -%territory combination, it will define a new dialect and add that. -% -%For example, \styfmt{tracklang} doesn't recognise \texttt{en-BE}, so -%the sample document below defines a new dialect labelled -%\texttt{enBEeuro}: -%\begin{verbatim} -%\input tracklang -% -%\def\TrackLangEnv{en-BE.utf8@euro} -% -%\TrackLangFromEnv -% -%Language: \TrackLangEnvLang. -%Territory: \TrackLangEnvTerritory. -%Codeset: \TrackLangEnvCodeSet. -%Modifier: \TrackLangEnvModifier. -%Any tracked languages? \AnyTrackedLanguages{Yes}{No}. -%Tracked dialect(s):% -%\ForEachTrackedDialect{\thisdialect}{\space\thisdialect}. -%\end{verbatim} -%This now produces: -%\medskip -% -%Language: en. Territory: BE. Codeset: utf8. Modifier: euro. -%Any tracked languages? Yes. -%Tracked dialect(s): enBEeuro. -% -%\chapter{Detecting the User's Requested Languages} -%\label{sec:user} -% -%The \styfmt{tracklang} package tries to track the loaded languages and -%the option names used to identify those languages. For want of a better -%term, the language option names are referred to as dialects even if -%they're only a synonym for the language rather than an actual -%dialect. For example, if the user -%has requested \texttt{british}, the \emph{root language} label is -%\texttt{english} and the dialect is \texttt{british}, whereas if the -%user requested \texttt{UKenglish}, the root language label is -%\texttt{english} and the dialect is \texttt{UKenglish}. The -%exceptions to this are the \styfmt{tracklang} package options that have been -%specified in the form \meta{iso lang}-\meta{iso country} (listed -%in \tableref{tab:rootlangopts}). For -%example, the package option \texttt{en-GB} behaves as though the -%user requested the package option \texttt{british}. -% -%If \cs{TrackLocale} or \cs{TrackLangFromEnv} are used and the locale -%isn't recognised a new dialect is created with the label formed from -%the ISO codes (and modifier, if present). -%Similarly for \cs{TrackLanguageTag} a new -%dialect is created with a label that's essentially the language tag -%without the hyphen separators. For example, -%\begin{verbatim} -%\TrackLocale{xx-YY} -%\end{verbatim} -%will add a new dialect with the label \texttt{xxYY}, -%\begin{verbatim} -%\TrackLocale{xx-YY@mod} -%\end{verbatim} -%will add a new dialect with the label \texttt{xxYYmod} and -%\begin{verbatim} -%\TrackLanguageTag{xx-Latn-YY} -%\end{verbatim} -%will add a new dialect with the label \texttt{xxLatnYY}. -% -%\begin{important} -%If \cs{TrackLocale} or \cs{TrackLangFromEnv} find a modifier, the -%value will be sanitized to allow it to be used as a label. If the -%modifier is set explicitly using \cs{SetTrackedDialectModifier}, -%no sanitization is performed. -%\end{important} -% -%In addition to the root language label and the dialect identifier, -%many of the language options also have corresponding ISO codes. In -%most cases there is an ISO~639-1 or an ISO~639-2 code (or both), and in some -%cases there is an ISO~3166-1 code identifying the dialect region. -%Where a language has both a \qt{T} and a \qt{B} ISO~639-2 -%code, the \qt{T} version is assumed. -% -%When the \styfmt{tracklang} \LaTeX\ package is loaded, it first attempts to find the -%language options through the package options supplied to -%\styfmt{tracklang}. This means that any languages that have been -%supplied in the document class options should get identified -%(provided that the document class has used the standard option -%declaration mechanism). If no languages have been supplied in this -%way, \styfmt{tracklang} then attempts to identify any \sty{babel} -%language options and failing that it will try the \sty{translator} -%language options. It will then check if \sty{ngerman} or -%\sty{polyglossia} have been loaded. -% -%Each identified language and dialect is added to the \emph{tracked -%language} and \emph{tracked dialect} lists. Note that the tracked -%language and tracked dialect are labels rather than proper nouns. -%If a~dialect label is identical to its root language label, the -%label will appear in both lists. -% -%You can check whether or not any languages have been detected using: -%\begin{definition}[\DescribeMacro\AnyTrackedLanguages] -%\cs{AnyTrackedLanguages}\marg{true part}\marg{false part} -%\end{definition} -%This will do \meta{true part} if one or more languages have been -%detected otherwise it will do \meta{false part}. (Each detected -%dialect will automatically have the root language label added -%to the tracked language list, if it's not already present.) -% -%If you want to find out if any of the tracked dialects -%matches a particular language tag, you can use: -%\begin{definition}[\DescribeMacro\GetTrackedDialectFromLanguageTag] -%\ics{GetTrackedDialectFromLanguageTag}\marg{tag}\marg{cs} -%\end{definition} -%If successful, the supplied control sequence \meta{cs} is set to the -%dialect label, otherwise \meta{cs} is set to empty. The test is for an exact -%match on the root language, script, sub-language, variant and -%region. The control sequence \meta{cs} will be empty if none of the -%tracked dialects matches all five of those elements. (If the script -%isn't given explicitly, the default for that language is assumed.) -%In the event that \meta{cs} is empty, you can now (as from v1.3.6) -%get the closest match with -%\begin{definition}[\DescribeMacro\TrackedDialectClosestSubMatch] -%\ics{TrackedDialectClosestSubMatch} -%\end{definition} -%(which is set by \cs{GetTrackedDialectFromLanguageTag}). -%This will be empty if no tracked dialects match on the root -%language or if there's a tracked dialect label that exactly matches -%the label formed by concatenating the language code, sub-language, -%script, region, modifier and variant. -% -%For example (Plain \TeX): -%\begin{verbatim} -%\input tracklang -%\TrackLanguageTag{en-826} -%Has en-Latn-GB been tracked? -%\GetTrackedDialectFromLanguageTag{en-Latn-GB}{\thisdialect}% -%\ifx\thisdialect\empty -% No! -%\else -% Yes! Dialect label: \thisdialect. -%\fi -%\bye -%\end{verbatim} -%This matches because the territory code 826 is recognised as -%equivalent to the code GB, and the default script for -%\texttt{english} is \texttt{Latn}. In this case, the dialect -%label is \texttt{british}. Note that this doesn't require -%the use of \cs{TrackLanguageTag} to track the dialect. -%It also works if the dialect has been tracked using other commands, -%such as \cs{TrackLocale}. -% -%Here's an example that doesn't have an exact match, but does have a -%partial match: -%\begin{verbatim} -%\input tracklang -%\TrackLanguageTag{de-CH-1996} -%Has de-DE-1996 been tracked? -%\GetTrackedDialectFromLanguageTag{de-DE-1996}{\thisdialect}% -%\ifx\thisdialect\empty -% No! -% \ifx\TrackedDialectClosestSubMatch\empty -% No match on root language. -% \else -% Closest match: \TrackedDialectClosestSubMatch. -% \fi -%\else -% Yes! Dialect label: \thisdialect. -%\fi -%\bye -%\end{verbatim} -%In this case the result is: -%\begin{quote} -%Has de-DE-1996 been tracked? No! Closest match: nswissgerman. -%\end{quote} -% -%You can iterate through each tracked dialect using: -%\begin{definition}[\DescribeMacro\ForEachTrackedDialect] -%\cs{ForEachTrackedDialect}\marg{cs}\marg{code} -%\end{definition} -%At the start of each iteration, this sets the control sequence -%\meta{cs} to the tracked dialect and does \meta{code}. -% -%You can iterate through each tracked language using: -%\begin{definition}[\DescribeMacro\ForEachTrackedLanguage] -%\cs{ForEachTrackedLanguage}\marg{cs}\marg{code} -%\end{definition} -%At the start of each iteration, this sets the control sequence \meta{cs} to the -%tracked language and does \meta{code}. -% -%The above for-loops use the same internal mechanism as \LaTeX's -%\cs{@for} loop. The provided control sequence \meta{cs} is updated at the -%start of each iteration to the current element. The loop is -%terminated when this control sequence is set to \cs{@nil}. This -%special control sequence should never been used as it's just a -%marker and isn't actually defined. If you get an error message -%stating that \cs{@nil} is undefined, then it's most likely due to a -%loop control sequence being used outside the loop. This can occur if -%the loop contains code that isn't expanded until later. For example, -%if the loop code includes \cs{AtBeginDocument}, you need to ensure -%that the loop control sequence is expanded before being added to the -%hook. -% -%You can test if a root language has been detected using: -%\begin{definition}[\DescribeMacro\IfTrackedLanguage] -%\cs{IfTrackedLanguage}\marg{label}\marg{true part}\marg{false part} -%\end{definition} -%where \meta{label} is the language label. If -%true, this does \meta{true part} otherwise it does \meta{false -%part}. -% -%You can test if a particular dialect has been detected using: -%\begin{definition}[\DescribeMacro\IfTrackedDialect] -%\cs{IfTrackedDialect}\marg{label}\marg{true part}\marg{false part} -%\end{definition} -%where \meta{label} is the dialect label. If the root language was explicitly specified, then it will -%also be detected as a dialect. -% -%For example: -%\begin{verbatim} -%\documentclass[british,dutch]{article} -% -%\usepackage{tracklang} -% -%\begin{document} -%``english'' \IfTrackedDialect{english}{has}{hasn't} been specified. -% -%``british'' \IfTrackedDialect{british}{has}{hasn't} been specified. -% -%``flemish'' \IfTrackedDialect{flemish}{has}{hasn't} been specified. -% -%``dutch'' \IfTrackedDialect{dutch}{has}{hasn't} been specified. -% -%``english'' or an English variant -%\IfTrackedLanguage{english}{has}{hasn't} been specified. -% -%\end{document} -%\end{verbatim} -%This produces: -%\begin{quote} -%``english'' hasn't been specified. -% -%``british'' has been specified. -% -%``flemish'' hasn't been specified. -% -%``dutch'' has been specified. -% -%``english'' or an English variant has been specified. -%\end{quote} -% -%You can find the root language label for a given tracked dialect -%using: -%\begin{definition}[\DescribeMacro\TrackedLanguageFromDialect] -%\cs{TrackedLanguageFromDialect}\marg{dialect} -%\end{definition} -%If \meta{dialect} hasn't been defined this does nothing otherwise it -%expands to the root language label. -% -%You can find the tracked dialects from a given root language -%using: -%\begin{definition}[\DescribeMacro\TrackedDialectsFromLanguage] -%\cs{TrackedDialectsFromLanguage}\marg{root language label} -%\end{definition} -%This will expand to a~comma-separated list of dialect labels -%if the root language label has been defined, otherwise it -%does nothing. -% -% -%You can test if a language or dialect has a corresponding ISO code using: -%\begin{definition}[\DescribeMacro\IfTrackedLanguageHasIsoCode] -%\cs{IfTrackedLanguageHasIsoCode}\marg{code -%type}\marg{label}\marg{true part}\marg{false part} -%\end{definition} -%where \meta{code type} is the type of ISO code (for example, -%\texttt{639-1} for root languages or \texttt{3166-1} for regional -%dialects), and \meta{label} is the language or dialect label. -%Note that the \texttt{639-3} may be set for the dialect -%rather than root language for sub-languages parsed using -%\ics{TrackLanguageTag}. -% -%Alternatively, you can test if a particular ISO code has been -%defined using: -%\begin{definition}[\DescribeMacro\IfTrackedIsoCode] -%\cs{IfTrackedIsoCode}\marg{code type}\marg{code}\marg{true -%part}\marg{false part} -%\end{definition} -%where \meta{code type} is again the type of ISO code (for example, -%\texttt{639-1} or \texttt{3166-1}), and \meta{code} is the -%particular code (for example, \texttt{en} for ISO 639-1 or -%\texttt{GB} for ISO 3166-1). -% -%You can fetch the language (or dialect) label associated with a -%given ISO code using: -%\begin{definition}[\DescribeMacro\TrackedLanguageFromIsoCode] -%\cs{TrackedLanguageFromIsoCode}\marg{code type}\marg{code} -%\end{definition} -%This does nothing if the given \meta{code} for the given ISO -%\meta{code type} has not been defined, otherwise it expands -%a~comma-separated list of language or dialect labels. -% -%You can fetch the ISO code for a given code type using: -%\begin{definition}[\DescribeMacro\TrackedIsoCodeFromLanguage] -%\cs{TrackedIsoCodeFromLanguage}\marg{code type}\marg{label} -%\end{definition} -%where \meta{label} is the language or dialect label and \meta{code -%type} is the ISO code type (for example, \texttt{639-1} or -%\texttt{3166-1}). Unlike \ics{TrackedLanguageFromIsoCode}, this -%command only expands to a single label rather than a~comma-separated -%list. -% -%The above commands do nothing in the event of an unknown code or -%code type, -%so if you accidentally get the wrong code type, you won't get an error. -%If you're unsure of the code type, you can use the following commands: -%\begin{definition}[\DescribeMacro\TwoLetterIsoCountryCode] -%\cs{TwoLetterIsoCountryCode} -%\end{definition} -%This expands to 3166-1 and is used for the two-letter country codes. -% -%\begin{definition}[\DescribeMacro\TwoLetterIsoLanguageCode] -%\cs{TwoLetterIsoLanguageCode} -%\end{definition} -%This expands to 639-1 and is used for the two-letter root language codes. -% -%\begin{definition}[\DescribeMacro\ThreeLetterIsoLanguageCode] -%\cs{ThreeLetterIsoLanguageCode} -%\end{definition} -%This expands to 639-2 and is used for the three-letter root language -%codes. -% -%\begin{definition}[\DescribeMacro\ThreeLetterExtIsoLanguageCode] -%\cs{ThreeLetterExtIsoLanguageCode} -%\end{definition} -%(New to v1.3.) This expands to 639-3. This code is only used for a root language if -%there's no 639-1 or 639-2 code. It may also be used for a -%dialect if a sub-language part has been set in the language -%tag parsed by \cs{TrackLanguageTag}. -% -%The \cs{Get\ldots} commands below are designed to be expandable. -%If the supplied \meta{dialect} is unrecognised they expand to empty. -%Remember that the dialect must first be identified as a tracked -%language for it to be recognised. -% -%As from v1.3, the language tag for a given dialect can be obtained -%using: -%\begin{definition}[\DescribeMacro\GetTrackedLanguageTag] -%\cs{GetTrackedLanguageTag}\marg{dialect} -%\end{definition} -%where \meta{dialect} is the label identifying the dialect. -%Uses the \texttt{und} (undetermined) code for unknown languages. -% -%As from v1.3, each tracked dialect may also have an associated -%modifier, which can be fetched using: -%\begin{definition}[\DescribeMacro\GetTrackedDialectModifier] -%\cs{GetTrackedDialectModifier}\marg{dialect} -%\end{definition} -%where \meta{dialect} is the label identifying the dialect. -%This value is typically obtained by parsing a POSIX locale identifier -%with \cs{TrackLocale} or \cs{TrackLangFromEnv} but may be set explicitly. -%(See \sectionref{sec:langsty} for setting this value. Likewise for -%the following commands.) -% -%You can test if a dialect has an associated modifier using: -%\begin{definition}[\DescribeMacro\IfHasTrackedDialectModifier] -%\cs{IfHasTrackedDialectModifier}\marg{dialect}\marg{true}\marg{false} -%\end{definition} -%If the dialect has an associated modifier this does \meta{true} -%otherwise it does \meta{false}. -% -%For example: -%\begin{verbatim} -%\documentclass[british,francais,american,canadian,canadien,dutch]{article} -% -%\usepackage{tracklang} -% -%\begin{document} -% -%Languages: \ForEachTrackedLanguage{\ThisLanguage}{\ThisLanguage\space -%(ISO \TwoLetterIsoLanguageCode: -%``\TrackedIsoCodeFromLanguage{\TwoLetterIsoLanguageCode}{\ThisLanguage}''). } -% -%Dialects: \ForEachTrackedDialect{\ThisDialect}{\ThisDialect\space -%(\IfTrackedLanguageHasIsoCode{\TwoLetterIsoCountryCode}{\ThisDialect}% -% {ISO \TwoLetterIsoCountryCode: -% ``\TrackedIsoCodeFromLanguage{\TwoLetterIsoCountryCode}{\ThisDialect}''}% -% {no specific region}; -%root: \TrackedLanguageFromDialect{\ThisDialect}). } -% -%Language for ISO \TwoLetterIsoCountryCode\ ``GB'': -%\TrackedLanguageFromIsoCode{\TwoLetterIsoCountryCode}{GB}. -% -%Language for ISO \TwoLetterIsoCountryCode\ ``CA'': -%\TrackedLanguageFromIsoCode{\TwoLetterIsoCountryCode}{CA}. -% -%Country ISO \TwoLetterIsoCountryCode\ code for ``canadian'': -%\TrackedIsoCodeFromLanguage{\TwoLetterIsoCountryCode}{canadian}. -% -%\end{document} -%\end{verbatim} -%This produces: -%\begin{quote} -%Languages: english (ISO 639-1: ``en''). french (ISO 639-1: ``fr''). -%dutch (ISO 639-1: ``nl''). -% -%Dialects: american (ISO 3166-1: ``US''; root: english). -%british (ISO 3166-1: ``GB''; root: english). -%canadian (ISO 3166-1: ``CA''; root: english). -%canadien (ISO 3166-1: ``CA''; root: french). -%dutch (no specific region; root: dutch). -%francais (no specific region; root: french). -% -%Language for ISO 3166-1 ``GB'': british. -% -%Language for ISO 3166-1 ``CA'': canadian,canadien. -% -%Country ISO 3166-1 code for ``canadian'': CA. -% -%\end{quote} -% -%As from v1.3, each tracked dialect may also have an associated -%variant, which can be fetched using: -%\begin{definition}[\DescribeMacro\GetTrackedDialectVariant] -%\cs{GetTrackedDialectVariant}\marg{dialect} -%\end{definition} -%where \meta{dialect} is the label identifying the dialect. -%This value is typically obtained by parsing a language tag -%with \cs{TrackLanguageTag} but may be set explicitly. -% -%You can test if a dialect has an associated variant using: -%\begin{definition}[\DescribeMacro\IfHasTrackedDialectVariant] -%\cs{IfHasTrackedDialectVariant}\marg{dialect}\marg{true}\marg{false} -%\end{definition} -% -%As from v1.3, each tracked dialect may also have an associated -%script, which can be fetched using: -%\begin{definition}[\DescribeMacro\GetTrackedDialectScript] -%\cs{GetTrackedDialectScript}\marg{dialect} -%\end{definition} -%where \meta{dialect} is the label identifying the dialect. -% -%You can test if a dialect has an associated script using: -%\begin{definition}[\DescribeMacro\IfHasTrackedDialectScript] -%\cs{IfHasTrackedDialectScript}\marg{dialect}\marg{true}\marg{false} -%\end{definition} -%If the dialect has an associated script this does \meta{true} -%otherwise it does \meta{false}. This information is provided -%for language packages that need to know what script is required, -%but there's no guarantee that the script will actually be set -%in the document. Similarly for all the other attributes described -%here. -% -%Note that the script should be a recognised four-letter ISO 15924 -%code, such as \texttt{Latn} or \texttt{Cyrl}. If a~dialect -%doesn't have an associated script then the default for the root -%language should be assumed. For example, \qt{Latn} for English dialects or -%\qt{Cyrl} for Russian dialects. (The default script for -%known languages can be obtained using -%\cs{TrackLangGetDefaultScript}, see -%\sectionref{sec:code:knownlangs} for further details. -%Most root languages have a default script, but there -%are a few without one as it may depend on region, politics -%or ideology.) -% -%There's a convenient expandable command for testing the script: -%\begin{definition} -%\cs{IfTrackedDialectIsScriptCs}\marg{dialect}\marg{cs}\marg{true}\marg{false} -%\end{definition} -%This tests if the given tracked dialect has an associated script and -%compares the value with the replacement text of \meta{cs}. -%If the dialect hasn't been explicitly assigned a script, -%then test is performed against the default script for the root -%language. -% -%The supplementary package \sty{tracklang-scripts} provides some -%additional commands relating to writing systems, including commands -%in the form \ics{TrackLangScript\meta{code}} where -%\meta{code} is the ISO 15924 four-letter code. If the dialect -%doesn't have an associated script, \meta{false} is done. -%This package isn't -%loaded automatically, so you'll need to explicitly load it. The -%generic code is in \texttt{tracklang-scripts.tex}: -%\begin{verbatim} -%\input tracklang-scripts -%\end{verbatim} -%There's a convenient \LaTeX\ wrapper \texttt{tracklang-scripts.sty}: -%\begin{verbatim} -%\usepackage{tracklang-scripts} -%\end{verbatim} -%See \sectionref{sec:tracklang-scripts.tex} for further details of -%that package. -% -%For example, the following defines a command to check if -%the given dialect should use a Latin script: -%\begin{verbatim} -%\input tracklang-scripts -%\def\islatin#1#2#3{% -% \IfTrackedDialectIsScriptCs{#1}{\TrackLangScriptLatn}{#2}{#3}% -%} -%\end{verbatim} -% -%\begin{important} -%Note that the script value doesn't mean that the document is -%actually using that script. It means that this is the user's -%\emph{desired} script, but whether that script is actually set relies -%on the appropriate settings in the relevant language package (such -%as \sty{polyglossia}'s \texttt{script} key). -%\end{important} -% -%As from v1.3, each tracked dialect may also have a sub-language -%identifier (for example, \texttt{arevela}), which can be fetched -%using: -%\begin{definition}[\DescribeMacro\GetTrackedDialectSubLang] -%\cs{GetTrackedDialectSubLang}\marg{dialect} -%\end{definition} -%where \meta{dialect} is the label identifying the dialect. -% -%You can test if a dialect has an associated sub-tag using: -%\begin{definition}[\DescribeMacro\IfHasTrackedDialectSubLang] -%\cs{IfHasTrackedDialectSubLang}\marg{dialect}\marg{true}\marg{false} -%\end{definition} -%If the dialect has an associated sub-tag this does \meta{true} -%otherwise it does \meta{false}. -% -%As from v1.3, each tracked dialect may also have additional -%information, which can be fetched using: -%\begin{definition}[\DescribeMacro\GetTrackedDialectAdditional] -%\cs{GetTrackedDialectAdditional}\marg{dialect} -%\end{definition} -%where \meta{dialect} is the label identifying the dialect. -% -%You can test if a dialect has additional information using: -%\begin{definition}[\DescribeMacro\IfHasTrackedDialectAdditional] -%\cs{IfHasTrackedDialectAdditional}\marg{dialect}\marg{true}\marg{false} -%\end{definition} -%If the dialect has additional information this does \meta{true} -%otherwise it does \meta{false}. -% -% -%Most packages that implement multilingual support have a~set of -%language definition files for each supported language or dialect. -%It may be that only the root language is needed, if there are no -%variations between that language's dialect (for the purposes of that -%package), or it may be that separate definition files are required -%for each dialect. However it can be awkward trying to map the -%requested dialect or language label to the file name. Should, say, -%the file containing the French code be called -%\meta{prefix}\texttt{-french-}\meta{suffix} or -%\meta{prefix}\texttt{-frenchb-}\meta{suffix} or -%\meta{prefix}\texttt{-francais-}\meta{suffix}? -%Should, say, the file containing the British English code be called -%\meta{prefix}\texttt{-british-}\meta{suffix} or -%\meta{prefix}\texttt{-UKenglish-}\meta{suffix}? -%If you want to modularise the language support for your package so -%that each language module has a different maintainer will the -%maintainers know what tag to use for their language? -% -%\label{pg:filesearch}To help with this, \styfmt{tracklang} provides: -%\begin{definition} -%\ics{IfTrackedLanguageFileExists}\marg{dialect}\marg{prefix}\marg{suffix}\marg{true part}\marg{false part} -%\end{definition} -%This attempts to find the file called -%\meta{prefix}\meta{localeid}\meta{suffix} where \meta{localeid} is determined -%from \meta{dialect} (see below). If the file is found -%\begin{definition} -%\ics{CurrentTrackedTag} -%\end{definition} -%is set to \meta{localeid} and \meta{true part} is done, otherwise -%\meta{false part} is done. If this command -%is empty, then the dialect hasn't been detected. If the dialect -%has been detected, but no file can be found, then -%\ics{CurrentTrackedTag} is set to the final attempt at determining -%\meta{localeid}. -% -%There's a convenient shortcut command new to version 1.3: -%\begin{definition}[\DescribeMacro\TrackLangRequireDialect] -%\cs{TrackLangRequireDialect}\oarg{load code}\marg{pkgname}\marg{dialect} -%\end{definition} -%which uses \cs{IfTrackedLanguageFileExists} to input the resource -%file if found. The prefix is given by \meta{pkgname}\texttt{-} and -%the suffix is \texttt{.ldf}. A warning is issued if no resource file -%is found. Note that while it makes sense for \meta{pkgname} -%to be the same as the base name of the package that uses these -%resource files, they don't have to be the same. This command -%additionally defines -%\begin{definition}[\DescribeMacro\TrackLangRequireDialectPrefix] -%\cs{TrackLangRequireDialectPrefix} -%\end{definition} -%to \meta{pkgname}, which allows the prefix to be picked up by -%resource file commands, such as \cs{TrackLangProvidesResource} -%and \cs{TrackLangRequireResource}. (See below.) -% -%The optional argument \meta{load code} is the code that actually -%inputs the required file. This defaults to -%\begin{verbatim} -%\TrackLangRequireResource{\CurrentTrackedTag} -%\end{verbatim} -% -% -%The \ics{IfTrackedLanguageFileExists} command sets up the current -%tracked dialect with -%\ics{SetCurrentTrackedDialect}\marg{dialect}, which enables the following -%commands that may be used within \meta{true part} or \meta{false -%part}: -%\begin{definition} -%\ics{CurrentTrackedDialect} -%\end{definition} -%The dialect label. -% -%\begin{definition} -%\ics{CurrentTrackedLanguage} -%\end{definition} -%If the dialect hasn't been detected, this command will be empty, -%otherwise it will expand to the root language label (which may -%be the same as the dialect label). -% -%\begin{definition} -%\ics{CurrentTrackedRegion} -%\end{definition} -%If the dialect hasn't been detected, this command will be empty. -%If the dialect has been assigned an ISO~3166-1 code, -%\ics{CurrentTrackedRegion} will expand to that code, otherwise it -%will be empty. -% -%\begin{definition} -%\ics{CurrentTrackedIsoCode} -%\end{definition} -%If the dialect hasn't been detected, this command will be empty. -%Otherwise it may be empty or it may expand to the -%ISO~639-1 or ISO~639-2 or ISO~639-3 code. -% -%\begin{definition} -%\ics{CurrentTrackedDialectModifier} -%\end{definition} -%The dialect's modifier or empty if not set. (This is set but not -%used in the set of possible \meta{localeid} values.) -% -%\begin{definition} -%\ics{CurrentTrackedDialectVariant} -%\end{definition} -%The dialect's variant or empty if not set. -% -%\begin{definition} -%\ics{CurrentTrackedDialectSubTag} -%\end{definition} -%The dialect's sub-language code or empty if not set. -% -%\begin{definition} -%\ics{CurrentTrackedDialectAdditional} -%\end{definition} -%The dialect's additional information or empty if not set. -% -%\begin{definition} -%\ics{CurrentTrackedLanguageTag} -%\end{definition} -%The dialect's language tag. Take care not to confuse this -%with \cs{CurrentTrackedTag}. -% -%\begin{definition} -%\ics{CurrentTrackedDialectScript} -%\end{definition} -%The dialect's script. If the dialect doesn't have the script set, -%the default script for the language is used instead. -% -%\cs{IfTrackedLanguageFileExists} behaves as follows: -%\begin{itemize} -% \item If no dialect with the given label has been -% detected, the condition evaluates to \emph{false} and -% \ics{CurrentTrackedTag} is empty. -% \item If a dialect with the given label has been detected, then: -% \begin{itemize} -% \item For each possible \meta{localeid} in an ordered set of tags determined by -% the dialect label (see below), the first file matching -% \meta{prefix}\meta{localeid}\meta{suffix} that's found on -% \TeX's path results in the condition evaluating to \emph{true} and -% \ics{CurrentTrackedTag} is set to the current \meta{localeid} in the -% set. The rest of the set of possible values of \meta{localeid} is skipped. -% \item If no file matching \meta{prefix}\meta{localeid}\meta{suffix} is -% found on \TeX's path, then the condition evaluates to \emph{false} -% and \ics{CurrentTrackedTag} is set to the final \meta{localeid} in the -% set (the language label). -% \end{itemize} -%\end{itemize} -% -%The ordered set of possible values of \meta{localeid} is determined from -%the given dialect. -%\begin{important} -%The ordering has changed in version 1.4, which now also includes the -%script and variant. This new ordering should typically make the more -%common combinations closer to the start of the search. -%\end{important} -%The possible values of \meta{localeid} are listed below in the order of priority used -%by \cs{IfTrackedLanguageFileExists}. Note that the set may contain -%repetitions (for example, if the dialect label is the same as the -%root language label). If an item contains an element that hasn't -%been set (such as the ISO~639-3 code or a sub-language \meta{sublang} or variant) then -%that item is skipped. -%\begin{enumerate} -%\item \meta{localeid} is just the value of \ics{CurrentTrackedLanguageTag}. -%\item \meta{localeid} is just the dialect label. -% -%\item \meta{localeid} is -%\meta{ISO~639-1}\texttt{-}\meta{sublang}\texttt{-}\meta{script}\texttt{-}\meta{region}. -%\item \meta{localeid} is -%\meta{ISO~639-1}\texttt{-}\meta{script}\texttt{-}\meta{region}. -%\item \meta{localeid} is -%\meta{ISO~639-1}\texttt{-}\meta{sublang}\texttt{-}\meta{region} (if there's no script or if -%the script is the default for the given language). -%\meta{ISO~639-1}\texttt{-}\meta{region} (if there's no script or if -%the script is the default for the given language). -%\item \meta{localeid} is -%\meta{ISO~639-1}\texttt{-}\meta{sublang}\texttt{-}\meta{script}. -%\item \meta{localeid} is -%\meta{ISO~639-1}\texttt{-}\meta{script}. -%\item \meta{localeid} is \meta{ISO~639-1}\texttt{-}\meta{sublang}. -%\item \meta{localeid} is just \meta{ISO~639-1}. -% -%\item \meta{localeid} is -%\meta{ISO~639-2}\texttt{-}\meta{sublang}\texttt{-}\meta{script}\texttt{-}\meta{region}. -%\item \meta{localeid} is -%\meta{ISO~639-2}\texttt{-}\meta{script}\texttt{-}\meta{region}. -%\item \meta{localeid} is -%\meta{ISO~639-2}\texttt{-}\meta{sublang}\texttt{-}\meta{region} (if there's no script or if -%the script is the default for the given language). -%\meta{ISO~639-2}\texttt{-}\meta{region} (if there's no script or if -%the script is the default for the given language). -%\item \meta{localeid} is -%\meta{ISO~639-2}\texttt{-}\meta{sublang}\texttt{-}\meta{script}. -%\item \meta{localeid} is -%\meta{ISO~639-2}\texttt{-}\meta{script}. -%\item \meta{localeid} is \meta{ISO~639-2}\texttt{-}\meta{sublang}. -%\item \meta{localeid} is just \meta{ISO~639-2}. -% -%\item \meta{localeid} is -%\meta{ISO~639-3}\texttt{-}\meta{sublang}\texttt{-}\meta{script}\texttt{-}\meta{region}. -%\item \meta{localeid} is -%\meta{ISO~639-3}\texttt{-}\meta{script}\texttt{-}\meta{region}. -%\item \meta{localeid} is -%\meta{ISO~639-3}\texttt{-}\meta{sublang}\texttt{-}\meta{region} (if there's no script or if -%the script is the default for the given language). -%\meta{ISO~639-3}\texttt{-}\meta{region} (if there's no script or if -%the script is the default for the given language). -%\item \meta{localeid} is -%\meta{ISO~639-3}\texttt{-}\meta{sublang}\texttt{-}\meta{script}. -%\item \meta{localeid} is -%\meta{ISO~639-3}\texttt{-}\meta{script}. -%\item \meta{localeid} is \meta{ISO~639-3}\texttt{-}\meta{sublang}. -%\item \meta{localeid} is just \meta{ISO~639-3}. -% -%\item \meta{localeid} is just \meta{region}. -% -%\item \meta{localeid} is -%\meta{ISO~639-1}\texttt{-}\meta{sublang}\texttt{-}\meta{variant} -%or \meta{ISO~639-1}\texttt{-}\meta{variant} if \meta{sublang} is missing. -% -%\item \meta{localeid} is -%\meta{ISO~639-2}\texttt{-}\meta{sublang}\texttt{-}\meta{variant} -%or \meta{ISO~639-2}\texttt{-}\meta{variant} if \meta{sublang} is missing. -% -%\item \meta{localeid} is -%\meta{ISO~639-3}\texttt{-}\meta{sublang}\texttt{-}\meta{variant} -%or \meta{ISO~639-3}\texttt{-}\meta{variant} if \meta{sublang} is missing. -% -%\item \meta{localeid} is just the value of \ics{CurrentTrackedLanguage} -%(the root language label). -%\end{enumerate} -% -%For example (pre v1.3): -%\begin{verbatim} -%\AnyTrackedLanguages -%{% -% \ForEachTrackedDialect{\ThisDialect}% -% {% try to load the language file for this dialect -% \IfTrackedLanguageFileExists{\ThisDialect}% -% {mypackage-}% file prefix -% {.ldf}% file suffix -% {\input mypackage-\CurrentTrackedTag.ldf}% file found -% {% file not found -% \PackageWarning{mypackage}{No support for language -% `\ThisDialect'}% -% }% -% }% -%} -%{% no languages detected so use defaults -%} -%\end{verbatim} -%With version 1.3 onwards, this can be written more concisely as: -%\begin{verbatim} -%\AnyTrackedLanguages -%{% -% \ForEachTrackedDialect{\ThisDialect}% -% {% try to load the language file for this dialect -% \TrackLangRequireDialect{mypackage}{\ThisDialect}% -% }% -%} -%{% no languages detected so use defaults -%} -%\end{verbatim} -%which additionally enables the \styfmt{tracklang} version 1.3 commands described below, -%such as \cs{TrackLangRequireResource}. -% -%If, for example, \ics{ThisDialect} is \texttt{british}, then the file search will -%be in the order: -%\begin{enumerate} -%\item \texttt{mypackage-en-GB.ldf} (language tag) -%\item \texttt{mypackage-british.ldf} (dialect label) -% -%\item \texttt{mypackage-en-Latn-GB.ldf} (639-1 language code, script, region) -%\item \texttt{mypackage-en-GB.ldf} (639-1 language code, region) -%\item \texttt{mypackage-en-Latn.ldf} (639-1 language code, script) -%\item \texttt{mypackage-en.ldf} (639-1 language code) -% -%\item \texttt{mypackage-eng-Latn-GB.ldf} (639-2 language code, script, region) -%\item \texttt{mypackage-eng-GB.ldf} (639-2 language code, region) -%\item \texttt{mypackage-eng-Latn.ldf} (639-2 language code, script) -%\item \texttt{mypackage-eng.ldf} (639-2 language code) -% -%\item \texttt{mypackage-GB.ldf} (region) -%\item \texttt{mypackage-english.ldf} (language label) -%\end{enumerate} -% -%If, for example, \ics{ThisDialect} is \texttt{naustrian}, then the file search will -%be in the order: -%\begin{enumerate} -%\item \texttt{mypackage-de-AT-1996.ldf} (language tag) -%\item \texttt{mypackage-naustrian.ldf} (dialect label) -% -%\item \texttt{mypackage-de-Latn-AT.ldf} (639-1 language code, script, region) -%\item \texttt{mypackage-de-AT.ldf} (639-1 language code, region) -%\item \texttt{mypackage-de-Latn.ldf} (639-1 language code, script) -%\item \texttt{mypackage-de.ldf} (639-1 language code) -% -%\item \texttt{mypackage-deu-Latn-AT.ldf} (639-2 language code, script, region) -%\item \texttt{mypackage-deu-AT.ldf} (639-2 language code, region) -%\item \texttt{mypackage-deu-Latn.ldf} (639-2 language code, script) -%\item \texttt{mypackage-deu.ldf} (639-2 language code) -% -%\item \texttt{mypackage-AT.ldf} (region) -% -%\item \texttt{mypackage-de-1996.ldf} (639-1 language code, variant) -%\item \texttt{mypackage-deu-1996.ldf} (639-2 language code, variant) -% -%\item \texttt{mypackage-german.ldf} (language label) -%\end{enumerate} -% -%If, for example, \ics{ThisDialect} is \texttt{francais}, then the file search will -%be in the order: -%\begin{enumerate} -%\item \texttt{mypackage-fr.ldf} (language tag) -%\item \texttt{mypackage-francais.ldf} (dialect label) -%\item \texttt{mypackage-fr-Latn.ldf} (639-1 language code, script) -%\item \texttt{mypackage-fr.ldf} (639-1 language code) -%\item \texttt{mypackage-fra-Latn.ldf} (639-2 language code, script) -%\item \texttt{mypackage-fra.ldf} (639-2 language code) -%\item \texttt{mypackage-french.ldf} (language) -%\end{enumerate} -%This is because the predefined \texttt{francais} option has no -%region assigned to it. Be careful if the dialect label is the actual -%root language. For example, if \cs{ThisDialect} is \texttt{french}, -%then the file search will be in the order: -%\begin{enumerate} -%\item \texttt{mypackage-fr.ldf} (language tag) -%\item \texttt{mypackage-french.ldf} (dialect label) -%\item \texttt{mypackage-fr-Latn.ldf} (639-1 language code, script) -%\item \texttt{mypackage-fr.ldf} (639-1 language code) -%\item \texttt{mypackage-fra-Latn.ldf} (639-2 language code, script) -%\item \texttt{mypackage-fra.ldf} (639-2 language code) -%\item \texttt{mypackage-french.ldf} (language) -%\end{enumerate} -%Note that the last try will always fail in this case since if the -%file exists, it will be found on the second try. -% -%If the dialect label is identical to the root language label then it -%means that all associated information is the default -%for that language. For example, in the above case of \texttt{french}, -%the script is \texttt{Latn} and the region is unspecified. The root -%language label can therefore be used as the fallback in the event of -%no other match but for the specific case where the dialect is -%identical to the root language then all unnecessary file name checks -%can be skipped. -% -%If you're only providing support for the root languages (pre v1.3): -%\begin{verbatim} -%\AnyTrackedLanguages -%{% -% \ForEachTrackedLanguage{\ThisLanguage}% -% {% try to load the language file for this root language -% \IfTrackedLanguageFileExists{\ThisLanguage}% -% {mypackage-}% file prefix -% {.ldf}% file suffix -% {\input mypackage-\CurrentTrackedTag.ldf}% file found -% {% file not found -% \PackageWarning{mypackage}{No support for language -% `\ThisLanguage'}% -% }% -% }% -%} -%{% no languages detected so use defaults -%} -%\end{verbatim} -%With version 1.3 onwards, this can be written more concisely as: -%\begin{verbatim} -%\AnyTrackedLanguages -%{% -% \ForEachTrackedLanguage{\ThisLanguage}% -% {% try to load the language file for this root language -% \TrackLangRequireDialect{mypackage}{\ThisLanguage}% -% }% -%} -%{% no languages detected so use defaults -%} -%\end{verbatim} -%which additionally enables the commands described below. -%Note that in this case, if more than one dialect for the same -%language has been tracked, only the hooks for the last dialect for -%that language will be adjusted, so it's usually best to iterate over -%the dialects. -% -%The following \cs{TrackLang\ldots Resource\ldots} commands may -%only be used in resource files that are loaded using -%\ics{TrackLangRequireDialect}. An error will occur if the file is -%input through some other method. -% -%Within the resource file -%\meta{pkgname}\texttt{-}\meta{localeid}\texttt{.ldf}, -%you can identify the file using (new to version 1.3): -%\begin{definition}[\DescribeMacro\TrackLangProvidesResource] -%\cs{TrackLangProvidesResource}\marg{tag}\oarg{version info} -%\end{definition} -% -%If \cs{ProvidesFile} is defined (through the \LaTeX\ kernel) this is -%used, otherwise a simplified generic alternative is used that's -%suitable for other \TeX\ formats. -% -%The resource file can load another resource file -%\meta{pkgname}\texttt{-}\meta{localeid2}\texttt{.ldf}, -%using (new to version 1.3): -%\begin{definition}[\DescribeMacro\TrackLangRequireResource] -%\cs{TrackLangRequireResource}\marg{localeid2} -%\end{definition} -%For example, the dialect file \texttt{foo-en-GB.ldf} might need to -%load the root language resource file \texttt{foo-english.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{en-GB} -%\TrackLangRequireResource{english} -%\end{verbatim} -%If \texttt{foo-english.ldf} is also identified with -%\cs{TrackLangProvidesResource}, this will ensure that it's only -%loaded once. -% -%If you require the resource file and want to perform -%\meta{code1} if it's loaded at this point or \meta{code2} if it's -%already been loaded then you can use (new to version 1.3): -%\begin{definition}[\DescribeMacro\TrackLangRequireResourceOrDo] -%\cs{TrackLangRequireResourceOrDo}\marg{localeid2}\marg{code1}\marg{code2} -%\end{definition} -% -%If you want to load a resource file if it exists (without an -%error if it doesn't exist), then you can use -%\begin{definition}[\DescribeMacro\TrackLangRequestResource] -%\cs{TrackLangRequestResource}\marg{localeid2}\marg{not found code} -%\end{definition} -%If the file doesn't exist, \meta{not found code} is done. -% -%\begin{important} -%Note that these \cs{\ldots}\texttt{Resource} commands are only -%permitted within the resource files. They are internally enabled -%through \cs{TrackLangRequireDialect}. -%\end{important} -% -%The above restriction on the resource files loaded through -%\cs{TrackLangRequireDialect}, and the fact that it internally uses -%\cs{IfTrackedLanguageFileExists}, means that commands like -%\cs{CurrentTrackedLanguage} or \cs{CurrentTrackedDialect} may be -%used in those files. This means that the name of the captions hook -%can be obtained through them. (Remember that the file -%\texttt{foo-en-GB.ldf} might have been loaded with, say, the -%\texttt{british} dialect or with the synonymous \texttt{UKenglish} -%dialect or with a dialect label that doesn't have a corresponding -%caption hook, such as \texttt{enGBLatn}.) -% -%The \sty{polyglossia} package has caption hooks in the form -%\cs{captions\meta{language}} whereas \sty{babel} has captions hooks -%in the form \cs{captions\meta{dialect}}. This leads to a rather -%cumbersome set of conditionals: -%\begin{verbatim} -%\ifcsundef{captions\CurrentTrackedLanguage} -%{% -% \ifcsundef{captions\CurrentTrackedDialect}% -% {}% -% {% -% \csgappto{captions\CurrentTrackedDialect}{% -% % code to append to hook -% }% -% }% -%}% -%{% -% \csgappto{captions\CurrentTrackedLanguage}{% -% % code to append to hook -% }% -%} -%% do code now to initialise -%\end{verbatim} -%Note that the above has been simplified through the use of -%\sty{etoolbox} commands, which isn't suitable for generic use. -%It also doesn't query the mapping from \styfmt{tracklang}'s dialect -%label to the closest matching \sty{babel} dialect label. -% -%Instead (new to version 1.3), \styfmt{tracklang} provides a command -%to perform this set of conditionals using generic code: -%\begin{definition}[\DescribeMacro\TrackLangAddToHook] -%\cs{TrackLangAddToHook}\marg{code}\marg{type} -%\end{definition} -%where \meta{code} is the code to append to the \meta{type} hook. -%This always performs \meta{code} after testing for the hook in case -%the hook is undefined or has already been called (for example, \sty{ngerman} uses -%\cs{captionsngerman} when the package is loaded, not at the start of -%the document). -% -%Note that this command is enabled through -%\cs{TrackLangRequireDialect} so should only be used inside resource -%files. -% -%Since \texttt{captions} is a commonly used hook type, there's -%a~shortcut command provided: -%\begin{definition}[\DescribeMacro\TrackLangAddToCaptions] -%\cs{TrackLangAddToCaptions}\marg{code} -%\end{definition} -%This is equivalent to -%\cs{TrackLangAddToHook}\marg{code}\verb|{captions}|. -% -%There may be some hooks, such as \cs{date}\meta{label}, that need -%redefining rather than appending to. As from v1.4, there's an -%analogous command: -%\begin{definition}[\DescribeMacro\TrackLangRedefHook] -%\cs{TrackLangRedefHook}\marg{code}\marg{type} -%\end{definition} -%which will redefined the hook to do \meta{code}. -% -%Note that no expansion is performed on \meta{code} when appending or -%redefining a hook. -% -%\section{Examples} -%\label{sec:examples} -% -%The examples in this section illustrate the above commands. -% -%\subsection{animals.sty} -%\label{sec:animals} -% -%This example is for a trivial package called \sty{animals.sty} -%that defines three textual commands: \cs{catname}, \cs{dogname} -%and \cs{ladybirdname}. The default values are: \qt{cat}, \qt{dog} and -%\qt{bishy-barney-bee}.\footnote{Thass Broad Norfolk, my bewties -%\texttt{:-P}} -% -%The supported languages are defined in files -%with the prefix \texttt{animals-} and the suffix \texttt{.ldf}. -% -%Here's the code for \texttt{animals.sty}: -%\begin{verbatim} -% \NeedsTeXFormat{LaTeX2e} -% \ProvidesPackage{animals} -% -% \RequirePackage{tracklang}[2019/11/30] %v1.4 -% -% % Any undeclared options are language settings: -% -% \DeclareOption*{% -% \TrackIfKnownLanguage{\CurrentOption}% -% {\PackageInfo{animals}{Tracking language `\CurrentOption'}}% successful -% {% failed -% \PackageError{animals}% -% {Unknown language specification `\CurrentOption'}% -% {You need to supply either a known dialect label or a valid language tag}% -% }% -% } -% -% \ProcessOptions -% -% % Default definitions -% \newcommand\catname{cat} -% \newcommand\dogname{dog} -% \newcommand\ladybirdname{bishy-barney-bee} -% -% \AnyTrackedLanguages -% {% -% \ForEachTrackedDialect{\this@dialect}{% -% \TrackLangRequireDialect{animals}{\this@dialect}% -% }% -% } -% {% no tracked languages, default already set up -% } -% -% \endinput -%\end{verbatim} -%Here's a Plain \TeX\ version that picks up the language from the -%locale environment variable: -%\begin{verbatim} -% \input tracklang -% -% \TrackLangFromEnv -% -% % Default definitions -% \def\catname{cat} -% \def\dogname{dog} -% \def\ladybirdname{bishy-barney-bee} -% -% \AnyTrackedLanguages -% {% -% \ForEachTrackedDialect{\thisdialect}{% -% \TrackLangRequireDialect{animals}{\thisdialect}% -% }% -% } -% {% no tracked languages, default already set up -% } -%\end{verbatim} -%In the event that a user or supplementary package for some -%reason wants to load a resource -%file for a language that hasn't been tracked, it might be worth -%providing a command for this purpose: -%\begin{verbatim} -%\newcommand*{\RequireAnimalsDialect}[1]{% -% \TrackLangRequireDialect{animals}{#1}% -%} -%\end{verbatim} -%The loop can then be changed to: -%\begin{verbatim} -% \ForEachTrackedDialect{\this@dialect}{% -% \RequireAnimalsDialect\this@dialect -% }% -%\end{verbatim} -% -%The \texttt{animals-english.ldf} file valid for both the Plain \TeX\ -%and \LaTeX\ formats contains: -%\begin{verbatim} -%\TrackLangProvidesResource{english} -% -%\def\englishanimals{% -% \def\catname{cat}% -% \def\dogname{dog}% -% \def\ladybirdname{bishy-barney-bee}% -%} -% -%\TrackLangAddToCaptions{\englishanimals} -%\end{verbatim} -%The \texttt{animals-en-GB.ldf} file contains: -%\begin{verbatim} -%\TrackLangProvidesResource{en-GB} -%\TrackLangRequireResource{english} -% -%\def\enGBanimals{% -% \englishanimals -% \def\ladybirdname{ladybird}% -%} -%\TrackLangAddToCaptions{\enGBanimals} -%\end{verbatim} -%The \texttt{animals-en-US.ldf} file contains: -%\begin{verbatim} -%\TrackLangProvidesResource{en-US} -%\TrackLangRequireResource{english} -% -%\def\enUSanimals{% -% \englishanimals -% \def\ladybirdname{ladybug}% -%} -%\TrackLangAddToCaptions{\enUSanimals} -%\end{verbatim} -%Here's a German version in the file \texttt{animals-german.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{german} -% -%\def\germananimals{% -% \def\catname{Katze}% -% \def\dogname{Hund}% -% \def\ladybirdname{Marienk\"afer}% -%} -% -%\TrackLangAddToCaptions{\germananimals} -%\end{verbatim} -% -%This means that if \sty{babel} or \sty{polyglossia} are loaded, the -%redefinitions are automatically performed whenever the language is -%changed, but if there's no caption mechanism the user can switch -%the fixed names using the \cs{\ldots animals} commands. -% -%Here's an example \LaTeX\ document that doesn't have any caption -%hooks: -%\begin{verbatim} -%\documentclass[english,german,a4paper]{article} -% -%\usepackage{animals} -% -%\begin{document} -%\englishanimals -% -%\catname. -%\dogname. -%\ladybirdname. -% -%\germananimals -% -%\catname. -%\dogname. -%\ladybirdname. -%\end{document} -%\end{verbatim} -%Here's a \sty{babel} example document: -%\begin{verbatim} -%\documentclass[american,german,british,a4paper]{article} -% -%\usepackage{babel} -%\usepackage{animals} -% -%\begin{document} -%\selectlanguage{american} -% -%\catname. -%\dogname. -%\ladybirdname. -% -%\selectlanguage{german} -% -%\catname. -%\dogname. -%\ladybirdname. -% -%\selectlanguage{british} -% -%\catname. -%\dogname. -%\ladybirdname. -% -%\end{document} -%\end{verbatim} -% -%There is some redundancy with the above resource files. Consider the -%\sty{babel} example above. The \texttt{american} dialect is the -%first option, so in that case \texttt{animals-en-US.ldf} is loaded -%followed by \texttt{animals-english.ldf}. This means that the -%\cs{captionsamerican} hook now includes -%\begin{verbatim} -%\englishanimals -%\enUSanimals -%\end{verbatim} -%Since \cs{enUSanimals} includes \cs{englishanimals}, there is -%redundant code. However, when the \texttt{british} dialect is -%processed, this loads the file \texttt{animals-en-GB.ldf} but not -%the file \texttt{animals-english.ldf} (since it's already been loaded). This -%means that \cs{captionsbritish} contains \cs{enGBanimals} but not -%\cs{englishanimals}. -% -%If this redundancy is an issue (for example, there are so many -%redefinitions needed that it significantly slows the document build -%process), then it can be addressed with the following modifications. -%The \texttt{animals-en-GB.ldf} file is now: -%\begin{verbatim} -%\TrackLangProvidesResource{en-GB} -% -%\def\enGBanimals{% -% \englishanimals -% \def\ladybirdname{ladybird}% -%} -% -%\TrackLangRequireResourceOrDo{english}% -%{ -% \TrackLangAddToCaptions{% -% \def\ladybirdname{ladybird}% -% }% -%} -%{ -% \TrackLangAddToCaptions{\enGBanimals} -%} -%\end{verbatim} -%The \texttt{animals-en-US.ldf} file is now: -%\begin{verbatim} -%\TrackLangProvidesResource{en-US} -% -%\providecommand*{\enUSanimals}{% -% \englishanimals -% \renewcommand*{\ladybirdname}{ladybug}% -%} -% -%\TrackLangRequireResourceOrDo{english} -%{ -% \TrackLangAddToCaptions{% -% \renewcommand*{\ladybirdname}{ladybird}% -% }% -%} -%{ -% \TrackLangAddToCaptions{\enUSanimals}{captions} -%} -%\end{verbatim} -%This means that the document that has the dialects listed in the -%order \texttt{american}, \texttt{british} now has -%\begin{verbatim} -%\englishanimals -%\def\ladybirdname{ladybird} -%\end{verbatim} -%in the \cs{captionsbritish} hook and just \cs{enUSanimals} in the -%\cs{captionsamerican} hook, which has removed most of the redundancy. -% -%Note that \sty{polyglossia} has a \cs{captionsenglish} hook but not -%\cs{captionsamerican} or \cs{captionsbritish}, so this code doesn't -%allow for switching between variants of the same language with -%\sty{polyglossia}. -% -%\subsection{regions.sty} -%\label{sec:regions} -% -%Earlier, I~mentioned the search order for -%\ics{IfTrackedLanguageFileExists} where if, for example, the dialect -%is \texttt{british}, the file search (v1.4+) will be: -%\begin{enumerate} -%\item \texttt{mypackage-british.ldf} -%\item \texttt{mypackage-en-GB.ldf} -%\item \texttt{mypackage-en.ldf} -%\item \texttt{mypackage-eng-GB.ldf} -%\item \texttt{mypackage-eng.ldf} -%\item \texttt{mypackage-GB.ldf} -%\item \texttt{mypackage-english.ldf} -%\end{enumerate} -%You may have wondered why -%\texttt{mypackage-GB.ldf} is included in the search given that some -%countries have multiple official languages, which means that the country code on its -%own may not indicate the language. -% -%The reason for including just the country code as the \meta{localeid} in the -%file search is to allow for region rather than language dependent -%settings. For example, suppose I~want to write a package that needs -%to know whether to use imperial or metric measurements in the -%document, but I also want to provide multilingual support. The -%language alone won't tell me whether to use imperial or metric (for -%example, the US uses imperial and the UK uses metric for most -%product attributes). I could provide \texttt{.ldf} files for every -%language and region combination, but this would result in a lot -%redundancy. -% -%\cs{TrackLangRequireDialect} has an optional argument for adjusting -%the way the resource files are loaded. Suppose I have -%\texttt{regions-}\meta{localeid}\texttt{.ldf} resource files, then -%\begin{verbatim} -%\TrackLangRequireDialect{regions}{\this@dialect} -%\end{verbatim} -%loads the resource file for the dialect given by \cs{this@dialect} -%using -%\begin{verbatim} -%\TrackLangRequireResource{\CurrentTrackedTag} -%\end{verbatim} -%I can use the optional argument to also load the resource file for the -%root language as well: -%\begin{verbatim} -%\newcommand*{\RequireRegionsDialect}[1]{% -% \TrackLangRequireDialect -% [\TrackLangRequireResource{\CurrentTrackedTag}% -% \TrackLangRequireResource{\CurrentTrackedLanguage}% -% ]% -% {regions}{#1}% -%} -%\end{verbatim} -%Now the dialect \texttt{british} can load both -%\texttt{regions-GB.ldf} and \texttt{regions-english.ldf}. -% -%The example package (\texttt{regions.sty}) below illustrates this. -%\begin{verbatim} -%\NeedsTeXFormat{LaTeX2e} -%\ProvidesPackage{regions} -% -%\RequirePackage{tracklang}[2016/10/07] -% -%\DeclareOption*{\TrackLanguageTag{\CurrentOption}} -%\ProcessOptions -% -%\newcommand*{\weightunit}{kg} -%\newcommand*{\lengthunit}{mm} -%\newcommand*{\currencyunit}{EUR} -% -%\newcommand*{\unitname}{units} -% -%\newcommand*{\RequireRegionsDialect}[1]{% -% \TrackLangRequireDialect -% [\TrackLangRequireResource{\CurrentTrackedTag}% -% \TrackLangRequireResource{\CurrentTrackedLanguage}% -% ]% -% {regions}{#1}% -%} -% -%\AnyTrackedLanguages -%{% -% \ForEachTrackedDialect{\this@dialect}{% -% \RequireRegionsDialect\this@dialect -% }% -%} -%{% no tracked languages, default already set up -%} -% -%\endinput -%\end{verbatim} -%There are separate \texttt{.ldf} files for region and language. -%First are the regions. -% -%\begin{itemize} -%\item \texttt{regions-BE.ldf} (Belgium): -%\begin{verbatim} -%\TrackLangProvidesResource{BE} -% -%\providecommand*{\BEunits}{% -% \renewcommand*{\weightunit}{kg}% -% \renewcommand*{\lengthunit}{mm}% -% \renewcommand*{\currencyunit}{EUR}% -%} -% -%\TrackLangAddToCaptions{\BEunits} -%\end{verbatim} -% -%\item \texttt{regions-CA.ldf} (Canada): -%\begin{verbatim} -%\TrackLangProvidesResource{CA} -% -%\providecommand*{\CAunits}{% -% \renewcommand*{\weightunit}{kg}% -% \renewcommand*{\lengthunit}{mm}% -% \renewcommand*{\currencyunit}{CAD}% -%} -% -%\TrackLangAddToCaptions{\CAunits} -%\end{verbatim} -% -%\item \texttt{regions-GB.ldf} (Great Britain): -%\begin{verbatim} -%\TrackLangProvidesResource{GB} -% -%\providecommand*{\GBunits}{% -% \renewcommand*{\weightunit}{kg}% -% \renewcommand*{\lengthunit}{mm}% -% \renewcommand*{\currencyunit}{GBP}% -%} -% -%\TrackLangAddToCaptions{\GBunits} -%\end{verbatim} -% -%\item \texttt{regions-US.ldf} (USA): -%\begin{verbatim} -%\TrackLangProvidesResource{US} -% -%\providecommand*{\USunits}{% -% \renewcommand*{\weightunit}{lb}% -% \renewcommand*{\lengthunit}{in}% -% \renewcommand*{\currencyunit}{USD}% -%} -% -%\TrackLangAddToCaptions{\USunits} -%\end{verbatim} -%\end{itemize} -%Now the language files: -% -%\begin{itemize} -%\item \texttt{regions-dutch.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{dutch} -% -%\providecommand*{\dutchnames}{% -% \renewcommand*{\unitname}{meeteenheden}% -%} -% -%\TrackLangAddToCaptions{\dutchnames} -%\end{verbatim} -% -%\item \texttt{regions-english.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{english} -% -%\providecommand*{\englishnames}{% -% \renewcommand*{\unitname}{units}% -%} -% -%\TrackLangAddToCaptions{\englishnames} -%\end{verbatim} -% -%\item \texttt{regions-french.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{french} -% -%\providecommand*{\frenchnames}{% -% \renewcommand*{\unitname}{unit\'es}% -%} -% -%\TrackLangAddToCaptions{\frenchnames} -%\end{verbatim} -% -%\item \texttt{regions-german.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{french} -% -%\providecommand*{\germannames}{% -% \renewcommand*{\unitname}{Ma\ss einheiten}% -%} -% -%\TrackLangAddToCaptions{\germannames} -%\end{verbatim} -%\end{itemize} -% -%Here's an example document that uses this package: -%\begin{verbatim} -%\documentclass[canadien]{article} -% -%\usepackage{regions} -% -%\begin{document} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\end{document} -%\end{verbatim} -% -%This works because the \meta{localeid} search looks for the -%country code before the root language label. However, this will fail if -%the dialect label is the same as a root language label that has an -%associated territory, marked with \fnregion\ in -%\tableref{tab:rootlangopts}, as then it will be picked up before the -%country code. -% -%In the above example, -%\texttt{regions-CA.ldf} is matched rather than -%\texttt{regions-french.ldf}, so \texttt{regions-CA.ldf} is loaded by -%\begin{verbatim} -%\TrackLangRequireResource{\CurrentTrackedTag} -%\end{verbatim} -%After this, the language file \texttt{regions-french.ldf} is then loaded: -%\begin{verbatim} -%\TrackLangRequireResource{\CurrentTrackedLanguage} -%\end{verbatim} -% -%This assumes that there's a country code \texttt{.ldf} file -%available. This example needs a little modification to use default -%units in case the region is missing: -%\begin{verbatim} -%\NeedsTeXFormat{LaTeX2e} -%\ProvidesPackage{regions} -% -%% Pass all options to tracklang: -%\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{tracklang}} -%\ProcessOptions -% -%\RequirePackage{tracklang} -% -%\newcommand*{\weightunit}{kg} -%\newcommand*{\lengthunit}{mm} -%\newcommand*{\currencyunit}{EUR} -% -%\newcommand*{\unitname}{units} -% -%\newcommand*{\defaultunits}{% -% \renewcommand*{\weightunit}{kg}% -% \renewcommand*{\lengthunit}{mm}% -% \renewcommand*{\currencyunit}{EUR}% -%} -% -%\newcommand*{\RequireRegionsDialect}[1]{% -% \TrackLangRequireDialect -% [\TrackLangRequireResource{\CurrentTrackedTag}% -% \ifx\CurrentTrackedTag\CurrentTrackedLanguage -% \TrackLangAddToCaptions{\defaultunits}% -% \else -% \TrackLangRequireResource{\CurrentTrackedLanguage}% -% \fi -% ]% -% {regions}{#1}% -%} -% -%\AnyTrackedLanguages -%{% -% \ForEachTrackedDialect{\this@dialect}{% -% \RequireRegionsDialect\this@dialect -% }% -%} -%{% no tracked languages, default already set up -%} -% -%\endinput -%\end{verbatim} -%Note that we still have a problem for dialect labels that are -%identical to root language labels with an associated territory (such -%as \pkgopt{manx}). This case can be checked with the following -%adjustment: -%\begin{verbatim} -%\newcommand*{\RequireRegionsDialect}[1]{% -% \TrackLangRequireDialect -% [\TrackLangRequireResource{\CurrentTrackedTag}% -% \ifx\CurrentTrackedTag\CurrentTrackedLanguage -% \ifx\CurrentTrackedRegion\empty -% \TrackLangAddToCaptions{\defaultunits}% -% \else -% \TrackLangRequireResource{\CurrentTrackedRegion}% -% \fi -% \else -% \TrackLangRequireResource{\CurrentTrackedLanguage}% -% \fi -% ]% -% {regions}{#1}% -%} -%\end{verbatim} -%In the case where both the dialect and root language label are -%\texttt{manx} with the resource files \texttt{regions-manx.ldf} -%and \texttt{regions-IM.ldf}, then \cs{CurrentTrackedTag} will be -%\texttt{manx} (the dialect label) so \texttt{regions-manx.ldf} will -%be loaded with: -%\begin{verbatim} -%\TrackLangRequireResource{\CurrentTrackedTag} -%\end{verbatim} -%In this case \cs{CurrentTrackedRegion} is \texttt{IM} (that is, it's -%not empty) so then \texttt{regions-IM.ldf} will be loaded with: -%\begin{verbatim} -%\TrackLangRequireResource{\CurrentTrackedRegion} -%\end{verbatim} -% -%Here's another document that sets up dialects with -%\styfmt{tracklang} labels that aren't recognised by \sty{babel}. -%This means that there's no corresponding \cs{captions\ldots} hook -%for either the dialect label or the root language label, -%so mappings need to be defined from the \styfmt{tracklang} dialect -%label to the matching \sty{babel} dialect label. -% -%\begin{verbatim} -%\documentclass{article} -% -%\usepackage{tracklang} -% -%\TrackLanguageTag{de-US-1996} -%\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{ngerman} -% -%\TrackLanguageTag{en-MT} -%\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish} -% -%\usepackage[main=ngerman,UKenglish]{babel} -%\usepackage{regions} -% -%\begin{document} -%\selectlanguage{ngerman} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\selectlanguage{UKenglish} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\end{document} -%\end{verbatim} -%This produces: -%\begin{quote} -%Ma\ss einheiten: lb, in, USD. -% -%units: kg, mm, EUR. -%\end{quote} -%Compare this with: -%\begin{verbatim} -%\documentclass{article} -% -%\usepackage[main=ngerman,UKenglish]{babel} -%\usepackage{regions} -% -%\begin{document} -%\selectlanguage{ngerman} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\selectlanguage{UKenglish} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\end{document} -%\end{verbatim} -%which produces: -%\begin{quote} -%Ma\ss einheiten: kg, mm, EUR. -% -%units: kg, mm, GBP. -%\end{quote} -% -%Note that these mappings aren't needed if \sty{babel} -%is loaded with the root language labels instead. For example: -%\begin{verbatim} -%\documentclass{article} -% -%\usepackage{tracklang} -% -%\TrackLanguageTag{de-US-1996} -%\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{ngerman} -% -%\TrackLanguageTag{en-MT} -% -%\usepackage[main=ngerman,english]{babel} -%\usepackage{regions2} -% -%\begin{document} -%\selectlanguage{ngerman} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\selectlanguage{english} -% -%\unitname: \weightunit, \lengthunit, \currencyunit. -% -%\end{document} -%\end{verbatim} -%No mapping is required for the \texttt{en-MT} locale as -%it can pick up \cs{captionsenglish} when \cs{TrackLangAddToHook} -%(used by \cs{TrackLangAddToCaptions}) -%queries the root language label after failing to find the -%language hook from the dialect label. -% -%Some of the predefined \styfmt{tracklang} dialects come with -%a mapping to the closest matching \sty{babel} dialect label. -%For example, the option \pkgopt{ngermanDE} listed in -%\tableref{tab:nonisoopts} automatically provides a mapping -%to \texttt{ngerman}. Since a \styfmt{tracklang} dialect label -%can only map to one \styfmt{babel} label, this can be problematic -%for synonymous labels such as -%\texttt{british}\slash\texttt{UKenglish} or -%\texttt{american}\slash\texttt{USenglish}. The default mappings used -%by \styfmt{tracklang} are shown in \tableref{tab:nonisoopts}. -% -%\chapter{Adding Support for Language Tracking} -%\label{sec:langsty} -% -%If you are writing a package that \emph{sets up} the document languages (rather -%than a package that provides multilingual support if the user has -%already loaded a language package) then you can load \styfmt{tracklang} -%and use the commands below to help other packages track your -%provided languages. (See also: -%\href{https://www.dickimaw-books.com/latex/tracklang/langpkg.shtml}{Integrating -%\texttt{tracklang.tex} into Language Packages}.) -% -%The \styfmt{tracklang} package can be loaded using -%\begin{verbatim} -%\input tracklang -%\end{verbatim} -%or (\LaTeX\ only) -%\begin{verbatim} -%\RequirePackage{tracklang} -%\end{verbatim} -% -%When using \LaTeX, there's a difference between the two. -%The first case prevents \styfmt{tracklang} from picking up -%the document class options but skips the check for known -%language packages. This check is redundant since your package is -%the language package, so you need to decide is whether or -%not to allow the user to set up the localisation information -%through the document class options. -% -%If you prefer \cs{RequirePackage} over \cs{input} but you want to make -%\texttt{tracklang.sty} skip the check for known -%language packages then (as from v1.3.8) define the pre-language -%package check hook as follows: -%\begin{verbatim} -%\providecommand\@tracklang@prelangpkgcheck@hook{\endinput} -%\RequirePackage{tracklang}[2019/10/06] -%\end{verbatim} -%This will still pick up languages supplied through the -%document class options. -% -%If you just use \cs{input}, there's a test at the start of -%\texttt{tracklang.tex} to determine if it's already been loaded, so -%you don't need to worry if the document has already loaded it. -% -%To integrate \sty{tracklang} into your language package, you need to consider the following -%steps: -%\begin{enumerate} -%\item Does \sty{tracklang} define your supported ISO~15924 language -%scripts in the \texttt{tracklang-scripts.tex} file? -% -%If yes, then skip this step. Otherwise create a file with the -%relevant \ics{TrackLangScriptMap} command for each unknown script and identify -%this new file with \ics{TrackLangAddExtraScriptFile} (see -%\sectionref{sec:newscripts}). This usually -%won't be necessary unless you have a custom script or a child script -%(a script that's a sub-category of another script). -% -%\item Does \sty{tracklang} recognise the root language? -% -%If yes, then skip this step. -% -%If your package is setting up a language that \sty{tracklang} -%doesn't recognise then you will need to define the root language -%using \cs{TrackLangNewLanguage} (see \sectionref{sec:newlanguages}). -% -%This usually won't be the case as \sty{tracklang} should support all -%languages that have an official ISO~639-1 alpha-2 code. -% -%If you simply have a different label from \sty{tracklang} identifying the root language, -%then you can just set up your label as a dialect using -%\cs{TrackLangProvidePredefinedDialect} (see \sectionref{sec:predefinedlabels}). -% -%\item Does \sty{tracklang} define the relevant ISO~3166 region codes -%in the \texttt{tracklang-region-codes.tex} file? -% -%If yes, then skip this step. Otherwise create a file with the -%relevant \ics{TrackLangRegionMap} command for each new region and -%identify this new file with \ics{TrackLangAddExtraRegionFile} (see -%\sectionref{sec:newregions}). This usually won't be necessary as -%\sty{tracklang} should recognise all countries that have an alpha-2 -%region code, but you may require it if you need a broader region, -%such as EU. -% -%\item Do you want to define some convenient dialect labels that can -%be used with \ics{TrackPredefinedDialect}? -% -%If no, then skip this step. Otherwise you can use -%\ics{TrackLangProvidePredefinedLanguage} for root languages -%and \ics{TrackLangProvidePredefinedDialect} for dialects with -%additional information, such as a region, sub-language or script -%(see \sectionref{sec:predefinedlabels}). -% -%\item In your language initialisation code, add the \sty{tracklang} -%code to track the particular dialect (for example, use -%\cs{TrackPredefinedDialect} for recognised dialect labels or -%use the \cs{AddTracked}\ldots\ set of commands). See -%\sectionref{sec:initnewlang}. -% -%\item In your language selection code (such as \cs{selectlanguage}), add -%\cs{SetCurrentTrackedDialect}\marg{label} to allow the document -%author to easily query the current localisation settings (such as -%the region). See \sectionref{sec:selectlanguage}. -%\end{enumerate} -% -%\section{Initialising a New Language or Dialect} -%\label{sec:initnewlang} -% -%When the user requests a particular dialect through your language -%package, you can notify \styfmt{tracklang} of this choice using -%\begin{definition} -%\cs{TrackPredefinedDialect}\marg{dialect} -%\end{definition} -%provided the dialect label is recognised by \styfmt{tracklang} (all those -%listed in \refoptstables). -% -%If there's no matching dialect predefined by \styfmt{tracklang}, you -%can just use \cs{TrackLocale} or \cs{TrackLanguageTag} -%(described in \sectionref{sec:generic}) -%with the appropriate ISO codes \emph{if you're not providing caption -%hooks}. -% -%If you are providing a captions hook mechanism -%in the form \ics{captions\meta{dialect}}, then if \meta{dialect} -%doesn't match the corresponding \styfmt{tracklang} dialect label, -%you can provide a mapping using -%\cs{SetTrackedDialectLabelMap}, described below. -% -%\section{Switching Language or Dialect} -%\label{sec:selectlanguage} -% -%When the document author switches to a different language or -%dialect, the current localisation information can be set with: -%\begin{definition}[\DescribeMacro\SetCurrentTrackedDialect] -%\cs{SetCurrentTrackedDialect}\marg{dialect} -%\end{definition} -%where \meta{dialect} may the \styfmt{tracklang} dialect label, -%or the mapped label previously set through \cs{SetTrackedDialectLabelMap}, -%described below, or the language label (in which case the -%last dialect to be tracked with that root language will -%be assumed). -% -%This will make the following commands available which may be -%of use to other packages: -%\begin{itemize} -%\item\ics{CurrentTrackedDialect} The dialect label recognised -%by \styfmt{tracklang} (which may not be the same as \meta{dialect}). -% -%\item\ics{CurrentTrackedLanguage} -%The root language label used by \styfmt{tracklang}. -%\item\ics{CurrentTrackedDialectModifier} The dialect modifier. -%\item\ics{CurrentTrackedDialectVariant} The dialect variant. -%\item\ics{CurrentTrackedDialectScript} The dialect script. -%Note that if \sty{tracklang-scripts} is also loaded, this allows the -%script direction to be accessed using -%\begin{verbatim} -%\TrackLangScriptAlphaToDir{\CurrentTrackedDialectScript} -%\end{verbatim} -%See \sectionref{sec:tracklang-scripts.tex} for further details. -%\item\ics{CurrentTrackedDialectSubLang} The dialect sub-language -%code. -%\item\ics{GetTrackedDialectAdditional} The dialect's additional -%information. -%\item\ics{CurrentTrackedIsoCode} The dialect's root language -%ISO code. (The first found in the sequence 639-1, 639-2, 639-3.) -%\item\ics{CurrentTrackedRegion} The dialect's ISO 3166-1 region -%code. -%\item\ics{CurrentTrackedLanguageTag} The dialect's language tag. -%\end{itemize} -%(Without this automated use of \cs{SetCurrentTrackedDialect}, -%the same information can be picked up using commands -%like \cs{GetTrackedDialectScript}, but that's less convenient, -%especially if \cs{languagename} needs to be converted -%to \meta{dialect}. See the accompanying sample file -%\texttt{sample-setlang.tex} for an example.) -% -%\section{Defining New Scripts} -%\label{sec:newscripts} -% -%The \texttt{tracklang-scripts.tex} file isn't automatically loaded, -%but if it is then, as from v1.4, it contains a hook at the end of -%the file that can be used to load additional files that define -%supplementary scripts. This entails creating a file called, say, -%\texttt{mypackage-scripts.tex} that contains: -%\begin{definition}[\DescribeMacro\TrackLangScriptMap] -%\cs{TrackLangScriptMap}\marg{alpha code}\marg{numeric -%code}\marg{name}\marg{direction}\marg{parent} -%\end{definition} -%The first argument \meta{alpha code} is the four-letter ISO~15924 code (such as -%\texttt{Latn}), the second argument is the numeric code (such as -%215), the third argument \meta{name} is the name of the script (such -%as \texttt{Latin}), the fourth argument is the direction (such as -%\texttt{LR} for left-to-right) and the final argument is the parent -%script (leave blank if there's no parent). Note that this command will override any previous -%mapping for those codes. No check is performed to determine if they -%have already been defined. -% -%The supplementary file should be identified with: -%\begin{definition}[\DescribeMacro\TrackLangAddExtraScriptFile] -%\cs{TrackLangAddExtraScriptFile}\marg{filename} -%\end{definition} -% -%\section{Defining New Regions} -%\label{sec:newregions} -% -%The \texttt{tracklang-region-codes.tex} file isn't automatically loaded, -%but if it is then, as from v1.4, it contains a hook at the end of -%the file that can be used to load additional files that define -%supplementary regions. This entails creating a file called, say, -%\texttt{mypackage-regions.tex} that contains: -%\begin{definition}[\DescribeMacro\TrackLangRegionMap] -%\cs{TrackLangRegionMap}\marg{numeric code}\marg{alpha-2 code}\marg{alpha-3 code} -%\end{definition} -%where the first argument is the numeric region code (such as 826), -%the second argument is the alpha-2 region code (such as \texttt{GB}) -%and the third argument is the alpha-3 region code (such as -%\texttt{GBR}). Note that this command will override any previous -%mapping for those codes. No check is performed to determine if they -%have already been defined. -% -%The supplementary file should be identified with: -%\begin{definition}[\DescribeMacro\TrackLangAddExtraRegionFile] -%\cs{TrackLangAddExtraRegionFile}\marg{filename} -%\end{definition} -% -%\section{Defining a New Language} -%\label{sec:newlanguages} -% -%(New to version 1.3.) -%If the root language isn't recognised by \styfmt{tracklang} -%(not listed in \tableref{tab:rootlangopts}), then -%it can be defined (but not tracked at this point) using: -%\begin{definition}[\DescribeMacro\TrackLangNewLanguage] -%\cs{TrackLangNewLanguage}\marg{language name}\marg{639-1 -%code}\marg{639-2 (T)}\marg{639-2 (B)}\marg{639-3}\marg{3166-1}\marg{default -%script} -%\end{definition} -%where \meta{language name} is the root language name, -%\meta{639-1 code} is the ISO 639-1 code for that language (may be -%empty if there isn't one), \meta{639-2 (T)} is the ISO 639-2 (T) -%code for that language (may be empty if there isn't one), -%\meta{639-2 (B)} is the ISO 639-2 (B) code for that language (may be -%empty if it's the same as \meta{639-2 (T)}), \meta{639-3} is the ISO -%639-3 code for that language (empty if the same as the 639-2 -%code), \meta{3166-1} is the territory ISO code for languages that are only spoken in one -%territory (should be empty if the language is spoken in multiple -%territories), and \meta{default script} is the default script (empty -%if disputed or varies according to region). -% -%You can then track this language using \cs{AddTrackedDialect} for -%dialects or, if no regional variant is needed, you can instead use: -%\begin{definition}[\DescribeMacro\AddTrackedLanguage] -%\cs{AddTrackedLanguage}\marg{root language label} -%\end{definition} -%This is equivalent to \ics{AddTrackedDialect}\marg{root language -%label}\marg{root language label}. -% -% -%\section{Defining New \styfmt{tracklang} Labels} -%\label{sec:predefinedlabels} -% -%A dialect label may be predefined with associated information that -%allows that particular combination to be easily tracked with -%\cs{TrackPredefinedDialect}. In the case of a dialect label that -%only requires the information provided in \cs{TrackLangNewLanguage} -%you can use: -%\begin{definition}[\DescribeMacro\TrackLangProvidePredefinedLanguage] -%\cs{TrackLangProvidePredefinedLanguage}\marg{label} -%\end{definition} -%where \meta{label} corresponds to the language label used in -%\cs{TrackLangNewLanguage}. This allows -%\cs{TrackPredefinedDialect}\marg{label} to not only track the root -%language but also the associated ISO codes. -% -%If the dialect label doesn't match the root language label then use: -%\begin{definition}[\DescribeMacro\TrackLangProvidePredefinedDialect] -%\cs{TrackLangProvidePredefinedDialect}\marg{dialect}\marg{language}\marg{region}\marg{modifier}\marg{variant}\marg{map}\marg{script} -%\end{definition} -%where \meta{dialect} is the new \sty{tracklang} dialect label, -%\marg{language} is the \sty{tracklang} root language label, -%\meta{region} is the ISO~3166-1 region code (may be empty), -%\meta{modifier} is the modifier (may be empty), \meta{variant} -%is the variant information (may be empty), \meta{map} is your -%package's language label that corresponds to the \sty{tracklang} -%dialect label supplied in the first argument (may be empty if -%identical), and \meta{script} is the ISO~15914 alpha-4 script code -%(may be empty if it's the same as the default script for the root -%language). -% -%For compatibility with pre version 1.3, -%if the dialect isn't predefined by -%\styfmt{tracklang}, then you can use: -%\begin{definition}[\DescribeMacro\AddTrackedDialect] -%\cs{AddTrackedDialect}\marg{dialect}\marg{root language label} -%\end{definition} -%where \meta{root language label} is the label for the dialect's root -%language (\tableref{tab:rootlangopts}) and \meta{dialect} matches -%the captions hook. If the dialect is already in the tracked dialect -%list, it won't be added again. If the root language is already in -%the tracked language list, it won't be added again. As from version -%1.3 this additionally defines: -%\begin{definition}[\DescribeMacro\TrackLangLastTrackedDialect] -%\cs{TrackLangLastTrackedDialect} -%\end{definition} -%to \meta{dialect} for convenient reference if required. -%Note that \cs{AddTrackedDialect} is internally used by commands like -%\cs{TrackPredefinedDialect}, \cs{TrackLocale} and -%\cs{TrackLanguageTag}. -% -%(New to version 1.3.) Many of the \styfmt{tracklang} dialect -%labels don't have a corresponding match in various language packages. For -%example, \styfmt{tracklang} provides \texttt{ngermanDE} but the -%closest match in \sty{babel} is \texttt{ngerman}. This means that -%the caption hook \cs{captionsngerman} can't be accessed -%through -%\begin{verbatim} -%\csname captions\CurrentTrackedDialect\endcsname -%\end{verbatim} -%in the resource files. In this case, a mapping may be defined -%between the \styfmt{tracklang} dialect label and the closest -%matching label used by the language hooks. This is done through -%\begin{definition}[\DescribeMacro\SetTrackedDialectLabelMap] -%\cs{SetTrackedDialectLabelMap}\marg{from}\marg{to} -%\end{definition} -%where \meta{from} is the \styfmt{tracklang} label and \meta{to} -%is the language hook label. For example: -%\begin{verbatim} -%\TrackLanguageTag{de-AR-1996} -%\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{ngerman} -%\end{verbatim} -%Since \cs{TrackLanguageTag} internally uses \cs{AddTrackedDialect} -%the dialect label created by \styfmt{tracklang} can be accessed -%using \cs{TrackLangLastTrackedDialect}. This means that -%\ics{TrackLangAddToCaptions} can now find the \cs{captionsngerman} -%hook even though the \styfmt{tracklang} dialect label isn't \texttt{ngerman}. -% -%(New to version 1.3.) -%If the root language label is recognised by \styfmt{tracklang}, you -%can add the ISO codes using: -%\begin{definition}[\DescribeMacro\AddTrackedLanguageIsoCodes] -%\cs{AddTrackedLanguageIsoCodes}\marg{root language} -%\end{definition} -% -%As from v1.3, you can also provide a modifier for a given -%dialect using: -%\begin{definition}[\DescribeMacro\SetTrackedDialectModifier] -%\cs{SetTrackedDialectModifier}\marg{dialect}\marg{value} -%\end{definition} -%where \meta{dialect} is the dialect label and \meta{value} -%is the modifier value. For example: -%\begin{verbatim} -%\AddTrackedDialect{oldgerman}{german} -%\AddTrackedLanguageIsoCodes{german} -%\SetTrackedDialectModifier{oldgerman}{old} -%\end{verbatim} -% -%Note that no sanitization is performed on \meta{value} when the -%modifier is set explicitly through \cs{SetTrackedDialectModifier}, -%since it's assumed that any package that specifically sets the -%modifier in this way is using a sensible labelling system. If the -%modifier is obtained through commands like \cs{TrackLocale}, then -%the modifier is sanitized as the value may have been obtained from -%the operating system and there's no guarantee that it won't contain -%problematic characters. -% -%The modifier is typically obtained by parsing locale information in -%POSIX format. -%\begin{display} -%\meta{language}[\_\meta{territory}][.\meta{codeset}][@\meta{modifier}] -%\end{display} -%whereas the variant is typically obtained by parsing the language -%tag. -% -%The information provided in the commands below (such as the script) -%are typically obtained by parsing the language tag. For example, -%with Serbian in the Latin alphabet the modifier would be \texttt{latin} -%whereas the script would be \texttt{Latn}: -%\begin{verbatim} -%\AddTrackedDialect{serbianlatin}{serbian} -%\AddTrackedLanguageIsoCodes{serbian} -%\SetTrackedDialectModifier{serbianlatin}{latin} -%\SetTrackedDialectScript{serbianlatin}{Latn} -%\end{verbatim} -% -%As from v1.3, you can provide a script (for example, -%\qt{Latn} or \qt{Cyrl}) using: -%\begin{definition}[\DescribeMacro\SetTrackedDialectScript] -%\cs{SetTrackedDialectScript}\marg{dialect}\marg{value} -%\end{definition} -%where \meta{dialect} is the dialect label and \meta{value} is the -%four letter script identifier. For example: -%\begin{verbatim} -%\AddTrackedDialect{serbiancyrl}{serbian} -%\AddTrackedLanguageIsoCodes{serbian} -%\SetTrackedDialectScript{serbiancyrl}{Cyrl} -%\end{verbatim} -% -%As from v1.3, you can provide a variant for a given -%dialect using: -%\begin{definition}[\DescribeMacro\SetTrackedDialectVariant] -%\cs{SetTrackedDialectVariant}\marg{dialect}\marg{value} -%\end{definition} -%For example: -%\begin{verbatim} -%\AddTrackedDialect{german1901}{german} -%\SetTrackedDialectVariant{german1901}{1901} -%\end{verbatim} -% -%As from v1.3, you can also provide a sub-language using: -%\begin{definition}[\DescribeMacro\SetTrackedDialectSubLang] -%\cs{SetTrackedDialectSubLang}\marg{dialect}\marg{value} -%\end{definition} -%where \meta{dialect} is the dialect label and \meta{value} is the -%code. For example: -%\begin{verbatim} -%\AddTrackedDialect{mandarin}{chinese} -%\AddTrackedLanguageIsoCodes{chinese} -%\SetTrackedDialectSubLang{mandarin}{cmn} -%\AddTrackedIsoLanguage{639-3}{cmn}{mandarin} -%\end{verbatim} -% -%As from v1.3, you can also provide additional information using: -%\begin{definition}[\DescribeMacro\SetTrackedDialectAdditional] -%\cs{SetTrackedDialectAdditional}\marg{dialect}\marg{value} -%\end{definition} -%where \meta{dialect} is the dialect label and \meta{value} is the -%additional information. -% -%\section{Example} -% -%Suppose I want to create a language package \texttt{alien.sty} that defines the -%\texttt{martian} language with regional dialects -%\texttt{lowermartian} and \texttt{uppermartian}. First, let's -%suppose that \styfmt{tracklang} recognises the root language -%\texttt{martian}: -%\begin{verbatim} -% \ProvidesPackage{alien} -% -% \input{tracklang}% v1.3 -% -% \DeclareOption{martian}{% -% \TrackPredefinedDialect{martian} -% } -% \DeclareOption{lowermartian}{% -% \AddTrackedDialect{lowermartian}{martian} -% \AddTrackedIsoCodes{martian} -% \AddTrackedIsoLanguage{3166-1}{YY}{lowermartian} -% % other attributes such as -% % \SetTrackedDialectVariant{lowermartian}{...} -% } -% \DeclareOption{uppermartian}{% -% \AddTrackedDialect{uppermartian}{martian} -% \AddTrackedIsoCodes{martian} -% \AddTrackedIsoLanguage{3166-1}{XX}{uppermartian} -% % other attributes such as -% % \SetTrackedDialectVariant{uppermartian}{...} -% } -% -% \ProcessOptions -% -% \newcommand*{\selectlanguage}[1]{% -% \def\languagename{#1}% -% % other stuff -% \SetCurrentTrackedDialect{#1}% -% } -% -% \AnyTrackedLanguages -% { -% \ForEachTrackedDialect{\thisdialect} -% {% -% \TrackLangRequireDialect{alien}{\thisdialect} -% } -% } -%\end{verbatim} -%The caption commands and language set up are in the files -%\texttt{alien-}\meta{localeid}\texttt{.ldf} as in the examples from -%\sectionref{sec:examples}. This allows for the user having already -%loaded \styfmt{tracklang} before \styfmt{alien} and used \cs{TrackLangFromEnv} to pick up -%the locale from the operating system's environment variables. -%(For example, they may have \envvar{LANG} set to \texttt{xx\_YY}.) -% -%The resource files may need to set the mapping between the -%\styfmt{tracklang} dialect label and the \styfmt{alien} dialect -%label. For example, in \texttt{alien-xx-YY.ldf}: -%\begin{verbatim} -%\TrackLangProvidesResource{xx-YY} -% -%\TrackLangRequireResource{martian}% load common elements -% -%\newcommand{\captionslowermartian}{% -% \captionsmartian -% \def\contentsname{X'flurp}% regional variation -%} +% -doc "tracklang-codedoc.tex" +% -author "Nicola Talbot" +% -codetitle "Main Package Code" +% -src "tracklang.sty\Z=>tracklang.sty" +% -src "tracklang.tex\Z=>tracklang.tex" +% -src "tracklang-region-codes.tex\Z=>tracklang-region-codes.tex" +% -src "tracklang-scripts.sty\Z=>tracklang-scripts.sty" +% -src "tracklang-scripts.tex\Z=>tracklang-scripts.tex" +% tracklang +% Created on 2022/10/29 18:01 +%\fi +%\iffalse +%<*package> +%% \CharacterTable +%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +%% Digits \0\1\2\3\4\5\6\7\8\9 +%% Exclamation \! Double quote \" Hash (number) \# +%% Dollar \$ Percent \% Ampersand \& +%% Acute accent \' Left paren \( Right paren \) +%% Asterisk \* Plus \+ Comma \, +%% Minus \- Point \. Solidus \/ +%% Colon \: Semicolon \; Less than \< +%% Equals \= Greater than \> Question mark \? +%% Commercial at \@ Left bracket \[ Backslash \\ +%% Right bracket \] Circumflex \^ Underscore \_ +%% Grave accent \` Left brace \{ Vertical bar \| +%% Right brace \} Tilde \~} +%
+%\fi +% \iffalse +% Doc-Source file to use with LaTeX2e +% Copyright (C) 2022 Nicola Talbot, all rights reserved. +% \fi +% \iffalse +%<*driver> +\iffalse +tracklang-codedoc.tex is a stub file used by makedtx to create +tracklang.dtx +\fi + +\documentclass{article} +\usepackage{doc} + +\CheckSum{6236} + +\RecordChanges +\PageIndex +\SetupDoc{reportchangedates} +\setcounter{IndexColumns}{2} + +\usepackage[T1]{fontenc} +\usepackage{tcolorbox} + +\definecolor{defbackground}{rgb}{1,1,0.75} + +\newtcolorbox{definition}{halign=flush left, + colframe=black,colback=defbackground, + fontupper=\ttfamily, + before upper={\frenchspacing\obeylines}, + after={\par\noindent\ignorespacesafterend} +} + +\NewDocElement{Option}{option} + +\providecommand{\sty}[1]{\styfmt{#1}} +\providecommand{\styfmt}[1]{\textsf{#1}} +\providecommand{\pkgoptfmt}[1]{\textsf{#1}} +\providecommand{\envvar}[1]{\texttt{#1}} +\providecommand{\app}[1]{\texttt{#1}} +\providecommand{\qt}[1]{``#1''} +\providecommand{\sectionref}[1]{\S\ref{#1}} + +\providecommand\marg[1]{% + \texorpdfstring{\allowbreak{\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}} + {\{#1\}}} +\providecommand\oarg[1]{% + \texorpdfstring{\allowbreak{\ttfamily[}\meta{#1}{\ttfamily]}} + {[#1]}} + +\begin{document} +\DocInput{tracklang.dtx} +\end{document} +% +%\fi % -%\SetTrackedDialectLabelMap{\CurrentTrackedDialect}{lowermartian} -%\end{verbatim} +% \title{Documented Code For tracklang v1.6} +% \author{Nicola L.C. Talbot\\[10pt] +%Dickimaw Books\\ +%\url{http://www.dickimaw-books.com/}} % -%Now let's consider the case where \styfmt{tracklang} doesn't know -%about the \texttt{martian} language. In this case the user can't -%track the dialect until the root language has been defined, so the -%user can't use \cs{TrackLangFromEnv} before using the \styfmt{alien} -%package. +% \date{2022-10-29} +% \maketitle % -%With \styfmt{tracklang} v1.3. The new root language can be defined -%with a minor adjustment to the above code: -%\begin{verbatim} -% \ProvidesPackage{alien} +%\tableofcontents % -% \input{tracklang}% needs v1.3 +%\section{Introduction} % -% \TrackLangIfKnownLang{martian} -% {}% tracklang already knows about the martian language -% { -% % tracklang doesn't known about the martian language, so define it -% % with ISO 639-1 (xx) and ISO 639-2 (xxx) codes: -% \TrackLangNewLanguage{martian}{xx}{xxx}{}{}{}{Latn} -% } -%\end{verbatim} -%The rest is as before. +%This is the documented code for the \sty{tracklang} package. +%See \texttt{tracklang-manual.pdf} for the main user guide. % -%Now other package writers who want to provide support -%for the Martian dialects can easily detect which language options -%the user requested through my package, \emph{without needing to know -%anything about my \styfmt{alien} package}. +%\StopEventually{\clearpage\PrintChanges \clearpage\PrintIndex} % -%\StopEventually{% -% \printindex[user] -% \PrintCodeIndex -% \PrintChanges -%} % % -%\chapter{The Code} +%\section{Main Package Code} %\iffalse % \begin{macrocode} %<*tracklang.sty> @@ -3583,7 +119,7 @@ and~\ref{tab:nonisoopts}} % packages such as \styfmt{etoolbox}. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{tracklang}[2020/06/30 v1.5 (NLCT) Track Languages] +\ProvidesPackage{tracklang}[2022/10/29 v1.6 (NLCT) Track Languages] % \end{macrocode} %\begin{macro}{\@tracklang@declareoption} % Set up package options. @@ -3673,6 +209,15 @@ and~\ref{tab:nonisoopts}} \@ifpackageloaded{polyglossia} {% % \end{macrocode} +%\sty{polyglossia} now provides \cs{xpg@bcp@loaded}, which contains +%a comma-separated list of language tags, so use that if +%it exists. +%\changes{1.6}{2022-10-29}{added check for \cs{xpg@bcp@loaded}} +% \begin{macrocode} + \@ifundefined{xpg@bcp@loaded}% + {% +% \end{macrocode} +% Older versions: % \sty{polyglossia} sets \cs{\meta{lang}@loaded} for each loaded % language, so check this for all known languages. I don't know how % to consistently check for variants. (Conditionals such as @@ -3687,34 +232,70 @@ and~\ref{tab:nonisoopts}} %\changes{1.3}{2016-10-07}{removed hard-coded polyglossia language list} %\changes{1.3.5}{2018-02-21}{check for \cs{xpg@loaded}} % \begin{macrocode} - \@ifundefined{xpg@loaded}% - {% + \@ifundefined{xpg@loaded}% + {% % \end{macrocode} %\cs{xpg@loaded} isn't defined, so iterate over known options and %check if the language has been loaded. % \begin{macrocode} - \PackageInfo{tracklang}{polyglossia loaded but - \string\xpg@loaded\space not defined. Will attempt - to track known languages.}% - \@for\this@language:=\@tracklang@declaredoptions\do{% - \@ifundefined{\this@language @loaded}% - {}% - {\@nameuse{@tracklang@add@\this@language}}% - }% - }% - {% - \@for\this@language:=\xpg@loaded\do{% - \@ifundefined{@tracklang@add@\this@language}% - {% - \PackageWarning{tracklang}% - {Adding unknown polyglossia language `\this@language'}% + \PackageInfo{tracklang}{polyglossia loaded but + \string\xpg@loaded\space not defined. Will attempt + to track known languages.}% + \@for\this@language:=\@tracklang@declaredoptions\do{% + \@ifundefined{\this@language @loaded}% + {}% + {\@nameuse{@tracklang@add@\this@language}}% + }% + }% + {% + \@for\this@language:=\xpg@loaded\do{% + \@ifundefined{@tracklang@add@\this@language}% + {% + \PackageWarning{tracklang}% + {Adding unknown polyglossia language `\this@language'}% % \end{macrocode} %\changes{1.3.7}{2019-08-31}{corrected misspelt command} % \begin{macrocode} - \AddTrackedLanguage{\this@language}% + \AddTrackedLanguage{\this@language}% + }% + {\@nameuse{@tracklang@add@\this@language}}% }% - {\@nameuse{@tracklang@add@\this@language}}% - }% + }% + }% + {% + \@for\this@language:=\xpg@bcp@loaded\do{% +% \end{macrocode} +%These are language tags, which is more convenient. +% \begin{macrocode} + \expandafter\TrackLanguageTag{\this@language}% + }% + }% +% \end{macrocode} +%The \cs{xpg@bcp@loaded} list doesn't seem to include the main +%language until the start of the document environment but +%\cs{mainbabelname} is defined after \cs{setmainlanguage}. I'm not +%sure if \cs{mainbabelname} was provided in the same version of +%\sty{polyglossia} as \cs{xpg@bcp@loaded} or a different one, so +%have a separate conditional. +% \begin{macrocode} + \@ifundefined{mainbabelname}{}% + {% + \let\@org@tracklang@add@latex\@tracklang@add@latex + \def\@tracklang@add@latex{% + \PackageWarning{tracklang}% + {Can't detect polyglossia main language. It may + not have been set yet}% + }% + \@ifundefined{@tracklang@add@\mainbabelname}% + {% + \PackageWarning{tracklang}% + {Adding unknown polyglossia main babel name `\mainbabelname'}% + \expandafter\AddTrackedLanguage{\mainbabelname}% + }% + {% + \@nameuse{@tracklang@add@\mainbabelname}% + }% + \let\@tracklang@add@latex\@org@tracklang@add@latex }% }% {% @@ -3879,7 +460,7 @@ and~\ref{tab:nonisoopts}} % Version info. % \begin{macrocode} \expandafter\def\csname ver@tracklang.tex\endcsname{% - 2020/06/30 v1.5 (NLCT) Track Languages Generic Code} + 2022/10/29 v1.6 (NLCT) Track Languages Generic Code} % \end{macrocode} % Define a long command for determining the existence of a control % sequence by its name. (\cs{relax} is considered undefined.) @@ -4348,18 +929,19 @@ and~\ref{tab:nonisoopts}} % \end{macrocode} %\begin{macro}{\TrackLangQueryEnv} %\changes{1.3}{2016-10-07}{new} +%\changes{1.6}{2022-10-29}{changed \cs{x} to \cs{@tracklang@x}} % \begin{macrocode} \def\TrackLangQueryEnv{% \begingroup\endlinechar=-1\relax \everyeof{\noexpand}% - \edef\x{\endgroup\def\noexpand\TrackLangEnv{% - \@tracklang@input|"kpsewhich --var-value LC_ALL" }}\x + \edef\@tracklang@x{\endgroup\def\noexpand\TrackLangEnv{% + \@tracklang@input|"kpsewhich --var-value LC_ALL" }}\@tracklang@x \@tracklang@checklocale \ifx\TrackLangEnv\empty \begingroup\endlinechar=-1\relax \everyeof{\noexpand}% - \edef\x{\endgroup\def\noexpand\TrackLangEnv{% - \@tracklang@input|"kpsewhich --var-value LANG" }}\x + \edef\@tracklang@x{\endgroup\def\noexpand\TrackLangEnv{% + \@tracklang@input|"kpsewhich --var-value LANG" }}\@tracklang@x % \end{macrocode} %Not sure if a path is likely to occur with \app{kpsewhich} %but check for it just in case. @@ -4392,20 +974,20 @@ and~\ref{tab:nonisoopts}} \def\TrackLangQueryOtherEnv#1{% \begingroup\endlinechar=-1\relax \everyeof{\noexpand}% - \edef\x{\endgroup\def\noexpand\TrackLangEnv{% - \@tracklang@input|"kpsewhich --var-value LC_ALL" }}\x + \edef\@tracklang@x{\endgroup\def\noexpand\TrackLangEnv{% + \@tracklang@input|"kpsewhich --var-value LC_ALL" }}\@tracklang@x \@tracklang@checklocale \ifx\TrackLangEnv\empty \begingroup\endlinechar=-1\relax \everyeof{\noexpand}% - \edef\x{\endgroup\def\noexpand\TrackLangEnv{% - \@tracklang@input|"kpsewhich --var-value #1" }}\x + \edef\@tracklang@x{\endgroup\def\noexpand\TrackLangEnv{% + \@tracklang@input|"kpsewhich --var-value #1" }}\@tracklang@x \@tracklang@checklocale \ifx\TrackLangEnv\empty \begingroup\endlinechar=-1\relax \everyeof{\noexpand}% - \edef\x{\endgroup\def\noexpand\TrackLangEnv{% - \@tracklang@input|"kpsewhich --var-value LANG"}}\x + \edef\@tracklang@x{\endgroup\def\noexpand\TrackLangEnv{% + \@tracklang@input|"kpsewhich --var-value LANG"}}\@tracklang@x \@tracklang@checklocale \ifx\TrackLangEnv\empty % \end{macrocode} @@ -5231,6 +1813,7 @@ and~\ref{tab:nonisoopts}} %\end{macro} % %\begin{macro}{\ThreeLetterExtIsoLanguageCode} +%\changes{1.3}{2016-10-07}{new} % \begin{macrocode} \def\ThreeLetterExtIsoLanguageCode{639-3} % \end{macrocode} @@ -5688,7 +2271,7 @@ and~\ref{tab:nonisoopts}} %\begin{definition} %\cs{AddTrackedLanguageIsoCodes}\marg{language} %\end{definition} -%Adds the ISO 639-1, 639-2 and 639-3 ISO codes for the given language, +%Adds the 639-1, 639-2 and 639-3 ISO codes for the given language, %which must have previously been declared using %\cs{TrackLangNewLanguage}. % \begin{macrocode} @@ -12437,7 +9020,7 @@ and~\ref{tab:nonisoopts}} % Version info. % \begin{macrocode} \expandafter\def\csname ver@tracklang-region-codes.tex\endcsname{% - 2020/06/30 v1.5 (NLCT) Track Languages Regions}% + 2022/10/29 v1.6 (NLCT) Track Languages Regions}% % \end{macrocode} % %\begin{macro}{\TrackLangRegionMap} @@ -12830,7 +9413,7 @@ and~\ref{tab:nonisoopts}} %\changes{1.3}{2016-10-07}{added tracklang-scripts.sty} % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{tracklang-scripts}[2020/06/30 v1.5 (NLCT) Track +\ProvidesPackage{tracklang-scripts}[2022/10/29 v1.6 (NLCT) Track Language Scripts (LaTeX)] \RequirePackage{tracklang} \input{tracklang-scripts} @@ -12872,10 +9455,10 @@ Language Scripts (LaTeX)] % Version info. % \begin{macrocode} \expandafter\def\csname ver@tracklang-scripts.tex\endcsname{% - 2020/06/30 v1.5 (NLCT) Track Languages Scripts (Generic)}% + 2022/10/29 v1.6 (NLCT) Track Languages Scripts (Generic)}% % \end{macrocode} % -%\begin{macro}{\TrackLangScriptsMap} +%\begin{macro}{\TrackLangScriptMap} %\changes{1.3}{2016-10-07}{new} %\begin{definition} %\cs{TrackLangScriptMap}\marg{letter @@ -13193,7 +9776,6 @@ Language Scripts (LaTeX)] \TrackLangScriptMap{Tale}{353}{Tai Le}{LR}{}% \TrackLangScriptMap{Talu}{354}{New Tai Lue}{LR}{}% \TrackLangScriptMap{Taml}{346}{Tamil}{LR}{}% -\TrackLangScriptMap{Taml}{346}{Tamil}{LR}{}% \TrackLangScriptMap{Tang}{520}{Tangut}{LR}{}% \TrackLangScriptMap{Tavt}{359}{Tai Viet}{LR}{}% \TrackLangScriptMap{Telu}{340}{Telugu}{LR}{}% diff --git a/macros/generic/tracklang/tracklang.ins b/macros/generic/tracklang/tracklang.ins index 4b7bca1dde..42a18dc526 100644 --- a/macros/generic/tracklang/tracklang.ins +++ b/macros/generic/tracklang/tracklang.ins @@ -1,10 +1,10 @@ -% tracklang.ins generated using makedtx version 1.2 2020/6/30 11:55 +% tracklang.ins generated using makedtx version 1.2 2022/10/29 18:01 \input docstrip \preamble tracklang.dtx - Copyright 2020 Nicola Talbot + Copyright 2022 Nicola Talbot This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/generic/tracklang/tracklang.pdf b/macros/generic/tracklang/tracklang.pdf deleted file mode 100644 index a498800ab0..0000000000 Binary files a/macros/generic/tracklang/tracklang.pdf and /dev/null differ diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt index 2de15cc139..3d308fe078 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/ChangeLog.txt @@ -1,3 +1,8 @@ +2022-10-30, v0.3.6 + + * API changes: + - Add support for backrefs. + 2020-11-02, v0.3.5 * Changes to documentation: diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf index ddf54b7c8f..262076de2e 100644 Binary files a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf and b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector-ay.pdf differ diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf index 62da3d0589..4fe8a1d3bf 100644 Binary files a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf and b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.pdf differ diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex index d67aee127a..601cef3f8b 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/doc/caspervector.tex @@ -1,6 +1,6 @@ % Documentation for biblatex-caspervector % -% Copyright (c) 2012-2016,2018-2019 Casper Ti. Vector +% Copyright (c) 2012-2016,2018-2019,2022 Casper Ti. Vector % % This work may be distributed and/or modified under the conditions of the % LaTeX Project Public License, either version 1.3 of this license or (at @@ -22,7 +22,7 @@ \usepackage[margin = 2cm, centering, includefoot]{geometry} \usepackage[ backend = biber, style = caspervector, utf8, - giveninits = true, sortgiveninits = true + giveninits = true, sortgiveninits = true, backref = true ]{biblatex} \usepackage{iftex, fancyhdr, hyperref, enumitem, fancyvrb, hologo} @@ -48,13 +48,13 @@ \addbibresource{caspervector.bib} \begin{document} -\title{\textbf{biblatex 参考文献和引用样式:\texttt{caspervector} v0.3.5}} +\title{\textbf{biblatex 参考文献和引用样式:\texttt{caspervector} v0.3.6}} \author{% Casper Ti.\ Vector\thanks{\ % \href{mailto:CasperVector@gmail.com}{\texttt{CasperVector@gmail.com}}.% }% } -\date{2020/11/02} +\date{2022/10/30} \maketitle \section{引言} @@ -518,7 +518,9 @@ biblatex 3.0--3.3 的功能调整导致分类排序失效。% 这两种方法中更加推荐使用前者,因为前者只须手动实现出版年和期号的排版。 \begin{refcontext}[sorting = none] -\printbibliography[category = cited, heading = bibnumbered, title = {本文参考文献}] +\printbibliography[category = cited, heading = bibnumbered, title = {% + 本文参考文献(反向引用页码是设定 \texttt{backref = true} 产生的)% +}] \end{refcontext} \begin{refcontext}[sorting = ecnyt] \printbibliography[notcategory = cited, heading = bibnumbered, title = {% diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def index c23b4b1dad..4d326af7ce 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-base.def @@ -1,6 +1,6 @@ % Casper Ti. Vector's biblatex style % -% Copyright (c) 2012-2019 Casper Ti. Vector +% Copyright (c) 2012-2019,2022 Casper Ti. Vector % % This work may be distributed and/or modified under the conditions of the % LaTeX Project Public License, either version 1.3 of this license or (at @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{blx-caspervector-base.def}% - [2020/11/02 v0.3.5 Casper Ti. Vector's biblatex library] + [2022/10/30 v0.3.6 Casper Ti. Vector's biblatex library] \RequireBiber[3] \newtoggle{bbx:gbk} @@ -113,8 +113,9 @@ \renewcommand*{\finalnamedelim}{\ifcitation{\bbx@citebcomma}{\finallistdelim}} \renewcommand*{\multinamedelim}{\ifcitation{\bbx@citebcomma}{\multilistdelim}} \renewcommand*{\postnotedelim}{\bbx@citecomma} -\renewcommand*{\finentrypunct}% - {\iffieldundef{addendum}{\bbx@cepunct{\bbx@cnperiod}{.}}{}} +\renewcommand*{\finentrypunct}{\ifboolexpr{ + test {\iffieldundef{addendum}} and test {\iflistundef{pageref}} +}{\bbx@cepunct{\bbx@cnperiod}{.}}{}} \DefineBibliographyExtras{english}{% \renewcommand*{\finalandcomma}{}% } @@ -135,6 +136,7 @@ {\ifinteger{#1}{{\bbx@cnnr} {#1} {\bbx@cnedition}}{#1}}% {\ifinteger{#1}{\mkbibordedition{#1}~\bibstring{edition}}{#1\isdot}}% } +\DeclareFieldFormat*{mypageref}{\mkbibbrackets{\^{}\,#1}} \newcommand*{\bbx@print}[1]{\iffieldundef{#1}{}{\printfield{#1}}} \newbibmacro*{cntypedelim}[1]{\ifandothers{#1}{}{\printtext{\andothersdelim}}} \newbibmacro*{cein:}% @@ -243,6 +245,13 @@ \printurldate% }% } +\newbibmacro*{addendum+pageref}{% + \printfield{addendum}% + \iflistundef{pageref}{}{% + \bbx@cepunct{}{\setunit{\addspace}}% + \printtext[mypageref]{\printlist[pageref][-\value{listtotal}]{pageref}}% + }% +} \DeclareBibliographyDriver{book}{% \usebibmacro{bibindex}\usebibmacro{begentry}% @@ -256,7 +265,7 @@ \usebibmacro{location+publisher+date+note+pages}% \printunit{\bbx@ceperiod}\newblock \usebibmacro{eid+url+urldate}\printunit{\bbx@ceperiod}\newblock - \printfield{addendum}\usebibmacro{finentry}% + \usebibmacro{addendum+pageref}\usebibmacro{finentry}% } \DeclareBibliographyDriver{incollection}{% @@ -274,7 +283,7 @@ \usebibmacro{location+publisher+date+note+pages}% \printunit{\bbx@ceperiod}\newblock \usebibmacro{eid+url+urldate}\printunit{\bbx@ceperiod}\newblock - \printfield{addendum}\usebibmacro{finentry}% + \usebibmacro{addendum+pageref}\usebibmacro{finentry}% } \DeclareBibliographyDriver{periodical}{% @@ -290,7 +299,7 @@ \printlist{location}\setunit*{\bbx@cecolon}% \printlist{publisher}\printunit{\bbx@ceperiod}\newblock \usebibmacro{eid+url+urldate}\printunit{\bbx@ceperiod}\newblock - \printfield{addendum}\usebibmacro{finentry}% + \usebibmacro{addendum+pageref}\usebibmacro{finentry}% } \DeclareBibliographyDriver{article}{% @@ -304,7 +313,7 @@ \usebibmacro{date+volume+number+note+pages}% \printunit{\bbx@ceperiod}\newblock \usebibmacro{eid+url+urldate}\printunit{\bbx@ceperiod}\newblock - \printfield{addendum}\usebibmacro{finentry}% + \usebibmacro{addendum+pageref}\usebibmacro{finentry}% } \DeclareBibliographyDriver{patent}{% @@ -320,12 +329,12 @@ \usebibmacro{date}\setunit*{\bbx@cecomma}% \printfield{note}\printunit{\bbx@ceperiod}\newblock \usebibmacro{eid+url+urldate}\printunit{\bbx@ceperiod}\newblock - \printfield{addendum}\usebibmacro{finentry}% + \usebibmacro{addendum+pageref}\usebibmacro{finentry}% } \DeclareBibliographyDriver{customf}{% \usebibmacro{bibindex}\usebibmacro{begentry}% - \printfield{addendum}\usebibmacro{finentry}% + \usebibmacro{addendum+pageref}\usebibmacro{finentry}% } \DeclareBibliographyAlias{booklet}{book} diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def index 429ee5db47..83650ccb5d 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-gbk.def @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{blx-caspervector-gbk.def}% - [2020/11/02 v0.3.5 Chinese punctuations and captions in GBK] + [2022/10/30 v0.3.6 Chinese punctuations and captions in GBK] \newcommand*\bbx@cnldquot{} \newcommand*\bbx@cnrdquot{} diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def index 872d40567f..571291605d 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/blx-caspervector-utf8.def @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{blx-caspervector-utf8.def}% - [2020/11/02 v0.3.5 Chinese punctuations and captions in UTF-8] + [2022/10/30 v0.3.6 Chinese punctuations and captions in UTF-8] \newcommand*\bbx@cnldquot{“} \newcommand*\bbx@cnrdquot{”} diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx index 139b83551f..690d19fe9d 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.bbx @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{caspervector-ay.bbx}% - [2020/11/02 v0.3.5 Casper Ti. Vector's author-year biblatex bibstyle] + [2022/10/30 v0.3.6 Casper Ti. Vector's author-year biblatex bibstyle] \RequireBibliographyStyle{authoryear-comp} \input{blx-caspervector-base.def} diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx index 12133338a9..a58fecebe3 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector-ay.cbx @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{caspervector-ay.cbx}% - [2020/11/02 v0.3.5 Casper Ti. Vector's author-year biblatex citestyle] + [2022/10/30 v0.3.6 Casper Ti. Vector's author-year biblatex citestyle] \RequireCitationStyle{authoryear-comp} \renewcommand*{\compcitedelim}{\bbx@citebcomma} diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx index 80682d4e05..9647c575da 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.bbx @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{caspervector.bbx}% - [2020/11/02 v0.3.5 Casper Ti. Vector's numeric biblatex bibstyle] + [2022/10/30 v0.3.6 Casper Ti. Vector's numeric biblatex bibstyle] \RequireBibliographyStyle{numeric-comp} \input{blx-caspervector-base.def} diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx index 5a3ac392cf..da4f7b5a70 100644 --- a/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx +++ b/macros/latex/contrib/biblatex-contrib/biblatex-caspervector/tex/caspervector.cbx @@ -23,7 +23,7 @@ % blx-caspervector-utf8.def \ProvidesFile{caspervector.cbx}% - [2020/11/02 v0.3.5 Casper Ti. Vector's numeric biblatex citestyle] + [2022/10/30 v0.3.6 Casper Ti. Vector's numeric biblatex citestyle] \RequireCitationStyle{numeric-comp} \ExecuteBibliographyOptions{autocite = superscript} diff --git a/macros/latex/contrib/eolang/DEPENDS.txt b/macros/latex/contrib/eolang/DEPENDS.txt index 11d8637225..d3abb692d7 100644 --- a/macros/latex/contrib/eolang/DEPENDS.txt +++ b/macros/latex/contrib/eolang/DEPENDS.txt @@ -9,3 +9,4 @@ hard pdftexcmds hard ifluatex hard ifxetex hard adjustbox +hard hyperref \ No newline at end of file diff --git a/macros/latex/contrib/eolang/eolang.dtx b/macros/latex/contrib/eolang/eolang.dtx index 65e87c220a..c7bad93739 100644 --- a/macros/latex/contrib/eolang/eolang.dtx +++ b/macros/latex/contrib/eolang/eolang.dtx @@ -50,7 +50,7 @@ %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{eolang} %<*package> -[2022-10-29 0.2.0 Formulas and Graphs for EO Programming Language] +[2022-10-30 0.3.0 Formulas and Graphs for EO Programming Language] % %<*driver> \documentclass{ltxdoc} @@ -126,6 +126,8 @@ % (|\varnothing|), % \item ``|->|'' maps to ``$\mapsto$'' % (|\mapsto|), +% \item ``|~>|'' maps to ``$\phiWave$'' +% (|\phiWave|), % \item ``|!->|'' maps to ``$\phiConst$'' % (|\phiConst|), % \item ``|..>|'' maps to ``$\phiDotted$'' @@ -153,9 +155,9 @@ % \pagestyle{empty} % \usepackage{eolang} % \begin{document} -% A simple object \\ +% A simple object % \phiq{x -> [[@ -> y]]} \\ -% is a decorator of \\ +% is a decorator of % the data object \\ % \phiq{y -> [[\Delta ..> 42]]}. % \end{document} @@ -267,6 +269,27 @@ % \end{document} % \end{docshot} +% This is how you can use |\dfrac| from |amsmath| for large inference rules, +% with the help of |\begin{split}| and |\end{split}|: +% \begin{docshot} +% \documentclass{article} +% \usepackage{amsmath} +% \usepackage{eolang} +% \pagestyle{empty} +% \begin{document} +% \begin{phiquation*} +% \dfrac{\begin{split} +% x->[[@->y, z->42, +% \alpha_0->?, \alpha_1->42]] +% \end{split}}{\begin{split} +% x->[[@->y, z->?, f ~> |pi|( +% \alpha_0->[[ \psi !-> |hello|(12) ]], +% \alpha_1->42)]] +% \end{split}}\text{R2}. +% \end{phiquation*} +% \end{document} +% \end{docshot} + % The |phiquation| environment may be used together with \href{https://ctan.org/pkg/acmart}{acmart}: % \begin{docshot} % \documentclass{acmart} @@ -346,12 +369,22 @@ \iexec[null]{mkdir -p "\eolang@tmpdir/\jobname"}% % \end{macrocode} +% \begin{macro}{\eolang@lineno} +% \changes{0.3.0}{2022/10/30}{New counter for protecting lineno.} +% Then, we define an internal counter to protect line number from changing: +% \begin{macrocode} +\makeatletter\newcounter{eolang@lineno}\makeatother +% \end{macrocode} +% \end{macro} + % \begin{macro}{\eolang@mdfive} % \changes{0.1.0}{2022/10/26}{New supplementary command added to calculate MD5 sum of a file.} % Then, we define a command for MD5 hash calculating of a file: % \begin{macrocode} \RequirePackage{pdftexcmds} -\makeatletter\newcommand\eolang@mdfive[1]{\pdf@filemdfivesum{#1}}\makeatother +\makeatletter +\newcommand\eolang@mdfive[1]{\pdf@filemdfivesum{#1}} +\makeatother % \end{macrocode} % \end{macro} @@ -361,7 +394,9 @@ % \changes{0.0.2}{2022/10/21}{Parsing of symbols ``@,'' ``\^{},'' and ``\&'' enabled (varphi, rho, and sigma)} % \changes{0.1.0}{2022/10/26}{A new Perl script "eolang-phi.pl" added for parsing of phi expressions.} % \changes{0.2.0}{2022/10/29}{Numbers automatically render as "texttt". No need to use vertical bars around them anymore.} -% Then, we create a Perl script for |phiquation| processing: +% \changes{0.3.0}{2022/10/30}{New arrow added, that looks like "leadsto".} +% Then, we create a Perl script for |phiquation| processing using |VerbatimOut| from +% \href{https://ctan.org/pkg/fancyvrb}{fancyvrb}: % \begin{macrocode} \makeatletter \begin{VerbatimOut}{\eolang@tmpdir/eolang-phi.pl} @@ -400,12 +435,15 @@ $tex =~ s/\$/\\xi{}/g; $tex =~ s/-([a-z]+)>/\\mathrel{\\xrightarrow{\\text{\\sffamily\\scshape \1}}}/g; $tex =~ s/!->/\\mathrel{\\phiConst}/g; $tex =~ s/->/\\mathrel{\\mapsto}/g; +$tex =~ s/~>/\\mathrel{\\phiWave}/g; $tex =~ s/:=/\\mathrel{\\vDash}/g; $tex =~ s/..>/\\mathrel{\\phiDotted}/g; -$tex =~ s/\|([^\|]+)\|/\\texttt{\1}{}/g; +$tex =~ s/\|([^\|]+)\|/\\textnormal{\\texttt{\1}}{}/g; $tex =~ s/\[\[/\\llbracket\\mathrel{}/g; $tex =~ s/\]\]/\\mathrel{}\\rrbracket{}/g; if ($env ne 'phiq') { + $tex =~ s/\\begin\{split\}\n/\\begin{split}&/g; + $tex =~ s/\n\s*\\end\{split\}/\\end{split}/g; $tex =~ s/\n\n/\\\\&/g; $tex =~ s/\n/\\\\[-4pt]&/g; $tex =~ s/([^&\s])\s{2}([^\s])/\1 \2/g; @@ -446,13 +484,18 @@ print '\endinput', "\n"; perl "\eolang@tmpdir/eolang-phi.pl" '#1' "\eolang@tmpdir/\jobname/\hash.tex"}% + \setcounter{FancyVerbLine}{\value{eolang@lineno}}% } \newenvironment{phiquation*}% -{\VerbatimEnvironment\begin{VerbatimOut} +{\VerbatimEnvironment% +\setcounter{eolang@lineno}{\value{FancyVerbLine}}% +\begin{VerbatimOut} {\eolang@tmpdir/\jobname/phiquation.tex}} {\end{VerbatimOut}\eolang@process{equation*}} \newenvironment{phiquation}% -{\VerbatimEnvironment\begin{VerbatimOut} +{\VerbatimEnvironment% +\setcounter{eolang@lineno}{\value{FancyVerbLine}}% +\begin{VerbatimOut} {\eolang@tmpdir/\jobname/phiquation.tex}} {\end{VerbatimOut}\eolang@process{equation}} \makeatother @@ -460,12 +503,12 @@ print '\endinput', "\n"; % \end{macro} % \begin{macro}{\phiq} -% \changes{0.0.2}{2022/10/21}{Parsing of additional symbols enabled} +% \changes{0.0.2}{2022/10/21}{Parsing of additional symbols enabled.} % Then, we define |\phiq| command: % \begin{macrocode} -\makeatletter\newcommand\phiq[1]{ +\makeatletter\newcommand\phiq[1]{% \iexec[trace,quiet,stdout=\eolang@tmpdir/\jobname/phiq.tex]{ - /bin/echo '\detokenize{#1}'} + /bin/echo '\detokenize{#1}'}% \def\hash{\eolang@mdfive {\eolang@tmpdir/\jobname/phiq.tex}}% \iexec[null]{cp "\eolang@tmpdir/\jobname/phiq.tex" @@ -481,7 +524,8 @@ print '\endinput', "\n"; % \changes{0.0.2}{2022/10/24}{The Perl file now has a fixed name, which doesn't depend on the name of the TeX job. This file may be shared among jobs, no need to make it uniquely named.} % \changes{0.1.0}{2022/10/26}{There are two Perl scripts now: one for phiquation, another one for sodg.} % \changes{0.2.0}{2022/10/28}{The content of "atom" and "data" boxes is parsed automatically as formulas and numbers, respectively.} -% Then, we create a Perl script for |sodg| graphs processing: +% Then, we create a Perl script for |sodg| graphs processing using |VerbatimOut| from +% \href{https://ctan.org/pkg/fancyvrb}{fancyvrb}: % \begin{macrocode} \makeatletter \begin{VerbatimOut}{\eolang@tmpdir/eolang-sodg.pl} @@ -498,7 +542,7 @@ if (index($tex, "\t") > 0) { $tex =~ s/^\s+|\s+$//g; $tex =~ s/(\\[a-zA-Z]+)\s+/\1/g; $tex =~ s/\n\s+/\n/g; -$tex =~ s/\|([^\|]+)\|/\\texttt{\1}/g; +$tex =~ s/\|([^\|]+)\|/\\textnormal{\\texttt{\1}}/g; my @cmds = split (/\n/g, $tex); foreach my $t (@cmds) { print '% ', $t, "\n"; @@ -528,7 +572,7 @@ foreach my $c (@cmds) { if (not $opts{'data'} eq '') { my $d = $opts{'data'}; if (index($d, '|') == -1) { - $d = '\texttt{' . $d . '}'; + $d = '\textnormal{\texttt{' . $d . '}}'; } $opts{'box'} = $d; } @@ -596,6 +640,14 @@ print '\end{phicture}', "\n", '\endinput'; % \end{macrocode} % \end{macro} +% \begin{macro}{FancyVerbLine} +% Then, we reset the counter for \href{https://ctan.org/pkg/fancyvrb}{fancyvrb}, so that +% it starts counting lines from zero when the document starts rendering: +% \begin{macrocode} +\setcounter{FancyVerbLine}{0} +% \end{macrocode} +% \end{macro} + % \begin{macro}{tikz} % Then, we include |tikz| package and its libraries: % \begin{macrocode} @@ -648,7 +700,9 @@ print '\end{phicture}', "\n", '\endinput'; % \href{https://tex.stackexchange.com/questions/661056}{here}: % \begin{macrocode} \makeatletter\newenvironment{sodg}% -{\VerbatimEnvironment\begin{VerbatimOut} +{\VerbatimEnvironment% +\setcounter{eolang@lineno}{\value{FancyVerbLine}}% +\begin{VerbatimOut} {\eolang@tmpdir/\jobname/sodg.tex}} {\end{VerbatimOut}% \def\hash{\eolang@mdfive @@ -658,6 +712,7 @@ print '\end{phicture}', "\n", '\endinput'; \iexec[trace,stdout=\eolang@tmpdir/\jobname/\hash-post.tex]{ perl "\eolang@tmpdir/eolang-sodg.pl" "\eolang@tmpdir/\jobname/\hash.tex"}% + \setcounter{FancyVerbLine}{\value{eolang@lineno}}% }\makeatother % \end{macrocode} % \end{macro} @@ -682,11 +737,12 @@ print '\end{phicture}', "\n", '\endinput'; % \changes{0.1.0}{2022/10/25}{New command "phic" prints the name of $\varphi$-calculus in both % normal and anonymous mode of "acmart"} % \begin{macrocode} +\RequirePackage{hyperref} \newcommand\phic{% \ifdefined\anon% - \anon[$\alpha$-calculus]{$\varphi$-calculus}% + \anon[\texorpdfstring{$\alpha$}{a}-calculus]{\texorpdfstring{$\varphi$}{phi}-calculus}% \else% - $\varphi$-calculus% + \texorpdfstring{$\varphi$}{phi}-calculus% \fi% } % \end{macrocode} @@ -716,6 +772,16 @@ print '\end{phicture}', "\n", '\endinput'; % \end{macrocode} % \end{macro} +% \begin{macro}{\phiWave} +% \changes{0.3.0}{2022/10/30}{New command "phiWave" added to denote a link to a multi-layer attribute.} +% Then, we define a command to render an arrow for a multi-layer attribute, +% as suggested \href{https://tex.stackexchange.com/questions/198755}{here}: +% \begin{macrocode} +\newcommand\phiWave{% + \mapstochar\mathrel{\mspace{0.45mu}}\leadsto} +% \end{macrocode} +% \end{macro} + % \begin{macro}{\phiDotted} % \changes{0.1.0}{2022/10/27}{New command "phiDotted" added to denote a link to a special attribute.} % Then, we define a command to render an arrow for a special attribute, diff --git a/macros/latex/contrib/eolang/eolang.pdf b/macros/latex/contrib/eolang/eolang.pdf index e2b1d20e83..28befcb7bf 100644 Binary files a/macros/latex/contrib/eolang/eolang.pdf and b/macros/latex/contrib/eolang/eolang.pdf differ diff --git a/macros/latex/contrib/ffcode/DEPENDS.txt b/macros/latex/contrib/ffcode/DEPENDS.txt index 52a46fbc48..935840f850 100644 --- a/macros/latex/contrib/ffcode/DEPENDS.txt +++ b/macros/latex/contrib/ffcode/DEPENDS.txt @@ -1,5 +1,3 @@ hard xkeyval hard minted hard tcolorbox -hard pgf -hard environ diff --git a/macros/latex/contrib/ffcode/README.md b/macros/latex/contrib/ffcode/README.md index fe0332ddfe..f62fa0aa99 100644 --- a/macros/latex/contrib/ffcode/README.md +++ b/macros/latex/contrib/ffcode/README.md @@ -23,11 +23,10 @@ void r() { \end{document} ``` -The full example and all commands are available in the -[`ffcode.tex`](https://github.com/yegor256/ffcode/blob/master/ffcode.tex) file. +Otherwise, you can download [`ffcode.sty`](https://raw.githubusercontent.com/yegor256/ffcode/gh-pages/ffcode/ffcode.sty) and add to your project. -If you want to contribute yourself, make a fork, then create a branch, -then run `make` in the root directory. +If you want to contribute yourself, make a fork, then create a branch, +then run `l3build ctan` in the root directory. It should compile everything without errors. If not, submit an issue and wait. -Otherwise, make your changes and then run `make` again. If the build is +Otherwise, make your changes and then run `l3build ctan` again. If the build is still clean, submit a pull request. diff --git a/macros/latex/contrib/ffcode/ffcode.dtx b/macros/latex/contrib/ffcode/ffcode.dtx index c6d717c7b5..e3c430c8de 100644 --- a/macros/latex/contrib/ffcode/ffcode.dtx +++ b/macros/latex/contrib/ffcode/ffcode.dtx @@ -50,18 +50,20 @@ %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{ffcode} %<*package> -[03.10.2022 0.5.0 Fixed Font Code] +[2022-10-30 0.5.1 Fixed Font Code] % %<*driver> \documentclass{ltxdoc} \usepackage[T1]{fontenc} \usepackage[tt=false,type1=true]{libertine} \usepackage{microtype} +\AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}} \usepackage{href-ul} \usepackage{ffcode} \usepackage{amsmath} \usepackage{multicol} \usepackage{xcolor} +\usepackage[dtx,runs=2]{docshots} \PageIndex \EnableCrossrefs \CodelineIndex @@ -86,86 +88,51 @@ % and make sure it looks nice. Install it from CTAN and then % use like this (pay attention to |\ff| command % and |ffcode| environment): -% \begin{multicols}{2} -% \setlength{\parskip}{0pt} -% \raggedcolumns -%\iffalse -%<*verb> -%\fi -\begin{verbatim} -\documentclass{article} -\usepackage{ffcode} -\begin{document} -The function \ff{fibo()} -is recursive: -\begin{ffcode} -int fibo(int n) { - if (n < 2) { - return n; |$\label{ln:ret}$| - } - return fibo(n-1)+fibo(n-2); -} -\end{ffcode} -The line no.~\ref{ln:ret} -terminates it. -\end{document} -\end{verbatim} -%\iffalse -% -%\fi -% -% \columnbreak -% -% The function \ff{fibo()} is recursive: -% -%\iffalse -%<*verb> -%\fi -\begin{ffcode} -int fibo(int n) { - if (n < 2) { - return n; |$\label{ln:ret}$| - } - return fibo(n-1)+fibo(n-2); -} -\end{ffcode} -%\iffalse -% -%\fi -% -% The line no.~\ref{ln:ret} terminates it. -% \end{multicols} +% \begin{docshot} +% \documentclass{article} +% \usepackage{ffcode} +% \pagestyle{empty} +% \begin{document} +% The function \ff{fibo()} +% is recursive: +% \begin{ffcode} +% int fibo(int n) { +% if (n < 2) { +% return n; |$\label{ln:ret}$| +% } +% return fibo(n-1)+fibo(n-2); +% } +% \end{ffcode} +% The line no.~\ref{ln:ret} +% terminates it. +% \end{document} +% \end{docshot} % \section{Package Options} -% \begin{macro}{nopygments} +% \DescribeMacro{nopygments} % You have to run |pdflatex| with |--shell-escape| flag % in order to let |minted| (the package we use) to run Pygments % and format the code. If you don't want this to happen, % just use |nopygments| option. -% \end{macro} -% \begin{macro}{noframes} +% \DescribeMacro{noframes} % If you want to omit the light gray frames around |\ff| % texts, use the package option |noframes|. -% \end{macro} -% \begin{macro}{nobars} +% \DescribeMacro{nobars} % To omit the vertical gray bar at the left side of each snippet, % use |nobars| option of the package. -% \end{macro} -% \begin{macro}{nonumbers} +% \DescribeMacro{nonumbers} % To omit the line numbers, use |nonumbers| option of the package. -% \end{macro} -% \begin{macro}{nocn} +% \DescribeMacro{nocn} % By default, the numbering is continuous: line numbers start at the % first snippet and increment until the end of the document. If you % want them to start from one at each snippet, use |nocn| % (stands for ``no continuous numbering'') % option of the package. -% \end{macro} % \section{Typesetting} @@ -178,86 +145,40 @@ int fibo(int n) { % The command |\ff| behaves differently in math mode --- it doesn't % add gray frames: -% \begin{multicols}{2} -% \setlength{\parskip}{0pt} -% \raggedcolumns -%\iffalse -%<*verb> -%\fi -\begin{verbatim} -\documentclass{article} -\usepackage{ffcode} -\begin{document} -\begin{equation} -x = \int_\ff{home}^N f(x). -\end{equation} -\end{document} -\end{verbatim} -%\iffalse -% -%\fi -% -% \columnbreak -% -%\iffalse -%<*verb> -%\fi -% \begin{equation} +% \begin{docshot} +% \documentclass{article} +% \usepackage{ffcode} +% \usepackage{mathtools} +% \pagestyle{empty} +% \begin{document} +% \begin{equation*} % x = \int_\ff{home}^N f(x). -% \end{equation} -%\iffalse -% -%\fi -% \end{multicols} +% \end{equation*} +% \end{document} +% \end{docshot} % \section{Line Highlighting} % You can highlight some lines in your |ffcode| environment, % or can use any other additional configuration parameters from % |minted| package: - -% \begin{multicols}{2} -% \setlength{\parskip}{0pt} -% \raggedcolumns -%\iffalse -%<*verb> -%\fi -\begin{verbatim} -\documentclass{article} -\usepackage{ffcode} -\begin{document} -\begin{ffcode*} - {highlightlines={1,4-5}} -while (true) { - print("Hello!") - print("Enter your name:") - scan(x) - print("You name is " + x) -} -\end{ffcode*} -\end{document} -\end{verbatim} -%\iffalse -% -%\fi -% -% \columnbreak -% -%\iffalse -%<*verb> -%\fi -\begin{ffcode*}{highlightlines={7,10-11}} -while (true) { - print("Hello!") - print("Enter your name:") - scan(x) - print("You name is " + x) -} -\end{ffcode*} -%\iffalse -% -%\fi -% \end{multicols} +% \begin{docshot} +% \documentclass{article} +% \usepackage[paperwidth=3in]{geometry} +% \usepackage{ffcode} +% \pagestyle{empty} +% \begin{document} +% \begin{ffcode*} +% {highlightlines={1,4-5}} +% while (true) { +% print("Hello!") +% print("Enter your name:") +% scan(x) +% print("You name is " + x) +% } +% \end{ffcode*} +% \end{document} +% \end{docshot} % Using this second argument of |ffcode*| (with the trailing asterisk), % you can provide any other options from |minted| package to the @@ -266,8 +187,7 @@ while (true) { % \StopEventually{} % \section{Implementation} - -% \changes{v0.2.0}{2021/07/10}{Initial version} +% \changes{v0.1.0}{2021/06/10}{Initial version} % First, we parse package options: % \begin{macrocode} @@ -276,10 +196,14 @@ while (true) { \DeclareOptionX{nopygments}{\PassOptionsToPackage{draft=true}{minted}} \newif\ifff@noframes \DeclareOptionX{noframes}{\ff@noframestrue} +% \changes{v0.4.0}{2022/01/09}{Package option "nobars" added.} \newif\ifff@nobars \DeclareOptionX{nobars}{\ff@nobarstrue} +% \changes{v0.2.0}{2021/06/13}{Package options "nonumbers" +% and "noframes" added.} \newif\ifff@nonumbers \DeclareOptionX{nonumbers}{\ff@nonumberstrue} +% \changes{v0.3.0}{2021/09/07}{Package option "nocn" added.} \newif\ifff@nocn \DeclareOptionX{nocn}{\ff@nocntrue} \ProcessOptionsX\relax @@ -306,7 +230,7 @@ while (true) { framerule=1pt,rulecolor=gray,frame=leftline} \fi \else - \renewcommand{\theFancyVerbLine}{\textcolor{gray} + \renewcommand{\theFancyVerbLine}{\textcolor{gray}% {\tiny\oldstylenums{\ttfamily\arabic{FancyVerbLine}}}} \ifff@nocn \ifff@nobars @@ -337,10 +261,11 @@ while (true) { % \begin{macro}{\ff@print} % Then, we define supplementary commands |\ff@print| and |\ff@printx|: +% \changes{v0.5.1}{2022/10/30}{Now, the command "ff" ignores italic and bold and always prints "texttt" as it should be.} % \begin{macrocode} \makeatletter \newcommand\ff@print{\begingroup\obeyspaces\ff@printx} -\newcommand\ff@printx[1]{\texttt{#1}\endgroup} +\newcommand\ff@printx[1]{\textnormal{\texttt{#1}}\endgroup} \makeatother % \end{macrocode} % \end{macro} @@ -368,7 +293,7 @@ while (true) { \newcommand\ff[1]{\relax\ifmmode% {\ff@rule\ff@print{#1}}% \else% - {\ff@box{\ff@rule\ff@print{#1}}} + {\ff@box{\ff@rule\ff@print{#1}}}% \fi} \fi\makeatother % \end{macrocode} diff --git a/macros/latex/contrib/ffcode/ffcode.ins b/macros/latex/contrib/ffcode/ffcode.ins index 758b0a2a81..9e7c56593e 100644 --- a/macros/latex/contrib/ffcode/ffcode.ins +++ b/macros/latex/contrib/ffcode/ffcode.ins @@ -48,8 +48,8 @@ SOFTWARE. \endpreamble \generate{\file{ffcode.sty}{\from{ffcode.dtx}{package}}} \obeyspaces -\Msg{*** To finish the installation you have to move the ".sty"} -\Msg{*** file into a directory searched by TeX. To produce the} -\Msg{*** documentation run the file ".dtx" through LaTeX. If any} -\Msg{*** questions, submit a new GitHub issue.} +\Msg{To finish the installation you have to move the ".sty"} +\Msg{file into a directory searched by TeX. To produce the} +\Msg{documentation run the file ".dtx" through LaTeX. If any} +\Msg{questions, submit a new GitHub issue.} \endbatchfile diff --git a/macros/latex/contrib/ffcode/ffcode.pdf b/macros/latex/contrib/ffcode/ffcode.pdf index 1533df9d95..a24f23e4b0 100644 Binary files a/macros/latex/contrib/ffcode/ffcode.pdf and b/macros/latex/contrib/ffcode/ffcode.pdf differ diff --git a/macros/latex/contrib/pkuthss/doc/example.pdf b/macros/latex/contrib/pkuthss/doc/example.pdf index a435dc0541..18b82d1f72 100644 Binary files a/macros/latex/contrib/pkuthss/doc/example.pdf and b/macros/latex/contrib/pkuthss/doc/example.pdf differ diff --git a/macros/latex/contrib/pkuthss/doc/example/spine.tex b/macros/latex/contrib/pkuthss/doc/example/spine.tex index 005e4c3950..8bcb77dd58 100644 --- a/macros/latex/contrib/pkuthss/doc/example/spine.tex +++ b/macros/latex/contrib/pkuthss/doc/example/spine.tex @@ -1,10 +1,11 @@ -% Copyright (c) 2018-2019 Casper Ti. Vector +% Copyright (c) 2018-2019,2022 Casper Ti. Vector % Public domain. \documentclass[UTF8, zihao = -4]{ctexart} \usepackage{calc, geometry, graphicx} -\usepackage[defaultsups]{newtxtext} -\usepackage[cmintegrals, varg]{newtxmath} +% 如须用 xelatex 编译,请参考 pkuthss.cls 修改字体设置。 +\usepackage{textcomp, mathptmx} +\usepackage[scaled = 0.95]{helvet} \pagestyle{empty} \newlength{\colpad} \newcommand{\colwidth}{0.99\ccwd} @@ -37,7 +38,7 @@ \hspace{\colpad} \begin{minipage}[b][\textheight][b]{\miniwidth} % thesis.pdf 应事先编译好,此处会自动提取其首页。 - % 因为要插入 pdf 图片,本文档应用 pdflatex 或 xelatex 编译。 + % 因为要插入 pdf 图片,本文档应用 pdflatex 编译。 \includegraphics[height = \textheight, page = 1]{thesis} \end{minipage} \end{document} diff --git a/macros/latex/contrib/pkuthss/doc/example/thesis.tex b/macros/latex/contrib/pkuthss/doc/example/thesis.tex index dbfd37994d..f12e379aff 100644 --- a/macros/latex/contrib/pkuthss/doc/example/thesis.tex +++ b/macros/latex/contrib/pkuthss/doc/example/thesis.tex @@ -1,5 +1,5 @@ % Copyright (c) 2008-2009 solvethis -% Copyright (c) 2010-2016,2018-2019,2021 Casper Ti. Vector +% Copyright (c) 2010-2016,2018-2019,2021-2022 Casper Ti. Vector % Copyright (c) 2021 Kurapica % Public domain. % @@ -71,7 +71,7 @@ 生成的 PDF 文件中标记链接的彩色框不会出现在打印版论文中。 如仍须去掉,可在 \texttt{thesis.tex} 导言区加入 - \texttt{\string\hypersetup\{hidelinks\}}。 + \texttt{\string\hypersetup\string{hidelinks\string}}。 若要避免章末空白页,请在调用 pkuthss 文档类时加入 \texttt{openany} 选项。 diff --git a/macros/latex/contrib/pkuthss/doc/pkuthss.pdf b/macros/latex/contrib/pkuthss/doc/pkuthss.pdf index 7e96dbb735..d81143c642 100644 Binary files a/macros/latex/contrib/pkuthss/doc/pkuthss.pdf and b/macros/latex/contrib/pkuthss/doc/pkuthss.pdf differ diff --git a/macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt b/macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt index 665120151a..89e7fcb899 100644 --- a/macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt +++ b/macros/latex/contrib/pkuthss/doc/readme/ChangeLog.txt @@ -1,3 +1,12 @@ +2022-10-30, v1.9.3 + + * Changes to package code: + - Get rid of newtx completely (thank @CastleStar14654). + - pkuthss.cls: fix scrextend, better footnotes (thank @CastleStar14654). + + * Misc: + - Minor fixes and cosmetics. + 2022-05-04, v1.9.2 * Changes to package code: diff --git a/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex b/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex index 4b5073b08a..de7aa296ee 100644 --- a/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex +++ b/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap2.tex @@ -308,8 +308,9 @@ pkuthss 文档模版使用作者编写的 biblatex\cupercite{biblatex} 样式% \begin{itemize} \item 启用 \verb|pkufont| 选项时会调用 unicode-math \cupercite{unicode-math} 宏包(\hologo{XeLaTeX} 编译)或 - newtxtext/newtxmath\cupercite{newtx} 宏包(非 \hologo{XeLaTeX} - 编译),否则会调用 latexsym\cupercite{latexsym} 宏包。 + mathptmx/helvet\cupercite{psnfss} 和 textcomp 宏包(非 + \hologo{XeLaTeX} 编译),此外在非 \hologo{XeLaTeX} 编译或不启用 + \verb|pkufont| 选项时均会调用 latexsym\cupercite{latexsym} 宏包。 \item 启用 \verb|pkufoot| 选项时会调用 tikz\cupercite{tikz} 和 scrextend\cupercite{scrextend} 宏包。 \item 启用 \verb|pkuspace| 选项时会调用 diff --git a/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex b/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex index 7dcf4ff855..c39ea13268 100644 --- a/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex +++ b/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-chap3.tex @@ -1,7 +1,7 @@ % Documentation for pkuthss. % % Copyright (c) 2008-2009 solvethis -% Copyright (c) 2010-2019,2021 Casper Ti. Vector +% Copyright (c) 2010-2019,2021-2022 Casper Ti. Vector % % This work may be distributed and/or modified under the conditions of the % LaTeX Project Public License, either version 1.3 of this license or (at @@ -89,21 +89,6 @@ data source .../par-xxxxxxxx/cache-xxxxxxxx/ 遇到这种情况时,删除掉上述临时目录及其所有内容, 再重新运行 biber 通常便可解决问题。 -就目前而言,amsthm\cupercite{amsthm} 宏包在后于 newtxmath\cupercite{newtx} -宏包被调用时会导致以下的错误: -\begin{Verbatim} -! LaTeX Error: Command \openbox already defined. - Or name \end... illegal, see p.192 of the manual. -\end{Verbatim} -解决此问题的最简单方法是在通过 -\begin{Verbatim} -\usepackage{amsthm} -\end{Verbatim} -调用 amsthm 宏包之前加入以下命令: -\begin{Verbatim} -\let\openbox\relax -\end{Verbatim} - \section{文档格式可能存在的问题} 目前在 \hologo{LaTeX} 中似乎没有一个可以很好地替代其它各类似宏包的 diff --git a/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex b/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex index 396f9fe6c3..70f4bf5360 100644 --- a/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex +++ b/macros/latex/contrib/pkuthss/doc/readme/chap/pkuthss-intro.tex @@ -1,7 +1,7 @@ % Documentation for pkuthss. % % Copyright (c) 2008-2009 solvethis -% Copyright (c) 2010-2012,2014-2015,2018-2019 Casper Ti. Vector +% Copyright (c) 2010-2012,2014-2015,2018-2019,2022 Casper Ti. Vector % % This work may be distributed and/or modified under the conditions of the % LaTeX Project Public License, either version 1.3 of this license or (at @@ -63,6 +63,6 @@ pkuthss 文档模版现在的维护者是 Casper Ti. Vector\footnote% {\href{mailto:CasperVector@gmail.com}{\texttt{CasperVector@gmail.com}}.}。% pkuthss 文档模版目前托管在 Gitea 上, 其项目主页是:\\ -\hspace*{\parindent}\url{https://gitea.com/CasperVector/pkuthss} +\hspace*{\parindent}\url{https://gitea.com/CasperVector/pkuthss}。 % vim:ts=4:sw=4 diff --git a/macros/latex/contrib/pkuthss/doc/readme/ctex-fontset-pkuthss.def b/macros/latex/contrib/pkuthss/doc/readme/ctex-fontset-pkuthss.def new file mode 120000 index 0000000000..bd7e3e362f --- /dev/null +++ b/macros/latex/contrib/pkuthss/doc/readme/ctex-fontset-pkuthss.def @@ -0,0 +1 @@ +../example/ctex-fontset-pkuthss.def \ No newline at end of file diff --git a/macros/latex/contrib/pkuthss/doc/readme/ctexopts.cfg b/macros/latex/contrib/pkuthss/doc/readme/ctexopts.cfg new file mode 120000 index 0000000000..7fabe3504d --- /dev/null +++ b/macros/latex/contrib/pkuthss/doc/readme/ctexopts.cfg @@ -0,0 +1 @@ +../example/ctexopts.cfg \ No newline at end of file diff --git a/macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib b/macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib index 9e1770056e..6f7e3d323c 100644 --- a/macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib +++ b/macros/latex/contrib/pkuthss/doc/readme/pkuthss.bib @@ -138,13 +138,13 @@ } @online{graphicx, - author = {Carlisle, D. P.}, - title = {Packages in the `graphics' bundle}, + author = {Carlisle, D. P. and Rahtz, S. P. Q.}, + title = {The graphicx package}, edition = {Ver.~1.2d}, type = {M/OL}, date = {2021-09-16}, url = {https://ctan.org/pkg/graphicx}, - urldate = {2022-05-04}, + urldate = {2022-05-06}, language = {english}, } @@ -170,14 +170,14 @@ language = {english}, } -@online{newtx, - author = {Sharpe, Michael}, - title = {New TX font package}, - edition = {Ver.~1.71}, +@online{psnfss, + author = {Schmidt, Walter}, + title = {Using common PostScript fonts with \hologo{LaTeX}}, + edition = {Ver.~9.3}, type = {M/OL}, - date = {2022-03-02}, - url = {https://ctan.org/pkg/newtx}, - urldate = {2022-05-04}, + date = {2020-03-25}, + url = {https://ctan.org/pkg/psnfss}, + urldate = {2022-05-06}, language = {english}, } diff --git a/macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex b/macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex index 0bccb1a29b..2def8ad843 100644 --- a/macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex +++ b/macros/latex/contrib/pkuthss/doc/readme/pkuthss.tex @@ -51,7 +51,7 @@ } \newif\ifblind\blindfalse -\newcommand*{\docversion}{v1.9.2} +\newcommand*{\docversion}{v1.9.3} \pkuthssinfo{ cthesisname = {本科生毕业论文}, ethesisname = {Undergraduate Thesis}, ctitle = {北京大学学位论文模版{\thssnl}pkuthss \docversion}, @@ -60,7 +60,7 @@ \texorpdfstring{\thssnl}{: }pkuthss \docversion% }, cauthor = {盖茨波·钛·维克托}, eauthor = {Casper Ti.\ Vector}, - date = {\zhdigits{2022}年\zhnumber{5}月}, + date = {\zhdigits{2022}年\zhnumber{10}月}, studentid = {00910???}, school = {化学与分子工程学院}, cmajor = {应用化学}, emajor = {Applied Chemistry}, direction = {据说 Casper 自己也不知道}, mentorlines = {2}, diff --git a/macros/latex/contrib/pkuthss/tex/pkulogo.pdf b/macros/latex/contrib/pkuthss/tex/pkulogo.pdf index 7789b318aa..8160a06564 100644 Binary files a/macros/latex/contrib/pkuthss/tex/pkulogo.pdf and b/macros/latex/contrib/pkuthss/tex/pkulogo.pdf differ diff --git a/macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def b/macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def index 0633806021..46b20d974d 100644 --- a/macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def +++ b/macros/latex/contrib/pkuthss/tex/pkuthss-gbk.def @@ -24,7 +24,7 @@ % pkuword.eps \ProvidesFile{pkuthss-gbk.def} - [2022/05/05 v1.9.2 Labels and captions in GBK encoding + [2022/10/30 v1.9.3 Labels and captions in GBK encoding for the pkuthss document class] \def\label@ctitle{Ŀ} diff --git a/macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def b/macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def index 5d0e25905e..e0358eb18e 100644 --- a/macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def +++ b/macros/latex/contrib/pkuthss/tex/pkuthss-utf8.def @@ -24,7 +24,7 @@ % pkuword.eps \ProvidesFile{pkuthss-utf8.def} - [2022/05/05 v1.9.2 Labels and captions in UTF-8 encoding + [2022/10/30 v1.9.3 Labels and captions in UTF-8 encoding for the pkuthss document class] \def\label@ctitle{题目:} diff --git a/macros/latex/contrib/pkuthss/tex/pkuthss.cls b/macros/latex/contrib/pkuthss/tex/pkuthss.cls index 22bdde1209..ad3945afba 100644 --- a/macros/latex/contrib/pkuthss/tex/pkuthss.cls +++ b/macros/latex/contrib/pkuthss/tex/pkuthss.cls @@ -25,7 +25,7 @@ \NeedsTeXFormat{LaTeX2e}[1995/12/01] \ProvidesClass{pkuthss} - [2022/05/05 v1.9.2 Peking University dissertation document class] + [2022/10/30 v1.9.3 Peking University dissertation document class] % eg. `\thss@int@boolopt{spacing}{true}' will expand to: % \newif\ifthss@opt@spacing \thss@opt@spacingtrue @@ -112,16 +112,15 @@ UprightFont = *-regular, BoldFont = *-bold, ItalicFont = *-italic, - BoldItalicFont = *-bolditalic + BoldItalicFont = *-bolditalic, + Scale = 0.95 ]{texgyreheros} \else - % `nofontspec' avoids errors like `The font "FangSong" cannot be found'. - % `defaultsups' prevents newtxtext from manipulating footnote marks. - \usepackage[nofontspec, defaultsups]{newtxtext} - \usepackage[varg]{newtxmath} + \RequirePackage{textcomp, mathptmx, latexsym} + \RequirePackage[scaled = 0.95]{helvet} \fi \else - % Provides `\Box' for originauth.tex if XITSMath/newtx is absent. + % Provides `\Box' for originauth.tex if unicode-math is absent. \RequirePackage{latexsym} \fi @@ -133,9 +132,9 @@ % Circled text, cf. . \RequirePackage{tikz} \newcommand*{\thss@int@circled}[1]{% - \scalebox{0.8}{\tikz[baseline = (char.base)]{ + \scalebox{0.8}{\tikz[baseline = {([yshift = -0.1\ccwd] char.base)}]{ \node[ - shape = circle, draw = black, minimum size = 1.25em, inner sep = 0pt + shape = circle, draw = black, minimum size = 1.25\ccwd, inner sep = 0pt ] (char) {#1}; }}% } @@ -144,10 +143,9 @@ \renewcommand*{\thefootnote}% {\protect\thss@int@circled{\arabic{footnote}}} % Provides utility to modify footnote spacing. - % Option used to make sure it does not render interleaf pages totally blank. - \RequirePackage[cleardoublepage = current]{scrextend} - % Set up footnote spacing: whole paragraph indent 2 ccwd, 0.5 ccwd after mark. - \deffootnote{2\ccwd}{0pt}{\thefootnotemark\hspace{0.5\ccwd}} + \RequirePackage{scrextend} + % Set up footnote spacing: whole paragraph indent 1.5 ccwd, 0.5 ccwd after mark. + \deffootnote{1.5\ccwd}{0pt}{\thefootnotemark\hspace{0.5\ccwd}} \fi \ifthss@opt@pkuspace diff --git a/macros/latex/contrib/pkuthss/tex/pkuthss.def b/macros/latex/contrib/pkuthss/tex/pkuthss.def index 80239cf01c..c4b2681745 100644 --- a/macros/latex/contrib/pkuthss/tex/pkuthss.def +++ b/macros/latex/contrib/pkuthss/tex/pkuthss.def @@ -23,7 +23,7 @@ % pkuword.eps \ProvidesFile{pkuthss.def} - [2022/05/05 v1.9.2 Labels and captions for the pkuthss document class] + [2022/10/30 v1.9.3 Labels and captions for the pkuthss document class] \def\label@ementor{Directed by\ } \def\euniversity{Peking University} diff --git a/macros/latex/contrib/pkuthss/tex/pkuword.pdf b/macros/latex/contrib/pkuthss/tex/pkuword.pdf index 8021172ab7..e608ef5def 100644 Binary files a/macros/latex/contrib/pkuthss/tex/pkuword.pdf and b/macros/latex/contrib/pkuthss/tex/pkuword.pdf differ diff --git a/macros/luatex/latex/luaoptions/Contributors.md b/macros/luatex/latex/luaoptions/Contributors.md new file mode 100644 index 0000000000..ab09dc720d --- /dev/null +++ b/macros/luatex/latex/luaoptions/Contributors.md @@ -0,0 +1,6 @@ +## Authors + +Luaoptions is developped by: + +- [Fr. Jacques Peron](mailto:cataclop@hotmail.com); [@jperon](https://github.com/jperon) +- [Urs Liska](mailto:git@ursliska.de); [@uliska](https://github.com/uliska), [@openlilylib](https://github.com/openlilylib) diff --git a/macros/luatex/latex/luaoptions/LICENSE b/macros/luatex/latex/luaoptions/LICENSE new file mode 100644 index 0000000000..479e0ec593 --- /dev/null +++ b/macros/luatex/latex/luaoptions/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2015--2022 the lualatex-tools Project + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/macros/luatex/latex/luaoptions/README.md b/macros/luatex/latex/luaoptions/README.md new file mode 100644 index 0000000000..19ad0c6770 --- /dev/null +++ b/macros/luatex/latex/luaoptions/README.md @@ -0,0 +1,15 @@ +Main author: [Fr. Jacques Peron](mailto:cataclop@hotmail.com)\nThis material is subject to the MIT license.\n +# `luaoptions` +Option handling for LuaLaTeX packages + +This package has been extracted from +[`lyluatex`](https://github.com/jperon/lyluatex) where it was originally +developed as supporting functionality. However, as it turned out it is useful +as a building block for LuaLaTeX packages in general, and the development of +[`luaformatters`](https://github.com/lualatex-tools/luaformatters) made it +clear that the option handling code had to be moved to a standalone package. + +Initially there is no extensive documentation available since the package wasn't +originally intended to be exposed to third-party packages or even end-users; +the best sources of documentation are `lyluatex` and `luaformatters` codes, +and the docstrings of `luaoptions.lua` and `luaoptions-lib.lua`. diff --git a/macros/luatex/latex/luaoptions/latexmkrc b/macros/luatex/latex/luaoptions/latexmkrc new file mode 100644 index 0000000000..d654412169 --- /dev/null +++ b/macros/luatex/latex/luaoptions/latexmkrc @@ -0,0 +1,2 @@ +$pdf_mode="1"; +$pdflatex="lualatex --shell-escape %O %S"; diff --git a/macros/luatex/latex/luaoptions/luaoptions-lib.lua b/macros/luatex/latex/luaoptions/luaoptions-lib.lua new file mode 100644 index 0000000000..4f797da12e --- /dev/null +++ b/macros/luatex/latex/luaoptions/luaoptions-lib.lua @@ -0,0 +1,240 @@ +-- luacheck: ignore ly log self luatexbase internalversion font fonts tex token kpse status +local err, warn, info, log = luatexbase.provides_module({ + name = "luaoptions-lib", + version = '0.8', --LUAOPTIONS_VERSION + date = "2022/10/30", --LUAOPTIONS_DATE + description = "Module luaoptions-lib.", + author = "The lualatex-tools Project", + copyright = "2015-2022 - the lualatex-tools Project", + license = "MIT", +}) + +local lib = {} +lib.TEX_UNITS = {'bp', 'cc', 'cm', 'dd', 'in', 'mm', 'pc', 'pt', 'sp', 'em', +'ex'} + +------------------------- +-- General tool functions + +function lib.basename(str) +--[[ + Given the full path to a file, return only the file name (without path). + If there is no slash, return the full name. +--]] + return str:gsub(".*/(.*)", "%1") or str +end + + +function lib.contains(table_var, value) +--[[ + Returns the key if the given table contains the given value, or nil. + A value of 'false' (string) is considered equal to false (Boolean). +--]] + for k, v in pairs(table_var) do + if v == value then return k + elseif v == 'false' and value == false then return k + end + end +end + + +function lib.contains_key(table_var, key) +-- Returs true if the given key is present in the table, nil otherwise. + for k in pairs(table_var) do + if k == key then return true end + end +end + + +function lib.convert_unit(value) +--[[ + Convert a LaTeX unit, if possible. + TODO: Understand what this *really* does, what is accepted and returned. +--]] + if not value then return 0 + elseif value == '' then return false + elseif value:match('\\') then + local n, u = value:match('^%d*%.?%d*'), value:match('%a+') + if n == '' then n = 1 end + return tonumber(n) * tex.dimen[u] / tex.sp("1pt") + else return ('%f'):format(tonumber(value) or tex.sp(value) / tex.sp("1pt")) + end +end + + +function lib.current_font_size() +--[[ + Convenience function to return the font size of the current font +--]] + return lib.fontinfo(font.current()).size +end + + +function lib.dirname(str) +--[[ + Given the full path to a file, return only the path (without file name), + including the last slash. If there is no slash, return an empty string. +--]] + return str:gsub("(.*/).*", "%1") or '' +end + + +local fontdata = fonts.hashes.identifiers +function lib.fontinfo(id) +--[[ + Return a LuaTeX font object based on the given ID +--]] + return fontdata[id] or font.getfont(id) +end + + +function lib.max(a, b) + a, b = tonumber(a), tonumber(b) + if a > b then return a else return b end +end + + +function lib.min(a, b) + a, b = tonumber(a), tonumber(b) + if a < b then return a else return b end +end + + +function lib.mkdirs(str) + local path + if str:sub(1, 1) == '/' then path = '' else path = '.' end + for dir in str:gmatch('([^%/]+)') do + path = path .. '/' .. dir + lfs.mkdir(path) + end +end + + +function lib.orderedkeys(t) + local orderedIndex = {} + for k in pairs(t) do table.insert(orderedIndex, k) end + table.sort(orderedIndex) + return orderedIndex +end + + +function lib.orderedpairs(t) + local key + local i = 0 + local orderedIndex = lib.orderedkeys(t) + return function () + i = i + 1 + key = orderedIndex[i] + if key then return key, t[key] end + end +end + + +function lib.print_table(t, indent) +-- Recursively print a table, avoiding recursion loops + indent = indent or ' ' + local visited = {} + local skips = 0 + + local function _print_table(_t, _ind) + local keys = lib.orderedkeys(_t) + local display_keys = {} + local length = 0 + for key, _ in pairs(_t) do + length = lib.max(length, #tostring(key)) + end + for key, _ in pairs(_t) do + display_key = tostring(key) + display_keys[key] = display_key .. string.rep( + ' ', length - #display_key) + end + for k, v in lib.orderedpairs(_t) do + if type(v) == 'table' then + if visited[v] then + skips = skips + 1 + else + visited[v] = true + print(_ind..display_keys[k], v) + if #_ind > 40 then err("k") end + _print_table(v, _ind..indent) + end + else + if v == '' then v = '(empty string)' end + print(_ind..display_keys[k], v) + end + end + end + + print() + visited[t] = true + print("Print table:", t) + _print_table(t, indent) + print() + if skips > 0 then + print(string.format('%s recursive tables skipped', skips)) + end + print("============") + print() +end + +function lib.readlinematching(s, f) + if f then + local result = '' + while result and not result:find(s) do result = f:read() end + f:close() + return result + end +end + + +function lib.splitext(str, ext) +--[[ + If 'ext' is supplied return str stripped of the given extension, + otherwise return the base and extension (if any) +--]] + return ext and (str:match('(.*)%.'..ext..'$') or str) + or (str:match('(.*)%.(%w*)$') or str) +end + + +------------------------------------ +-- Engine, version, TeX distribution + +local function _loaded(ext) +--[[ + Returns a function that checks whether a class or a package is loaded + https://tex.stackexchange.com/questions/501635/ +--]] + local fmt = "ver@%s." .. ext + return function(name) + local macro = token.get_macro(fmt:format(name)) + return macro ~= nil + end +end + +-- Lua implementations of \@ifpackageloaded and \@ifclassloaded +lib.class_loaded = _loaded('cls') +lib.package_loaded = _loaded('sty') + +local tex_engine = {} +setmetatable(tex_engine, tex_engine) + +function tex_engine:__call() +--[[ + Defines the properties extracted from the first line of jobname.log. +--]] + local f = io.open(tex.jobname..'.log') + if not f then return end + self.engine, self.engine_version, self.dist, self.dist_version, self.format, self.format_version = + f:read():match( + 'This is ([^,]*), Version ([^%(]*) %(([^%)]*) ([^%)]*)%)%s+%(format=([^%)]*) ([^)]*)%)' + ) + f:close() + return self +end + +function tex_engine:__index(k) return rawget(self(), k) end + + +lib.tex_engine = tex_engine +return lib diff --git a/macros/luatex/latex/luaoptions/luaoptions.lua b/macros/luatex/latex/luaoptions/luaoptions.lua new file mode 100644 index 0000000000..16f25150bf --- /dev/null +++ b/macros/luatex/latex/luaoptions/luaoptions.lua @@ -0,0 +1,329 @@ +-- luacheck: ignore ly warn info log self luatexbase internalversion font fonts tex token kpse status +local err, warn, info, log = luatexbase.provides_module({ + name = "luaoptions", + version = '0.8', --LUAOPTIONS_VERSION + date = "2022/10/30", --LUAOPTIONS_DATE + description = "Module luaoptions.", + author = "The lualatex-tools Project", + copyright = "2015-2022 - the lualatex-tools Project", + license = "MIT", +}) + +--[[ + This module provides functionality to handle package options and make them + configurable in a fine-grained fashion as + - package options + - local options (for individual instances of commands/environments) + - changed “from here on” within a document. + +-- ]] + +local lib = require(kpse.find_file("luaoptions-lib.lua") or "luaoptions-lib.lua") +local optlib = {} -- namespace for the returned table +local Opts = {options = {}} -- Options class +Opts.__index = function (self, k) return self.options[k] or rawget(Opts, k) end +setmetatable(Opts, Opts) +local clients = {} + +function Opts:new(declarations) +--[[ + Declare an options object along with default and accepted values. + To *some* extent also provide type checking. + - declarations: a definition table stored in the calling module (see below) + Each entry in the 'declarations' table represents one package option, with each + value being an array (table with integer indexes instead of keys). For + details please refer to the manual. +--]] + local o = setmetatable( + { + declarations = declarations, + options = {} + }, + self + ) + for k, v in pairs(declarations) do + o.options[k] = v[1] or '' + end + return o +end + +function Opts:check_local_options(opts, ignore_declarations) +--[[ + Parse the given options (options passed to a command/environment), + sanitize them against the global package options and return a table + with the local options that should then supersede the global options. + If ignore_declaration is given any non-false value the sanitization + step is skipped (i.e. local options are only parsed and duplicates + rejected). +--]] + local options = {} + local next_opt = opts:gmatch('([^,]+)') -- iterator over options + for opt in next_opt do + local k, v = opt:match('([^=]+)=?(.*)') + if k then + if v and v:sub(1, 1) == '{' then -- handle keys with {multiple, values} + while select(2, v:gsub('{', '')) ~= select(2, v:gsub('}', '')) do v = v..','..next_opt() end + v = v:sub(2, -2) -- remove { } + end + if not ignore_declarations then + k, v = self:sanitize_option(k:gsub('^%s', ''), v:gsub('^%s', '')) + end + if k then + if options[k] then err('Option %s is set two times for the same score.', k) + else options[k] = v + end + end + end + end + return options +end + +function Opts:has_option(name) +--[[ + Returns true if the given option is declared +--]] + return self.declarations[name] ~= nil +end + +function Opts:is_neg(k) +--[[ + Type check for a 'negative' option. This is an existing option + name prefixed with 'no' (e.g. 'noalign') +--]] + local _, i = k:find('^no') + return i and lib.contains_key(self.declarations, k:sub(i + 1)) +end + +function Opts:sanitize_option(k, v) +--[[ + Check and (if necessary) adjust the value of a given option. + Reject undefined options + Check 'negative' options + Handle boolean options (empty strings or 'false'), set them to real booleans +--]] + local declarations = self.declarations + if k == '' or k == 'noarg' then return end + if not lib.contains_key(declarations, k) then err('Unknown option: '..k) end + -- aliases + if declarations[k] and declarations[k][2] == optlib.is_alias then + if declarations[k][1] == v then return + else k = declarations[k] end + end + -- boolean + if v == 'false' then v = false end + -- negation (for example, noindent is the negation of indent) + if self:is_neg(k) then + if v ~= nil and v ~= 'default' then + k = k:gsub('^no(.*)', '%1') + v = not v + else return + end + end + return k, v +end + +function Opts:set_option(k, v) +--[[ + Set an option for the given prefix to be in effect from this point on. + Raises an error if the option is not declared or does not meet the + declared expectations. (TODO: The latter has to be integrated by extracting + optlib.validate_option from optlib.validate_options and call it in + sanitize_option). +--]] + k, v = self:sanitize_option(k, v) + if k then + self.options[k] = v + self:validate_option(k) + end +end + +function Opts:use_option(key) +--[[ + Call an option and write its value to the TeX space. + This is a shorthand for accessing options from the TeX side + (rather than having to write tex.print(XX_opts.some_options)) +--]] + local option = self.options[key] + if option then + tex.print(option:explode('\n')) + else + err(string.format("Trying to access non-existent option %s", key)) + end +end + +function Opts:validate_option(key, options_obj) +--[[ + Validate an (already sanitized) option against its expected values. + With options_obj a local options table can be provided, + otherwise the global options stored in OPTIONS are checked. +--]] + local package_opts = self.declarations + local options = options_obj or self.options + local unexpected + if options[key] == 'default' then + -- Replace 'default' with an actual value + options[key] = package_opts[key][1] + unexpected = options[key] == nil + end + if not lib.contains(package_opts[key], options[key]) and package_opts[key][2] then + -- option value is not in the array of accepted values + if type(package_opts[key][2]) == 'function' then package_opts[key][2](key, options[key]) + else unexpected = true + end + end + if unexpected then + err([[ + Unexpected value "%s" for option %s: + authorized values are "%s" + ]], + options[key], key, table.concat(package_opts[key], ', ') + ) + end +end + +function Opts:validate_options(options_obj) +--[[ + Validate the given set of options against the option declaration + table for the given prefix. + With options_obj a local options table can be provided, + otherwise the global options stored in OPTIONS are checked. +--]] + for k, _ in lib.orderedpairs(self.declarations) do + self:validate_option(k, options_obj) + end +end + + +function optlib.is_alias() +--[[ + This function doesn't do anything, but if an option is defined + as an alias, its second parameter will be this function, so the + test declarations[k][2] == optlib.is_alias in Opts:sanitize_options + will return true. +--]] +end + + +function optlib.is_dim(k, v) +--[[ + Type checking for options that accept a LaTeX dimension. + This can be + - a number (integer or float) + - a number with unit + - a (multiplied) TeX length + (see error message in code for examples) +--]] + if v == '' or v == false or tonumber(v) then return true end + local n, sl, u = v:match('^%d*%.?%d*'), v:match('\\'), v:match('%a+') + -- a value of number - backslash - length is a dimension + -- invalid input will be prevented in by the LaTeX parser already + if n and sl and u then return true end + if n and lib.contains(lib.TEX_UNITS, u) then return true end + err([[ +Unexpected value "%s" for dimension %s: +should be either a number (for example "12"), +a number with unit, without space ("12pt"), +or a (multiplied) TeX length (".8\linewidth") +]], + v, k + ) +end + + +function optlib.is_neg(k, _) +--[[ + Type check for a 'negative' option. At this stage, + we only check that it begins with 'no'. +--]] + return k:find('^no') +end + + +function optlib.is_num(_, v) +--[[ + Type check for number options +--]] + return v == '' or tonumber(v) +end + + +function optlib.is_str(_, v) +--[[ + Type check for string options +--]] + return type(v) == 'string' +end + + +function optlib.merge_options(base_opt, super_opt) +--[[ + Merge two tables. + Create a new table as a copy of base_opt, then merge with + super_opt. Entries in super_opt supersede (i.e. overwrite) + colliding entries in base_opt. +--]] + local result = {} + for k, v in pairs(base_opt) do result[k] = v end + for k, v in pairs(super_opt) do result[k] = v end + return result +end + +function optlib.register(client_name, declarations) +--[[ + Register a client as package options. + - Create a new Opts object, + - initialize it, + - store it in a global variable _opts, + - write the code to handle the package options. +--]] + local o = Opts:new(declarations) + local exopt = '' + for k, v in pairs(declarations) do + tex.sprint(string.format([[ +\DeclareOptionX{%s}{\setluaoption{%s}{%s}{#1}}%% +]], + k, client_name, k + )) + exopt = exopt..k..'='..(v[1] or '')..',' + end + clients[client_name] = o + tex.sprint([[\ExecuteOptionsX{]]..exopt..[[}%%]], [[\ProcessOptionsX]]) +end + +function optlib.client(name) +--[[ + Return the FormattersTable instance registered with the given client name. + Return 'nil' if no client is found. +--]] + return clients[name] +end + +function optlib.get_option(client_name, k) +--[[ + Get an option's value from a registered client. + Raises an error if the client hasn't been registered. +--]] + local client = optlib.client(client_name) + return client.options[k] +end + +function optlib.set_option(client_name, k, v) +--[[ + Set an option. + Look up a registered client and set an option. + Produces an error if the client hasn't been registered. +--]] + local client = optlib.client(client_name) + client:set_option(k, v) +end + +function optlib.use_option(client_name, k) +--[[ + Look up an option and write it to LaTex. +--]] + local client = optlib.client(client_name) + client:use_option(k) +end + +optlib.Opts = Opts +return optlib diff --git a/macros/luatex/latex/luaoptions/luaoptions.pdf b/macros/luatex/latex/luaoptions/luaoptions.pdf new file mode 100644 index 0000000000..3339fbeb63 Binary files /dev/null and b/macros/luatex/latex/luaoptions/luaoptions.pdf differ diff --git a/macros/luatex/latex/luaoptions/luaoptions.sty b/macros/luatex/latex/luaoptions/luaoptions.sty new file mode 100644 index 0000000000..559c615ab6 --- /dev/null +++ b/macros/luatex/latex/luaoptions/luaoptions.sty @@ -0,0 +1,36 @@ +% luaoptions support package. +% +% Copyright (C) 2015-2022 the lualatex-tools Project +% License: MIT +% This file is part of luaoptions. + +\NeedsTeXFormat{LaTeX2e}% +\ProvidesPackage{luaoptions}[2022/10/30 v0.8] + +% Dependencies +\RequirePackage{luatexbase} +\RequirePackage{luaotfload} +\RequirePackage{xkeyval} + +\directlua{ + lua_options = require(kpse.find_file("luaoptions.lua") or "luaoptions.lua") +} + +% Set an option in a registered client +\newcommand{\setluaoption}[3]{% + \directlua{ + lua_options.set_option( + '\luatexluaescapestring{#1}', + '\luatexluaescapestring{#2}', + '\luatexluaescapestring{#3}') + } +} + +% Use an option and directly write it to LaTeX +\newcommand{\useluaoption}[2]{% + \directlua{ + lua_options.use_option( + '\luatexluaescapestring{#1}', + '\luatexluaescapestring{#2}') + }% +} diff --git a/macros/luatex/latex/luaoptions/luaoptions.tex b/macros/luatex/latex/luaoptions/luaoptions.tex new file mode 100644 index 0000000000..627583f678 --- /dev/null +++ b/macros/luatex/latex/luaoptions/luaoptions.tex @@ -0,0 +1,188 @@ +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode}{hyperref} +\PassOptionsToPackage{hyphens}{url} +% +\documentclass[ +]{luaoptionsmanual} +\usepackage{amsmath,amssymb} +\usepackage[]{libertine} +\usepackage{iftex} +\ifPDFTeX + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex + \usepackage{unicode-math} + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} +\fi +% Use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +\usepackage{xcolor} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} +\hypersetup{ + pdfauthor={Fr.~Jacques Peron; Urs Liska}, + hidelinks, + pdfcreator={LaTeX via pandoc}} +\urlstyle{same} % disable monospaced font for URLs +\usepackage{color} +\usepackage{fancyvrb} +\newcommand{\VerbBar}{|} +\newcommand{\VERB}{\Verb[commandchars=\\\{\}]} +\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}} +% Add ',fontsize=\small' for more characters per line +\newenvironment{Shaded}{}{} +\newcommand{\AlertTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}} +\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}} +\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} +\newcommand{\BuiltInTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} +\newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}} +\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}} +\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} +\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.56,0.13,0.00}{#1}} +\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} +\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.73,0.13,0.13}{\textit{#1}}} +\newcommand{\ErrorTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}} +\newcommand{\ExtensionTok}[1]{#1} +\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} +\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}} +\newcommand{\ImportTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} +\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} +\newcommand{\NormalTok}[1]{#1} +\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}} +\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}} +\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.74,0.48,0.00}{#1}} +\newcommand{\RegionMarkerTok}[1]{#1} +\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}} +\newcommand{\StringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}} +\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} +\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} +\setlength{\emergencystretch}{3em} % prevent overfull lines +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures +\fi + +\title{\texttt{luaoptions}} +\usepackage{etoolbox} +\makeatletter +\providecommand{\subtitle}[1]{% add subtitle to \maketitle + \apptocmd{\@title}{\par {\large #1 \par}}{}{} +} +\makeatother +\subtitle{0.8} +\author{Fr.~Jacques Peron \and Urs Liska} +\date{\luaoptionsmanualdate} + +\begin{document} +\maketitle + +\thispagestyle{empty} +\enlargethispage*{3\baselineskip} + +\hypertarget{introduction}{% +\section{Introduction}\label{introduction}} + +\texttt{luaoptions} is a LuaLaTeX package providing extensive support +for handling \emph{options}, on package level and locally. It is hosted +at \url{https://github.com/lualatex-tools/luaoptions} and maintained by +Jacques Peron +(\href{mailto:cataclop@hotmail.com}{\nolinkurl{cataclop@hotmail.com}}) +and Urs Liska +(\href{mailto:git@ursliska.de}{\nolinkurl{git@ursliska.de}}). The +package was originally developed as part of the \texttt{lyluatex} +package\footnote{\url{https://github.com/jperon/lyluatex}} but has now +been extracted as a standalone package because we realized it can be a +useful tool for arbitrary LuaLaTeX packages having to deal with +\emph{options} -- both \emph{package options} and \emph{optional macro +arguments}. A \texttt{lyluatex} installation should not be a dependency +for packages that want to make use of option handling but are not +interested in music engraving \dots + +\texttt{luaoptions} allows the declaration of sets of options, along +with defaults, expected/allowed values and limited type checking. These +options can be enforced as package options, changed at any point during +a document, or overwritten locally by optional macro arguments. It is +also possible to instantiate an \texttt{Options} object as an +independent Lua object, without linking it to a package. +\texttt{luaoptions} can be used to enforce and prepopulate options, or +it can be used to simply handle the parsing of optional +\texttt{key=value} arguments into proper Lua tables. + +The main use of \texttt{luaoptions} is to define package options as +follows: + +\begin{Shaded} +\begin{Highlighting}[] +\FunctionTok{\textbackslash{}RequirePackage}\NormalTok{\{luaoptions\}} +\FunctionTok{\textbackslash{}directlua}\NormalTok{\{} +\NormalTok{ local \_opt = lua\_options} +\NormalTok{ lua\_options.register(\textquotesingle{}myoptions\textquotesingle{}, \{} +\NormalTok{ [\textquotesingle{}option\textquotesingle{}] = \{\textquotesingle{}default value\textquotesingle{}, \textquotesingle{}other value\textquotesingle{}, \textquotesingle{}\textquotesingle{}\},} +\NormalTok{ [\textquotesingle{}otheroption\textquotesingle{}] = \{\textquotesingle{}default\textquotesingle{}, validator\},} +\NormalTok{ [\textquotesingle{}yetanotheroptions\textquotesingle{}] = \{\},} +\NormalTok{ \})} +\NormalTok{\}} +\end{Highlighting} +\end{Shaded} + +\texttt{validator} is a function that returns \texttt{true} when the +defined option is valid, \texttt{false} otherwise. \texttt{luaoptions} +itself contains predefined such functions. + +After that, defined options are available in a lua table, which can be +used by the mean of the \texttt{client} command: + +\begin{Shaded} +\begin{Highlighting}[] +\KeywordTok{local}\NormalTok{ myopts }\OperatorTok{=}\NormalTok{ lua\_options}\OperatorTok{.}\NormalTok{client}\OperatorTok{(}\StringTok{\textquotesingle{}myoptions\textquotesingle{}}\OperatorTok{)} +\NormalTok{tex}\OperatorTok{.}\NormalTok{sprint}\OperatorTok{(}\NormalTok{myopts}\OperatorTok{.}\NormalTok{option}\OperatorTok{)} +\end{Highlighting} +\end{Shaded} + +This initial release does \emph{not} include documentation beyond this +short introduction; please refer to the docstrings in +\texttt{luaoptions.lua} and \texttt{luaoptions-lib.lua} for more +information. + +For the time being it is possible to look into how some of our own +packages make use of \texttt{luaoptions}: + +\begin{itemize} +\tightlist +\item + \url{https://github.com/jperon/lyluatex/blob/master/lyluatextools.sty} +\item + \url{https://github.com/jperon/lyluatex/blob/master/lyluatex.lua} +\item + \url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.sty} +\item + \url{https://github.com/lualatex-tools/luaformatters/blob/master/luaformatters.lua} +\item + \url{https://github.com/lualatex-tools/luaformatters/blob/master/submodules/luaformatters-formatter.lua} +\end{itemize} + +\end{document} diff --git a/macros/luatex/latex/luaoptions/luaoptionsbase.cls b/macros/luatex/latex/luaoptions/luaoptionsbase.cls new file mode 100644 index 0000000000..3f2ac5726e --- /dev/null +++ b/macros/luatex/latex/luaoptions/luaoptionsbase.cls @@ -0,0 +1,37 @@ +%Luaoptions LaTeX class. +% +% Copyright (C) 2015-2022 the lualatex-tools Project +% License: MIT +% This file is part of lualatex-tools. + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{luaoptionsbase}[2022/10/30 v0.8] %%LUAOPTIONS_DATE LUAOPTIONS_VERSION + +\LoadClass[DIV=11]{scrartcl} +\RequirePackage{blindtext} +\RequirePackage{libertine} +\RequirePackage{listings} +\RequirePackage{minted} +\RequirePackage{pgffor} +\RequirePackage{fancyvrb} +\RequirePackage[colorlinks=true]{hyperref} + + +% Common formatting elements for manual and examples +\usepackage{xcolor} +\newcommand{\highlight}[1]{\textcolor{blue}{#1}} +\newcommand{\cmd}[1]{\highlight{\texttt{\textbackslash #1}}} +\newcommand{\option}[1]{\highlight{\texttt{#1}}} +\newcommand{\lyMargin}[1]{% + +\medskip +\hspace*{-1em}% +\noindent% +\highlight{#1} +\nopagebreak +} + +\newcommand{\lyOption}[2]{\lyMargin{\texttt{#1} {\small \emph{(#2)}}\index{#1}}} +\newcommand{\lyCmd}[1]{% +\lyMargin{\texttt{\textbackslash #1}\index{\textbackslash #1}}} +\newcommand{\lyIssue}[1]{\lyMargin{\textbf{\textcolor{red}{#1}}}} diff --git a/macros/luatex/latex/luaoptions/luaoptionsmanual.cls b/macros/luatex/latex/luaoptions/luaoptionsmanual.cls new file mode 100644 index 0000000000..5de9da32b6 --- /dev/null +++ b/macros/luatex/latex/luaoptions/luaoptionsmanual.cls @@ -0,0 +1,41 @@ +%Luaoptions LaTeX class for the manual. +% +% Copyright (C) 2015-2022 the lualatex-tools Project +% License: MIT +% This file is part of luaoptions. + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{luaoptionsmanual}[2022/10/30 v0.8] %%LUAOPTIONS_DATE LUAOPTIONS_VERSION + +\LoadClass{luaoptionsbase} + +\RequirePackage{fontspec} +\RequirePackage{microtype} +\RequirePackage{libertine} +\setmonofont[Scale=MatchLowercase,StylisticSet=1]{InconsolataN} +\defaultfontfeatures{ + Ligatures=TeX, + Scale=MatchLowercase, + Numbers=Proportional, + Numbers=OldStyle +} +\frenchspacing + +\RequirePackage{makeidx} +\makeindex + +\newcommand{\linkexample}[2]{ + \addcontentsline{toc}{subsection}{#2} + \hypertarget{#1}{} +} + + +\newcommand{\luaoptionsmanualdate}{ + \directlua{ + local PC = string.char(37) + local date_fmt = PC..'Y-'..PC..'m-'..PC..'d' + local p = io.popen('git log -n1 --date=short --format='..PC..'"ad"', 'r') + tex.sprint(p and p:read('*a'):sub(1,-2) or os.date(date_fmt)) + if p then p:close() end + } +} diff --git a/macros/unicodetex/latex/bithesis/bithesis.dtx b/macros/unicodetex/latex/bithesis/bithesis.dtx index 1038cef364..1a99ce1238 100644 --- a/macros/unicodetex/latex/bithesis/bithesis.dtx +++ b/macros/unicodetex/latex/bithesis/bithesis.dtx @@ -21,7 +21,7 @@ %\ProvidesExplClass{bithesis} %\ProvidesExplClass{bitreport} %\ProvidesExplClass{bitbeamer} -%{2022-10-23}{3.1.0}{BIT Thesis Templates} +%{2022-10-29}{3.1.1}{BIT Thesis Templates} % %\NeedsTeXFormat{LaTeX2e}[2020/10/01] %\ProvidesClass{bitbook} @@ -30,7 +30,7 @@ % [2022/05/09 v2.1.1 BIT Thesis Templates] % %<*driver> -\ProvidesFile{bithesis.dtx}[2022/10/23 3.1.0 BIT Thesis Templates] +\ProvidesFile{bithesis.dtx}[2022/10/29 3.1.1 BIT Thesis Templates] \documentclass[letterpaper]{l3doc} \usepackage{dtx-style} @@ -1254,7 +1254,7 @@ % 攻读学位期间发表论文与研究成果清单。 % \end{function} % -% \begin{function}{\addpubs,\addpub} +% \begin{function}[added=2022-10-23]{\addpubs,\addpub} % \begin{bitsyntax}[emph={[1]publications,addpubs,addpub}] % \begin{publications} % \addpub{\meta{单条引用内容的key}} @@ -1266,7 +1266,7 @@ % 用于添加个人成果,添加过的成果可以通过 |printbibliography| 打印。 % \end{function} % -% \begin{function}{\pubsection} +% \begin{function}[added=2022-10-23]{\pubsection} % \begin{bitsyntax}[emph={[1]publications,pubsection,printbibliography}] % \begin{publications} % \addpubs{\meta{引用内容的key},\meta{引用内容的key2}} @@ -1283,7 +1283,7 @@ % 用于添加分类的目录。 % \end{function} % -% \begin{function}{\Author,\AuthorEn} +% \begin{function}[added=2022-10-23]{\Author,\AuthorEn} % \begin{bitsyntax}[emph={[1]Author}] % \Author[][<覆盖普通模式下内容>][<覆盖盲审模式下内容>] % \end{bitsyntax} @@ -1317,6 +1317,22 @@ % 个人简介。 % \end{function} % +% \section{常见问题和疑难解答} +% +% \subsection{如何修改数学公式的字体?} +% +% 本项目已经使用 \pkg{unicode-math} 宏包, +% 可以在导言区使用 |\setmathfont{XITS Math}| 修改数学环境下字体: +% +% \begin{latex} +% \unimathsetup{bold-style=ISO} +% \setmathfont{XITS Math} +% \end{latex} +% +% \textit{请事先安装 XITS 字体。} +% +% \textit{更多字体与使用方法请参考 \url{https://ctan.org/pkg/unicode-math?lang=zh}。} +% % \section{\cls{bitreport.cls} 使用与配置} % \label{sec:bitreport} % @@ -2198,12 +2214,14 @@ \RequirePackage{multirow} \RequirePackage{tikz} \RequirePackage{etoolbox} -\RequirePackage{hyperref} +% Hide color and border in hyperref. +\RequirePackage[hidelinks]{hyperref} \RequirePackage{xcolor} \RequirePackage{caption} \RequirePackage{array} \RequirePackage{amsmath} \RequirePackage{amssymb} +\RequirePackage{pifont} \RequirePackage{amsthm} \RequirePackage{unicode-math} \RequirePackage{pdfpages} @@ -2257,13 +2275,17 @@ } % \end{macrocode} % -% 根据学校的要求,在图片前后加上一行空白。 +% 根据学校的要求,在本科生模板图片前后加上一行空白。 % \begin{macrocode} -\setlength{\intextsep}{2\baselineskip plus 0.2\baselineskip minus 0.2\baselineskip} +\@@_if_bachelor_thesis:T { + \setlength{\intextsep}{2\baselineskip plus 0.2\baselineskip minus 0.2\baselineskip} +} % \end{macrocode} % % 设置 Times New Roman 字体。 +% 根据学校规范要求,默认情况下也使用 Times New Roman 字体。 % \begin{macrocode} +\setmainfont{Times~New~Roman} \setromanfont{Times~New~Roman} % \end{macrocode} % @@ -3060,6 +3082,14 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\BigStar} +% 提供密级选项中需要的五角星,在普通环境中使用。 +% \begin{macrocode} +\DeclareDocumentCommand \BigStar { } + { \ding{72} } +% \end{macrocode} +% \end{macro} +% % \begin{environment}{blindPeerReview} % 用于包裹涉及个人信息的内容。 % @@ -3830,6 +3860,40 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\addpub,\addpubs} +% 添加一个或多个参考文献。 +% \begin{macrocode} +\NewDocumentCommand \addpub {m} { + \nocite{#1} + \addtocategory{mypub}{#1} +} + +\NewDocumentCommand \addpubs {m} { + % apply a clist + \clist_map_function:nN {#1} \addpub +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\pubsection} +% 设置小标题。 +% \begin{macrocode} +\NewDocumentCommand \pubsection {m} { + { + % 自增计数器 + \par\stepcounter{pub} + % 设置小标题,暂时没有考虑英文模式 + \noindent + \textbf{ + \heiti{ + \zhnumber{\thepub}、#1 + } + }\par + } +} +% \end{macrocode} +% \end{macro} +% % \begin{environment}{publications} % 生成攻读学位期间发表论文与研究成果清单。 % \begin{macrocode} @@ -3914,34 +3978,13 @@ } } - % 添加一个参考文献 - \cs_new:Npn \addpub ##1 { - \nocite{##1} - \addtocategory{mypub}{##1} - } - - % 添加多个参考文献 - \cs_new:Npn \addpubs ##1 { - % apply a clist - \clist_map_function:nN {##1} \addpub - } - - % 设置计数器 - \newcounter{pub} - % 设置小标题 - \cs_new:Npn \pubsection ##1 { - { - % 自增计数器 - \stepcounter{pub} - % 设置小标题,暂时没有考虑英文模式 - \noindent - \textbf{ - \heiti{ - \zhnumber{\thepub}、##1 - } - }\par - } - } + \if_cs_exist:N \c@pub { + % 重置计数器 + \setcounter{pub}{0} + } \else: { + % 设置计数器 + \newcounter{pub} + } \fi: % 设置参考文献的排序 \bool_if:NTF \l_@@_publications_sorting_bool { diff --git a/macros/unicodetex/latex/bithesis/bithesis.pdf b/macros/unicodetex/latex/bithesis/bithesis.pdf index 3e80f53288..2ce8119710 100644 Binary files a/macros/unicodetex/latex/bithesis/bithesis.pdf and b/macros/unicodetex/latex/bithesis/bithesis.pdf differ diff --git a/macros/xetex/latex/xepersian/README b/macros/xetex/latex/xepersian/README index b1c63bf40b..e37f06cdd3 100644 --- a/macros/xetex/latex/xepersian/README +++ b/macros/xetex/latex/xepersian/README @@ -1,6 +1,6 @@ ____________________ The XePersian package -v24.7 +v24.8 The xepersian package provides a convenient interface for typesetting Persian and English texts in LaTeX, using XeTeX @@ -25,7 +25,7 @@ The announcements for the new releases of the package will also appear in the Discussions space under the Announcements category. -Current version release date: 2022/07/02 +Current version release date: 2022/10/30 ___________________________________________ Vafa Khalighi diff --git a/macros/xetex/latex/xepersian/xepersian-doc-intro.ltx b/macros/xetex/latex/xepersian/xepersian-doc-intro.ltx index 1e40958b5d..333d7efb4b 100644 --- a/macros/xetex/latex/xepersian/xepersian-doc-intro.ltx +++ b/macros/xetex/latex/xepersian/xepersian-doc-intro.ltx @@ -25,7 +25,7 @@ If you use \textsf{\XePersian} package to write any input \TeX\ document, and th * Copyright (c) 2008--2022 Vafa Khalighi * Copyright (c) 2018--2020 bidi-tex GitHub Organization * -* v24.7, 2022/07/02 +* v24.8 (Release Women, Life, and Freedom), 2022/10/30 * * License: LaTeX Project Public License, version * 1.3c or higher (your choice) diff --git a/macros/xetex/latex/xepersian/xepersian-doc-title.ltx b/macros/xetex/latex/xepersian/xepersian-doc-title.ltx index 0d9d2397c5..27ad90198d 100644 --- a/macros/xetex/latex/xepersian/xepersian-doc-title.ltx +++ b/macros/xetex/latex/xepersian/xepersian-doc-title.ltx @@ -3,7 +3,7 @@ \begin{document} \title{\textcolor{blue!65!black}{\Huge The \textsf{\XePersian} \textit{Package}}\\ \LARGE Persian for \LaTeXe, using {\XeTeX} engine\\[5pt] -\large User documentation for \textcolor{blue!65!black}{version 24.7}} +\large User documentation for \textcolor{blue!65!black}{version 24.8}} \author{Vafa Khalighi\thanks{Thanks to the bidi-tex GitHub organization consisted of David Carlisle and other members of the {\LaTeX} team to maintain the package in the period 2018--2020.}} \setcounter{page}{0} \thispagestyle{empty} @@ -13,7 +13,7 @@ \textcolor{blue!65!black}{\Huge The \textsf{\XePersian} \textit{Package}} \Large -User documentation for \textcolor{blue!65!black}{version 24.7}} +User documentation for \textcolor{blue!65!black}{version 24.8}} \vskip 0pt plus 3fill \textit{\large to my Master, \textbf{Ferdowsi The Great}} diff --git a/macros/xetex/latex/xepersian/xepersian-doc.ltx b/macros/xetex/latex/xepersian/xepersian-doc.ltx index fe47fba51c..6a74c7edc8 100644 --- a/macros/xetex/latex/xepersian/xepersian-doc.ltx +++ b/macros/xetex/latex/xepersian/xepersian-doc.ltx @@ -1,7 +1,7 @@ \documentclass{ltxdoc} \input{xepersian-doc-preamble.ltx} \hypersetup{% - pdftitle={User documentation for version 24.7 of the XePersian + pdftitle={User documentation for version 24.8 of the XePersian package}% } \begin{document} diff --git a/macros/xetex/latex/xepersian/xepersian-doc.pdf b/macros/xetex/latex/xepersian/xepersian-doc.pdf index 0ea9d4988c..49b3ee1d15 100644 Binary files a/macros/xetex/latex/xepersian/xepersian-doc.pdf and b/macros/xetex/latex/xepersian/xepersian-doc.pdf differ diff --git a/macros/xetex/latex/xepersian/xepersian.dtx b/macros/xetex/latex/xepersian/xepersian.dtx index bb454e519c..b9a707a4f9 100644 --- a/macros/xetex/latex/xepersian/xepersian.dtx +++ b/macros/xetex/latex/xepersian/xepersian.dtx @@ -5,7 +5,7 @@ %<*readme> ____________________ The XePersian package -v24.7 +v24.8 The xepersian package provides a convenient interface for typesetting Persian and English texts in LaTeX, using XeTeX @@ -31,7 +31,7 @@ also appear in the Discussions space under the Announcements category. -Current version release date: 2022/07/02 +Current version release date: 2022/10/30 ___________________________________________ Vafa Khalighi @@ -168,7 +168,7 @@ by Vafa Khalighi. \documentclass{ltxdoc} \input{xepersian-doc-preamble.ltx} \hypersetup{% - pdftitle={Source documentation for version 24.7 of the XePersian + pdftitle={Source documentation for version 24.8 of the XePersian package}% } \EnableCrossrefs @@ -187,7 +187,7 @@ by Vafa Khalighi. % \GetFileInfo{\jobname.dtx} % \title{\textcolor{blue!65!black}{\Huge The \textsf{\XePersian} \textit{Package}}\\ %\LARGE Persian for \LaTeXe, using {\XeTeX} engine\\[5pt] -%\large Source documentation for \textcolor{blue!65!black}{version 24.7}} +%\large Source documentation for \textcolor{blue!65!black}{version 24.8}} % \author{Vafa Khalighi\thanks{Thanks to the bidi-tex GitHub organization consisted of David Carlisle and other members of the {\LaTeX} team to maintain the package in the period 2018--2020.}} %\setcounter{page}{0} %\thispagestyle{empty} @@ -197,7 +197,7 @@ by Vafa Khalighi. %\textcolor{blue!65!black}{\Huge The \textsf{\XePersian} \textit{Package}} % %\Large -%Source documentation for \textcolor{blue!65!black}{version 24.7}} +%Source documentation for \textcolor{blue!65!black}{version 24.8}} % %\vskip 0pt plus 3fill %\textit{\large to my Master, \textbf{Ferdowsi The Great}} @@ -245,7 +245,7 @@ by Vafa Khalighi. %\iffalse %<*table> %\fi -%% \CheckSum{11173} +%% \CheckSum{11192} %% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z @@ -2021,7 +2021,7 @@ by Vafa Khalighi. %\fi % \section{File \texttt{hyperref-xepersian.def}} % \begin{macrocode} -\ProvidesFile{hyperref-xepersian.def}[2022/06/10 v0.7 xepersian adaptations for hyperref package] +\ProvidesFile{hyperref-xepersian.def}[2022/10/30 v0.8 xepersian adaptations for hyperref package] \def\equationautorefname{\if@RTL معادله\else Equation\fi}% \def\footnoteautorefname{\if@RTL زیرنویس\else footnote\fi}% \def\itemautorefname{\if@RTL فقره\else item\fi}% @@ -2051,9 +2051,9 @@ by Vafa Khalighi. }% \fi \pdfstringdefDisableCommands{% -\let\lr\@firstofone -\let\rl\@firstofone -\def\XePersian{XePersian} + \let\lr\@firstofone + \let\rl\@firstofone + \def\XePersian{XePersian}% } \ltx@IfUndefined{@resets@pp}{% }{% @@ -3592,9 +3592,12 @@ U+003E U+003E <> U+00BB ; >> -> RIGHT POINTING GUILLEMET % \section{File \texttt{xepersian.sty}} % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\def\xepersian@version{24.7} -\def\xepersiandate{2022/07/02} -\ProvidesPackage{xepersian}[\xepersiandate\space v\xepersian@version\space +\def\xepersian@version{24.8} +\def\xepersiandate{2022/10/30} +\def\xepersian@releasename{Women, Life, and Freedom} +\def\xepersian@persian@@releasename{زن، زندگی، و آزادی} +\newcommand*{\xepersianreleasename}{\if@RTL\xepersian@persian@@releasename\else\xepersian@releasename\fi} +\ProvidesPackage{xepersian}[\xepersiandate\space v\xepersian@version\space (Release \xepersian@releasename)\space Persian typesetting in XeLaTeX] \RequirePackage{fontspec} \RequirePackage{xepersian-persiancal} @@ -3611,7 +3614,7 @@ Persian typesetting in XeLaTeX] * Copyright (c) 2008--2022 Vafa Khalighi^^J% * Copyright (c) 2018--2020 bidi-tex GitHub Organization^^J% * ^^J% -* v\xepersian@version, \xepersiandate^^J% +* v\xepersian@version\space (Release \xepersian@releasename), \xepersiandate^^J% * ^^J% * License: LaTeX Project Public License, version^^J% * 1.3c or higher (your choice)^^J% @@ -4437,12 +4440,12 @@ Persian typesetting in XeLaTeX] \textsf{\XePersian}\quad\@bidi@logo{xepersian-logo.pdf}}} \renewcommand*{\@bidi@pdfcreator}{% - The xepersian package, v\xepersian@version, \xepersiandate + The xepersian package, v\xepersian@version\space (Release \xepersian@releasename), \xepersiandate } \newcommand*{\@xepersian@pdfcustomproperties}{% - This is the xepersian package, Version \xepersian@version, - Released July 2, 2022. + This is the xepersian package, Version \xepersian@version\space (Release \xepersian@releasename), + Released October 30, 2022. } \newcommand\twocolumnstableofcontents{% diff --git a/macros/xetex/latex/xepersian/xepersian.pdf b/macros/xetex/latex/xepersian/xepersian.pdf index a4a8cef342..c61333a7b1 100644 Binary files a/macros/xetex/latex/xepersian/xepersian.pdf and b/macros/xetex/latex/xepersian/xepersian.pdf differ diff --git a/support/latexindent/LatexIndent/GetYamlSettings.pm b/support/latexindent/LatexIndent/GetYamlSettings.pm index 96577d28d0..23f5a70d85 100644 --- a/support/latexindent/LatexIndent/GetYamlSettings.pm +++ b/support/latexindent/LatexIndent/GetYamlSettings.pm @@ -67,6 +67,9 @@ sub yaml_read_settings { $logger->info("Reading defaultSettings.yaml from $FindBin::RealBin/defaultSettings.yaml"); my $myLibDir = dirname(__FILE__); + my ( $name, $dir, $ext ) = fileparse( $INC{"LatexIndent/GetYamlSettings.pm"}, "pm" ); + $dir =~ s/\/$//; + # if latexindent.exe is invoked from TeXLive, then defaultSettings.yaml won't be in # the same directory as it; we need to navigate to it if ( !$defaultSettings ) { @@ -81,6 +84,9 @@ sub yaml_read_settings { elsif ( -e "$FindBin::RealBin/LatexIndent/defaultSettings.yaml" ) { $defaultSettings = YAML::Tiny->read("$FindBin::RealBin/LatexIndent/defaultSettings.yaml"); } + elsif ( -e "$dir/defaultSettings.yaml" ) { + $defaultSettings = YAML::Tiny->read("$dir/defaultSettings.yaml"); + } elsif ( -e "$myLibDir/defaultSettings.yaml" ) { +$defaultSettings = YAML::Tiny->read("$myLibDir/defaultSettings.yaml"); } diff --git a/support/latexindent/LatexIndent/Version.pm b/support/latexindent/LatexIndent/Version.pm index 5c9cd5c2ae..04aaf11759 100644 --- a/support/latexindent/LatexIndent/Version.pm +++ b/support/latexindent/LatexIndent/Version.pm @@ -20,6 +20,6 @@ use warnings; use Exporter qw/import/; our @EXPORT_OK = qw/$versionNumber $versionDate/; -our $versionNumber = '3.18'; -our $versionDate = '2022-06-12'; +our $versionNumber = '3.19'; +our $versionDate = '2022-10-30'; 1 diff --git a/support/latexindent/README b/support/latexindent/README index 7a48e5607f..44ef79a17e 100644 --- a/support/latexindent/README +++ b/support/latexindent/README @@ -1,5 +1,5 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - latexindent.pl, version 3.18, 2022-06-12 + latexindent.pl, version 3.19, 2022-10-30 PERL script to indent code within environments, and align delimited environments in .tex files. @@ -24,9 +24,14 @@ FOR COMPLETE DETAILS, PLEASE SEE documentation/latexindent.pdf -Note: latexindent.exe was created using +Note: The standalone executable files (in the bin directory) are created using commands + such as the following: - perl ppp.pl -u -o latexindent.exe latexindent.pl + pp + --addfile="defaultSettings.yaml;lib/LatexIndent/defaultSettings.yaml" + --cachedeps=scancache + --output latexindent-linux + latexindent.pl using the Par::Packer perl module. @@ -43,15 +48,14 @@ USAGE * IMPORTANT * -This script may not work for your style of formatting; I highly -recommend comparing the outputfile.tex to make sure that +This script may not work for your style of formatting; I highly +recommend that when you first use the script you use the `-o` switch +to output to a separate file; something like + + latexindent.pl myfile.tex -o myfile-output.tex + +and then check `myfile-output.tex` carefully to make sure that nothing has been changed (or removed) in a way that will damage your file. -I recommend both using the following: - - a visual check, at the very least, make sure that - each file has the same number of lines - - a check using latexdiff inputfile.tex outputfile.tex - - git status myfile.tex - %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/support/latexindent/bin/linux/latexindent b/support/latexindent/bin/linux/latexindent new file mode 100644 index 0000000000..1533c2587d Binary files /dev/null and b/support/latexindent/bin/linux/latexindent differ diff --git a/support/latexindent/bin/macos/latexindent b/support/latexindent/bin/macos/latexindent new file mode 100644 index 0000000000..3207ce9a2b Binary files /dev/null and b/support/latexindent/bin/macos/latexindent differ diff --git a/support/latexindent/defaultSettings.yaml b/support/latexindent/defaultSettings.yaml index 5f10f499bf..91f6fb9a70 100644 --- a/support/latexindent/defaultSettings.yaml +++ b/support/latexindent/defaultSettings.yaml @@ -1,4 +1,4 @@ -# defaultSettings.yaml for latexindent.pl, version 3.18, 2022-06-12 +# defaultSettings.yaml for latexindent.pl, version 3.19, 2022-10-30 # a script that aims to # beautify .tex, .sty, .cls files # diff --git a/support/latexindent/documentation/cmhlistings.tex b/support/latexindent/documentation/cmhlistings.tex deleted file mode 100644 index 6b8506c344..0000000000 --- a/support/latexindent/documentation/cmhlistings.tex +++ /dev/null @@ -1,35 +0,0 @@ -\newcommand{\cmhlistingsfromfile}[4]{ -.. literalinclude:: #1^^J -^^I:class: .#4^^J -^^I:caption: #2^^J -^^I:name: #3^^J -} -\newcommand{\cmhlistingsfromfilelines}[4]{ -.. literalinclude:: #1^^J -^^I:class: .#4^^J -^^I:caption: #2^^J -^^I:name: #3^^J -^^I:linenos:^^J -} -\newcommand{\cmhlistingsfromfilefour}[6]{ -.. literalinclude:: #3^^J -^^I:class: .#6^^J -^^I:caption: #4^^J -^^I:name: #5^^J -^^I:lines: #1-#2^^J -^^I:linenos:^^J -^^I:lineno-start: #1^^J -} -\newcommand{\cmhlabel}[1]{ -.. \_#1:^^J -} -\newcommand{\warning}[1]{ -.. warning::^^J -#1^^J -.. endwarning::^^J -} -\newcommand{\example}[1]{ -.. proof:example::^^J -#1^^J -.. endproof:example::^^J -} diff --git a/support/latexindent/documentation/contributors.bib b/support/latexindent/documentation/contributors.bib new file mode 100644 index 0000000000..4b7af4f8da --- /dev/null +++ b/support/latexindent/documentation/contributors.bib @@ -0,0 +1,176 @@ +% 2013 +% 2013 +% 2013 +@online{paulo, + title = "arara rule, indent.yaml", + url = "https://github.com/islandoftex/arara/blob/master/rules/arara-rule-indent.yaml", + author = "Paulo Cereda", + date = {2013-05-23}, + urldate = {2021-03-19}, + keywords = {contributor},} +@online{vosskuhle, + title = "Remove trailing white space", + url = "https://github.com/cmhughes/latexindent.pl/pull/12", + author = "Michel Vo{\ss}kuhle", + date = {2013-11-10}, + urldate = {2017-01-23}, + keywords = {contributor},} +@online{harish, + title = "Early version testing", + url = "https://github.com/harishkumarholla", + author = "Harish Kumar", + date = {2013-11-10}, + urldate = {2017-06-30}, + keywords = {contributor},} +% 2014 +% 2014 +% 2014 +@online{jacobo-diaz-hidden-config, + title = "Hiddenconfig", + url = "https://github.com/cmhughes/latexindent.pl/pull/18", + author = "Jacobo Diaz", + date = {2014-07-21}, + urldate = {2017-01-23}, + keywords = {contributor},} +@online{jacobo-diaz-she-bang, + title = "Changed shebang to make the script more portable", + url = "https://github.com/cmhughes/latexindent.pl/pull/17", + author = "Jacobo Diaz", + date = {2014-07-23}, + urldate = {2017-01-23}, + keywords = {contributor},} +% 2015 +% 2015 +% 2015 +@online{jasjuang, + title = "add in PATH installation", + url = "https://github.com/cmhughes/latexindent.pl/pull/38", + author = "Jason Juang", + date = {2015-11-24}, + urldate = {2017-01-23}, + keywords = {contributor},} +% 2017 +% 2017 +% 2017 +@online{jowens, + title = "Paragraph line break routine removal", + url = "https://github.com/cmhughes/latexindent.pl/issues/33", + author = "John Owens", + date = {2017-05-27}, + urldate = {2017-05-27}, + keywords = {contributor},} +@online{mlep, + title = "One sentence per line", + url = "https://github.com/cmhughes/latexindent.pl/issues/81", + date = {2017-08-16}, + author = "mlep", + urldate = {2018-01-08}, + keywords = {contributor},} +% 2018 +% 2018 +% 2018 +@online{zoehneto, + title = "Improving text wrap", + url = "https://github.com/cmhughes/latexindent.pl/issues/103", + author = "Tom Z{\"o}hner (zoehneto)", + date = {2018-02-04}, + urldate = {2018-08-04}, + keywords = {contributor},} +@online{xu-cheng, + title = "always output log/help text to STDERR", + url = "https://github.com/cmhughes/latexindent.pl/pull/121", + author = "Cheng Xu (xu-cheng)", + date = {2018-07-13}, + urldate = {2018-08-05}, + keywords = {contributor},} +% 2019 +% 2019 +% 2019 +@online{sransara, + title = "Print usage tip to STDERR only if STDIN is TTY" , + url = "https://github.com/cmhughes/latexindent.pl/pull/174", + date = {2019-09-17}, + author = "Sam Abey", + urldate = {2021-03-19}, + keywords = {contributor},} +% 2020 +% 2020 +% 2020 +@online{jun-sheaf, + title = "Alpine-linux instructions", + url = "https://github.com/cmhughes/latexindent.pl/pull/214", + date = {2020-08-10}, + author = "Randolf J.", + urldate = {2020-08-10}, + keywords = {contributor},} +@online{jeanlego, + title = "Search localSettings in CWD as well", + url = "https://github.com/cmhughes/latexindent.pl/pull/221", + date = {2020-09-15}, + author = "jeanlego", + urldate = {2021-03-19}, + keywords = {contributor},} +% 2021 +% 2021 +% 2021 +@online{newptcai, + title = "Update appendices.tex", + url = "https://github.com/cmhughes/latexindent.pl/pull/221", + date = {2021-02-16}, + author = "newptcai", + urldate = {2021-03-19}, + keywords = {contributor},} +@online{alexreg, + title = "Update help screen", + url = "https://github.com/cmhughes/latexindent.pl/pull/261", + date = {2021-03-18}, + author = "Alexander Regueiro", + urldate = {2021-03-19}, + keywords = {contributor},} +@online{qiancy98, + title = "Locale encoding of file system", + url = "https://github.com/cmhughes/latexindent.pl/pull/273", + date = {2021-05-06}, + author = "qiancy98", + urldate = {2021-05-06}, + keywords = {contributor},} +@online{XuehaiPan, + title = "Verbatim block upgrade", + url = "https://github.com/cmhughes/latexindent.pl/pull/290", + date = {2021-10-03}, + author = "XuehaiPan", + urldate = {2021-10-03}, + keywords = {contributor},} +@online{XuehaiPan1, + title = "-y switch upgrade", + url = "https://github.com/cmhughes/latexindent.pl/pull/297", + date = {2021-11-12}, + author = "XuehaiPan", + urldate = {2021-11-12}, + keywords = {contributor},} +% 2022 +% 2022 +% 2022 +@online{tdegeusprecommit, + title = "Adding Perl installation + pre-commit hook", + url = "https://github.com/cmhughes/latexindent.pl/pull/322", + date = {2022-01-21}, + author = "Tom de Geus", + urldate = {2022-01-21}, + keywords = {contributor},} + +@online{holzhausprecommit, + title = "Fix pre-commit usage", + url = "https://github.com/cmhughes/latexindent.pl/pull/354", + date = {2022-03-31}, + author = "Jan Holthuis", + urldate = {2022-04-02}, + keywords = {contributor},} + +@online{eggplants, + title = "Add Dockerfile and its updater/releaser", + url = "https://github.com/cmhughes/latexindent.pl/pull/370", + date = {2022-06-12}, + author = "eggplants", + urldate = {2022-06-12}, + keywords = {contributor},} diff --git a/support/latexindent/documentation/figure-schematic.tex b/support/latexindent/documentation/figure-schematic.tex deleted file mode 100644 index 08fea69139..0000000000 --- a/support/latexindent/documentation/figure-schematic.tex +++ /dev/null @@ -1,31 +0,0 @@ -\documentclass{standalone} -\usepackage{tikz} -\usetikzlibrary{positioning} -\begin{document} -\begin{tikzpicture}[ - needed/.style={very thick, draw=blue,fill=blue!20, text centered, minimum height=2.5em,rounded corners=1ex}, - optional/.style={draw=black, very thick,scale=0.8, text centered, minimum height=2.5em,rounded corners=1ex}, - optionalfill/.style={fill=black!10}, - connections/.style={draw=black!30,dotted,line width=3pt,text=red}, - ] - % Draw diagram elements - \node (latexindent) [needed,circle] {\texttt{latexindent.pl}}; - \node (default) [needed,above right=.5cm of latexindent] {\texttt{defaultSettings.yaml}}; - \node (indentconfig) [optional,right=of latexindent] {\texttt{indentconfig.yaml}}; - \node (any) [optional,optionalfill,above right=of indentconfig] {\texttt{any.yaml}}; - \node (name) [optional,optionalfill,right=of indentconfig] {\texttt{name.yaml}}; - \node (you) [optional,optionalfill,below right=of indentconfig] {\texttt{you.yaml}}; - \node (want) [optional,optionalfill,below=of indentconfig] {\texttt{want.yaml}}; - \node (local) [optional,below=of latexindent] {\texttt{localSettings.yaml}}; - \node (yamlswitch) [optional,left=of latexindent] {\texttt{-y switch}}; - % Draw arrows between elements - \draw[connections,solid] (latexindent) to[in=-90]node[pos=0.5,anchor=north]{1} (default.south) ; - \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{2} (indentconfig) ; - \draw[connections,optional] (indentconfig) to[in=-90] (any.south) ; - \draw[connections,optional] (indentconfig) -- (name) ; - \draw[connections,optional] (indentconfig) to[out=-45,in=90] (you) ; - \draw[connections,optional] (indentconfig) -- (want) ; - \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=west]{3} (local) ; - \draw[connections,optional] (latexindent) -- node[pos=0.5,anchor=north]{4} (yamlswitch) ; -\end{tikzpicture} -\end{document} diff --git a/support/latexindent/documentation/latex-indent.bib b/support/latexindent/documentation/latex-indent.bib new file mode 100644 index 0000000000..34d0dc3120 --- /dev/null +++ b/support/latexindent/documentation/latex-indent.bib @@ -0,0 +1,138 @@ +@online{cmh:videodemo, + title = "Video demonstration of latexindent.pl on youtube", + url = "https://www.youtube.com/watch?v=wo38aaH2F4E&spfreload=10", + urldate = {2017-02-21}, + keywords = {other}, +} +@online{cpan, + title = "CPAN: Comprehensive Perl Archive Network", + urldate = {2017-01-23}, + url = "http://www.cpan.org/", + keywords = {perl}, +} +@online{strawberryperl, + title = "Strawberry Perl", + urldate = {2017-01-23}, + url = "http://strawberryperl.com/", + keywords = {perl}, +} +@online{cmhblog, + title = "A Perl script for indenting tex files", + urldate = {2017-01-23}, + url = "http://tex.blogoverflow.com/2012/08/a-perl-script-for-indenting-tex-files/", + keywords = {other}, +} +@online{latexindent-home, + title = "Home of latexindent.pl", + urldate = {2017-01-23}, + url = "https://github.com/cmhughes/latexindent.pl", + keywords = {other}, +} +@online{perlbrew, + title = "Perlbrew", + urldate = {2017-01-23}, + url = "http://perlbrew.pl/", + keywords = {perl}, +} +@online{textwrap, + title = "Text::Wrap Perl module", + url = "http://perldoc.perl.org/Text/Wrap.html", + urldate = {2017-05-01}, + keywords = {perl}, +} +@online{texttabs, + title = "Text::Tabs Perl module", + url = "http://search.cpan.org/~muir/Text-Tabs+Wrap-2013.0523/lib.old/Text/Tabs.pm", + urldate = {2017-07-06}, + keywords = {perl}, +} +@online{log4perl, + title = "Log4perl Perl module", + url = "http://search.cpan.org/~mschilli/Log-Log4perl-1.49/lib/Log/Log4perl.pm", + urldate = {2017-09-24}, + keywords = {perl}, +} +@book{masteringregexp, + title = "Mastering Regular Expressions", + author = {Jeffrey E. F. Friedl}, + ISBN = {0596002890}, + keywords = {perl}, +} +@online{encoding, + title = "perldoc Encode::Supported", + url = "https://perldoc.perl.org/Encode::Supported", + urldate = {2021-05-06}, + keywords = {perl}, +} +@online{bersbersbers, + title = "Windows line breaks on Linux prevent removal of white space from end of line", + url = "https://github.com/cmhughes/latexindent.pl/issues/256", + urldate = {2021-06-18}, + keywords = {other}, +} +@online{dumper, + title = "Data::Dumper module", + url = "https://perldoc.perl.org/Data::Dumper", + urldate = {2021-06-18}, + keywords = {perl}, +} +@online{dumperdemo, + title = "Data Dumper demonstration", + url = "https://stackoverflow.com/questions/7466825/how-do-you-sort-the-output-of-datadumper", + urldate = {2021-06-18}, + keywords = {perl}, +} +@online{conda, + title = "conda forge", + url = "https://github.com/conda-forge/miniforge", + urldate = {2021-12-22}, + keywords = {conda}, +} +@online{anacoda, + title = "anacoda", + url = "https://www.anaconda.com/products/individual", + urldate = {2021-12-22}, + keywords = {conda}, +} +@online{condainstallubuntu, + title = "How to install Anaconda on Ubuntu?", + url = "https://askubuntu.com/questions/505919/how-to-install-anaconda-on-ubuntu", + urldate = {2022-01-21}, + keywords = {conda}, +} +@online{condainstallhelp, + title = "Solving environment: failed with initial frozen solve. Retrying with flexible solve.", + url = "https://github.com/conda/conda/issues/9367#issuecomment-558863143", + urldate = {2022-01-21}, + keywords = {conda}, +} +@online{vscode-yaml-demo, + title = "How to create your own auto-completion for JSON and YAML files on VS Code with the help of JSON Schema", + url = "https://dev.to/brpaz/how-to-create-your-own-auto-completion-for-json-and-yaml-files-on-vs-code-with-the-help-of-json-schema-k1i", + urldate = {2022-01-01}, + keywords = {vscode}, +} +@online{vscode-yaml-extentions, + title = "VSCode YAML extension", + url = "https://marketplace.visualstudio.com/items?itemName = redhat.vscode-yaml", + urldate = {2022-01-01}, + keywords = {vscode}, +} +@online{miktex-guide, + title = "How to use latexindent on Windows?", + url = "https://tex.stackexchange.com/questions/577250/how-to-use-latexindent-on-windows", + urldate = {2022-01-08}, + keywords = {other}, +} +@online{pre-commithome, + title = "pre-commit: A framework for managing and maintaining multi-language pre-commit hooks.", + url = "https://pre-commit.com/", + urldate = {2022-01-08}, + keywords = {other}, +} +@online{cmhughesio, + title = "latexindent.pl ghcr (GitHub Container Repository) location", + url = "https://github.com/cmhughes?tab=packages", + urldate = {2022-06-12}, + keywords = {other}, +} diff --git a/support/latexindent/documentation/latexindent-yaml-schema.json b/support/latexindent/documentation/latexindent-yaml-schema.json index 8fe129d18a..26a9a63798 100644 --- a/support/latexindent/documentation/latexindent-yaml-schema.json +++ b/support/latexindent/documentation/latexindent-yaml-schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/schema", "$id": "latexindent-yaml-schema.json", "title": "latexindent.pl YAML schema", - "description": "latexindent.pl YAML schema helper, V3.18 2022-06-12", + "description": "latexindent.pl YAML schema helper, V3.19 2022-10-30", "type": "object", "properties": { "fileExtensionPreference": { diff --git a/support/latexindent/documentation/latexindent.pdf b/support/latexindent/documentation/latexindent.pdf index 04b5d2ef38..f42e874c8c 100644 Binary files a/support/latexindent/documentation/latexindent.pdf and b/support/latexindent/documentation/latexindent.pdf differ diff --git a/support/latexindent/documentation/latexindent.tex b/support/latexindent/documentation/latexindent.tex index 2bfe0248d1..4d7a6dd87b 100644 --- a/support/latexindent/documentation/latexindent.tex +++ b/support/latexindent/documentation/latexindent.tex @@ -604,8 +604,6 @@ {\endlist\endstars} {\item} -\newtcbox{yamltitlebox}[1][]{colframe=black!50!white,boxrule=.5pt,sharp corners,#1} - \newcommand{\flagbox}[1]{% \par \makebox[30pt][l]{% @@ -618,7 +616,7 @@ \par \makebox[30pt][l]{% \hspace{-2cm}% - \yamltitlebox[#1]{% + \tcbox[colframe=black!50!white,boxrule=.5pt,sharp corners,#1]{% {\ttfamily\fontseries{b}\selectfont{\color{blue!80!white}#2}}: % \IfBooleanTF{#3} {$\langle$\itshape #4$\rangle$} @@ -792,41 +790,7198 @@ %\testdefaultsettingstrue \begin{document} -\renewcommand*{\thefootnote}{\arabic{footnote}} -\input{title.tex} -\tableofcontents -% start sections on new page -\newcommand{\sectionbreak}{\clearpage\thispagestyle{plain}} - \iftestdefaultsettings - \input{test-default-settings} - \else - \input{sec-introduction} - \input{sec-demonstration} - \input{sec-how-to-use} - \input{sec-indent-config-and-settings.tex} - \input{sec-default-user-local} - \input{subsec-noAdditionalIndent-indentRules} - \input{subsubsec-environments-and-their-arguments} - \input{subsubsec-environments-with-items} - \input{subsubsec-commands-with-arguments} - \input{subsubsec-ifelsefi} - \input{subsubsec-special} - \input{subsubsec-headings} - \input{subsubsec-no-add-remaining-code-blocks} - \stopcontents[noAdditionalIndent] - \input{subsec-commands-and-their-options} - \input{sec-the-m-switch} - \input{subsec-text-wrap} - \input{subsec-one-sentence-per-line} - \input{subsec-poly-switches} - \stopcontents[the-m-switch] - \input{sec-replacements} - \input{sec-the-line-switch} - \input{sec-fine-tuning} - \input{sec-conclusions-know-limitations} - \input{sec-references} - \input{sec-appendices} - {\clearpage\addcontentsline{toc}{section}{List of listings}\small\lstlistoflistings} - \printindex - \fi +% arara: pdflatex: { files: [latexindent]} +\section{Introduction} +\subsection{Thanks} + I first created \texttt{latexindent.pl} to help me format chapter files in a big project. + After I blogged about it on the \TeX{} stack exchange \cite{cmhblog} I received some + positive feedback and follow-up feature requests. A big thank you to Harish Kumar + \cite{harish} who helped to develop and test the initial versions of the script. + + The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired by the + wonderful \texttt{arara} tool; any similarities are deliberate, and I hope that it is + perceived as the compliment that it is. Thank you to Paulo Cereda and the team for + releasing this awesome tool; I initially worried that I was going to have to make a GUI + for \texttt{latexindent.pl}, but the release of \texttt{arara} has meant there is no + need. + + There have been several contributors to the project so far (and hopefully more in the + future!); thank you very much to the people detailed in \vref{sec:contributors} for their + valued contributions, and thank you to those who report bugs and request features at + \cite{latexindent-home}. + +\subsection{License} + \texttt{latexindent.pl} is free and open source, and it always will be; it + is released under the GNU General Public License v3.0. + + Before you start using it on any important files, bear in mind that + \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. It will + always make at least one backup (you can choose how many it makes, see + \cpageref{page:onlyonebackup}) but you should still be careful when using it. The script + has been tested on many files, but there are some known limitations (see + \cref{sec:knownlimitations}). You, the user, are responsible for ensuring that you + maintain backups of your files before running \texttt{latexindent.pl} on them. I think it + is important at this stage to restate an important part of the license here: + \begin{quote}\itshape + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + \end{quote} + There is certainly no malicious intent in releasing this script, and I do hope that it + works as you expect it to; if it does not, please first of all make sure that you have + the correct settings, and then feel free to let me know at \cite{latexindent-home} with a + complete minimum working example as I would like to improve the code as much as possible. + + \begin{warning} + Before you try the script on anything important (like your thesis), test it out on the + sample files in the \texttt{test-case} directory \cite{latexindent-home}. + \index{warning!be sure to test before use} + \end{warning} + + \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there + are a few changes to the interface; see \vref{app:differences} and the comments + throughout this document for details}. + +\subsection{Quick start}\label{sec:quickstart} + If you'd like to get started with \texttt{latexindent.pl} then simply type + \begin{commandshell} +latexindent.pl myfile.tex +\end{commandshell} + from the command line. + + We give an introduction to \texttt{latexindent.pl} using \cref{lst:quick-start}; there is + no explanation in this section, which is deliberate for a quick start. The rest of the + manual is more verbose. + + \cmhlistingsfromfile{demonstrations/quick-start.tex}{\texttt{quick-start.tex}}{lst:quick-start} + + Running + \begin{commandshell} +latexindent.pl quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-default}. + + \cmhlistingsfromfile{demonstrations/quick-start-default.tex}{\texttt{quick-start-default.tex}}{lst:quick-start-default} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -l quick-start1.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod1}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start1.yaml}[yaml-TCB]{\texttt{quick-start1.yaml}}{lst:quick-start1yaml} + \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod1.tex}{\texttt{quick-start-mod1.tex}}{lst:quick-start-mod1} + \end{cmhtcbraster} + \end{example} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -l quick-start2.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod2}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start2.yaml}[yaml-TCB]{\texttt{quick-start2.yaml}}{lst:quick-start2yaml} + \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod2.tex}{\texttt{quick-start-mod2.tex}}{lst:quick-start-mod2} + \end{cmhtcbraster} + \end{example} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -l quick-start3.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod3}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start3.yaml}[yaml-TCB]{\texttt{quick-start3.yaml}}{lst:quick-start3yaml} + \cmhlistingsfromfile{demonstrations/quick-start-mod3.tex}{\texttt{quick-start-mod3.tex}}{lst:quick-start-mod3} + \end{cmhtcbraster} + \end{example} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -m -l quick-start4.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod4}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start4.yaml}[MLB-TCB]{\texttt{quick-start4.yaml}}{lst:quick-start4yaml} + \cmhlistingsfromfile{demonstrations/quick-start-mod4.tex}{\texttt{quick-start-mod4.tex}}{lst:quick-start-mod4} + \end{cmhtcbraster} + Full details of text wrapping in \cref{subsec:textwrapping}. + \end{example} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -m -l quick-start5.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod5}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start5.yaml}[MLB-TCB]{\texttt{quick-start5.yaml}}{lst:quick-start5yaml} + \cmhlistingsfromfile{demonstrations/quick-start-mod5.tex}{\texttt{quick-start-mod5.tex}}{lst:quick-start-mod5} + \end{cmhtcbraster} + Full details of text wrapping in \cref{subsec:textwrapping}. + \end{example} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -m -l quick-start6.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod6}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start6.yaml}[MLB-TCB]{\texttt{quick-start6.yaml}}{lst:quick-start6yaml} + \cmhlistingsfromfile{demonstrations/quick-start-mod6.tex}{\texttt{quick-start-mod6.tex}}{lst:quick-start-mod6} + \end{cmhtcbraster} + This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are + covered in \cref{sec:poly-switches}. + \end{example} + + \begin{example} + Running + \begin{commandshell} +latexindent.pl -m -l quick-start7.yaml quick-start.tex +\end{commandshell} + gives \cref{lst:quick-start-mod7}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/quick-start7.yaml}[MLB-TCB]{\texttt{quick-start7.yaml}}{lst:quick-start7yaml} + \cmhlistingsfromfile{demonstrations/quick-start-mod7.tex}{\texttt{quick-start-mod7.tex}}{lst:quick-start-mod7} + \end{cmhtcbraster} + Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. + \end{example} + +\subsection{Required perl modules} + If you receive an error message such as that given in + \cref{lst:poss-errors}, then you need to install the missing perl modules. + \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors} +Can't locate File/HomeDir.pm in @INC (@INC contains: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at helloworld.pl line 10. +BEGIN failed--compilation aborted at helloworld.pl line 10. +\end{cmhlistings} + \texttt{latexindent.pl} ships with a script to help with this process; if you run the + following script, you should be prompted to install the appropriate modules. + \begin{commandshell} +perl latexindent-module-installer.pl +\end{commandshell} + You might also like to see + \href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}, + for example, as well as \vref{sec:requiredmodules}. + +\subsection{About this documentation} + As you read through this documentation, you will see many listings; in this version of + the documentation, there are a total of \totallstlistings. This may seem a lot, but I + deem it necessary in presenting the various different options of \texttt{latexindent.pl} + and the associated output that they are capable of producing. + + The different listings are presented using different styles: + + \begin{minipage}{.4\textwidth} + \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex} + \end{minipage}% + \hfill + \begin{minipage}{.4\textwidth} + This type of listing is a \texttt{.tex} file. + \end{minipage}% + + \begin{minipage}{.4\textwidth} + \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\textwidth} + This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here) + it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in + detail in \vref{sec:defuseloc}. + \end{minipage}% + + \begin{minipage}{.55\textwidth} + \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\textwidth} + This type of listing is a \texttt{.yaml} file, but it will only + be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks} + for more details. + \end{minipage}% + + \begin{minipage}{.55\textwidth} + \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} + \end{minipage}% + \hfill + \begin{minipage}{.4\textwidth} + This type of listing is a \texttt{.yaml} file, but it will only + be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} + for more details. + \end{minipage}% + + % \begin{latexonly} + You will occasionally see dates shown in the margin (for example, next to this + paragraph!) \announce{2017-06-25}{announce} which detail the date of the version in which + the feature was implemented; the `N' stands for `new as of the date shown' and `U' stands + for `updated as of the date shown'. If you see \stardemo, it means that the feature is + either new (N) or updated (U) as of the release of the current version; if you see + \stardemo\, attached to a listing, then it means that listing is new (N) or updated (U) + as of the current version. If you have not read this document before (and even if you + have!), then you can ignore every occurrence of the \stardemo; they are simply there to + highlight new and updated features. The new and updated features in this documentation + (\gitRel) are on the following pages: \listOfNewFeatures% % \end{latexonly} + +\subsection{A word about regular expressions} + \index{regular expressions!a word about} + As you read this documentation, you may encounter the term \emph{regular expressions}. + I've tried to write this documentation in such a way so as to allow you to engage with + them or not, as you prefer. This documentation is not designed to be a guide to regular + expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}. +% arara: pdflatex: { files: [latexindent]} +\section{Demonstration: before and after} + Let's give a demonstration of some before and after code -- after all, you probably won't + want to try the script if you don't much like the results. You might also like to watch + the video demonstration I made on youtube \cite{cmh:videodemo} + + As you look at \crefrange{lst:filecontentsbefore}{lst:pstricksafter}, remember that + \texttt{latexindent.pl} is just following its rules, and there is nothing particular + about these code snippets. All of the rules can be modified so that you can personalise + your indentation scheme. + + In each of the samples given in \crefrange{lst:filecontentsbefore}{lst:pstricksafter} the + `before' case is a `worst case scenario' with no effort to make indentation. The `after' + result would be the same, regardless of the leading white space at the beginning of each + line which is stripped by \texttt{latexindent.pl} (unless a \texttt{verbatim}-like + environment or \texttt{noIndentBlock} is specified -- more on this in + \cref{sec:defuseloc}). + + \begin{widepage} + \centering + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/filecontents1.tex}{\texttt{filecontents1.tex}}{lst:filecontentsbefore} + \end{minipage}\hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/filecontents1-default.tex}{\texttt{filecontents1.tex} default output}{lst:filecontentsafter} + \end{minipage}% + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/tikzset.tex}{\texttt{tikzset.tex}}{lst:tikzsetbefore} + \end{minipage}\hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/tikzset-default.tex}{\texttt{tikzset.tex} default output}{lst:tikzsetafter} + \end{minipage}% + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/pstricks.tex}{\texttt{pstricks.tex}}{lst:pstricksbefore} + \end{minipage}\hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/pstricks-default.tex}{\texttt{pstricks.tex} default output}{lst:pstricksafter} + \end{minipage}% + \end{widepage} + +% arara: pdflatex: { files: [latexindent]} +\section{How to use the script}\label{sec:how:to:use} + \texttt{latexindent.pl} ships as part of the \TeX Live distribution for + Linux and Mac users; \texttt{latexindent.exe} ships as part of the \TeX Live for Windows + users. These files are also available from github \cite{latexindent-home} should you wish + to use them without a \TeX{} distribution; in this case, you may like to read + \vref{sec:updating-path} which details how the \texttt{path} variable can be updated. + \index{TeXLive} + + In what follows, we will always refer to \texttt{latexindent.pl}, but depending on your + operating system and preference, you might substitute \texttt{latexindent.exe} or simply + \texttt{latexindent}. + + There are two ways to use \texttt{latexindent.pl}: from the command line, and using + \texttt{arara}; we discuss these in \cref{sec:commandline} and \cref{sec:arara} + respectively. We will discuss how to change the settings and behaviour of the script in + \vref{sec:defuseloc}. + +\subsection{Requirements} +\subsubsection{Perl users} + Perl users will need a few standard Perl modules -- see \vref{sec:requiredmodules} for + details; \announce{2018-01-13}{perl module installer helper script} in particular, note + that a module installer helper script is shipped with \texttt{latexindent.pl}.% + +\subsubsection{Windows users without perl}\label{subsubsec:latexindent:exe} + \texttt{latexindent.pl} ships with \texttt{latexindent.exe} for Windows + users, so that you can use the script with or without a Perl distribution. + + \texttt{latexindent.exe} is available from \cite{latexindent-home}. + + MiKTeX users on Windows may like to see \cite{miktex-guide} for details of how to use + \texttt{latexindent.exe} without a Perl installation. \index{MiKTeX} + \index{latexindent.exe} \index{Windows} + +\subsubsection{Ubuntu Linux users without perl} + \texttt{latexindent.pl} ships with \texttt{latexindent-linux} for Ubuntu + Linux users, so that you can use the script with or without a Perl distribution. + \index{latexindent-linux} \index{linux} \index{TeXLive} + + \texttt{latexindent-linux} is available from \cite{latexindent-home}. + \announce*{2022-10-30}{Linux Ubuntu standalone executable} + +\subsubsection{macOS users without perl} + \texttt{latexindent.pl} ships with \texttt{latexindent-macos} for macOS + users, so that you can use the script with or without a Perl distribution. + \index{latexindent-macos} \index{macOS} \index{TeXLive} + + \texttt{latexindent-macOS} is available from \cite{latexindent-home}. + \announce*{2022-10-30}{macOS standalone executable} + +\subsubsection{conda users} + Users of \texttt{conda} should see the details given in \cref{sec:app:conda}. + \index{conda} + +\subsubsection{docker users} + Users of \texttt{docker} should see the details given in \cref{sec:app:docker}. + \index{docker} + +\subsection{From the command line}\label{sec:commandline} + \texttt{latexindent.pl} has a number of different switches/flags/options, which + can be combined in any way that you like, either in short or long form as detailed below. + \texttt{latexindent.pl} produces a \texttt{.log} file, \texttt{indent.log}, every time it + is run; the name of the log file can be customised, but we will refer to the log file as + \texttt{indent.log} throughout this document. There is a base of information that is + written to \texttt{indent.log}, but other additional information will be written + depending on which of the following options are used. + +\flagbox{-v, --version} + \index{switches!-v, --version definition and details} + \announce{2017-06-25}{version} + \begin{commandshell} +latexindent.pl -v +latexindent.pl --version +\end{commandshell} + This will output only the version number to the terminal. + +\flagbox{-vv, --vversion} + \index{switches!-vv, --vversion definition and details} + \announce{2022-01-08}{vversion switch} + \begin{commandshell} +latexindent.pl -vv +latexindent.pl --vversion +\end{commandshell} + This will output \emph{verbose} version details to the terminal, including the location + of \texttt{latexindent.pl} and \texttt{defaultSettings.yaml}. + +\flagbox{-h, --help} + \index{switches!-h, --help definition and details} + + \begin{commandshell} +latexindent.pl -h +latexindent.pl --help +\end{commandshell} + + As above this will output a welcome message to the terminal, including the version number + and available options. + \begin{commandshell} +latexindent.pl myfile.tex +\end{commandshell} + + This will operate on \texttt{myfile.tex}, but will simply output to your terminal; + \texttt{myfile.tex} will not be changed by \texttt{latexindent.pl} in any way using this + command. + + You can \announce{2022-03-25}{batches of files demonstration} instruct + \texttt{latexindent.pl} to operate on multiple (batches) of files, for example + \begin{commandshell} +latexindent.pl myfile1.tex myfile2.tex +\end{commandshell} + Full details are given in \vref{sec:batches}. + +\flagbox{-w, --overwrite} + \index{switches!-w, --overwrite definition and details} + \index{backup files!overwrite switch, -w} + \begin{commandshell} +latexindent.pl -w myfile.tex +latexindent.pl --overwrite myfile.tex +latexindent.pl myfile.tex --overwrite +\end{commandshell} + + This \emph{will} overwrite \texttt{myfile.tex}, but it will make a copy of + \texttt{myfile.tex} first. You can control the name of the extension (default is + \texttt{.bak}), and how many different backups are made -- more on this in + \cref{sec:defuseloc}, and in particular see \texttt{backupExtension} and + \texttt{onlyOneBackUp}. + + Note that if \texttt{latexindent.pl} can not create the backup, then it will exit without + touching your original file; an error message will be given asking you to check the + permissions of the backup file. + +\flagbox{-wd, --overwriteIfDifferent} + \index{switches!-wd, --overwriteIfDifferent definition and details} + \index{backup files!overwriteIfDifferent switch, -wd} + \announce{2022-03-25}{overwriteIfDifferent switch} + \begin{commandshell} +latexindent.pl -wd myfile.tex +latexindent.pl --overwriteIfDifferent myfile.tex +latexindent.pl myfile.tex --overwriteIfDifferent +\end{commandshell} + + This \emph{will} overwrite \texttt{myfile.tex} but only \emph{if the indented text is + different from the original}. If the indented text is \emph{not} different from the + original, then \texttt{myfile.tex} will \emph{not} be overwritten. + + All other details from the \texttt{-w} switch are relevant here. If you call + \texttt{latexindent.pl} with both the \texttt{-wd} and the \texttt{-w} switch, then the + \texttt{-w} switch will be deactivated and the \texttt{-wd} switch takes priority. + +\flagbox{-o=output.tex,--outputfile=output.tex} + \index{switches!-o, --output definition and details} + \begin{commandshell} +latexindent.pl -o=output.tex myfile.tex +latexindent.pl myfile.tex -o=output.tex +latexindent.pl --outputfile=output.tex myfile.tex +latexindent.pl --outputfile output.tex myfile.tex +\end{commandshell} + + This will indent \texttt{myfile.tex} and output it to \texttt{output.tex}, overwriting it + (\texttt{output.tex}) if it already exists\footnote{Users of version 2.* should note the + subtle change in syntax}. + + Note that if \texttt{latexindent.pl} is called with both the \texttt{-w} and \texttt{-o} + switches, then \texttt{-w} will be ignored and \texttt{-o} will take priority (this seems + safer than the other way round). The same is true for the \texttt{-wd} switch, and the + \texttt{-o} switch takes priority over it. + + Note that using \texttt{-o} as above is equivalent to using + \begin{commandshell} +latexindent.pl myfile.tex > output.tex +\end{commandshell} + + You can call the \texttt{-o} switch with the name of the output file \emph{without} an + extension; in \announce{2017-06-25}{upgrade to -o switch} this case, + \texttt{latexindent.pl} will use the extension from the original file. For example, the + following two calls to \texttt{latexindent.pl} are equivalent:% + \begin{commandshell} +latexindent.pl myfile.tex -o=output +latexindent.pl myfile.tex -o=output.tex +\end{commandshell} + + You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will + \announce{2017-06-25}{+ sign in o switch} concatenate the name of the input file and the + text given to the \texttt{-o} switch. For example, the following two calls to + \texttt{latexindent.pl} are equivalent:% + \begin{commandshell} +latexindent.pl myfile.tex -o=+new +latexindent.pl myfile.tex -o=myfilenew.tex +\end{commandshell} + + You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name + \announce{2017-06-25}{++ in o switch} of your output file; this tells + \texttt{latexindent.pl} to search successively for the name of your output file + concatenated with $0, 1, \ldots$ while the name of the output file exists. For example,% + \begin{commandshell} +latexindent.pl myfile.tex -o=output++ +\end{commandshell} + tells \texttt{latexindent.pl} to output to \texttt{output0.tex}, but if it exists then + output to \texttt{output1.tex}, and so on. + + Calling \texttt{latexindent.pl} with simply + \begin{commandshell} +latexindent.pl myfile.tex -o=++ +\end{commandshell} + tells it to output to \texttt{myfile0.tex}, but if it exists then output to + \texttt{myfile1.tex} and so on. + + The \texttt{+} and \texttt{++} feature of the \texttt{-o} switch can be combined; for + example, calling + \begin{commandshell} +latexindent.pl myfile.tex -o=+out++ +\end{commandshell} + tells \texttt{latexindent.pl} to output to \texttt{myfileout0.tex}, but if it exists, + then try \texttt{myfileout1.tex}, and so on. + + There is no need to specify a file extension when using the \texttt{++} feature, but if + you wish to, then you should include it \emph{after} the \texttt{++} symbols, for example + \begin{commandshell} +latexindent.pl myfile.tex -o=+out++.tex +\end{commandshell} + + See \vref{app:differences} for details of how the interface has changed from Version 2.2 + to Version 3.0 for this flag. \flagbox{-s, --silent} \index{switches!-s, --silent + definition and details} + \begin{commandshell} +latexindent.pl -s myfile.tex +latexindent.pl myfile.tex -s +\end{commandshell} + + Silent mode: no output will be given to the terminal. + +\flagbox{-t, --trace} + \index{switches!-t, --trace definition and details} + \begin{commandshell} +latexindent.pl -t myfile.tex +latexindent.pl myfile.tex -t +\end{commandshell} + + \label{page:traceswitch} + Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if + \texttt{latexindent.pl} has made a mistake and you're trying to find out where and why. + You might also be interested in learning about \texttt{latexindent.pl}'s thought process + -- if so, this switch is for you, although it should be noted that, especially for large + files, this does affect performance of the script. + +\flagbox{-tt, --ttrace} + \index{switches!-tt, --ttrace definition and details} + \begin{commandshell} +latexindent.pl -tt myfile.tex +latexindent.pl myfile.tex -tt +\end{commandshell} + + \emph{More detailed} tracing mode: this option gives more details to + \texttt{indent.log} + than the standard \texttt{trace} option (note that, even more so than with \texttt{-t}, + especially for large files, performance of the script will be affected). + +\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]} + \index{switches!-l, --local definition and details} + \begin{commandshell} +latexindent.pl -l myfile.tex +latexindent.pl -l=myyaml.yaml myfile.tex +latexindent.pl -l myyaml.yaml myfile.tex +latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex +latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex +latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml +\end{commandshell} + + \label{page:localswitch} + \texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with + camel) and if it is called with the \texttt{-l} switch and it finds + \texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex}, then, if not + found, it looks for \texttt{localSettings.yaml} (and friends, see + \vref{sec:localsettings}) in the current working directory, then + these% + \announce{2021-03-14}*{-l switch: localSettings and + friends} settings will be added to the indentation scheme. Information will be given in + \texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}. + + The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or + names separated by commas) of a YAML file(s) that resides in the same directory as + \texttt{myfile.tex}; you can use this option if you would like to load a settings file in + the current working directory that is \emph{not} called \texttt{localSettings.yaml}. + \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both + \emph{relative} and \emph{absolute paths} for your YAML files; for example% + \begin{commandshell} +latexindent.pl -l=../../myyaml.yaml myfile.tex +latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex +latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex +\end{commandshell} + You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch + throughout this documentation, + + You can call the \texttt{-l} switch with a `+' symbol either before or after + \announce{2017-06-25}{+ sign with -l switch} another YAML file; for example: + \begin{commandshell} +latexindent.pl -l=+myyaml.yaml myfile.tex +latexindent.pl -l "+ myyaml.yaml" myfile.tex +latexindent.pl -l=myyaml.yaml+ myfile.tex +\end{commandshell} + which translate, respectively, to + \begin{commandshell} +latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex +latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex +latexindent.pl -l=myyaml.yaml,localSettings.yaml myfile.tex +\end{commandshell} + Note that the following is \emph{not} allowed: + \begin{commandshell} +latexindent.pl -l+myyaml.yaml myfile.tex +\end{commandshell} + and + \begin{commandshell} +latexindent.pl -l + myyaml.yaml myfile.tex +\end{commandshell} + will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be + ignored. If you wish to use spaces between any of the YAML settings, then you must wrap + the entire list of YAML files in quotes, as demonstrated above. + + You may also choose to omit the \texttt{yaml} extension, such as \announce{2017-06-25}{no + extension for -l switch}% + \begin{commandshell} +latexindent.pl -l=localSettings,myyaml myfile.tex +\end{commandshell} +\flagbox{-y, --yaml=yaml settings} + \index{switches!-y, --yaml definition and details} + \index{indentation!default} + \index{indentation!defaultIndent using -y switch} + \begin{commandshell} +latexindent.pl myfile.tex -y="defaultIndent: ' '" +latexindent.pl myfile.tex -y="defaultIndent: ' ',maximumIndentation:' '" +latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'" +latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3' -m +latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m +\end{commandshell} + \label{page:yamlswitch}You% + \announce{2017-08-21}{the -y switch} can specify YAML settings from the command line + using the \texttt{-y} or \texttt{--yaml} switch; sample demonstrations are given above. + Note, in particular, that multiple settings can be specified by separating them via + commas. There is a further option to use a \texttt{;} to separate fields, which is + demonstrated in \vref{sec:yamlswitch}. + + Any settings specified via this switch will be loaded \emph{after} any specified using + the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. \flagbox{-d, + --onlydefault} \index{switches!-d, --onlydefault definition and details} + \begin{commandshell} +latexindent.pl -d myfile.tex +\end{commandshell} + + Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before + using this switch. By default, \texttt{latexindent.pl} will always search for + \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you + would prefer it not to do so then (instead of deleting or renaming + \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply call the script + with the \texttt{-d} switch; note that this will also tell the script to ignore + \texttt{localSettings.yaml} even if it has been called with the \texttt{-l} switch; + \texttt{latexindent.pl} \announce{2017-08-21}*{updated -d switch} will also ignore any + settings specified from the \texttt{-y} switch.% + +\flagbox{-c, --cruft=} + \index{switches!-c, --cruft definition and details} + \begin{commandshell} +latexindent.pl -c=/path/to/directory/ myfile.tex +\end{commandshell} + + If you wish to have backup files and \texttt{indent.log} written to a directory other + than the current working directory, then you can send these `cruft' files to another + directory. Note the use of a trailing forward slash. % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory + +\flagbox{-g, --logfile=} + \index{switches!-g, --logfile definition and details} + \begin{commandshell} +latexindent.pl -g=other.log myfile.tex +latexindent.pl -g other.log myfile.tex +latexindent.pl --logfile other.log myfile.tex +latexindent.pl myfile.tex -g other.log +\end{commandshell} + + By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if + you wish to change the name of this file, simply call the script with your chosen name + after the \texttt{-g} switch as demonstrated above. + + \announce{2021-05-07}{log file creation updated} If \texttt{latexindent.pl} can not open + the log file that you specify, then the script will operate, and no log file will be + produced; this might be helpful to users who wish to specify the following, for example + \begin{commandshell} +latexindent.pl -g /dev/null myfile.tex +\end{commandshell} + +\flagbox{-sl, --screenlog} + \index{switches!-sl, --screenlog definition and details} + \begin{commandshell} +latexindent.pl -sl myfile.tex +latexindent.pl -screenlog myfile.tex +\end{commandshell} + Using this \announce{2018-01-13}{screenlog switch created} option tells + \texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen + log file.% + +\flagbox{-m, --modifylinebreaks} + \index{switches!-m, --modifylinebreaks definition and details} + \begin{commandshell} +latexindent.pl -m myfile.tex +latexindent.pl -modifylinebreaks myfile.tex +\end{commandshell} + + One of the most exciting developments in Version~3.0 is the ability to modify line + breaks; for full details see \vref{sec:modifylinebreaks} + + \texttt{latexindent.pl} can also be called on a file without the file extension, for + example + \begin{commandshell} +latexindent.pl myfile +\end{commandshell} + and in which case, you can specify the order in which extensions are searched for; see + \vref{lst:fileExtensionPreference} for full details. \flagbox{STDIN} + \begin{commandshell} +cat myfile.tex | latexindent.pl +cat myfile.tex | latexindent.pl - +\end{commandshell} + \texttt{latexindent.pl} will% + \announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can + pipe output from other commands directly into the script. For example assuming that you + have content in \texttt{myfile.tex}, then the above command will output the results of + operating upon \texttt{myfile.tex}. + + If you wish to use this feature with your own local settings, via the \texttt{-l} switch, + then you should finish your call to \texttt{latexindent.pl} with a \texttt{-} sign: + \begin{commandshell} +cat myfile.tex | latexindent.pl -l=mysettings.yaml - +\end{commandshell} + + Similarly, if you \announce{2018-01-13}*{no options/filename updated} simply type + \texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the + command line.% + \begin{commandshell} +latexindent.pl +\end{commandshell} + + Once you have finished typing your input, you can press + \begin{itemize} + \item \texttt{CTRL+D} on Linux + \item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows + \end{itemize} + to signify that your input has finished. Thanks to \cite{xu-cheng} for an update to this + feature. \flagbox{-r, --replacement} \index{switches!-r, --replacement definition and + details} + \begin{commandshell} +latexindent.pl -r myfile.tex +latexindent.pl -replacement myfile.tex +\end{commandshell} + You can \announce{2019-07-13}{replacement mode switch} call \texttt{latexindent.pl} with + the \texttt{-r} switch to instruct it to perform replacements/substitutions on your file; + full details and examples are given in \vref{sec:replacements}. \index{verbatim!rv, + replacementrespectverb switch}% + +\flagbox{-rv, --replacementrespectverb} + \index{switches!-rv, --replacementrespectverb definition and details} + \begin{commandshell} +latexindent.pl -rv myfile.tex +latexindent.pl -replacementrespectverb myfile.tex +\end{commandshell} + You can \announce{2019-07-13}{replacement mode switch, respecting verbatim} instruct + \texttt{latexindent.pl} to perform replacements/substitutions by using the \texttt{-rv} + switch, but will \emph{respect verbatim code blocks}; full details and examples are given + in \vref{sec:replacements}.% + +\flagbox{-rr, --onlyreplacement} + \index{switches!-rr, --onlyreplacement definition and details} + \begin{commandshell} +latexindent.pl -rr myfile.tex +latexindent.pl -onlyreplacement myfile.tex +\end{commandshell} + You can \announce{2019-07-13}{replacement (only) mode switch} instruct + \texttt{latexindent.pl} to skip all of its other indentation operations and \emph{only} + perform replacements/substitutions by using the \texttt{-rr} switch; full details and + examples are given in \vref{sec:replacements}.% + +\flagbox{-k, --check} + \index{switches!-k, --check definition and details} + \begin{commandshell} +latexindent.pl -k myfile.tex +latexindent.pl -check myfile.tex +\end{commandshell} + You can \announce{2021-09-16}{-k,-check switch} instruct \texttt{latexindent.pl} to check + if the text after indentation matches that given in the original file.% + + The \texttt{exit} code \index{exit code} of \texttt{latexindent.pl} is 0 by default. If + you use the \texttt{-k} switch then + \begin{itemize} + \item if the text after indentation matches that given in the original file, then the exit code + is 0; + \item if the text after indentation does \emph{not} match that given in the original file, then + the exit code is 1. + \end{itemize} + + The value of the exit code may be important to those wishing to, for example, check the + status of the indentation in continuous integration tools such as GitHub Actions. Full + details of the exit codes of \texttt{latexindent.pl} are given in \cref{tab:exit-codes}. + + A simple \texttt{diff} will be given in \texttt{indent.log}. + +\flagbox{-kv, --checkv} + \index{switches!-kv, --checkv definition and details} + \begin{commandshell} +latexindent.pl -kv myfile.tex +latexindent.pl -checkv myfile.tex +\end{commandshell} + \announce{2021-09-16}{-kv, -checkv: check verbose switch} The \texttt{check verbose} + switch is exactly the same as the \texttt{-k} switch, except that it is \emph{verbose}, + and it will output the (simple) diff to the terminal, as well as to \texttt{indent.log}. + +\flagbox{-n, --lines=MIN-MAX} + \index{switches!-n, --lines definition and details} + \begin{commandshell} +latexindent.pl -n 5-8 myfile.tex +latexindent.pl -lines 5-8 myfile.tex +\end{commandshell} + \announce{2021-09-16}{-n, -lines switch} The \texttt{lines} switch instructs + \texttt{latexindent.pl} to operate only on specific line ranges within + \texttt{myfile.tex}. + + Complete demonstrations are given in \cref{sec:line-switch}. + +\flagbox{--GCString} + \index{switches!--GCString} + \begin{commandshell} +latexindent.pl --GCString myfile.tex +\end{commandshell} + \announce{2022-03-25}{GCString switch} instructs \texttt{latexindent.pl} to load the + \texttt{Unicode::GCString} module. This should only be necessary if you find that the + alignment at ampersand routine (described in \cref{subsec:align-at-delimiters}) does not + work for your language. Further details are given in \cref{subsec:the-GCString}. + +\subsection{From arara}\label{sec:arara} + Using \texttt{latexindent.pl} from the command line is fine for some folks, but others + may find it easier to use from \texttt{arara}; you can find the arara rule for + \texttt{latexindent.pl} and its associated documentation at \cite{paulo}. + +\subsection{Summary of exit codes} + \index{exit code!summary} + Assuming that you call \texttt{latexindent.pl} on \texttt{myfile.tex} + \begin{commandshell} +latexindent.pl myfile.tex +\end{commandshell} + then \texttt{latexindent.pl} can exit with the exit codes given in \cref{tab:exit-codes}. + + \begin{table}[!htb] + \caption{Exit codes for \texttt{latexindent.pl}} + \label{tab:exit-codes} + \begin{tabular}{ccl} + \toprule + exit code & indentation & status \\ + \midrule + 0 & \faCheck & success; if \texttt{-k} or \texttt{-kv} active, indented text matches original \\ + 0 & \faClose & success; if \texttt{-version}, \texttt{-vversion} or \texttt{-help}, no indentation performed \\ + 1 & \faCheck & success, and \texttt{-k} or \texttt{-kv} active; indented text \emph{different} from original \\ + \midrule + 2 & \faClose & failure, \texttt{defaultSettings.yaml} could not be read \\ + 3 & \faClose & failure, myfile.tex not found \\ + 4 & \faClose & failure, myfile.tex exists but cannot be read \\ + 5 & \faClose & failure, \texttt{-w} active, and back-up file cannot be written \\ + 6 & \faClose & failure, \texttt{-c} active, and cruft directory does not exist \\ + \bottomrule + \end{tabular} + \end{table} +% arara: pdflatex: { files: [latexindent]} +\section{indentconfig.yaml, local settings and the -y switch }\label{sec:indentconfig} + The behaviour of \texttt{latexindent.pl} is controlled from the settings specified in any + of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} will only + load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load + your own settings files. + +\subsection{indentconfig.yaml and .indentconfig.yaml} + \texttt{latexindent.pl} will always check your home directory for + \texttt{indentconfig.yaml} + and \texttt{.indentconfig.yaml} (unless it is called with the \texttt{-d} switch), which + is a plain text file you can create that contains the \emph{absolute} paths for any + settings files that you wish \texttt{latexindent.pl} to load. There is no difference + between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the fact + that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to + \cite{jacobo-diaz-hidden-config} for providing this feature. In what follows, we will use + \texttt{indentconfig.yaml}, but it is understood that this could equally represent + \texttt{.indentconfig.yaml}. If you have both files in existence then + \texttt{indentconfig.yaml} takes priority. + + For Mac and Linux users, their home directory is \texttt{~/username} while Windows (Vista + onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure where to put + \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log + file exactly where to put it assuming it doesn't exist already.} \Cref{lst:indentconfig} + shows a sample \texttt{indentconfig.yaml} file. + + \begin{yaml}{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} +# Paths to user settings for latexindent.pl +# +# Note that the settings will be read in the order you +# specify here- each successive settings file will overwrite +# the variables that you specify + +paths: +- /home/cmhughes/Documents/yamlfiles/mysettings.yaml +- /home/cmhughes/folder/othersettings.yaml +- /some/other/folder/anynameyouwant.yaml +- C:\Users\chughes\Documents\mysettings.yaml +- C:\Users\chughes\Desktop\test spaces\more spaces.yaml +\end{yaml} + + Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be + loaded in the order in which you write them. Each file doesn't have to have every switch + from \texttt{defaultSettings.yaml}; in fact, I recommend that you only keep the switches + that you want to \emph{change} in these settings files. + + To get started with your own settings file, you might like to save a copy of + \texttt{defaultSettings.yaml} in another directory and call it, for example, + \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} you + can change the switches and add more code-block names to it as you see fit -- have a look + at \cref{lst:mysettings} for an example that uses four tabs for the default indent, adds + the \texttt{tabbing} environment/command to the list of environments that contains + alignment delimiters; you might also like to refer to the many YAML files detailed + throughout the rest of this documentation. \index{indentation!defaultIndent using YAML + file} + + \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings} +# Default value of indentation +defaultIndent: "\t\t\t\t" + +# environments that have tab delimiters, add more +# as needed +lookForAlignDelims: + tabbing: 1 +\end{yaml} + + You can make sure that your settings are loaded by checking \texttt{indent.log} for + details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognise + then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} + has read your settings file \footnote{Windows users may find that they have to end + \texttt{.yaml} files with a blank line}. \index{warning!editing YAML files} + + \begin{warning} + When editing \texttt{.yaml} files it is \emph{extremely} important to remember how + sensitive they are to spaces. I highly recommend copying and pasting from + \texttt{defaultSettings.yaml} when you create your first + \texttt{whatevernameyoulike.yaml} file. + + If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it will tell you so in + \texttt{indent.log}. + \end{warning} + + If you find that \announce{2021-06-19}{encoding option for indentconfig.yaml} + \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of the + default commandline encoding not being UTF-8; normally this will only occcur for Windows + users. In this case, you might like to explore the \texttt{encoding} option for + \texttt{indentconfig.yaml} as demonstrated in \cref{lst:indentconfig-encoding}.% + + \cmhlistingsfromfile{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding} + + Thank you to \cite{qiancy98} for this contribution; please see \vref{app:encoding} and + details within \cite{encoding} for further information. + +\subsection{localSettings.yaml and friends}\label{sec:localsettings} + The \texttt{-l} switch tells \texttt{latexindent.pl} to look for + \texttt{localSettings.yaml} and/or friends in the \emph{same directory} as + \texttt{myfile.tex}. For% + \announce{2021-03-14}*{-l + switch: localSettings and friends} example, if you use the following command + \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl -l myfile.tex +\end{commandshell} + then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of + the following files in the following order: + \begin{enumerate} + \item localSettings.yaml + \item latexindent.yaml + \item .localSettings.yaml + \item .latexindent.yaml + \end{enumerate} + These files will be assumed to be in the same directory as \texttt{myfile.tex}, or + otherwise in the current working directory. You do not need to have all of the above + files, usually just one will be sufficient. In what follows, whenever we refer to + \texttt{localSettings.yaml} it is assumed that it can mean any of the four named options + listed above. + + If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say, + \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call + \texttt{latexindent.pl} using, for example, + \begin{commandshell} +latexindent.pl -l=mysettings.yaml myfile.tex +\end{commandshell} + + Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} + \texttt{defaultSettings.yaml} and, assuming they exist, any user setting files specified + in \texttt{indentconfig.yaml}. + + Your settings file can contain any switches that you'd like to change; a sample is shown + in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this + manual. \index{verbatim!verbatimEnvironments demonstration (-l switch)} + + \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} +# verbatim environments - environments specified +# here will not be changed at all! +verbatimEnvironments: + cmhenvironment: 0 + myenv: 1 +\end{yaml} + + You can make sure that your settings file has been loaded by checking \texttt{indent.log} + for details; if it can not be read then you receive a warning, otherwise you'll get + confirmation that \texttt{latexindent.pl} has read your settings file. + +\subsection{The -y|yaml switch}\label{sec:yamlswitch} + You% + \announce{2017-08-21}{demonstration of the -y switch} + may use the \texttt{-y} switch to load your settings; for example, if you wished to + specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, then you + could use the following command: + \index{verbatim!verbatimEnvironments demonstration (-y switch)} + \begin{commandshell} +latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex +\end{commandshell} + Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. + This is shorthand, and equivalent, to using the following command: \index{switches!-y + demonstration} + \begin{commandshell} +latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex +\end{commandshell} + You may, of course, specify settings using the \texttt{-y} switch as well as, for + example, settings loaded using the \texttt{-l} switch; for example, \index{switches!-l + demonstration} \index{switches!-y demonstration} + \begin{commandshell} +latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex +\end{commandshell} + Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any + specified using \texttt{indentconfig.yaml} and the \texttt{-l} switch. + + If you wish to specify any regex-based settings using the \texttt{-y} switch, + \index{regular expressions!using -y switch} it is important not to use quotes surrounding + the regex; for example, with reference to the `one sentence per line' feature + (\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the + following settings give the option to have sentences end with a semicolon + \index{switches!-y demonstration} + \begin{commandshell} +latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' +\end{commandshell} + +\subsection{Settings load order}\label{sec:loadorder} + \texttt{latexindent.pl} loads the settings files in the following order: + \index{switches!-l in relation to other settings} + \begin{enumerate} + \item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed; + \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in + \texttt{indentconfig.yaml}; + \item \texttt{localSettings.yaml} but only if found in the same directory as + \texttt{myfile.tex} + and called with \texttt{-l} switch; this file can be renamed, provided that the call to + \texttt{latexindent.pl} is adjusted accordingly (see \cref{sec:localsettings}). You may + specify both relative and absolute% + \announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l} + switch, separating multiple files using commas; + \item any settings \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y} + switch.% + \end{enumerate} + A visual representation of this is given in \cref{fig:loadorder}. + + \begin{figure}[!htb] + \centering + \input{figure-schematic} + \caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent + mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can + contain as many files as you like. The files will be loaded in order; if you specify + settings for the same field in more than one file, the most recent takes priority. } + \label{fig:loadorder} + \end{figure} +% arara: pdflatex: { files: [latexindent]} +\section{defaultSettings.yaml}\label{sec:defuseloc} + \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea + is to separate the behaviour of the script from the internal working -- this is very + similar to the way that we separate content from form when writing our documents in + \LaTeX. + + If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the + behaviour of \texttt{latexindent.pl}. If you're not sure where + \texttt{defaultSettings.yaml} resides on your computer, don't worry as + \texttt{indent.log} will tell you where to find it. \texttt{defaultSettings.yaml} is + commented, but here is a description of what each switch is designed to do. The default + value is given in each case; whenever you see \emph{integer} in \emph{this} section, + assume that it must be greater than or equal to \texttt{0} unless otherwise stated. + + For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers, + then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For + fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the + specific context and associated commentary should make it clear which values are allowed. + +\yamltitle{fileExtensionPreference}*{fields} + \texttt{latexindent.pl} can be called to + act on a file without specifying the file extension. For example we can call + \begin{commandshell} +latexindent.pl myfile +\end{commandshell} + in which case the script will look for \texttt{myfile} with the extensions specified in + \texttt{fileExtensionPreference} in their numeric order. If no match is found, the script + will exit. As with all of the fields, you should change and/or add to this as necessary. + + \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} + + Calling \texttt{latexindent.pl myfile} with the (default) settings specified in + \cref{lst:fileExtensionPreference} means that the script will first look for + \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally + \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line + numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. + + \index{backup files!extension settings} + +\subsection{Backup and log file preferences} +\yamltitle{backupExtension}*{extension name} + + If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite + \texttt{myfile.tex}) then it will create a backup file before doing any indentation; the + default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be + created when calling \texttt{latexindent.pl myfile.tex} for the first time. + + By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w} + to act upon \texttt{myfile.tex}, it will create successive back up files: + \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. + +\yamltitle{onlyOneBackUp}*{integer} + \label{page:onlyonebackup} + \index{backup files!number of backup files} + If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you + don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want + \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change + \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is + \texttt{0}. + \index{backup files!maximum number of backup files} + \index{backup files!number of backup files} + +\yamltitle{maxNumberOfBackUps}*{integer} + Some users may only want a finite number of backup files, say at most $3$, in which case, + they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$ + which will \emph{not} prevent backup files being made; in this case, the behaviour will + be dictated entirely by \texttt{onlyOneBackUp}. The default value of + \texttt{maxNumberOfBackUps} is \texttt{0}. + +\yamltitle{cycleThroughBackUps}*{integer} + \index{backup files!cycle through} + Some users may wish to cycle through backup files, by deleting the oldest backup file and + keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and + \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given + below would be obeyed. + + \begin{commandshell} +copy myfile.bak1 to myfile.bak0 +copy myfile.bak2 to myfile.bak1 +copy myfile.bak3 to myfile.bak2 +copy myfile.bak4 to myfile.bak3 +\end{commandshell} + The default value of \texttt{cycleThroughBackUps} is \texttt{0}. + +\yamltitle{logFilePreferences}*{fields} + \texttt{latexindent.pl} writes information to \texttt{indent.log}, some + of which can be customized by changing \texttt{logFilePreferences}; see + \cref{lst:logFilePreferences}. If you load your own user settings (see + \vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in + \texttt{indent.log}; you can choose not to have the details logged by switching + \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you + can see the amalgamated settings in the log file by switching + \texttt{showAmalgamatedSettings} to \texttt{1}, if you wish. + + \cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} + + When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either + of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will + receive detailed information in \texttt{indent.log}. You can specify character strings to + appear before and after the notification of a found code block using, respectively, + \texttt{showDecorationStartCodeBlockTrace} and + \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in + \vref{app:logfile-demo}.% + + The log file will end with the characters given in \texttt{endLogFileWith}, and will + report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if + \texttt{showGitHubInfoFooter} is set to \texttt{1}. + + Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the + creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}% + + Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper + options} for Perl's \texttt{Dumper} module can be specified in + \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more + information. These options will mostly be helpful for those calling + \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% + +\subsection{Verbatim code blocks} +\yamltitle{verbatimEnvironments}*{fields} + + A field that contains a list of environments that you would like left completely alone -- + no indentation will be performed on environments that you have specified in this field, + see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} + \index{verbatim!commands} + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} + \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} + \end{cmhtcbraster} + + Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields + such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then + \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. + + You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the + \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as + its argument; thank you to \cite{XuehaiPan} for contributing this feature. + + For demonstration, then assuming that your file contains the environments + \texttt{latexcode}, \texttt{latexcode*}, \texttt{pythoncode} and \texttt{pythoncode*}, + then the listings given in \cref{lst:nameAsRegex1,lst:nameAsRegex2} are equivalent. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} + \cmhlistingsfromfile{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} + \end{cmhtcbraster} + + With reference to \cref{lst:nameAsRegex2}: + \begin{itemize} + \item the \texttt{name} field as specified here means \emph{any word followed by the word code, + optionally followed by *}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description + you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + \end{itemize} + +\yamltitle{verbatimCommands}*{fields} + A field that contains a list of commands that are verbatim commands, for example + \lstinline|\lstinline|; any commands populated in this field are protected from line + breaking routines (only relevant if the \texttt{-m} is active, see + \vref{sec:modifylinebreaks}). + + With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks + for \lstinline|\verb| immediately followed by another character, and then it takes the + body as anything up to the next occurrence of the character; this means that, for + example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}. + + You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the + \texttt{verbatimCommands} field using the \texttt{name} field which takes a regular + expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. + + For demonstration, then assuming that your file contains the commands + \texttt{verbinline}, \texttt{myinline} then the listings given in + \cref{lst:nameAsRegex3,lst:nameAsRegex4} are equivalent. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} + \cmhlistingsfromfile{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} + \end{cmhtcbraster} + + With reference to \cref{lst:nameAsRegex4}: + \begin{itemize} + \item the \texttt{name} field as specified here means \emph{any word followed by the word + inline}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description + you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + \end{itemize} + +\yamltitle{noIndentBlock}*{fields} + If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if + \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can + wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for + this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. + + \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} + + Of course, you don't want to have to specify these as null environments in your code, so + you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly + none) as you like; see \cref{lst:noIndentBlockdemo} for example. + + \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo} + + Important note: it is assumed that the \texttt{noindent} block statements specified in + this way appear on their own line. + + The \announce{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock} fields + can also be specified in terms of \texttt{begin} and \texttt{end} fields. We use the code + in \cref{lst:noIndentBlock1} to demonstrate this feature.% + + \cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1} + + The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent: + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} + \cmhlistingsfromfile{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} + \cmhlistingsfromfile{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} + \end{cmhtcbraster} + + Upon running the commands + \begin{commandshell} +latexindent.pl -l noindent1.yaml noindent1 +latexindent.pl -l noindent2.yaml noindent1 +\end{commandshell} + then we receive the output given in \cref{lst:noIndentBlock1-mod1}. + + \cmhlistingsfromfile{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1} + + The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are + all \emph{regular expressions}. If the \texttt{body} field is not specified, then it + takes a default value of \lstinline!.*?! which is written explicitly in + \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the + fewest number of characters (possibly none) until the `end' field is reached}. + + The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + + Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off); running + the command + \begin{commandshell} +latexindent.pl -l noindent3.yaml noindent1 +\end{commandshell} + gives the output in \cref{lst:noIndentBlock1-mod3}. + + \cmhlistingsfromfile{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3} + + We will demonstrate this feature later in the documentation in \cref{lst:href3}. + + You can, optionally, specify \announce{2021-10-30}{noIndentBlock name feature} the + \texttt{noIndentBlock} field using the \texttt{name} field which takes a regular + expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. + + For demonstration, then assuming that your file contains the environments + \texttt{testnoindent}, \texttt{testnoindent*} then the listings given in + \cref{lst:nameAsRegex5,lst:nameAsRegex6} are equivalent. + + \begin{widepage} + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} + \cmhlistingsfromfile{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} + \end{cmhtcbraster} + \end{widepage} + + With reference to \cref{lst:nameAsRegex6}: + \begin{itemize} + \item the \texttt{name} field as specified here means \emph{any word followed by the word + noindent, optionally followed by *}; + \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description + you like; + \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by + default, it is assumed to be 1 (on). + \end{itemize} +\subsection{filecontents and preamble} +\yamltitle{fileContentsEnvironments}*{field} + + Before \texttt{latexindent.pl} determines the difference between preamble (if any) and + the main document, it first searches for any of the environments specified in + \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour + of \texttt{latexindent.pl} on these environments is determined by their location + (preamble or not), and the value \texttt{indentPreamble}, discussed next. + + \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} + +\yamltitle{indentPreamble}{0|1} + + The preamble of a document can sometimes contain some trickier code for + \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to + operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default), + but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to + \texttt{1}. + +\yamltitle{lookForPreamble}*{fields} + + Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} + files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for + example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of + \texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex} + files. + + \cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} +\yamltitle{preambleCommandsBeforeEnvironments}{0|1} + Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a + document, when this switch is set to \texttt{0} then environment code blocks will be + sought first, and then command code blocks. When this switch is set to \texttt{1}, + commands will be sought first. The example that first motivated this switch contained the + code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. + + \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} +... +preheadhook={\begin{mdframed}[style=myframedstyle]}, +postfoothook=\end{mdframed}, +... +\end{cmhlistings} + + \index{indentation!defaultIndent description} + +\subsection{Indentation and horizontal space} +\yamltitle{defaultIndent}*{horizontal space} + This is the default indentation used in the absence of other details for the code block + with which we are working. The default value is \lstinline!\t! which means a tab; we will + explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. + + If you're interested in experimenting with \texttt{latexindent.pl} then you can + \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. + +\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace} + + Trailing white space can be removed both \emph{before} and \emph{after} processing the + document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take + the values \texttt{0} or \texttt{1}. See + \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before + and after results. Thanks to \cite{vosskuhle} for providing this feature. + + \begin{minipage}{.4\textwidth} + \cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} + \end{minipage}% + \hfill + \begin{minipage}{.5\textwidth} + \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt} +removeTrailingWhitespace: 1 +\end{yaml} + \end{minipage}% + + You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if + you wish; in this case, \announce{2017-06-28}{removeTrailingWhitespace} + \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and + \texttt{afterProcessing} to the value you specify; see + \cref{lst:removeTrailingWhitespace-alt}.% + +\subsection{Aligning at delimiters}\label{subsec:align-at-delimiters} +\yamltitle{lookForAlignDelims}*{fields} + This contains a list of code blocks that are operated upon in a special way by + \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in + \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} + version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in + \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced + settings of lookForAlignDelims} + + \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} +lookForAlignDelims: + tabular: 1 + tabularx: 1 + longtable: 1 + array: 1 + matrix: 1 + ... + \end{yaml} + + Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align + each column by its alignment delimiters. It does have some limitations (discussed further + in \cref{sec:knownlimitations}), but in many cases it will produce results such as those + in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. + + If you find that \texttt{latexindent.pl} does not perform satisfactorily on such + environments then you can set the relevant key to \texttt{0}, for example + \texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} instances + of the environment, you could wrap them in something from \texttt{noIndentBlock} (see + \vref{lst:noIndentBlock}). + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} + \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} + \end{cmhtcbraster} + + If, for example, you wish to remove the alignment of the \lstinline!\\! within a + delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in + \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx} + \index{regular expressions!ampersand alignment} \index{delimiters!default settings of + lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings} + \index{delimiters!lookForAlignDelims} + + \cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} + + Note that you can use a mixture of the basic and advanced form: in + \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and + \texttt{longtable} is basic. When using the advanced form, each field should receive at + least 1 sub-field, and \emph{can} (but does not have to) receive any of the following + fields: + \begin{itemize} + \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for + example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. + If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be + called for this code block (default: 1); + \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if + \lstinline!\\! + should be aligned (default: 1); + \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% + \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} + specifies the number (integer $\geq$ 0) of spaces to be inserted before + \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} + \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 + or 1) that details if \texttt{latexindent.pl} should group columns above and below a + \lstinline!\multicolumn! command (default: 0); + \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: + binary switch (0 or 1) that details if rows that do not contain the maximum number of + delimeters should be formatted so as to have the ampersands aligned (default: 1); + \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand + alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ + 0) of spaces to be placed \emph{before} ampersands (default: 1); + \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand + alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ + 0) of spaces to be placed \emph{After} ampersands (default: 1); + \item \announce{2018-01-13}{justification of cells in ampersand + alignment}\texttt{justification}: optionally specifies the justification of each cell as + either \emph{left} or \emph{right} (default: left); + \item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} + optionally specifies if the \emph{final} double back slash should be used for alignment + (default: 0); + \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if + user-specified cells, rows or the largest entries should \emph{not} be measured (default: + 0); + \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the + pattern matching to be used for the alignment delimeter (default: + \lstinline* '(?!. + We employ the settings given in \cref{lst:delimiterRegEx1} and run the command + \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml +\end{commandshell} + to receive the output given in \cref{lst:tabbing-mod1}. \index{regular + expressions!delimiter regex at \textbackslash= or \textbackslash>} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} + \cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} + \end{cmhtcbraster} + We note that: + \begin{itemize} + \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the + \lstinline!\=! and \lstinline!\>!; + \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression + using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it + must be followed by either \lstinline!=! or \lstinline!>!. + \end{itemize} + We can explore \texttt{delimiterRegEx} a little further using the settings in + \cref{lst:delimiterRegEx2} and run the command \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml +\end{commandshell} + to receive the output given in \cref{lst:tabbing-mod2}. \index{regular + expressions!delimiter regex at only \textbackslash>} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} + \cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} + \end{cmhtcbraster} + We note that only the \lstinline!\>! have been aligned. + + Of course, the other lookForAlignDelims options can be used alongside the + \texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or + anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for + example, using the settings in \cref{lst:delimiterRegEx3}, and running \index{switches!-l + demonstration} + \begin{commandshell} +latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml +\end{commandshell} + to receive the output given in \cref{lst:tabbing-mod3}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} + \cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} + \end{cmhtcbraster} + + It is possible that delimiters specified within \texttt{delimiterRegEx} can be of + different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in + \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option + for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different + lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o + demonstration} + \begin{commandshell} +latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 +\end{commandshell} + we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter + regex at \#} + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} + \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} + \cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} + \end{cmhtcbraster} + + You can set the \emph{delimiter} justification as either \texttt{left} (default) or + \texttt{right}, which will only have effect when delimiters in the same column have + different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the + command \index{switches!-l demonstration} \index{switches!-o demonstration} + \begin{commandshell} +latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 +\end{commandshell} + gives the output in \cref{lst:tabbing1-mod5}. \index{regular expressions!delimiter regex + at \# or \textbackslash>} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} + \cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} + \end{cmhtcbraster} + + Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right + aligned} -- it is quite subtle! + +\subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks} + There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in + which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child + blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to + proceed. + + Using the settings from \vref{lst:dontMeasure1} on the file in \cref{lst:tabular-DM-1} + and running the command + \begin{commandshell} +latexindent.pl tabular-DM-1.tex -l=dontMeasure1.yaml -o=+-mod1 +\end{commandshell} + gives the output in \cref{lst:tabular-DM-1-mod1}. + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-1.tex}{\texttt{tabular-DM-1.tex}}{lst:tabular-DM-1} + \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1.tex}{\texttt{tabular-DM-1-mod1.tex}}{lst:tabular-DM-1-mod1} + \end{cmhtcbraster} + + We can improve the output from \cref{lst:tabular-DM-1-mod1} by employing the settings in + \cref{lst:dontMeasure1a} + \begin{commandshell} +latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a +\end{commandshell} + which gives the output in \cref{lst:dontMeasure1a}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} + \cmhlistingsfromfile{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} + \end{cmhtcbraster} + +\subsection{Indent after items, specials and headings} +\yamltitle{indentAfterItems}*{fields} + The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} + to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then + indentation will be performed so as indent the code after each \texttt{item}. A + demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} + \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} + \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} + \end{cmhtcbraster} + +\yamltitle{itemNames}*{fields} + If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem}, + for example) then you can put populate them in \texttt{itemNames}. For example, users of + the \texttt{exam} document class might like to add \texttt{parts} to + \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings + (see \vref{sec:indentconfig} for details of how to configure user settings, and + \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) + + \cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} + +\yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} + The fields specified \index{specialBeginEnd!introduction} + \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default + state, focused on math mode begin and end statements, but there is no requirement for + this to be the case; \cref{lst:specialBeginEnd} shows the default settings of + \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% + + \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} + + The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} + represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. + You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); + indeed, you might like to set up your own special begin and end statements. + + A demonstration of the before-and-after results are shown in + \cref{lst:specialbefore,lst:specialafter}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} + \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} + \end{cmhtcbraster} + + For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that + \texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl} + not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}. + + There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is + advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for + commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For + example, consider the file shown in \cref{lst:specialLRbefore}.% + + \cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore} + + Now consider the YAML files shown in + \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} + \index{specialBeginEnd!searching for special before commands} + + \begin{cmhtcbraster} + \cmhlistingsfromfile[]{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} + \cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} + \end{cmhtcbraster} + + Upon running the following commands \index{switches!-l demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl specialLR.tex -l=specialsLeftRight.yaml +latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml +\end{commandshell} + \end{widepage} + we receive the respective outputs in + \cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}. + + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex} + \end{minipage} + \hfill + \begin{minipage}{.49\linewidth} + \cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex} + \end{minipage} + + Notice that in: + \begin{itemize} + \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a + \emph{command}, with one optional argument; + \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in + \cref{lst:specialsLeftRight-yaml} + has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the + \texttt{specialBeginEnd} should be sought \emph{before} commands. + \end{itemize} + + You can,optionally, specify \announce{2018-04-27}{update to specialBeginEnd} the + \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For + example, let's consider the \texttt{.tex} file in \cref{lst:special2}. + \index{specialBeginEnd!middle} \index{specialBeginEnd!IfElsFi example}% + + \cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2} + + Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the + commands \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl special2.tex -l=middle +latexindent.pl special2.tex -l=middle1 +\end{commandshell} + then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} + \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} + \end{cmhtcbraster} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} + \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} + \end{cmhtcbraster} + + We note that: + \begin{itemize} + \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been + indented appropriately; + \item the \texttt{Else} statement has \emph{not} been indented appropriately in + \cref{lst:special2-mod1} -- read on! + \item we have specified multiple settings for the \texttt{middle} field using the syntax + demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement + has been indented appropriately in \cref{lst:special2-mod2}. + \end{itemize} + + You may \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in + \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing + \texttt{lookForThis} to be \texttt{verbatim}. \index{verbatim!specialBeginEnd}% + + For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in + \cref{lst:special-verb1-yaml}, and running \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl special3.tex -l=special-verb1 +\end{commandshell} + then the output in \cref{lst:special3-mod1} is unchanged. + \index{specialBeginEnd!specifying as verbatim} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} + \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} + \end{cmhtcbraster} + + We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. + We begin with the code in \cref{lst:special-align}. + + \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} + + Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} + text; we employ the code given in \cref{lst:edge-node1} and run the command + \index{switches!-l demonstration} \index{switches!-o demonstration} + \begin{commandshell} +latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 +\end{commandshell} + to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined + with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} + \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} + \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within + specialBeginEnd blocks} \index{regular expressions!numeric 0-9} + + \begin{cmhtcbraster}[ raster left skip=-3.5cm,] + \cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} + \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} + \end{cmhtcbraster} + + The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings + within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the + code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} + \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} + \begin{commandshell} +latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 +\end{commandshell} + to receive the output in \cref{lst:special-align-mod2}. + \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} + \index{regular expressions!horizontal space \textbackslash{h}} + + \begin{cmhtcbraster}[ raster left skip=-3.5cm,] + \cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} + \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} + \end{cmhtcbraster} + + The \texttt{lookForThis} field can be considered optional; + \announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is + assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.% + +\yamltitle{indentAfterHeadings}*{fields} + This field enables the user to specify indentation rules that take effect after heading + commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!, + \lstinline!\subsection*!, or indeed any user-specified command written in this + field.\footnote{There is a slight difference in interface for this field when comparing + Version 2.2 to Version 3.0; see \vref{app:differences} for details.} + + \cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} + + The default settings do \emph{not} place indentation after a heading, but you can easily + switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The + \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure + in your document. You might, for example, like to have both \texttt{section} and + \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to + go too deep. + + You can add any of your own custom heading commands to this field, specifying the + \texttt{level} as appropriate. You can also specify your own indentation in + \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default + \texttt{indentRules} contains \lstinline!chapter: " "! which tells + \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings + (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). + + For example, assuming that you have the code in \cref{lst:headings1yaml} saved into + \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into + \texttt{headings1.tex}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} + \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} + \end{cmhtcbraster} + + If you run the command \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl headings1.tex -l=headings1.yaml +\end{commandshell} + then you should receive the output given in \cref{lst:headings1-mod1}. + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1} + \end{minipage}% + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2} + \end{minipage} + + Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the + \texttt{paragraph} \texttt{level} is \texttt{1}; after running \index{switches!-l + demonstration} + \begin{commandshell} +latexindent.pl headings1.tex -l=headings1.yaml +\end{commandshell} + you should receive the code given in \cref{lst:headings1-mod2}; notice that the + \texttt{paragraph} and \texttt{subsection} are at the same indentation level. + + \index{indentation!maximum indetation} + +\yamltitle{maximumIndentation}*{horizontal space} + You can control the maximum indentation given to your file by + \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation} + field as horizontal space (but \emph{not} including tabs). This feature uses the + \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.% + + For example, consider the example shown in \cref{lst:mult-nested} together with the + default output shown in \cref{lst:mult-nested-default}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested} + \cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default} + \end{cmhtcbraster} + + Now say that, for example, you have the \texttt{max-indentation1.yaml} from + \cref{lst:max-indentation1yaml} and that you run the following command: + \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl mult-nested.tex -l=max-indentation1 +\end{commandshell} + You should receive the output shown in \cref{lst:mult-nested-max-ind1}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} + \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} + \end{cmhtcbraster} + + Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice + that the (default) tabs of indentation have been replaced by a single space. + + In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be + replaced by equivalent spaces except, of course, those found in + \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or + \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). + +\subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} + + As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of + these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} + \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} + \index{regular expressions!horizontal space \textbackslash{h}} + + \begin{table}[!htp] + \begin{widepage} + \centering + \caption{Code blocks known to \texttt{latexindent.pl}} + \label{tab:code-blocks} + \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} + \toprule + Code block & characters allowed in name & example \\ + \midrule + environments & \lstinline!a-zA-Z@\*0-9_\\! & + \begin{lstlisting}[,nolol=true,] +\begin{myenv} +body of myenv +\end{myenv} + \end{lstlisting} + \\\cmidrule{2-3} + optionalArguments & \emph{inherits} name from parent (e.g environment name) & + \begin{lstlisting}[,nolol=true,] +[ +opt arg text +] + \end{lstlisting} + \\\cmidrule{2-3} + mandatoryArguments & \emph{inherits} name from parent (e.g environment name) & + \begin{lstlisting}[,nolol=true,] +{ +mand arg text +} + \end{lstlisting} + \\\cmidrule{2-3} + commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} + namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*>! between them. + There are switches that can allow them to contain other strings, which we discuss next. + +\yamltitle{commandCodeBlocks}*{fields} + + The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a + few switches detailed in \cref{lst:commandCodeBlocks}.% + + \cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} + +\yamltitle{roundParenthesesAllowed}{0|1} + + The need for this field was mostly motivated by commands found in code used to generate + images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider the code given + in \cref{lst:pstricks1}. + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default} + \end{minipage} + + Notice that the \lstinline!\defFunction! command has an optional argument, followed by a + mandatory argument, followed by a round-parenthesis argument, $(u,v)$. + + By default, because \texttt{roundParenthesesAllowed} is set to $1$ in + \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis + between optional and mandatory arguments. In the case of the code in + \cref{lst:pstricks1}, \texttt{latexindent.pl} finds \emph{all} the arguments of + \lstinline!defFunction!, both before and after \lstinline!(u,v)!. + + The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually + leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is + because of \texttt{noAdditionalIndentGlobal} as discussed on + \cpageref{page:command:noAddGlobal}. + + Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command + \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl pstricks1.tex -l noRoundParentheses.yaml +\end{commandshell} + we obtain the output given in \cref{lst:pstricks1-nrp}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} + \end{cmhtcbraster} + + Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; + in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not} + allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes + at the first opening round parenthesis. As such, the remaining braced, mandatory, + arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see + \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence + the tabbed indentation in \cref{lst:pstricks1-nrp}. + + Let's explore this using the YAML given in \cref{lst:defFunction} and run the command + \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl pstricks1.tex -l defFunction.yaml +\end{commandshell} + then the output is as in \cref{lst:pstricks1-indent-rules}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} + \end{cmhtcbraster} + + Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the + \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the + command name, have received the single space of indentation specified by + \cref{lst:defFunction}. + +\yamltitle{stringsAllowedBetweenArguments}*{fields} + \texttt{tikz} users may well specify code such as that given in + \cref{lst:tikz-node1}; processing this code using + \texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}. + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default} + \end{minipage} + + With reference to \vref{lst:commandCodeBlocks}, we see that the strings + \begin{quote} + to, node, ++ + \end{quote} + are all allowed to appear between arguments; importantly, you are encouraged to add + further names to this field as necessary. This means that when \texttt{latexindent.pl} + processes \cref{lst:tikz-node1}, it consumes: + \begin{itemize} + \item the optional argument \lstinline![thin]! + \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is + $1$ by default + \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the optional argument \lstinline![in=110,out=-90]! + \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the round-bracketed argument \lstinline!(0,-0.5cm)! because + \texttt{roundParenthesesAllowed} is $1$ by default + \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) + \item the optional argument \lstinline![below,align=left,scale=0.5]! + \end{itemize} + + We can explore this further, for example using \cref{lst:draw} and running the command + \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl tikz-node1.tex -l draw.yaml +\end{commandshell} + we receive the output given in \cref{lst:tikz-node1-draw}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} + \end{cmhtcbraster} + + Notice that each line after the \lstinline!\draw! command (its `body') in + \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation + specified in \cref{lst:draw}. + + Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, + and running the command \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl tikz-node1.tex -l no-strings.yaml +\end{commandshell} + given in \cref{lst:tikz-node1-no-strings}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} + \end{cmhtcbraster} + + In this case, \texttt{latexindent.pl} sees that: + \begin{itemize} + \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as + \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings + allowed between arguments; + \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see + \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! + \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} + with argument \lstinline![below,align=left,scale=0.5]! + \end{itemize} + + Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in + commandCodeBlocks}, we see that the first field in the + \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} + by default. This is for users who wish to specify their settings in multiple YAML files. + For example, by using the settings in either \cref{lst:amalgamate-demo} + or\cref{lst:amalgamate-demo1} is equivalent to using the settings in + \cref{lst:amalgamate-demo2}.% + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} + \end{cmhtcbraster} + + We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings + loaded prior to those specified, including the default, will be overwritten. For example, + using the settings in \cref{lst:amalgamate-demo3} means that only the strings specified + in that field will be used. + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} + + It is important to note that the \texttt{amalgamate} field, if used, must be in the first + field, and specified using the syntax given in + \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. + + We may explore this feature further with the code in \cref{lst:for-each}, whose default + output is given in \cref{lst:for-each-default}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} + \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} + \end{cmhtcbraster} + + Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, + and running the command \index{switches!-l demonstration} + \begin{commandshell} +latexindent.pl for-each.tex -l foreach.yaml +\end{commandshell} + given in \cref{lst:for-each-mod1}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} + \end{cmhtcbraster} + + You might like to compare the output given in \cref{lst:for-each-default} and + \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the + \texttt{foreach} command has not included any of the subsequent strings, and that the + braces have been treated as a \texttt{namedGroupingBracesBrackets}. In + \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have + \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in + \cref{lst:foreach}. + +\yamltitle{commandNameSpecial}*{fields} + There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do + not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is + \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of + the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by + sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, + \texttt{latexindent.pl} would not be able to label it as such, because the \lstinline![! + is, necessarily, not matched by a closing \lstinline!]!.% + + For example, consider the sample file in \cref{lst:ifnextchar}, which has default output + in \cref{lst:ifnextchar-default}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} + \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} + \end{cmhtcbraster} + + Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to + indent its body, because \texttt{latexindent.pl} has successfully found the command + \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts + from \emph{the inner most and works outwards}, discussed in more detail on + \cpageref{page:phases}. + + For demonstration, we can compare this output with that given in + \cref{lst:ifnextchar-off} in which the settings from \cref{lst:no-ifnextchar} have + dictated that no special command names, including the \lstinline!\@ifnextchar[! command, + should not be searched for specially; as such, the \texttt{parbox} command has been + \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! + command has not been found. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} + \end{cmhtcbraster} + + The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for + \texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, + which we state again here: \index{warning!amalgamate field} + + \begin{warning} + It is important to note that the \texttt{amalgamate} field, if used, in either + \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the + first field, and specified using the syntax given in + \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. + \end{warning} +% arara: pdflatex: { files: [latexindent]} +\renewcommand{\imagetouse}{logo} +\section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks} + \fancyhead[R]{\bfseries\thepage% + \tikz[remember picture,overlay] { + \node at (1,0){\includegraphics{logo}}; + }} + All features described in this section will only be relevant if the \texttt{-m} switch is + used. + + \startcontents[the-m-switch] + \printcontents[the-m-switch]{}{0}{} + +\yamltitle{modifylinebreaks}*{fields} + \makebox[0pt][r]{% + \raisebox{-\totalheight}[0pt][0pt]{% + \tikz\node[opacity=1] at (0,0) + {\includegraphics[width=4cm]{logo}};}}% + As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits + \texttt{latexindent.pl} to modify line breaks, according to the specifications in the + \texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered + if the \texttt{-m} switch has been used}. A snippet of the default settings of this field + is shown in \cref{lst:modifylinebreaks}. + + \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} + + Having read the previous paragraph, it should sound reasonable that, if you call + \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to + modify line breaks in your file, but let's be clear: \index{warning!the m switch} + + \begin{warning} + If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you are giving it + permission to modify line breaks. By default, the only thing that will happen is that + multiple blank lines will be condensed into one blank line; many other settings are + possible, discussed next. + \end{warning} + +\yamltitle{preserveBlankLines}{0|1} + This field is directly related to \emph{poly-switches}, discussed in + \cref{sec:poly-switches}. By default, it is set to \texttt{1}, which means that blank + lines will be \emph{protected} from removal; however, regardless of this setting, + multiple blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is + greater than \texttt{0}, discussed next. + +\yamltitle{condenseMultipleBlankLinesInto}*{positive integer} + Assuming that this switch takes an integer value greater than \texttt{0}, + \texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines + illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file with + blank lines; upon running \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl myfile.tex -m -o=+-mod1 +\end{commandshell} + the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines have + been condensed into one blank line, and note also that we have used the \texttt{-m} + switch! + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl} + \cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1-mod1.tex}}{lst:mlb-bl-out} + \end{cmhtcbraster} +% arara: pdflatex: { files: [latexindent]} +\subsection{Text Wrapping}\label{subsec:textwrapping} + \announce{2022-03-13}{text wrap overhaul}\emph{The text wrapping routine has been over-hauled as + of V3.16; I hope that the interface is simpler, and most importantly, the results are + better}. + + The complete settings for this feature are given in \cref{lst:textWrapOptionsAll}. + + \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} + +\subsubsection{Text wrap: overview} + An overview of how the text wrapping feature works: + \begin{enumerate} + \item the default value of \texttt{columns} is 0, which means that text wrapping will + \emph{not} happen by default; + \item it happens \emph{after} verbatim blocks have been found; + \item it happens \emph{after} the oneSentencePerLine routine (see + \cref{sec:onesentenceperline}); + \item it happens \emph{before} all of the other code blocks are found and does \emph{not} + operate on a per-code-block basis; this means that, including indentation, you may + receive a column width wider than that which you specify in \texttt{columns} + \item code blocks to be text wrapped will: + \begin{enumerate} + \item \emph{follow} the fields specified in \texttt{blocksFollow} + \item \emph{begin} with the fields specified in \texttt{blocksBeginWith} + \item \emph{end} before the fields specified in \texttt{blocksEndBefore} + \end{enumerate} + \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line + breaks, and then wrapping according to the specified value of \texttt{columns}; + \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap + block; + \item by default, the text wrapping routine will remove line breaks within text blocks because + \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; + \item about trailing comments within text wrap blocks: + \begin{enumerate} + \item trailing comments that do \emph{not} have leading space instruct the text wrap routine to + connect the lines \emph{without} space (see \cref{lst:tw-tc2}); + \item multiple trailing comments will be connected at the end of the text wrap block (see + \cref{lst:tw-tc4}); + \item the number of spaces between the end of the text wrap block and the (possibly combined) + trailing comments is determined by the spaces (if any) at the end of the text wrap block + (see \cref{lst:tw-tc5}). + \end{enumerate} + \end{enumerate} + + We demonstrate this feature using a series of examples. + +\subsubsection{Text wrap: simple examples}\label{subsec:textwrapping-quick-start} + + \begin{example} + Let's use the sample text given in \cref{lst:textwrap1}. \index{text wrap!quick start} + + \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1} + + We will change the value of \texttt{columns} in \cref{lst:textwrap1-yaml} and then run + the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml textwrap1.tex +\end{commandshell} + then we receive the output given in \cref{lst:textwrap1-mod1}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1} + \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} + \end{cmhtcbraster} + \end{example} + + \begin{example} + If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within + the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo + text wrapping. \index{text wrap!setting columns to -1} + + Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in + \cref{lst:textwrap1A-yaml} + + \cmhlistingsfromfile{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml} + + and running + \begin{commandshell} +latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex +\end{commandshell} + gives the output in \cref{lst:textwrap1-mod1A}. + + \cmhlistingsfromfile{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A} + \end{example} + + \begin{example} + By default, the text wrapping routine will convert multiple spaces into single spaces. + You can change this behaviour by flicking the switch \texttt{multipleSpacesToSingle} + which we have done in \cref{lst:textwrap1B-yaml} + + Using the settings in \cref{lst:textwrap1B-yaml} and running + \begin{commandshell} +latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex +\end{commandshell} + gives the output in \cref{lst:textwrap1-mod1B}. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml} + \cmhlistingsfromfile[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B} + \end{cmhtcbraster} + We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been + condensed into single spaces. + \end{example} + +\subsubsection{Text wrap: \texttt{blocksFollow} examples} + We examine the \texttt{blocksFollow} field of \cref{lst:textWrapOptionsAll}. \index{text + wrap!blocksFollow} + + \begin{example} + Let's use the sample text given in \cref{lst:tw-headings1}. \index{text + wrap!blocksFollow!headings} + + \cmhlistingsfromfile{demonstrations/tw-headings1.tex}{\texttt{tw-headings1.tex}}{lst:tw-headings1} + + We note that \cref{lst:tw-headings1} contains the heading commands \texttt{section} and + \texttt{subsection}. Upon running the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml tw-headings1.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-headings1-mod1}. + + \cmhlistingsfromfile{demonstrations/tw-headings1-mod1.tex}{\texttt{tw-headings1-mod1.tex}}{lst:tw-headings1-mod1} + + We reference \vref{lst:textWrapOptionsAll} and also \vref{lst:indentAfterHeadings}: + \begin{itemize} + \item in \cref{lst:textWrapOptionsAll} the \texttt{headings} field is set to \texttt{1}, which + instructs \texttt{latexindent.pl} to read the fields from \vref{lst:indentAfterHeadings}, + \emph{regardless of the value of indentAfterThisHeading or level}; + \item the default is to assume that the heading command can, optionally, be followed by a + \texttt{label} command. + \end{itemize} + If you find scenarios in which the default value of \texttt{headings} does not work, then + you can explore the \texttt{other} field. + + We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex +\end{commandshell} + gives the output in \cref{lst:tw-headings1-mod2}, in which text wrapping has been + instructed \emph{not to happen} following headings. + \begin{cmhtcbraster}[raster column skip=.1\linewidth, + raster left skip=-3.5cm, + raster right skip=-2cm, + ] + \cmhlistingsfromfile{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml} + \cmhlistingsfromfile{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2} + \end{cmhtcbraster} + \end{example} + + \begin{example} + Let's use the sample text given in \cref{lst:tw-comments1}. \index{text + wrap!blocksFollow!comments} + + \cmhlistingsfromfile{demonstrations/tw-comments1.tex}{\texttt{tw-comments1.tex}}{lst:tw-comments1} + + We note that \cref{lst:tw-comments1} contains trailing comments. Upon running the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml tw-comments1.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-comments1-mod1}. + + \cmhlistingsfromfile{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1} + + With reference to \vref{lst:textWrapOptionsAll} the \texttt{commentOnPreviousLine} field + is set to \texttt{1}, which instructs \texttt{latexindent.pl} to find text wrap blocks + after a comment on its own line. + + We can turn off \texttt{comments} as in \cref{lst:bf-no-comments-yaml} and then run + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex +\end{commandshell} + gives the output in \cref{lst:tw-comments1-mod2}, in which text wrapping has been + instructed \emph{not to happen} following comments on their own line. + \begin{cmhtcbraster}[raster column skip=.1\linewidth, + raster left skip=-3.5cm, + raster right skip=-2cm, + ] + \cmhlistingsfromfile{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml} + \cmhlistingsfromfile{demonstrations/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2} + \end{cmhtcbraster} + \end{example} + + Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par}, + \texttt{blankline}, \texttt{verbatim} and \texttt{filecontents} fields operate in + analogous ways to those demonstrated in the above. + + The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned + off) or set as a regular expression. The default value is set to + \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a + square bracket} or \emph{backslash item followed by horizontal space or a square + bracket}, or in other words, \emph{end of display math} or an item command. + + \begin{example} + Let's use the sample text given in \cref{lst:tw-disp-math1}. \index{text + wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow} + + \cmhlistingsfromfile{demonstrations/tw-disp-math1.tex}{\texttt{tw-disp-math1.tex}}{lst:tw-disp-math1} + + We note that \cref{lst:tw-disp-math1} contains display math. Upon running the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml tw-disp-math1.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-disp-math1-mod1}. + + \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1} + + With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to + \lstinline!\\\]!, which instructs \texttt{latexindent.pl} to find text wrap blocks after + the end of display math. + + We can turn off this switch as in \cref{lst:bf-no-disp-math-yaml} and then run + \begin{widepage} + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex +\end{commandshell} + \end{widepage} + gives the output in \cref{lst:tw-disp-math1-mod2}, in which text wrapping has been + instructed \emph{not to happen} following display math. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml} + \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2} + \end{cmhtcbraster} + + Naturally, you should feel encouraged to customise this as you see fit. + \end{example} + + The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text + wrapping to occur after \texttt{begin environment} statements. You are encouraged to + customize the \texttt{other} field to accomodate the environments that you would like to + text wrap individually, as in the next example. + + \begin{example} + Let's use the sample text given in \cref{lst:tw-bf-myenv1}. \index{text + wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow} + + \cmhlistingsfromfile{demonstrations/tw-bf-myenv1.tex}{\texttt{tw-bf-myenv1.tex}}{lst:tw-bf-myenv1} + + We note that \cref{lst:tw-bf-myenv1} contains \texttt{myenv} environment. Upon running + the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml tw-bf-myenv1.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-bf-myenv1-mod1}. + + \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1} + + We note that we have \emph{not} received much text wrapping. We can turn do better by + employing \cref{lst:tw-bf-myenv-yaml} and then run + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex +\end{commandshell} + which gives the output in \cref{lst:tw-bf-myenv1-mod2}, in which text wrapping has been + implemented across the file. + \begin{cmhtcbraster}[raster column skip=.1\linewidth, + raster left skip=-3.5cm, + raster right skip=-2cm, + ] + \cmhlistingsfromfile{demonstrations/tw-bf-myenv.yaml}[MLB-TCB]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml} + \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2} + \end{cmhtcbraster} + + \end{example} + +\subsubsection{Text wrap: \texttt{blocksBeginWith} examples} + We examine the \texttt{blocksBeginWith} field of \cref{lst:textWrapOptionsAll} with a + series of examples. \index{text wrap!blocksBeginWith} + + \begin{example} + By default, text wrap blocks can begin with the characters \texttt{a-z} and \texttt{A-Z}. + + If we start with the file given in \cref{lst:tw-0-9} + \cmhlistingsfromfile{demonstrations/tw-0-9.tex}{\texttt{tw-0-9.tex}}{lst:tw-0-9} + and run the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml tw-0-9.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-0-9-mod1} in which text wrapping has + \emph{not} occured. + \cmhlistingsfromfile{demonstrations/tw-0-9-mod1.tex}{\texttt{tw-0-9-mod1.tex}}{lst:tw-0-9-mod1} + + We can allow paragraphs to begin with \texttt{0-9} characters by using the settings in + \cref{lst:bb-0-9-yaml} and running + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex +\end{commandshell} + gives the output in \cref{lst:tw-0-9-mod2}, in which text wrapping \emph{has} happened. + \begin{cmhtcbraster}[raster column skip=.1\linewidth,] + \cmhlistingsfromfile{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml} + \cmhlistingsfromfile{demonstrations/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2} + \end{cmhtcbraster} + \end{example} + + \begin{example} + Let's now use the file given in \cref{lst:tw-bb-announce1} + \cmhlistingsfromfile{demonstrations/tw-bb-announce1.tex}{\texttt{tw-bb-announce1.tex}}{lst:tw-bb-announce1} + and run the command + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml tw-bb-announce1.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text + wrapping has \emph{not} occured. + + \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1} + + We can allow \lstinline!\announce! to be at the beginning of paragraphs by using the + settings in \cref{lst:tw-bb-announce-yaml} and running + \begin{widepage} + \begin{commandshell} +latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex +\end{commandshell} + \end{widepage} + gives the output in \cref{lst:tw-bb-announce1-mod2}, in which text wrapping \emph{has} + happened. + \begin{cmhtcbraster}[raster column skip=.1\linewidth,] + \cmhlistingsfromfile{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml} + \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2} + \end{cmhtcbraster} + + \end{example} + +\subsubsection{Text wrap: \texttt{blocksEndBefore} examples} + We examine the \texttt{blocksEndBefore} field of \cref{lst:textWrapOptionsAll} with a + series of examples. \index{text wrap!blocksEndBefore} + + \begin{example} + Let's use the sample text given in \cref{lst:tw-be-equation}. \index{text + wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow} + + \cmhlistingsfromfile{demonstrations/tw-be-equation.tex}{\texttt{tw-be-equation.tex}}{lst:tw-be-equation} + + We note that \cref{lst:tw-be-equation} contains an environment. Upon running the command + \begin{commandshell} +latexindent.pl -m -l textwrap1A.yaml tw-be-equation.tex +\end{commandshell} + then we receive the output given in \cref{lst:tw-be-equation-mod1}. + + \cmhlistingsfromfile{demonstrations/tw-be-equation-mod1.tex}{\texttt{tw-be-equation-mod1.tex}}{lst:tw-be-equation-mod1} + + With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to + \lstinline!\\begin\{|\\\[|\\end\{!, which instructs \texttt{latexindent.pl} to + \emph{stop} text wrap blocks before \texttt{begin} statements, display math, and + \texttt{end} statements. + + We can turn off this switch as in \cref{lst:tw-be-equation-yaml} and then run + \begin{widepage} + \begin{commandshell} +latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex +\end{commandshell} + \end{widepage} + gives the output in \cref{lst:tw-be-equation-mod2}, in which text wrapping has been + instructed \emph{not} to stop at these statements. + + \cmhlistingsfromfile{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml} + + \begin{widepage} + \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2} + \end{widepage} + + Naturally, you should feel encouraged to customise this as you see fit. + \end{example} + +\subsubsection{Text wrap: trailing comments and spaces} + We explore the behaviour of the text wrap routine in relation to trailing comments using + the following examples. + + \begin{example} + The file in \cref{lst:tw-tc1} contains a trailing comment which \emph{does} have a space + infront of it. + + Running the command + \begin{commandshell} +latexindent.pl -m tw-tc1.tex -l textwrap1A.yaml -o=+-mod1 +\end{commandshell} + gives the output given in \cref{lst:tw-tc1-mod1}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc1.tex}{\texttt{tw-tc1.tex}}{lst:tw-tc1} + \cmhlistingsfromfile{demonstrations/tw-tc1-mod1.tex}{\texttt{tw-tc1-mod1.tex}}{lst:tw-tc1-mod1} + \end{cmhtcbraster} + \end{example} + + \begin{example} + The file in \cref{lst:tw-tc2} contains a trailing comment which does \emph{not} have a + space infront of it. + + Running the command + \begin{commandshell} +latexindent.pl -m tw-tc2.tex -l textwrap1A.yaml -o=+-mod1 +\end{commandshell} + gives the output in \cref{lst:tw-tc2-mod1}. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/tw-tc2.tex}{\texttt{tw-tc2.tex}}{lst:tw-tc2} + \cmhlistingsfromfile{demonstrations/tw-tc2-mod1.tex}{\texttt{tw-tc2-mod1.tex}}{lst:tw-tc2-mod1} + \end{cmhtcbraster} + We note that, because there is \emph{not} a space before the trailing comment, that the + lines have been joined \emph{without} a space. + \end{example} + + \begin{example} + The file in \cref{lst:tw-tc3} contains multiple trailing comments. + + Running the command + \begin{commandshell} +latexindent.pl -m tw-tc3.tex -l textwrap1A.yaml -o=+-mod1 +\end{commandshell} + gives the output in \cref{lst:tw-tc3-mod1}. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/tw-tc3.tex}{\texttt{tw-tc3.tex}}{lst:tw-tc3} + \cmhlistingsfromfile{demonstrations/tw-tc3-mod1.tex}{\texttt{tw-tc3-mod1.tex}}{lst:tw-tc3-mod1} + \end{cmhtcbraster} + \end{example} + + \begin{example} + The file in \cref{lst:tw-tc4} contains multiple trailing comments. + + Running the command + \begin{commandshell} +latexindent.pl -m tw-tc4.tex -l textwrap1A.yaml -o=+-mod1 +\end{commandshell} + gives the output in \cref{lst:tw-tc4-mod1}. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/tw-tc4.tex}{\texttt{tw-tc4.tex}}{lst:tw-tc4} + \cmhlistingsfromfile{demonstrations/tw-tc4-mod1.tex}{\texttt{tw-tc4-mod1.tex}}{lst:tw-tc4-mod1} + \end{cmhtcbraster} + \end{example} + + \begin{example} + The file in \cref{lst:tw-tc5} contains multiple trailing comments. + + Running the command + \begin{commandshell} +latexindent.pl -m tw-tc5.tex -l textwrap1A.yaml -o=+-mod1 +\end{commandshell} + gives the output in \cref{lst:tw-tc5-mod1}. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5.tex}{\texttt{tw-tc5.tex}}{lst:tw-tc5} + \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5-mod1.tex}{\texttt{tw-tc5-mod1.tex}}{lst:tw-tc5-mod1} + \end{cmhtcbraster} + The space at the end of the text block has been preserved. + \end{example} + + \begin{example} + The file in \cref{lst:tw-tc6} contains multiple trailing comments. + + Running the command + \begin{commandshell} +latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 +\end{commandshell} + gives the output in \cref{lst:tw-tc6-mod1}. + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6.tex}{\texttt{tw-tc6.tex}}{lst:tw-tc6} + \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6-mod1.tex}{\texttt{tw-tc6-mod1.tex}}{lst:tw-tc6-mod1} + \end{cmhtcbraster} + The space at the end of the text block has been preserved. + \end{example} + +\subsubsection{Text wrap: huge, tabstop and separator} + The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge} + is \texttt{overflow}, which means that words will \emph{not} be broken by the text + wrapping routine, implemented by the \texttt{Text::Wrap} \cite{textwrap}. There are + options to change the \texttt{huge} option for the \texttt{Text::Wrap} module to either + \texttt{wrap} or \texttt{die}. Before modifying the value of \texttt{huge}, please bear + in mind the following warning: \index{warning!changing huge (textwrap)}% + \begin{warning} + \raggedright + Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow + down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active. + + Furthermore, changing \texttt{huge} means that you may have some words \emph{or + commands}(!) split across lines in your .tex file, which may affect your output. I do not + recommend changing this field. + \end{warning} + + For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and + running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} + \index{switches!-o demonstration} + \begin{commandshell} + latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml + latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml +\end{commandshell} + gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A} + \cmhlistingsfromfile{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml} + + \cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B} + \cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml} + \end{cmhtcbraster} + + You can also specify the \texttt{tabstop} field \announce{2020-11-06}{tabstop option for + text wrap module} as an integer value, which is passed to the text wrap module; see + \cite{textwrap} for details. Starting with the code in \cref{lst:textwrap-ts} with + settings in \cref{lst:tabstop}, and running the command \index{switches!-l demonstration} + \index{switches!-m demonstration} \index{switches!-o demonstration}% + \begin{commandshell} + latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml + \end{commandshell} + gives the code given in \cref{lst:textwrap-ts-mod1}. + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.03\linewidth] + \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} + \cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} + \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} + \end{cmhtcbraster} + + You can specify \texttt{separator}, \texttt{break} and \texttt{unexpand} options in your + settings in analogous ways to those demonstrated in + \cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the + \texttt{Text::Wrap} module. I have not found a useful reason to do this; see + \cite{textwrap} for more details. +% arara: pdflatex: { files: [latexindent]} +\subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline} + + You can instruct \texttt{latexindent.pl} to format \announce{2018-01-13}{one sentence per + line} your file so that it puts one sentence per line. Thank you to \cite{mlep} for + helping to shape and test this feature. The behaviour of this part of the script is + controlled by the switches detailed in \cref{lst:oneSentencePerLine}, all of which we + discuss next. \index{modifying linebreaks! by using one sentence per line} + \index{sentences!oneSentencePerLine} \index{sentences!one sentence per line} + \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph + A-Z}% + + \cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} + +\yamltitle{manipulateSentences}{0|1} + This is a binary switch that details if \texttt{latexindent.pl} should perform the + sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you + will need to turn it on (by setting it to \texttt{1}) if you want the script to modify + line breaks surrounding and within sentences. + +\yamltitle{removeSentenceLineBreaks}{0|1} + When operating upon sentences \texttt{latexindent.pl} will, by default, remove internal + line breaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. Setting this + switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so. + \index{sentences!removing sentence line breaks} + + For example, consider \texttt{multiple-sentences.tex} shown in + \cref{lst:multiple-sentences}. + + \cmhlistingsfromfile{demonstrations/multiple-sentences.tex}{\texttt{multiple-sentences.tex}}{lst:multiple-sentences} + + If we use the YAML files in + \cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml +latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml +\end{commandshell} + \end{widepage} + then we obtain the respective output given in + \cref{lst:multiple-sentences-mod1,lst:multiple-sentences-mod2}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/multiple-sentences-mod1.tex}{\texttt{multiple-sentences.tex} using \cref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/manipulate-sentences.yaml}[MLB-TCB]{\texttt{manipulate-sentences.yaml}}{lst:manipulate-sentences-yaml} + \end{cmhtcbraster} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/multiple-sentences-mod2.tex}{\texttt{multiple-sentences.tex} using \cref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml} + \end{cmhtcbraster} + + Notice, in particular, that the `internal' sentence line breaks in + \cref{lst:multiple-sentences} have been removed in \cref{lst:multiple-sentences-mod1}, + but have not been removed in \cref{lst:multiple-sentences-mod2}. + +\yamltitle{multipleSpacesToSingle}{0|1} + \announce{2022-03-25}*{multipleSpacesToSingle for oneSentencePerLine} By default, the + one-sentence-per-line routine will convert multiple spaces into single spaces. You can + change this behaviour by changing the switch \texttt{multipleSpacesToSingle} to a value + of \texttt{0}. + + The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct + \texttt{latexindent.pl} on how to define a sentence. From the perspective of + \texttt{latexindent.pl} a sentence must: \index{sentences!follow} \index{sentences!begin + with} \index{sentences!end with} + \begin{itemize} + \item \emph{follow} a certain character or set of characters (see + \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a + blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace + (\}) or a comment on the previous line; + \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by + default, this is only capital letters; + \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by + default, these are full stop/period (.), exclamation mark (!) and question mark (?). + \end{itemize} + In each case, you can specify the \texttt{other} field to include any pattern that you + would like; you can specify anything in this field using the language of regular + expressions. \index{regular expressions!lowercase alph a-z} \index{regular + expressions!uppercase alph A-Z} + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.5cm, + raster right skip=-2cm, + raster column skip=.06\linewidth] + \cmhlistingsfromfile[style=sentencesFollow]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} + \cmhlistingsfromfile[style=sentencesBeginWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} + \cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} + \end{cmhtcbraster} + +\subsubsection{sentencesFollow} + Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with + \vref{lst:multiple-sentences}, and use the YAML settings given in + \cref{lst:sentences-follow1-yaml}. Using the command \index{sentences!follow} + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml +\end{commandshell} + we obtain the output given in \cref{lst:multiple-sentences-mod3}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/multiple-sentences-mod3.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-follow1-yaml}}{lst:multiple-sentences-mod3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml} + \end{cmhtcbraster} + + Notice that, because \texttt{blankLine} is set to \texttt{0}, \texttt{latexindent.pl} + will not seek sentences following a blank line, and so the fourth sentence has not been + accounted for. + + We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with the + \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}. + + \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1} + + Upon running the following commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml +latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-follow2.yaml +\end{commandshell} + \end{widepage} + then we obtain the respective output given in + \cref{lst:multiple-sentences1-mod1,lst:multiple-sentences1-mod2}. + \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod1.tex}{\texttt{multiple-sentences1.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences1-mod1} + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=1cm}, + ] + \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod2.tex}{\texttt{multiple-sentences1.tex} using \cref{lst:sentences-follow2-yaml}}{lst:multiple-sentences1-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml} + \end{cmhtcbraster} + + Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the + \texttt{)} has not been accounted for, but that following the inclusion of + \cref{lst:sentences-follow2-yaml}, the output given in + \cref{lst:multiple-sentences1-mod2} demonstrates that the sentence \emph{has} been + accounted for correctly. + +\subsubsection{sentencesBeginWith} + By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper + case letters \texttt{A-Z}; you can instruct the script to define sentences to begin with + lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other} + field to define sentences to begin with other characters. \index{sentences!begin with} + + \cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2} + + Upon running the following commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml +latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-begin1.yaml +\end{commandshell} + \end{widepage} + then we obtain the respective output given in + \cref{lst:multiple-sentences2-mod1,lst:multiple-sentences2-mod2}. + \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod1.tex}{\texttt{multiple-sentences2.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences2-mod1} + \index{regular expressions!numeric 0-9} + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=1cm}, + ] + \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod2.tex}{\texttt{multiple-sentences2.tex} using \cref{lst:sentences-begin1-yaml}}{lst:multiple-sentences2-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-begin1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} + \end{cmhtcbraster} + Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted + for but that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, + all of the sentences have been accounted for, because the \texttt{other} field in + \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either \lstinline!$! + or any numeric digit, \texttt{0} to \texttt{9}. + +\subsubsection{sentencesEndWith} + Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in + which \texttt{latexindent.pl} will operate on the sentences in this file in + \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any + character that we wish; for example, using the YAML specified in + \cref{lst:sentences-end1-yaml} and the command \index{sentences!end with} + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences -m -l=sentences-end1.yaml +latexindent.pl multiple-sentences -m -l=sentences-end2.yaml +\end{commandshell} + then we obtain the output in \cref{lst:multiple-sentences-mod4}. \index{regular + expressions!lowercase alph a-z} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end1.yaml}[MLB-TCB]{\texttt{sentences-end1.yaml}}{lst:sentences-end1-yaml} + \end{cmhtcbraster} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/multiple-sentences-mod5.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end2-yaml}}{lst:multiple-sentences-mod5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml} + \end{cmhtcbraster} + + There is a subtle difference between the output in + \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in particular, in + \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not been defined as a + sentence, because we have not instructed \texttt{latexindent.pl} to begin sentences with + lower case letters. We have changed this by using the settings in + \cref{lst:sentences-end2-yaml}, and the associated output in + \cref{lst:multiple-sentences-mod5} reflects this. + + Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called + \texttt{basicFullStop}, which is set to \texttt{0}, and that the \texttt{betterFullStop} + is set to \texttt{1} by default. + + Let's consider the file shown in \cref{lst:url}. + + \cmhlistingsfromfile{demonstrations/url.tex}{\texttt{url.tex}}{lst:url} + + Upon running the following commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl url -m -l=manipulate-sentences.yaml +\end{commandshell} + we obtain the output given in \cref{lst:url-mod1}. + + \cmhlistingsfromfile{demonstrations/url-mod1.tex}{\texttt{url.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:url-mod1} + + Notice that the full stop within the url has been interpreted correctly. This is because, + within the \texttt{betterFullStop}, full stops at the end of sentences have the following + properties: + \begin{itemize} + \item they are ignored within \texttt{e.g.} and \texttt{i.e.}; + \item they can not be immediately followed by a lower case or upper case letter; + \item they can not be immediately followed by a hyphen, comma, or number. + \end{itemize} + If you find that the \texttt{betterFullStop} does not work for your purposes, then you + can switch it off by setting it to \texttt{0}, and you can experiment with the + \texttt{other} field. \announce{2019-07-13}{fine tuning the betterFullStop} You can also + seek to customise the \texttt{betterFullStop} routine by using the \emph{fine tuning}, + detailed in \vref{lst:fineTuning}.% + + The \texttt{basicFullStop} routine should probably be avoided in most situations, as it + does not accommodate the specifications above. For example, using the following command + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl url -m -l=alt-full-stop1.yaml +\end{commandshell} + and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in \cref{lst:url-mod2}. + + \begin{cmhtcbraster}[ raster left skip=-3.5cm, + raster right skip=-2cm, + raster force size=false, + raster column 1/.style={add to width=.1\textwidth}, + raster column skip=.06\linewidth] + \cmhlistingsfromfile{demonstrations/url-mod2.tex}{\texttt{url.tex} using \cref{lst:alt-full-stop1-yaml}}{lst:url-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alt-full-stop1.yaml}[MLB-TCB,width=.5\textwidth]{\texttt{alt-full-stop1.yaml}}{lst:alt-full-stop1-yaml} + \end{cmhtcbraster} + + Notice that the full stop within the URL has not been accommodated correctly because of + the non-default settings in \cref{lst:alt-full-stop1-yaml}. + +\subsubsection{Features of the oneSentencePerLine routine} + The sentence manipulation routine takes place \emph{after} verbatim \index{verbatim!in + relation to oneSentencePerLine} environments, preamble and trailing comments have been + accounted for; this means that any characters within these types of code blocks will not + be part of the sentence manipulation routine. + + For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3}, + and run the command \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml +\end{commandshell} + then we obtain the output in \cref{lst:multiple-sentences3-mod1}. + \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3} + \cmhlistingsfromfile{demonstrations/multiple-sentences3-mod1.tex}{\texttt{multiple-sentences3.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences3-mod1} + + Furthermore, if sentences run across environments then, by default, the line breaks + internal to the sentence will be removed. For example, if we use the \texttt{.tex} file + in \cref{lst:multiple-sentences4} and run the commands \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml +latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml +\end{commandshell} + then we obtain the output in + \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. + \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} + \begin{widepage} + \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1} + \end{widepage} + \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2} + + Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the + removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml} + and the command \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml +\end{commandshell} + the output of which is shown in \cref{lst:multiple-sentences4-mod3}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod3.tex}{\texttt{multiple-sentences4.tex} using \cref{lst:item-rules2-yaml}}{lst:multiple-sentences4-mod3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml} + \end{cmhtcbraster} + +\subsubsection{Text wrapping and indenting sentences} + The \texttt{oneSentencePerLine} \announce{2018-08-13}{oneSentencePerline text wrap and + indent} can be instructed to perform text wrapping and indentation upon sentences. + \index{sentences!text wrapping} \index{sentences!indenting}% + + Let's use the code in \cref{lst:multiple-sentences5}. + + \cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5} + + Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml +\end{commandshell} + we receive the output given in \cref{lst:multiple-sentences5-mod1}. + + \begin{cmhtcbraster}[ raster left skip=-3.5cm, + raster right skip=-2cm, + raster force size=false, + raster column 1/.style={add to width=.1\textwidth}, + raster column skip=.06\linewidth] + \cmhlistingsfromfile{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap1.yaml}[MLB-TCB,width=0.5\textwidth]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml} + \end{cmhtcbraster} + + If you specify \texttt{textWrapSentences} as 1, but do \emph{not} specify a value for + \texttt{columns} then the text wrapping will \emph{not} operate on sentences, and you + will see a warning in \texttt{indent.log}. + + The indentation of sentences requires that sentences are stored as code blocks. This + means that you may need to tweak \vref{lst:sentencesEndWith}. Let's explore this in + relation to \cref{lst:multiple-sentences6}. + + \cmhlistingsfromfile{demonstrations/multiple-sentences6.tex}{\texttt{multiple-sentences6.tex}}{lst:multiple-sentences6} + + By default, \texttt{latexindent.pl} will find the full-stop within the first + \texttt{item}, which means that, upon running the following commands \index{switches!-l + demonstration} \index{switches!-m demonstration} \index{switches!-y demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml +latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''" +\end{commandshell} + we receive the respective output in \cref{lst:multiple-sentences6-mod1} and + \cref{lst:multiple-sentences6-mod2}. + + \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod1.tex}{\texttt{multiple-sentences6-mod1.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences6-mod1} + + \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod2.tex}{\texttt{multiple-sentences6-mod2.tex} using \cref{lst:sentence-wrap1-yaml} and no sentence indentation}{lst:multiple-sentences6-mod2} + + We note that \cref{lst:multiple-sentences6-mod1} the \texttt{itemize} code block has + \emph{not} been indented appropriately. This is because the oneSentencePerLine has been + instructed to store sentences (because \cref{lst:sentence-wrap1-yaml}); each sentence is + then searched for code blocks. + + We can tweak the settings in \vref{lst:sentencesEndWith} to ensure that full stops are + not followed by \texttt{item} commands, and that the end of sentences contains + \lstinline!\end{itemize}! as in \cref{lst:itemize-yaml} (if you intend to use this, + ensure that you remove the line breaks from the \texttt{other} field). \index{regular + expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} + \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space + \textbackslash{h}} + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml} + + Upon running \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml +\end{commandshell} + we receive the output in \cref{lst:multiple-sentences6-mod3}. + + \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod3.tex}{\texttt{multiple-sentences6-mod3.tex} using \cref{lst:sentence-wrap1-yaml} and \cref{lst:itemize-yaml}}{lst:multiple-sentences6-mod3} + + Notice that the sentence has received indentation, and that the \texttt{itemize} code + block has been found and indented correctly. + + Text \announce{2022-04-04}*{oneSentencePerLine text wrapping update} wrapping when using + the \texttt{oneSentencePerLine} routine determines if it will remove line breaks while + text wrapping, from the value of \texttt{removeSentenceLineBreaks}. +% arara: pdflatex: { files: [latexindent]} +\subsection{Poly-switches}\label{sec:poly-switches} + Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take + one of the following% + \announce{2017-08-21}*{blank line poly-switch} integer values: + \index{modifying linebreaks! using poly-switches} + \index{poly-switches!definition} + \index{poly-switches!values} + \index{poly-switches!off by default: set to 0} + \begin{description} + \item[$-1$] \emph{remove mode}: line breaks before or after the + \emph{} can be removed (assuming that \texttt{preserveBlankLines} is + set to \texttt{0}); + \item[0] \emph{off mode}: line breaks will not be modified for the + \emph{} under consideration; + \item[1] \emph{add mode}: a line break will be added before or after the + \emph{} under consideration, assuming that + there is not already a line break before or after the \emph{}; + \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break + before or after the \emph{} under consideration, assuming that there is + not already a comment and line break before or after the \emph{}; + \item[3] \emph{add then blank line mode}% + \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after + the \emph{} under consideration, assuming that there is not already a line + break before or after the \emph{}, followed by a blank line; + \item[4] \emph{add blank line mode}% + \announce{2019-07-13}{blank line poly-switch}; a blank line will + be added before or after the \emph{} under consideration, even if the + \emph{} is already on its own line. + \end{description} + In the above, \emph{} refers to either the \emph{begin statement}, + \emph{body} or \emph{end statement} of the code blocks detailed in + \vref{tab:code-blocks}. All poly-switches are \emph{off} by default; + \texttt{latexindent.pl} searches first of all for per-name settings, and then followed by + global per-thing settings. + +\subsubsection{Poly-switches for environments}\label{sec:modifylinebreaks-environments} + We start by viewing a snippet of \texttt{defaultSettings.yaml} in + \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately + after the \texttt{environments} field) and that \emph{per-name} settings are also allowed + -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been + specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by + default. \index{poly-switches!default values} \index{poly-switches!environment global + example} \index{poly-switches!environment per-code block example} + + \cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} + + Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have + annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, + $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields + specified in \cref{lst:environments-mlb}. \index{poly-switches!visualisation: + $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, + $\EndFinishesWithLineBreak$} + + \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex} +before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words +\end{cmhlistings} + + \paragraph{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine} + Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in + \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to + take a value of $1$. \index{modifying linebreaks! at the \emph{beginning} of a code + block} \index{poly-switches!adding line breaks: set to 1} + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2} + \end{minipage} + + After running the following commands, \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m env-mlb.tex -l env-mlb1.yaml +latexindent.pl -m env-mlb.tex -l env-mlb2.yaml +\end{commandshell} + the output is as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2} respectively. + + \begin{widepage} + \begin{minipage}{.56\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1} + \end{minipage} + \hfill + \begin{minipage}{.43\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2} + \end{minipage} + \end{widepage} + + There are a couple of points to note: + \begin{itemize} + \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by + $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been + changed; + \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by + $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the \emph{body} + of \texttt{myenv} has received the appropriate (default) indentation. + \end{itemize} + + Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so + that they are $2$ and save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml} + respectively (see \cref{lst:env-mlb3,lst:env-mlb4}). \index{poly-switches!adding comments + and then line breaks: set to 2} + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4} + \end{minipage} + + Upon running commands analogous to the above, we obtain + \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. + + \begin{widepage} + \begin{minipage}{.56\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3} + \end{minipage} + \hfill + \begin{minipage}{.43\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4} + \end{minipage} + \end{widepage} + + Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but + this time a comment symbol has been added before adding the line break; in both cases, + trailing horizontal space has been stripped before doing so. + + Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each + of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and + save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see + \cref{lst:env-mlb5,lst:env-mlb6}). \index{poly-switches!adding blank lines: set to 3}% + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6} + \end{minipage} + + Upon running commands analogous to the above, we obtain + \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. + + \begin{widepage} + \begin{minipage}{.56\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5} + \end{minipage} + \hfill + \begin{minipage}{.43\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6} + \end{minipage} + \end{widepage} + + Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but + this time a \emph{blank line} has been added after adding the line break. + + Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each + of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and + save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see + \cref{lst:env-beg4,lst:env-body4}). \index{poly-switches!adding blank lines (again"!): + set to 4}% + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} + \end{minipage} + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4} + \end{minipage} + + We will demonstrate this poly-switch value using the code in \cref{lst:env-mlb1-text}. + + \cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text} + + Upon running the commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl -m env-mlb1.tex -l env-beg4.yaml +latexindent.pl -m env-mlb.1tex -l env-body4.yaml +\end{commandshell} + + then we receive the respective outputs in \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/env-mlb1-beg4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-beg4}}{lst:env-mlb1-beg4} + \cmhlistingsfromfile{demonstrations/env-mlb1-body4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-body4}}{lst:env-mlb1-body4} + \end{cmhtcbraster} + + We note in particular that, by design, for this value of the poly-switches: + \begin{enumerate} + \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the \lstinline!\begin! + statement, even though the \lstinline!\begin! statement was already on its own line; + \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the + \emph{body}, even though it already began on its own line. + \end{enumerate} + + \paragraph{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak} + Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in + \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to + take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block} + \index{poly-switches!adding line breaks: set to 1} + + \begin{minipage}{.49\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7} + \end{minipage} + \hfill + \begin{minipage}{.49\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8} + \end{minipage} + + After running the following commands, \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m env-mlb.tex -l env-mlb7.yaml +latexindent.pl -m env-mlb.tex -l env-mlb8.yaml +\end{commandshell} + the output is as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}. + + \begin{widepage} + \begin{minipage}{.42\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7} + \end{minipage} + \hfill + \begin{minipage}{.57\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8} + \end{minipage} + \end{widepage} + + There are a couple of points to note: + \begin{itemize} + \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by + $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been changed + and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as + intended); + \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by + $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}. + \end{itemize} + + Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so + that they are $2$ and save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} + respectively (see \cref{lst:env-mlb9,lst:env-mlb10}). \index{poly-switches!adding + comments and then line breaks: set to 2} + + \begin{minipage}{.49\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9} + \end{minipage} + \hfill + \begin{minipage}{.49\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10} + \end{minipage} + + Upon running commands analogous to the above, we obtain + \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. + + \begin{widepage} + \begin{minipage}{.43\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9} + \end{minipage} + \hfill + \begin{minipage}{.56\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10} + \end{minipage} + \end{widepage} + + Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but + this time a comment symbol has been added before adding the line break; in both cases, + trailing horizontal space has been stripped before doing so. + + Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each + of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and + save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see + \cref{lst:env-mlb11,lst:env-mlb12}). \index{poly-switches!adding blank lines: set to 3}% + + \begin{minipage}{.49\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} + \end{minipage} + \hfill + \begin{minipage}{.49\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12} + \end{minipage} + + Upon running commands analogous to the above, we obtain + \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. + + \begin{widepage} + \begin{minipage}{.42\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11} + \end{minipage} + \hfill + \begin{minipage}{.57\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12} + \end{minipage} + \end{widepage} + + Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and + that a \emph{blank line} has been added after the line break. + + Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each + of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and + save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see + \cref{lst:env-end4,lst:env-end-f4}). \index{poly-switches!adding blank lines (again"!): + set to 4}% + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4} + \end{minipage} + \hfill + \begin{minipage}{.5\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4} + \end{minipage} + + We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}. + + Upon running the commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl -m env-mlb1.tex -l env-end4.yaml +latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml +\end{commandshell} + + then we receive the respective outputs in \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/env-mlb1-end4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end4}}{lst:env-mlb1-end4} + \cmhlistingsfromfile{demonstrations/env-mlb1-end-f4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end-f4}}{lst:env-mlb1-end-f4} + \end{cmhtcbraster} + + We note in particular that, by design, for this value of the poly-switches: + \begin{enumerate} + \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the \lstinline!\end! + statement, even though the \lstinline!\end! statement was already on its own line; + \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the \lstinline!\end! + statement, even though it already began on its own line. + \end{enumerate} + + \paragraph{poly-switches 1, 2, and 3 only add line breaks when necessary} + If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a + poly-switch value of $1$ (or $2$ or $3$), it will only do so if necessary. For example, + if you process the file in \vref{lst:mlb2} using poly-switch values of 1, 2, or 3, it + will be left unchanged. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2} + \end{minipage} + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3} + \end{minipage} + + Setting the poly-switches to a value of $4$ instructs \texttt{latexindent.pl} to add a + line break even if the \emph{} is already on its own line; see + \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4} and + \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}. + + In contrast, the output from processing the file in \cref{lst:mlb3} will vary depending + on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the comment symbol + after the \lstinline!\begin{myenv}! has been moved to the next line, as + \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see + that the comment has been accounted for correctly because \texttt{BodyStartsOnOwnLine} + has been set to \texttt{2}, and the comment symbol has \emph{not} been moved to its own + line. You're encouraged to experiment with \cref{lst:mlb3} and by setting the other + poly-switches considered so far to \texttt{2} in turn. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2} + \cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4} + \end{cmhtcbraster} + + The details of the discussion in this section have concerned \emph{global} poly-switches + in the \texttt{environments} field; each switch can also be specified on a + \emph{per-name} basis, which would take priority over the global values; with reference + to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*} + environment. + + \paragraph{Removing line breaks (poly-switches set to $-1$)} + Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the + \emph{}, if necessary. We will consider the example code given in + \cref{lst:mlb4}, noting in particular the positions of the line break highlighters, + $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and + $\EndFinishesWithLineBreak$, together with the associated YAML files in + \crefrange{lst:env-mlb13}{lst:env-mlb16}. \index{poly-switches!removing line breaks: set + to -1} + + \begin{minipage}{.45\linewidth} + \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4} +before words(*@$\BeginStartsOnOwnLine$@*) +\begin{myenv}(*@$\BodyStartsOnOwnLine$@*) +body of myenv(*@$\EndStartsOnOwnLine$@*) +\end{myenv}(*@$\EndFinishesWithLineBreak$@*) +after words +\end{cmhlistings} + \end{minipage}% + \hfill + \begin{minipage}{.51\textwidth} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13} + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14} + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15} + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16} + \end{minipage} + + After running the commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml +latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml +latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml +latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml +\end{commandshell} + + we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}. + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13} + \end{minipage} + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14} + \end{minipage} + + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15} + \end{minipage} + \hfill + \begin{minipage}{.45\linewidth} + \cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16} + \end{minipage} + + Notice that in: + \begin{itemize} + \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in + \cref{lst:mlb4} has been removed; + \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in + \cref{lst:mlb4} has been removed; + \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in + \cref{lst:mlb4} has been removed; + \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in + \cref{lst:mlb4} has been removed. + \end{itemize} + We examined each of these cases separately for clarity of explanation, but you can + combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one + file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using the + following command, for example \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml +\end{commandshell} + \end{widepage} + which gives the output in \vref{lst:env-mlb1-tex}. + + \paragraph{About trailing horizontal space} + Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field + \texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if + horizontal space should be removed \texttt{beforeProcessing} and + \texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant when + considering the \texttt{-m} switch; let's consider the file shown in \cref{lst:mlb5}, + which highlights trailing spaces. + + \begin{cmhtcbraster} + \begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5} +before words (*@$\BeginStartsOnOwnLine$@*) +\begin{myenv} (*@$\BodyStartsOnOwnLine$@*) +body of myenv (*@$\EndStartsOnOwnLine$@*) +\end{myenv} (*@$\EndFinishesWithLineBreak$@*) +after words +\end{cmhlistings} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before} + \end{cmhtcbraster} + + The output from the following commands \index{switches!-l demonstration} + \index{switches!-m demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml +latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml +\end{commandshell} + \end{widepage} + is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note + that the trailing horizontal white space has been preserved (by default) in + \cref{lst:env-mlb5-modAll}, while in \cref{lst:env-mlb5-modAll-remove-WS}, it has been + removed using the switch specified in \cref{lst:removeTWS-before}. + + \begin{widepage} + \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll} + + \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS} + \end{widepage} + + \paragraph{poly-switch line break removal and blank lines} + Now let's consider the file in \cref{lst:mlb6}, which contains blank lines. + \index{poly-switches!blank lines} + + \begin{cmhtcbraster} + \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6} +before words(*@$\BeginStartsOnOwnLine$@*) + + +\begin{myenv}(*@$\BodyStartsOnOwnLine$@*) + + +body of myenv(*@$\EndStartsOnOwnLine$@*) + + +\end{myenv}(*@$\EndFinishesWithLineBreak$@*) + +after words +\end{cmhlistings} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines} + \end{cmhtcbraster} + + Upon running the following commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{widepage} + \begin{commandshell} +latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml +latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml +\end{commandshell} + \end{widepage} + we receive the respective outputs in + \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In + \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed + into one blank line, but that blank lines have \emph{not} been removed by the + poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set to + \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have + allowed the poly-switches to remove blank lines because, in + \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}. + + \begin{cmhtcbraster}[ raster left skip=-3.5cm, + raster right skip=-2cm, + raster force size=false, + raster column 1/.style={add to width=-.2\textwidth}, + raster column 2/.style={add to width=.2\textwidth}, + raster column skip=.06\linewidth] + \cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb6-modAll} + \cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines} + \end{cmhtcbraster} + + We can explore this further using the blank-line poly-switch value of $3$; let's use the + file given in \cref{lst:env-mlb7-tex}. + + \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex} + + Upon running the following commands \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml +latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml +\end{commandshell} + we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}. + + \cmhlistingsfromfile{demonstrations/env-mlb7-preserve.tex}{\texttt{env-mlb7-preserve.tex}}{lst:env-mlb7-preserve} + \cmhlistingsfromfile{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve} + + Notice that in: + \begin{itemize} + \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, + because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and + even though the line break ahead of \lstinline!\begin{two}! should have been removed + (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has + been preserved by default; + \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, + because of the settings in \cref{lst:UnpreserveBlankLines}. + \end{itemize} + +\subsubsection{Poly-switches for double back slash}\label{subsec:dbs} + With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic}) + \announce{2019-07-13}{poly-switch for double back slash} you can specify poly-switches to + dictate the line-break behaviour of double back slashes in environments + (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code + blocks (\vref{lst:specialafter}). Note that for these poly-switches to take effect, the + name of the code block must necessarily be specified within \texttt{lookForAlignDelims} + (\vref{lst:aligndelims:basic}); we will demonstrate this in what follows. + \index{delimiters!poly-switches for double back slash} \index{modifying linebreaks! + surrounding double back slash} \index{poly-switches!for double back slash (delimiters)}% + + Consider the code given in \cref{lst:dbs-demo}. + \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo} +\begin{tabular}{cc} + 1 & 2 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) 3 & 4 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) +\end{tabular} +\end{cmhlistings} + Referencing \cref{lst:dbs-demo}: + \begin{itemize} + \item \texttt{DBS} stands for \emph{double back slash}; + \item line breaks ahead of the double back slash are annotated by $\ElseStartsOnOwnLine$, and + are controlled by \texttt{DBSStartsOnOwnLine}; + \item line breaks after the double back slash are annotated by $\ElseFinishesWithLineBreak$, + and are controlled by \texttt{DBSFinishesWithLineBreak}. + \end{itemize} + + Let's explore each of these in turn. + + \paragraph{Double back slash starts on own line} + We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo}); + starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in + \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands \index{switches!-l + demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m tabular3.tex -l DBS1.yaml +latexindent.pl -m tabular3.tex -l DBS2.yaml +\end{commandshell} + then we receive the respective output given in \cref{lst:tabular3-DBS1} and + \cref{lst:tabular3-DBS2}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/tabular3-mod1.tex}{\texttt{tabular3.tex} using \cref{lst:DBS1}}{lst:tabular3-DBS1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS1.yaml}[MLB-TCB]{\texttt{DBS1.yaml}}{lst:DBS1} + \end{cmhtcbraster} + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/tabular3-mod2.tex}{\texttt{tabular3.tex} using \cref{lst:DBS2}}{lst:tabular3-DBS2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS2.yaml}[MLB-TCB]{\texttt{DBS2.yaml}}{lst:DBS2} + \end{cmhtcbraster} + + We note that + \begin{itemize} + \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for + \emph{every} environment (that is within \texttt{lookForAlignDelims}, + \vref{lst:aligndelims:advanced}); + the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in + \cref{lst:tabular3-DBS1}; + \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a + \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, + \vref{lst:aligndelims:advanced}); + the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in + \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. + \end{itemize} + + \paragraph{Double back slash finishes with line break} + Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in + \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the + YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following + commands \index{poly-switches!for double back slash (delimiters)} \index{switches!-l + demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m tabular3.tex -l DBS3.yaml +latexindent.pl -m tabular3.tex -l DBS4.yaml +\end{commandshell} + then we receive the respective output given in \cref{lst:tabular3-DBS3} and + \cref{lst:tabular3-DBS4}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/tabular3-mod3.tex}{\texttt{tabular3.tex} using \cref{lst:DBS3}}{lst:tabular3-DBS3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS3.yaml}[MLB-TCB]{\texttt{DBS3.yaml}}{lst:DBS3} + \end{cmhtcbraster} + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/tabular3-mod4.tex}{\texttt{tabular3.tex} using \cref{lst:DBS4}}{lst:tabular3-DBS4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS4.yaml}[MLB-TCB]{\texttt{DBS4.yaml}}{lst:DBS4} + \end{cmhtcbraster} + + We note that + \begin{itemize} + \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for + \emph{every} environment (that is within \texttt{lookForAlignDelims}, + \vref{lst:aligndelims:advanced}); + the code following the double back slashes from \cref{lst:dbs-demo} has been moved to + their own line in \cref{lst:tabular3-DBS3}; + \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a + \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, + \vref{lst:aligndelims:advanced}); + the first double back slashes from \cref{lst:dbs-demo} have moved code following them to + their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving + them; the final double back slashes have \emph{not} added a line break as they are at the + end of the body within the code block. + \end{itemize} + + \paragraph{Double back slash poly-switches for specialBeginEnd} + Let's explore the double back slash poly-switches for code blocks within + \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code + within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch + demonstration} \index{poly-switches!double backslash} \index{poly-switches!for double + back slash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters} + \index{linebreaks!summary of poly-switches} + + \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} + + Upon using the YAML settings in \cref{lst:DBS5}, and running the command + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m special4.tex -l DBS5.yaml +\end{commandshell} + then we receive the output given in \cref{lst:special4-DBS5}. \index{delimiters!with + specialBeginEnd and the -m switch} + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}, + raster column skip=.06\linewidth] + \cmhlistingsfromfile{demonstrations/special4-mod5.tex}{\texttt{special4.tex} using \cref{lst:DBS5}}{lst:special4-DBS5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS5.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS5.yaml}}{lst:DBS5} + \end{cmhtcbraster} + + There are a few things to note: + \begin{itemize} + \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within \texttt{lookForAlignDelims}; + without this, the double back slash poly-switches would be ignored for this code block; + \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks + following the double back slashes; + \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a + comment symbol, followed by a line break, as it is set to a value of 2. + \end{itemize} + + \paragraph{Double back slash poly-switches for optional and mandatory arguments} + For clarity, we provide a demonstration of controlling the double back slash + poly-switches for optional and mandatory arguments. We begin with the code in + \cref{lst:mycommand2}. \index{poly-switches!for double back slash (delimiters)} + + \cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2} + + Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command + \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m mycommand2.tex -l DBS6.yaml +latexindent.pl -m mycommand2.tex -l DBS7.yaml +\end{commandshell} + then we receive the output given in \cref{lst:mycommand2-DBS6,lst:mycommand2-DBS7}. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/mycommand2-mod6.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS6}}{lst:mycommand2-DBS6} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS6.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS6.yaml}}{lst:DBS6} + \end{cmhtcbraster} + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}, + raster column skip=.03\linewidth] + \cmhlistingsfromfile{demonstrations/mycommand2-mod7.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS7}}{lst:mycommand2-DBS7} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS7.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS7.yaml}}{lst:DBS7} + \end{cmhtcbraster} + + \paragraph{Double back slash optional square brackets} + The pattern matching for the double back slash will also, optionally, allow trailing + square brackets that contain a measurement of vertical spacing, for example + \lstinline!\\[3pt]!. \index{poly-switches!for double back slash (delimiters)} + + For example, beginning with the code in \cref{lst:pmatrix3} + + \cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3} + + and running the following command, using \cref{lst:DBS3}, \index{switches!-l + demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m pmatrix3.tex -l DBS3.yaml +\end{commandshell} + then we receive the output given in \cref{lst:pmatrix3-DBS3}. + + \cmhlistingsfromfile{demonstrations/pmatrix3-mod3.tex}{\texttt{pmatrix3.tex} using \cref{lst:DBS3}}{lst:pmatrix3-DBS3} + + You can customise the pattern for the double back slash by exploring the \emph{fine + tuning} field detailed in \vref{lst:fineTuning}. + +\subsubsection{Poly-switches for other code blocks} + Rather than repeat the examples shown for the environment code blocks (in + \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all + other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of + these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. + + Note also that, by design, line breaks involving, \texttt{filecontents} and + `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be modified + using \texttt{latexindent.pl}. \announce{2019-05-05}*{verbatim poly-switch} However, + there are two poly-switches available for \texttt{verbatim} code blocks: environments + (\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and + \texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}). + \index{specialBeginEnd!poly-switch summary} \index{verbatim!poly-switch summary} + \index{poly-switches!summary of all poly-switches}% + + \clearpage + \begin{longtable}{llll} + \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ + \toprule + Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\ + \midrule + environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\ + & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ + & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\ + & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\ + & \verb!after words! & & \\ + \cmidrule{2-4} + ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\ + & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ + & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine % + \announce{2018-04-27}{new ifElseFi code block poly-switches} \\ + & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\ + & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\ + & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\ + & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\ + & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\ + & \verb!after words! & & \\ + \cmidrule{2-4} + optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\ + & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\ + \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ + & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ + & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\ + & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\ + & \verb!...! & & \\ + \cmidrule{2-4} + mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\ + & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\ + \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ + & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ + & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\ + & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\ + & \verb!...! & & \\ + \cmidrule{2-4} + commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\ + & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\ + & $\langle$\itshape{arguments}$\rangle$ & & \\ + \cmidrule{2-4} + namedGroupingBracesBrackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\ + & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\ + & $\langle$\itshape{braces/brackets}$\rangle$ & & \\ + \cmidrule{2-4} + keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\ + & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\ + & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\ + \cmidrule{2-4} + items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\ + & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\ + & \verb!...! & & \\ + \cmidrule{2-4} + specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\ + & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\ + & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine % + \announce{2018-04-27}{new special code block poly-switches} \\ + & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\ + & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\ + & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\ + & after words & & \\ + \cmidrule{2-4} + verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\ + \announce{2019-05-05}{verbatim poly-switches} & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & VerbatimEndFinishesWithLineBreak \\ + & after words & & \\ + \bottomrule + \end{longtable} +\subsubsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches} + Some poly-switches need to be partnered together; in particular, when line breaks + involving the \emph{first} argument of a code block need to be accounted for using both + \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and + \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} + for optional arguments. \index{poly-switches!conflicting partnering} + + Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in + \cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key + \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}. + + \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} + + Upon running the command \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex +\end{commandshell} + we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument + beginning brace \lstinline!{! has had its leading line break removed, but that the + \emph{first} brace has not. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-1cm}, + ] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1} + \end{cmhtcbraster} + + Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running + the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both + beginning braces \lstinline!{! have had their leading line breaks removed. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-1cm}, + ] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2} + \end{cmhtcbraster} + + Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running + the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-1cm}, + ] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3} + \end{cmhtcbraster} + +\subsubsection{Conflicting poly-switches: sequential code blocks} + It is very easy to have conflicting poly-switches; if we use the example from + \vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The + output from running \index{poly-switches!conflicting switches} \index{switches!-l + demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex +\end{commandshell} + is given in \cref{lst:mycom-mlb4}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} + \end{cmhtcbraster} + + Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with + one another: + \begin{itemize} + \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as + poly-switch is set to $-1$); + \item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line + break. + \end{itemize} + So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is + clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that + \emph{the second argument was processed after the first} -- in general, the most + recently-processed code block and associated poly-switch takes priority. + + We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; + upon running the command \index{switches!-l demonstration} \index{switches!-m + demonstration} + \begin{commandshell} +latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex +\end{commandshell} + we obtain the output given in \cref{lst:mycommand1-mlb5}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} + \end{cmhtcbraster} + + As previously, the most-recently-processed code block takes priority -- as before, the + second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings + in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}. + + \begin{cmhtcbraster}[raster column skip=.1\linewidth] + \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} + \end{cmhtcbraster} + + Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this + is because: + \begin{itemize} + \item while processing the \emph{first} argument, the trailing line break has been removed + (\texttt{RCuBFinishesWithLineBreak} set to $-1$); + \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does + \emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to + $2$, it adds a comment, followed by a line break. + \end{itemize} + +\subsubsection{Conflicting poly-switches: nested code blocks} + Now let's consider an example when nested code blocks have conflicting poly-switches; + we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments. + \index{poly-switches!conflicting switches} + + \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} + + Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running + the command \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex +\end{commandshell} + gives the output in \cref{lst:nested-env-mlb1}. + + \begin{cmhtcbraster}[raster column skip=.05\linewidth] + \cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} + \end{cmhtcbraster} + + In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have + received the appropriate (default) indentation; secondly, note that the poly-switch + \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! + has had its leading line break removed. + + To understand it, let's talk about the three basic phases \label{page:phases}of + \texttt{latexindent.pl}: + \begin{enumerate} + \item Phase 1: packing, in which code blocks are replaced with unique ids, working from + \emph{the inside to the outside}, and then sequentially -- for example, in + \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the + \texttt{one} environment; if the -m switch is active, then during this phase: + \begin{itemize} + \item line breaks at the beginning of the \texttt{body} can be added (if + \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} + is $-1$); + \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or + $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$); + \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is + $1$ or $2$). + \end{itemize} + \item Phase 2: indentation, in which white space is added to the begin, body, and end + statements; + \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code + blocks; if the -m switch is active, then during this phase, + \begin{itemize} + \item line breaks before \texttt{begin} statements can be added or removed (depending upon + \texttt{BeginStartsOnOwnLine}); + \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see + \texttt{EndFinishesWithLineBreak}). + \end{itemize} + \end{enumerate} + + With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1: + \begin{itemize} + \item the \texttt{two} environment is found first, and the line break ahead of the + \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to + $-1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} + finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. + \item next, the \texttt{one} environment is found; the line break ahead of + \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. + \end{itemize} + The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line + break after the \lstinline!end! statements}. We can justify this by remembering that + during Phase 3, the \texttt{one} environment will be found and processed first, followed + by the \texttt{two} environment. If the \texttt{two} environment were to add a line break + after the \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way + of knowing how much indentation to add to the subsequent text (in this case, + \lstinline!\end{one}!). + + We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon + running the command \index{switches!-l demonstration} \index{switches!-m demonstration} + \begin{commandshell} +latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex +\end{commandshell} + we obtain the output given in \cref{lst:nested-env-mlb2-output}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2} + \end{cmhtcbraster} + + During Phase 1: + \begin{itemize} + \item the \texttt{two} environment is found first, and the line break ahead of the + \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set + to $1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} + finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. + \item next, the \texttt{one} environment is found; the line break ahead of + \lstinline!\end{one}! is already present, and no action is needed. + \end{itemize} + The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is + found and processed first, followed by the \texttt{two} environment. \emph{At this + stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so + it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has + completely finished with the \texttt{one} environment. +% arara: pdflatex: { files: [latexindent]} +\section{The -r, -rv and -rr switches}\label{sec:replacements} + \fancyhead[R]{\bfseries\thepage% + \tikz[remember picture,overlay] { + \node at (1,0){\includegraphics{logo-bw}}; } + } + + You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your + \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r}, + \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch} + \begin{itemize} + \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim + code blocks; + \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will} + respect verbatim code blocks; + \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform + replacements not respecting verbatim code blocks. + \end{itemize} + + We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but + a summary is given in \cref{tab:replacementswitches}. + + \begin{table}[!htb] + \centering + \caption{The replacement mode switches}\label{tab:replacementswitches} + \begin{tabular}{rcc} + \toprule + switch & indentation? & respect verbatim? \\ + \midrule + \texttt{-r} & \faCheck & \faClose \\ + \texttt{-rv} & \faCheck & \faCheck \\ + \texttt{-rr} & \faClose & \faClose \\ + \bottomrule + \end{tabular} + \end{table} + + The default value of the \texttt{replacements} field is shown in \cref{lst:replacements}; + as with all of the other fields, you are encouraged to customise and change this as you + see fit. The options in this field will \emph{only} be considered if the \texttt{-r}, + \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related + to the replacement-mode switches, we will use the style given in \cref{lst:replacements}. + + \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements} + + The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is + \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from + each settings file that you specify. As you'll see in the demonstrations that follow, + there is no need to specify this field. + + You'll notice that, by default, there is only \emph{one} entry in the + \texttt{replacements} field, but it can take as many entries as you would like; each one + needs to begin with a \texttt{-} on its own line. + +\subsection{Introduction to replacements} + Let's explore the action of the default settings, and then we'll demonstrate the feature + with further examples. With reference to \cref{lst:replacements}, the default action will + replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}. + + Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r + demonstration} + \begin{commandshell} +latexindent.pl -r replace1.tex +\end{commandshell} + gives the output given in \cref{lst:replace1-r1}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1} + \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1} + \end{cmhtcbraster} + + If we don't wish to perform this replacement, then we can tweak the default settings of + \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in + \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration} + \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r replace1.tex -l=replace1.yaml +\end{commandshell} + which gives the output in \cref{lst:replace1-mod1}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml} + \end{cmhtcbraster} + + Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that + the default replacements are overwritten. + + We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of + the discussion in what follows. + +\subsection{The two types of replacements} + There are two types of replacements: + \begin{enumerate} + \item \emph{string}-based replacements, which replace the string in + \emph{this} with the string in \emph{that}. + If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that} + field will be assumed to be empty. + \index{regular expressions!replacement switch, -r} + \item \emph{regex}-based replacements, which use the \texttt{substitution} field. + \end{enumerate} + We will demonstrate both in the examples that follow. + + \texttt{latexindent.pl} chooses which type of replacement to make based on which fields + have been specified; if the \texttt{this} field is specified, then it will make + \emph{string}-based replacements, regardless of if \texttt{substitution} is present or + not. + +\subsection{Examples of replacements} + \begin{example} + We begin with code given in \cref{lst:colsep} + + \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep} + + Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we + can achieve this in a few different ways. + + Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l + demonstration} \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r colsep.tex -l=colsep.yaml +\end{commandshell} + then we achieve the output in \cref{lst:colsep-mod0}. + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml} + \end{cmhtcbraster} + Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each + with their own `\emph{this}' field; furthermore, for both of the separate fields, we have + not specified `\texttt{that}', so the \texttt{that} field is assumed to be blank by + \texttt{latexindent.pl}; + + We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the + \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the + command \index{switches!-l demonstration} \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r colsep.tex -l=colsep1.yaml +\end{commandshell} + then we achieve the output in \cref{lst:colsep-mod1}. \index{regular + expressions!substitution field, arraycolsep} \index{regular expressions!at least one +} + \begin{cmhtcbraster}[raster column skip=.01\linewidth, + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}] + \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1} + \end{cmhtcbraster} + + The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which + we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a + tutorial on regular expressions; you might like to read, for example, + \cite{masteringregexp} for a detailed covering of the topic. With reference to + \cref{lst:colsep1}, we do note the following: + \begin{itemize} + \item the general form of the \texttt{substitution} field is + \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like + within this; + \item we have `escaped' the backslash by using \lstinline!\\! + \item we have used \lstinline!\d+! to represent \emph{at least} one digit + \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs + \texttt{latexindent.pl} to treat your file as one single line; + \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs + \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file; + you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the + difference in output. + \end{itemize} + You might like to see + \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers} + for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers + for this feature. + \end{example} + + \begin{example} + We'll keep working with the file in \vref{lst:colsep} for this example. + + Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l + demonstration} \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r colsep.tex -l=multi-line.yaml +\end{commandshell} + then we achieve the output in \cref{lst:colsep-mod2}. + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line} + \end{cmhtcbraster} + With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of + \texttt{this} by employing the \emph{literal} YAML style \lstinline!|-!. See, for + example, + \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines} + for further options, all of which can be used in your YAML file. + + This is a natural point to explore the \texttt{when} field, specified in + \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after}, + which respectively instruct \texttt{latexindent.pl} to perform the replacements + \emph{before} indentation or \emph{after} it. The default value is \texttt{before}. + + Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l + demonstration} \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r colsep.tex -l=multi-line1.yaml +\end{commandshell} + then we achieve the output in \cref{lst:colsep-mod3}. + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1} + \end{cmhtcbraster} + We note that, because we have specified \texttt{when: after}, that + \texttt{latexindent.pl} has not found the string specified in \cref{lst:multi-line1} + within the file in \vref{lst:colsep}. As it has looked for the string within + \cref{lst:multi-line1} \emph{after} the indentation has been performed. After + indentation, the string as written in \cref{lst:multi-line1} is no longer part of the + file, and has therefore not been replaced. + + As a final note on this example, if you use the \texttt{-rr} switch, as follows, + \index{switches!-l demonstration} \index{switches!-rr demonstration} + \begin{commandshell} +latexindent.pl -rr colsep.tex -l=multi-line1.yaml +\end{commandshell} + then the \texttt{when} field is ignored, no indentation is done, and the output is as in + \cref{lst:colsep-mod2}. + \end{example} + + \begin{example} + An important part of the substitution routine is in \emph{capture groups}. + + Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our + goal is to replace each occurrence of \lstinline!$$...$$! with + \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by + \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex + stackexchange question 242150}. + + \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath} + + We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l + demonstration} \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r displaymath.tex -l=displaymath1.yaml +\end{commandshell} + to receive the output given in \cref{lst:displaymath-mod1}. \index{regular + expressions!substitution field, equation} + + \begin{cmhtcbraster}[raster left skip=-3.75cm, + raster right skip=-2cm,] + \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1} + \end{cmhtcbraster} + + A few notes about \cref{lst:displaymath1}: + \begin{enumerate} + \item we have used the \texttt{x} modifier, which allows us to have white space within the + regex; + \item we have used a capture group, \lstinline!(.*?)! which captures the content between the + \lstinline!$$...$$! into the special variable, \lstinline!$1!; + \item we have used the content of the capture group, \lstinline!$1!, in the replacement text. + \end{enumerate} + See + \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups} + for a discussion of capture groups. + + The features of the replacement switches can, of course, be combined with others from the + toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of + \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command + \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r + demonstration} + \begin{commandshell} +latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml +\end{commandshell} + then we receive the output in \cref{lst:displaymath-mod2}. + + \begin{cmhtcbraster}[ + raster force size=false, + raster column 1/.style={add to width=-.1\textwidth}, + raster column skip=.06\linewidth] + \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation} + \end{cmhtcbraster} + \end{example} + + \begin{example} + This example is motivated by + \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex + stackexchange question 490086}. We begin with the code in \cref{lst:phrase}. + + \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase} + + Our goal is to make the spacing uniform between the phrases. To achieve this, we employ + the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration} + \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r phrase.tex -l=hspace.yaml +\end{commandshell} + which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one + +} \index{regular expressions!horizontal space \textbackslash{h}} + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace} + \end{cmhtcbraster} + + The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one + horizontal space} with a single space. + \end{example} + + \begin{example} + We begin with the code in \cref{lst:references}. + + \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references} + + Our goal is to change each reference so that both the text and the reference are + contained within one hyperlink. We achieve this by employing \cref{lst:reference} and + running the command \index{switches!-l demonstration} \index{switches!-r demonstration} + \begin{commandshell} +latexindent.pl -r references.tex -l=reference.yaml +\end{commandshell} + which gives the output in \cref{lst:references-mod1}. \index{regular + expressions!horizontal space \textbackslash{h}} + + \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1} + + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference} + + Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used + \emph{capture groups}, together with an example of an \emph{optional} pattern, + \lstinline!(?:eq)?!. + \end{example} + + \begin{example} + Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in + the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will + use the settings in \cref{lst:verbatim1-yaml}. + + \begin{cmhtcbraster} + \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml} + \end{cmhtcbraster} + + Upon running the following commands, \index{verbatim!comparison with -r and -rr switches} + \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r + demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration} + \begin{commandshell} +latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1 +latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1 +latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 +\end{commandshell} + we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1} + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.75cm, + raster right skip=-2cm,] + \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1} + \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1} + \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1} + \end{cmhtcbraster} + \end{example} + + We note that: + \begin{enumerate} + \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements + specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code + block; + \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements + have \emph{not} been performed within the verbatim environment, because the \texttt{rv} + switch is active; + \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that + replacements have been performed, not respecting the verbatim code block. + \end{enumerate} + See the summary within \vref{tab:replacementswitches}. + + \begin{example} + Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context + of the file specified in \cref{lst:amalg1}. + + \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1} + + Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}. + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.75cm, + raster right skip=-2cm,] + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml} + \end{cmhtcbraster} + + Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r + demonstration} + \begin{commandshell} +latexindent.pl -r amalg1.tex -l=amalg1-yaml +latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml +latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml +\end{commandshell} + we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}. + + \begin{cmhtcbraster}[raster columns=3, + raster left skip=-3.75cm, + raster right skip=-2cm,] + \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1} + \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12} + \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123} + \end{cmhtcbraster} + We note that: + \begin{enumerate} + \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used; + \item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml} + have \emph{both} been used, because the default value of \texttt{amalgamate} is 1; + \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have + been used, because the value of \texttt{amalgamate} has been set to 0. + \end{enumerate} + \end{example} +% arara: pdflatex: { files: [latexindent]} +\section{The --lines switch}\label{sec:line-switch} + \texttt{latexindent.pl} + \announce{2021-09-16}{line switch demonstration} can + operate on a \emph{selection} of lines of the file using the \texttt{--lines} or + \texttt{-n} switch. + + \index{switches!-lines demonstration} + + The basic syntax is \texttt{--lines MIN-MAX}, so for example + \begin{commandshell} +latexindent.pl --lines 3-7 myfile.tex +latexindent.pl -n 3-7 myfile.tex +\end{commandshell} + will only operate upon lines 3 to 7 in \texttt{myfile.tex}. All of the other lines will + \emph{not} be operated upon by \texttt{latexindent.pl}. + + The options for the \texttt{lines} switch are: + \begin{itemize} + \item line range, as in \texttt{--lines 3-7} + \item single line, as in \texttt{--lines 5} + \item multiple line ranges separated by commas, as in \texttt{--lines 3-5,8-10} + \item negated line ranges, as in \texttt{--lines !3-5} which translates to \texttt{--lines + 1-2,6-N}, where N is the number of lines in your file. + \end{itemize} + + We demonstrate this feature, and the available variations in what follows. We will use + the file in \cref{lst:myfile}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile.tex}[tex-TCB]{\texttt{myfile.tex}}{lst:myfile} + + \begin{example} + We demonstrate the basic usage using the command + \begin{commandshell} +latexindent.pl --lines 3-7 myfile.tex -o=+-mod1 +\end{commandshell} + which instructs \texttt{latexindent.pl} to only operate on lines 3 to 7; the output is + given in \cref{lst:myfile-mod1}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod1.tex}[tex-TCB]{\texttt{myfile-mod1.tex}}{lst:myfile-mod1} + + The following two calls to \texttt{latexindent.pl} are equivalent + \begin{commandshell} +latexindent.pl --lines 3-7 myfile.tex -o=+-mod1 +latexindent.pl --lines 7-3 myfile.tex -o=+-mod1 +\end{commandshell} + as \texttt{latexindent.pl} performs a check to put the lowest number first. + \end{example} + + \begin{example} + You can call the \texttt{lines} switch with only \emph{one number} and in which case only + that line will be operated upon. For example + \begin{commandshell} +latexindent.pl --lines 5 myfile.tex -o=+-mod2 +\end{commandshell} + instructs \texttt{latexindent.pl} to only operate on line 5; the output is given in + \cref{lst:myfile-mod2}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod2.tex}[tex-TCB]{\texttt{myfile-mod2.tex}}{lst:myfile-mod2} + + The following two calls are equivalent: + \begin{commandshell} +latexindent.pl --lines 5 myfile.tex +latexindent.pl --lines 5-5 myfile.tex +\end{commandshell} + \end{example} + + \begin{example} + If you specify a value outside of the line range of the file then \texttt{latexindent.pl} + will ignore the \texttt{lines} argument, detail as such in the log file, and proceed to + operate on the entire file. + + For example, in the following call + \begin{commandshell} +latexindent.pl --lines 11-13 myfile.tex + \end{commandshell} + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because \cref{lst:myfile} only has 12 lines. + + Similarly, in the call + \begin{commandshell} +latexindent.pl --lines -1-3 myfile.tex + \end{commandshell} + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because we assume that negatively numbered + lines in a file do not exist. + \end{example} + + \begin{example} + You can specify \emph{multiple line ranges} as in the following + \begin{commandshell} +latexindent.pl --lines 3-5,8-10 myfile.tex -o=+-mod3 +\end{commandshell} + which instructs \texttt{latexindent.pl} to operate upon lines 3 to 5 and lines 8 to 10; + the output is given in \cref{lst:myfile-mod3}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod3.tex}[tex-TCB]{\texttt{myfile-mod3.tex}}{lst:myfile-mod3} + + The following calls to \texttt{latexindent.pl} are all equivalent + \begin{commandshell} +latexindent.pl --lines 3-5,8-10 myfile.tex +latexindent.pl --lines 8-10,3-5 myfile.tex +latexindent.pl --lines 10-8,3-5 myfile.tex +latexindent.pl --lines 10-8,5-3 myfile.tex +\end{commandshell} + as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and + within each line range, it puts the lowest number first. + \end{example} + + \begin{example} + There's no limit to the number of line ranges that you can specify, they just need to be + separated by commas. For example + \begin{commandshell} +latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex -o=+-mod4 +\end{commandshell} + has four line ranges: lines 1 to 2, lines 4 to 5, lines 9 to 10 and line 12. The output + is given in \cref{lst:myfile-mod4}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod4.tex}[tex-TCB]{\texttt{myfile-mod4.tex}}{lst:myfile-mod4} + + As previously, the ordering does not matter, and the following calls to + \texttt{latexindent.pl} are all equivalent + \begin{commandshell} +latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex +latexindent.pl --lines 2-1,4-5,9-10,12 myfile.tex +latexindent.pl --lines 4-5,1-2,9-10,12 myfile.tex +latexindent.pl --lines 12,4-5,1-2,9-10 myfile.tex +\end{commandshell} + as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and + within each line range, it puts the lowest number first. + \end{example} + + \begin{example} + \index{switches!-lines demonstration, negation} + You can specify \emph{negated line ranges} by using \texttt{!} as in + \begin{commandshell} +latexindent.pl --lines !5-7 myfile.tex -o=+-mod5 +\end{commandshell} + which instructs \texttt{latexindent.pl} to operate upon all of the lines \emph{except} + lines 5 to 7. + + In other words, \texttt{latexindent.pl} \emph{will} operate on lines 1 to 4, and 8 to 12, + so the following two calls are equivalent: + \begin{commandshell} +latexindent.pl --lines !5-7 myfile.tex +latexindent.pl --lines 1-4,8-12 myfile.tex +\end{commandshell} + The output is given in \cref{lst:myfile-mod5}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod5.tex}[tex-TCB]{\texttt{myfile-mod5.tex}}{lst:myfile-mod5} + + \end{example} + + \begin{example} + \index{switches!-lines demonstration, negation} + You can specify \emph{multiple negated line ranges} such as + \begin{commandshell} +latexindent.pl --lines !5-7,!9-10 myfile.tex -o=+-mod6 + \end{commandshell} + which is equivalent to: + \begin{commandshell} +latexindent.pl --lines 1-4,8,11-12 myfile.tex -o=+-mod6 + \end{commandshell} + The output is given in \cref{lst:myfile-mod6}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod6.tex}[tex-TCB]{\texttt{myfile-mod6.tex}}{lst:myfile-mod6} + \end{example} + + \begin{example} + If you specify a line range with anything other than an integer, then + \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the + entire file}. + + Sample calls that result in the \texttt{lines} argument being ignored include the + following: + \begin{commandshell} +latexindent.pl --lines 1-x myfile.tex +latexindent.pl --lines !y-3 myfile.tex + \end{commandshell} + \end{example} + + \begin{example} + We can, of course, use the \texttt{lines} switch in combination with other switches. + + For example, let's use with the file in \cref{lst:myfile1}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1.tex}[tex-TCB]{\texttt{myfile1.tex}}{lst:myfile1} + + We can demonstrate interaction with the \texttt{-m} switch (see + \vref{sec:modifylinebreaks}); in particular, if we use \vref{lst:mlb2}, + \vref{lst:env-mlb7} and \vref{lst:env-mlb8} and run + \begin{widepage} + \begin{commandshell} +latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 -o=+-mod1 + \end{commandshell} + \end{widepage} + then we receive the output in \cref{lst:myfile1-mod1}. + + \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1-mod1.tex}[tex-TCB]{\texttt{myfile1-mod1.tex}}{lst:myfile1-mod1} + \end{example} +% arara: pdflatex: { files: [latexindent]} +\section{Fine tuning}\label{sec:finetuning} + \texttt{latexindent.pl} operates by looking for the code blocks detailed in + \vref{tab:code-blocks}. + \announce{2019-07-13}{details of fine tuning of code blocks} The fine tuning of the + details of such code blocks is controlled by the \texttt{fineTuning} field, detailed in + \cref{lst:fineTuning}. + + This field is for those that would like to peek under the bonnet/hood and make some fine + tuning to \texttt{latexindent.pl}'s operating. \index{warning!fine tuning} \index{regular + expressions!fine tuning} \index{regular expressions!environments} \index{regular + expressions!ifElseFi} \index{regular expressions!commands} \index{regular + expressions!keyEqualsValuesBracesBrackets} \index{regular + expressions!NamedGroupingBracesBrackets} \index{regular + expressions!UnNamedGroupingBracesBrackets} \index{regular expressions!arguments} + \index{regular expressions!modifyLineBreaks} \index{regular expressions!lowercase alph + a-z} \index{regular expressions!uppercase alph A-Z} \index{regular expressions!numeric + 0-9} \index{regular expressions!at least one +} \index{regular expressions!horizontal + space \textbackslash{h}} + + \begin{warning} + Making changes to the fine tuning may have significant consequences for your indentation + scheme, proceed with caution! + \end{warning} + + \begin{widepage} + \cmhlistingsfromfile[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,enhanced jigsaw,breakable,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} + \end{widepage} + + The fields given in \cref{lst:fineTuning} are all \emph{regular expressions}. This manual + is not intended to be a tutorial on regular expressions; you might like to read, for + example, \cite{masteringregexp} for a detailed covering of the topic. + + We make the following comments with reference to \cref{lst:fineTuning}: + \begin{enumerate} + \item the \texttt{environments:name} field details that the \emph{name} of an environment can + contain: + \begin{enumerate} + \item \texttt{a-z} lower case letters + \item \texttt{A-Z} upper case letters + \item \texttt{@} the \texttt{@} 'letter' + \item \lstinline!\*! stars + \item \texttt{0-9} numbers + \item \lstinline!_! underscores + \item \lstinline!\! backslashes + \end{enumerate} + \index{regular expressions!at least one +} + The \texttt{+} at the end means \emph{at least one} of the above characters. + \item the \texttt{ifElseFi:name} field: + \begin{enumerate} + \item \lstinline^@?^ means that it \emph{can possibly} begin with + \lstinline^@^ + \item followed by \texttt{if} + \item followed by 0 or more characters from \texttt{a-z}, \texttt{A-Z} and \texttt{@} + \item the \texttt{?} the end means \emph{non-greedy}, which means `stop the match as soon as + possible' + \end{enumerate} + \item the \texttt{keyEqualsValuesBracesBrackets} contains some interesting syntax: + \begin{enumerate} + \item \lstinline!|! means `or' + \item \lstinline^(?:(?^ is designed for 'beamer'-type commands; the + \lstinline^.*?^ means anything in between \lstinline^<...>^ + \end{enumerate} + \item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in + \vref{sec:modifylinebreaks}. In particular: + \begin{enumerate} + \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in + \vref{sec:onesentenceperline} + \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and + \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double back slashes, see + \vref{subsec:dbs} + \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and + \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and + mandatory arguments; see \vref{tab:poly-switch-mapping} + \end{enumerate} + \end{enumerate} + + It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow}, + \texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and + horizontal spaces between each character. + + \index{warning!capture groups} + \begin{warning} + For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, + such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)! + \end{warning} + + \begin{example} + As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its + default output using the command + \begin{commandshell} +latexindent.pl finetuning1.tex +\end{commandshell} + is given in \cref{lst:finetuning1-default}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1} + \cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default} + \end{cmhtcbraster} + + It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked + as expected. We can \emph{fine tune} the indentation scheme by employing the settings + given in \cref{lst:fine-tuning1} and running the command \index{switches!-l + demonstration} + \begin{commandshell} +latexindent.pl finetuning1.tex -l=fine-tuning1.yaml +\end{commandshell} + and the associated (desired) output is given in \cref{lst:finetuning1-mod1}. + \index{regular expressions!at least one +} + + \begin{cmhtcbraster}[raster column skip=.01\linewidth] + \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1} + \end{cmhtcbraster} + \end{example} + + \begin{example} + Let's have another demonstration; consider the file given in \cref{lst:finetuning2}, + together with its default output using the command + \begin{commandshell} +latexindent.pl finetuning2.tex +\end{commandshell} + is given in \cref{lst:finetuning2-default}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth, + raster left skip=-3.75cm, + raster right skip=0cm,] + \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2} + \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default} + \end{cmhtcbraster} + + It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked + as expected. We can \emph{fine tune} the indentation scheme by employing the settings + given in \cref{lst:fine-tuning2} and running the command \index{switches!-l + demonstration} + \begin{commandshell} +latexindent.pl finetuning2.tex -l=fine-tuning2.yaml +\end{commandshell} + and the associated (desired) output is given in \cref{lst:finetuning2-mod1}. + + \begin{cmhtcbraster}[raster column skip=.01\linewidth, + raster left skip=-3.75cm, + raster right skip=0cm,] + \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1} + \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2} + \end{cmhtcbraster} + + In particular, note that the settings in \cref{lst:fine-tuning2} specify that + \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can + follow \texttt{"} and that we allow \lstinline!---! between arguments. + \end{example} + + \begin{example} + You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use + quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and + running the following command + \begin{commandshell} +latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(?myfile.tex} + + Similarly, + \begin{commandshell} +latexindent.pl myfile*.tex -o=++ +\end{commandshell} + \emph{will} work because the `existence check/incrementation' routine will be applied. + + \subsection{interaction with lines switch} + This behaves as expected by attempting to operate on the line numbers specified for each file. See + the examples in \cref{sec:line-switch}. + + \subsection{interaction with check switches} + The exit codes for \texttt{latexindent.pl} are given in \vref{tab:exit-codes}. + + When operating on multiple files with the check switch active, as in + \begin{commandshell} +latexindent.pl myfile*.tex --check + \end{commandshell} + then + \begin{itemize} + \item exit code 0 means that the text from \emph{none} of the files has been changed; + \item exit code 1 means that the text from \emph{at least one} of the files been file changed. + \end{itemize} + + The interaction with \texttt{checkv} switch is as in the check switch, but with verbose + output. + + \subsection{when a file does not exist} + What happens if one of the files can not be operated upon? + \begin{itemize} + \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called + to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl} + will try to operate on each file that it is called upon, and will not exit with a fatal + message in this case; + \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called + to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl} + will try to operate on each file that it is called upon, and will not exit with a fatal + message in this case; + \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not + exist and some cannot be read, then the exit code will be either 3 or 4, depending upon + which it scenario it encountered most recently. + \end{itemize} + + \section{latexindent-yaml-schema.json} + + \texttt{latexindent.pl} + \announce{2022-01-02}{latexindent-yaml-schema.json} ships with + \texttt{latexindent-yaml-schema.json} + which might help you when constructing your YAML files. + \index{json!schema for YAML files} + + \subsection{VSCode demonstration} + To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the + following steps: \index{VSCode} \index{json!VSCode} + \begin{enumerate} + \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of + \cite{latexindent-home}, save it in whichever directory you would like, noting it for + reference; + \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install + the VSCode YAML extension \cite{vscode-yaml-extentions}; + \item set up your \texttt{settings.json} file using the directory you saved the file by + adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at + \texttt{/home/cmhughes/.config/Code/User/settings.json}. + \end{enumerate} + + \begin{widepage} + \cmhlistingsfromfile{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json} + \end{widepage} + + Alternatively, if you would prefer not to download the json file, you might be able to + use an adapted version of \cref{lst:settings-alt.json}. + + \begin{widepage} + \cmhlistingsfromfile{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json} + \end{widepage} + + Finally, if your TeX distribution is up to date, then + \texttt{latexindent-yaml-schema.json} \emph{should} be in the documentation folder of + your installation, so an adapted version of \cref{lst:settings-alt1.json} may work. + + \begin{widepage} + \cmhlistingsfromfile{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json} + \end{widepage} + + If you have details of how to implement this schema in other editors, please feel + encouraged to contribute to this documentation. + + \section{Using conda}\label{sec:app:conda} + If you use conda you'll only need + \begin{commandshell} +conda install latexindent.pl -c conda-forge +\end{commandshell} + This will install the executable and all its dependencies (including perl) in the + activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} as + it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}. + \index{conda} + + You can get a conda installation for example from \cite{conda} or from \cite{anacoda}. + + \subsection{Sample conda installation on Ubuntu} + On Ubuntu I followed the 64-bit installation instructions at \cite{condainstallubuntu} + and then I ran the following commands: + \begin{commandshell} +conda create -n latexindent.pl +conda activate latexindent.pl +conda install latexindent.pl -c conda-forge +conda info --envs +conda list +conda run latexindent.pl -vv +\end{commandshell} + I found the details given at \cite{condainstallhelp} to be helpful. + + \section{Using docker}\label{sec:app:docker} + If you use docker you'll only need \announce{2022-06-12}{docker support} + \begin{commandshell} +docker pull ghcr.io/cmhughes/latexindent.pl +\end{commandshell} + This will download the image packed \texttt{latexindent}'s executable and its all + dependencies. \index{docker} Thank you to \cite{eggplants} for contributing this feature; + see also \cite{cmhughesio}. For reference, \emph{ghcr} stands for \emph{GitHub Container + Repository}. + + \subsection{Sample docker installation on Ubuntu} + To pull the image and show \texttt{latexindent}'s help on Ubuntu: + + \begin{cmhlistings}*[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install} +# setup docker if not already installed +if ! command -v docker &> /dev/null; then + sudo apt install docker.io -y + sudo groupadd docker + sudo gpasswd -a "$USER" docker + sudo systemctl restart docker +fi + +# download image and execute +docker pull ghcr.io/cmhughes/latexindent.pl +docker run ghcr.io/cmhughes/latexindent.pl -h +\end{cmhlistings} + + \subsection{How to format on Docker} + When you use \texttt{latexindent} with the docker image, you have to mount target \texttt{tex} file like this: + \begin{commandshell} +docker run -v /path/to/local/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s -w myfile.tex +\end{commandshell} + + \section{pre-commit} + + Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for + latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is + supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for + contributing this feature, and to \cite{holzhausprecommit} for their contribution to it. + + To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample + instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there + are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda}, + detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively. + + \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu} + On Ubuntu I ran the following command: + \begin{commandshell} +python3 -m pip install pre-commit +\end{commandshell} + I then updated my path via .bashrc so that it includes the line in + \cref{lst:bashrc-update}. + \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{.bashrc} update}{lst:bashrc-update} +... +export PATH=$PATH:/home/cmhughes/.local/bin +\end{cmhlistings} + + \subsection{pre-commit defaults} + The default values that are employed by \texttt{pre-commit} are shown in \cref{lst:.pre-commit-yaml-default}. + \index{pre-commit!default} + + \cmhlistingsfromfile{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default} + + In particular, the decision has deliberately been made (in collaboration with + \cite{holzhausprecommit}) to have the default to employ the following switches: + \texttt{overwriteIfDifferent}, \texttt{silent}, \texttt{local}; this is detailed in the + lines that specify \texttt{args} in \cref{lst:.pre-commit-yaml-default}. + + \index{pre-commit!warning} + \index{warning!pre-commit} + \begin{warning} + Users of \texttt{pre-commit} will, by default, have the \texttt{overwriteIfDifferent} + switch employed. It is assumed that such users have version control in place, and are + intending to overwrite their files. + \end{warning} + + \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan} + + To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file + \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your + git-repository. \index{cpan} \index{git} \index{pre-commit!cpan} + + \cmhlistingsfromfile{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan} + Once created, you should then be able to run the following command: + \begin{commandshell} +pre-commit run --all-files +\end{commandshell} + A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: + \begin{itemize} + \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct + \texttt{pre-commit} to use \texttt{CPAN} to get dependencies; + \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system; + \item the \texttt{args} lists selected command-line options; the settings in + \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling + \begin{commandshell} +latexindent.pl -s myfile.tex +\end{commandshell} + for each \texttt{.tex} file in your repository; + \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you + can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. + \end{itemize} + + Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your + preference. + + \subsection{pre-commit using conda}\label{sec:pre-commit-conda} + + You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of + \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. + \index{conda} \index{git} \index{pre-commit!conda} + + \cmhlistingsfromfile{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda} + Once created, you should then be able to run the following command: + \begin{commandshell} +pre-commit run --all-files +\end{commandshell} + A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: + \begin{itemize} + \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct + \texttt{pre-commit} to use \texttt{conda} to get dependencies; + \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system; + \item the \texttt{args} lists selected command-line options; the settings in + \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling + \begin{commandshell} +conda run latexindent.pl -s myfile.tex +\end{commandshell} + for each \texttt{.tex} file in your repository; + \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you + can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. + \end{itemize} + + \subsection{pre-commit using docker}\label{sec:pre-commit-docker} + + You can also rely on \texttt{docker} (detailed in \cref{sec:app:docker}) instead of + \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. + \index{docker} \index{git} \index{pre-commit!docker} + + \cmhlistingsfromfile{demonstrations/pre-commit-config-docker.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (docker)}{lst:.pre-commit-config.yaml-docker} + Once created, you should then be able to run the following command: + \begin{commandshell} +pre-commit run --all-files +\end{commandshell} + A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: + \begin{itemize} + \item the settings given in \cref{lst:.pre-commit-config.yaml-docker} instruct + \texttt{pre-commit} to use \texttt{docker} to get dependencies; + \item this requires \texttt{pre-commit} and \texttt{docker} to be installed on your system; + \item the \texttt{args} lists selected command-line options; the settings in + \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling + \begin{commandshell} +docker run -v /path/to/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s myfile.tex +\end{commandshell} + for each \texttt{.tex} file in your repository; + \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you + can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. + \end{itemize} + + \subsection{pre-commit example using -l, -m switches} + Let's consider a small example, with local \texttt{latexindent.pl} settings in + \texttt{.latexindent.yaml}. + + \begin{example} + We use the local settings given in \cref{lst:.latexindent.yaml}. + \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml} +onlyOneBackUp: 1 + +modifyLineBreaks: + oneSentencePerLine: + manipulateSentences: 1 +\end{cmhlistings} + + and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}: + + \cmhlistingsfromfile{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches} + Now running + \begin{commandshell} +pre-commit run --all-files +\end{commandshell} + is equivalent to running + \begin{commandshell} +latexindent.pl -l -m -s -w myfile.tex +\end{commandshell} + for each \texttt{.tex} file in your repository. + + A few notes about \cref{lst:.latexindent.yaml-switches}: + \begin{itemize} + \item the \texttt{-l} option was added to use the local \texttt{.latexindent.yaml} (where it + was specified to only create one back-up file, as \texttt{git} typically takes care of + this when you use \texttt{pre-commit}); + \item \texttt{-m} to modify line breaks; in addition to \texttt{-s} to suppress command-line + output, and \texttt{-w} to format files in place. + \end{itemize} + \end{example} + + \section{logFilePreferences}\label{app:logfile-demo} + \Vref{lst:logFilePreferences} describes the options for customising the information given + to the log file, and we provide a few demonstrations here. Let's say that we start with + the code given in \cref{lst:simple}, and the settings specified in + \cref{lst:logfile-prefs1-yaml}. + + \begin{minipage}{.35\linewidth} + \cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple} + \end{minipage} + \hfill + \begin{minipage}{.6\linewidth} + \cmhlistingsfromfile{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml} + \end{minipage} + + If we run the following command (noting that \texttt{-t} is active) + \begin{commandshell} +latexindent.pl -t -l=logfile-prefs1.yaml simple.tex +\end{commandshell} + then on inspection of \texttt{indent.log} we will find the snippet given in + \cref{lst:indentlog}. + \begin{cmhlistings}[style=tcblatex,morekeywords={TRACE}]{\texttt{indent.log}}{lst:indentlog} + +++++ +TRACE: environment found: myenv + No ancestors found for myenv + Storing settings for myenvenvironments + indentRulesGlobal specified (0) for environments, ... + Using defaultIndent for myenv + Putting linebreak after replacementText for myenv + looking for COMMANDS and key = {value} +TRACE: Searching for commands with optional and/or mandatory arguments AND key = {value} + looking for SPECIAL begin/end +TRACE: Searching myenv for special begin/end (see specialBeginEnd) +TRACE: Searching myenv for optional and mandatory arguments + ... no arguments found + ----- + \end{cmhlistings} + Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++} + and \lstinline!-----! respectively. + + \section{Encoding indentconfig.yaml}\label{app:encoding} + In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with + \texttt{indentconfig.yaml}, may wish to run the following command in either + \texttt{cmd.exe} or \texttt{powershell.exe}: + \begin{dosprompt} +chcp + \end{dosprompt} + They may receive the following result + \begin{dosprompt} +Active code page: 936 + \end{dosprompt} + and can then use the settings given in \cref{lst:indentconfig-encoding1} within their + \texttt{indentconfig.yaml}, where 936 is the result of the \texttt{chcp} command. + + \cmhlistingsfromfile{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1} + + \section{dos2unix linebreak adjustment} + + \yamltitle{dos2unixlinebreaks}*{integer} + If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux + \announce{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal + space is not removed as you hope. + + In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and + employing, for example, the following command. + + \begin{commandshell} +latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex +\end{commandshell} + + See \cite{bersbersbers} for further dertails. + + \section{Differences from Version 2.2 to 3.0}\label{app:differences} + There are a few (small) changes to the interface when comparing Version 2.2 to Version + 3.0. Explicitly, in previous versions you might have run, for example, \index{switches!-o + demonstration} + \begin{commandshell} +latexindent.pl -o myfile.tex outputfile.tex +\end{commandshell} + whereas in Version 3.0 you would run any of the following, for example, + \index{switches!-o demonstration} + \begin{commandshell} +latexindent.pl -o=outputfile.tex myfile.tex +latexindent.pl -o outputfile.tex myfile.tex +latexindent.pl myfile.tex -o outputfile.tex +latexindent.pl myfile.tex -o=outputfile.tex +latexindent.pl myfile.tex -outputfile=outputfile.tex +latexindent.pl myfile.tex -outputfile outputfile.tex +\end{commandshell} + noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch. + + The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0 onwards. + \cmhlistingsfromfile{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml} + + There is a slight difference when specifying indentation after headings; specifically, we + now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See + \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew} + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld} + \end{minipage}% + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew} + \end{minipage}% + + To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you + would write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would + write YAML as in \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m} + switch, \cref{lst:indentAfterThisHeadingNew2}. \index{specialBeginEnd!update to + displaymath V3.0} + + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} + \end{minipage}% + \hfill + \begin{minipage}{.45\textwidth} + \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} + + \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} + \end{minipage}% + + \mbox{}\hfill + \begin{minipage}{.25\textwidth} + \hrule + + \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}} + + \end{minipage} \end{document} diff --git a/support/latexindent/documentation/logo.tex b/support/latexindent/documentation/logo.tex deleted file mode 100644 index d80dfec721..0000000000 --- a/support/latexindent/documentation/logo.tex +++ /dev/null @@ -1,33 +0,0 @@ -% arara: pdflatex -% -% to create the black and white logo: -% convert -density 1000 -colorspace GRAY logo.pdf logo-bw.pdf -\documentclass[border=1mm]{standalone} - -\usepackage{tikz} -\usetikzlibrary{matrix} -\definecolor{harvestgold}{cmyk}{0.00, 0.05, 0.51, 0.07} %EDE275 -\definecolor{cmhgold}{cmyk}{0,0.178,0.909,0.008} %FDD017 -\definecolor{bakeoffblue}{cmyk}{0.24, 0.00, 0.02, 0.18} %9fd2cd -\definecolor{bakeoffgreen}{cmyk}{0.30, 0.00, 0.20, 0.29} %80b692 -\definecolor{burntorange}{cmyk}{0.00, 0.41, 1.00, 0.04} -\begin{document} -\begin{tikzpicture}[logo/.style={draw=blue,circle,fill=white}] - \matrix{ - \node[logo,dash pattern=on .5pt off 1.0pt,thick,draw=purple!75!white]{}; & \node[logo,draw=burntorange]{}; \\ - \node[logo,fill,draw=bakeoffgreen,fill=bakeoffblue]{}; & \node[logo,double,draw=cmhgold,fill=harvestgold]{};\\}; -\end{tikzpicture} -\end{document} - -% for reference, the following puts the GitHub logo in the background; also needs -% \usetikzlibrary{backgrounds} -\pagecolor{white} -\begin{tikzpicture}[logo/.style={draw=blue,circle,fill=none,fill opacity=0.75}] - \matrix{% - \node[logo,dash pattern=on .5pt off 1.0pt,thick,draw=purple!75!white]{}; & \node[logo,draw=burntorange]{}; \\ - \node[logo,fill,draw=bakeoffgreen,fill=bakeoffblue]{}; & \node[logo,double,draw=cmhgold,fill=harvestgold]{};\\}; - \begin{scope}[on background layer] - %\node [yshift=0.01em,xshift=0.07em] {\resizebox{1cm}{!}{\color{gray!50!white}\faGithub}}; - \node {\resizebox{1cm}{!}{\color{gray!25!white}\faGithub}}; - \end{scope} -\end{tikzpicture} diff --git a/support/latexindent/documentation/sec-appendices.tex b/support/latexindent/documentation/sec-appendices.tex deleted file mode 100644 index 84dd9d56f7..0000000000 --- a/support/latexindent/documentation/sec-appendices.tex +++ /dev/null @@ -1,720 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\appendix - \section{Required Perl modules}\label{sec:requiredmodules} - If you intend to use \texttt{latexindent.pl} and \emph{not} one of the supplied - standalone executable files (\texttt{latexindent.exe} is available for Windows users - without Perl, see \cref{subsubsec:latexindent:exe}), then you will need a few standard - Perl modules. - - If you can run the minimum code in \cref{lst:helloworld} as in - \begin{commandshell} -perl helloworld.pl - \end{commandshell} - then you will be able to run \texttt{latexindent.pl}, otherwise you may need to install - the missing modules; see \cref{sec:module-installer,sec:manual-module-instal}. - - \begin{cmhlistings}[style=tcblatex,language=Perl]{\texttt{helloworld.pl}}{lst:helloworld} -#!/usr/bin/perl - -use strict; # | -use warnings; # | -use Encode; # | -use Getopt::Long; # | -use Data::Dumper; # these modules are -use List::Util qw(max); # generally part -use PerlIO::encoding; # of a default perl distribution -use open ':std', ':encoding(UTF-8)';# | -use Text::Wrap; # | -use Text::Tabs; # | -use FindBin; # | -use File::Copy; # | -use File::Basename; # | -use File::HomeDir; # <--- typically requires install via cpanm -use YAML::Tiny; # <--- typically requires install via cpanm - -print "hello world"; -exit; -\end{cmhlistings} - - \subsection{Module installer script}\label{sec:module-installer} - \announce{2018-01-13}{perl module helper script} \texttt{latexindent.pl} ships with a - helper script that will install any missing \texttt{perl} modules on your system; if you - run - \begin{commandshell} -perl latexindent-module-installer.pl -\end{commandshell} - or - \begin{dosprompt} -perl latexindent-module-installer.pl - \end{dosprompt} - then, once you have answered \texttt{Y}, the appropriate modules will be installed onto - your distribution. - - \subsection{Manually installing modules}\label{sec:manual-module-instal} - Manually installing the modules given in \cref{lst:helloworld} will vary depending on - your operating system and \texttt{Perl} distribution. - - \subsubsection{Linux} - \paragraph{perlbrew} - Linux users may be interested in exploring Perlbrew \cite{perlbrew}; an example - installation would be: - \begin{commandshell} -sudo apt-get install perlbrew -perlbrew init -perlbrew install perl-5.28.1 -perlbrew switch perl-5.28.1 -sudo apt-get install curl -curl -L http://cpanmin.us | perl - App::cpanminus -cpanm YAML::Tiny -cpanm File::HomeDir -\end{commandshell} - \index{cpan} - - \paragraph{Ubuntu/Debian} - For other distributions, the Ubuntu/Debian approach may work as follows - \begin{commandshell} -sudo apt install perl -sudo cpan -i App::cpanminus -sudo cpanm YAML::Tiny -sudo cpanm File::HomeDir -\end{commandshell} - or else by running, for example, - \begin{commandshell} -sudo perl -MCPAN -e'install "File::HomeDir"' -\end{commandshell} - - \paragraph{Ubuntu: using the texlive from apt-get} - Ubuntu users that install texlive using \texttt{apt-get} as in the following - \begin{commandshell} -sudo apt install texlive -sudo apt install texlive-latex-recommended -\end{commandshell} - may need the following additional command to work with \texttt{latexindent.pl} - \begin{commandshell} -sudo apt install texlive-extra-utils -\end{commandshell} - \paragraph{Arch-based distributions} - First install the dependencies - \begin{commandshell} -sudo pacman -S perl cpanminus -\end{commandshell} - then run the latexindent-module-installer.pl file located at helper-scripts/ - - \paragraph{Alpine} - If you are using Alpine, some \texttt{Perl} modules are not build-compatible with Alpine, - but replacements are available through \texttt{apk}. For example, you might use the - commands given in \cref{lst:alpine-install}; thanks to \cite{jun-sheaf} for providing - these details. - - \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{alpine-install.sh}}{lst:alpine-install} -# Installing perl -apk --no-cache add miniperl perl-utils - -# Installing incompatible latexindent perl dependencies via apk -apk --no-cache add \ - perl-log-dispatch \ - perl-namespace-autoclean \ - perl-specio \ - perl-unicode-linebreak - -# Installing remaining latexindent perl dependencies via cpan -apk --no-cache add curl wget make -ls /usr/share/texmf-dist/scripts/latexindent -cd /usr/local/bin && \ - curl -L https://cpanmin.us/ -o cpanm && \ - chmod +x cpanm -cpanm -n App::cpanminus -cpanm -n File::HomeDir -cpanm -n Params::ValidationCompiler -cpanm -n YAML::Tiny -\end{cmhlistings} - - Users of NixOS might like to see - \href{https://github.com/cmhughes/latexindent.pl/issues/222}{https://github.com/cmhughes/latexindent.pl/issues/222} - for tips. - \subsubsection{Mac} - Users of the Macintosh operating system might like to explore the following commands, for - example: - \begin{commandshell} -brew install perl -brew install cpanm - -cpanm YAML::Tiny -cpanm File::HomeDir -\end{commandshell} - Alternatively, - \begin{commandshell} -brew install latexindent -\end{commandshell} - - \subsubsection{Windows} - Strawberry Perl users on Windows might use \texttt{CPAN client}. All of the modules are - readily available on CPAN \cite{cpan}. - - \texttt{indent.log} will contain details of the location - of the Perl modules on your system. \texttt{latexindent.exe} is a standalone executable - for Windows (and therefore does not require a Perl distribution) and caches copies of the - Perl modules onto your system; if you wish to see where they are cached, use the - \texttt{trace} option, e.g - \begin{dosprompt} -latexindent.exe -t myfile.tex - \end{dosprompt} - - \subsection{The GCString switch}\label{subsec:the-GCString} - If you find that the \texttt{lookForAlignDelims} (as in \cref{subsec:align-at-delimiters}) does not work correctly - for your language, then you may with to use the \texttt{Unicode::GCString} module \announce*{2022-03-25}{Unicode::GCString}. - \index{perl!Unicode GCString module} - \index{switches!--GCString demonstration} - - This can be loaded by calling \texttt{latexindent.pl} with the \texttt{GCString} switch - as in - \begin{commandshell} -latexindent.pl --GCString myfile.tex -\end{commandshell} - In this case, you will need to have the \texttt{Unicode::GCString} installed in your - \texttt{perl} distribution by using, for example, - \begin{commandshell} -cpanm YAML::Tiny -\end{commandshell} - - Note: this switch does \emph{nothing} for \texttt{latexindent.exe} which loads the module - by default. Users of \texttt{latexindent.exe} should not see any difference in behaviour - whether they use this switch or not, as \texttt{latexindent.exe} loads the - \texttt{Unicode::GCString} module. - - \section{Updating the path variable}\label{sec:updating-path} - \texttt{latexindent.pl} has a few scripts (available at \cite{latexindent-home}) that can - update the \texttt{path} variables. Thank you to \cite{jasjuang} for this feature. If - you're on a Linux or Mac machine, then you'll want \texttt{CMakeLists.txt} from - \cite{latexindent-home}. - \subsection{Add to path for Linux} - To add \texttt{latexindent.pl} to the path for Linux, follow these steps: - \begin{enumerate} - \item download \texttt{latexindent.pl} and its associated modules, - \texttt{defaultSettings.yaml}, to your chosen directory from \cite{latexindent-home} ; - \item within your directory, create a directory called \texttt{path-helper-files} and download - \texttt{CMakeLists.txt} and \lstinline!cmake_uninstall.cmake.in! from - \cite{latexindent-home}/path-helper-files to this directory; - \item run - \begin{commandshell} -ls /usr/local/bin -\end{commandshell} - to see what is \emph{currently} in there; - \item run the following commands - \begin{commandshell} -sudo apt-get update -sudo apt-get install --no-install-recommends cmake make # or any other generator -mkdir build && cd build -cmake ../path-helper-files -sudo make install -\end{commandshell} - \item run - \begin{commandshell} -ls /usr/local/bin -\end{commandshell} - again to check that \texttt{latexindent.pl}, its modules and - \texttt{defaultSettings.yaml} have been added. - \end{enumerate} - To \emph{remove} the files, run - \begin{commandshell} -sudo make uninstall -\end{commandshell} - \subsection{Add to path for Windows} - To add \texttt{latexindent.exe} to the path for Windows, follow these steps: - \begin{enumerate} - \item download \texttt{latexindent.exe}, \texttt{defaultSettings.yaml}, - \texttt{add-to-path.bat} from \cite{latexindent-home} to your chosen directory; - \item open a command prompt and run the following command to see what is \emph{currently} in - your \lstinline!%path%! variable; - \begin{dosprompt} -echo %path% - \end{dosprompt} - \item right click on \texttt{add-to-path.bat} and \emph{Run as administrator}; - \item log out, and log back in; - \item open a command prompt and run - \begin{dosprompt} -echo %path% - \end{dosprompt} - to check that the appropriate directory has been added to your \lstinline!%path%!. - \end{enumerate} - To \emph{remove} the directory from your \lstinline!%path%!, run - \texttt{remove-from-path.bat} as administrator. - - \section{Batches of files}\label{sec:batches} - - You can \announce*{2022-03-25}{batches of files details} instruct \texttt{latexindent.pl} - to operate on multiple files. For example, the following calls are all valid - \begin{commandshell} -latexindent.pl myfile1.tex -latexindent.pl myfile1.tex myfile2.tex -latexindent.pl myfile*.tex - \end{commandshell} - - We note the following features of the script in relation to the switches detailed in - \cref{sec:how:to:use}. - - \subsection{location of indent.log} - If the \texttt{-c} switch is \emph{not} active, then \texttt{indent.log} goes to the directory of the final file called. - - If the \texttt{-c} switch \emph{is} active, then \texttt{indent.log} goes to the - specified directory. - - \subsection{interaction with -w switch} - If the \texttt{-w} switch is active, as in - \begin{commandshell} -latexindent.pl -w myfile*.tex -\end{commandshell} - then files will be overwritten individually. Back-up files can be re-directed via the - \texttt{-c} switch. - - \subsection{interaction with -o switch} - If \texttt{latexindent.pl} is called using the \texttt{-o} switch as in - \begin{commandshell} -latexindent.pl myfile*.tex -o=my-output-file.tex - \end{commandshell} - and there are multiple files to operate upon, then the \texttt{-o} switch is ignored - because there is only \emph{one} output file specified. - - More generally, if the \texttt{-o} switch does \emph{not} have a \texttt{+} symbol at the - beginning, then the \texttt{-o} switch will be ignored, and is turned it off. - - For example - \begin{commandshell} -latexindent.pl myfile*.tex -o=+myfile -\end{commandshell} - \emph{will} work fine because \emph{each} \texttt{.tex} file will output to - \texttt{myfile.tex} - - Similarly, - \begin{commandshell} -latexindent.pl myfile*.tex -o=++ -\end{commandshell} - \emph{will} work because the `existence check/incrementation' routine will be applied. - - \subsection{interaction with lines switch} - This behaves as expected by attempting to operate on the line numbers specified for each file. See - the examples in \cref{sec:line-switch}. - - \subsection{interaction with check switches} - The exit codes for \texttt{latexindent.pl} are given in \vref{tab:exit-codes}. - - When operating on multiple files with the check switch active, as in - \begin{commandshell} -latexindent.pl myfile*.tex --check - \end{commandshell} - then - \begin{itemize} - \item exit code 0 means that the text from \emph{none} of the files has been changed; - \item exit code 1 means that the text from \emph{at least one} of the files been file changed. - \end{itemize} - - The interaction with \texttt{checkv} switch is as in the check switch, but with verbose - output. - - \subsection{when a file does not exist} - What happens if one of the files can not be operated upon? - \begin{itemize} - \item if at least one of the files does not exist and \texttt{latexindent.pl} has been called - to act upon multiple files, then the exit code is 3; note that \texttt{latexindent.pl} - will try to operate on each file that it is called upon, and will not exit with a fatal - message in this case; - \item if at least one of the files can not be read and \texttt{latexindent.pl} has been called - to act upon multiple files, then the exit code is 4; note that \texttt{latexindent.pl} - will try to operate on each file that it is called upon, and will not exit with a fatal - message in this case; - \item if \texttt{latexindent.pl} has been told to operate on multiple files, and some do not - exist and some cannot be read, then the exit code will be either 3 or 4, depending upon - which it scenario it encountered most recently. - \end{itemize} - - \section{latexindent-yaml-schema.json} - - \texttt{latexindent.pl} - \announce{2022-01-02}{latexindent-yaml-schema.json} ships with - \texttt{latexindent-yaml-schema.json} - which might help you when constructing your YAML files. - \index{json!schema for YAML files} - - \subsection{VSCode demonstration} - To use \texttt{latexindent-yaml-schema.json} with \texttt{VSCode}, you can use the - following steps: \index{VSCode} \index{json!VSCode} - \begin{enumerate} - \item download \texttt{latexindent-yaml-schema.json} from the \texttt{documentation} folder of - \cite{latexindent-home}, save it in whichever directory you would like, noting it for - reference; - \item following the instructions from \cite{vscode-yaml-demo}, for example, you should install - the VSCode YAML extension \cite{vscode-yaml-extentions}; - \item set up your \texttt{settings.json} file using the directory you saved the file by - adapting \cref{lst:settings.json}; on my Ubuntu laptop this file lives at - \texttt{/home/cmhughes/.config/Code/User/settings.json}. - \end{enumerate} - - \begin{widepage} - \cmhlistingsfromfile{demonstrations/settings.json}[yaml-TCB]{\texttt{settings.json}}{lst:settings.json} - \end{widepage} - - Alternatively, if you would prefer not to download the json file, you might be able to - use an adapted version of \cref{lst:settings-alt.json}. - - \begin{widepage} - \cmhlistingsfromfile{demonstrations/settings-alt.json}[yaml-TCB]{\texttt{settings-alt.json}}{lst:settings-alt.json} - \end{widepage} - - Finally, if your TeX distribution is up to date, then - \texttt{latexindent-yaml-schema.json} \emph{should} be in the documentation folder of - your installation, so an adapted version of \cref{lst:settings-alt1.json} may work. - - \begin{widepage} - \cmhlistingsfromfile{demonstrations/settings-alt1.json}[yaml-TCB]{\texttt{settings-alt1.json}}{lst:settings-alt1.json} - \end{widepage} - - If you have details of how to implement this schema in other editors, please feel - encouraged to contribute to this documentation. - - \section{Using conda}\label{sec:app:conda} - If you use conda you'll only need - \begin{commandshell} -conda install latexindent.pl -c conda-forge -\end{commandshell} - This will install the executable and all its dependencies (including perl) in the - activate environment. You don't even have to worry about \texttt{defaultSettings.yaml} as - it included too, you can thus skip \cref{sec:requiredmodules,sec:updating-path}. - \index{conda} - - You can get a conda installation for example from \cite{conda} or from \cite{anacoda}. - - \subsection{Sample conda installation on Ubuntu} - On Ubuntu I followed the 64-bit installation instructions at \cite{condainstallubuntu} - and then I ran the following commands: - \begin{commandshell} -conda create -n latexindent.pl -conda activate latexindent.pl -conda install latexindent.pl -c conda-forge -conda info --envs -conda list -conda run latexindent.pl -vv -\end{commandshell} - I found the details given at \cite{condainstallhelp} to be helpful. - - \section{Using docker}\label{sec:app:docker} - If you use docker you'll only need \announce*{2022-06-12}{docker support} - \begin{commandshell} -docker pull ghcr.io/cmhughes/latexindent.pl -\end{commandshell} - This will download the image packed \texttt{latexindent}'s executable and its all - dependencies. \index{docker} Thank you to \cite{eggplants} for contributing this feature; - see also \cite{cmhughesio}. For reference, \emph{ghcr} stands for \emph{GitHub Container - Repository}. - - \subsection{Sample docker installation on Ubuntu} - To pull the image and show \texttt{latexindent}'s help on Ubuntu: - - \begin{cmhlistings}*[style=tcblatex,language=Bash]{\texttt{docker-install.sh}}{lst:docker-install} -# setup docker if not already installed -if ! command -v docker &> /dev/null; then - sudo apt install docker.io -y - sudo groupadd docker - sudo gpasswd -a "$USER" docker - sudo systemctl restart docker -fi - -# download image and execute -docker pull ghcr.io/cmhughes/latexindent.pl -docker run ghcr.io/cmhughes/latexindent.pl -h -\end{cmhlistings} - - \subsection{How to format on Docker} - When you use \texttt{latexindent} with the docker image, you have to mount target \texttt{tex} file like this: - \begin{commandshell} -docker run -v /path/to/local/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s -w myfile.tex -\end{commandshell} - - \section{pre-commit} - - Users of \texttt{.git} may be interested \announce{2022-01-21}{pre-commit for - latexindent.pl} in exploring the \texttt{pre-commit} tool \cite{pre-commithome}, which is - supported by \texttt{latexindent.pl}. Thank you to \cite{tdegeusprecommit} for - contributing this feature, and to \cite{holzhausprecommit} for their contribution to it. - - To use the \texttt{pre-commit} tool, you will need to install \texttt{pre-commit}; sample - instructions for Ubuntu are given in \cref{sec:pre-commit-ubuntu}. Once installed, there - are two ways to use \texttt{pre-commit}: using \texttt{CPAN} or using \texttt{conda}, - detailed in \cref{sec:pre-commit-cpan} and \cref{sec:pre-commit-conda} respectively. - - \subsection{Sample pre-commit installation on Ubuntu}\label{sec:pre-commit-ubuntu} - On Ubuntu I ran the following command: - \begin{commandshell} -python3 -m pip install pre-commit -\end{commandshell} - I then updated my path via .bashrc so that it includes the line in - \cref{lst:bashrc-update}. - \begin{cmhlistings}[style=tcblatex,language=Bash]{\texttt{.bashrc} update}{lst:bashrc-update} -... -export PATH=$PATH:/home/cmhughes/.local/bin -\end{cmhlistings} - - \subsection{pre-commit defaults} - The default values that are employed by \texttt{pre-commit} are shown in \cref{lst:.pre-commit-yaml-default}. - \index{pre-commit!default} - - \cmhlistingsfromfile*{../.pre-commit-hooks.yaml}[yaml-TCB]{\texttt{.pre-commit-hooks.yaml} (default)}{lst:.pre-commit-yaml-default} - - In particular, the decision has deliberately been made (in collaboration with - \cite{holzhausprecommit}) to have the default to employ the following switches: - \texttt{overwriteIfDifferent}, \texttt{silent}, \texttt{local}; this is detailed in the - lines that specify \texttt{args} in \cref{lst:.pre-commit-yaml-default}. - - \index{pre-commit!warning} - \index{warning!pre-commit} - \begin{warning} - Users of \texttt{pre-commit} will, by default, have the \texttt{overwriteIfDifferent} - switch employed. It is assumed that such users have version control in place, and are - intending to overwrite their files. - \end{warning} - - \subsection{pre-commit using CPAN}\label{sec:pre-commit-cpan} - - To use \texttt{latexindent.pl} with \texttt{pre-commit}, create the file - \texttt{.pre-commit-config.yaml} given in \cref{lst:.pre-commit-config.yaml-cpan} in your - git-repository. \index{cpan} \index{git} \index{pre-commit!cpan} - - \cmhlistingsfromfile{demonstrations/pre-commit-config-cpan.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (cpan)}{lst:.pre-commit-config.yaml-cpan} - Once created, you should then be able to run the following command: - \begin{commandshell} -pre-commit run --all-files -\end{commandshell} - A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: - \begin{itemize} - \item the settings given in \cref{lst:.pre-commit-config.yaml-cpan} instruct - \texttt{pre-commit} to use \texttt{CPAN} to get dependencies; - \item this requires \texttt{pre-commit} and \texttt{perl} to be installed on your system; - \item the \texttt{args} lists selected command-line options; the settings in - \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling - \begin{commandshell} -latexindent.pl -s myfile.tex -\end{commandshell} - for each \texttt{.tex} file in your repository; - \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you - can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. - \end{itemize} - - Naturally you can add options, or omit \texttt{-s} and \texttt{-w}, according to your - preference. - - \subsection{pre-commit using conda}\label{sec:pre-commit-conda} - - You can also rely on \texttt{conda} (detailed in \cref{sec:app:conda}) instead of - \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. - \index{conda} \index{git} \index{pre-commit!conda} - - \cmhlistingsfromfile{demonstrations/pre-commit-config-conda.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (conda)}{lst:.pre-commit-config.yaml-conda} - Once created, you should then be able to run the following command: - \begin{commandshell} -pre-commit run --all-files -\end{commandshell} - A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: - \begin{itemize} - \item the settings given in \cref{lst:.pre-commit-config.yaml-conda} instruct - \texttt{pre-commit} to use \texttt{conda} to get dependencies; - \item this requires \texttt{pre-commit} and \texttt{conda} to be installed on your system; - \item the \texttt{args} lists selected command-line options; the settings in - \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling - \begin{commandshell} -conda run latexindent.pl -s myfile.tex -\end{commandshell} - for each \texttt{.tex} file in your repository; - \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you - can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. - \end{itemize} - - \subsection{pre-commit using docker}\label{sec:pre-commit-docker} - - You can also rely on \texttt{docker} (detailed in \cref{sec:app:docker}) instead of - \texttt{CPAN} for all dependencies, including \texttt{latexindent.pl} itself. - \index{docker} \index{git} \index{pre-commit!docker} - - \cmhlistingsfromfile*{demonstrations/pre-commit-config-docker.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (docker)}{lst:.pre-commit-config.yaml-docker} - Once created, you should then be able to run the following command: - \begin{commandshell} -pre-commit run --all-files -\end{commandshell} - A few notes about \cref{lst:.pre-commit-config.yaml-cpan}: - \begin{itemize} - \item the settings given in \cref{lst:.pre-commit-config.yaml-docker} instruct - \texttt{pre-commit} to use \texttt{docker} to get dependencies; - \item this requires \texttt{pre-commit} and \texttt{docker} to be installed on your system; - \item the \texttt{args} lists selected command-line options; the settings in - \cref{lst:.pre-commit-config.yaml-cpan} are equivalent to calling - \begin{commandshell} -docker run -v /path/to/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s myfile.tex -\end{commandshell} - for each \texttt{.tex} file in your repository; - \item to instruct \texttt{latexindent.pl} to overwrite the files in your repository, then you - can update \cref{lst:.pre-commit-config.yaml-cpan} so that \texttt{args: [-s, -w]}. - \end{itemize} - - \subsection{pre-commit example using -l, -m switches} - Let's consider a small example, with local \texttt{latexindent.pl} settings in - \texttt{.latexindent.yaml}. - - \begin{example} - We use the local settings given in \cref{lst:.latexindent.yaml}. - \begin{cmhlistings}[style=tcblatex]{\texttt{.latexindent.yaml}}{lst:.latexindent.yaml} -onlyOneBackUp: 1 - -modifyLineBreaks: - oneSentencePerLine: - manipulateSentences: 1 -\end{cmhlistings} - - and \texttt{.pre-commit-config.yaml} as in \cref{lst:.latexindent.yaml-switches}: - - \cmhlistingsfromfile{demonstrations/pre-commit-config-demo.yaml}[yaml-TCB]{\texttt{.pre-commit-config.yaml} (demo)}{lst:.latexindent.yaml-switches} - Now running - \begin{commandshell} -pre-commit run --all-files -\end{commandshell} - is equivalent to running - \begin{commandshell} -latexindent.pl -l -m -s -w myfile.tex -\end{commandshell} - for each \texttt{.tex} file in your repository. - - A few notes about \cref{lst:.latexindent.yaml-switches}: - \begin{itemize} - \item the \texttt{-l} option was added to use the local \texttt{.latexindent.yaml} (where it - was specified to only create one back-up file, as \texttt{git} typically takes care of - this when you use \texttt{pre-commit}); - \item \texttt{-m} to modify line breaks; in addition to \texttt{-s} to suppress command-line - output, and \texttt{-w} to format files in place. - \end{itemize} - \end{example} - - \section{logFilePreferences}\label{app:logfile-demo} - \Vref{lst:logFilePreferences} describes the options for customising the information given - to the log file, and we provide a few demonstrations here. Let's say that we start with - the code given in \cref{lst:simple}, and the settings specified in - \cref{lst:logfile-prefs1-yaml}. - - \begin{minipage}{.35\linewidth} - \cmhlistingsfromfile{demonstrations/simple.tex}{\texttt{simple.tex}}{lst:simple} - \end{minipage} - \hfill - \begin{minipage}{.6\linewidth} - \cmhlistingsfromfile{demonstrations/logfile-prefs1.yaml}[yaml-TCB]{\texttt{logfile-prefs1.yaml}}{lst:logfile-prefs1-yaml} - \end{minipage} - - If we run the following command (noting that \texttt{-t} is active) - \begin{commandshell} -latexindent.pl -t -l=logfile-prefs1.yaml simple.tex -\end{commandshell} - then on inspection of \texttt{indent.log} we will find the snippet given in - \cref{lst:indentlog}. - \begin{cmhlistings}[style=tcblatex,morekeywords={TRACE}]{\texttt{indent.log}}{lst:indentlog} - +++++ -TRACE: environment found: myenv - No ancestors found for myenv - Storing settings for myenvenvironments - indentRulesGlobal specified (0) for environments, ... - Using defaultIndent for myenv - Putting linebreak after replacementText for myenv - looking for COMMANDS and key = {value} -TRACE: Searching for commands with optional and/or mandatory arguments AND key = {value} - looking for SPECIAL begin/end -TRACE: Searching myenv for special begin/end (see specialBeginEnd) -TRACE: Searching myenv for optional and mandatory arguments - ... no arguments found - ----- - \end{cmhlistings} - Notice that the information given about \texttt{myenv} is `framed' using \texttt{+++++} - and \lstinline!-----! respectively. - - \section{Encoding indentconfig.yaml}\label{app:encoding} - In relation to \vref{sec:indentconfig}, Windows users that encounter encoding issues with - \texttt{indentconfig.yaml}, may wish to run the following command in either - \texttt{cmd.exe} or \texttt{powershell.exe}: - \begin{dosprompt} -chcp - \end{dosprompt} - They may receive the following result - \begin{dosprompt} -Active code page: 936 - \end{dosprompt} - and can then use the settings given in \cref{lst:indentconfig-encoding1} within their - \texttt{indentconfig.yaml}, where 936 is the result of the \texttt{chcp} command. - - \cmhlistingsfromfile{demonstrations/encoding1.yaml}[yaml-TCB]{\texttt{encoding} demonstration for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding1} - - \section{dos2unix linebreak adjustment} - - \yamltitle{dos2unixlinebreaks}*{integer} - If you use \texttt{latexindent.pl} on a dos-based Windows file on Linux - \announce{2021-06-19}{dos2unix linebreaks} then you may find that trailing horizontal - space is not removed as you hope. - - In such a case, you may wish to try setting \texttt{dos2unixlinebreaks} to 1 and - employing, for example, the following command. - - \begin{commandshell} -latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex -\end{commandshell} - - See \cite{bersbersbers} for further dertails. - - \section{Differences from Version 2.2 to 3.0}\label{app:differences} - There are a few (small) changes to the interface when comparing Version 2.2 to Version - 3.0. Explicitly, in previous versions you might have run, for example, \index{switches!-o - demonstration} - \begin{commandshell} -latexindent.pl -o myfile.tex outputfile.tex -\end{commandshell} - whereas in Version 3.0 you would run any of the following, for example, - \index{switches!-o demonstration} - \begin{commandshell} -latexindent.pl -o=outputfile.tex myfile.tex -latexindent.pl -o outputfile.tex myfile.tex -latexindent.pl myfile.tex -o outputfile.tex -latexindent.pl myfile.tex -o=outputfile.tex -latexindent.pl myfile.tex -outputfile=outputfile.tex -latexindent.pl myfile.tex -outputfile outputfile.tex -\end{commandshell} - noting that the \emph{output} file is given \emph{next to} the \texttt{-o} switch. - - The fields given in \cref{lst:obsoleteYaml} are \emph{obsolete} from Version 3.0 onwards. - \cmhlistingsfromfile{demonstrations/obsolete.yaml}[yaml-obsolete]{Obsolete YAML fields from Version 3.0}{lst:obsoleteYaml} - - There is a slight difference when specifying indentation after headings; specifically, we - now write \texttt{indentAfterThisHeading} instead of \texttt{indent}. See - \cref{lst:indentAfterThisHeadingOld,lst:indentAfterThisHeadingNew} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingOld.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 2.2}{lst:indentAfterThisHeadingOld} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/indentAfterThisHeadingNew.yaml}[yaml-TCB]{\texttt{indentAfterThisHeading} in Version 3.0}{lst:indentAfterThisHeadingNew} - \end{minipage}% - - To specify \texttt{noAdditionalIndent} for display-math environments in Version 2.2, you - would write YAML as in \cref{lst:noAdditionalIndentOld}; as of Version 3.0, you would - write YAML as in \cref{lst:indentAfterThisHeadingNew1} or, if you're using \texttt{-m} - switch, \cref{lst:indentAfterThisHeadingNew2}. \index{specialBeginEnd!update to - displaymath V3.0} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/noAddtionalIndentOld.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} in Version 2.2}{lst:noAdditionalIndentOld} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew1} - - \cmhlistingsfromfile{demonstrations/noAddtionalIndentNew1.yaml}[yaml-TCB]{\texttt{noAdditionalIndent} for \texttt{displayMath} in Version 3.0}{lst:indentAfterThisHeadingNew2} - \end{minipage}% - - \mbox{}\hfill - \begin{minipage}{.25\textwidth} - \hrule - - \hfill\itshape End\\\mbox{}\hfill\mbox{}\rlap{\hfill\includegraphics{logo}} - - \end{minipage} diff --git a/support/latexindent/documentation/sec-conclusions-know-limitations.tex b/support/latexindent/documentation/sec-conclusions-know-limitations.tex deleted file mode 100644 index 7a45e46382..0000000000 --- a/support/latexindent/documentation/sec-conclusions-know-limitations.tex +++ /dev/null @@ -1,28 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\section{Conclusions and known limitations}\label{sec:knownlimitations} - There are a number of known limitations of the script, and almost certainly quite a few - that are \emph{unknown}! The known issues include: - \begin{description} - \item[multicolumn alignment] when working with code blocks in which multicolumn commands - overlap, the algorithm can fail; see \vref{lst:tabular2-mod2}. - \item[text wrap] routine operates \emph{before} indentation occurs; this means that it is - likely that your final, indented, text wrapped text may exceed the value of - \texttt{columns} that you specify; see \vref{subsec:textwrapping}. - \item[efficiency] particularly when the \texttt{-m} switch is active, as this adds many checks - and processes. The current implementation relies upon finding and storing \emph{every} - code block (see the discussion on \cpageref{page:phases}); I hope that, in a future - version, only \emph{nested} code blocks will need to be stored in the `packing' phase, - and that this will improve the efficiency of the script. - \end{description} - - You can run \texttt{latexindent} on any file; \announce{2019-07-13}*{ability to call - latexindent on any file} if you don't specify an extension, then the extensions that you - specify in \lstinline[breaklines=true]!fileExtensionPreference! (see - \vref{lst:fileExtensionPreference}) will be consulted. If you find a case in which the - script struggles, please feel free to report it at \cite{latexindent-home}, and in the - meantime, consider using a \texttt{noIndentBlock} (see \cpageref{lst:noIndentBlock}).% - - I hope that this script is useful to some; if you find an example where the script does - not behave as you think it should, the best way to contact me is to report an issue on - \cite{latexindent-home}; otherwise, feel free to find me on the - \url{http://tex.stackexchange.com/users/6621/cmhughes}. diff --git a/support/latexindent/documentation/sec-default-user-local.tex b/support/latexindent/documentation/sec-default-user-local.tex deleted file mode 100644 index af47092333..0000000000 --- a/support/latexindent/documentation/sec-default-user-local.tex +++ /dev/null @@ -1,1304 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\section{defaultSettings.yaml}\label{sec:defuseloc} - \texttt{latexindent.pl} loads its settings from \texttt{defaultSettings.yaml}. The idea - is to separate the behaviour of the script from the internal working -- this is very - similar to the way that we separate content from form when writing our documents in - \LaTeX. - - If you look in \texttt{defaultSettings.yaml} you'll find the switches that govern the - behaviour of \texttt{latexindent.pl}. If you're not sure where - \texttt{defaultSettings.yaml} resides on your computer, don't worry as - \texttt{indent.log} will tell you where to find it. \texttt{defaultSettings.yaml} is - commented, but here is a description of what each switch is designed to do. The default - value is given in each case; whenever you see \emph{integer} in \emph{this} section, - assume that it must be greater than or equal to \texttt{0} unless otherwise stated. - - For most of the settings in \texttt{defaultSettings.yaml} that are specified as integers, - then we understand \texttt{0} to represent `off' and \texttt{1} to represent `on'. For - fields that allow values other than \texttt{0} or \texttt{1}, it is hoped that the - specific context and associated commentary should make it clear which values are allowed. - -\yamltitle{fileExtensionPreference}*{fields} - \texttt{latexindent.pl} can be called to - act on a file without specifying the file extension. For example we can call - \begin{commandshell} -latexindent.pl myfile -\end{commandshell} - in which case the script will look for \texttt{myfile} with the extensions specified in - \texttt{fileExtensionPreference} in their numeric order. If no match is found, the script - will exit. As with all of the fields, you should change and/or add to this as necessary. - - \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} - - Calling \texttt{latexindent.pl myfile} with the (default) settings specified in - \cref{lst:fileExtensionPreference} means that the script will first look for - \texttt{myfile.tex}, then \texttt{myfile.sty}, \texttt{myfile.cls}, and finally - \texttt{myfile.bib} in order\footnote{Throughout this manual, listings shown with line - numbers represent code taken directly from \texttt{defaultSettings.yaml}.}. - - \index{backup files!extension settings} - -\subsection{Backup and log file preferences} -\yamltitle{backupExtension}*{extension name} - - If you call \texttt{latexindent.pl} with the \texttt{-w} switch (to overwrite - \texttt{myfile.tex}) then it will create a backup file before doing any indentation; the - default extension is \texttt{.bak}, so, for example, \texttt{myfile.bak0} would be - created when calling \texttt{latexindent.pl myfile.tex} for the first time. - - By default, every time you subsequently call \texttt{latexindent.pl} with the \texttt{-w} - to act upon \texttt{myfile.tex}, it will create successive back up files: - \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc. - -\yamltitle{onlyOneBackUp}*{integer} - \label{page:onlyonebackup} - \index{backup files!number of backup files} - If you don't want a backup for every time that you call \texttt{latexindent.pl} (so you - don't want \texttt{myfile.bak1}, \texttt{myfile.bak2}, etc) and you simply want - \texttt{myfile.bak} (or whatever you chose \texttt{backupExtension} to be) then change - \texttt{onlyOneBackUp} to \texttt{1}; the default value of \texttt{onlyOneBackUp} is - \texttt{0}. - \index{backup files!maximum number of backup files} - \index{backup files!number of backup files} - -\yamltitle{maxNumberOfBackUps}*{integer} - Some users may only want a finite number of backup files, say at most $3$, in which case, - they can change this switch. The smallest value of \texttt{maxNumberOfBackUps} is $0$ - which will \emph{not} prevent backup files being made; in this case, the behaviour will - be dictated entirely by \texttt{onlyOneBackUp}. The default value of - \texttt{maxNumberOfBackUps} is \texttt{0}. - -\yamltitle{cycleThroughBackUps}*{integer} - \index{backup files!cycle through} - Some users may wish to cycle through backup files, by deleting the oldest backup file and - keeping only the most recent; for example, with \texttt{maxNumberOfBackUps: 4}, and - \texttt{cycleThroughBackUps} set to \texttt{1} then the \texttt{copy} procedure given - below would be obeyed. - - \begin{commandshell} -copy myfile.bak1 to myfile.bak0 -copy myfile.bak2 to myfile.bak1 -copy myfile.bak3 to myfile.bak2 -copy myfile.bak4 to myfile.bak3 -\end{commandshell} - The default value of \texttt{cycleThroughBackUps} is \texttt{0}. - -\yamltitle{logFilePreferences}*{fields} - \texttt{latexindent.pl} writes information to \texttt{indent.log}, some - of which can be customized by changing \texttt{logFilePreferences}; see - \cref{lst:logFilePreferences}. If you load your own user settings (see - \vref{sec:indentconfig}) then \texttt{latexindent.pl} will detail them in - \texttt{indent.log}; you can choose not to have the details logged by switching - \texttt{showEveryYamlRead} to \texttt{0}. Once all of your settings have been loaded, you - can see the amalgamated settings in the log file by switching - \texttt{showAmalgamatedSettings} to \texttt{1}, if you wish. - - \cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} - - When \announce{2018-01-13}{showDecorationStartCodeBlockTrace feature for log file} either - of the \texttt{trace} modes (see \cpageref{page:traceswitch}) are active, you will - receive detailed information in \texttt{indent.log}. You can specify character strings to - appear before and after the notification of a found code block using, respectively, - \texttt{showDecorationStartCodeBlockTrace} and - \texttt{showDecorationFinishCodeBlockTrace}. A demonstration is given in - \vref{app:logfile-demo}.% - - The log file will end with the characters given in \texttt{endLogFileWith}, and will - report the \texttt{GitHub} address of \texttt{latexindent.pl} to the log file if - \texttt{showGitHubInfoFooter} is set to \texttt{1}. - - Note: \texttt{latexindent.pl} no longer uses the \texttt{log4perl} module to handle the - creation of the logfile. \announce{2021-03-14}*{no longer using log4perl}% - - Some of the options \announce{2021-06-19}*{logFilePreferences updated to include Dumper - options} for Perl's \texttt{Dumper} module can be specified in - \cref{lst:logFilePreferences}; see \cite{dumper} and \cite{dumperdemo} for more - information. These options will mostly be helpful for those calling - \texttt{latexindent.pl} with the \texttt{-tt} option described in \cref{sec:commandline}.% - -\subsection{Verbatim code blocks} -\yamltitle{verbatimEnvironments}*{fields} - - A field that contains a list of environments that you would like left completely alone -- - no indentation will be performed on environments that you have specified in this field, - see \cref{lst:verbatimEnvironments}. \index{verbatim!environments} - \index{verbatim!commands} - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} - \cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} - \end{cmhtcbraster} - - Note that if you put an environment in \texttt{verbatimEnvironments} and in other fields - such as \texttt{lookForAlignDelims} or \texttt{noAdditionalIndent} then - \texttt{latexindent.pl} will \emph{always} prioritize \texttt{verbatimEnvironments}. - - You can, optionally, specify \announce{2021-10-30}{verbatim name feature} the - \texttt{verbatim} field using the \texttt{name} field which takes a regular expression as - its argument; thank you to \cite{XuehaiPan} for contributing this feature. - - For demonstration, then assuming that your file contains the environments - \texttt{latexcode}, \texttt{latexcode*}, \texttt{pythoncode} and \texttt{pythoncode*}, - then the listings given in \cref{lst:nameAsRegex1,lst:nameAsRegex2} are equivalent. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex1.yaml}[yaml-TCB]{\texttt{nameAsRegex1.yaml}}{lst:nameAsRegex1} - \cmhlistingsfromfile{demonstrations/nameAsRegex2.yaml}[yaml-TCB]{\texttt{nameAsRegex2.yaml}}{lst:nameAsRegex2} - \end{cmhtcbraster} - - With reference to \cref{lst:nameAsRegex2}: - \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word code, - optionally followed by *}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - \end{itemize} - -\yamltitle{verbatimCommands}*{fields} - A field that contains a list of commands that are verbatim commands, for example - \lstinline|\lstinline|; any commands populated in this field are protected from line - breaking routines (only relevant if the \texttt{-m} is active, see - \vref{sec:modifylinebreaks}). - - With reference to \cref{lst:verbatimCommands}, by default \texttt{latexindent.pl} looks - for \lstinline|\verb| immediately followed by another character, and then it takes the - body as anything up to the next occurrence of the character; this means that, for - example, \lstinline|\verb!x+3!| is treated as a \texttt{verbatimCommands}. - - You can, optionally, specify \announce{2021-10-30}{verbatimCommands name feature} the - \texttt{verbatimCommands} field using the \texttt{name} field which takes a regular - expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. - - For demonstration, then assuming that your file contains the commands - \texttt{verbinline}, \texttt{myinline} then the listings given in - \cref{lst:nameAsRegex3,lst:nameAsRegex4} are equivalent. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex3.yaml}[yaml-TCB]{\texttt{nameAsRegex3.yaml}}{lst:nameAsRegex3} - \cmhlistingsfromfile{demonstrations/nameAsRegex4.yaml}[yaml-TCB]{\texttt{nameAsRegex4.yaml}}{lst:nameAsRegex4} - \end{cmhtcbraster} - - With reference to \cref{lst:nameAsRegex4}: - \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word - inline}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - \end{itemize} - -\yamltitle{noIndentBlock}*{fields} - If you have a block of code that you don't want \texttt{latexindent.pl} to touch (even if - \index{verbatim!noIndentBlock} it is \emph{not} a verbatim-like environment) then you can - wrap it in an environment from \texttt{noIndentBlock}; you can use any name you like for - this, provided you populate it as demonstrate in \cref{lst:noIndentBlock}. - - \cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} - - Of course, you don't want to have to specify these as null environments in your code, so - you use them with a comment symbol, \lstinline!%!, followed by as many spaces (possibly - none) as you like; see \cref{lst:noIndentBlockdemo} for example. - - \cmhlistingsfromfile{demonstrations/noindentblock.tex}{\texttt{noIndentBlock.tex}}{lst:noIndentBlockdemo} - - Important note: it is assumed that the \texttt{noindent} block statements specified in - this way appear on their own line. - - The \announce{2021-06-19}{noIndentBlock specified as regex} \texttt{noIndentBlock} fields - can also be specified in terms of \texttt{begin} and \texttt{end} fields. We use the code - in \cref{lst:noIndentBlock1} to demonstrate this feature.% - - \cmhlistingsfromfile{demonstrations/noindentblock1.tex}{\texttt{noIndentBlock1.tex}}{lst:noIndentBlock1} - - The settings given in \cref{lst:noindent1,lst:noindent2} are equivalent: - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/noindent1.yaml}[yaml-TCB]{\texttt{noindent1.yaml}}{lst:noindent1} - \cmhlistingsfromfile{demonstrations/noindent2.yaml}[yaml-TCB]{\texttt{noindent2.yaml}}{lst:noindent2} - \cmhlistingsfromfile{demonstrations/noindent3.yaml}[yaml-TCB]{\texttt{noindent3.yaml}}{lst:noindent3} - \end{cmhtcbraster} - - Upon running the commands - \begin{commandshell} -latexindent.pl -l noindent1.yaml noindent1 -latexindent.pl -l noindent2.yaml noindent1 -\end{commandshell} - then we receive the output given in \cref{lst:noIndentBlock1-mod1}. - - \cmhlistingsfromfile{demonstrations/noindentblock1-mod1.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent1} or \cref{lst:noindent2}}{lst:noIndentBlock1-mod1} - - The \texttt{begin}, \texttt{body} and \texttt{end} fields for \texttt{noIndentBlock} are - all \emph{regular expressions}. If the \texttt{body} field is not specified, then it - takes a default value of \lstinline!.*?! which is written explicitly in - \cref{lst:noindent1}. In this context, we interpret \lstinline!.*?! in words as \emph{the - fewest number of characters (possibly none) until the `end' field is reached}. - - The \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - - Using \cref{lst:noindent3} demonstrates setting \texttt{lookForThis} to 0 (off); running - the command - \begin{commandshell} -latexindent.pl -l noindent3.yaml noindent1 -\end{commandshell} - gives the output in \cref{lst:noIndentBlock1-mod3}. - - \cmhlistingsfromfile{demonstrations/noindentblock1-mod3.tex}{\texttt{noIndentBlock1.tex} using \cref{lst:noindent3}}{lst:noIndentBlock1-mod3} - - We will demonstrate this feature later in the documentation in \cref{lst:href3}. - - You can, optionally, specify \announce{2021-10-30}{noIndentBlock name feature} the - \texttt{noIndentBlock} field using the \texttt{name} field which takes a regular - expression as its argument; thank you to \cite{XuehaiPan} for contributing this feature. - - For demonstration, then assuming that your file contains the environments - \texttt{testnoindent}, \texttt{testnoindent*} then the listings given in - \cref{lst:nameAsRegex5,lst:nameAsRegex6} are equivalent. - - \begin{widepage} - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/nameAsRegex5.yaml}[yaml-TCB]{\texttt{nameAsRegex5.yaml}}{lst:nameAsRegex5} - \cmhlistingsfromfile{demonstrations/nameAsRegex6.yaml}[yaml-TCB]{\texttt{nameAsRegex6.yaml}}{lst:nameAsRegex6} - \end{cmhtcbraster} - \end{widepage} - - With reference to \cref{lst:nameAsRegex6}: - \begin{itemize} - \item the \texttt{name} field as specified here means \emph{any word followed by the word - noindent, optionally followed by *}; - \item we have used \texttt{nameAsRegex} to identify this field, but you can use any description - you like; - \item the \texttt{lookForThis} field is optional, and can take the values 0 (off) or 1 (on); by - default, it is assumed to be 1 (on). - \end{itemize} -\subsection{filecontents and preamble} -\yamltitle{fileContentsEnvironments}*{field} - - Before \texttt{latexindent.pl} determines the difference between preamble (if any) and - the main document, it first searches for any of the environments specified in - \texttt{fileContentsEnvironments}, see \cref{lst:fileContentsEnvironments}. The behaviour - of \texttt{latexindent.pl} on these environments is determined by their location - (preamble or not), and the value \texttt{indentPreamble}, discussed next. - - \cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} - -\yamltitle{indentPreamble}{0|1} - - The preamble of a document can sometimes contain some trickier code for - \texttt{latexindent.pl} to operate upon. By default, \texttt{latexindent.pl} won't try to - operate on the preamble (as \texttt{indentPreamble} is set to \texttt{0}, by default), - but if you'd like \texttt{latexindent.pl} to try then change \texttt{indentPreamble} to - \texttt{1}. - -\yamltitle{lookForPreamble}*{fields} - - Not all files contain preamble; for example, \texttt{sty}, \texttt{cls} and \texttt{bib} - files typically do \emph{not}. Referencing \cref{lst:lookForPreamble}, if you set, for - example, \texttt{.tex} to \texttt{0}, then regardless of the setting of the value of - \texttt{indentPreamble}, preamble will not be assumed when operating upon \texttt{.tex} - files. - - \cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} -\yamltitle{preambleCommandsBeforeEnvironments}{0|1} - Assuming that \texttt{latexindent.pl} is asked to operate upon the preamble of a - document, when this switch is set to \texttt{0} then environment code blocks will be - sought first, and then command code blocks. When this switch is set to \texttt{1}, - commands will be sought first. The example that first motivated this switch contained the - code given in \cref{lst:motivatepreambleCommandsBeforeEnvironments}. - - \begin{cmhlistings}{Motivating \texttt{preambleCommandsBeforeEnvironments}}{lst:motivatepreambleCommandsBeforeEnvironments} -... -preheadhook={\begin{mdframed}[style=myframedstyle]}, -postfoothook=\end{mdframed}, -... -\end{cmhlistings} - - \index{indentation!defaultIndent description} - -\subsection{Indentation and horizontal space} -\yamltitle{defaultIndent}*{horizontal space} - This is the default indentation used in the absence of other details for the code block - with which we are working. The default value is \lstinline!\t! which means a tab; we will - explore customisation beyond \texttt{defaultIndent} in \vref{sec:noadd-indent-rules}. - - If you're interested in experimenting with \texttt{latexindent.pl} then you can - \emph{remove} all indentation by setting \texttt{defaultIndent: ""}. - -\yamltitle{removeTrailingWhitespace}*{fields}\label{yaml:removeTrailingWhitespace} - - Trailing white space can be removed both \emph{before} and \emph{after} processing the - document, as detailed in \cref{lst:removeTrailingWhitespace}; each of the fields can take - the values \texttt{0} or \texttt{1}. See - \vref{lst:removeTWS-before,lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS} for before - and after results. Thanks to \cite{vosskuhle} for providing this feature. - - \begin{minipage}{.4\textwidth} - \cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} - \end{minipage}% - \hfill - \begin{minipage}{.5\textwidth} - \begin{yaml}[numbers=none]{removeTrailingWhitespace (alt)}[before=\centering]{lst:removeTrailingWhitespace-alt} -removeTrailingWhitespace: 1 -\end{yaml} - \end{minipage}% - - You can specify \texttt{removeTrailingWhitespace} simply as \texttt{0} or \texttt{1}, if - you wish; in this case, \announce{2017-06-28}{removeTrailingWhitespace} - \texttt{latexindent.pl} will set both \texttt{beforeProcessing} and - \texttt{afterProcessing} to the value you specify; see - \cref{lst:removeTrailingWhitespace-alt}.% - -\subsection{Aligning at delimiters}\label{subsec:align-at-delimiters} -\yamltitle{lookForAlignDelims}*{fields} - This contains a list of code blocks that are operated upon in a special way by - \texttt{latexindent.pl} (see \cref{lst:aligndelims:basic}). In fact, the fields in - \texttt{lookForAlignDelims} can actually take two different forms: the \emph{basic} - version is shown in \cref{lst:aligndelims:basic} and the \emph{advanced} version in - \cref{lst:aligndelims:advanced}; we will discuss each in turn. \index{delimiters!advanced - settings of lookForAlignDelims} - - \begin{yaml}[numbers=none]{\texttt{lookForAlignDelims} (basic)}[width=.8\linewidth,before=\centering]{lst:aligndelims:basic} -lookForAlignDelims: - tabular: 1 - tabularx: 1 - longtable: 1 - array: 1 - matrix: 1 - ... - \end{yaml} - - Specifying code blocks in this field instructs \texttt{latexindent.pl} to try and align - each column by its alignment delimiters. It does have some limitations (discussed further - in \cref{sec:knownlimitations}), but in many cases it will produce results such as those - in \cref{lst:tabularbefore:basic,lst:tabularafter:basic}. - - If you find that \texttt{latexindent.pl} does not perform satisfactorily on such - environments then you can set the relevant key to \texttt{0}, for example - \texttt{tabular: 0}; alternatively, if you just want to ignore \emph{specific} instances - of the environment, you could wrap them in something from \texttt{noIndentBlock} (see - \vref{lst:noIndentBlock}). - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular1.tex}{\texttt{tabular1.tex}}{lst:tabularbefore:basic} - \cmhlistingsfromfile{demonstrations/tabular1-default.tex}{\texttt{tabular1.tex} default output}{lst:tabularafter:basic} - \end{cmhtcbraster} - - If, for example, you wish to remove the alignment of the \lstinline!\\! within a - delimiter-aligned block, then the advanced form of \texttt{lookForAlignDelims} shown in - \cref{lst:aligndelims:advanced} is for you. \index{regular expressions!delimiterRegEx} - \index{regular expressions!ampersand alignment} \index{delimiters!default settings of - lookForAlignDelims} \index{delimiters!ampersand \&} \index{delimiters!advanced settings} - \index{delimiters!lookForAlignDelims} - - \cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} - - Note that you can use a mixture of the basic and advanced form: in - \cref{lst:aligndelims:advanced} \texttt{tabular} and \texttt{tabularx} are advanced and - \texttt{longtable} is basic. When using the advanced form, each field should receive at - least 1 sub-field, and \emph{can} (but does not have to) receive any of the following - fields: - \begin{itemize} - \item \texttt{delims}: binary switch (0 or 1) equivalent to simply specifying, for - example, \texttt{tabular: 1} in the basic version shown in \cref{lst:aligndelims:basic}. - If \texttt{delims} is set to \texttt{0} then the align at ampersand routine will not be - called for this code block (default: 1); - \item \texttt{alignDoubleBackSlash}: binary switch (0 or 1) to determine if - \lstinline!\\! - should be aligned (default: 1); - \item \texttt{spacesBeforeDoubleBackSlash}: optionally,% - \announce{2018-01-13}*{update to spacesBeforeDoubleBackSlash in ampersand alignment} - specifies the number (integer $\geq$ 0) of spaces to be inserted before - \lstinline!\\! (default: 1); %\footnote{Previously this only activated if \texttt{alignDoubleBackSlash} was set to \texttt{0}.} - \item \announce{2017-06-19}{multiColumnGrouping} \texttt{multiColumnGrouping}: binary switch (0 - or 1) that details if \texttt{latexindent.pl} should group columns above and below a - \lstinline!\multicolumn! command (default: 0); - \item \announce{2017-06-19}{alignRowsWithoutMaxDelims} \texttt{alignRowsWithoutMaxDelims}: - binary switch (0 or 1) that details if rows that do not contain the maximum number of - delimeters should be formatted so as to have the ampersands aligned (default: 1); - \item \announce{2018-01-13}{spacesBeforeAmpersand in ampersand - alignment}\texttt{spacesBeforeAmpersand}: optionally specifies the number (integer $\geq$ - 0) of spaces to be placed \emph{before} ampersands (default: 1); - \item \announce{2018-01-13}{spacesAfterAmpersand in ampersand - alignment}\texttt{spacesAfterAmpersand}: optionally specifies the number (integer $\geq$ - 0) of spaces to be placed \emph{After} ampersands (default: 1); - \item \announce{2018-01-13}{justification of cells in ampersand - alignment}\texttt{justification}: optionally specifies the justification of each cell as - either \emph{left} or \emph{right} (default: left); - \item \announce{2020-03-21}{align final double back slash}{alignFinalDoubleBackSlash} - optionally specifies if the \emph{final} double back slash should be used for alignment - (default: 0); - \item \announce{2020-03-21}{don't measure feature}{dontMeasure} optionally specifies if - user-specified cells, rows or the largest entries should \emph{not} be measured (default: - 0); - \item \announce{2020-03-21}{delimiter RegEx feature}{delimiterRegEx} optionally specifies the - pattern matching to be used for the alignment delimeter (default: - \lstinline* '(?!. - We employ the settings given in \cref{lst:delimiterRegEx1} and run the command - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl tabbing.tex -l=delimiterRegEx1.yaml -\end{commandshell} - to receive the output given in \cref{lst:tabbing-mod1}. \index{regular - expressions!delimiter regex at \textbackslash= or \textbackslash>} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing-mod1.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx1}}{lst:tabbing-mod1} - \cmhlistingsfromfile{demonstrations/delimiterRegEx1.yaml}[yaml-TCB]{\texttt{delimiterRegEx1.yaml}}{lst:delimiterRegEx1} - \end{cmhtcbraster} - We note that: - \begin{itemize} - \item in \cref{lst:tabbing-mod1} the code has been aligned, as intended, at both the - \lstinline!\=! and \lstinline!\>!; - \item in \cref{lst:delimiterRegEx1} we have heeded the warning and captured the expression - using grouping parenthesis, specified a backslash using \lstinline!\\! and said that it - must be followed by either \lstinline!=! or \lstinline!>!. - \end{itemize} - We can explore \texttt{delimiterRegEx} a little further using the settings in - \cref{lst:delimiterRegEx2} and run the command \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl tabbing.tex -l=delimiterRegEx2.yaml -\end{commandshell} - to receive the output given in \cref{lst:tabbing-mod2}. \index{regular - expressions!delimiter regex at only \textbackslash>} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing-mod2.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx2}}{lst:tabbing-mod2} - \cmhlistingsfromfile{demonstrations/delimiterRegEx2.yaml}[yaml-TCB]{\texttt{delimiterRegEx2.yaml}}{lst:delimiterRegEx2} - \end{cmhtcbraster} - We note that only the \lstinline!\>! have been aligned. - - Of course, the other lookForAlignDelims options can be used alongside the - \texttt{delimiterRegEx}; regardless of the type of delimiter being used (ampersand or - anything else), the fields from \vref{lst:aligndelims:advanced} remain the same; for - example, using the settings in \cref{lst:delimiterRegEx3}, and running \index{switches!-l - demonstration} - \begin{commandshell} -latexindent.pl tabbing.tex -l=delimiterRegEx3.yaml -\end{commandshell} - to receive the output given in \cref{lst:tabbing-mod3}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing-mod3.tex}{\texttt{tabbing.tex} using \cref{lst:delimiterRegEx3}}{lst:tabbing-mod3} - \cmhlistingsfromfile{demonstrations/delimiterRegEx3.yaml}[yaml-TCB]{\texttt{delimiterRegEx3.yaml}}{lst:delimiterRegEx3} - \end{cmhtcbraster} - - It is possible that delimiters specified within \texttt{delimiterRegEx} can be of - different lengths. Consider the file in \cref{lst:tabbing1}, and associated YAML in - \cref{lst:delimiterRegEx4}. Note that the \cref{lst:delimiterRegEx4} specifies the option - for the delimiter to be either \lstinline!#! or \lstinline!\>!, \emph{which are different - lengths}. Upon running the command \index{switches!-l demonstration} \index{switches!-o - demonstration} - \begin{commandshell} -latexindent.pl tabbing1.tex -l=delimiterRegEx4.yaml -o=+-mod4 -\end{commandshell} - we receive the output in \cref{lst:tabbing1-mod4}. \index{regular expressions!delimiter - regex at \#} - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/tabbing1.tex}{\texttt{tabbing1.tex}}{lst:tabbing1} - \cmhlistingsfromfile{demonstrations/tabbing1-mod4.tex}{\texttt{tabbing1-mod4.tex}}{lst:tabbing1-mod4} - \cmhlistingsfromfile{demonstrations/delimiterRegEx4.yaml}[yaml-TCB]{\texttt{delimiterRegEx4.yaml}}{lst:delimiterRegEx4} - \end{cmhtcbraster} - - You can set the \emph{delimiter} justification as either \texttt{left} (default) or - \texttt{right}, which will only have effect when delimiters in the same column have - different lengths. Using the settings in \cref{lst:delimiterRegEx5} and running the - command \index{switches!-l demonstration} \index{switches!-o demonstration} - \begin{commandshell} -latexindent.pl tabbing1.tex -l=delimiterRegEx5.yaml -o=+-mod5 -\end{commandshell} - gives the output in \cref{lst:tabbing1-mod5}. \index{regular expressions!delimiter regex - at \# or \textbackslash>} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabbing1-mod5.tex}{\texttt{tabbing1-mod5.tex}}{lst:tabbing1-mod5} - \cmhlistingsfromfile{demonstrations/delimiterRegEx5.yaml}[yaml-TCB]{\texttt{delimiterRegEx5.yaml}}{lst:delimiterRegEx5} - \end{cmhtcbraster} - - Note that in \cref{lst:tabbing1-mod5} the second set of delimiters have been \emph{right - aligned} -- it is quite subtle! - -\subsubsection{lookForAlignDelims: lookForChildCodeBlocks}\label{sec:lookForChildCodeBlocks} - There \announce{2021-12-13}{lookForChildCodeBlocks demonstration} may be scenarios in - which you would prefer to instruct \texttt{latexindent.pl} \emph{not} to search for child - blocks; in which case setting \texttt{lookForChildCodeBlocks} to 0 may be a good way to - proceed. - - Using the settings from \vref{lst:dontMeasure1} on the file in \cref{lst:tabular-DM-1} - and running the command - \begin{commandshell} -latexindent.pl tabular-DM-1.tex -l=dontMeasure1.yaml -o=+-mod1 -\end{commandshell} - gives the output in \cref{lst:tabular-DM-1-mod1}. - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-1.tex}{\texttt{tabular-DM-1.tex}}{lst:tabular-DM-1} - \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1.tex}{\texttt{tabular-DM-1-mod1.tex}}{lst:tabular-DM-1-mod1} - \end{cmhtcbraster} - - We can improve the output from \cref{lst:tabular-DM-1-mod1} by employing the settings in - \cref{lst:dontMeasure1a} - \begin{commandshell} -latexindent.pl tabular-DM-1.tex -l=dontMeasure1a.yaml -o=+-mod1a -\end{commandshell} - which gives the output in \cref{lst:dontMeasure1a}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/tabular-DM-1-mod1a.tex}{\texttt{tabular-DM-1-mod1a.tex}}{lst:tabular-DM-1-mod1a} - \cmhlistingsfromfile{demonstrations/dontMeasure1a.yaml}[yaml-TCB]{\texttt{dontMeasure1a.yaml}}{lst:dontMeasure1a} - \end{cmhtcbraster} - -\subsection{Indent after items, specials and headings} -\yamltitle{indentAfterItems}*{fields} - The environment names specified in \texttt{indentAfterItems} tell \texttt{latexindent.pl} - to look for \lstinline!\item! commands; if these switches are set to \texttt{1} then - indentation will be performed so as indent the code after each \texttt{item}. A - demonstration is given in \cref{lst:itemsbefore,lst:itemsafter} - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} - \cmhlistingsfromfile{demonstrations/items1.tex}{\texttt{items1.tex}}{lst:itemsbefore} - \cmhlistingsfromfile{demonstrations/items1-default.tex}{\texttt{items1.tex} default output}{lst:itemsafter} - \end{cmhtcbraster} - -\yamltitle{itemNames}*{fields} - If you have your own \texttt{item} commands (perhaps you prefer to use \texttt{myitem}, - for example) then you can put populate them in \texttt{itemNames}. For example, users of - the \texttt{exam} document class might like to add \texttt{parts} to - \texttt{indentAfterItems} and \texttt{part} to \texttt{itemNames} to their user settings - (see \vref{sec:indentconfig} for details of how to configure user settings, and - \vref{lst:mysettings} \\ in particular \label{page:examsettings}.) - - \cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} - -\yamltitle{specialBeginEnd}*{fields}\label{yaml:specialBeginEnd} - The fields specified \index{specialBeginEnd!introduction} - \announce{2017-08-21}*{specialBeginEnd} in \texttt{specialBeginEnd} are, in their default - state, focused on math mode begin and end statements, but there is no requirement for - this to be the case; \cref{lst:specialBeginEnd} shows the default settings of - \texttt{specialBeginEnd}. \index{specialBeginEnd!default settings}% - - \cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} - - The field \texttt{displayMath} represents \lstinline!\[...\]!, \texttt{inlineMath} - represents \lstinline!$...$! and \texttt{displayMathTex} represents \lstinline!$$...$$!. - You can, of course, rename these in your own YAML files (see \vref{sec:localsettings}); - indeed, you might like to set up your own special begin and end statements. - - A demonstration of the before-and-after results are shown in - \cref{lst:specialbefore,lst:specialafter}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/special1.tex}{\texttt{special1.tex} before}{lst:specialbefore} - \cmhlistingsfromfile{demonstrations/special1-default.tex}{\texttt{special1.tex} default output}{lst:specialafter} - \end{cmhtcbraster} - - For each field, \texttt{lookForThis} is set to \texttt{1} by default, which means that - \texttt{latexindent.pl} will look for this pattern; you can tell \texttt{latexindent.pl} - not to look for the pattern, by setting \texttt{lookForThis} to \texttt{0}. - - There are \announce{2017-08-21}{specialBeforeCommand} examples in which it is - advantageous to search for \texttt{specialBeginEnd} fields \emph{before} searching for - commands, and the \texttt{specialBeforeCommand} switch controls this behaviour. For - example, consider the file shown in \cref{lst:specialLRbefore}.% - - \cmhlistingsfromfile{demonstrations/specialLR.tex}{\texttt{specialLR.tex}}{lst:specialLRbefore} - - Now consider the YAML files shown in - \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml} - \index{specialBeginEnd!searching for special before commands} - - \begin{cmhtcbraster} - \cmhlistingsfromfile[]{demonstrations/specialsLeftRight.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialsLeftRight.yaml}}{lst:specialsLeftRight-yaml} - \cmhlistingsfromfile[]{demonstrations/specialBeforeCommand.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeforeCommand.yaml}}{lst:specialBeforeCommand-yaml} - \end{cmhtcbraster} - - Upon running the following commands \index{switches!-l demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl specialLR.tex -l=specialsLeftRight.yaml -latexindent.pl specialLR.tex -l=specialsLeftRight.yaml,specialBeforeCommand.yaml -\end{commandshell} - \end{widepage} - we receive the respective outputs in - \cref{lst:specialLR-comm-first-tex,lst:specialLR-special-first-tex}. - - \begin{minipage}{.49\linewidth} - \cmhlistingsfromfile{demonstrations/specialLR-comm-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml}}{lst:specialLR-comm-first-tex} - \end{minipage} - \hfill - \begin{minipage}{.49\linewidth} - \cmhlistingsfromfile{demonstrations/specialLR-special-first.tex}{\texttt{specialLR.tex} using \cref{lst:specialsLeftRight-yaml,lst:specialBeforeCommand-yaml}}{lst:specialLR-special-first-tex} - \end{minipage} - - Notice that in: - \begin{itemize} - \item \cref{lst:specialLR-comm-first-tex} the \lstinline!\left! has been treated as a - \emph{command}, with one optional argument; - \item \cref{lst:specialLR-special-first-tex} the \texttt{specialBeginEnd} pattern in - \cref{lst:specialsLeftRight-yaml} - has been obeyed because \cref{lst:specialBeforeCommand-yaml} specifies that the - \texttt{specialBeginEnd} should be sought \emph{before} commands. - \end{itemize} - - You can,optionally, specify \announce{2018-04-27}{update to specialBeginEnd} the - \texttt{middle} field for anything that you specify in \texttt{specialBeginEnd}. For - example, let's consider the \texttt{.tex} file in \cref{lst:special2}. - \index{specialBeginEnd!middle} \index{specialBeginEnd!IfElsFi example}% - - \cmhlistingsfromfile{demonstrations/special2.tex}{\texttt{special2.tex}}{lst:special2} - - Upon saving the YAML settings in \cref{lst:middle-yaml,lst:middle1-yaml} and running the - commands \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl special2.tex -l=middle -latexindent.pl special2.tex -l=middle1 -\end{commandshell} - then we obtain the output given in \cref{lst:special2-mod1,lst:special2-mod2}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/middle.yaml}[yaml-TCB]{\texttt{middle.yaml}}{lst:middle-yaml} - \cmhlistingsfromfile{demonstrations/special2-mod1.tex}{\texttt{special2.tex} using \cref{lst:middle-yaml}}{lst:special2-mod1} - \end{cmhtcbraster} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/middle1.yaml}[yaml-TCB]{\texttt{middle1.yaml}}{lst:middle1-yaml} - \cmhlistingsfromfile{demonstrations/special2-mod2.tex}{\texttt{special2.tex} using \cref{lst:middle1-yaml}}{lst:special2-mod2} - \end{cmhtcbraster} - - We note that: - \begin{itemize} - \item in \cref{lst:special2-mod1} the bodies of each of the \texttt{Elsif} statements have been - indented appropriately; - \item the \texttt{Else} statement has \emph{not} been indented appropriately in - \cref{lst:special2-mod1} -- read on! - \item we have specified multiple settings for the \texttt{middle} field using the syntax - demonstrated in \cref{lst:middle1-yaml} so that the body of the \texttt{Else} statement - has been indented appropriately in \cref{lst:special2-mod2}. - \end{itemize} - - You may \announce{2018-08-13}{specialBeginEnd verbatim} specify fields in - \texttt{specialBeginEnd} to be treated as verbatim code blocks by changing - \texttt{lookForThis} to be \texttt{verbatim}. \index{verbatim!specialBeginEnd}% - - For example, beginning with the code in \cref{lst:special3-mod1} and the YAML in - \cref{lst:special-verb1-yaml}, and running \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl special3.tex -l=special-verb1 -\end{commandshell} - then the output in \cref{lst:special3-mod1} is unchanged. - \index{specialBeginEnd!specifying as verbatim} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/special-verb1.yaml}[yaml-TCB]{\texttt{special-verb1.yaml}}{lst:special-verb1-yaml} - \cmhlistingsfromfile{demonstrations/special3-mod1.tex}{\texttt{special3.tex} and output using \cref{lst:special-verb1-yaml}}{lst:special3-mod1} - \end{cmhtcbraster} - - We can combine the \texttt{specialBeginEnd} with the \texttt{lookForAlignDelims} feature. - We begin with the code in \cref{lst:special-align}. - - \cmhlistingsfromfile{demonstrations/special-align.tex}{\texttt{special-align.tex}}{lst:special-align} - - Let's assume that our goal is to align the code at the \texttt{edge} and \texttt{node} - text; we employ the code given in \cref{lst:edge-node1} and run the command - \index{switches!-l demonstration} \index{switches!-o demonstration} - \begin{commandshell} -latexindent.pl special-align.tex -l edge-node1.yaml -o=+-mod1 -\end{commandshell} - to receive the output in \cref{lst:special-align-mod1}. \index{specialBeginEnd!combined - with lookForAlignDelims} \index{specialBeginEnd!delimiterRegEx} - \index{specialBeginEnd!alignment at delimiter} \index{specialBeginEnd!tikz example} - \index{regular expressions!delimiter alignment for edge or node} \index{delimiters!within - specialBeginEnd blocks} \index{regular expressions!numeric 0-9} - - \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile{demonstrations/edge-node1.yaml}[yaml-TCB]{\texttt{edge-node1.yaml}}{lst:edge-node1} - \cmhlistingsfromfile{demonstrations/special-align-mod1.tex}{\texttt{special-align.tex} using \cref{lst:edge-node1}}{lst:special-align-mod1} - \end{cmhtcbraster} - - The output in \cref{lst:special-align-mod1} is not quite ideal. We can tweak the settings - within \cref{lst:edge-node1} in order to improve the output; in particular, we employ the - code in \cref{lst:edge-node2} and run the command \index{switches!-l demonstration} - \index{switches!-o demonstration} \index{regular expressions!uppercase alph A-Z} - \begin{commandshell} -latexindent.pl special-align.tex -l edge-node2.yaml -o=+-mod2 -\end{commandshell} - to receive the output in \cref{lst:special-align-mod2}. - \index{specialBeginEnd!delimiterRegEx tweaked} \index{regular expressions!at least one +} - \index{regular expressions!horizontal space \textbackslash{h}} - - \begin{cmhtcbraster}[ raster left skip=-3.5cm,] - \cmhlistingsfromfile{demonstrations/edge-node2.yaml}[yaml-TCB]{\texttt{edge-node2.yaml}}{lst:edge-node2} - \cmhlistingsfromfile{demonstrations/special-align-mod2.tex}{\texttt{special-align.tex} using \cref{lst:edge-node2}}{lst:special-align-mod2} - \end{cmhtcbraster} - - The \texttt{lookForThis} field can be considered optional; - \announce{2021-06-19}*{lookForThis optional for specialBeginEnd} by default, it is - assumed to be 1, which is demonstrated in \cref{lst:edge-node2}.% - -\yamltitle{indentAfterHeadings}*{fields} - This field enables the user to specify indentation rules that take effect after heading - commands such as \lstinline!\part!, \lstinline!\chapter!, \lstinline!\section!, - \lstinline!\subsection*!, or indeed any user-specified command written in this - field.\footnote{There is a slight difference in interface for this field when comparing - Version 2.2 to Version 3.0; see \vref{app:differences} for details.} - - \cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} - - The default settings do \emph{not} place indentation after a heading, but you can easily - switch them on by changing \texttt{indentAfterThisHeading} from 0 to 1. The - \texttt{level} field tells \texttt{latexindent.pl} the hierarchy of the heading structure - in your document. You might, for example, like to have both \texttt{section} and - \texttt{subsection} set with \texttt{level: 3} because you do not want the indentation to - go too deep. - - You can add any of your own custom heading commands to this field, specifying the - \texttt{level} as appropriate. You can also specify your own indentation in - \texttt{indentRules} (see \vref{sec:noadd-indent-rules}); you will find the default - \texttt{indentRules} contains \lstinline!chapter: " "! which tells - \texttt{latexindent.pl} simply to use a space character after \texttt{chapter} headings - (once \texttt{indent} is set to \texttt{1} for \texttt{chapter}). - - For example, assuming that you have the code in \cref{lst:headings1yaml} saved into - \texttt{headings1.yaml}, and that you have the text from \cref{lst:headings1} saved into - \texttt{headings1.tex}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings1.yaml}[yaml-TCB]{\texttt{headings1.yaml}}{lst:headings1yaml} - \cmhlistingsfromfile{demonstrations/headings1.tex}{\texttt{headings1.tex}}{lst:headings1} - \end{cmhtcbraster} - - If you run the command \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl headings1.tex -l=headings1.yaml -\end{commandshell} - then you should receive the output given in \cref{lst:headings1-mod1}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod1.tex}{\texttt{headings1.tex} using \cref{lst:headings1yaml}}{lst:headings1-mod1} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/headings1-mod2.tex}{\texttt{headings1.tex} second modification}{lst:headings1-mod2} - \end{minipage} - - Now say that you modify the \texttt{YAML} from \cref{lst:headings1yaml} so that the - \texttt{paragraph} \texttt{level} is \texttt{1}; after running \index{switches!-l - demonstration} - \begin{commandshell} -latexindent.pl headings1.tex -l=headings1.yaml -\end{commandshell} - you should receive the code given in \cref{lst:headings1-mod2}; notice that the - \texttt{paragraph} and \texttt{subsection} are at the same indentation level. - - \index{indentation!maximum indetation} - -\yamltitle{maximumIndentation}*{horizontal space} - You can control the maximum indentation given to your file by - \announce{2017-08-21}{maximumIndentation} specifying the \texttt{maximumIndentation} - field as horizontal space (but \emph{not} including tabs). This feature uses the - \texttt{Text::Tabs} module \cite{texttabs}, and is \emph{off} by default.% - - For example, consider the example shown in \cref{lst:mult-nested} together with the - default output shown in \cref{lst:mult-nested-default}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/mult-nested.tex}{\texttt{mult-nested.tex}}{lst:mult-nested} - \cmhlistingsfromfile[showtabs=true]{demonstrations/mult-nested-default.tex}{\texttt{mult-nested.tex} default output}{lst:mult-nested-default} - \end{cmhtcbraster} - - Now say that, for example, you have the \texttt{max-indentation1.yaml} from - \cref{lst:max-indentation1yaml} and that you run the following command: - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl mult-nested.tex -l=max-indentation1 -\end{commandshell} - You should receive the output shown in \cref{lst:mult-nested-max-ind1}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/max-indentation1.yaml}[yaml-TCB]{\texttt{max-indentation1.yaml}}{lst:max-indentation1yaml} - \cmhlistingsfromfile[showspaces=true]{demonstrations/mult-nested-max-ind1.tex}{\texttt{mult-nested.tex} using \cref{lst:max-indentation1yaml}}{lst:mult-nested-max-ind1} - \end{cmhtcbraster} - - Comparing the output in \cref{lst:mult-nested-default,lst:mult-nested-max-ind1} we notice - that the (default) tabs of indentation have been replaced by a single space. - - In general, when using the \texttt{maximumIndentation} feature, any leading tabs will be - replaced by equivalent spaces except, of course, those found in - \texttt{verbatimEnvironments} (see \vref{lst:verbatimEnvironments}) or - \texttt{noIndentBlock} (see \vref{lst:noIndentBlock}). - -\subsection{The code blocks known latexindent.pl}\label{subsubsec:code-blocks} - - As of Version 3.0, \texttt{latexindent.pl} processes documents using code blocks; each of - these are shown in \cref{tab:code-blocks}. \index{regular expressions!uppercase alph A-Z} - \index{regular expressions!lowercase alph a-z} \index{regular expressions!numeric 0-9} - \index{regular expressions!horizontal space \textbackslash{h}} - - \begin{table}[!htp] - \begin{widepage} - \centering - \caption{Code blocks known to \texttt{latexindent.pl}} - \label{tab:code-blocks} - \begin{tabular}{m{.3\linewidth}@{\hspace{.25cm}}m{.4\linewidth}@{\hspace{.25cm}}m{.2\linewidth}} - \toprule - Code block & characters allowed in name & example \\ - \midrule - environments & \lstinline!a-zA-Z@\*0-9_\\! & - \begin{lstlisting}[,nolol=true,] -\begin{myenv} -body of myenv -\end{myenv} - \end{lstlisting} - \\\cmidrule{2-3} - optionalArguments & \emph{inherits} name from parent (e.g environment name) & - \begin{lstlisting}[,nolol=true,] -[ -opt arg text -] - \end{lstlisting} - \\\cmidrule{2-3} - mandatoryArguments & \emph{inherits} name from parent (e.g environment name) & - \begin{lstlisting}[,nolol=true,] -{ -mand arg text -} - \end{lstlisting} - \\\cmidrule{2-3} - commands & \lstinline!+a-zA-Z@\*0-9_\:! & \lstinline!\mycommand!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - keyEqualsValuesBracesBrackets & \lstinline!a-zA-Z@\*0-9_\/.\h\{\}:\#-! & \lstinline!my key/.style=!$\langle$\itshape{arguments}$\rangle$ \\\cmidrule{2-3} - namedGroupingBracesBrackets & \lstinline!0-9\.a-zA-Z@\*>^ is designed for 'beamer'-type commands; the - \lstinline^.*?^ means anything in between \lstinline^<...>^ - \end{enumerate} - \item the \texttt{modifyLineBreaks} field refers to fine tuning settings detailed in - \vref{sec:modifylinebreaks}. In particular: - \begin{enumerate} - \item \texttt{betterFullStop} is in relation to the one sentence per line routine, detailed in - \vref{sec:onesentenceperline} - \item \texttt{doubleBackSlash} is in relation to the \texttt{DBSStartsOnOwnLine} and - \texttt{DBSFinishesWithLineBreak} polyswitches surrounding double back slashes, see - \vref{subsec:dbs} - \item \texttt{comma} is in relation to the \texttt{CommaStartsOnOwnLine} and - \texttt{CommaFinishesWithLineBreak} polyswitches surrounding commas in optional and - mandatory arguments; see \vref{tab:poly-switch-mapping} - \end{enumerate} - \end{enumerate} - - It is not obvious from \cref{lst:fineTuning}, but each of the \texttt{follow}, - \texttt{before} and \texttt{between} fields allow trailing comments, line breaks, and - horizontal spaces between each character. - - \index{warning!capture groups} - \begin{warning} - For the \texttt{fineTuning} feature you should only ever use \emph{non}-capturing groups, - such as \lstinline!(?:...)! and \emph{not} capturing groups, which are \lstinline!(...)! - \end{warning} - - \begin{example} - As a demonstration, consider the file given in \cref{lst:finetuning1}, together with its - default output using the command - \begin{commandshell} -latexindent.pl finetuning1.tex -\end{commandshell} - is given in \cref{lst:finetuning1-default}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/finetuning1.tex}{\texttt{finetuning1.tex}}{lst:finetuning1} - \cmhlistingsfromfile{demonstrations/finetuning1-default.tex}{\texttt{finetuning1.tex} default}{lst:finetuning1-default} - \end{cmhtcbraster} - - It's clear from \cref{lst:finetuning1-default} that the indentation scheme has not worked - as expected. We can \emph{fine tune} the indentation scheme by employing the settings - given in \cref{lst:fine-tuning1} and running the command \index{switches!-l - demonstration} - \begin{commandshell} -latexindent.pl finetuning1.tex -l=fine-tuning1.yaml -\end{commandshell} - and the associated (desired) output is given in \cref{lst:finetuning1-mod1}. - \index{regular expressions!at least one +} - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/finetuning1-mod1.tex}{\texttt{finetuning1.tex} using \cref{lst:fine-tuning1}}{lst:finetuning1-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning1.yaml}[yaml-TCB]{\texttt{finetuning1.yaml}}{lst:fine-tuning1} - \end{cmhtcbraster} - \end{example} - - \begin{example} - Let's have another demonstration; consider the file given in \cref{lst:finetuning2}, - together with its default output using the command - \begin{commandshell} -latexindent.pl finetuning2.tex -\end{commandshell} - is given in \cref{lst:finetuning2-default}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth, - raster left skip=-3.75cm, - raster right skip=0cm,] - \cmhlistingsfromfile{demonstrations/finetuning2.tex}{\texttt{finetuning2.tex}}{lst:finetuning2} - \cmhlistingsfromfile{demonstrations/finetuning2-default.tex}{\texttt{finetuning2.tex} default}{lst:finetuning2-default} - \end{cmhtcbraster} - - It's clear from \cref{lst:finetuning2-default} that the indentation scheme has not worked - as expected. We can \emph{fine tune} the indentation scheme by employing the settings - given in \cref{lst:fine-tuning2} and running the command \index{switches!-l - demonstration} - \begin{commandshell} -latexindent.pl finetuning2.tex -l=fine-tuning2.yaml -\end{commandshell} - and the associated (desired) output is given in \cref{lst:finetuning2-mod1}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth, - raster left skip=-3.75cm, - raster right skip=0cm,] - \cmhlistingsfromfile{demonstrations/finetuning2-mod1.tex}{\texttt{finetuning2.tex} using \cref{lst:fine-tuning2}}{lst:finetuning2-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/fine-tuning2.yaml}[yaml-TCB]{\texttt{finetuning2.yaml}}{lst:fine-tuning2} - \end{cmhtcbraster} - - In particular, note that the settings in \cref{lst:fine-tuning2} specify that - \texttt{NamedGroupingBracesBrackets} and \texttt{UnNamedGroupingBracesBrackets} can - follow \texttt{"} and that we allow \lstinline!---! between arguments. - \end{example} - - \begin{example} - You can tweak the \texttt{fineTuning} using the \texttt{-y} switch, but to be sure to use - quotes appropriately. For example, starting with the code in \cref{lst:finetuning3} and - running the following command - \begin{commandshell} -latexindent.pl -m -y='modifyLineBreaks:oneSentencePerLine:manipulateSentences: 1, modifyLineBreaks:oneSentencePerLine:sentencesBeginWith:a-z: 1, fineTuning:modifyLineBreaks:betterFullStop: "(?:\.|;|:(?![a-z]))|(?:(? output.tex -\end{commandshell} - - You can call the \texttt{-o} switch with the name of the output file \emph{without} an - extension; in \announce{2017-06-25}{upgrade to -o switch} this case, - \texttt{latexindent.pl} will use the extension from the original file. For example, the - following two calls to \texttt{latexindent.pl} are equivalent:% - \begin{commandshell} -latexindent.pl myfile.tex -o=output -latexindent.pl myfile.tex -o=output.tex -\end{commandshell} - - You can call the \texttt{-o} switch using a \texttt{+} symbol at the beginning; this will - \announce{2017-06-25}{+ sign in o switch} concatenate the name of the input file and the - text given to the \texttt{-o} switch. For example, the following two calls to - \texttt{latexindent.pl} are equivalent:% - \begin{commandshell} -latexindent.pl myfile.tex -o=+new -latexindent.pl myfile.tex -o=myfilenew.tex -\end{commandshell} - - You can call the \texttt{-o} switch using a \texttt{++} symbol at the end of the name - \announce{2017-06-25}{++ in o switch} of your output file; this tells - \texttt{latexindent.pl} to search successively for the name of your output file - concatenated with $0, 1, \ldots$ while the name of the output file exists. For example,% - \begin{commandshell} -latexindent.pl myfile.tex -o=output++ -\end{commandshell} - tells \texttt{latexindent.pl} to output to \texttt{output0.tex}, but if it exists then - output to \texttt{output1.tex}, and so on. - - Calling \texttt{latexindent.pl} with simply - \begin{commandshell} -latexindent.pl myfile.tex -o=++ -\end{commandshell} - tells it to output to \texttt{myfile0.tex}, but if it exists then output to - \texttt{myfile1.tex} and so on. - - The \texttt{+} and \texttt{++} feature of the \texttt{-o} switch can be combined; for - example, calling - \begin{commandshell} -latexindent.pl myfile.tex -o=+out++ -\end{commandshell} - tells \texttt{latexindent.pl} to output to \texttt{myfileout0.tex}, but if it exists, - then try \texttt{myfileout1.tex}, and so on. - - There is no need to specify a file extension when using the \texttt{++} feature, but if - you wish to, then you should include it \emph{after} the \texttt{++} symbols, for example - \begin{commandshell} -latexindent.pl myfile.tex -o=+out++.tex -\end{commandshell} - - See \vref{app:differences} for details of how the interface has changed from Version 2.2 - to Version 3.0 for this flag. \flagbox{-s, --silent} \index{switches!-s, --silent - definition and details} - \begin{commandshell} -latexindent.pl -s myfile.tex -latexindent.pl myfile.tex -s -\end{commandshell} - - Silent mode: no output will be given to the terminal. - -\flagbox{-t, --trace} - \index{switches!-t, --trace definition and details} - \begin{commandshell} -latexindent.pl -t myfile.tex -latexindent.pl myfile.tex -t -\end{commandshell} - - \label{page:traceswitch} - Tracing mode: verbose output will be given to \texttt{indent.log}. This is useful if - \texttt{latexindent.pl} has made a mistake and you're trying to find out where and why. - You might also be interested in learning about \texttt{latexindent.pl}'s thought process - -- if so, this switch is for you, although it should be noted that, especially for large - files, this does affect performance of the script. - -\flagbox{-tt, --ttrace} - \index{switches!-tt, --ttrace definition and details} - \begin{commandshell} -latexindent.pl -tt myfile.tex -latexindent.pl myfile.tex -tt -\end{commandshell} - - \emph{More detailed} tracing mode: this option gives more details to - \texttt{indent.log} - than the standard \texttt{trace} option (note that, even more so than with \texttt{-t}, - especially for large files, performance of the script will be affected). - -\flagbox{-l, --local[=myyaml.yaml,other.yaml,...]} - \index{switches!-l, --local definition and details} - \begin{commandshell} -latexindent.pl -l myfile.tex -latexindent.pl -l=myyaml.yaml myfile.tex -latexindent.pl -l myyaml.yaml myfile.tex -latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex -latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex -latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml -\end{commandshell} - - \label{page:localswitch} - \texttt{latexindent.pl} will always load \texttt{defaultSettings.yaml} (rhymes with - camel) and if it is called with the \texttt{-l} switch and it finds - \texttt{localSettings.yaml} in the same directory as \texttt{myfile.tex}, then, if not - found, it looks for \texttt{localSettings.yaml} (and friends, see - \vref{sec:localsettings}) in the current working directory, then - these% - \announce{2021-03-14}*{-l switch: localSettings and - friends} settings will be added to the indentation scheme. Information will be given in - \texttt{indent.log} on the success or failure of loading \texttt{localSettings.yaml}. - - The \texttt{-l} flag can take an \emph{optional} parameter which details the name (or - names separated by commas) of a YAML file(s) that resides in the same directory as - \texttt{myfile.tex}; you can use this option if you would like to load a settings file in - the current working directory that is \emph{not} called \texttt{localSettings.yaml}. - \announce{2017-08-21}*{-l switch absolute paths} In fact, you can specify both - \emph{relative} and \emph{absolute paths} for your YAML files; for example% - \begin{commandshell} -latexindent.pl -l=../../myyaml.yaml myfile.tex -latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex -latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex -\end{commandshell} - You will find a lot of other explicit demonstrations of how to use the \texttt{-l} switch - throughout this documentation, - - You can call the \texttt{-l} switch with a `+' symbol either before or after - \announce{2017-06-25}{+ sign with -l switch} another YAML file; for example: - \begin{commandshell} -latexindent.pl -l=+myyaml.yaml myfile.tex -latexindent.pl -l "+ myyaml.yaml" myfile.tex -latexindent.pl -l=myyaml.yaml+ myfile.tex -\end{commandshell} - which translate, respectively, to - \begin{commandshell} -latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex -latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex -latexindent.pl -l=myyaml.yaml,localSettings.yaml myfile.tex -\end{commandshell} - Note that the following is \emph{not} allowed: - \begin{commandshell} -latexindent.pl -l+myyaml.yaml myfile.tex -\end{commandshell} - and - \begin{commandshell} -latexindent.pl -l + myyaml.yaml myfile.tex -\end{commandshell} - will \emph{only} load \texttt{localSettings.yaml}, and \texttt{myyaml.yaml} will be - ignored. If you wish to use spaces between any of the YAML settings, then you must wrap - the entire list of YAML files in quotes, as demonstrated above. - - You may also choose to omit the \texttt{yaml} extension, such as \announce{2017-06-25}{no - extension for -l switch}% - \begin{commandshell} -latexindent.pl -l=localSettings,myyaml myfile.tex -\end{commandshell} -\flagbox{-y, --yaml=yaml settings} - \index{switches!-y, --yaml definition and details} - \index{indentation!default} - \index{indentation!defaultIndent using -y switch} - \begin{commandshell} -latexindent.pl myfile.tex -y="defaultIndent: ' '" -latexindent.pl myfile.tex -y="defaultIndent: ' ',maximumIndentation:' '" -latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'" -latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3' -m -latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m -\end{commandshell} - \label{page:yamlswitch}You% - \announce{2017-08-21}{the -y switch} can specify YAML settings from the command line - using the \texttt{-y} or \texttt{--yaml} switch; sample demonstrations are given above. - Note, in particular, that multiple settings can be specified by separating them via - commas. There is a further option to use a \texttt{;} to separate fields, which is - demonstrated in \vref{sec:yamlswitch}. - - Any settings specified via this switch will be loaded \emph{after} any specified using - the \texttt{-l} switch. This is discussed further in \vref{sec:loadorder}. \flagbox{-d, - --onlydefault} \index{switches!-d, --onlydefault definition and details} - \begin{commandshell} -latexindent.pl -d myfile.tex -\end{commandshell} - - Only \texttt{defaultSettings.yaml}: you might like to read \cref{sec:defuseloc} before - using this switch. By default, \texttt{latexindent.pl} will always search for - \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml} in your home directory. If you - would prefer it not to do so then (instead of deleting or renaming - \texttt{indentconfig.yaml} or \texttt{.indentconfig.yaml}) you can simply call the script - with the \texttt{-d} switch; note that this will also tell the script to ignore - \texttt{localSettings.yaml} even if it has been called with the \texttt{-l} switch; - \texttt{latexindent.pl} \announce{2017-08-21}*{updated -d switch} will also ignore any - settings specified from the \texttt{-y} switch.% - -\flagbox{-c, --cruft=} - \index{switches!-c, --cruft definition and details} - \begin{commandshell} -latexindent.pl -c=/path/to/directory/ myfile.tex -\end{commandshell} - - If you wish to have backup files and \texttt{indent.log} written to a directory other - than the current working directory, then you can send these `cruft' files to another - directory. Note the use of a trailing forward slash. % this switch was made as a result of http://tex.stackexchange.com/questions/142652/output-latexindent-auxiliary-files-to-a-different-directory - -\flagbox{-g, --logfile=} - \index{switches!-g, --logfile definition and details} - \begin{commandshell} -latexindent.pl -g=other.log myfile.tex -latexindent.pl -g other.log myfile.tex -latexindent.pl --logfile other.log myfile.tex -latexindent.pl myfile.tex -g other.log -\end{commandshell} - - By default, \texttt{latexindent.pl} reports information to \texttt{indent.log}, but if - you wish to change the name of this file, simply call the script with your chosen name - after the \texttt{-g} switch as demonstrated above. - - \announce{2021-05-07}{log file creation updated} If \texttt{latexindent.pl} can not open - the log file that you specify, then the script will operate, and no log file will be - produced; this might be helpful to users who wish to specify the following, for example - \begin{commandshell} -latexindent.pl -g /dev/null myfile.tex -\end{commandshell} - -\flagbox{-sl, --screenlog} - \index{switches!-sl, --screenlog definition and details} - \begin{commandshell} -latexindent.pl -sl myfile.tex -latexindent.pl -screenlog myfile.tex -\end{commandshell} - Using this \announce{2018-01-13}{screenlog switch created} option tells - \texttt{latexindent.pl} to output the log file to the screen, as well as to your chosen - log file.% - -\flagbox{-m, --modifylinebreaks} - \index{switches!-m, --modifylinebreaks definition and details} - \begin{commandshell} -latexindent.pl -m myfile.tex -latexindent.pl -modifylinebreaks myfile.tex -\end{commandshell} - - One of the most exciting developments in Version~3.0 is the ability to modify line - breaks; for full details see \vref{sec:modifylinebreaks} - - \texttt{latexindent.pl} can also be called on a file without the file extension, for - example - \begin{commandshell} -latexindent.pl myfile -\end{commandshell} - and in which case, you can specify the order in which extensions are searched for; see - \vref{lst:fileExtensionPreference} for full details. \flagbox{STDIN} - \begin{commandshell} -cat myfile.tex | latexindent.pl -cat myfile.tex | latexindent.pl - -\end{commandshell} - \texttt{latexindent.pl} will% - \announce{2018-01-13}{STDIN allowed} allow input from STDIN, which means that you can - pipe output from other commands directly into the script. For example assuming that you - have content in \texttt{myfile.tex}, then the above command will output the results of - operating upon \texttt{myfile.tex}. - - If you wish to use this feature with your own local settings, via the \texttt{-l} switch, - then you should finish your call to \texttt{latexindent.pl} with a \texttt{-} sign: - \begin{commandshell} -cat myfile.tex | latexindent.pl -l=mysettings.yaml - -\end{commandshell} - - Similarly, if you \announce{2018-01-13}*{no options/filename updated} simply type - \texttt{latexindent.pl} at the command line, then it will expect (STDIN) input from the - command line.% - \begin{commandshell} -latexindent.pl -\end{commandshell} - - Once you have finished typing your input, you can press - \begin{itemize} - \item \texttt{CTRL+D} on Linux - \item \texttt{CTRL+Z} followed by \texttt{ENTER} on Windows - \end{itemize} - to signify that your input has finished. Thanks to \cite{xu-cheng} for an update to this - feature. \flagbox{-r, --replacement} \index{switches!-r, --replacement definition and - details} - \begin{commandshell} -latexindent.pl -r myfile.tex -latexindent.pl -replacement myfile.tex -\end{commandshell} - You can \announce{2019-07-13}{replacement mode switch} call \texttt{latexindent.pl} with - the \texttt{-r} switch to instruct it to perform replacements/substitutions on your file; - full details and examples are given in \vref{sec:replacements}. \index{verbatim!rv, - replacementrespectverb switch}% - -\flagbox{-rv, --replacementrespectverb} - \index{switches!-rv, --replacementrespectverb definition and details} - \begin{commandshell} -latexindent.pl -rv myfile.tex -latexindent.pl -replacementrespectverb myfile.tex -\end{commandshell} - You can \announce{2019-07-13}{replacement mode switch, respecting verbatim} instruct - \texttt{latexindent.pl} to perform replacements/substitutions by using the \texttt{-rv} - switch, but will \emph{respect verbatim code blocks}; full details and examples are given - in \vref{sec:replacements}.% - -\flagbox{-rr, --onlyreplacement} - \index{switches!-rr, --onlyreplacement definition and details} - \begin{commandshell} -latexindent.pl -rr myfile.tex -latexindent.pl -onlyreplacement myfile.tex -\end{commandshell} - You can \announce{2019-07-13}{replacement (only) mode switch} instruct - \texttt{latexindent.pl} to skip all of its other indentation operations and \emph{only} - perform replacements/substitutions by using the \texttt{-rr} switch; full details and - examples are given in \vref{sec:replacements}.% - -\flagbox{-k, --check} - \index{switches!-k, --check definition and details} - \begin{commandshell} -latexindent.pl -k myfile.tex -latexindent.pl -check myfile.tex -\end{commandshell} - You can \announce{2021-09-16}{-k,-check switch} instruct \texttt{latexindent.pl} to check - if the text after indentation matches that given in the original file.% - - The \texttt{exit} code \index{exit code} of \texttt{latexindent.pl} is 0 by default. If - you use the \texttt{-k} switch then - \begin{itemize} - \item if the text after indentation matches that given in the original file, then the exit code - is 0; - \item if the text after indentation does \emph{not} match that given in the original file, then - the exit code is 1. - \end{itemize} - - The value of the exit code may be important to those wishing to, for example, check the - status of the indentation in continuous integration tools such as GitHub Actions. Full - details of the exit codes of \texttt{latexindent.pl} are given in \cref{tab:exit-codes}. - - A simple \texttt{diff} will be given in \texttt{indent.log}. - -\flagbox{-kv, --checkv} - \index{switches!-kv, --checkv definition and details} - \begin{commandshell} -latexindent.pl -kv myfile.tex -latexindent.pl -checkv myfile.tex -\end{commandshell} - \announce{2021-09-16}{-kv, -checkv: check verbose switch} The \texttt{check verbose} - switch is exactly the same as the \texttt{-k} switch, except that it is \emph{verbose}, - and it will output the (simple) diff to the terminal, as well as to \texttt{indent.log}. - -\flagbox{-n, --lines=MIN-MAX} - \index{switches!-n, --lines definition and details} - \begin{commandshell} -latexindent.pl -n 5-8 myfile.tex -latexindent.pl -lines 5-8 myfile.tex -\end{commandshell} - \announce{2021-09-16}{-n, -lines switch} The \texttt{lines} switch instructs - \texttt{latexindent.pl} to operate only on specific line ranges within - \texttt{myfile.tex}. - - Complete demonstrations are given in \cref{sec:line-switch}. - -\flagbox{--GCString} - \index{switches!--GCString} - \begin{commandshell} -latexindent.pl --GCString myfile.tex -\end{commandshell} - \announce*{2022-03-25}{GCString switch} instructs \texttt{latexindent.pl} to load the - \texttt{Unicode::GCString} module. This should only be necessary if you find that the - alignment at ampersand routine (described in \cref{subsec:align-at-delimiters}) does not - work for your language. Further details are given in \cref{subsec:the-GCString}. - -\subsection{From arara}\label{sec:arara} - Using \texttt{latexindent.pl} from the command line is fine for some folks, but others - may find it easier to use from \texttt{arara}; you can find the arara rule for - \texttt{latexindent.pl} and its associated documentation at \cite{paulo}. - -\subsection{Summary of exit codes} - \index{exit code!summary} - Assuming that you call \texttt{latexindent.pl} on \texttt{myfile.tex} - \begin{commandshell} -latexindent.pl myfile.tex -\end{commandshell} - then \texttt{latexindent.pl} can exit with the exit codes given in \cref{tab:exit-codes}. - - \begin{table}[!htb] - \caption{Exit codes for \texttt{latexindent.pl}} - \label{tab:exit-codes} - \begin{tabular}{ccl} - \toprule - exit code & indentation & status \\ - \midrule - 0 & \faCheck & success; if \texttt{-k} or \texttt{-kv} active, indented text matches original \\ - 0 & \faClose & success; if \texttt{-version}, \texttt{-vversion} or \texttt{-help}, no indentation performed \\ - 1 & \faCheck & success, and \texttt{-k} or \texttt{-kv} active; indented text \emph{different} from original \\ - \midrule - 2 & \faClose & failure, \texttt{defaultSettings.yaml} could not be read \\ - 3 & \faClose & failure, myfile.tex not found \\ - 4 & \faClose & failure, myfile.tex exists but cannot be read \\ - 5 & \faClose & failure, \texttt{-w} active, and back-up file cannot be written \\ - 6 & \faClose & failure, \texttt{-c} active, and cruft directory does not exist \\ - \bottomrule - \end{tabular} - \end{table} diff --git a/support/latexindent/documentation/sec-indent-config-and-settings.tex b/support/latexindent/documentation/sec-indent-config-and-settings.tex deleted file mode 100644 index 600d24bb4f..0000000000 --- a/support/latexindent/documentation/sec-indent-config-and-settings.tex +++ /dev/null @@ -1,207 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\section{indentconfig.yaml, local settings and the -y switch }\label{sec:indentconfig} - The behaviour of \texttt{latexindent.pl} is controlled from the settings specified in any - of the YAML files that you tell it to load. By default, \texttt{latexindent.pl} will only - load \texttt{defaultSettings.yaml}, but there are a few ways that you can tell it to load - your own settings files. - -\subsection{indentconfig.yaml and .indentconfig.yaml} - \texttt{latexindent.pl} will always check your home directory for - \texttt{indentconfig.yaml} - and \texttt{.indentconfig.yaml} (unless it is called with the \texttt{-d} switch), which - is a plain text file you can create that contains the \emph{absolute} paths for any - settings files that you wish \texttt{latexindent.pl} to load. There is no difference - between \texttt{indentconfig.yaml} and \texttt{.indentconfig.yaml}, other than the fact - that \texttt{.indentconfig.yaml} is a `hidden' file; thank you to - \cite{jacobo-diaz-hidden-config} for providing this feature. In what follows, we will use - \texttt{indentconfig.yaml}, but it is understood that this could equally represent - \texttt{.indentconfig.yaml}. If you have both files in existence then - \texttt{indentconfig.yaml} takes priority. - - For Mac and Linux users, their home directory is \texttt{~/username} while Windows (Vista - onwards) is \lstinline!C:\Users\username!\footnote{If you're not sure where to put - \texttt{indentconfig.yaml}, don't worry \texttt{latexindent.pl} will tell you in the log - file exactly where to put it assuming it doesn't exist already.} \Cref{lst:indentconfig} - shows a sample \texttt{indentconfig.yaml} file. - - \begin{yaml}{\texttt{indentconfig.yaml} (sample)}{lst:indentconfig} -# Paths to user settings for latexindent.pl -# -# Note that the settings will be read in the order you -# specify here- each successive settings file will overwrite -# the variables that you specify - -paths: -- /home/cmhughes/Documents/yamlfiles/mysettings.yaml -- /home/cmhughes/folder/othersettings.yaml -- /some/other/folder/anynameyouwant.yaml -- C:\Users\chughes\Documents\mysettings.yaml -- C:\Users\chughes\Desktop\test spaces\more spaces.yaml -\end{yaml} - - Note that the \texttt{.yaml} files you specify in \texttt{indentconfig.yaml} will be - loaded in the order in which you write them. Each file doesn't have to have every switch - from \texttt{defaultSettings.yaml}; in fact, I recommend that you only keep the switches - that you want to \emph{change} in these settings files. - - To get started with your own settings file, you might like to save a copy of - \texttt{defaultSettings.yaml} in another directory and call it, for example, - \texttt{mysettings.yaml}. Once you have added the path to \texttt{indentconfig.yaml} you - can change the switches and add more code-block names to it as you see fit -- have a look - at \cref{lst:mysettings} for an example that uses four tabs for the default indent, adds - the \texttt{tabbing} environment/command to the list of environments that contains - alignment delimiters; you might also like to refer to the many YAML files detailed - throughout the rest of this documentation. \index{indentation!defaultIndent using YAML - file} - - \begin{yaml}{\texttt{mysettings.yaml} (example)}{lst:mysettings} -# Default value of indentation -defaultIndent: "\t\t\t\t" - -# environments that have tab delimiters, add more -# as needed -lookForAlignDelims: - tabbing: 1 -\end{yaml} - - You can make sure that your settings are loaded by checking \texttt{indent.log} for - details -- if you have specified a path that \texttt{latexindent.pl} doesn't recognise - then you'll get a warning, otherwise you'll get confirmation that \texttt{latexindent.pl} - has read your settings file \footnote{Windows users may find that they have to end - \texttt{.yaml} files with a blank line}. \index{warning!editing YAML files} - - \begin{warning} - When editing \texttt{.yaml} files it is \emph{extremely} important to remember how - sensitive they are to spaces. I highly recommend copying and pasting from - \texttt{defaultSettings.yaml} when you create your first - \texttt{whatevernameyoulike.yaml} file. - - If \texttt{latexindent.pl} can not read your \texttt{.yaml} file it will tell you so in - \texttt{indent.log}. - \end{warning} - - If you find that \announce{2021-06-19}{encoding option for indentconfig.yaml} - \texttt{latexindent.pl} does not read your YAML file, then it might be as a result of the - default commandline encoding not being UTF-8; normally this will only occcur for Windows - users. In this case, you might like to explore the \texttt{encoding} option for - \texttt{indentconfig.yaml} as demonstrated in \cref{lst:indentconfig-encoding}.% - - \cmhlistingsfromfile{demonstrations/encoding.yaml}[yaml-TCB]{The \texttt{encoding} option for \texttt{indentconfig.yaml}}{lst:indentconfig-encoding} - - Thank you to \cite{qiancy98} for this contribution; please see \vref{app:encoding} and - details within \cite{encoding} for further information. - -\subsection{localSettings.yaml and friends}\label{sec:localsettings} - The \texttt{-l} switch tells \texttt{latexindent.pl} to look for - \texttt{localSettings.yaml} and/or friends in the \emph{same directory} as - \texttt{myfile.tex}. For% - \announce{2021-03-14}*{-l - switch: localSettings and friends} example, if you use the following command - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl -l myfile.tex -\end{commandshell} - then \texttt{latexindent.pl} will search for and then, assuming they exist, load each of - the following files in the following order: - \begin{enumerate} - \item localSettings.yaml - \item latexindent.yaml - \item .localSettings.yaml - \item .latexindent.yaml - \end{enumerate} - These files will be assumed to be in the same directory as \texttt{myfile.tex}, or - otherwise in the current working directory. You do not need to have all of the above - files, usually just one will be sufficient. In what follows, whenever we refer to - \texttt{localSettings.yaml} it is assumed that it can mean any of the four named options - listed above. - - If you'd prefer to name your \texttt{localSettings.yaml} file something different, (say, - \texttt{mysettings.yaml} as in \cref{lst:mysettings}) then you can call - \texttt{latexindent.pl} using, for example, - \begin{commandshell} -latexindent.pl -l=mysettings.yaml myfile.tex -\end{commandshell} - - Any settings file(s) specified using the \texttt{-l} switch will be read \emph{after} - \texttt{defaultSettings.yaml} and, assuming they exist, any user setting files specified - in \texttt{indentconfig.yaml}. - - Your settings file can contain any switches that you'd like to change; a sample is shown - in \cref{lst:localSettings}, and you'll find plenty of further examples throughout this - manual. \index{verbatim!verbatimEnvironments demonstration (-l switch)} - - \begin{yaml}{\texttt{localSettings.yaml} (example)}{lst:localSettings} -# verbatim environments - environments specified -# here will not be changed at all! -verbatimEnvironments: - cmhenvironment: 0 - myenv: 1 -\end{yaml} - - You can make sure that your settings file has been loaded by checking \texttt{indent.log} - for details; if it can not be read then you receive a warning, otherwise you'll get - confirmation that \texttt{latexindent.pl} has read your settings file. - -\subsection{The -y|yaml switch}\label{sec:yamlswitch} - You% - \announce{2017-08-21}{demonstration of the -y switch} - may use the \texttt{-y} switch to load your settings; for example, if you wished to - specify the settings from \cref{lst:localSettings} using the \texttt{-y} switch, then you - could use the following command: - \index{verbatim!verbatimEnvironments demonstration (-y switch)} - \begin{commandshell} -latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex -\end{commandshell} - Note the use of \texttt{;} to specify another field within \texttt{verbatimEnvironments}. - This is shorthand, and equivalent, to using the following command: \index{switches!-y - demonstration} - \begin{commandshell} -latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex -\end{commandshell} - You may, of course, specify settings using the \texttt{-y} switch as well as, for - example, settings loaded using the \texttt{-l} switch; for example, \index{switches!-l - demonstration} \index{switches!-y demonstration} - \begin{commandshell} -latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex -\end{commandshell} - Any settings specified using the \texttt{-y} switch will be loaded \emph{after} any - specified using \texttt{indentconfig.yaml} and the \texttt{-l} switch. - - If you wish to specify any regex-based settings using the \texttt{-y} switch, - \index{regular expressions!using -y switch} it is important not to use quotes surrounding - the regex; for example, with reference to the `one sentence per line' feature - (\vref{sec:onesentenceperline}) and the listings within \vref{lst:sentencesEndWith}, the - following settings give the option to have sentences end with a semicolon - \index{switches!-y demonstration} - \begin{commandshell} -latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' -\end{commandshell} - -\subsection{Settings load order}\label{sec:loadorder} - \texttt{latexindent.pl} loads the settings files in the following order: - \index{switches!-l in relation to other settings} - \begin{enumerate} - \item \texttt{defaultSettings.yaml} is always loaded, and can not be renamed; - \item \texttt{anyUserSettings.yaml} and any other arbitrarily-named files specified in - \texttt{indentconfig.yaml}; - \item \texttt{localSettings.yaml} but only if found in the same directory as - \texttt{myfile.tex} - and called with \texttt{-l} switch; this file can be renamed, provided that the call to - \texttt{latexindent.pl} is adjusted accordingly (see \cref{sec:localsettings}). You may - specify both relative and absolute% - \announce{2017-08-21}*{-l absolute paths} paths to other YAML files using the \texttt{-l} - switch, separating multiple files using commas; - \item any settings \announce{2017-08-21}{-y switch load order} specified in the \texttt{-y} - switch.% - \end{enumerate} - A visual representation of this is given in \cref{fig:loadorder}. - - \begin{figure}[!htb] - \centering - \input{figure-schematic} - \caption{Schematic of the load order described in \cref{sec:loadorder}; solid lines represent - mandatory files, dotted lines represent optional files. \texttt{indentconfig.yaml} can - contain as many files as you like. The files will be loaded in order; if you specify - settings for the same field in more than one file, the most recent takes priority. } - \label{fig:loadorder} - \end{figure} diff --git a/support/latexindent/documentation/sec-introduction.tex b/support/latexindent/documentation/sec-introduction.tex deleted file mode 100644 index 83db4317c2..0000000000 --- a/support/latexindent/documentation/sec-introduction.tex +++ /dev/null @@ -1,250 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\section{Introduction} -\subsection{Thanks} - I first created \texttt{latexindent.pl} to help me format chapter files in a big project. - After I blogged about it on the \TeX{} stack exchange \cite{cmhblog} I received some - positive feedback and follow-up feature requests. A big thank you to Harish Kumar - \cite{harish} who helped to develop and test the initial versions of the script. - - The \texttt{YAML}-based interface of \texttt{latexindent.pl} was inspired by the - wonderful \texttt{arara} tool; any similarities are deliberate, and I hope that it is - perceived as the compliment that it is. Thank you to Paulo Cereda and the team for - releasing this awesome tool; I initially worried that I was going to have to make a GUI - for \texttt{latexindent.pl}, but the release of \texttt{arara} has meant there is no - need. - - There have been several contributors to the project so far (and hopefully more in the - future!); thank you very much to the people detailed in \vref{sec:contributors} for their - valued contributions, and thank you to those who report bugs and request features at - \cite{latexindent-home}. - -\subsection{License} - \texttt{latexindent.pl} is free and open source, and it always will be; it - is released under the GNU General Public License v3.0. - - Before you start using it on any important files, bear in mind that - \texttt{latexindent.pl} has the option to overwrite your \texttt{.tex} files. It will - always make at least one backup (you can choose how many it makes, see - \cpageref{page:onlyonebackup}) but you should still be careful when using it. The script - has been tested on many files, but there are some known limitations (see - \cref{sec:knownlimitations}). You, the user, are responsible for ensuring that you - maintain backups of your files before running \texttt{latexindent.pl} on them. I think it - is important at this stage to restate an important part of the license here: - \begin{quote}\itshape - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - \end{quote} - There is certainly no malicious intent in releasing this script, and I do hope that it - works as you expect it to; if it does not, please first of all make sure that you have - the correct settings, and then feel free to let me know at \cite{latexindent-home} with a - complete minimum working example as I would like to improve the code as much as possible. - - \begin{warning} - Before you try the script on anything important (like your thesis), test it out on the - sample files in the \texttt{test-case} directory \cite{latexindent-home}. - \index{warning!be sure to test before use} - \end{warning} - - \emph{If you have used any version 2.* of \texttt{latexindent.pl}, there - are a few changes to the interface; see \vref{app:differences} and the comments - throughout this document for details}. - -\subsection{Quick start}\label{sec:quickstart} - If you'd like to get started with \texttt{latexindent.pl} then simply type - \begin{commandshell} -latexindent.pl myfile.tex -\end{commandshell} - from the command line. - - We give an introduction to \texttt{latexindent.pl} using \cref{lst:quick-start}; there is - no explanation in this section, which is deliberate for a quick start. The rest of the - manual is more verbose. - - \cmhlistingsfromfile{demonstrations/quick-start.tex}{\texttt{quick-start.tex}}{lst:quick-start} - - Running - \begin{commandshell} -latexindent.pl quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-default}. - - \cmhlistingsfromfile{demonstrations/quick-start-default.tex}{\texttt{quick-start-default.tex}}{lst:quick-start-default} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -l quick-start1.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod1}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start1.yaml}[yaml-TCB]{\texttt{quick-start1.yaml}}{lst:quick-start1yaml} - \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod1.tex}{\texttt{quick-start-mod1.tex}}{lst:quick-start-mod1} - \end{cmhtcbraster} - \end{example} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -l quick-start2.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod2}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start2.yaml}[yaml-TCB]{\texttt{quick-start2.yaml}}{lst:quick-start2yaml} - \cmhlistingsfromfile[showspaces=true]{demonstrations/quick-start-mod2.tex}{\texttt{quick-start-mod2.tex}}{lst:quick-start-mod2} - \end{cmhtcbraster} - \end{example} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -l quick-start3.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod3}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start3.yaml}[yaml-TCB]{\texttt{quick-start3.yaml}}{lst:quick-start3yaml} - \cmhlistingsfromfile{demonstrations/quick-start-mod3.tex}{\texttt{quick-start-mod3.tex}}{lst:quick-start-mod3} - \end{cmhtcbraster} - \end{example} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -m -l quick-start4.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod4}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start4.yaml}[MLB-TCB]{\texttt{quick-start4.yaml}}{lst:quick-start4yaml} - \cmhlistingsfromfile{demonstrations/quick-start-mod4.tex}{\texttt{quick-start-mod4.tex}}{lst:quick-start-mod4} - \end{cmhtcbraster} - Full details of text wrapping in \cref{subsec:textwrapping}. - \end{example} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -m -l quick-start5.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod5}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start5.yaml}[MLB-TCB]{\texttt{quick-start5.yaml}}{lst:quick-start5yaml} - \cmhlistingsfromfile{demonstrations/quick-start-mod5.tex}{\texttt{quick-start-mod5.tex}}{lst:quick-start-mod5} - \end{cmhtcbraster} - Full details of text wrapping in \cref{subsec:textwrapping}. - \end{example} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -m -l quick-start6.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod6}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start6.yaml}[MLB-TCB]{\texttt{quick-start6.yaml}}{lst:quick-start6yaml} - \cmhlistingsfromfile{demonstrations/quick-start-mod6.tex}{\texttt{quick-start-mod6.tex}}{lst:quick-start-mod6} - \end{cmhtcbraster} - This is an example of a \emph{poly-switch}; full details of \emph{poly-switches} are - covered in \cref{sec:poly-switches}. - \end{example} - - \begin{example} - Running - \begin{commandshell} -latexindent.pl -m -l quick-start7.yaml quick-start.tex -\end{commandshell} - gives \cref{lst:quick-start-mod7}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/quick-start7.yaml}[MLB-TCB]{\texttt{quick-start7.yaml}}{lst:quick-start7yaml} - \cmhlistingsfromfile{demonstrations/quick-start-mod7.tex}{\texttt{quick-start-mod7.tex}}{lst:quick-start-mod7} - \end{cmhtcbraster} - Full details of \emph{poly-switches} are covered in \cref{sec:poly-switches}. - \end{example} - -\subsection{Required perl modules} - If you receive an error message such as that given in - \cref{lst:poss-errors}, then you need to install the missing perl modules. - \begin{cmhlistings}[style=tcblatex,language=Perl]{Possible error messages}{lst:poss-errors} -Can't locate File/HomeDir.pm in @INC (@INC contains: /Library/Perl/5.12/darwin-thread-multi-2level /Library/Perl/5.12 /Network/Library/Perl/5.12/darwin-thread-multi-2level /Network/Library/Perl/5.12 /Library/Perl/Updates/5.12.4/darwin-thread-multi-2level /Library/Perl/Updates/5.12.4 /System/Library/Perl/5.12/darwin-thread-multi-2level /System/Library/Perl/5.12 /System/Library/Perl/Extras/5.12/darwin-thread-multi-2level /System/Library/Perl/Extras/5.12 .) at helloworld.pl line 10. -BEGIN failed--compilation aborted at helloworld.pl line 10. -\end{cmhlistings} - \texttt{latexindent.pl} ships with a script to help with this process; if you run the - following script, you should be prompted to install the appropriate modules. - \begin{commandshell} -perl latexindent-module-installer.pl -\end{commandshell} - You might also like to see - \href{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}{https://stackoverflow.com/questions/19590042/error-cant-locate-file-homedir-pm-in-inc}, - for example, as well as \vref{sec:requiredmodules}. - -\subsection{About this documentation} - As you read through this documentation, you will see many listings; in this version of - the documentation, there are a total of \totallstlistings. This may seem a lot, but I - deem it necessary in presenting the various different options of \texttt{latexindent.pl} - and the associated output that they are capable of producing. - - The different listings are presented using different styles: - - \begin{minipage}{.4\textwidth} - \cmhlistingsfromfile{demonstrations/demo-tex.tex}{\texttt{demo-tex.tex}}{lst:demo-tex} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.tex} file. - \end{minipage}% - - \begin{minipage}{.4\textwidth} - \cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.yaml} file; when you see line numbers given (as here) - it means that the snippet is taken directly from \texttt{defaultSettings.yaml}, discussed in - detail in \vref{sec:defuseloc}. - \end{minipage}% - - \begin{minipage}{.55\textwidth} - \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.yaml} file, but it will only - be relevant when the \texttt{-m} switch is active; see \vref{sec:modifylinebreaks} - for more details. - \end{minipage}% - - \begin{minipage}{.55\textwidth} - \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} - \end{minipage}% - \hfill - \begin{minipage}{.4\textwidth} - This type of listing is a \texttt{.yaml} file, but it will only - be relevant when the \texttt{-r} switch is active; see \vref{sec:replacements} - for more details. - \end{minipage}% - - % \begin{latexonly} - You will occasionally see dates shown in the margin (for example, next to this - paragraph!) \announce{2017-06-25}{announce} which detail the date of the version in which - the feature was implemented; the `N' stands for `new as of the date shown' and `U' stands - for `updated as of the date shown'. If you see \stardemo, it means that the feature is - either new (N) or updated (U) as of the release of the current version; if you see - \stardemo\, attached to a listing, then it means that listing is new (N) or updated (U) - as of the current version. If you have not read this document before (and even if you - have!), then you can ignore every occurrence of the \stardemo; they are simply there to - highlight new and updated features. The new and updated features in this documentation - (\gitRel) are on the following pages: \listOfNewFeatures% % \end{latexonly} - -\subsection{A word about regular expressions} - \index{regular expressions!a word about} - As you read this documentation, you may encounter the term \emph{regular expressions}. - I've tried to write this documentation in such a way so as to allow you to engage with - them or not, as you prefer. This documentation is not designed to be a guide to regular - expressions, and if you'd like to read about them, I recommend \cite{masteringregexp}. diff --git a/support/latexindent/documentation/sec-references.tex b/support/latexindent/documentation/sec-references.tex deleted file mode 100644 index 97641d40e1..0000000000 --- a/support/latexindent/documentation/sec-references.tex +++ /dev/null @@ -1,16 +0,0 @@ -\nocite{*} -\section{References} - \printbibliography[heading=subbibnumbered,title={perl-related links},keyword=perl] - - \printbibliography[heading=subbibnumbered,title={conda-related links},keyword=conda] - \index{conda} - - \printbibliography[heading=subbibnumbered,title={VScode-related links},keyword=vscode] - \index{VSCode} - - \printbibliography[heading=subbibnumbered,title={Other links},keyword=other] - \index{pre-commit} - \index{MiKTeX} - - \index{contributors} - \printbibliography[env=specialbib,heading=subbibnumbered,title={Contributors (in chronological order)\label{sec:contributors}},keyword=contributor] diff --git a/support/latexindent/documentation/sec-replacements.tex b/support/latexindent/documentation/sec-replacements.tex deleted file mode 100644 index 08468ba295..0000000000 --- a/support/latexindent/documentation/sec-replacements.tex +++ /dev/null @@ -1,407 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\section{The -r, -rv and -rr switches}\label{sec:replacements} - \fancyhead[R]{\bfseries\thepage% - \tikz[remember picture,overlay] { - \node at (1,0){\includegraphics{logo-bw}}; } - } - - You can instruct \texttt{latexindent.pl} to perform replacements/substitutions on your - \announce{2019-07-13}{replacement mode switches} file by using any of the \texttt{-r}, - \texttt{-rv} or \texttt{-rr} switches: \index{verbatim!rv, replacementrespectverb switch} - \begin{itemize} - \item the \texttt{-r} switch will perform indentation and replacements, not respecting verbatim - code blocks; - \item the \texttt{-rv} switch will perform indentation and replacements, and \emph{will} - respect verbatim code blocks; - \item the \texttt{-rr} switch will \emph{not} perform indentation, and will perform - replacements not respecting verbatim code blocks. - \end{itemize} - - We will demonstrate each of the \texttt{-r}, \texttt{-rv} and \texttt{-rr} switches, but - a summary is given in \cref{tab:replacementswitches}. - - \begin{table}[!htb] - \centering - \caption{The replacement mode switches}\label{tab:replacementswitches} - \begin{tabular}{rcc} - \toprule - switch & indentation? & respect verbatim? \\ - \midrule - \texttt{-r} & \faCheck & \faClose \\ - \texttt{-rv} & \faCheck & \faCheck \\ - \texttt{-rr} & \faClose & \faClose \\ - \bottomrule - \end{tabular} - \end{table} - - The default value of the \texttt{replacements} field is shown in \cref{lst:replacements}; - as with all of the other fields, you are encouraged to customise and change this as you - see fit. The options in this field will \emph{only} be considered if the \texttt{-r}, - \texttt{-rv} or \texttt{-rr} switches are active; when discussing YAML settings related - to the replacement-mode switches, we will use the style given in \cref{lst:replacements}. - - \cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements} - - The first entry within the \texttt{replacements} field is \texttt{amalgamate}, and is - \emph{optional}; by default it is set to 1, so that replacements will be amalgamated from - each settings file that you specify. As you'll see in the demonstrations that follow, - there is no need to specify this field. - - You'll notice that, by default, there is only \emph{one} entry in the - \texttt{replacements} field, but it can take as many entries as you would like; each one - needs to begin with a \texttt{-} on its own line. - -\subsection{Introduction to replacements} - Let's explore the action of the default settings, and then we'll demonstrate the feature - with further examples. With reference to \cref{lst:replacements}, the default action will - replace every instance of the text \texttt{latexindent.pl} with \texttt{pl.latexindent}. - - Beginning with the code in \cref{lst:replace1} and running the command \index{switches!-r - demonstration} - \begin{commandshell} -latexindent.pl -r replace1.tex -\end{commandshell} - gives the output given in \cref{lst:replace1-r1}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/replace1.tex}{\texttt{replace1.tex}}{lst:replace1} - \cmhlistingsfromfile{demonstrations/replace1-r1.tex}{\texttt{replace1.tex} default}{lst:replace1-r1} - \end{cmhtcbraster} - - If we don't wish to perform this replacement, then we can tweak the default settings of - \vref{lst:replacements} by changing \texttt{lookForThis} to 0; we perform this action in - \cref{lst:replace1-yaml}, and run the command \index{switches!-l demonstration} - \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r replace1.tex -l=replace1.yaml -\end{commandshell} - which gives the output in \cref{lst:replace1-mod1}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/replace1-mod1.tex}{\texttt{replace1.tex} using \cref{lst:replace1-yaml}}{lst:replace1-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/replace1.yaml}[replace-TCB]{\texttt{replace1.yaml}}{lst:replace1-yaml} - \end{cmhtcbraster} - - Note that in \cref{lst:replace1-yaml} we have specified \texttt{amalgamate} as 0 so that - the default replacements are overwritten. - - We haven't yet discussed the \texttt{when} field; don't worry, we'll get to it as part of - the discussion in what follows. - -\subsection{The two types of replacements} - There are two types of replacements: - \begin{enumerate} - \item \emph{string}-based replacements, which replace the string in - \emph{this} with the string in \emph{that}. - If you specify \texttt{this} and you do not specify \texttt{that}, then the \texttt{that} - field will be assumed to be empty. - \index{regular expressions!replacement switch, -r} - \item \emph{regex}-based replacements, which use the \texttt{substitution} field. - \end{enumerate} - We will demonstrate both in the examples that follow. - - \texttt{latexindent.pl} chooses which type of replacement to make based on which fields - have been specified; if the \texttt{this} field is specified, then it will make - \emph{string}-based replacements, regardless of if \texttt{substitution} is present or - not. - -\subsection{Examples of replacements} - \begin{example} - We begin with code given in \cref{lst:colsep} - - \cmhlistingsfromfile{demonstrations/colsep.tex}{\texttt{colsep.tex}}{lst:colsep} - - Let's assume that our goal is to remove both of the \texttt{arraycolsep} statements; we - can achieve this in a few different ways. - - Using the YAML in \cref{lst:colsep-yaml}, and running the command \index{switches!-l - demonstration} \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r colsep.tex -l=colsep.yaml -\end{commandshell} - then we achieve the output in \cref{lst:colsep-mod0}. - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/colsep-mod0.tex}{\texttt{colsep.tex} using \cref{lst:colsep}}{lst:colsep-mod0} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep.yaml}[replace-TCB]{\texttt{colsep.yaml}}{lst:colsep-yaml} - \end{cmhtcbraster} - Note that in \cref{lst:colsep-yaml}, we have specified \emph{two} separate fields, each - with their own `\emph{this}' field; furthermore, for both of the separate fields, we have - not specified `\texttt{that}', so the \texttt{that} field is assumed to be blank by - \texttt{latexindent.pl}; - - We can make the YAML in \cref{lst:colsep-yaml} more concise by exploring the - \texttt{substitution} field. Using the settings in \cref{lst:colsep1} and running the - command \index{switches!-l demonstration} \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r colsep.tex -l=colsep1.yaml -\end{commandshell} - then we achieve the output in \cref{lst:colsep-mod1}. \index{regular - expressions!substitution field, arraycolsep} \index{regular expressions!at least one +} - \begin{cmhtcbraster}[raster column skip=.01\linewidth, - raster force size=false, - raster column 1/.style={add to width=-.1\textwidth}] - \cmhlistingsfromfile{demonstrations/colsep-mod1.tex}{\texttt{colsep.tex} using \cref{lst:colsep1}}{lst:colsep-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/colsep1.yaml}[replace-TCB,width=0.6\textwidth]{\texttt{colsep1.yaml}}{lst:colsep1} - \end{cmhtcbraster} - - The code given in \cref{lst:colsep1} is an example of a \emph{regular expression}, which - we may abbreviate to \emph{regex} in what follows. This manual is not intended to be a - tutorial on regular expressions; you might like to read, for example, - \cite{masteringregexp} for a detailed covering of the topic. With reference to - \cref{lst:colsep1}, we do note the following: - \begin{itemize} - \item the general form of the \texttt{substitution} field is - \lstinline!s/regex/replacement/modifiers!. You can place any regular expression you like - within this; - \item we have `escaped' the backslash by using \lstinline!\\! - \item we have used \lstinline!\d+! to represent \emph{at least} one digit - \item the \texttt{s} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs - \texttt{latexindent.pl} to treat your file as one single line; - \item the \texttt{g} \emph{modifier} (in the \texttt{sg} at the end of the line) instructs - \texttt{latexindent.pl} to make the substitution \emph{globally} throughout your file; - you might try removing the \texttt{g} modifier from \cref{lst:colsep1} and observing the - difference in output. - \end{itemize} - You might like to see - \href{https://perldoc.perl.org/perlre.html#Modifiers}{https://perldoc.perl.org/perlre.html\#Modifiers} - for details of modifiers; in general, I recommend starting with the \texttt{sg} modifiers - for this feature. - \end{example} - - \begin{example} - We'll keep working with the file in \vref{lst:colsep} for this example. - - Using the YAML in \cref{lst:multi-line}, and running the command \index{switches!-l - demonstration} \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r colsep.tex -l=multi-line.yaml -\end{commandshell} - then we achieve the output in \cref{lst:colsep-mod2}. - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/colsep-mod2.tex}{\texttt{colsep.tex} using \cref{lst:multi-line}}{lst:colsep-mod2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line.yaml}[replace-TCB]{\texttt{multi-line.yaml}}{lst:multi-line} - \end{cmhtcbraster} - With reference to \cref{lst:multi-line}, we have specified a \emph{multi-line} version of - \texttt{this} by employing the \emph{literal} YAML style \lstinline!|-!. See, for - example, - \href{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines}{https://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines} - for further options, all of which can be used in your YAML file. - - This is a natural point to explore the \texttt{when} field, specified in - \vref{lst:replacements}. This field can take two values: \emph{before} and \emph{after}, - which respectively instruct \texttt{latexindent.pl} to perform the replacements - \emph{before} indentation or \emph{after} it. The default value is \texttt{before}. - - Using the YAML in \cref{lst:multi-line1}, and running the command \index{switches!-l - demonstration} \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r colsep.tex -l=multi-line1.yaml -\end{commandshell} - then we achieve the output in \cref{lst:colsep-mod3}. - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/colsep-mod3.tex}{\texttt{colsep.tex} using \cref{lst:multi-line1}}{lst:colsep-mod3} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/multi-line1.yaml}[replace-TCB]{\texttt{multi-line1.yaml}}{lst:multi-line1} - \end{cmhtcbraster} - We note that, because we have specified \texttt{when: after}, that - \texttt{latexindent.pl} has not found the string specified in \cref{lst:multi-line1} - within the file in \vref{lst:colsep}. As it has looked for the string within - \cref{lst:multi-line1} \emph{after} the indentation has been performed. After - indentation, the string as written in \cref{lst:multi-line1} is no longer part of the - file, and has therefore not been replaced. - - As a final note on this example, if you use the \texttt{-rr} switch, as follows, - \index{switches!-l demonstration} \index{switches!-rr demonstration} - \begin{commandshell} -latexindent.pl -rr colsep.tex -l=multi-line1.yaml -\end{commandshell} - then the \texttt{when} field is ignored, no indentation is done, and the output is as in - \cref{lst:colsep-mod2}. - \end{example} - - \begin{example} - An important part of the substitution routine is in \emph{capture groups}. - - Assuming that we start with the code in \cref{lst:displaymath}, let's assume that our - goal is to replace each occurrence of \lstinline!$$...$$! with - \lstinline!\begin{equation*}...\end{equation*}!. This example is partly motivated by - \href{https://tex.stackexchange.com/questions/242150/good-looking-latex-code}{tex - stackexchange question 242150}. - - \cmhlistingsfromfile{demonstrations/displaymath.tex}{\texttt{displaymath.tex}}{lst:displaymath} - - We use the settings in \cref{lst:displaymath1} and run the command \index{switches!-l - demonstration} \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r displaymath.tex -l=displaymath1.yaml -\end{commandshell} - to receive the output given in \cref{lst:displaymath-mod1}. \index{regular - expressions!substitution field, equation} - - \begin{cmhtcbraster}[raster left skip=-3.75cm, - raster right skip=-2cm,] - \cmhlistingsfromfile{demonstrations/displaymath-mod1.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1}}{lst:displaymath-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displaymath1.yaml}[replace-TCB]{\texttt{displaymath1.yaml}}{lst:displaymath1} - \end{cmhtcbraster} - - A few notes about \cref{lst:displaymath1}: - \begin{enumerate} - \item we have used the \texttt{x} modifier, which allows us to have white space within the - regex; - \item we have used a capture group, \lstinline!(.*?)! which captures the content between the - \lstinline!$$...$$! into the special variable, \lstinline!$1!; - \item we have used the content of the capture group, \lstinline!$1!, in the replacement text. - \end{enumerate} - See - \href{https://perldoc.perl.org/perlre.html#Capture-groups}{https://perldoc.perl.org/perlre.html\#Capture-groups} - for a discussion of capture groups. - - The features of the replacement switches can, of course, be combined with others from the - toolkit of \texttt{latexindent.pl}. For example, we can combine the poly-switches of - \vref{sec:poly-switches}, which we do in \cref{lst:equation}; upon running the command - \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-r - demonstration} - \begin{commandshell} -latexindent.pl -r -m displaymath.tex -l=displaymath1.yaml,equation.yaml -\end{commandshell} - then we receive the output in \cref{lst:displaymath-mod2}. - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-.1\textwidth}, - raster column skip=.06\linewidth] - \cmhlistingsfromfile{demonstrations/displaymath-mod2.tex}{\texttt{displaymath.tex} using \cref{lst:displaymath1,lst:equation}}{lst:displaymath-mod2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/equation.yaml}[MLB-TCB,width=0.55\textwidth]{\texttt{equation.yaml}}{lst:equation} - \end{cmhtcbraster} - \end{example} - - \begin{example} - This example is motivated by - \href{https://tex.stackexchange.com/questions/490086/bring-several-lines-together-to-fill-blank-spaces-in-texmaker}{tex - stackexchange question 490086}. We begin with the code in \cref{lst:phrase}. - - \cmhlistingsfromfile{demonstrations/phrase.tex}{\texttt{phrase.tex}}{lst:phrase} - - Our goal is to make the spacing uniform between the phrases. To achieve this, we employ - the settings in \cref{lst:hspace}, and run the command \index{switches!-l demonstration} - \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r phrase.tex -l=hspace.yaml -\end{commandshell} - which gives the output in \cref{lst:phrase-mod1}. \index{regular expressions!at least one - +} \index{regular expressions!horizontal space \textbackslash{h}} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/phrase-mod1.tex}{\texttt{phrase.tex} using \cref{lst:hspace}}{lst:phrase-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/hspace.yaml}[replace-TCB]{\texttt{hspace.yaml}}{lst:hspace} - \end{cmhtcbraster} - - The \lstinline!\h+! setting in \cref{lst:hspace} say to replace \emph{at least one - horizontal space} with a single space. - \end{example} - - \begin{example} - We begin with the code in \cref{lst:references}. - - \cmhlistingsfromfile{demonstrations/references.tex}{\texttt{references.tex}}{lst:references} - - Our goal is to change each reference so that both the text and the reference are - contained within one hyperlink. We achieve this by employing \cref{lst:reference} and - running the command \index{switches!-l demonstration} \index{switches!-r demonstration} - \begin{commandshell} -latexindent.pl -r references.tex -l=reference.yaml -\end{commandshell} - which gives the output in \cref{lst:references-mod1}. \index{regular - expressions!horizontal space \textbackslash{h}} - - \cmhlistingsfromfile{demonstrations/references-mod1.tex}{\texttt{references.tex} using \cref{lst:reference}}{lst:references-mod1} - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/reference.yaml}[replace-TCB]{\texttt{reference.yaml}}{lst:reference} - - Referencing \cref{lst:reference}, the \lstinline!|! means \emph{or}, we have used - \emph{capture groups}, together with an example of an \emph{optional} pattern, - \lstinline!(?:eq)?!. - \end{example} - - \begin{example} - Let's explore the three replacement mode switches (see \vref{tab:replacementswitches}) in - the context of an example that contains a verbatim code block, \cref{lst:verb1}; we will - use the settings in \cref{lst:verbatim1-yaml}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/verb1.tex}{\texttt{verb1.tex}}{lst:verb1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/verbatim1.yaml}[replace-TCB]{\texttt{verbatim1.yaml}}{lst:verbatim1-yaml} - \end{cmhtcbraster} - - Upon running the following commands, \index{verbatim!comparison with -r and -rr switches} - \index{switches!-l demonstration} \index{switches!-o demonstration} \index{switches!-r - demonstration} \index{switches!-rv demonstration} \index{switches!-rr demonstration} - \begin{commandshell} -latexindent.pl -r verb1.tex -l=verbatim1.yaml -o=+mod1 -latexindent.pl -rv verb1.tex -l=verbatim1.yaml -o=+-rv-mod1 -latexindent.pl -rr verb1.tex -l=verbatim1.yaml -o=+-rr-mod1 -\end{commandshell} - we receive the respective output in \crefrange{lst:verb1-mod1}{lst:verb1-rr-mod1} - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.75cm, - raster right skip=-2cm,] - \cmhlistingsfromfile{demonstrations/verb1-mod1.tex}{\texttt{verb1-mod1.tex}}{lst:verb1-mod1} - \cmhlistingsfromfile{demonstrations/verb1-rv-mod1.tex}{\texttt{verb1-rv-mod1.tex}}{lst:verb1-rv-mod1} - \cmhlistingsfromfile{demonstrations/verb1-rr-mod1.tex}{\texttt{verb1-rr-mod1.tex}}{lst:verb1-rr-mod1} - \end{cmhtcbraster} - \end{example} - - We note that: - \begin{enumerate} - \item in \cref{lst:verb1-mod1} indentation has been performed, and that the replacements - specified in \cref{lst:verbatim1-yaml} have been performed, even within the verbatim code - block; - \item in \cref{lst:verb1-rv-mod1} indentation has been performed, but that the replacements - have \emph{not} been performed within the verbatim environment, because the \texttt{rv} - switch is active; - \item in \cref{lst:verb1-rr-mod1} indentation has \emph{not} been performed, but that - replacements have been performed, not respecting the verbatim code block. - \end{enumerate} - See the summary within \vref{tab:replacementswitches}. - - \begin{example} - Let's explore the \texttt{amalgamate} field from \vref{lst:replacements} in the context - of the file specified in \cref{lst:amalg1}. - - \cmhlistingsfromfile{demonstrations/amalg1.tex}{\texttt{amalg1.tex}}{lst:amalg1} - - Let's consider the YAML files given in \crefrange{lst:amalg1-yaml}{lst:amalg3-yaml}. - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.75cm, - raster right skip=-2cm,] - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg1-yaml.yaml}[replace-TCB]{\texttt{amalg1-yaml.yaml}}{lst:amalg1-yaml} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg2-yaml.yaml}[replace-TCB]{\texttt{amalg2-yaml.yaml}}{lst:amalg2-yaml} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalg3-yaml.yaml}[replace-TCB]{\texttt{amalg3-yaml.yaml}}{lst:amalg3-yaml} - \end{cmhtcbraster} - - Upon running the following commands, \index{switches!-l demonstration} \index{switches!-r - demonstration} - \begin{commandshell} -latexindent.pl -r amalg1.tex -l=amalg1-yaml -latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml -latexindent.pl -r amalg1.tex -l=amalg1-yaml,amalg2-yaml,amalg3-yaml -\end{commandshell} - we receive the respective output in \crefrange{lst:amalg1-mod1}{lst:amalg1-mod123}. - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.75cm, - raster right skip=-2cm,] - \cmhlistingsfromfile{demonstrations/amalg1-mod1.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml}}{lst:amalg1-mod1} - \cmhlistingsfromfile{demonstrations/amalg1-mod12.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml}}{lst:amalg1-mod12} - \cmhlistingsfromfile{demonstrations/amalg1-mod123.tex}{\texttt{amalg1.tex} using \cref{lst:amalg1-yaml,lst:amalg2-yaml,lst:amalg3-yaml}}{lst:amalg1-mod123} - \end{cmhtcbraster} - We note that: - \begin{enumerate} - \item in \cref{lst:amalg1-mod1} the replacements from \cref{lst:amalg1-yaml} have been used; - \item in \cref{lst:amalg1-mod12} the replacements from \cref{lst:amalg1-yaml,lst:amalg2-yaml} - have \emph{both} been used, because the default value of \texttt{amalgamate} is 1; - \item in \cref{lst:amalg1-mod123} \emph{only} the replacements from \cref{lst:amalg3-yaml} have - been used, because the value of \texttt{amalgamate} has been set to 0. - \end{enumerate} - \end{example} diff --git a/support/latexindent/documentation/sec-the-line-switch.tex b/support/latexindent/documentation/sec-the-line-switch.tex deleted file mode 100644 index 96fccecb36..0000000000 --- a/support/latexindent/documentation/sec-the-line-switch.tex +++ /dev/null @@ -1,198 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\section{The --lines switch}\label{sec:line-switch} - \texttt{latexindent.pl} - \announce{2021-09-16}{line switch demonstration} can - operate on a \emph{selection} of lines of the file using the \texttt{--lines} or - \texttt{-n} switch. - - \index{switches!-lines demonstration} - - The basic syntax is \texttt{--lines MIN-MAX}, so for example - \begin{commandshell} -latexindent.pl --lines 3-7 myfile.tex -latexindent.pl -n 3-7 myfile.tex -\end{commandshell} - will only operate upon lines 3 to 7 in \texttt{myfile.tex}. All of the other lines will - \emph{not} be operated upon by \texttt{latexindent.pl}. - - The options for the \texttt{lines} switch are: - \begin{itemize} - \item line range, as in \texttt{--lines 3-7} - \item single line, as in \texttt{--lines 5} - \item multiple line ranges separated by commas, as in \texttt{--lines 3-5,8-10} - \item negated line ranges, as in \texttt{--lines !3-5} which translates to \texttt{--lines - 1-2,6-N}, where N is the number of lines in your file. - \end{itemize} - - We demonstrate this feature, and the available variations in what follows. We will use - the file in \cref{lst:myfile}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile.tex}[tex-TCB]{\texttt{myfile.tex}}{lst:myfile} - - \begin{example} - We demonstrate the basic usage using the command - \begin{commandshell} -latexindent.pl --lines 3-7 myfile.tex -o=+-mod1 -\end{commandshell} - which instructs \texttt{latexindent.pl} to only operate on lines 3 to 7; the output is - given in \cref{lst:myfile-mod1}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod1.tex}[tex-TCB]{\texttt{myfile-mod1.tex}}{lst:myfile-mod1} - - The following two calls to \texttt{latexindent.pl} are equivalent - \begin{commandshell} -latexindent.pl --lines 3-7 myfile.tex -o=+-mod1 -latexindent.pl --lines 7-3 myfile.tex -o=+-mod1 -\end{commandshell} - as \texttt{latexindent.pl} performs a check to put the lowest number first. - \end{example} - - \begin{example} - You can call the \texttt{lines} switch with only \emph{one number} and in which case only - that line will be operated upon. For example - \begin{commandshell} -latexindent.pl --lines 5 myfile.tex -o=+-mod2 -\end{commandshell} - instructs \texttt{latexindent.pl} to only operate on line 5; the output is given in - \cref{lst:myfile-mod2}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod2.tex}[tex-TCB]{\texttt{myfile-mod2.tex}}{lst:myfile-mod2} - - The following two calls are equivalent: - \begin{commandshell} -latexindent.pl --lines 5 myfile.tex -latexindent.pl --lines 5-5 myfile.tex -\end{commandshell} - \end{example} - - \begin{example} - If you specify a value outside of the line range of the file then \texttt{latexindent.pl} - will ignore the \texttt{lines} argument, detail as such in the log file, and proceed to - operate on the entire file. - - For example, in the following call - \begin{commandshell} -latexindent.pl --lines 11-13 myfile.tex - \end{commandshell} - \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because \cref{lst:myfile} only has 12 lines. - - Similarly, in the call - \begin{commandshell} -latexindent.pl --lines -1-3 myfile.tex - \end{commandshell} - \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the entire file} because we assume that negatively numbered - lines in a file do not exist. - \end{example} - - \begin{example} - You can specify \emph{multiple line ranges} as in the following - \begin{commandshell} -latexindent.pl --lines 3-5,8-10 myfile.tex -o=+-mod3 -\end{commandshell} - which instructs \texttt{latexindent.pl} to operate upon lines 3 to 5 and lines 8 to 10; - the output is given in \cref{lst:myfile-mod3}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod3.tex}[tex-TCB]{\texttt{myfile-mod3.tex}}{lst:myfile-mod3} - - The following calls to \texttt{latexindent.pl} are all equivalent - \begin{commandshell} -latexindent.pl --lines 3-5,8-10 myfile.tex -latexindent.pl --lines 8-10,3-5 myfile.tex -latexindent.pl --lines 10-8,3-5 myfile.tex -latexindent.pl --lines 10-8,5-3 myfile.tex -\end{commandshell} - as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and - within each line range, it puts the lowest number first. - \end{example} - - \begin{example} - There's no limit to the number of line ranges that you can specify, they just need to be - separated by commas. For example - \begin{commandshell} -latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex -o=+-mod4 -\end{commandshell} - has four line ranges: lines 1 to 2, lines 4 to 5, lines 9 to 10 and line 12. The output - is given in \cref{lst:myfile-mod4}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod4.tex}[tex-TCB]{\texttt{myfile-mod4.tex}}{lst:myfile-mod4} - - As previously, the ordering does not matter, and the following calls to - \texttt{latexindent.pl} are all equivalent - \begin{commandshell} -latexindent.pl --lines 1-2,4-5,9-10,12 myfile.tex -latexindent.pl --lines 2-1,4-5,9-10,12 myfile.tex -latexindent.pl --lines 4-5,1-2,9-10,12 myfile.tex -latexindent.pl --lines 12,4-5,1-2,9-10 myfile.tex -\end{commandshell} - as \texttt{latexindent.pl} performs a check to put the lowest line ranges first, and - within each line range, it puts the lowest number first. - \end{example} - - \begin{example} - \index{switches!-lines demonstration, negation} - You can specify \emph{negated line ranges} by using \texttt{!} as in - \begin{commandshell} -latexindent.pl --lines !5-7 myfile.tex -o=+-mod5 -\end{commandshell} - which instructs \texttt{latexindent.pl} to operate upon all of the lines \emph{except} - lines 5 to 7. - - In other words, \texttt{latexindent.pl} \emph{will} operate on lines 1 to 4, and 8 to 12, - so the following two calls are equivalent: - \begin{commandshell} -latexindent.pl --lines !5-7 myfile.tex -latexindent.pl --lines 1-4,8-12 myfile.tex -\end{commandshell} - The output is given in \cref{lst:myfile-mod5}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod5.tex}[tex-TCB]{\texttt{myfile-mod5.tex}}{lst:myfile-mod5} - - \end{example} - - \begin{example} - \index{switches!-lines demonstration, negation} - You can specify \emph{multiple negated line ranges} such as - \begin{commandshell} -latexindent.pl --lines !5-7,!9-10 myfile.tex -o=+-mod6 - \end{commandshell} - which is equivalent to: - \begin{commandshell} -latexindent.pl --lines 1-4,8,11-12 myfile.tex -o=+-mod6 - \end{commandshell} - The output is given in \cref{lst:myfile-mod6}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile-mod6.tex}[tex-TCB]{\texttt{myfile-mod6.tex}}{lst:myfile-mod6} - \end{example} - - \begin{example} - If you specify a line range with anything other than an integer, then - \texttt{latexindent.pl} will ignore the \texttt{lines} argument, and \emph{operate on the - entire file}. - - Sample calls that result in the \texttt{lines} argument being ignored include the - following: - \begin{commandshell} -latexindent.pl --lines 1-x myfile.tex -latexindent.pl --lines !y-3 myfile.tex - \end{commandshell} - \end{example} - - \begin{example} - We can, of course, use the \texttt{lines} switch in combination with other switches. - - For example, let's use with the file in \cref{lst:myfile1}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1.tex}[tex-TCB]{\texttt{myfile1.tex}}{lst:myfile1} - - We can demonstrate interaction with the \texttt{-m} switch (see - \vref{sec:modifylinebreaks}); in particular, if we use \vref{lst:mlb2}, - \vref{lst:env-mlb7} and \vref{lst:env-mlb8} and run - \begin{widepage} - \begin{commandshell} -latexindent.pl --lines 6 myfile1.tex -o=+-mod1 -m -l env-mlb2,env-mlb7,env-mlb8 -o=+-mod1 - \end{commandshell} - \end{widepage} - then we receive the output in \cref{lst:myfile1-mod1}. - - \cmhlistingsfromfile[style=lineNumbersTeX]{demonstrations/myfile1-mod1.tex}[tex-TCB]{\texttt{myfile1-mod1.tex}}{lst:myfile1-mod1} - \end{example} diff --git a/support/latexindent/documentation/sec-the-m-switch.tex b/support/latexindent/documentation/sec-the-m-switch.tex deleted file mode 100644 index 9e15c59387..0000000000 --- a/support/latexindent/documentation/sec-the-m-switch.tex +++ /dev/null @@ -1,60 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\renewcommand{\imagetouse}{logo} -\section{The -m (modifylinebreaks) switch}\label{sec:modifylinebreaks} - \fancyhead[R]{\bfseries\thepage% - \tikz[remember picture,overlay] { - \node at (1,0){\includegraphics{logo}}; - }} - All features described in this section will only be relevant if the \texttt{-m} switch is - used. - - \startcontents[the-m-switch] - \printcontents[the-m-switch]{}{0}{} - -\yamltitle{modifylinebreaks}*{fields} - \makebox[0pt][r]{% - \raisebox{-\totalheight}[0pt][0pt]{% - \tikz\node[opacity=1] at (0,0) - {\includegraphics[width=4cm]{logo}};}}% - As of Version 3.0, \texttt{latexindent.pl} has the \texttt{-m} switch, which permits - \texttt{latexindent.pl} to modify line breaks, according to the specifications in the - \texttt{modifyLineBreaks} field. \emph{The settings in this field will only be considered - if the \texttt{-m} switch has been used}. A snippet of the default settings of this field - is shown in \cref{lst:modifylinebreaks}. - - \cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} - - Having read the previous paragraph, it should sound reasonable that, if you call - \texttt{latexindent.pl} using the \texttt{-m} switch, then you give it permission to - modify line breaks in your file, but let's be clear: \index{warning!the m switch} - - \begin{warning} - If you call \texttt{latexindent.pl} with the \texttt{-m} switch, then you are giving it - permission to modify line breaks. By default, the only thing that will happen is that - multiple blank lines will be condensed into one blank line; many other settings are - possible, discussed next. - \end{warning} - -\yamltitle{preserveBlankLines}{0|1} - This field is directly related to \emph{poly-switches}, discussed in - \cref{sec:poly-switches}. By default, it is set to \texttt{1}, which means that blank - lines will be \emph{protected} from removal; however, regardless of this setting, - multiple blank lines can be condensed if \texttt{condenseMultipleBlankLinesInto} is - greater than \texttt{0}, discussed next. - -\yamltitle{condenseMultipleBlankLinesInto}*{positive integer} - Assuming that this switch takes an integer value greater than \texttt{0}, - \texttt{latexindent.pl} will condense multiple blank lines into the number of blank lines - illustrated by this switch. As an example, \cref{lst:mlb-bl} shows a sample file with - blank lines; upon running \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl myfile.tex -m -o=+-mod1 -\end{commandshell} - the output is shown in \cref{lst:mlb-bl-out}; note that the multiple blank lines have - been condensed into one blank line, and note also that we have used the \texttt{-m} - switch! - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/mlb1.tex}{\texttt{mlb1.tex}}{lst:mlb-bl} - \cmhlistingsfromfile{demonstrations/mlb1-out.tex}{\texttt{mlb1-mod1.tex}}{lst:mlb-bl-out} - \end{cmhtcbraster} diff --git a/support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex b/support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex deleted file mode 100644 index 0e8a4591f3..0000000000 --- a/support/latexindent/documentation/subsec-combine-text-wrap-para-line-breaks.tex +++ /dev/null @@ -1,111 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsection{Combining removeParagraphLineBreaks and textWrapOptions}\label{subsec:removeparagraphlinebreaks:and:textwrap} - - The \announce{2018-08-13}{combine text wrap and remove paragraph line breaks} text - wrapping routine (\vref{subsec:textwrapping}) and remove paragraph line breaks routine - (\vref{subsec:removeparagraphlinebreaks}) can be combined.% - - We motivate this feature with the code given in \cref{lst:textwrap7}. - - \cmhlistingsfromfile{demonstrations/textwrap7.tex}{\texttt{textwrap7.tex}}{lst:textwrap7} - - Applying the text wrap routine from \vref{subsec:textwrapping} with, for example, - \vref{lst:textwrap3-yaml} gives the output in \cref{lst:textwrap7-mod3}. - - \cmhlistingsfromfile{demonstrations/textwrap7-mod3.tex}{\texttt{textwrap7.tex} using \cref{lst:textwrap3-yaml}}{lst:textwrap7-mod3} - - The text wrapping routine has behaved as expected, but it may be desired to remove - paragraph line breaks \emph{before} performing the text wrapping routine. The desired - behaviour can be achieved by employing the \texttt{beforeTextWrap} switch. - - Explicitly, using the settings in \cref{lst:textwrap12-yaml} and running the command - \index{switches!-l demonstration} \index{switches!-m demonstration} \index{switches!-o - demonstration} - \begin{commandshell} -latexindent.pl -m textwrap7.tex -l=textwrap12.yaml -o=+-mod12 -\end{commandshell} - we obtain the output in \cref{lst:textwrap7-mod12}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/textwrap7-mod12.tex}{\texttt{textwrap7-mod12.tex}}{lst:textwrap7-mod12} - \cmhlistingsfromfile{demonstrations/textwrap12.yaml}[MLB-TCB]{\texttt{textwrap12.yaml}}{lst:textwrap12-yaml} - \end{cmhtcbraster} - - In \cref{lst:textwrap7-mod12} the paragraph line breaks have first been removed from - \cref{lst:textwrap7}, and then the text wrapping routine has been applied. It is - envisaged that variants of \cref{lst:textwrap12-yaml} will be among the most useful - settings for these two features. - -\subsubsection{text wrapping beforeFindingChildCodeBlocks}\label{subsubsec:text-wrap-remove-para-bfccb} - - \index{text wrap!recommended starting point} - - I \announce{2021-07-31}{textWrapOptions new feature: beforeFindingChildCodeBlocks} think - it likely that most users will wish to employ the \texttt{beforeFindingChildCodeBlocks} - option for the text wrap routine.% - - To motivate its use, we begin with the file in \cref{lst:textwrap-bfccb}. - - \cmhlistingsfromfile{demonstrations/textwrap-bfccb.tex}{\texttt{textwrap-bfccb.tex}}{lst:textwrap-bfccb} - - Using the settings in \cref{lst:textwrap12-yaml} and running - \begin{commandshell} -latexindent.pl -m textwrap-bfccb.tex -l=textwrap12.yaml -o=+-mod12 -\end{commandshell} - gives the output in \cref{lst:textwrap-bfccb-mod12} - - \cmhlistingsfromfile{demonstrations/textwrap-bfccb-mod12.tex}{\texttt{textwrap-bfccb-mod12.tex}}{lst:textwrap-bfccb-mod12} - - Note that we have added a `ruler' to \cref{lst:textwrap-bfccb-mod12} to assist with - measuring. - - The output in \cref{lst:textwrap-bfccb-mod12} is not ideal, but it is \emph{expected}. - The reasoning is as follows: - \begin{itemize} - \item \texttt{latexindent.pl} first of all searches for code blocks (see - \vref{tab:code-blocks}); - \item it replaces each code block with a unique identifying string; - \item with the settings of \cref{lst:textwrap12-yaml} in place, it performs the paragraph line - break removal, and then the text wrapping routine first of all on the \texttt{text} - command, and then on the surrounding text; - \item the surrounding text does not know that \texttt{text} is a command. - \end{itemize} - - We can instruct \texttt{latexindent.pl} to perform text wrapping \emph{before searching - for child code blocks} by using the \texttt{beforeFindingChildCodeBlocks} field. - - We save the \emph{quick-start} settings from \cref{lst:textwrap-qs-yaml} into - \cref{lst:textwrap13-yaml} and change the value of \texttt{columns} for demonstration. - Upon running the command - \begin{commandshell} -latexindent.pl -m textwrap-bfccb.tex -l=textwrap13.yaml -o=+-mod13 -\end{commandshell} - we receive the output in \cref{lst:textwrap-bfccb-mod13}. - - \cmhlistingsfromfile{demonstrations/textwrap13.yaml}[MLB-TCB,width=\linewidth]{\texttt{textwrap13.yaml} (tweaked quick start)}{lst:textwrap13-yaml} - - \cmhlistingsfromfile{demonstrations/textwrap-bfccb-mod13.tex}{\texttt{textwrap-bfccb-mod13.tex}}{lst:textwrap-bfccb-mod13} - - This output is different from \cref{lst:textwrap-bfccb-mod12}, but is still not ideal, as - the \texttt{test} command has indented its mandatory argument. We can employ - \texttt{noAdditionalIndent} from \vref{sec:noadd-indent-rules} in - \cref{lst:textwrap14-yaml} and run the command - \begin{commandshell} -latexindent.pl -m textwrap-bfccb.tex -l=textwrap14.yaml -o=+-mod14 -\end{commandshell} - to receive the output in \cref{lst:textwrap-bfccb-mod14}. - - \begin{widepage} - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/textwrap-bfccb-mod14.tex}{\texttt{textwrap-bfccb-mod14.tex}}{lst:textwrap-bfccb-mod14} - \cmhlistingsfromfile{demonstrations/textwrap14.yaml}[MLB-TCB]{\texttt{textwrap14.yaml}}{lst:textwrap14-yaml} - \end{cmhtcbraster} - \end{widepage} - - For reference, let's say that we had started from \cref{lst:textwrap12-yaml}, which - instructs \texttt{latexindent.pl} to apply the text-wrapping and - paragraph-line-break-removal routines to \emph{all} code blocks. In order to achieve the - output in \cref{lst:textwrap-bfccb-mod14}, then we would need to employ an exception, - which we demonstrate in \cref{lst:textwrap15-yaml}. - - \cmhlistingsfromfile{demonstrations/textwrap15.yaml}[MLB-TCB]{\texttt{textwrap15.yaml}}{lst:textwrap15-yaml} diff --git a/support/latexindent/documentation/subsec-commands-and-their-options.tex b/support/latexindent/documentation/subsec-commands-and-their-options.tex deleted file mode 100644 index ff44ad229e..0000000000 --- a/support/latexindent/documentation/subsec-commands-and-their-options.tex +++ /dev/null @@ -1,251 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsection{Commands and the strings between their arguments}\label{subsec:commands-string-between} The \texttt{command} code blocks will - always look for optional (square bracketed) and mandatory (curly braced) arguments which - can contain comments, line breaks and `beamer' commands \lstinline!<.*?>! between them. - There are switches that can allow them to contain other strings, which we discuss next. - -\yamltitle{commandCodeBlocks}*{fields} - - The \texttt{commandCodeBlocks} field \announce{2018-04-27}*{commandCodeBlocks} contains a - few switches detailed in \cref{lst:commandCodeBlocks}.% - - \cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} - -\yamltitle{roundParenthesesAllowed}{0|1} - - The need for this field was mostly motivated by commands found in code used to generate - images in \texttt{PSTricks} and \texttt{tikz}; for example, let's consider the code given - in \cref{lst:pstricks1}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/pstricks1.tex}{\texttt{pstricks1.tex}}{lst:pstricks1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/pstricks1-default.tex}{\texttt{pstricks1} default output}{lst:pstricks1-default} - \end{minipage} - - Notice that the \lstinline!\defFunction! command has an optional argument, followed by a - mandatory argument, followed by a round-parenthesis argument, $(u,v)$. - - By default, because \texttt{roundParenthesesAllowed} is set to $1$ in - \cref{lst:commandCodeBlocks}, then \texttt{latexindent.pl} will allow round parenthesis - between optional and mandatory arguments. In the case of the code in - \cref{lst:pstricks1}, \texttt{latexindent.pl} finds \emph{all} the arguments of - \lstinline!defFunction!, both before and after \lstinline!(u,v)!. - - The default output from running \texttt{latexindent.pl} on \cref{lst:pstricks1} actually - leaves it unchanged (see \cref{lst:pstricks1-default}); note in particular, this is - because of \texttt{noAdditionalIndentGlobal} as discussed on - \cpageref{page:command:noAddGlobal}. - - Upon using the YAML settings in \cref{lst:noRoundParentheses}, and running the command - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl pstricks1.tex -l noRoundParentheses.yaml -\end{commandshell} - we obtain the output given in \cref{lst:pstricks1-nrp}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/pstricks1-nrp.tex}{\texttt{pstricks1.tex} using \cref{lst:noRoundParentheses}}{lst:pstricks1-nrp} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/noRoundParentheses.yaml}[yaml-TCB]{\texttt{noRoundParentheses.yaml}}{lst:noRoundParentheses} - \end{cmhtcbraster} - - Notice the difference between \cref{lst:pstricks1-default} and \cref{lst:pstricks1-nrp}; - in particular, in \cref{lst:pstricks1-nrp}, because round parentheses are \emph{not} - allowed, \texttt{latexindent.pl} finds that the \lstinline!\defFunction! command finishes - at the first opening round parenthesis. As such, the remaining braced, mandatory, - arguments are found to be \texttt{UnNamedGroupingBracesBrackets} (see - \vref{tab:code-blocks}) which, by default, assume indentation for their body, and hence - the tabbed indentation in \cref{lst:pstricks1-nrp}. - - Let's explore this using the YAML given in \cref{lst:defFunction} and run the command - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl pstricks1.tex -l defFunction.yaml -\end{commandshell} - then the output is as in \cref{lst:pstricks1-indent-rules}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/pstricks1-indent-rules.tex}{\texttt{pstricks1.tex} using \cref{lst:defFunction}}{lst:pstricks1-indent-rules} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/defFunction.yaml}[yaml-TCB]{\texttt{defFunction.yaml}}{lst:defFunction} - \end{cmhtcbraster} - - Notice in \cref{lst:pstricks1-indent-rules} that the \emph{body} of the - \lstinline!defFunction! command i.e, the subsequent lines containing arguments after the - command name, have received the single space of indentation specified by - \cref{lst:defFunction}. - -\yamltitle{stringsAllowedBetweenArguments}*{fields} - \texttt{tikz} users may well specify code such as that given in - \cref{lst:tikz-node1}; processing this code using - \texttt{latexindent.pl} gives the default output in \cref{lst:tikz-node1-default}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1.tex}{\texttt{tikz-node1.tex}}{lst:tikz-node1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[columns=fixed]{demonstrations/tikz-node1-default.tex}{\texttt{tikz-node1} default output}{lst:tikz-node1-default} - \end{minipage} - - With reference to \vref{lst:commandCodeBlocks}, we see that the strings - \begin{quote} - to, node, ++ - \end{quote} - are all allowed to appear between arguments; importantly, you are encouraged to add - further names to this field as necessary. This means that when \texttt{latexindent.pl} - processes \cref{lst:tikz-node1}, it consumes: - \begin{itemize} - \item the optional argument \lstinline![thin]! - \item the round-bracketed argument \lstinline!(c)! because \texttt{roundParenthesesAllowed} is - $1$ by default - \item the string \lstinline!to! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the optional argument \lstinline![in=110,out=-90]! - \item the string \lstinline!++! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the round-bracketed argument \lstinline!(0,-0.5cm)! because - \texttt{roundParenthesesAllowed} is $1$ by default - \item the string \lstinline!node! (specified in \texttt{stringsAllowedBetweenArguments}) - \item the optional argument \lstinline![below,align=left,scale=0.5]! - \end{itemize} - - We can explore this further, for example using \cref{lst:draw} and running the command - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl tikz-node1.tex -l draw.yaml -\end{commandshell} - we receive the output given in \cref{lst:tikz-node1-draw}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/tikz-node1-draw.tex}{\texttt{tikz-node1.tex} using \cref{lst:draw}}{lst:tikz-node1-draw} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/draw.yaml}[yaml-TCB]{\texttt{draw.yaml}}{lst:draw} - \end{cmhtcbraster} - - Notice that each line after the \lstinline!\draw! command (its `body') in - \cref{lst:tikz-node1-draw} has been given the appropriate two-spaces worth of indentation - specified in \cref{lst:draw}. - - Let's compare this with the output from using the YAML settings in \cref{lst:no-strings}, - and running the command \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl tikz-node1.tex -l no-strings.yaml -\end{commandshell} - given in \cref{lst:tikz-node1-no-strings}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/tikz-node1-no-strings.tex}{\texttt{tikz-node1.tex} using \cref{lst:no-strings}}{lst:tikz-node1-no-strings} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-strings.yaml}[yaml-TCB]{\texttt{no-strings.yaml}}{lst:no-strings} - \end{cmhtcbraster} - - In this case, \texttt{latexindent.pl} sees that: - \begin{itemize} - \item the \lstinline!\draw! command finishes after the \lstinline!(c)!, as - \texttt{stringsAllowedBetweenArguments} has been set to $0$ so there are no strings - allowed between arguments; - \item it finds a \texttt{namedGroupingBracesBrackets} called \texttt{to} (see - \vref{tab:code-blocks}) \emph{with} argument \lstinline![in=110,out=-90]! - \item it finds another \texttt{namedGroupingBracesBrackets} but this time called \texttt{node} - with argument \lstinline![below,align=left,scale=0.5]! - \end{itemize} - - Referencing \vref{lst:commandCodeBlocks}, \announce{2018-04-27}*{amalgamate feature in - commandCodeBlocks}, we see that the first field in the - \texttt{stringsAllowedBetweenArguments} is \texttt{amalgamate} and is set to \texttt{1} - by default. This is for users who wish to specify their settings in multiple YAML files. - For example, by using the settings in either \cref{lst:amalgamate-demo} - or\cref{lst:amalgamate-demo1} is equivalent to using the settings in - \cref{lst:amalgamate-demo2}.% - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo.yaml}[yaml-TCB]{\texttt{amalgamate-demo.yaml}}{lst:amalgamate-demo} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo1.yaml}[yaml-TCB]{\texttt{amalgamate-demo1.yaml}}{lst:amalgamate-demo1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo2.yaml}[yaml-TCB]{\texttt{amalgamate-demo2.yaml}}{lst:amalgamate-demo2} - \end{cmhtcbraster} - - We specify \texttt{amalgamate} to be set to \texttt{0} and in which case any settings - loaded prior to those specified, including the default, will be overwritten. For example, - using the settings in \cref{lst:amalgamate-demo3} means that only the strings specified - in that field will be used. - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/amalgamate-demo3.yaml}[yaml-TCB]{\texttt{amalgamate-demo3.yaml}}{lst:amalgamate-demo3} - - It is important to note that the \texttt{amalgamate} field, if used, must be in the first - field, and specified using the syntax given in - \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. - - We may explore this feature further with the code in \cref{lst:for-each}, whose default - output is given in \cref{lst:for-each-default}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/for-each.tex}{\texttt{for-each.tex}}{lst:for-each} - \cmhlistingsfromfile{demonstrations/for-each-default.tex}{\texttt{for-each} default output}{lst:for-each-default} - \end{cmhtcbraster} - - Let's compare this with the output from using the YAML settings in \cref{lst:foreach}, - and running the command \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl for-each.tex -l foreach.yaml -\end{commandshell} - given in \cref{lst:for-each-mod1}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/for-each-mod1.tex}{\texttt{for-each.tex} using \cref{lst:foreach}}{lst:for-each-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/foreach.yaml}[yaml-TCB]{\texttt{foreach.yaml}}{lst:foreach} - \end{cmhtcbraster} - - You might like to compare the output given in \cref{lst:for-each-default} and - \cref{lst:for-each-mod1}. Note,in particular, in \cref{lst:for-each-default} that the - \texttt{foreach} command has not included any of the subsequent strings, and that the - braces have been treated as a \texttt{namedGroupingBracesBrackets}. In - \cref{lst:for-each-mod1} the \texttt{foreach} command has been allowed to have - \lstinline!\x/\y! and \texttt{in} between arguments because of the settings given in - \cref{lst:foreach}. - -\yamltitle{commandNameSpecial}*{fields} - There are some special command names \announce{2018-04-27}*{commandNameSpecial} that do - not fit within the names recognised by \texttt{latexindent.pl}, the first one of which is - \lstinline!\@ifnextchar[!. From the perspective of \texttt{latexindent.pl}, the whole of - the text \lstinline!\@ifnextchar[! is a command, because it is immediately followed by - sets of mandatory arguments. However, without the \texttt{commandNameSpecial} field, - \texttt{latexindent.pl} would not be able to label it as such, because the \lstinline![! - is, necessarily, not matched by a closing \lstinline!]!.% - - For example, consider the sample file in \cref{lst:ifnextchar}, which has default output - in \cref{lst:ifnextchar-default}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/ifnextchar.tex}{\texttt{ifnextchar.tex}}{lst:ifnextchar} - \cmhlistingsfromfile{demonstrations/ifnextchar-default.tex}{\texttt{ifnextchar.tex} default output}{lst:ifnextchar-default} - \end{cmhtcbraster} - - Notice that in \cref{lst:ifnextchar-default} the \texttt{parbox} command has been able to - indent its body, because \texttt{latexindent.pl} has successfully found the command - \lstinline!\@ifnextchar! first; the pattern-matching of \texttt{latexindent.pl} starts - from \emph{the inner most and works outwards}, discussed in more detail on - \cpageref{page:phases}. - - For demonstration, we can compare this output with that given in - \cref{lst:ifnextchar-off} in which the settings from \cref{lst:no-ifnextchar} have - dictated that no special command names, including the \lstinline!\@ifnextchar[! command, - should not be searched for specially; as such, the \texttt{parbox} command has been - \emph{unable} to indent its body successfully, because the \lstinline!\@ifnextchar[! - command has not been found. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/ifnextchar-off.tex}{\texttt{ifnextchar.tex} using \cref{lst:no-ifnextchar}}{lst:ifnextchar-off} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/no-ifnextchar.yaml}[yaml-TCB]{\texttt{no-ifnextchar.yaml}}{lst:no-ifnextchar} - \end{cmhtcbraster} - - The \texttt{amalgamate} field can be used for \texttt{commandNameSpecial}, just as for - \texttt{stringsAllowedBetweenArguments}. The same condition holds as stated previously, - which we state again here: \index{warning!amalgamate field} - - \begin{warning} - It is important to note that the \texttt{amalgamate} field, if used, in either - \texttt{commandNameSpecial} or \texttt{stringsAllowedBetweenArguments} must be in the - first field, and specified using the syntax given in - \cref{lst:amalgamate-demo1,lst:amalgamate-demo2,lst:amalgamate-demo3}. - \end{warning} diff --git a/support/latexindent/documentation/subsec-noAdditionalIndent-indentRules.tex b/support/latexindent/documentation/subsec-noAdditionalIndent-indentRules.tex deleted file mode 100644 index ec0e699aaa..0000000000 --- a/support/latexindent/documentation/subsec-noAdditionalIndent-indentRules.tex +++ /dev/null @@ -1,36 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -% arara: pdflatex: { files: [latexindent]} -\index{indentation!no additional indent} -\index{indentation!removing indentation per-code block} -\index{indentation!customising indentation per-code block} -\index{indentation!customising per-name} -\index{indentation!no additional indent global} -\subsection{noAdditionalIndent and indentRules}\label{sec:noadd-indent-rules} - \texttt{latexindent.pl} operates on files by looking for code blocks, as detailed in - \vref{subsubsec:code-blocks}; - for each type of code block in \vref{tab:code-blocks} (which we will call a - \emph{$\langle$thing$\rangle$} in what follows) it searches YAML fields for information - in the following order: - \begin{enumerate} - \item \texttt{noAdditionalIndent} for the \emph{name} of the current - \emph{$\langle$thing$\rangle$}; - \item \texttt{indentRules} for the \emph{name} of the current \emph{$\langle$thing$\rangle$}; - \item \texttt{noAdditionalIndentGlobal} for the \emph{type} of the current - \emph{$\langle$thing$\rangle$}; - \item \texttt{indentRulesGlobal} for the \emph{type} of the current - \emph{$\langle$thing$\rangle$}. - \end{enumerate} - - Using the above list, the first piece of information to be found will be used; failing - that, the value of \texttt{defaultIndent} is used. If information is found in multiple - fields, the first one according to the list above will be used; for example, if - information is present in both \texttt{indentRules} and in - \texttt{noAdditionalIndentGlobal}, then the information from \texttt{indentRules} takes - priority. - - We now present details for the different type of code blocks known to - \texttt{latexindent.pl}, as detailed in \vref{tab:code-blocks}; for reference, there - follows a list of the code blocks covered. - - \startcontents[noAdditionalIndent] - \printcontents[noAdditionalIndent]{}{0}{} diff --git a/support/latexindent/documentation/subsec-one-sentence-per-line.tex b/support/latexindent/documentation/subsec-one-sentence-per-line.tex deleted file mode 100644 index 352697735f..0000000000 --- a/support/latexindent/documentation/subsec-one-sentence-per-line.tex +++ /dev/null @@ -1,380 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsection{oneSentencePerLine: modifying line breaks for sentences}\label{sec:onesentenceperline} - - You can instruct \texttt{latexindent.pl} to format \announce{2018-01-13}{one sentence per - line} your file so that it puts one sentence per line. Thank you to \cite{mlep} for - helping to shape and test this feature. The behaviour of this part of the script is - controlled by the switches detailed in \cref{lst:oneSentencePerLine}, all of which we - discuss next. \index{modifying linebreaks! by using one sentence per line} - \index{sentences!oneSentencePerLine} \index{sentences!one sentence per line} - \index{regular expressions!lowercase alph a-z} \index{regular expressions!uppercase alph - A-Z}% - - \cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} - -\yamltitle{manipulateSentences}{0|1} - This is a binary switch that details if \texttt{latexindent.pl} should perform the - sentence manipulation routine; it is \emph{off} (set to \texttt{0}) by default, and you - will need to turn it on (by setting it to \texttt{1}) if you want the script to modify - line breaks surrounding and within sentences. - -\yamltitle{removeSentenceLineBreaks}{0|1} - When operating upon sentences \texttt{latexindent.pl} will, by default, remove internal - line breaks as \texttt{removeSentenceLineBreaks} is set to \texttt{1}. Setting this - switch to \texttt{0} instructs \texttt{latexindent.pl} not to do so. - \index{sentences!removing sentence line breaks} - - For example, consider \texttt{multiple-sentences.tex} shown in - \cref{lst:multiple-sentences}. - - \cmhlistingsfromfile{demonstrations/multiple-sentences.tex}{\texttt{multiple-sentences.tex}}{lst:multiple-sentences} - - If we use the YAML files in - \cref{lst:manipulate-sentences-yaml,lst:keep-sen-line-breaks-yaml}, and run the commands - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl multiple-sentences -m -l=manipulate-sentences.yaml -latexindent.pl multiple-sentences -m -l=keep-sen-line-breaks.yaml -\end{commandshell} - \end{widepage} - then we obtain the respective output given in - \cref{lst:multiple-sentences-mod1,lst:multiple-sentences-mod2}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/multiple-sentences-mod1.tex}{\texttt{multiple-sentences.tex} using \cref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/manipulate-sentences.yaml}[MLB-TCB]{\texttt{manipulate-sentences.yaml}}{lst:manipulate-sentences-yaml} - \end{cmhtcbraster} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/multiple-sentences-mod2.tex}{\texttt{multiple-sentences.tex} using \cref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences-mod2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/keep-sen-line-breaks.yaml}[MLB-TCB]{\texttt{keep-sen-line-breaks.yaml}}{lst:keep-sen-line-breaks-yaml} - \end{cmhtcbraster} - - Notice, in particular, that the `internal' sentence line breaks in - \cref{lst:multiple-sentences} have been removed in \cref{lst:multiple-sentences-mod1}, - but have not been removed in \cref{lst:multiple-sentences-mod2}. - -\yamltitle{multipleSpacesToSingle}{0|1} - \announce{2022-03-25}*{multipleSpacesToSingle for oneSentencePerLine} By default, the - one-sentence-per-line routine will convert multiple spaces into single spaces. You can - change this behaviour by changing the switch \texttt{multipleSpacesToSingle} to a value - of \texttt{0}. - - The remainder of the settings displayed in \vref{lst:oneSentencePerLine} instruct - \texttt{latexindent.pl} on how to define a sentence. From the perspective of - \texttt{latexindent.pl} a sentence must: \index{sentences!follow} \index{sentences!begin - with} \index{sentences!end with} - \begin{itemize} - \item \emph{follow} a certain character or set of characters (see - \cref{lst:sentencesFollow}); by default, this is either \lstinline!\par!, a - blank line, a full stop/period (.), exclamation mark (!), question mark (?) right brace - (\}) or a comment on the previous line; - \item \emph{begin} with a character type (see \cref{lst:sentencesBeginWith}); by - default, this is only capital letters; - \item \emph{end} with a character (see \cref{lst:sentencesEndWith}); by - default, these are full stop/period (.), exclamation mark (!) and question mark (?). - \end{itemize} - In each case, you can specify the \texttt{other} field to include any pattern that you - would like; you can specify anything in this field using the language of regular - expressions. \index{regular expressions!lowercase alph a-z} \index{regular - expressions!uppercase alph A-Z} - - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.06\linewidth] - \cmhlistingsfromfile[style=sentencesFollow]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} - \cmhlistingsfromfile[style=sentencesBeginWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} - \cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} - \end{cmhtcbraster} - -\subsubsection{sentencesFollow} - Let's explore a few of the switches in \texttt{sentencesFollow}; let's start with - \vref{lst:multiple-sentences}, and use the YAML settings given in - \cref{lst:sentences-follow1-yaml}. Using the command \index{sentences!follow} - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences -m -l=sentences-follow1.yaml -\end{commandshell} - we obtain the output given in \cref{lst:multiple-sentences-mod3}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/multiple-sentences-mod3.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-follow1-yaml}}{lst:multiple-sentences-mod3} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow1.yaml}[MLB-TCB]{\texttt{sentences-follow1.yaml}}{lst:sentences-follow1-yaml} - \end{cmhtcbraster} - - Notice that, because \texttt{blankLine} is set to \texttt{0}, \texttt{latexindent.pl} - will not seek sentences following a blank line, and so the fourth sentence has not been - accounted for. - - We can explore the \texttt{other} field in \cref{lst:sentencesFollow} with the - \texttt{.tex} file detailed in \cref{lst:multiple-sentences1}. - - \cmhlistingsfromfile{demonstrations/multiple-sentences1.tex}{\texttt{multiple-sentences1.tex}}{lst:multiple-sentences1} - - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml -latexindent.pl multiple-sentences1 -m -l=manipulate-sentences.yaml,sentences-follow2.yaml -\end{commandshell} - \end{widepage} - then we obtain the respective output given in - \cref{lst:multiple-sentences1-mod1,lst:multiple-sentences1-mod2}. - \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod1.tex}{\texttt{multiple-sentences1.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences1-mod1} - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=1cm}, - ] - \cmhlistingsfromfile{demonstrations/multiple-sentences1-mod2.tex}{\texttt{multiple-sentences1.tex} using \cref{lst:sentences-follow2-yaml}}{lst:multiple-sentences1-mod2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-follow2.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-follow2.yaml}}{lst:sentences-follow2-yaml} - \end{cmhtcbraster} - - Notice that in \cref{lst:multiple-sentences1-mod1} the first sentence after the - \texttt{)} has not been accounted for, but that following the inclusion of - \cref{lst:sentences-follow2-yaml}, the output given in - \cref{lst:multiple-sentences1-mod2} demonstrates that the sentence \emph{has} been - accounted for correctly. - -\subsubsection{sentencesBeginWith} - By default, \texttt{latexindent.pl} will only assume that sentences begin with the upper - case letters \texttt{A-Z}; you can instruct the script to define sentences to begin with - lower case letters (see \cref{lst:sentencesBeginWith}), and we can use the \texttt{other} - field to define sentences to begin with other characters. \index{sentences!begin with} - - \cmhlistingsfromfile{demonstrations/multiple-sentences2.tex}{\texttt{multiple-sentences2.tex}}{lst:multiple-sentences2} - - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml -latexindent.pl multiple-sentences2 -m -l=manipulate-sentences.yaml,sentences-begin1.yaml -\end{commandshell} - \end{widepage} - then we obtain the respective output given in - \cref{lst:multiple-sentences2-mod1,lst:multiple-sentences2-mod2}. - \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod1.tex}{\texttt{multiple-sentences2.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences2-mod1} - \index{regular expressions!numeric 0-9} - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=1cm}, - ] - \cmhlistingsfromfile{demonstrations/multiple-sentences2-mod2.tex}{\texttt{multiple-sentences2.tex} using \cref{lst:sentences-begin1-yaml}}{lst:multiple-sentences2-mod2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-begin1.yaml}[MLB-TCB,width=.45\textwidth]{\texttt{sentences-begin1.yaml}}{lst:sentences-begin1-yaml} - \end{cmhtcbraster} - Notice that in \cref{lst:multiple-sentences2-mod1}, the first sentence has been accounted - for but that the subsequent sentences have not. In \cref{lst:multiple-sentences2-mod2}, - all of the sentences have been accounted for, because the \texttt{other} field in - \cref{lst:sentences-begin1-yaml} has defined sentences to begin with either \lstinline!$! - or any numeric digit, \texttt{0} to \texttt{9}. - -\subsubsection{sentencesEndWith} - Let's return to \vref{lst:multiple-sentences}; we have already seen the default way in - which \texttt{latexindent.pl} will operate on the sentences in this file in - \vref{lst:multiple-sentences-mod1}. We can populate the \texttt{other} field with any - character that we wish; for example, using the YAML specified in - \cref{lst:sentences-end1-yaml} and the command \index{sentences!end with} - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences -m -l=sentences-end1.yaml -latexindent.pl multiple-sentences -m -l=sentences-end2.yaml -\end{commandshell} - then we obtain the output in \cref{lst:multiple-sentences-mod4}. \index{regular - expressions!lowercase alph a-z} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/multiple-sentences-mod4.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end1-yaml}}{lst:multiple-sentences-mod4} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end1.yaml}[MLB-TCB]{\texttt{sentences-end1.yaml}}{lst:sentences-end1-yaml} - \end{cmhtcbraster} - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/multiple-sentences-mod5.tex}{\texttt{multiple-sentences.tex} using \cref{lst:sentences-end2-yaml}}{lst:multiple-sentences-mod5} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentences-end2.yaml}[MLB-TCB]{\texttt{sentences-end2.yaml}}{lst:sentences-end2-yaml} - \end{cmhtcbraster} - - There is a subtle difference between the output in - \cref{lst:multiple-sentences-mod4,lst:multiple-sentences-mod5}; in particular, in - \cref{lst:multiple-sentences-mod4} the word \texttt{sentence} has not been defined as a - sentence, because we have not instructed \texttt{latexindent.pl} to begin sentences with - lower case letters. We have changed this by using the settings in - \cref{lst:sentences-end2-yaml}, and the associated output in - \cref{lst:multiple-sentences-mod5} reflects this. - - Referencing \vref{lst:sentencesEndWith}, you'll notice that there is a field called - \texttt{basicFullStop}, which is set to \texttt{0}, and that the \texttt{betterFullStop} - is set to \texttt{1} by default. - - Let's consider the file shown in \cref{lst:url}. - - \cmhlistingsfromfile{demonstrations/url.tex}{\texttt{url.tex}}{lst:url} - - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl url -m -l=manipulate-sentences.yaml -\end{commandshell} - we obtain the output given in \cref{lst:url-mod1}. - - \cmhlistingsfromfile{demonstrations/url-mod1.tex}{\texttt{url.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:url-mod1} - - Notice that the full stop within the url has been interpreted correctly. This is because, - within the \texttt{betterFullStop}, full stops at the end of sentences have the following - properties: - \begin{itemize} - \item they are ignored within \texttt{e.g.} and \texttt{i.e.}; - \item they can not be immediately followed by a lower case or upper case letter; - \item they can not be immediately followed by a hyphen, comma, or number. - \end{itemize} - If you find that the \texttt{betterFullStop} does not work for your purposes, then you - can switch it off by setting it to \texttt{0}, and you can experiment with the - \texttt{other} field. \announce{2019-07-13}{fine tuning the betterFullStop} You can also - seek to customise the \texttt{betterFullStop} routine by using the \emph{fine tuning}, - detailed in \vref{lst:fineTuning}.% - - The \texttt{basicFullStop} routine should probably be avoided in most situations, as it - does not accommodate the specifications above. For example, using the following command - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl url -m -l=alt-full-stop1.yaml -\end{commandshell} - and the YAML in \cref{lst:alt-full-stop1-yaml} gives the output in \cref{lst:url-mod2}. - - \begin{cmhtcbraster}[ raster left skip=-3.5cm, - raster right skip=-2cm, - raster force size=false, - raster column 1/.style={add to width=.1\textwidth}, - raster column skip=.06\linewidth] - \cmhlistingsfromfile{demonstrations/url-mod2.tex}{\texttt{url.tex} using \cref{lst:alt-full-stop1-yaml}}{lst:url-mod2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/alt-full-stop1.yaml}[MLB-TCB,width=.5\textwidth]{\texttt{alt-full-stop1.yaml}}{lst:alt-full-stop1-yaml} - \end{cmhtcbraster} - - Notice that the full stop within the URL has not been accommodated correctly because of - the non-default settings in \cref{lst:alt-full-stop1-yaml}. - -\subsubsection{Features of the oneSentencePerLine routine} - The sentence manipulation routine takes place \emph{after} verbatim \index{verbatim!in - relation to oneSentencePerLine} environments, preamble and trailing comments have been - accounted for; this means that any characters within these types of code blocks will not - be part of the sentence manipulation routine. - - For example, if we begin with the \texttt{.tex} file in \cref{lst:multiple-sentences3}, - and run the command \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences3 -m -l=manipulate-sentences.yaml -\end{commandshell} - then we obtain the output in \cref{lst:multiple-sentences3-mod1}. - \cmhlistingsfromfile{demonstrations/multiple-sentences3.tex}{\texttt{multiple-sentences3.tex}}{lst:multiple-sentences3} - \cmhlistingsfromfile{demonstrations/multiple-sentences3-mod1.tex}{\texttt{multiple-sentences3.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences3-mod1} - - Furthermore, if sentences run across environments then, by default, the line breaks - internal to the sentence will be removed. For example, if we use the \texttt{.tex} file - in \cref{lst:multiple-sentences4} and run the commands \index{switches!-l demonstration} - \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences4 -m -l=manipulate-sentences.yaml -latexindent.pl multiple-sentences4 -m -l=keep-sen-line-breaks.yaml -\end{commandshell} - then we obtain the output in - \cref{lst:multiple-sentences4-mod1,lst:multiple-sentences4-mod2}. - \cmhlistingsfromfile{demonstrations/multiple-sentences4.tex}{\texttt{multiple-sentences4.tex}}{lst:multiple-sentences4} - \begin{widepage} - \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod1.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:manipulate-sentences-yaml}}{lst:multiple-sentences4-mod1} - \end{widepage} - \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod2.tex}{\texttt{multiple-sentences4.tex} using \vref{lst:keep-sen-line-breaks-yaml}}{lst:multiple-sentences4-mod2} - - Once you've read \cref{sec:poly-switches}, you will know that you can accommodate the - removal of internal sentence line breaks by using the YAML in \cref{lst:item-rules2-yaml} - and the command \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences4 -m -l=item-rules2.yaml -\end{commandshell} - the output of which is shown in \cref{lst:multiple-sentences4-mod3}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/multiple-sentences4-mod3.tex}{\texttt{multiple-sentences4.tex} using \cref{lst:item-rules2-yaml}}{lst:multiple-sentences4-mod3} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-rules2.yaml}[MLB-TCB]{\texttt{item-rules2.yaml}}{lst:item-rules2-yaml} - \end{cmhtcbraster} - -\subsubsection{Text wrapping and indenting sentences} - The \texttt{oneSentencePerLine} \announce{2018-08-13}{oneSentencePerline text wrap and - indent} can be instructed to perform text wrapping and indentation upon sentences. - \index{sentences!text wrapping} \index{sentences!indenting}% - - Let's use the code in \cref{lst:multiple-sentences5}. - - \cmhlistingsfromfile{demonstrations/multiple-sentences5.tex}{\texttt{multiple-sentences5.tex}}{lst:multiple-sentences5} - - Referencing \cref{lst:sentence-wrap1-yaml}, and running the following command - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences5 -m -l=sentence-wrap1.yaml -\end{commandshell} - we receive the output given in \cref{lst:multiple-sentences5-mod1}. - - \begin{cmhtcbraster}[ raster left skip=-3.5cm, - raster right skip=-2cm, - raster force size=false, - raster column 1/.style={add to width=.1\textwidth}, - raster column skip=.06\linewidth] - \cmhlistingsfromfile{demonstrations/multiple-sentences5-mod1.tex}{\texttt{multiple-sentences5.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences5-mod1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/sentence-wrap1.yaml}[MLB-TCB,width=0.5\textwidth]{\texttt{sentence-wrap1.yaml}}{lst:sentence-wrap1-yaml} - \end{cmhtcbraster} - - If you specify \texttt{textWrapSentences} as 1, but do \emph{not} specify a value for - \texttt{columns} then the text wrapping will \emph{not} operate on sentences, and you - will see a warning in \texttt{indent.log}. - - The indentation of sentences requires that sentences are stored as code blocks. This - means that you may need to tweak \vref{lst:sentencesEndWith}. Let's explore this in - relation to \cref{lst:multiple-sentences6}. - - \cmhlistingsfromfile{demonstrations/multiple-sentences6.tex}{\texttt{multiple-sentences6.tex}}{lst:multiple-sentences6} - - By default, \texttt{latexindent.pl} will find the full-stop within the first - \texttt{item}, which means that, upon running the following commands \index{switches!-l - demonstration} \index{switches!-m demonstration} \index{switches!-y demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml -y="modifyLineBreaks:oneSentencePerLine:sentenceIndent:''" -\end{commandshell} - we receive the respective output in \cref{lst:multiple-sentences6-mod1} and - \cref{lst:multiple-sentences6-mod2}. - - \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod1.tex}{\texttt{multiple-sentences6-mod1.tex} using \cref{lst:sentence-wrap1-yaml}}{lst:multiple-sentences6-mod1} - - \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod2.tex}{\texttt{multiple-sentences6-mod2.tex} using \cref{lst:sentence-wrap1-yaml} and no sentence indentation}{lst:multiple-sentences6-mod2} - - We note that \cref{lst:multiple-sentences6-mod1} the \texttt{itemize} code block has - \emph{not} been indented appropriately. This is because the oneSentencePerLine has been - instructed to store sentences (because \cref{lst:sentence-wrap1-yaml}); each sentence is - then searched for code blocks. - - We can tweak the settings in \vref{lst:sentencesEndWith} to ensure that full stops are - not followed by \texttt{item} commands, and that the end of sentences contains - \lstinline!\end{itemize}! as in \cref{lst:itemize-yaml} (if you intend to use this, - ensure that you remove the line breaks from the \texttt{other} field). \index{regular - expressions!lowercase alph a-z} \index{regular expressions!uppercase alph A-Z} - \index{regular expressions!numeric 0-9} \index{regular expressions!horizontal space - \textbackslash{h}} - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/itemized.yaml}[MLB-TCB]{\texttt{itemize.yaml}}{lst:itemize-yaml} - - Upon running \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl multiple-sentences6 -m -l=sentence-wrap1.yaml,itemize.yaml -\end{commandshell} - we receive the output in \cref{lst:multiple-sentences6-mod3}. - - \cmhlistingsfromfile{demonstrations/multiple-sentences6-mod3.tex}{\texttt{multiple-sentences6-mod3.tex} using \cref{lst:sentence-wrap1-yaml} and \cref{lst:itemize-yaml}}{lst:multiple-sentences6-mod3} - - Notice that the sentence has received indentation, and that the \texttt{itemize} code - block has been found and indented correctly. - - Text \announce{2022-04-04}*{oneSentencePerLine text wrapping update} wrapping when using - the \texttt{oneSentencePerLine} routine determines if it will remove line breaks while - text wrapping, from the value of \texttt{removeSentenceLineBreaks}. diff --git a/support/latexindent/documentation/subsec-poly-switches.tex b/support/latexindent/documentation/subsec-poly-switches.tex deleted file mode 100644 index ebec90f719..0000000000 --- a/support/latexindent/documentation/subsec-poly-switches.tex +++ /dev/null @@ -1,1053 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsection{Poly-switches}\label{sec:poly-switches} - Every other field in the \texttt{modifyLineBreaks} field uses poly-switches, and can take - one of the following% - \announce{2017-08-21}*{blank line poly-switch} integer values: - \index{modifying linebreaks! using poly-switches} - \index{poly-switches!definition} - \index{poly-switches!values} - \index{poly-switches!off by default: set to 0} - \begin{description} - \item[$-1$] \emph{remove mode}: line breaks before or after the - \emph{} can be removed (assuming that \texttt{preserveBlankLines} is - set to \texttt{0}); - \item[0] \emph{off mode}: line breaks will not be modified for the - \emph{} under consideration; - \item[1] \emph{add mode}: a line break will be added before or after the - \emph{} under consideration, assuming that - there is not already a line break before or after the \emph{}; - \item[2] \emph{comment then add mode}: a comment symbol will be added, followed by a line break - before or after the \emph{} under consideration, assuming that there is - not already a comment and line break before or after the \emph{}; - \item[3] \emph{add then blank line mode}% - \announce{2017-08-21}{blank line poly-switch}: a line break will be added before or after - the \emph{} under consideration, assuming that there is not already a line - break before or after the \emph{}, followed by a blank line; - \item[4] \emph{add blank line mode}% - \announce{2019-07-13}{blank line poly-switch}; a blank line will - be added before or after the \emph{} under consideration, even if the - \emph{} is already on its own line. - \end{description} - In the above, \emph{} refers to either the \emph{begin statement}, - \emph{body} or \emph{end statement} of the code blocks detailed in - \vref{tab:code-blocks}. All poly-switches are \emph{off} by default; - \texttt{latexindent.pl} searches first of all for per-name settings, and then followed by - global per-thing settings. - -\subsubsection{Poly-switches for environments}\label{sec:modifylinebreaks-environments} - We start by viewing a snippet of \texttt{defaultSettings.yaml} in - \cref{lst:environments-mlb}; note that it contains \emph{global} settings (immediately - after the \texttt{environments} field) and that \emph{per-name} settings are also allowed - -- in the case of \cref{lst:environments-mlb}, settings for \texttt{equation*} have been - specified for demonstration. Note that all poly-switches are \emph{off} (set to 0) by - default. \index{poly-switches!default values} \index{poly-switches!environment global - example} \index{poly-switches!environment per-code block example} - - \cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} - - Let's begin with the simple example given in \cref{lst:env-mlb1-tex}; note that we have - annotated key parts of the file using $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, - $\EndStartsOnOwnLine$ and $\EndFinishesWithLineBreak$, these will be related to fields - specified in \cref{lst:environments-mlb}. \index{poly-switches!visualisation: - $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$, - $\EndFinishesWithLineBreak$} - - \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb1.tex}}{lst:env-mlb1-tex} -before words(*@$\BeginStartsOnOwnLine$@*) \begin{myenv}(*@$\BodyStartsOnOwnLine$@*)body of myenv(*@$\EndStartsOnOwnLine$@*)\end{myenv}(*@$\EndFinishesWithLineBreak$@*) after words -\end{cmhlistings} - - \paragraph{Adding line breaks: BeginStartsOnOwnLine and BodyStartsOnOwnLine} - Let's explore \texttt{BeginStartsOnOwnLine} and \texttt{BodyStartsOnOwnLine} in - \cref{lst:env-mlb1,lst:env-mlb2}, and in particular, let's allow each of them in turn to - take a value of $1$. \index{modifying linebreaks! at the \emph{beginning} of a code - block} \index{poly-switches!adding line breaks: set to 1} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb1.yaml}[MLB-TCB]{\texttt{env-mlb1.yaml}}{lst:env-mlb1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb2.yaml}[MLB-TCB]{\texttt{env-mlb2.yaml}}{lst:env-mlb2} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m env-mlb.tex -l env-mlb1.yaml -latexindent.pl -m env-mlb.tex -l env-mlb2.yaml -\end{commandshell} - the output is as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2} respectively. - - \begin{widepage} - \begin{minipage}{.56\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod1.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb1}}{lst:env-mlb-mod1} - \end{minipage} - \hfill - \begin{minipage}{.43\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod2.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb2}}{lst:env-mlb-mod2} - \end{minipage} - \end{widepage} - - There are a couple of points to note: - \begin{itemize} - \item in \cref{lst:env-mlb-mod1} a line break has been added at the point denoted by - $\BeginStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; no other line breaks have been - changed; - \item in \cref{lst:env-mlb-mod2} a line break has been added at the point denoted by - $\BodyStartsOnOwnLine$ in \cref{lst:env-mlb1-tex}; furthermore, note that the \emph{body} - of \texttt{myenv} has received the appropriate (default) indentation. - \end{itemize} - - Let's now change each of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so - that they are $2$ and save them into \texttt{env-mlb3.yaml} and \texttt{env-mlb4.yaml} - respectively (see \cref{lst:env-mlb3,lst:env-mlb4}). \index{poly-switches!adding comments - and then line breaks: set to 2} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb3.yaml}[MLB-TCB]{\texttt{env-mlb3.yaml}}{lst:env-mlb3} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb4.yaml}[MLB-TCB]{\texttt{env-mlb4.yaml}}{lst:env-mlb4} - \end{minipage} - - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod3,lst:env-mlb-mod4}. - - \begin{widepage} - \begin{minipage}{.56\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod3.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb3}}{lst:env-mlb-mod3} - \end{minipage} - \hfill - \begin{minipage}{.43\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod4.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb4}}{lst:env-mlb-mod4} - \end{minipage} - \end{widepage} - - Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but - this time a comment symbol has been added before adding the line break; in both cases, - trailing horizontal space has been stripped before doing so. - - Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each - of the \texttt{1} values in \cref{lst:env-mlb1,lst:env-mlb2} so that they are $3$ and - save them into \texttt{env-mlb5.yaml} and \texttt{env-mlb6.yaml} respectively (see - \cref{lst:env-mlb5,lst:env-mlb6}). \index{poly-switches!adding blank lines: set to 3}% - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb5.yaml}[MLB-TCB]{\texttt{env-mlb5.yaml}}{lst:env-mlb5} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb6.yaml}[MLB-TCB]{\texttt{env-mlb6.yaml}}{lst:env-mlb6} - \end{minipage} - - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod5,lst:env-mlb-mod6}. - - \begin{widepage} - \begin{minipage}{.56\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod5.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb5}}{lst:env-mlb-mod5} - \end{minipage} - \hfill - \begin{minipage}{.43\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod6.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb6}}{lst:env-mlb-mod6} - \end{minipage} - \end{widepage} - - Note that line breaks have been added as in \cref{lst:env-mlb-mod1,lst:env-mlb-mod2}, but - this time a \emph{blank line} has been added after adding the line break. - - Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each - of the \texttt{1} values in \cref{lst:env-mlb5,lst:env-mlb6} so that they are $4$ and - save them into \texttt{env-beg4.yaml} and \texttt{env-body4.yaml} respectively (see - \cref{lst:env-beg4,lst:env-body4}). \index{poly-switches!adding blank lines (again"!): - set to 4}% - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-beg4.yaml}[MLB-TCB]{\texttt{env-beg4.yaml}}{lst:env-beg4} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-body4.yaml}[MLB-TCB]{\texttt{env-body4.yaml}}{lst:env-body4} - \end{minipage} - - We will demonstrate this poly-switch value using the code in \cref{lst:env-mlb1-text}. - - \cmhlistingsfromfile{demonstrations/env-mlb1.tex}{\texttt{env-mlb1.tex}}{lst:env-mlb1-text} - - Upon running the commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl -m env-mlb1.tex -l env-beg4.yaml -latexindent.pl -m env-mlb.1tex -l env-body4.yaml -\end{commandshell} - - then we receive the respective outputs in \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/env-mlb1-beg4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-beg4}}{lst:env-mlb1-beg4} - \cmhlistingsfromfile{demonstrations/env-mlb1-body4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-body4}}{lst:env-mlb1-body4} - \end{cmhtcbraster} - - We note in particular that, by design, for this value of the poly-switches: - \begin{enumerate} - \item in \cref{lst:env-mlb1-beg4} a blank line has been inserted before the \lstinline!\begin! - statement, even though the \lstinline!\begin! statement was already on its own line; - \item in \cref{lst:env-mlb1-body4} a blank line has been inserted before the beginning of the - \emph{body}, even though it already began on its own line. - \end{enumerate} - - \paragraph{Adding line breaks using EndStartsOnOwnLine and EndFinishesWithLineBreak} - Let's explore \texttt{EndStartsOnOwnLine} and \texttt{EndFinishesWithLineBreak} in - \cref{lst:env-mlb7,lst:env-mlb8}, and in particular, let's allow each of them in turn to - take a value of $1$. \index{modifying linebreaks! at the \emph{end} of a code block} - \index{poly-switches!adding line breaks: set to 1} - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb7.yaml}[MLB-TCB]{\texttt{env-mlb7.yaml}}{lst:env-mlb7} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb8.yaml}[MLB-TCB]{\texttt{env-mlb8.yaml}}{lst:env-mlb8} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m env-mlb.tex -l env-mlb7.yaml -latexindent.pl -m env-mlb.tex -l env-mlb8.yaml -\end{commandshell} - the output is as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}. - - \begin{widepage} - \begin{minipage}{.42\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod7.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb7}}{lst:env-mlb-mod7} - \end{minipage} - \hfill - \begin{minipage}{.57\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod8.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb8}}{lst:env-mlb-mod8} - \end{minipage} - \end{widepage} - - There are a couple of points to note: - \begin{itemize} - \item in \cref{lst:env-mlb-mod7} a line break has been added at the point denoted by - $\EndStartsOnOwnLine$ in \vref{lst:env-mlb1-tex}; no other line breaks have been changed - and the \lstinline!\end{myenv}! statement has \emph{not} received indentation (as - intended); - \item in \cref{lst:env-mlb-mod8} a line break has been added at the point denoted by - $\EndFinishesWithLineBreak$ in \vref{lst:env-mlb1-tex}. - \end{itemize} - - Let's now change each of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so - that they are $2$ and save them into \texttt{env-mlb9.yaml} and \texttt{env-mlb10.yaml} - respectively (see \cref{lst:env-mlb9,lst:env-mlb10}). \index{poly-switches!adding - comments and then line breaks: set to 2} - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb9.yaml}[MLB-TCB]{\texttt{env-mlb9.yaml}}{lst:env-mlb9} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb10.yaml}[MLB-TCB]{\texttt{env-mlb10.yaml}}{lst:env-mlb10} - \end{minipage} - - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod9,lst:env-mlb-mod10}. - - \begin{widepage} - \begin{minipage}{.43\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod9.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb9}}{lst:env-mlb-mod9} - \end{minipage} - \hfill - \begin{minipage}{.56\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod10.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb10}}{lst:env-mlb-mod10} - \end{minipage} - \end{widepage} - - Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, but - this time a comment symbol has been added before adding the line break; in both cases, - trailing horizontal space has been stripped before doing so. - - Let's \announce{2017-08-21}{demonstration of blank line poly-switch (3)} now change each - of the \texttt{1} values in \cref{lst:env-mlb7,lst:env-mlb8} so that they are $3$ and - save them into \texttt{env-mlb11.yaml} and \texttt{env-mlb12.yaml} respectively (see - \cref{lst:env-mlb11,lst:env-mlb12}). \index{poly-switches!adding blank lines: set to 3}% - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb11.yaml}[MLB-TCB]{\texttt{env-mlb11.yaml}}{lst:env-mlb11} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb12.yaml}[MLB-TCB]{\texttt{env-mlb12.yaml}}{lst:env-mlb12} - \end{minipage} - - Upon running commands analogous to the above, we obtain - \cref{lst:env-mlb-mod11,lst:env-mlb-mod12}. - - \begin{widepage} - \begin{minipage}{.42\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod11.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb11}}{lst:env-mlb-mod11} - \end{minipage} - \hfill - \begin{minipage}{.57\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb-mod12.tex}{\texttt{env-mlb.tex} using \cref{lst:env-mlb12}}{lst:env-mlb-mod12} - \end{minipage} - \end{widepage} - - Note that line breaks have been added as in \cref{lst:env-mlb-mod7,lst:env-mlb-mod8}, and - that a \emph{blank line} has been added after the line break. - - Let's now change \announce{2019-07-13}{demonstration of new blank line poly-switch} each - of the \texttt{1} values in \cref{lst:env-mlb11,lst:env-mlb12} so that they are $4$ and - save them into \texttt{env-end4.yaml} and \texttt{env-end-f4.yaml} respectively (see - \cref{lst:env-end4,lst:env-end-f4}). \index{poly-switches!adding blank lines (again"!): - set to 4}% - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end4.yaml}[MLB-TCB]{\texttt{env-end4.yaml}}{lst:env-end4} - \end{minipage} - \hfill - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-end-f4.yaml}[MLB-TCB]{\texttt{env-end-f4.yaml}}{lst:env-end-f4} - \end{minipage} - - We will demonstrate this poly-switch value using the code from \vref{lst:env-mlb1-text}. - - Upon running the commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl -m env-mlb1.tex -l env-end4.yaml -latexindent.pl -m env-mlb.1tex -l env-end-f4.yaml -\end{commandshell} - - then we receive the respective outputs in \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/env-mlb1-end4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end4}}{lst:env-mlb1-end4} - \cmhlistingsfromfile{demonstrations/env-mlb1-end-f4.tex}{\texttt{env-mlb1.tex} using \cref{lst:env-end-f4}}{lst:env-mlb1-end-f4} - \end{cmhtcbraster} - - We note in particular that, by design, for this value of the poly-switches: - \begin{enumerate} - \item in \cref{lst:env-mlb1-end4} a blank line has been inserted before the \lstinline!\end! - statement, even though the \lstinline!\end! statement was already on its own line; - \item in \cref{lst:env-mlb1-end-f4} a blank line has been inserted after the \lstinline!\end! - statement, even though it already began on its own line. - \end{enumerate} - - \paragraph{poly-switches 1, 2, and 3 only add line breaks when necessary} - If you ask \texttt{latexindent.pl} to add a line break (possibly with a comment) using a - poly-switch value of $1$ (or $2$ or $3$), it will only do so if necessary. For example, - if you process the file in \vref{lst:mlb2} using poly-switch values of 1, 2, or 3, it - will be left unchanged. - - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb2.tex}{\texttt{env-mlb2.tex}}{lst:mlb2} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb3.tex}{\texttt{env-mlb3.tex}}{lst:mlb3} - \end{minipage} - - Setting the poly-switches to a value of $4$ instructs \texttt{latexindent.pl} to add a - line break even if the \emph{} is already on its own line; see - \cref{lst:env-mlb1-beg4,lst:env-mlb1-body4} and - \cref{lst:env-mlb1-end4,lst:env-mlb1-end-f4}. - - In contrast, the output from processing the file in \cref{lst:mlb3} will vary depending - on the poly-switches used; in \cref{lst:env-mlb3-mod2} you'll see that the comment symbol - after the \lstinline!\begin{myenv}! has been moved to the next line, as - \texttt{BodyStartsOnOwnLine} is set to \texttt{1}. In \cref{lst:env-mlb3-mod4} you'll see - that the comment has been accounted for correctly because \texttt{BodyStartsOnOwnLine} - has been set to \texttt{2}, and the comment symbol has \emph{not} been moved to its own - line. You're encouraged to experiment with \cref{lst:mlb3} and by setting the other - poly-switches considered so far to \texttt{2} in turn. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/env-mlb3-mod2.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb2}}{lst:env-mlb3-mod2} - \cmhlistingsfromfile{demonstrations/env-mlb3-mod4.tex}{\texttt{env-mlb3.tex} using \vref{lst:env-mlb4}}{lst:env-mlb3-mod4} - \end{cmhtcbraster} - - The details of the discussion in this section have concerned \emph{global} poly-switches - in the \texttt{environments} field; each switch can also be specified on a - \emph{per-name} basis, which would take priority over the global values; with reference - to \vref{lst:environments-mlb}, an example is shown for the \texttt{equation*} - environment. - - \paragraph{Removing line breaks (poly-switches set to $-1$)} - Setting poly-switches to $-1$ tells \texttt{latexindent.pl} to remove line breaks of the - \emph{}, if necessary. We will consider the example code given in - \cref{lst:mlb4}, noting in particular the positions of the line break highlighters, - $\BeginStartsOnOwnLine$, $\BodyStartsOnOwnLine$, $\EndStartsOnOwnLine$ and - $\EndFinishesWithLineBreak$, together with the associated YAML files in - \crefrange{lst:env-mlb13}{lst:env-mlb16}. \index{poly-switches!removing line breaks: set - to -1} - - \begin{minipage}{.45\linewidth} - \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb4.tex}}{lst:mlb4} -before words(*@$\BeginStartsOnOwnLine$@*) -\begin{myenv}(*@$\BodyStartsOnOwnLine$@*) -body of myenv(*@$\EndStartsOnOwnLine$@*) -\end{myenv}(*@$\EndFinishesWithLineBreak$@*) -after words -\end{cmhlistings} - \end{minipage}% - \hfill - \begin{minipage}{.51\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb13.yaml}[MLB-TCB]{\texttt{env-mlb13.yaml}}{lst:env-mlb13} - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb14.yaml}[MLB-TCB]{\texttt{env-mlb14.yaml}}{lst:env-mlb14} - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb15.yaml}[MLB-TCB]{\texttt{env-mlb15.yaml}}{lst:env-mlb15} - - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/env-mlb16.yaml}[MLB-TCB]{\texttt{env-mlb16.yaml}}{lst:env-mlb16} - \end{minipage} - - After running the commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml -latexindent.pl -m env-mlb4.tex -l env-mlb14.yaml -latexindent.pl -m env-mlb4.tex -l env-mlb15.yaml -latexindent.pl -m env-mlb4.tex -l env-mlb16.yaml -\end{commandshell} - - we obtain the respective output in \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}. - - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb4-mod13.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb13}}{lst:env-mlb4-mod13} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb4-mod14.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb14}}{lst:env-mlb4-mod14} - \end{minipage} - - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb4-mod15.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb15}}{lst:env-mlb4-mod15} - \end{minipage} - \hfill - \begin{minipage}{.45\linewidth} - \cmhlistingsfromfile{demonstrations/env-mlb4-mod16.tex}{\texttt{env-mlb4.tex} using \cref{lst:env-mlb16}}{lst:env-mlb4-mod16} - \end{minipage} - - Notice that in: - \begin{itemize} - \item \cref{lst:env-mlb4-mod13} the line break denoted by $\BeginStartsOnOwnLine$ in - \cref{lst:mlb4} has been removed; - \item \cref{lst:env-mlb4-mod14} the line break denoted by $\BodyStartsOnOwnLine$ in - \cref{lst:mlb4} has been removed; - \item \cref{lst:env-mlb4-mod15} the line break denoted by $\EndStartsOnOwnLine$ in - \cref{lst:mlb4} has been removed; - \item \cref{lst:env-mlb4-mod16} the line break denoted by $\EndFinishesWithLineBreak$ in - \cref{lst:mlb4} has been removed. - \end{itemize} - We examined each of these cases separately for clarity of explanation, but you can - combine all of the YAML settings in \crefrange{lst:env-mlb13}{lst:env-mlb16} into one - file; alternatively, you could tell \texttt{latexindent.pl} to load them all by using the - following command, for example \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl -m env-mlb4.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml -\end{commandshell} - \end{widepage} - which gives the output in \vref{lst:env-mlb1-tex}. - - \paragraph{About trailing horizontal space} - Recall that on \cpageref{yaml:removeTrailingWhitespace} we discussed the YAML field - \texttt{removeTrailingWhitespace}, and that it has two (binary) switches to determine if - horizontal space should be removed \texttt{beforeProcessing} and - \texttt{afterProcessing}. The \texttt{beforeProcessing} is particularly relevant when - considering the \texttt{-m} switch; let's consider the file shown in \cref{lst:mlb5}, - which highlights trailing spaces. - - \begin{cmhtcbraster} - \begin{cmhlistings}[style=tcblatex,showspaces=true,escapeinside={(*@}{@*)}]{\texttt{env-mlb5.tex}}{lst:mlb5} -before words (*@$\BeginStartsOnOwnLine$@*) -\begin{myenv} (*@$\BodyStartsOnOwnLine$@*) -body of myenv (*@$\EndStartsOnOwnLine$@*) -\end{myenv} (*@$\EndFinishesWithLineBreak$@*) -after words -\end{cmhlistings} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/removeTWS-before.yaml}[yaml-TCB]{\texttt{removeTWS-before.yaml}}{lst:removeTWS-before} - \end{cmhtcbraster} - - The output from the following commands \index{switches!-l demonstration} - \index{switches!-m demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml -latexindent.pl -m env-mlb5.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,removeTWS-before.yaml -\end{commandshell} - \end{widepage} - is shown, respectively, in \cref{lst:env-mlb5-modAll,lst:env-mlb5-modAll-remove-WS}; note - that the trailing horizontal white space has been preserved (by default) in - \cref{lst:env-mlb5-modAll}, while in \cref{lst:env-mlb5-modAll-remove-WS}, it has been - removed using the switch specified in \cref{lst:removeTWS-before}. - - \begin{widepage} - \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb5-modAll} - - \cmhlistingsfromfile[showspaces=true]{demonstrations/env-mlb5-modAll-remove-WS.tex}{\texttt{env-mlb5.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:removeTWS-before}}{lst:env-mlb5-modAll-remove-WS} - \end{widepage} - - \paragraph{poly-switch line break removal and blank lines} - Now let's consider the file in \cref{lst:mlb6}, which contains blank lines. - \index{poly-switches!blank lines} - - \begin{cmhtcbraster} - \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{env-mlb6.tex}}{lst:mlb6} -before words(*@$\BeginStartsOnOwnLine$@*) - - -\begin{myenv}(*@$\BodyStartsOnOwnLine$@*) - - -body of myenv(*@$\EndStartsOnOwnLine$@*) - - -\end{myenv}(*@$\EndFinishesWithLineBreak$@*) - -after words -\end{cmhlistings} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/UnpreserveBlankLines.yaml}[MLB-TCB]{\texttt{UnpreserveBlankLines.yaml}}{lst:UnpreserveBlankLines} - \end{cmhtcbraster} - - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{widepage} - \begin{commandshell} -latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml -latexindent.pl -m env-mlb6.tex -l env-mlb13.yaml,env-mlb14.yaml,env-mlb15.yaml,env-mlb16.yaml,UnpreserveBlankLines.yaml -\end{commandshell} - \end{widepage} - we receive the respective outputs in - \cref{lst:env-mlb6-modAll,lst:env-mlb6-modAll-un-Preserve-Blank-Lines}. In - \cref{lst:env-mlb6-modAll} we see that the multiple blank lines have each been condensed - into one blank line, but that blank lines have \emph{not} been removed by the - poly-switches -- this is because, by default, \texttt{preserveBlankLines} is set to - \texttt{1}. By contrast, in \cref{lst:env-mlb6-modAll-un-Preserve-Blank-Lines}, we have - allowed the poly-switches to remove blank lines because, in - \cref{lst:UnpreserveBlankLines}, we have set \texttt{preserveBlankLines} to \texttt{0}. - - \begin{cmhtcbraster}[ raster left skip=-3.5cm, - raster right skip=-2cm, - raster force size=false, - raster column 1/.style={add to width=-.2\textwidth}, - raster column 2/.style={add to width=.2\textwidth}, - raster column skip=.06\linewidth] - \cmhlistingsfromfile{demonstrations/env-mlb6-modAll.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16}}{lst:env-mlb6-modAll} - \cmhlistingsfromfile{demonstrations/env-mlb6-modAll-un-Preserve-Blank-Lines.tex}{\texttt{env-mlb6.tex} using \crefrange{lst:env-mlb4-mod13}{lst:env-mlb4-mod16} \emph{and} \cref{lst:UnpreserveBlankLines}}{lst:env-mlb6-modAll-un-Preserve-Blank-Lines} - \end{cmhtcbraster} - - We can explore this further using the blank-line poly-switch value of $3$; let's use the - file given in \cref{lst:env-mlb7-tex}. - - \cmhlistingsfromfile{demonstrations/env-mlb7.tex}{\texttt{env-mlb7.tex}}{lst:env-mlb7-tex} - - Upon running the following commands \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl -m env-mlb7.tex -l env-mlb12.yaml,env-mlb13.yaml -latexindent.pl -m env-mlb7.tex -l env-mlb13.yaml,env-mlb14.yaml,UnpreserveBlankLines.yaml -\end{commandshell} - we receive the outputs given in \cref{lst:env-mlb7-preserve,lst:env-mlb7-no-preserve}. - - \cmhlistingsfromfile{demonstrations/env-mlb7-preserve.tex}{\texttt{env-mlb7-preserve.tex}}{lst:env-mlb7-preserve} - \cmhlistingsfromfile{demonstrations/env-mlb7-no-preserve.tex}{\texttt{env-mlb7-no-preserve.tex}}{lst:env-mlb7-no-preserve} - - Notice that in: - \begin{itemize} - \item \cref{lst:env-mlb7-preserve} that \lstinline!\end{one}! has added a blank line, - because of the value of \texttt{EndFinishesWithLineBreak} in \vref{lst:env-mlb12}, and - even though the line break ahead of \lstinline!\begin{two}! should have been removed - (because of \texttt{BeginStartsOnOwnLine} in \vref{lst:env-mlb13}), the blank line has - been preserved by default; - \item \cref{lst:env-mlb7-no-preserve}, by contrast, has had the additional line-break removed, - because of the settings in \cref{lst:UnpreserveBlankLines}. - \end{itemize} - -\subsubsection{Poly-switches for double back slash}\label{subsec:dbs} - With reference to \texttt{lookForAlignDelims} (see \vref{lst:aligndelims:basic}) - \announce{2019-07-13}{poly-switch for double back slash} you can specify poly-switches to - dictate the line-break behaviour of double back slashes in environments - (\vref{lst:tabularafter:basic}), commands (\vref{lst:matrixafter}), or special code - blocks (\vref{lst:specialafter}). Note that for these poly-switches to take effect, the - name of the code block must necessarily be specified within \texttt{lookForAlignDelims} - (\vref{lst:aligndelims:basic}); we will demonstrate this in what follows. - \index{delimiters!poly-switches for double back slash} \index{modifying linebreaks! - surrounding double back slash} \index{poly-switches!for double back slash (delimiters)}% - - Consider the code given in \cref{lst:dbs-demo}. - \begin{cmhlistings}[style=tcblatex,escapeinside={(*@}{@*)}]{\texttt{tabular3.tex}}{lst:dbs-demo} -\begin{tabular}{cc} - 1 & 2 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) 3 & 4 (*@$\ElseStartsOnOwnLine$@*)\\(*@$\ElseFinishesWithLineBreak$@*) -\end{tabular} -\end{cmhlistings} - Referencing \cref{lst:dbs-demo}: - \begin{itemize} - \item \texttt{DBS} stands for \emph{double back slash}; - \item line breaks ahead of the double back slash are annotated by $\ElseStartsOnOwnLine$, and - are controlled by \texttt{DBSStartsOnOwnLine}; - \item line breaks after the double back slash are annotated by $\ElseFinishesWithLineBreak$, - and are controlled by \texttt{DBSFinishesWithLineBreak}. - \end{itemize} - - Let's explore each of these in turn. - - \paragraph{Double back slash starts on own line} - We explore \texttt{DBSStartsOnOwnLine} ($\ElseStartsOnOwnLine$ in \cref{lst:dbs-demo}); - starting with the code in \cref{lst:dbs-demo}, together with the YAML files given in - \cref{lst:DBS1} and \cref{lst:DBS2} and running the following commands \index{switches!-l - demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m tabular3.tex -l DBS1.yaml -latexindent.pl -m tabular3.tex -l DBS2.yaml -\end{commandshell} - then we receive the respective output given in \cref{lst:tabular3-DBS1} and - \cref{lst:tabular3-DBS2}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/tabular3-mod1.tex}{\texttt{tabular3.tex} using \cref{lst:DBS1}}{lst:tabular3-DBS1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS1.yaml}[MLB-TCB]{\texttt{DBS1.yaml}}{lst:DBS1} - \end{cmhtcbraster} - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/tabular3-mod2.tex}{\texttt{tabular3.tex} using \cref{lst:DBS2}}{lst:tabular3-DBS2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS2.yaml}[MLB-TCB]{\texttt{DBS2.yaml}}{lst:DBS2} - \end{cmhtcbraster} - - We note that - \begin{itemize} - \item \cref{lst:DBS1} specifies \texttt{DBSStartsOnOwnLine} for - \emph{every} environment (that is within \texttt{lookForAlignDelims}, - \vref{lst:aligndelims:advanced}); - the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in - \cref{lst:tabular3-DBS1}; - \item \cref{lst:DBS2} specifies \texttt{DBSStartsOnOwnLine} on a - \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, - \vref{lst:aligndelims:advanced}); - the double back slashes from \cref{lst:dbs-demo} have been moved to their own line in - \cref{lst:tabular3-DBS2}, having added comment symbols before moving them. - \end{itemize} - - \paragraph{Double back slash finishes with line break} - Let's now explore \texttt{DBSFinishesWithLineBreak} ($\ElseFinishesWithLineBreak$ in - \cref{lst:dbs-demo}); starting with the code in \cref{lst:dbs-demo}, together with the - YAML files given in \cref{lst:DBS3} and \cref{lst:DBS4} and running the following - commands \index{poly-switches!for double back slash (delimiters)} \index{switches!-l - demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m tabular3.tex -l DBS3.yaml -latexindent.pl -m tabular3.tex -l DBS4.yaml -\end{commandshell} - then we receive the respective output given in \cref{lst:tabular3-DBS3} and - \cref{lst:tabular3-DBS4}. - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/tabular3-mod3.tex}{\texttt{tabular3.tex} using \cref{lst:DBS3}}{lst:tabular3-DBS3} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS3.yaml}[MLB-TCB]{\texttt{DBS3.yaml}}{lst:DBS3} - \end{cmhtcbraster} - - \begin{cmhtcbraster}[raster column skip=.01\linewidth] - \cmhlistingsfromfile{demonstrations/tabular3-mod4.tex}{\texttt{tabular3.tex} using \cref{lst:DBS4}}{lst:tabular3-DBS4} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS4.yaml}[MLB-TCB]{\texttt{DBS4.yaml}}{lst:DBS4} - \end{cmhtcbraster} - - We note that - \begin{itemize} - \item \cref{lst:DBS3} specifies \texttt{DBSFinishesWithLineBreak} for - \emph{every} environment (that is within \texttt{lookForAlignDelims}, - \vref{lst:aligndelims:advanced}); - the code following the double back slashes from \cref{lst:dbs-demo} has been moved to - their own line in \cref{lst:tabular3-DBS3}; - \item \cref{lst:DBS4} specifies \texttt{DBSFinishesWithLineBreak} on a - \emph{per-name} basis for \texttt{tabular} (that is within \texttt{lookForAlignDelims}, - \vref{lst:aligndelims:advanced}); - the first double back slashes from \cref{lst:dbs-demo} have moved code following them to - their own line in \cref{lst:tabular3-DBS4}, having added comment symbols before moving - them; the final double back slashes have \emph{not} added a line break as they are at the - end of the body within the code block. - \end{itemize} - - \paragraph{Double back slash poly-switches for specialBeginEnd} - Let's explore the double back slash poly-switches for code blocks within - \texttt{specialBeginEnd} code blocks (\vref{lst:specialBeginEnd}); we begin with the code - within \cref{lst:special4}. \index{specialBeginEnd!double backslash poly-switch - demonstration} \index{poly-switches!double backslash} \index{poly-switches!for double - back slash (delimiters)} \index{specialBeginEnd!lookForAlignDelims} \index{delimiters} - \index{linebreaks!summary of poly-switches} - - \cmhlistingsfromfile{demonstrations/special4.tex}{\texttt{special4.tex}}{lst:special4} - - Upon using the YAML settings in \cref{lst:DBS5}, and running the command - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m special4.tex -l DBS5.yaml -\end{commandshell} - then we receive the output given in \cref{lst:special4-DBS5}. \index{delimiters!with - specialBeginEnd and the -m switch} - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-.1\textwidth}, - raster column skip=.06\linewidth] - \cmhlistingsfromfile{demonstrations/special4-mod5.tex}{\texttt{special4.tex} using \cref{lst:DBS5}}{lst:special4-DBS5} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS5.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS5.yaml}}{lst:DBS5} - \end{cmhtcbraster} - - There are a few things to note: - \begin{itemize} - \item in \cref{lst:DBS5} we have specified \texttt{cmhMath} within \texttt{lookForAlignDelims}; - without this, the double back slash poly-switches would be ignored for this code block; - \item the \texttt{DBSFinishesWithLineBreak} poly-switch has controlled the line breaks - following the double back slashes; - \item the \texttt{SpecialEndStartsOnOwnLine} poly-switch has controlled the addition of a - comment symbol, followed by a line break, as it is set to a value of 2. - \end{itemize} - - \paragraph{Double back slash poly-switches for optional and mandatory arguments} - For clarity, we provide a demonstration of controlling the double back slash - poly-switches for optional and mandatory arguments. We begin with the code in - \cref{lst:mycommand2}. \index{poly-switches!for double back slash (delimiters)} - - \cmhlistingsfromfile{demonstrations/mycommand2.tex}{\texttt{mycommand2.tex}}{lst:mycommand2} - - Upon using the YAML settings in \cref{lst:DBS6,lst:DBS7}, and running the command - \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m mycommand2.tex -l DBS6.yaml -latexindent.pl -m mycommand2.tex -l DBS7.yaml -\end{commandshell} - then we receive the output given in \cref{lst:mycommand2-DBS6,lst:mycommand2-DBS7}. - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-.1\textwidth}, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/mycommand2-mod6.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS6}}{lst:mycommand2-DBS6} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS6.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS6.yaml}}{lst:DBS6} - \end{cmhtcbraster} - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-.1\textwidth}, - raster column skip=.03\linewidth] - \cmhlistingsfromfile{demonstrations/mycommand2-mod7.tex}{\texttt{mycommand2.tex} using \cref{lst:DBS7}}{lst:mycommand2-DBS7} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/DBS7.yaml}[MLB-TCB,width=0.6\textwidth]{\texttt{DBS7.yaml}}{lst:DBS7} - \end{cmhtcbraster} - - \paragraph{Double back slash optional square brackets} - The pattern matching for the double back slash will also, optionally, allow trailing - square brackets that contain a measurement of vertical spacing, for example - \lstinline!\\[3pt]!. \index{poly-switches!for double back slash (delimiters)} - - For example, beginning with the code in \cref{lst:pmatrix3} - - \cmhlistingsfromfile{demonstrations/pmatrix3.tex}{\texttt{pmatrix3.tex}}{lst:pmatrix3} - - and running the following command, using \cref{lst:DBS3}, \index{switches!-l - demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m pmatrix3.tex -l DBS3.yaml -\end{commandshell} - then we receive the output given in \cref{lst:pmatrix3-DBS3}. - - \cmhlistingsfromfile{demonstrations/pmatrix3-mod3.tex}{\texttt{pmatrix3.tex} using \cref{lst:DBS3}}{lst:pmatrix3-DBS3} - - You can customise the pattern for the double back slash by exploring the \emph{fine - tuning} field detailed in \vref{lst:fineTuning}. - -\subsubsection{Poly-switches for other code blocks} - Rather than repeat the examples shown for the environment code blocks (in - \vref{sec:modifylinebreaks-environments}), we choose to detail the poly-switches for all - other code blocks in \cref{tab:poly-switch-mapping}; note that each and every one of - these poly-switches is \emph{off by default}, i.e, set to \texttt{0}. - - Note also that, by design, line breaks involving, \texttt{filecontents} and - `comment-marked' code blocks (\vref{lst:alignmentmarkup}) can \emph{not} be modified - using \texttt{latexindent.pl}. \announce{2019-05-05}*{verbatim poly-switch} However, - there are two poly-switches available for \texttt{verbatim} code blocks: environments - (\vref{lst:verbatimEnvironments}), commands (\vref{lst:verbatimCommands}) and - \texttt{specialBeginEnd} (\vref{lst:special-verb1-yaml}). - \index{specialBeginEnd!poly-switch summary} \index{verbatim!poly-switch summary} - \index{poly-switches!summary of all poly-switches}% - - \clearpage - \begin{longtable}{llll} - \caption{Poly-switch mappings for all code-block types}\label{tab:poly-switch-mapping} \\ - \toprule - Code block & Sample & \multicolumn{2}{c}{Poly-switch mapping} \\ - \midrule - environment & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & BeginStartsOnOwnLine \\ - & \verb!\begin{myenv}!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ - & \verb!body of myenv!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & EndStartsOnOwnLine \\ - & \verb!\end{myenv}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & EndFinishesWithLineBreak \\ - & \verb!after words! & & \\ - \cmidrule{2-4} - ifelsefi & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & IfStartsOnOwnLine \\ - & \verb!\if...!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & BodyStartsOnOwnLine \\ - & \verb!body of if/or statement!$\OrStartsOnOwnLine$ & $\OrStartsOnOwnLine$ & OrStartsOnOwnLine % - \announce{2018-04-27}{new ifElseFi code block poly-switches} \\ - & \verb!\or!$\OrFinishesWithLineBreak$ & $\OrFinishesWithLineBreak$ & OrFinishesWithLineBreak \\ - & \verb!body of if/or statement!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & ElseStartsOnOwnLine \\ - & \verb!\else!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & ElseFinishesWithLineBreak \\ - & \verb!body of else statement!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & FiStartsOnOwnLine \\ - & \verb!\fi!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & FiFinishesWithLineBreak \\ - & \verb!after words! & & \\ - \cmidrule{2-4} - optionalArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LSqBStartsOnOwnLine\footnote{LSqB stands for Left Square Bracket} \\ - & \verb![!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & OptArgBodyStartsOnOwnLine \\ - \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ - & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ - & \verb!end of body of opt arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RSqBStartsOnOwnLine \\ - & \verb!]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RSqBFinishesWithLineBreak \\ - & \verb!...! & & \\ - \cmidrule{2-4} - mandatoryArguments & \verb!...!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & LCuBStartsOnOwnLine\footnote{LCuB stands for Left Curly Brace} \\ - & \verb!{!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & MandArgBodyStartsOnOwnLine \\ - \announce{2019-07-13}{new comma-related poly-switches} & \verb!value before comma!$\ElseStartsOnOwnLine$, & $\ElseStartsOnOwnLine$ & CommaStartsOnOwnLine \\ - & $\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & CommaFinishesWithLineBreak \\ - & \verb!end of body of mand arg!$\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & RCuBStartsOnOwnLine \\ - & \verb!}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & RCuBFinishesWithLineBreak \\ - & \verb!...! & & \\ - \cmidrule{2-4} - commands & \verb!before words!$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & CommandStartsOnOwnLine \\ - & \verb!\mycommand!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & CommandNameFinishesWithLineBreak \\ - & $\langle$\itshape{arguments}$\rangle$ & & \\ - \cmidrule{2-4} - namedGroupingBracesBrackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & NameStartsOnOwnLine \\ - & myname$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & NameFinishesWithLineBreak \\ - & $\langle$\itshape{braces/brackets}$\rangle$ & & \\ - \cmidrule{2-4} - keyEqualsValuesBraces\newline Brackets & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & KeyStartsOnOwnLine \\ - & key$\EqualsStartsOnOwnLine$=$\BodyStartsOnOwnLine$ & $\EqualsStartsOnOwnLine$ & EqualsStartsOnOwnLine \\ - & $\langle$\itshape{braces/brackets}$\rangle$ & $\BodyStartsOnOwnLine$ & EqualsFinishesWithLineBreak \\ - \cmidrule{2-4} - items & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & ItemStartsOnOwnLine \\ - & \verb!\item!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & ItemFinishesWithLineBreak \\ - & \verb!...! & & \\ - \cmidrule{2-4} - specialBeginEnd & before words$\BeginStartsOnOwnLine$ & $\BeginStartsOnOwnLine$ & SpecialBeginStartsOnOwnLine \\ - & \verb!\[!$\BodyStartsOnOwnLine$ & $\BodyStartsOnOwnLine$ & SpecialBodyStartsOnOwnLine \\ - & \verb!body of special/middle!$\ElseStartsOnOwnLine$ & $\ElseStartsOnOwnLine$ & SpecialMiddleStartsOnOwnLine % - \announce{2018-04-27}{new special code block poly-switches} \\ - & \verb!\middle!$\ElseFinishesWithLineBreak$ & $\ElseFinishesWithLineBreak$ & SpecialMiddleFinishesWithLineBreak \\ - & body of special/middle $\EndStartsOnOwnLine$ & $\EndStartsOnOwnLine$ & SpecialEndStartsOnOwnLine \\ - & \verb!\]!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & SpecialEndFinishesWithLineBreak \\ - & after words & & \\ - \cmidrule{2-4} - verbatim & before words$\BeginStartsOnOwnLine$\verb!\begin{verbatim}! & $\BeginStartsOnOwnLine$ & VerbatimBeginStartsOnOwnLine \\ - \announce{2019-05-05}{verbatim poly-switches} & body of verbatim \verb!\end{verbatim}!$\EndFinishesWithLineBreak$ & $\EndFinishesWithLineBreak$ & VerbatimEndFinishesWithLineBreak \\ - & after words & & \\ - \bottomrule - \end{longtable} -\subsubsection{Partnering BodyStartsOnOwnLine with argument-based poly-switches} - Some poly-switches need to be partnered together; in particular, when line breaks - involving the \emph{first} argument of a code block need to be accounted for using both - \texttt{BodyStartsOnOwnLine} (or its equivalent, see \vref{tab:poly-switch-mapping}) and - \texttt{LCuBStartsOnOwnLine} for mandatory arguments, and \texttt{LSqBStartsOnOwnLine} - for optional arguments. \index{poly-switches!conflicting partnering} - - Let's begin with the code in \cref{lst:mycommand1} and the YAML settings in - \cref{lst:mycom-mlb1}; with reference to \vref{tab:poly-switch-mapping}, the key - \texttt{CommandNameFinishesWithLineBreak} is an alias for \texttt{BodyStartsOnOwnLine}. - - \cmhlistingsfromfile{demonstrations/mycommand1.tex}{\texttt{mycommand1.tex}}{lst:mycommand1} - - Upon running the command \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl -m -l=mycom-mlb1.yaml mycommand1.tex -\end{commandshell} - we obtain \cref{lst:mycommand1-mlb1}; note that the \emph{second} mandatory argument - beginning brace \lstinline!{! has had its leading line break removed, but that the - \emph{first} brace has not. - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-1cm}, - ] - \cmhlistingsfromfile{demonstrations/mycommand1-mlb1.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb1}}{lst:mycommand1-mlb1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb1.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb1.yaml}}{lst:mycom-mlb1} - \end{cmhtcbraster} - - Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb2}; upon running - the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb2}; both - beginning braces \lstinline!{! have had their leading line breaks removed. - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-1cm}, - ] - \cmhlistingsfromfile{demonstrations/mycommand1-mlb2.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb2}}{lst:mycommand1-mlb2} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb2.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb2.yaml}}{lst:mycom-mlb2} - \end{cmhtcbraster} - - Now let's change the YAML file so that it is as in \cref{lst:mycom-mlb3}; upon running - the analogous command to that given above, we obtain \cref{lst:mycommand1-mlb3}. - - \begin{cmhtcbraster}[ - raster force size=false, - raster column 1/.style={add to width=-1cm}, - ] - \cmhlistingsfromfile{demonstrations/mycommand1-mlb3.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb3}}{lst:mycommand1-mlb3} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb3.yaml}[MLB-TCB,width=.6\textwidth]{\texttt{mycom-mlb3.yaml}}{lst:mycom-mlb3} - \end{cmhtcbraster} - -\subsubsection{Conflicting poly-switches: sequential code blocks} - It is very easy to have conflicting poly-switches; if we use the example from - \vref{lst:mycommand1}, and consider the YAML settings given in \cref{lst:mycom-mlb4}. The - output from running \index{poly-switches!conflicting switches} \index{switches!-l - demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m -l=mycom-mlb4.yaml mycommand1.tex -\end{commandshell} - is given in \cref{lst:mycom-mlb4}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/mycommand1-mlb4.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb4}}{lst:mycommand1-mlb4} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb4.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb4.yaml}}{lst:mycom-mlb4} - \end{cmhtcbraster} - - Studying \cref{lst:mycom-mlb4}, we see that the two poly-switches are at opposition with - one another: - \begin{itemize} - \item on the one hand, \texttt{LCuBStartsOnOwnLine} should \emph{not} start on its own line (as - poly-switch is set to $-1$); - \item on the other hand, \texttt{RCuBFinishesWithLineBreak} \emph{should} finish with a line - break. - \end{itemize} - So, which should win the conflict? As demonstrated in \cref{lst:mycommand1-mlb4}, it is - clear that \texttt{LCuBStartsOnOwnLine} won this conflict, and the reason is that - \emph{the second argument was processed after the first} -- in general, the most - recently-processed code block and associated poly-switch takes priority. - - We can explore this further by considering the YAML settings in \cref{lst:mycom-mlb5}; - upon running the command \index{switches!-l demonstration} \index{switches!-m - demonstration} - \begin{commandshell} -latexindent.pl -m -l=mycom-mlb5.yaml mycommand1.tex -\end{commandshell} - we obtain the output given in \cref{lst:mycommand1-mlb5}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/mycommand1-mlb5.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb5}}{lst:mycommand1-mlb5} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb5.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb5.yaml}}{lst:mycom-mlb5} - \end{cmhtcbraster} - - As previously, the most-recently-processed code block takes priority -- as before, the - second (i.e, \emph{last}) argument. Exploring this further, we consider the YAML settings - in \cref{lst:mycom-mlb6}, which give associated output in \cref{lst:mycommand1-mlb6}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/mycommand1-mlb6.tex}{\texttt{mycommand1.tex} using \cref{lst:mycom-mlb6}}{lst:mycommand1-mlb6} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycom-mlb6.yaml}[MLB-TCB,width=\linewidth]{\texttt{mycom-mlb6.yaml}}{lst:mycom-mlb6} - \end{cmhtcbraster} - - Note that a \lstinline!%! \emph{has} been added to the trailing first \lstinline!}!; this - is because: - \begin{itemize} - \item while processing the \emph{first} argument, the trailing line break has been removed - (\texttt{RCuBFinishesWithLineBreak} set to $-1$); - \item while processing the \emph{second} argument, \texttt{latexindent.pl} finds that it does - \emph{not} begin on its own line, and so because \texttt{LCuBStartsOnOwnLine} is set to - $2$, it adds a comment, followed by a line break. - \end{itemize} - -\subsubsection{Conflicting poly-switches: nested code blocks} - Now let's consider an example when nested code blocks have conflicting poly-switches; - we'll use the code in \cref{lst:nested-env}, noting that it contains nested environments. - \index{poly-switches!conflicting switches} - - \cmhlistingsfromfile{demonstrations/nested-env.tex}{\texttt{nested-env.tex}}{lst:nested-env} - - Let's use the YAML settings given in \cref{lst:nested-env-mlb1-yaml}, which upon running - the command \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m -l=nested-env-mlb1.yaml nested-env.tex -\end{commandshell} - gives the output in \cref{lst:nested-env-mlb1}. - - \begin{cmhtcbraster}[raster column skip=.05\linewidth] - \cmhlistingsfromfile{demonstrations/nested-env-mlb1.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb1-yaml}}{lst:nested-env-mlb1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb1.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb1.yaml}}{lst:nested-env-mlb1-yaml} - \end{cmhtcbraster} - - In \cref{lst:nested-env-mlb1}, let's first of all note that both environments have - received the appropriate (default) indentation; secondly, note that the poly-switch - \texttt{EndStartsOnOwnLine} appears to have won the conflict, as \lstinline!\end{one}! - has had its leading line break removed. - - To understand it, let's talk about the three basic phases \label{page:phases}of - \texttt{latexindent.pl}: - \begin{enumerate} - \item Phase 1: packing, in which code blocks are replaced with unique ids, working from - \emph{the inside to the outside}, and then sequentially -- for example, in - \cref{lst:nested-env}, the \texttt{two} environment is found \emph{before} the - \texttt{one} environment; if the -m switch is active, then during this phase: - \begin{itemize} - \item line breaks at the beginning of the \texttt{body} can be added (if - \texttt{BodyStartsOnOwnLine} is $1$ or $2$) or removed (if \texttt{BodyStartsOnOwnLine} - is $-1$); - \item line breaks at the end of the body can be added (if \texttt{EndStartsOnOwnLine} is $1$ or - $2$) or removed (if \texttt{EndStartsOnOwnLine} is $-1$); - \item line breaks after the end statement can be added (if \texttt{EndFinishesWithLineBreak} is - $1$ or $2$). - \end{itemize} - \item Phase 2: indentation, in which white space is added to the begin, body, and end - statements; - \item Phase 3: unpacking, in which unique ids are replaced by their \emph{indented} code - blocks; if the -m switch is active, then during this phase, - \begin{itemize} - \item line breaks before \texttt{begin} statements can be added or removed (depending upon - \texttt{BeginStartsOnOwnLine}); - \item line breaks after \emph{end} statements can be removed but \emph{NOT} added (see - \texttt{EndFinishesWithLineBreak}). - \end{itemize} - \end{enumerate} - - With reference to \cref{lst:nested-env-mlb1}, this means that during Phase 1: - \begin{itemize} - \item the \texttt{two} environment is found first, and the line break ahead of the - \lstinline!\end{two}! statement is removed because \texttt{EndStartsOnOwnLine} is set to - $-1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} - finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. - \item next, the \texttt{one} environment is found; the line break ahead of - \lstinline!\end{one}! is removed because \texttt{EndStartsOnOwnLine} is set to $-1$. - \end{itemize} - The indentation is done in Phase 2; in Phase 3 \emph{there is no option to add a line - break after the \lstinline!end! statements}. We can justify this by remembering that - during Phase 3, the \texttt{one} environment will be found and processed first, followed - by the \texttt{two} environment. If the \texttt{two} environment were to add a line break - after the \lstinline!\end{two}! statement, then \texttt{latexindent.pl} would have no way - of knowing how much indentation to add to the subsequent text (in this case, - \lstinline!\end{one}!). - - We can explore this further using the poly-switches in \cref{lst:nested-env-mlb2}; upon - running the command \index{switches!-l demonstration} \index{switches!-m demonstration} - \begin{commandshell} -latexindent.pl -m -l=nested-env-mlb2.yaml nested-env.tex -\end{commandshell} - we obtain the output given in \cref{lst:nested-env-mlb2-output}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/nested-env-mlb2.tex}{\texttt{nested-env.tex} using \cref{lst:nested-env-mlb2}}{lst:nested-env-mlb2-output} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/nested-env-mlb2.yaml}[MLB-TCB,width=\linewidth]{\texttt{nested-env-mlb2.yaml}}{lst:nested-env-mlb2} - \end{cmhtcbraster} - - During Phase 1: - \begin{itemize} - \item the \texttt{two} environment is found first, and the line break ahead of the - \lstinline!\end{two}! statement is not changed because \texttt{EndStartsOnOwnLine} is set - to $1$. Importantly, because, \emph{at this stage}, \lstinline!\end{two}! \emph{does} - finish with a line break, \texttt{EndFinishesWithLineBreak} causes no action. - \item next, the \texttt{one} environment is found; the line break ahead of - \lstinline!\end{one}! is already present, and no action is needed. - \end{itemize} - The indentation is done in Phase 2, and then in Phase 3, the \texttt{one} environment is - found and processed first, followed by the \texttt{two} environment. \emph{At this - stage}, the \texttt{two} environment finds \texttt{EndFinishesWithLineBreak} is $-1$, so - it removes the trailing line break; remember, at this point, \texttt{latexindent.pl} has - completely finished with the \texttt{one} environment. diff --git a/support/latexindent/documentation/subsec-text-wrap.tex b/support/latexindent/documentation/subsec-text-wrap.tex deleted file mode 100644 index e17188267a..0000000000 --- a/support/latexindent/documentation/subsec-text-wrap.tex +++ /dev/null @@ -1,513 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsection{Text Wrapping}\label{subsec:textwrapping} - \announce{2022-03-13}{text wrap overhaul}\emph{The text wrapping routine has been over-hauled as - of V3.16; I hope that the interface is simpler, and most importantly, the results are - better}. - - The complete settings for this feature are given in \cref{lst:textWrapOptionsAll}. - - \cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} - -\subsubsection{Text wrap: overview} - An overview of how the text wrapping feature works: - \begin{enumerate} - \item the default value of \texttt{columns} is 0, which means that text wrapping will - \emph{not} happen by default; - \item it happens \emph{after} verbatim blocks have been found; - \item it happens \emph{after} the oneSentencePerLine routine (see - \cref{sec:onesentenceperline}); - \item it happens \emph{before} all of the other code blocks are found and does \emph{not} - operate on a per-code-block basis; this means that, including indentation, you may - receive a column width wider than that which you specify in \texttt{columns} - \item code blocks to be text wrapped will: - \begin{enumerate} - \item \emph{follow} the fields specified in \texttt{blocksFollow} - \item \emph{begin} with the fields specified in \texttt{blocksBeginWith} - \item \emph{end} before the fields specified in \texttt{blocksEndBefore} - \end{enumerate} - \item setting \texttt{columns} to a value $>0$ will text wrap blocks by first removing line - breaks, and then wrapping according to the specified value of \texttt{columns}; - \item setting \texttt{columns} to $-1$ will \emph{only} remove line breaks within the text wrap - block; - \item by default, the text wrapping routine will remove line breaks within text blocks because - \texttt{removeBlockLineBreaks} is set to 1; switch it to 0 if you wish to change this; - \item about trailing comments within text wrap blocks: - \begin{enumerate} - \item trailing comments that do \emph{not} have leading space instruct the text wrap routine to - connect the lines \emph{without} space (see \cref{lst:tw-tc2}); - \item multiple trailing comments will be connected at the end of the text wrap block (see - \cref{lst:tw-tc4}); - \item the number of spaces between the end of the text wrap block and the (possibly combined) - trailing comments is determined by the spaces (if any) at the end of the text wrap block - (see \cref{lst:tw-tc5}). - \end{enumerate} - \end{enumerate} - - We demonstrate this feature using a series of examples. - -\subsubsection{Text wrap: simple examples}\label{subsec:textwrapping-quick-start} - - \begin{example} - Let's use the sample text given in \cref{lst:textwrap1}. \index{text wrap!quick start} - - \cmhlistingsfromfile{demonstrations/textwrap1.tex}{\texttt{textwrap1.tex}}{lst:textwrap1} - - We will change the value of \texttt{columns} in \cref{lst:textwrap1-yaml} and then run - the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml textwrap1.tex -\end{commandshell} - then we receive the output given in \cref{lst:textwrap1-mod1}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/textwrap1-mod1.tex}{\texttt{textwrap1-mod1.tex}}{lst:textwrap1-mod1} - \cmhlistingsfromfile{demonstrations/textwrap1.yaml}[MLB-TCB]{\texttt{textwrap1.yaml}}{lst:textwrap1-yaml} - \end{cmhtcbraster} - \end{example} - - \begin{example} - If we set \texttt{columns} to $-1$ then \texttt{latexindent.pl} remove line breaks within - the text wrap block, and will \emph{not} perform text wrapping. We can use this to undo - text wrapping. \index{text wrap!setting columns to -1} - - Starting from the file in \cref{lst:textwrap1-mod1} and using the settings in - \cref{lst:textwrap1A-yaml} - - \cmhlistingsfromfile{demonstrations/textwrap1A.yaml}[MLB-TCB]{\texttt{textwrap1A.yaml}}{lst:textwrap1A-yaml} - - and running - \begin{commandshell} -latexindent.pl -m -l textwrap1A.yaml textwrap1-mod1.tex -\end{commandshell} - gives the output in \cref{lst:textwrap1-mod1A}. - - \cmhlistingsfromfile{demonstrations/textwrap1-mod1A.tex}{\texttt{textwrap1-mod1A.tex}}{lst:textwrap1-mod1A} - \end{example} - - \begin{example} - By default, the text wrapping routine will convert multiple spaces into single spaces. - You can change this behaviour by flicking the switch \texttt{multipleSpacesToSingle} - which we have done in \cref{lst:textwrap1B-yaml} - - Using the settings in \cref{lst:textwrap1B-yaml} and running - \begin{commandshell} -latexindent.pl -m -l textwrap1B.yaml textwrap1-mod1.tex -\end{commandshell} - gives the output in \cref{lst:textwrap1-mod1B}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/textwrap1B.yaml}[MLB-TCB]{\texttt{textwrap1B.yaml}}{lst:textwrap1B-yaml} - \cmhlistingsfromfile[showspaces=true]{demonstrations/textwrap1-mod1B.tex}{\texttt{textwrap1-mod1B.tex}}{lst:textwrap1-mod1B} - \end{cmhtcbraster} - We note that in \cref{lst:textwrap1-mod1B} the multiple spaces have \emph{not} been - condensed into single spaces. - \end{example} - -\subsubsection{Text wrap: \texttt{blocksFollow} examples} - We examine the \texttt{blocksFollow} field of \cref{lst:textWrapOptionsAll}. \index{text - wrap!blocksFollow} - - \begin{example} - Let's use the sample text given in \cref{lst:tw-headings1}. \index{text - wrap!blocksFollow!headings} - - \cmhlistingsfromfile{demonstrations/tw-headings1.tex}{\texttt{tw-headings1.tex}}{lst:tw-headings1} - - We note that \cref{lst:tw-headings1} contains the heading commands \texttt{section} and - \texttt{subsection}. Upon running the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml tw-headings1.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-headings1-mod1}. - - \cmhlistingsfromfile{demonstrations/tw-headings1-mod1.tex}{\texttt{tw-headings1-mod1.tex}}{lst:tw-headings1-mod1} - - We reference \vref{lst:textWrapOptionsAll} and also \vref{lst:indentAfterHeadings}: - \begin{itemize} - \item in \cref{lst:textWrapOptionsAll} the \texttt{headings} field is set to \texttt{1}, which - instructs \texttt{latexindent.pl} to read the fields from \vref{lst:indentAfterHeadings}, - \emph{regardless of the value of indentAfterThisHeading or level}; - \item the default is to assume that the heading command can, optionally, be followed by a - \texttt{label} command. - \end{itemize} - If you find scenarios in which the default value of \texttt{headings} does not work, then - you can explore the \texttt{other} field. - - We can turn off \texttt{headings} as in \cref{lst:bf-no-headings-yaml} and then run - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml,bf-no-headings.yaml tw-headings1.tex -\end{commandshell} - gives the output in \cref{lst:tw-headings1-mod2}, in which text wrapping has been - instructed \emph{not to happen} following headings. - \begin{cmhtcbraster}[raster column skip=.1\linewidth, - raster left skip=-3.5cm, - raster right skip=-2cm, - ] - \cmhlistingsfromfile{demonstrations/bf-no-headings.yaml}[MLB-TCB]{\texttt{bf-no-headings.yaml}}{lst:bf-no-headings-yaml} - \cmhlistingsfromfile{demonstrations/tw-headings1-mod2.tex}{\texttt{tw-headings1-mod2.tex}}{lst:tw-headings1-mod2} - \end{cmhtcbraster} - \end{example} - - \begin{example} - Let's use the sample text given in \cref{lst:tw-comments1}. \index{text - wrap!blocksFollow!comments} - - \cmhlistingsfromfile{demonstrations/tw-comments1.tex}{\texttt{tw-comments1.tex}}{lst:tw-comments1} - - We note that \cref{lst:tw-comments1} contains trailing comments. Upon running the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml tw-comments1.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-comments1-mod1}. - - \cmhlistingsfromfile{demonstrations/tw-comments1-mod1.tex}{\texttt{tw-comments1-mod1.tex}}{lst:tw-comments1-mod1} - - With reference to \vref{lst:textWrapOptionsAll} the \texttt{commentOnPreviousLine} field - is set to \texttt{1}, which instructs \texttt{latexindent.pl} to find text wrap blocks - after a comment on its own line. - - We can turn off \texttt{comments} as in \cref{lst:bf-no-comments-yaml} and then run - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml,bf-no-comments.yaml tw-comments1.tex -\end{commandshell} - gives the output in \cref{lst:tw-comments1-mod2}, in which text wrapping has been - instructed \emph{not to happen} following comments on their own line. - \begin{cmhtcbraster}[raster column skip=.1\linewidth, - raster left skip=-3.5cm, - raster right skip=-2cm, - ] - \cmhlistingsfromfile{demonstrations/bf-no-comments.yaml}[MLB-TCB]{\texttt{bf-no-comments.yaml}}{lst:bf-no-comments-yaml} - \cmhlistingsfromfile{demonstrations/tw-comments1-mod2.tex}{\texttt{tw-comments1-mod2.tex}}{lst:tw-comments1-mod2} - \end{cmhtcbraster} - \end{example} - - Referencing \vref{lst:textWrapOptionsAll} the \texttt{blocksFollow} fields \texttt{par}, - \texttt{blankline}, \texttt{verbatim} and \texttt{filecontents} fields operate in - analogous ways to those demonstrated in the above. - - The \texttt{other} field of the \texttt{blocksFollow} can either be \texttt{0} (turned - off) or set as a regular expression. The default value is set to - \lstinline!\\\]|\\item(?:\h|\[)! which can be translated to \emph{backslash followed by a - square bracket} or \emph{backslash item followed by horizontal space or a square - bracket}, or in other words, \emph{end of display math} or an item command. - - \begin{example} - Let's use the sample text given in \cref{lst:tw-disp-math1}. \index{text - wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow} - - \cmhlistingsfromfile{demonstrations/tw-disp-math1.tex}{\texttt{tw-disp-math1.tex}}{lst:tw-disp-math1} - - We note that \cref{lst:tw-disp-math1} contains display math. Upon running the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml tw-disp-math1.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-disp-math1-mod1}. - - \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod1.tex}{\texttt{tw-disp-math1-mod1.tex}}{lst:tw-disp-math1-mod1} - - With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to - \lstinline!\\\]!, which instructs \texttt{latexindent.pl} to find text wrap blocks after - the end of display math. - - We can turn off this switch as in \cref{lst:bf-no-disp-math-yaml} and then run - \begin{widepage} - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml,bf-no-disp-math.yaml tw-disp-math1.tex -\end{commandshell} - \end{widepage} - gives the output in \cref{lst:tw-disp-math1-mod2}, in which text wrapping has been - instructed \emph{not to happen} following display math. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/bf-no-disp-math.yaml}[MLB-TCB]{\texttt{bf-no-disp-math.yaml}}{lst:bf-no-disp-math-yaml} - \cmhlistingsfromfile{demonstrations/tw-disp-math1-mod2.tex}{\texttt{tw-disp-math1-mod2.tex}}{lst:tw-disp-math1-mod2} - \end{cmhtcbraster} - - Naturally, you should feel encouraged to customise this as you see fit. - \end{example} - - The \texttt{blocksFollow} field \emph{deliberately} does not default to allowing text - wrapping to occur after \texttt{begin environment} statements. You are encouraged to - customize the \texttt{other} field to accomodate the environments that you would like to - text wrap individually, as in the next example. - - \begin{example} - Let's use the sample text given in \cref{lst:tw-bf-myenv1}. \index{text - wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow} - - \cmhlistingsfromfile{demonstrations/tw-bf-myenv1.tex}{\texttt{tw-bf-myenv1.tex}}{lst:tw-bf-myenv1} - - We note that \cref{lst:tw-bf-myenv1} contains \texttt{myenv} environment. Upon running - the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml tw-bf-myenv1.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-bf-myenv1-mod1}. - - \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod1.tex}{\texttt{tw-bf-myenv1-mod1.tex}}{lst:tw-bf-myenv1-mod1} - - We note that we have \emph{not} received much text wrapping. We can turn do better by - employing \cref{lst:tw-bf-myenv-yaml} and then run - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml,tw-bf-myenv.yaml tw-bf-myenv1.tex -\end{commandshell} - which gives the output in \cref{lst:tw-bf-myenv1-mod2}, in which text wrapping has been - implemented across the file. - \begin{cmhtcbraster}[raster column skip=.1\linewidth, - raster left skip=-3.5cm, - raster right skip=-2cm, - ] - \cmhlistingsfromfile{demonstrations/tw-bf-myenv.yaml}[MLB-TCB]{\texttt{tw-bf-myenv.yaml}}{lst:tw-bf-myenv-yaml} - \cmhlistingsfromfile{demonstrations/tw-bf-myenv1-mod2.tex}{\texttt{tw-bf-myenv1-mod2.tex}}{lst:tw-bf-myenv1-mod2} - \end{cmhtcbraster} - - \end{example} - -\subsubsection{Text wrap: \texttt{blocksBeginWith} examples} - We examine the \texttt{blocksBeginWith} field of \cref{lst:textWrapOptionsAll} with a - series of examples. \index{text wrap!blocksBeginWith} - - \begin{example} - By default, text wrap blocks can begin with the characters \texttt{a-z} and \texttt{A-Z}. - - If we start with the file given in \cref{lst:tw-0-9} - \cmhlistingsfromfile{demonstrations/tw-0-9.tex}{\texttt{tw-0-9.tex}}{lst:tw-0-9} - and run the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml tw-0-9.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-0-9-mod1} in which text wrapping has - \emph{not} occured. - \cmhlistingsfromfile{demonstrations/tw-0-9-mod1.tex}{\texttt{tw-0-9-mod1.tex}}{lst:tw-0-9-mod1} - - We can allow paragraphs to begin with \texttt{0-9} characters by using the settings in - \cref{lst:bb-0-9-yaml} and running - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml,bb-0-9-yaml tw-0-9.tex -\end{commandshell} - gives the output in \cref{lst:tw-0-9-mod2}, in which text wrapping \emph{has} happened. - \begin{cmhtcbraster}[raster column skip=.1\linewidth,] - \cmhlistingsfromfile{demonstrations/bb-0-9.yaml}[MLB-TCB]{\texttt{bb-0-9.yaml.yaml}}{lst:bb-0-9-yaml} - \cmhlistingsfromfile{demonstrations/tw-0-9-mod2.tex}{\texttt{tw-0-9-mod2.tex}}{lst:tw-0-9-mod2} - \end{cmhtcbraster} - \end{example} - - \begin{example} - Let's now use the file given in \cref{lst:tw-bb-announce1} - \cmhlistingsfromfile{demonstrations/tw-bb-announce1.tex}{\texttt{tw-bb-announce1.tex}}{lst:tw-bb-announce1} - and run the command - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml tw-bb-announce1.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-bb-announce1-mod1} in which text - wrapping has \emph{not} occured. - - \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod1.tex}{\texttt{tw-bb-announce1-mod1.tex}}{lst:tw-bb-announce1-mod1} - - We can allow \lstinline!\announce! to be at the beginning of paragraphs by using the - settings in \cref{lst:tw-bb-announce-yaml} and running - \begin{widepage} - \begin{commandshell} -latexindent.pl -m -l textwrap1.yaml,tw-bb-announce.yaml tw-bb-announce1.tex -\end{commandshell} - \end{widepage} - gives the output in \cref{lst:tw-bb-announce1-mod2}, in which text wrapping \emph{has} - happened. - \begin{cmhtcbraster}[raster column skip=.1\linewidth,] - \cmhlistingsfromfile{demonstrations/tw-bb-announce.yaml}[MLB-TCB]{\texttt{tw-bb-announce.yaml}}{lst:tw-bb-announce-yaml} - \cmhlistingsfromfile{demonstrations/tw-bb-announce1-mod2.tex}{\texttt{tw-bb-announce1-mod2.tex}}{lst:tw-bb-announce1-mod2} - \end{cmhtcbraster} - - \end{example} - -\subsubsection{Text wrap: \texttt{blocksEndBefore} examples} - We examine the \texttt{blocksEndBefore} field of \cref{lst:textWrapOptionsAll} with a - series of examples. \index{text wrap!blocksEndBefore} - - \begin{example} - Let's use the sample text given in \cref{lst:tw-be-equation}. \index{text - wrap!blocksFollow!other} \index{regular expressions!text wrap!blocksFollow} - - \cmhlistingsfromfile{demonstrations/tw-be-equation.tex}{\texttt{tw-be-equation.tex}}{lst:tw-be-equation} - - We note that \cref{lst:tw-be-equation} contains an environment. Upon running the command - \begin{commandshell} -latexindent.pl -m -l textwrap1A.yaml tw-be-equation.tex -\end{commandshell} - then we receive the output given in \cref{lst:tw-be-equation-mod1}. - - \cmhlistingsfromfile{demonstrations/tw-be-equation-mod1.tex}{\texttt{tw-be-equation-mod1.tex}}{lst:tw-be-equation-mod1} - - With reference to \vref{lst:textWrapOptionsAll} the \texttt{other} field is set to - \lstinline!\\begin\{|\\\[|\\end\{!, which instructs \texttt{latexindent.pl} to - \emph{stop} text wrap blocks before \texttt{begin} statements, display math, and - \texttt{end} statements. - - We can turn off this switch as in \cref{lst:tw-be-equation-yaml} and then run - \begin{widepage} - \begin{commandshell} -latexindent.pl -m -l textwrap1A.yaml,tw-be-equation.yaml tw-be-equation.tex -\end{commandshell} - \end{widepage} - gives the output in \cref{lst:tw-be-equation-mod2}, in which text wrapping has been - instructed \emph{not} to stop at these statements. - - \cmhlistingsfromfile{demonstrations/tw-be-equation.yaml}[MLB-TCB]{\texttt{tw-be-equation.yaml}}{lst:tw-be-equation-yaml} - - \begin{widepage} - \cmhlistingsfromfile{demonstrations/tw-be-equation-mod2.tex}{\texttt{tw-be-equation-mod2.tex}}{lst:tw-be-equation-mod2} - \end{widepage} - - Naturally, you should feel encouraged to customise this as you see fit. - \end{example} - -\subsubsection{Text wrap: trailing comments and spaces} - We explore the behaviour of the text wrap routine in relation to trailing comments using - the following examples. - - \begin{example} - The file in \cref{lst:tw-tc1} contains a trailing comment which \emph{does} have a space - infront of it. - - Running the command - \begin{commandshell} -latexindent.pl -m tw-tc1.tex -l textwrap1A.yaml -o=+-mod1 -\end{commandshell} - gives the output given in \cref{lst:tw-tc1-mod1}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc1.tex}{\texttt{tw-tc1.tex}}{lst:tw-tc1} - \cmhlistingsfromfile{demonstrations/tw-tc1-mod1.tex}{\texttt{tw-tc1-mod1.tex}}{lst:tw-tc1-mod1} - \end{cmhtcbraster} - \end{example} - - \begin{example} - The file in \cref{lst:tw-tc2} contains a trailing comment which does \emph{not} have a - space infront of it. - - Running the command - \begin{commandshell} -latexindent.pl -m tw-tc2.tex -l textwrap1A.yaml -o=+-mod1 -\end{commandshell} - gives the output in \cref{lst:tw-tc2-mod1}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/tw-tc2.tex}{\texttt{tw-tc2.tex}}{lst:tw-tc2} - \cmhlistingsfromfile{demonstrations/tw-tc2-mod1.tex}{\texttt{tw-tc2-mod1.tex}}{lst:tw-tc2-mod1} - \end{cmhtcbraster} - We note that, because there is \emph{not} a space before the trailing comment, that the - lines have been joined \emph{without} a space. - \end{example} - - \begin{example} - The file in \cref{lst:tw-tc3} contains multiple trailing comments. - - Running the command - \begin{commandshell} -latexindent.pl -m tw-tc3.tex -l textwrap1A.yaml -o=+-mod1 -\end{commandshell} - gives the output in \cref{lst:tw-tc3-mod1}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/tw-tc3.tex}{\texttt{tw-tc3.tex}}{lst:tw-tc3} - \cmhlistingsfromfile{demonstrations/tw-tc3-mod1.tex}{\texttt{tw-tc3-mod1.tex}}{lst:tw-tc3-mod1} - \end{cmhtcbraster} - \end{example} - - \begin{example} - The file in \cref{lst:tw-tc4} contains multiple trailing comments. - - Running the command - \begin{commandshell} -latexindent.pl -m tw-tc4.tex -l textwrap1A.yaml -o=+-mod1 -\end{commandshell} - gives the output in \cref{lst:tw-tc4-mod1}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/tw-tc4.tex}{\texttt{tw-tc4.tex}}{lst:tw-tc4} - \cmhlistingsfromfile{demonstrations/tw-tc4-mod1.tex}{\texttt{tw-tc4-mod1.tex}}{lst:tw-tc4-mod1} - \end{cmhtcbraster} - \end{example} - - \begin{example} - The file in \cref{lst:tw-tc5} contains multiple trailing comments. - - Running the command - \begin{commandshell} -latexindent.pl -m tw-tc5.tex -l textwrap1A.yaml -o=+-mod1 -\end{commandshell} - gives the output in \cref{lst:tw-tc5-mod1}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5.tex}{\texttt{tw-tc5.tex}}{lst:tw-tc5} - \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc5-mod1.tex}{\texttt{tw-tc5-mod1.tex}}{lst:tw-tc5-mod1} - \end{cmhtcbraster} - The space at the end of the text block has been preserved. - \end{example} - - \begin{example} - The file in \cref{lst:tw-tc6} contains multiple trailing comments. - - Running the command - \begin{commandshell} -latexindent.pl -m tw-tc6.tex -l textwrap1A.yaml -o=+-mod1 -\end{commandshell} - gives the output in \cref{lst:tw-tc6-mod1}. - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6.tex}{\texttt{tw-tc6.tex}}{lst:tw-tc6} - \cmhlistingsfromfile[showspaces=true]{demonstrations/tw-tc6-mod1.tex}{\texttt{tw-tc6-mod1.tex}}{lst:tw-tc6-mod1} - \end{cmhtcbraster} - The space at the end of the text block has been preserved. - \end{example} - -\subsubsection{Text wrap: huge, tabstop and separator} - The \announce{2021-07-23}*{huge:overflow is now default} default value of \texttt{huge} - is \texttt{overflow}, which means that words will \emph{not} be broken by the text - wrapping routine, implemented by the \texttt{Text::Wrap} \cite{textwrap}. There are - options to change the \texttt{huge} option for the \texttt{Text::Wrap} module to either - \texttt{wrap} or \texttt{die}. Before modifying the value of \texttt{huge}, please bear - in mind the following warning: \index{warning!changing huge (textwrap)}% - \begin{warning} - \raggedright - Changing the value of \texttt{huge} to anything other than \texttt{overflow} will slow - down \texttt{latexindent.pl} significantly when the \texttt{-m} switch is active. - - Furthermore, changing \texttt{huge} means that you may have some words \emph{or - commands}(!) split across lines in your .tex file, which may affect your output. I do not - recommend changing this field. - \end{warning} - - For example, using the settings in \cref{lst:textwrap2A-yaml,lst:textwrap2B-yaml} and - running the commands \index{switches!-l demonstration} \index{switches!-m demonstration} - \index{switches!-o demonstration} - \begin{commandshell} - latexindent.pl -m textwrap4.tex -o=+-mod2A -l textwrap2A.yaml - latexindent.pl -m textwrap4.tex -o=+-mod2B -l textwrap2B.yaml -\end{commandshell} - gives the respective output in \cref{lst:textwrap4-mod2A,lst:textwrap4-mod2B}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/textwrap4-mod2A.tex}{\texttt{textwrap4-mod2A.tex}}{lst:textwrap4-mod2A} - \cmhlistingsfromfile{demonstrations/textwrap2A.yaml}[MLB-TCB]{\texttt{textwrap2A.yaml}}{lst:textwrap2A-yaml} - - \cmhlistingsfromfile{demonstrations/textwrap4-mod2B.tex}{\texttt{textwrap4-mod2B.tex}}{lst:textwrap4-mod2B} - \cmhlistingsfromfile{demonstrations/textwrap2B.yaml}[MLB-TCB]{\texttt{textwrap2B.yaml}}{lst:textwrap2B-yaml} - \end{cmhtcbraster} - - You can also specify the \texttt{tabstop} field \announce{2020-11-06}{tabstop option for - text wrap module} as an integer value, which is passed to the text wrap module; see - \cite{textwrap} for details. Starting with the code in \cref{lst:textwrap-ts} with - settings in \cref{lst:tabstop}, and running the command \index{switches!-l demonstration} - \index{switches!-m demonstration} \index{switches!-o demonstration}% - \begin{commandshell} - latexindent.pl -m textwrap-ts.tex -o=+-mod1 -l tabstop.yaml - \end{commandshell} - gives the code given in \cref{lst:textwrap-ts-mod1}. - \begin{cmhtcbraster}[raster columns=3, - raster left skip=-3.5cm, - raster right skip=-2cm, - raster column skip=.03\linewidth] - \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts.tex}{\texttt{textwrap-ts.tex}}{lst:textwrap-ts} - \cmhlistingsfromfile{demonstrations/tabstop.yaml}[MLB-TCB]{\texttt{tabstop.yaml}}{lst:tabstop} - \cmhlistingsfromfile[showtabs=true]{demonstrations/textwrap-ts-mod1.tex}{\texttt{textwrap-ts-mod1.tex}}{lst:textwrap-ts-mod1} - \end{cmhtcbraster} - - You can specify \texttt{separator}, \texttt{break} and \texttt{unexpand} options in your - settings in analogous ways to those demonstrated in - \cref{lst:textwrap2B-yaml,lst:tabstop}, and they will be passed to the - \texttt{Text::Wrap} module. I have not found a useful reason to do this; see - \cite{textwrap} for more details. diff --git a/support/latexindent/documentation/subsubsec-commands-with-arguments.tex b/support/latexindent/documentation/subsubsec-commands-with-arguments.tex deleted file mode 100644 index f578d8a9a8..0000000000 --- a/support/latexindent/documentation/subsubsec-commands-with-arguments.tex +++ /dev/null @@ -1,109 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsubsection{Commands with arguments}\label{subsubsec:commands-arguments} - Let's begin with the simple example in \cref{lst:mycommand}; when \texttt{latexindent.pl} - operates on this file, the default output is shown in \cref{lst:mycommand-default}. - \footnote{The command code blocks have quite a few subtleties, described in - \vref{subsec:commands-string-between}.} - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/mycommand.tex}{\texttt{mycommand.tex}}{lst:mycommand} - \cmhlistingsfromfile{demonstrations/mycommand-default.tex}{\texttt{mycommand.tex} default output}{lst:mycommand-default} - \end{cmhtcbraster} - - As in the environment-based case (see \vref{lst:myenv-noAdd1,lst:myenv-noAdd2}) we may - specify \texttt{noAdditionalIndent} either in `scalar' form, or in `field' form, as shown - in \cref{lst:mycommand-noAdd1,lst:mycommand-noAdd2} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd1.yaml}}{lst:mycommand-noAdd1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd2.yaml}}{lst:mycommand-noAdd2} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl mycommand.tex -l mycommand-noAdd1.yaml -latexindent.pl mycommand.tex -l mycommand-noAdd2.yaml -\end{commandshell} - we receive the respective output given in - \cref{lst:mycommand-output-noAdd1,lst:mycommand-output-noAdd2} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/mycommand-noAdd1.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd1}}{lst:mycommand-output-noAdd1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/mycommand-noAdd2.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd2}}{lst:mycommand-output-noAdd2} - \end{minipage} - - Note that in \cref{lst:mycommand-output-noAdd1} that the `body', optional argument - \emph{and} mandatory argument have \emph{all} received no additional indentation, while - in \cref{lst:mycommand-output-noAdd2}, only the `body' has not received any additional - indentation. We define the `body' of a command as any lines following the command name - that include its optional or mandatory arguments. - - We may further customise \texttt{noAdditionalIndent} for \texttt{mycommand} as we did in - \vref{lst:myenv-noAdd5,lst:myenv-noAdd6}; explicit examples are given in - \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd3.yaml}}{lst:mycommand-noAdd3} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd4.yaml}}{lst:mycommand-noAdd4} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl mycommand.tex -l mycommand-noAdd3.yaml -latexindent.pl mycommand.tex -l mycommand-noAdd4.yaml -\end{commandshell} - we receive the respective output given in - \cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/mycommand-noAdd3.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd3}}{lst:mycommand-output-noAdd3} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/mycommand-noAdd4.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd4}}{lst:mycommand-output-noAdd4} - \end{minipage} - - Attentive readers will note that the body of \texttt{mycommand} in both - \cref{lst:mycommand-output-noAdd3,lst:mycommand-output-noAdd4} has received no additional - indent, even though \texttt{body} is explicitly set to \texttt{0} in both - \cref{lst:mycommand-noAdd3,lst:mycommand-noAdd4}. This is because, by default, - \texttt{noAdditionalIndentGlobal} for \texttt{commands} is set to \texttt{1} by default; - this can be easily fixed as in - \cref{lst:mycommand-noAdd5,lst:mycommand-noAdd6}.\label{page:command:noAddGlobal} - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd5.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd5.yaml}}{lst:mycommand-noAdd5} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mycommand-noAdd6.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mycommand-noAdd6.yaml}}{lst:mycommand-noAdd6} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl mycommand.tex -l mycommand-noAdd5.yaml -latexindent.pl mycommand.tex -l mycommand-noAdd6.yaml -\end{commandshell} - we receive the respective output given in - \cref{lst:mycommand-output-noAdd5,lst:mycommand-output-noAdd6}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/mycommand-noAdd5.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd5}}{lst:mycommand-output-noAdd5} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/mycommand-noAdd6.tex}{\texttt{mycommand.tex} using \cref{lst:mycommand-noAdd6}}{lst:mycommand-output-noAdd6} - \end{minipage} - - Both \texttt{indentRules} and \texttt{indentRulesGlobal} can be adjusted as they were for - \emph{environment} code blocks, as in \vref{lst:myenv-rules3,lst:myenv-rules4} and - \vref{lst:indentRulesGlobal:environments,lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob}. diff --git a/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex b/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex deleted file mode 100644 index 4d750c298b..0000000000 --- a/support/latexindent/documentation/subsubsec-environments-and-their-arguments.tex +++ /dev/null @@ -1,294 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsubsection{Environments and their arguments}\label{subsubsec:env-and-their-args} - There are a few different YAML switches governing the indentation of environments; let's - start with the code shown in \cref{lst:myenvtex}. - - \cmhlistingsfromfile{demonstrations/myenvironment-simple.tex}{\texttt{myenv.tex}}{lst:myenvtex} - -\yamltitle{noAdditionalIndent}*{fields} - If we do not wish \texttt{myenv} to receive any additional indentation, we have a few - choices available to us, as demonstrated in \cref{lst:myenv-noAdd1,lst:myenv-noAdd2}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd1.yaml}}{lst:myenv-noAdd1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd2.yaml}}{lst:myenv-noAdd2} - \end{minipage} - - On applying either of the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv.tex -l myenv-noAdd1.yaml -latexindent.pl myenv.tex -l myenv-noAdd2.yaml -\end{commandshell} - we obtain the output given in \cref{lst:myenv-output}; note in particular that the - environment \texttt{myenv} has not received any \emph{additional} indentation, but that - the \texttt{outer} environment \emph{has} still received indentation. - - \cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-noAdd1} or \cref{lst:myenv-noAdd2})}{lst:myenv-output} - - Upon changing the YAML files to those shown in \cref{lst:myenv-noAdd3,lst:myenv-noAdd4}, - and running either \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv.tex -l myenv-noAdd3.yaml -latexindent.pl myenv.tex -l myenv-noAdd4.yaml -\end{commandshell} - we obtain the output given in \cref{lst:myenv-output-4}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd3.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd3.yaml}}{lst:myenv-noAdd3} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd4.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd4.yaml}}{lst:myenv-noAdd4} - \end{minipage} - - \cmhlistingsfromfile{demonstrations/myenvironment-simple-noAdd-body4.tex}{\texttt{myenv.tex output} (using either \cref{lst:myenv-noAdd3} or \cref{lst:myenv-noAdd4})}{lst:myenv-output-4} - - Let's now allow \texttt{myenv} to have some optional and mandatory arguments, as in - \cref{lst:myenv-args}. - - \cmhlistingsfromfile{demonstrations/myenvironment-args.tex}{\texttt{myenv-args.tex}}{lst:myenv-args} - - Upon running \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl -l=myenv-noAdd1.yaml myenv-args.tex -\end{commandshell} - we obtain the output shown in \cref{lst:myenv-args-noAdd1}; note that the optional - argument, mandatory argument and body \emph{all} have received no additional indent. This - is because, when \texttt{noAdditionalIndent} is specified in `scalar' form (as in - \cref{lst:myenv-noAdd1}), then \emph{all} parts of the environment (body, optional and - mandatory arguments) are assumed to want no additional indent. - \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd-body1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd1}}{lst:myenv-args-noAdd1} - - We may customise \texttt{noAdditionalIndent} for optional and mandatory arguments of the - \texttt{myenv} environment, as shown in, for example, - \cref{lst:myenv-noAdd5,lst:myenv-noAdd6}. - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd5.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd5.yaml}}{lst:myenv-noAdd5} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-noAdd6.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-noAdd6.yaml}}{lst:myenv-noAdd6} - \end{minipage} - - Upon running \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv.tex -l myenv-noAdd5.yaml -latexindent.pl myenv.tex -l myenv-noAdd6.yaml -\end{commandshell} - we obtain the respective outputs given in - \cref{lst:myenv-args-noAdd5,lst:myenv-args-noAdd6}. Note that in - \cref{lst:myenv-args-noAdd5} the text for the \emph{optional} argument has not received - any additional indentation, and that in \cref{lst:myenv-args-noAdd6} the \emph{mandatory} - argument has not received any additional indentation; in both cases, the \emph{body} has - not received any additional indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd5.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd5}}{lst:myenv-args-noAdd5} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/myenvironment-args-noAdd6.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-noAdd6}}{lst:myenv-args-noAdd6} - \end{minipage} - -\yamltitle{indentRules}*{fields} - We may also specify indentation rules for environment code blocks using the - \texttt{indentRules} field; see, for example, \cref{lst:myenv-rules1,lst:myenv-rules2}. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules1.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules1.yaml}}{lst:myenv-rules1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules2.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules2.yaml}}{lst:myenv-rules2} - \end{cmhtcbraster} - - On applying either of the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv.tex -l myenv-rules1.yaml -latexindent.pl myenv.tex -l myenv-rules2.yaml -\end{commandshell} - we obtain the output given in \cref{lst:myenv-rules-output}; note in particular that the - environment \texttt{myenv} has received one tab (from the \texttt{outer} environment) - plus three spaces from \cref{lst:myenv-rules1} or \ref{lst:myenv-rules2}. - - \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenv-rules1.tex}{\texttt{myenv.tex} output (using either \cref{lst:myenv-rules1} or \cref{lst:myenv-rules2})}{lst:myenv-rules-output} - - If you specify a field in \texttt{indentRules} using anything other than horizontal - space, it will be ignored. - - Returning to the example in \cref{lst:myenv-args} that contains optional and mandatory - arguments. Upon using \cref{lst:myenv-rules1} as in \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv-args.tex -l=myenv-rules1.yaml -\end{commandshell} - we obtain the output in \cref{lst:myenv-args-rules1}; note that the body, optional - argument and mandatory argument of \texttt{myenv} have \emph{all} received the same - customised indentation. - \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1}}{lst:myenv-args-rules1} - - You can specify different indentation rules for the different features using, for - example, \cref{lst:myenv-rules3,lst:myenv-rules4} - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules3.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules3.yaml}}{lst:myenv-rules3} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/myenv-rules4.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{myenv-rules4.yaml}}{lst:myenv-rules4} - \end{minipage} - - After running \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv-args.tex -l myenv-rules3.yaml -latexindent.pl myenv-args.tex -l myenv-rules4.yaml -\end{commandshell} - then we obtain the respective outputs given in - \cref{lst:myenv-args-rules3,lst:myenv-args-rules4}. - - \begin{widepage} - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules3}}{lst:myenv-args-rules3} - \end{minipage}% - \hfill - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/myenvironment-args-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules4}}{lst:myenv-args-rules4} - \end{minipage} - \end{widepage} - - Note that in \cref{lst:myenv-args-rules3}, the optional argument has only received a - single space of indentation, while the mandatory argument has received the default (tab) - indentation; the environment body has received three spaces of indentation. - - In \cref{lst:myenv-args-rules4}, the optional argument has received the default (tab) - indentation, the mandatory argument has received two tabs of indentation, and the body - has received three spaces of indentation. - -\yamltitle{noAdditionalIndentGlobal}*{fields} - Assuming that your environment name is not found within neither - \texttt{noAdditionalIndent} nor \texttt{indentRules}, the next place that - \texttt{latexindent.pl} will look is \texttt{noAdditionalIndentGlobal}, and in particular - \emph{for the environments} key (see \cref{lst:noAdditionalIndentGlobal:environments}). - - \cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} - - Let's say that you change the value of \texttt{environments} to \texttt{1} in - \cref{lst:noAdditionalIndentGlobal:environments}, and that you run \index{switches!-l - demonstration} - - \begin{widepage} - \begin{commandshell} -latexindent.pl myenv-args.tex -l env-noAdditionalGlobal.yaml -latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-noAdditionalGlobal.yaml -\end{commandshell} - \end{widepage} - - The respective output from these two commands are in - \cref{lst:myenv-args-no-add-global1,lst:myenv-args-no-add-global2}; in - \cref{lst:myenv-args-no-add-global1} notice that \emph{both} environments receive no - additional indentation but that the arguments of \texttt{myenv} still \emph{do} receive - indentation. In \cref{lst:myenv-args-no-add-global2} notice that the \emph{outer} - environment does not receive additional indentation, but because of the settings from - \texttt{myenv-rules1.yaml} (in \vref{lst:myenv-rules1}), the \texttt{myenv} environment - still \emph{does} receive indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal1.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments}}{lst:myenv-args-no-add-global1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal2.tex}{\texttt{myenv-args.tex} using \cref{lst:noAdditionalIndentGlobal:environments,lst:myenv-rules1}}{lst:myenv-args-no-add-global2} - \end{minipage} - - In fact, \texttt{noAdditionalIndentGlobal} also contains keys that control the - indentation of optional and mandatory arguments; on referencing - \cref{lst:opt-args-no-add-glob,lst:mand-args-no-add-glob} - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/opt-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-no-add-glob.yaml}}{lst:opt-args-no-add-glob} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mand-args-no-add-glob.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-no-add-glob.yaml}}{lst:mand-args-no-add-glob} - \end{minipage} - - we may run the commands \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv-args.tex -local opt-args-no-add-glob.yaml -latexindent.pl myenv-args.tex -local mand-args-no-add-glob.yaml -\end{commandshell} - which produces the respective outputs given in - \cref{lst:myenv-args-no-add-opt,lst:myenv-args-no-add-mand}. Notice that in - \cref{lst:myenv-args-no-add-opt} the \emph{optional} argument has not received any - additional indentation, and in \cref{lst:myenv-args-no-add-mand} the \emph{mandatory} - argument has not received any additional indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-no-add-glob}}{lst:myenv-args-no-add-opt} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/myenvironment-args-rules1-noAddGlobal4.tex}{\texttt{myenv-args.tex} using \cref{lst:mand-args-no-add-glob}}{lst:myenv-args-no-add-mand} - \end{minipage} - -\yamltitle{indentRulesGlobal}*{fields} - The final check that \texttt{latexindent.pl} will make is to look for - \texttt{indentRulesGlobal} as detailed in \cref{lst:indentRulesGlobal:environments}. - - \cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} - - If you change the \texttt{environments} field to anything involving horizontal space, say - \lstinline!" "!, and then run the following commands \index{switches!-l demonstration} - - \begin{commandshell} -latexindent.pl myenv-args.tex -l env-indentRules.yaml -latexindent.pl myenv-args.tex -l myenv-rules1.yaml,env-indentRules.yaml -\end{commandshell} - then the respective output is shown in - \cref{lst:myenv-args-indent-rules-global1,lst:myenv-args-indent-rules-global2}. Note that - in \cref{lst:myenv-args-indent-rules-global1}, both the environment blocks have received - a single-space indentation, whereas in \cref{lst:myenv-args-indent-rules-global2} the - \texttt{outer} environment has received single-space indentation (specified by - \texttt{indentRulesGlobal}), but \texttt{myenv} has received \lstinline!" "!, as - specified by the particular \texttt{indentRules} for \texttt{myenv} - \vref{lst:myenv-rules1}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules1.tex}{\texttt{myenv-args.tex} using \cref{lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showspaces=true]{demonstrations/myenvironment-args-global-rules2.tex}{\texttt{myenv-args.tex} using \cref{lst:myenv-rules1,lst:indentRulesGlobal:environments}}{lst:myenv-args-indent-rules-global2} - \end{minipage} - - You can specify \texttt{indentRulesGlobal} for both optional and mandatory arguments, as - detailed in \cref{lst:opt-args-indent-rules-glob,lst:mand-args-indent-rules-glob} - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/opt-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{opt-args-indent-rules-glob.yaml}}{lst:opt-args-indent-rules-glob} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/mand-args-indent-rules-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{mand-args-indent-rules-glob.yaml}}{lst:mand-args-indent-rules-glob} - \end{minipage} - - Upon running the following commands \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl myenv-args.tex -local opt-args-indent-rules-glob.yaml -latexindent.pl myenv-args.tex -local mand-args-indent-rules-glob.yaml -\end{commandshell} - we obtain the respective outputs in - \cref{lst:myenv-args-indent-rules-global3,lst:myenv-args-indent-rules-global4}. Note that - the \emph{optional} argument in \cref{lst:myenv-args-indent-rules-global3} has received - two tabs worth of indentation, while the \emph{mandatory} argument has done so in - \cref{lst:myenv-args-indent-rules-global4}. - - \begin{widepage} - \begin{minipage}{.55\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules3.tex}{\texttt{myenv-args.tex} using \cref{lst:opt-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global3} - \end{minipage} - \hfill - \begin{minipage}{.55\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/myenvironment-args-global-rules4.tex}{\texttt{myenv-args.tex} using \cref{lst:mand-args-indent-rules-glob}}{lst:myenv-args-indent-rules-global4} - \end{minipage} - \end{widepage} diff --git a/support/latexindent/documentation/subsubsec-environments-with-items.tex b/support/latexindent/documentation/subsubsec-environments-with-items.tex deleted file mode 100644 index dab84cbdfd..0000000000 --- a/support/latexindent/documentation/subsubsec-environments-with-items.tex +++ /dev/null @@ -1,60 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsubsection{Environments with items} - With reference to \vref{lst:indentafteritems,lst:itemNames}, some commands may contain - \texttt{item} commands; for the purposes of this discussion, we will use the code from - \vref{lst:itemsbefore}. - - Assuming that you've populated \texttt{itemNames} with the name of your \texttt{item}, - you can put the item name into \texttt{noAdditionalIndent} as in \cref{lst:item-noAdd1}, - although a more efficient approach may be to change the relevant field in - \texttt{itemNames} to \texttt{0}. Similarly, you can customise the indentation that your - \texttt{item} receives using \texttt{indentRules}, as in \cref{lst:item-rules1} - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-noAdd1.yaml}[yaml-TCB]{\texttt{item-noAdd1.yaml}}{lst:item-noAdd1} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/item-rules1.yaml}[yaml-TCB]{\texttt{item-rules1.yaml}}{lst:item-rules1} - \end{cmhtcbraster} - - Upon running the following commands \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl items1.tex -local item-noAdd1.yaml -latexindent.pl items1.tex -local item-rules1.yaml -\end{commandshell} - the respective outputs are given in \cref{lst:items1-noAdd1,lst:items1-rules1}; note that - in \cref{lst:items1-noAdd1} that the text after each \texttt{item} has not received any - additional indentation, and in \cref{lst:items1-rules1}, the text after each - \texttt{item} has received a single space of indentation, specified by - \cref{lst:item-rules1}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/items1-noAdd1.tex}{\texttt{items1.tex} using \cref{lst:item-noAdd1}}{lst:items1-noAdd1} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showtabs=true,showspaces=true]{demonstrations/items1-rules1.tex}{\texttt{items1.tex} using \cref{lst:item-rules1}}{lst:items1-rules1} - \end{minipage} - - Alternatively, you might like to populate \texttt{noAdditionalIndentGlobal} or - \texttt{indentRulesGlobal} using the \texttt{items} key, as demonstrated in - \cref{lst:items-noAdditionalGlobal,lst:items-indentRulesGlobal}. Note that there is a - need to `reset/remove' the \texttt{item} field from \texttt{indentRules} in both cases - (see the hierarchy description given on \cpageref{sec:noadd-indent-rules}) as the - \texttt{item} command is a member of \texttt{indentRules} by default. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-noAdditionalGlobal.yaml}[yaml-TCB]{\texttt{items-noAdditionalGlobal.yaml}}{lst:items-noAdditionalGlobal} - \end{minipage}% - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/items-indentRulesGlobal.yaml}[yaml-TCB]{\texttt{items-indentRulesGlobal.yaml}}{lst:items-indentRulesGlobal} - \end{minipage} - - Upon running the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl items1.tex -local items-noAdditionalGlobal.yaml -latexindent.pl items1.tex -local items-indentRulesGlobal.yaml -\end{commandshell} - the respective outputs from \cref{lst:items1-noAdd1,lst:items1-rules1} are obtained; - note, however, that \emph{all} such \texttt{item} commands without their own individual - \texttt{noAdditionalIndent} or \texttt{indentRules} settings would behave as in these - listings. diff --git a/support/latexindent/documentation/subsubsec-headings.tex b/support/latexindent/documentation/subsubsec-headings.tex deleted file mode 100644 index ee863da138..0000000000 --- a/support/latexindent/documentation/subsubsec-headings.tex +++ /dev/null @@ -1,87 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsubsection{afterHeading code blocks}\label{subsubsec-headings-no-add-indent-rules} - Let's use the example \cref{lst:headings2} for demonstration throughout this - \namecref{subsubsec-headings-no-add-indent-rules}. As discussed on - \cpageref{lst:headings1}, by default \texttt{latexindent.pl} will not add indentation - after headings. - - \cmhlistingsfromfile{demonstrations/headings2.tex}{\texttt{headings2.tex}}{lst:headings2} - - On using the YAML file in \cref{lst:headings3yaml} by running the command - \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl headings2.tex -l headings3.yaml -\end{commandshell} - we obtain the output in \cref{lst:headings2-mod3}. Note that the argument of - \texttt{paragraph} has received (default) indentation, and that the body after the - heading statement has received (default) indentation. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/headings2-mod3.tex}{\texttt{headings2.tex} using \cref{lst:headings3yaml}}{lst:headings2-mod3} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings3.yaml}[yaml-TCB]{\texttt{headings3.yaml}}{lst:headings3yaml} - \end{cmhtcbraster} - - If we specify \texttt{noAdditionalIndent} as in \cref{lst:headings4yaml} and run the - command \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl headings2.tex -l headings4.yaml -\end{commandshell} - then we receive the output in \cref{lst:headings2-mod4}. Note that the arguments - \emph{and} the body after the heading of \texttt{paragraph} has received no additional - indentation, because we have specified \texttt{noAdditionalIndent} in scalar form. - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/headings2-mod4.tex}{\texttt{headings2.tex} using \cref{lst:headings4yaml}}{lst:headings2-mod4} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings4.yaml}[yaml-TCB]{\texttt{headings4.yaml}}{lst:headings4yaml} - \end{cmhtcbraster} - - Similarly, if we specify \texttt{indentRules} as in \cref{lst:headings5yaml} and run - analogous commands to those above, we receive the output in \cref{lst:headings2-mod5}; - note that the \emph{body}, \emph{mandatory argument} and content \emph{after the heading} - of \texttt{paragraph} have \emph{all} received three tabs worth of indentation. - - \begin{cmhtcbraster}[raster force size=false, - raster column 1/.style={add to width=1cm}, - raster column 2/.style={add to width=-1cm}, - ] - \cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod5.tex}{\texttt{headings2.tex} using \cref{lst:headings5yaml}}{lst:headings2-mod5} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings5.yaml}[yaml-TCB]{\texttt{headings5.yaml}}{lst:headings5yaml} - \end{cmhtcbraster} - - We may, instead, specify \texttt{noAdditionalIndent} in `field' form, as in - \cref{lst:headings6yaml} which gives the output in \cref{lst:headings2-mod6}. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/headings2-mod6.tex}{\texttt{headings2.tex} using \cref{lst:headings6yaml}}{lst:headings2-mod6} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings6.yaml}[yaml-TCB]{\texttt{headings6.yaml}}{lst:headings6yaml} - \end{cmhtcbraster} - - Analogously, we may specify \texttt{indentRules} as in \cref{lst:headings7yaml} which - gives the output in \cref{lst:headings2-mod7}; note that mandatory argument text has only - received a single space of indentation, while the body after the heading has received - three tabs worth of indentation. - - \begin{cmhtcbraster} - \cmhlistingsfromfile[showtabs=true]{demonstrations/headings2-mod7.tex}{\texttt{headings2.tex} using \cref{lst:headings7yaml}}{lst:headings2-mod7} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings7.yaml}[yaml-TCB]{\texttt{headings7.yaml}}{lst:headings7yaml} - \end{cmhtcbraster} - - Finally, let's consider \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} - shown in \cref{lst:headings8yaml,lst:headings9yaml} respectively, with respective output - in \cref{lst:headings2-mod8,lst:headings2-mod9}. Note that in \cref{lst:headings8yaml} - the \emph{mandatory argument} of \texttt{paragraph} has received a (default) tab's worth - of indentation, while the body after the heading has received \emph{no additional - indentation}. Similarly, in \cref{lst:headings2-mod9}, the \emph{argument} has received - both a (default) tab plus two spaces of indentation (from the global rule specified in - \cref{lst:headings9yaml}), and the remaining body after \texttt{paragraph} has received - just two spaces of indentation. - - \begin{cmhtcbraster} - \cmhlistingsfromfile{demonstrations/headings2-mod8.tex}{\texttt{headings2.tex} using \cref{lst:headings8yaml}}{lst:headings2-mod8} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings8.yaml}[yaml-TCB]{\texttt{headings8.yaml}}{lst:headings8yaml} - \end{cmhtcbraster} - - \begin{cmhtcbraster} - \cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/headings2-mod9.tex}{\texttt{headings2.tex} using \cref{lst:headings9yaml}}{lst:headings2-mod9} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/headings9.yaml}[yaml-TCB]{\texttt{headings9.yaml}}{lst:headings9yaml} - \end{cmhtcbraster} diff --git a/support/latexindent/documentation/subsubsec-ifelsefi.tex b/support/latexindent/documentation/subsubsec-ifelsefi.tex deleted file mode 100644 index 7effdd6dff..0000000000 --- a/support/latexindent/documentation/subsubsec-ifelsefi.tex +++ /dev/null @@ -1,87 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsubsection{ifelsefi code blocks} - Let's use the simple example shown in \cref{lst:ifelsefi1}; when \texttt{latexindent.pl} - operates on this file, the output as in \cref{lst:ifelsefi1-default}; note that the body - of each of the \lstinline!\if! statements have been indented, and that the - \lstinline!\else! statement has been accounted for correctly. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/ifelsefi1.tex}{\texttt{ifelsefi1.tex}}{lst:ifelsefi1} - \end{minipage}% - \hfill - \begin{minipage}{.54\textwidth} - \cmhlistingsfromfile{demonstrations/ifelsefi1-default.tex}{\texttt{ifelsefi1.tex} default output}{lst:ifelsefi1-default} - \end{minipage} - - It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the - `scalar' form only for these type of code blocks, although the `field' form would work, - assuming that \texttt{body} was specified. Examples are shown in - \cref{lst:ifnum-noAdd,lst:ifnum-indent-rules}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-noAdd.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-noAdd.yaml}}{lst:ifnum-noAdd} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifnum-indent-rules.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{ifnum-indent-rules.yaml}}{lst:ifnum-indent-rules} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl ifelsefi1.tex -local ifnum-noAdd.yaml -latexindent.pl ifelsefi1.tex -l ifnum-indent-rules.yaml -\end{commandshell} - we receive the respective output given in - \cref{lst:ifelsefi1-output-noAdd,lst:ifelsefi1-output-indent-rules}; note that in - \cref{lst:ifelsefi1-output-noAdd}, the \texttt{ifnum} code block has \emph{not} received - any additional indentation, while in \cref{lst:ifelsefi1-output-indent-rules}, the - \texttt{ifnum} code block has received one tab and two spaces of indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-noAdd}}{lst:ifelsefi1-output-noAdd} - \end{minipage} - \hfill - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[showspaces=true,showtabs=true]{demonstrations/ifelsefi1-indent-rules.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifnum-indent-rules}}{lst:ifelsefi1-output-indent-rules} - \end{minipage} - - We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in - \cref{lst:ifelsefi-noAdd-glob,lst:ifelsefi-indent-rules-global}. - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifelsefi-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-noAdd-glob.yaml}}{lst:ifelsefi-noAdd-glob} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/ifelsefi-indent-rules-global.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{ifelsefi-indent-rules-global.yaml}}{lst:ifelsefi-indent-rules-global} - \end{minipage} - - Upon running the following commands \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl ifelsefi1.tex -local ifelsefi-noAdd-glob.yaml -latexindent.pl ifelsefi1.tex -l ifelsefi-indent-rules-global.yaml -\end{commandshell} - we receive the outputs in - \cref{lst:ifelsefi1-output-noAdd-glob,lst:ifelsefi1-output-indent-rules-global}; notice - that in \cref{lst:ifelsefi1-output-noAdd-glob} neither of the \texttt{ifelsefi} code - blocks have received indentation, while in - \cref{lst:ifelsefi1-output-indent-rules-global} both code blocks have received a single - space of indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/ifelsefi1-noAdd-glob.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-noAdd-glob}}{lst:ifelsefi1-output-noAdd-glob} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showspaces=true]{demonstrations/ifelsefi1-indent-rules-global.tex}{\texttt{ifelsefi1.tex} using \cref{lst:ifelsefi-indent-rules-global}}{lst:ifelsefi1-output-indent-rules-global} - \end{minipage} - - We can further explore the treatment of \texttt{ifElseFi} code blocks - \announce{2018-04-27}*{updates to ifElseFi code blocks} in \cref{lst:ifelsefi2}, and the - associated default output given in \cref{lst:ifelsefi2-default}; note, in particular, - that the bodies of each of the `or statements' have been indented.% - - \begin{cmhtcbraster}[raster column skip=.1\linewidth] - \cmhlistingsfromfile{demonstrations/ifelsefi2.tex}{\texttt{ifelsefi2.tex}}{lst:ifelsefi2} - \cmhlistingsfromfile{demonstrations/ifelsefi2-default.tex}{\texttt{ifelsefi2.tex} default output}{lst:ifelsefi2-default} - \end{cmhtcbraster} diff --git a/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex b/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex deleted file mode 100644 index 300e39756c..0000000000 --- a/support/latexindent/documentation/subsubsec-no-add-remaining-code-blocks.tex +++ /dev/null @@ -1,134 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} -\subsubsection{The remaining code blocks} - Referencing the different types of code blocks in \vref{tab:code-blocks}, we have a few - code blocks yet to cover; these are very similar to the \texttt{commands} code block type - covered comprehensively in \vref{subsubsec:commands-arguments}, but a small discussion - defining these remaining code blocks is necessary. - - \paragraph{keyEqualsValuesBracesBrackets} - \texttt{latexindent.pl} defines this type of code block by the following criteria: - \begin{itemize} - \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! with - comments and blank lines allowed. - \item then it has a name made up of the characters detailed in \vref{tab:code-blocks}; - \item then an $=$ symbol; - \item then at least one set of curly braces or square brackets (comments and line breaks - allowed throughout). - \end{itemize} - See the \texttt{keyEqualsValuesBracesBrackets: follow} and - \texttt{keyEqualsValuesBracesBrackets: name} fields of the fine tuning section in - \vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: keyEqualsValuesBracesBrackets}% - - An example is shown in \cref{lst:pgfkeysbefore}, with the default output given in - \cref{lst:pgfkeys1:default}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/pgfkeys1.tex}{\texttt{pgfkeys1.tex}}{lst:pgfkeysbefore} - \end{minipage}% - \hfill - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/pgfkeys1-default.tex}{\texttt{pgfkeys1.tex} default output}{lst:pgfkeys1:default} - \end{minipage}% - - In \cref{lst:pgfkeys1:default}, note that the maximum indentation is three tabs, and - these come from: - \begin{itemize} - \item the \lstinline!\pgfkeys! command's mandatory argument; - \item the \lstinline!start coordinate/.initial! key's mandatory argument; - \item the \lstinline!start coordinate/.initial! key's body, which is defined as any lines - following the name of the key that include its arguments. This is the part controlled by - the \emph{body} field for \texttt{noAdditionalIndent} and friends from - \cpageref{sec:noadd-indent-rules}. - \end{itemize} - \paragraph{namedGroupingBracesBrackets} This type of code block is mostly motivated by - tikz-based code; we define this code block as follows: - \begin{itemize} - \item it must immediately follow either \emph{horizontal space} OR \emph{one or more line - breaks} OR \lstinline!{! OR \lstinline![! OR \lstinline!$! OR \lstinline!)! OR - \lstinline!(! - \item the name may contain the characters detailed in \vref{tab:code-blocks}; - \item then at least one set of curly braces or square brackets (comments and line breaks - allowed throughout). - \end{itemize} - See the \texttt{NamedGroupingBracesBrackets: follow} and - \texttt{NamedGroupingBracesBrackets: name} fields of the fine tuning section in - \vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: namedGroupingBracesBrackets}% - - A simple example is given in \cref{lst:child1}, with default output in - \cref{lst:child1:default}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/child1.tex}{\texttt{child1.tex}}{lst:child1} - \end{minipage}% - \hfill - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/child1-default.tex}{\texttt{child1.tex} default output}{lst:child1:default} - \end{minipage}% - - In particular, \texttt{latexindent.pl} considers \texttt{child}, \texttt{parent} and - \texttt{node} all to be \texttt{namedGroupingBracesBrackets}\footnote{ You may like to - verify this by using the \texttt{-tt} option and checking \texttt{indent.log}! }. - Referencing \cref{lst:child1:default}, note that the maximum indentation is two tabs, and - these come from: - \begin{itemize} - \item the \lstinline!child!'s mandatory argument; - \item the \lstinline!child!'s body, which is defined as any lines following the name of the - \texttt{namedGroupingBracesBrackets} that include its arguments. This is the part - controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from - \cpageref{sec:noadd-indent-rules}. - \end{itemize} - - \paragraph{UnNamedGroupingBracesBrackets} occur in a variety of situations; specifically, we - define this type of code block as satisfying the following criteria: - \begin{itemize} - \item it must immediately follow either \lstinline!{! OR \lstinline![! OR \lstinline!,! OR - \lstinline!&! OR \lstinline!)! OR \lstinline!(! OR \lstinline!$!; - \item then at least one set of curly braces or square brackets (comments and line breaks - allowed throughout). - \end{itemize} - See the \texttt{UnNamedGroupingBracesBrackets: follow} field of the fine tuning section - in \vref{lst:fineTuning} \announce{2019-07-13}{fine tuning: namedGroupingBracesBrackets}% - - An example is shown in \cref{lst:psforeach1} with default output give in - \cref{lst:psforeach:default}. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/psforeach1.tex}{\texttt{psforeach1.tex}}{lst:psforeach1} - \end{minipage}% - \hfill - \begin{minipage}{.5\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/psforeach1-default.tex}{\texttt{psforeach1.tex} default output}{lst:psforeach:default} - \end{minipage}% - - Referencing \cref{lst:psforeach:default}, there are \emph{three} sets of unnamed braces. - Note also that the maximum value of indentation is three tabs, and these come from: - \begin{itemize} - \item the \lstinline!\psforeach! command's mandatory argument; - \item the \emph{first} un-named braces mandatory argument; - \item the \emph{first} un-named braces \emph{body}, which we define as any lines following the - first opening \lstinline!{! or \lstinline![! that defined the code block. This is the - part controlled by the \emph{body} field for \texttt{noAdditionalIndent} and friends from - \cpageref{sec:noadd-indent-rules}. - \end{itemize} - Users wishing to customise the mandatory and/or optional arguments on a \emph{per-name} - basis for the \texttt{UnNamedGroupingBracesBrackets} should use \texttt{always-un-named}. - - \paragraph{filecontents} code blocks behave just as \texttt{environments}, except that - neither arguments nor items are sought. - -\subsubsection{Summary} - \index{indentation!summary} - Having considered all of the different types of code blocks, the functions of the fields - given in \cref{lst:noAdditionalIndentGlobal,lst:indentRulesGlobal} should now make sense. - \index{specialBeginEnd!noAdditionalIndentGlobal} - \index{specialBeginEnd!indentRulesGlobal} - - \begin{widepage} - \begin{minipage}{.47\linewidth} - \cmhlistingsfromfile[style=noAdditionalIndentGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal} - \end{minipage}% - \hfill - \begin{minipage}{.47\linewidth} - \cmhlistingsfromfile[style=indentRulesGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal} - \end{minipage}% - \end{widepage} diff --git a/support/latexindent/documentation/subsubsec-special.tex b/support/latexindent/documentation/subsubsec-special.tex deleted file mode 100644 index 128bd781ca..0000000000 --- a/support/latexindent/documentation/subsubsec-special.tex +++ /dev/null @@ -1,67 +0,0 @@ -% arara: pdflatex: {files: [latexindent]} -\subsubsection{specialBeginEnd code blocks} - Let's use the example from \vref{lst:specialbefore} which has default output shown in - \vref{lst:specialafter}. - - It is recommended to specify \texttt{noAdditionalIndent} and \texttt{indentRules} in the - `scalar' form for these type of code blocks, although the `field' form would work, - assuming that \texttt{body} was specified. Examples are shown in - \cref{lst:displayMath-noAdd,lst:displayMath-indent-rules}. - \index{specialBeginEnd!noAdditionalIndent} \index{specialBeginEnd!indentRules example} - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-noAdd.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-noAdd.yaml}}{lst:displayMath-noAdd} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/displayMath-indent-rules.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{displayMath-indent-rules.yaml}}{lst:displayMath-indent-rules} - \end{minipage} - - After running the following commands, \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl special1.tex -local displayMath-noAdd.yaml -latexindent.pl special1.tex -l displayMath-indent-rules.yaml -\end{commandshell} - we receive the respective output given in - \cref{lst:special1-output-noAdd,lst:special1-output-indent-rules}; note that in - \cref{lst:special1-output-noAdd}, the \texttt{displayMath} code block has \emph{not} - received any additional indentation, while in \cref{lst:special1-output-indent-rules}, - the \texttt{displayMath} code block has received three tabs worth of indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/special1-noAdd.tex}{\texttt{special1.tex} using \cref{lst:displayMath-noAdd}}{lst:special1-output-noAdd} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showtabs=true]{demonstrations/special1-indent-rules.tex}{\texttt{special1.tex} using \cref{lst:displayMath-indent-rules}}{lst:special1-output-indent-rules} - \end{minipage} - - We may specify \texttt{noAdditionalIndentGlobal} and \texttt{indentRulesGlobal} as in - \cref{lst:special-noAdd-glob,lst:special-indent-rules-global}. - - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-noAdd-glob.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-noAdd-glob.yaml}}{lst:special-noAdd-glob} - \end{minipage} - \hfill - \begin{minipage}{.49\textwidth} - \cmhlistingsfromfile[style=yaml-LST]{demonstrations/special-indent-rules-global.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{special-indent-rules-global.yaml}}{lst:special-indent-rules-global} - \end{minipage} - - Upon running the following commands \index{switches!-l demonstration} - \begin{commandshell} -latexindent.pl special1.tex -local special-noAdd-glob.yaml -latexindent.pl special1.tex -l special-indent-rules-global.yaml -\end{commandshell} - we receive the outputs in - \cref{lst:special1-output-noAdd-glob,lst:special1-output-indent-rules-global}; notice - that in \cref{lst:special1-output-noAdd-glob} neither of the \texttt{special} code blocks - have received indentation, while in \cref{lst:special1-output-indent-rules-global} both - code blocks have received a single space of indentation. - - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile{demonstrations/special1-noAdd-glob.tex}{\texttt{special1.tex} using \cref{lst:special-noAdd-glob}}{lst:special1-output-noAdd-glob} - \end{minipage} - \hfill - \begin{minipage}{.45\textwidth} - \cmhlistingsfromfile[showspaces=true]{demonstrations/special1-indent-rules-global.tex}{\texttt{special1.tex} using \cref{lst:special-indent-rules-global}}{lst:special1-output-indent-rules-global} - \end{minipage} diff --git a/support/latexindent/documentation/test-default-settings.tex b/support/latexindent/documentation/test-default-settings.tex deleted file mode 100644 index 02b858a749..0000000000 --- a/support/latexindent/documentation/test-default-settings.tex +++ /dev/null @@ -1,65 +0,0 @@ -% arara: pdflatex: { files: [latexindent]} - -% file used to check if line numbers are set correct for defaultSettings.yaml listings -sec-introduction.tex: - -\cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference-demo} -\cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks-demo} -\cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[replace-TCB,width=.85\linewidth,before=\centering]{\texttt{replacements}}{lst:replacements-demo} - -sec default user - -\cmhlistingsfromfile[style=fileExtensionPreference]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileExtensionPreference}}{lst:fileExtensionPreference} -\cmhlistingsfromfile[style=logFilePreferences,]{../defaultSettings.yaml}[width=.9\linewidth,before=\centering,yaml-TCB]{\texttt{logFilePreferences}}{lst:logFilePreferences} -\cmhlistingsfromfile[style=verbatimEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimEnvironments}}{lst:verbatimEnvironments} -\cmhlistingsfromfile[style=verbatimCommands]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{verbatimCommands}}{lst:verbatimCommands} -\cmhlistingsfromfile[style=noIndentBlock]{../defaultSettings.yaml}[width=.4\linewidth,before=\centering,yaml-TCB]{\texttt{noIndentBlock}}{lst:noIndentBlock} -\cmhlistingsfromfile[style=fileContentsEnvironments]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{fileContentsEnvironments}}{lst:fileContentsEnvironments} -\cmhlistingsfromfile[style=lookForPreamble]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{lookForPreamble}{lst:lookForPreamble} -\cmhlistingsfromfile[style=removeTrailingWhitespace]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{removeTrailingWhitespace}{lst:removeTrailingWhitespace} -\cmhlistingsfromfile[style=lookForAlignDelims]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{lookForAlignDelims} (advanced)}{lst:aligndelims:advanced} -\cmhlistingsfromfile[style=indentAfterItems]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterItems}}{lst:indentafteritems} -\cmhlistingsfromfile[style=itemNames]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{itemNames}}{lst:itemNames} -\cmhlistingsfromfile[style=specialBeginEnd]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{specialBeginEnd}}{lst:specialBeginEnd} -\cmhlistingsfromfile[style=indentAfterHeadings]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{indentAfterHeadings}}{lst:indentAfterHeadings} - -subsec-commands-and-their-options.tex: - -\cmhlistingsfromfile[style=commandCodeBlocks]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,yaml-TCB]{\texttt{commandCodeBlocks}}{lst:commandCodeBlocks} - -subsubsec-environments-and-their-arguments.tex: - -\cmhlistingsfromfile[style=noAdditionalIndentGlobalEnv]{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal:environments} -\cmhlistingsfromfile[style=indentRulesGlobalEnv]{../defaultSettings.yaml}[width=.5\linewidth,before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal:environments} - -subsubsec-no-add-remaining-code-blocks.tex: -\cmhlistingsfromfile[style=noAdditionalIndentGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{noAdditionalIndentGlobal}}{lst:noAdditionalIndentGlobal} -\cmhlistingsfromfile[style=indentRulesGlobal]{../defaultSettings.yaml}[before=\centering,yaml-TCB]{\texttt{indentRulesGlobal}}{lst:indentRulesGlobal} - -sec-the-m-switch.tex: - -\cmhlistingsfromfile[style=modifylinebreaks]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{modifyLineBreaks}}{lst:modifylinebreaks} - -subsec-one-sentence-per-line.tex: - -\cmhlistingsfromfile[style=oneSentencePerLine]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{oneSentencePerLine}}{lst:oneSentencePerLine} -\cmhlistingsfromfile[style=sentencesFollow]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesFollow}}{lst:sentencesFollow} -\cmhlistingsfromfile[style=sentencesBeginWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesBeginWith}}{lst:sentencesBeginWith} -\cmhlistingsfromfile[style=sentencesEndWith]{../defaultSettings.yaml}[MLB-TCB,width=.9\linewidth,before=\centering]{\texttt{sentencesEndWith}}{lst:sentencesEndWith} - -subsec-poly-switches.tex: - -\cmhlistingsfromfile[style=modifylinebreaksEnv]{../defaultSettings.yaml}[width=.8\linewidth,before=\centering,MLB-TCB]{\texttt{environments}}{lst:environments-mlb} - -subsec-text-wrap.tex: - -\cmhlistingsfromfile[style=textWrapOptions]{../defaultSettings.yaml}[MLB-TCB,width=.85\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptions} -\cmhlistingsfromfile[style=textWrapOptionsAll]{../defaultSettings.yaml}[MLB-TCB,width=.95\linewidth,before=\centering]{\texttt{textWrapOptions}}{lst:textWrapOptionsAll} - -sec-replacements.tex: - -\cmhlistingsfromfile[style=replacements]{../defaultSettings.yaml}[width=0.95\linewidth,before=\centering,replace-TCB]{\texttt{replacements}}{lst:replacements} - -sec-fine-tuning.tex: - -\cmhlistingsfromfile*[style=fineTuning]{../defaultSettings.yaml}[width=.95\linewidth,before=\centering,yaml-TCB]{\texttt{fineTuning}}{lst:fineTuning} diff --git a/support/latexindent/documentation/title.tex b/support/latexindent/documentation/title.tex deleted file mode 100644 index b9b3bdf117..0000000000 --- a/support/latexindent/documentation/title.tex +++ /dev/null @@ -1,30 +0,0 @@ -\title{% - \begin{tcolorbox}[ - width=5.2cm, - boxrule=0pt, - colframe=white!40!black, - colback=white, - rightrule=2pt, - sharp corners, - enhanced, - overlay={\node[anchor=north east,outer sep=2pt] at ([xshift=3cm,yshift=4mm]frame.north east) {\includegraphics[width=3cm]{logo}}; }] - \centering\ttfamily\bfseries latexindent.pl\\[1cm] Version 3.18 - \end{tcolorbox} -} -\author{Chris Hughes \thanks{and contributors! - See \vref{sec:contributors}. - For - all communication, please visit \cite{latexindent-home}.}} -\date{2022-06-12} -\maketitle -\begin{adjustwidth}{1cm}{1cm} - \small - \texttt{latexindent.pl} is a \texttt{Perl} script that indents \texttt{.tex} (and other) files according to an indentation scheme that the user can modify to suit their taste. - Environments, including those with alignment delimiters (such as \texttt{tabular}), and commands, including those that can split braces and brackets across lines, are \emph{usually} handled correctly by the script. - Options for \texttt{verbatim}-like environments and commands, together with indentation after headings (such as \lstinline!chapter!, \lstinline!section!, etc) are also available. - The script also has the ability to modify line breaks, and to add comment symbols and blank lines; furthermore, it permits string or - regex-based substitutions. - All user options are customisable via the switches and the YAML interface. - - tl;dr, a quick start guide is given in \vref{sec:quickstart}. -\end{adjustwidth} diff --git a/support/latexindent/latexindent.pl b/support/latexindent/latexindent.pl index 49dbe7192e..838b5ba328 100755 --- a/support/latexindent/latexindent.pl +++ b/support/latexindent/latexindent.pl @@ -1,5 +1,5 @@ #!/usr/bin/env perl -# latexindent.pl, version 3.18, 2022-06-12 +# latexindent.pl, version 3.19, 2022-10-30 # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by diff --git a/support/lyluatex/Contributors.md b/support/lyluatex/Contributors.md index 574ecf10a5..39fe7cc9c0 100644 --- a/support/lyluatex/Contributors.md +++ b/support/lyluatex/Contributors.md @@ -2,6 +2,6 @@ Lyluatex is developped by: -- [Fr. Jacques Peron](mailto:catacolp@hotmail.com); -- Urs Liska; -- Br. Samuel Springuel. +- [Fr. Jacques Peron](mailto:cataclop@hotmail.com); [@jperon](https://github.com/jperon) +- [Urs Liska](mailto:git@ursliska.de); [@uliska](https://github.com/uliska), [@openlilylib](https://github.com/openlilylib) +- Br. Samuel Springuel; [@rpspringuel](https://github.com/rpspringuel) diff --git a/support/lyluatex/LICENSE b/support/lyluatex/LICENSE index 515e3806df..9193cccea3 100644 --- a/support/lyluatex/LICENSE +++ b/support/lyluatex/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015--2019 jperon and others +Copyright (c) 2015--2022 jperon and others Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/support/lyluatex/README.md b/support/lyluatex/README.md index 18475559cc..7aa096a18d 100644 --- a/support/lyluatex/README.md +++ b/support/lyluatex/README.md @@ -1,6 +1,4 @@ -Main author: [Fr. Jacques Peron](mailto:cataclop@hotmail.com) -This material is subject to the MIT license. - +Main author: [Fr. Jacques Peron](mailto:cataclop@hotmail.com)\nThis material is subject to the MIT license.\n # Lyluatex ## Usage @@ -23,33 +21,37 @@ Thereafter, you can include a lilypond file with the command: \lilypondfile[staffsize=17]{PATH/TO/THE/FILE} ``` -The argument `staffsize`, which is optional, changes the size of the score. You -can change the size for all the subsequent scores in a document by placing the -following command before your first include statement to be so affected: +The argument `staffsize`, which is optional, changes the size of the score. +You can change the size for all the subsequent scores in a document by +placing the following command before your first include statement to be so +affected: ```TeX -\lysetoption{staffsize}{24} +\setluaoption{ly}{staffsize}{24} ``` Next, you simply need to compile the document normally with the command -`lualatex -shell-escape` : +`lualatex -shell-escape`: ```bash lualatex -shell-escape DOCUMENT.TEX ``` -Another "more secure" option is to add `lilypond` and `gs` to default allowed commands : +Another "more secure" option is to add `lilypond` and `gs` to default +allowed commands: ```bash shell_escape_commands=$(kpsewhich -expand-var '$shell_escape_commands'),lilypond,gs lualatex DOCUMENT.TEX ``` On systems with low RAM, when working on big documents, you could encounter -*buffer overflows* in `lilypond` calls. In that case, first compile with option -`-draftmode`, then compile again without this option. +*buffer overflows* in `lilypond` calls. In that case, first compile with +luatex's command line option `--draftmode` to generate all LilyPond output +snippets, then compile again without this option to generate the output PDF. -You can also input music directly into your docoment with the `lilypond` environment. -This is only recommended for relatively short snippets. For example: +You can also input music directly into your document with the `lilypond` +environment. This is only recommended for relatively short snippets. For +example: ```TeX \begin{lilypond} @@ -57,7 +59,8 @@ This is only recommended for relatively short snippets. For example: \end{lilypond} ``` -Finally, for truly short snippets, there is also the `\lily` command. Example: +Finally, for truly short snippets, there is also the `\lily` command. +Example: ```TeX \lilypond[staffsize=12]{c' d' g'} @@ -70,9 +73,9 @@ code with explicit `\score` blocks. Such code must be included with the ## Migration from `lilypond-book` In order to facilitate the migration from `lilypond-book`, `\lilypondfile`, -the environment `lilypond` and the command `\lilypond` should work nearly -as with `lilypond-book` ; for even more identical behaviour, call `lyluatex` -like follows: +the environment `lilypond` and the command `\lilypond` should work nearly as +with `lilypond-book`; for even more identical behaviour, call `lyluatex` +as follows: ```TeX \usepackage[program=/opt/lilypond-dev/lilypond]{lyluatex} @@ -83,15 +86,15 @@ That way, documents typeset with `lilypond-book` can be adapted to use # Credits -Cf. [Contributors.md](Contributors.md) +See [Contributors.md](Contributors.md). # Contributing -If you want improvements or encounter an error, do not hesitate to -to report the [issue](https://github.com/jperon/lyluatex/issues). -If you have programming skills, you may also propose your changes -via a [pull request](https://github.com/jperon/lyluatex/pulls). +If you want improvements or encounter an error, do not hesitate to to report +the [issue](https://github.com/jperon/lyluatex/issues). If you have +programming skills, you may also propose your changes via a [pull +request](https://github.com/jperon/lyluatex/pulls). -This extension is and will remain free; if you find it useful and -wish to encourage its development by a -[donation](https://www.paypal.me/abjperon), many thanks! +This extension is and will remain free; if you find it useful and wish to +encourage its development by a [donation](https://www.paypal.me/abjperon), +many thanks! diff --git a/support/lyluatex/lyluatex-lib.lua b/support/lyluatex/lyluatex-lib.lua deleted file mode 100644 index ebe6745eb5..0000000000 --- a/support/lyluatex/lyluatex-lib.lua +++ /dev/null @@ -1,163 +0,0 @@ --- luacheck: ignore ly log self luatexbase internalversion font fonts tex token kpse status -local err, warn, info, log = luatexbase.provides_module({ - name = "lyluatex-lib", - version = '1.0f', --LYLUATEX_VERSION - date = "2019/05/27", --LYLUATEX_DATE - description = "Module lyluatex-lib.", - author = "The Gregorio Project − (see Contributors.md)", - copyright = "2015-2019 - jperon and others", - license = "MIT", -}) - -local lib = {} -lib.TEX_UNITS = {'bp', 'cc', 'cm', 'dd', 'in', 'mm', 'pc', 'pt', 'sp', 'em', -'ex'} - -------------------------- --- General tool functions - -function lib.basename(str) ---[[ - Given the full path to a file, return only the file name (without path). - If there is no slash, return the full name. ---]] - return str:gsub(".*/(.*)", "%1") or str -end - - -function lib.contains(table_var, value) ---[[ - Returns the key if the given table contains the given value, or nil. - A value of 'false' (string) is considered equal to false (Boolean). ---]] - for k, v in pairs(table_var) do - if v == value then return k - elseif v == 'false' and value == false then return k - end - end -end - - -function lib.contains_key(table_var, key) --- Returs true if the given key is present in the table, nil otherwise. - for k in pairs(table_var) do - if k == key then return true end - end -end - - -function lib.convert_unit(value) ---[[ - Convert a LaTeX unit, if possible. - TODO: Understand what this *really* does, what is accepted and returned. ---]] - if not value then return 0 - elseif value == '' then return false - elseif value:match('\\') then - local n, u = value:match('^%d*%.?%d*'), value:match('%a+') - if n == '' then n = 1 end - return tonumber(n) * tex.dimen[u] / tex.sp("1pt") - else return ('%f'):format(tonumber(value) or tex.sp(value) / tex.sp("1pt")) - end -end - - -function lib.dirname(str) ---[[ - Given the full path to a file, return only the path (without file name), - including the last slash. If there is no slash, return an empty string. ---]] - return str:gsub("(.*/).*", "%1") or '' -end - - -local fontdata = fonts.hashes.identifiers -function lib.fontinfo(id) ---[[ - Return a LuaTeX font object based on the given ID ---]] - return fontdata[id] or font.fonts[id] -end - - -function lib.max(a, b) - a, b = tonumber(a), tonumber(b) - if a > b then return a else return b end -end - - -function lib.min(a, b) - a, b = tonumber(a), tonumber(b) - if a < b then return a else return b end -end - - -function lib.mkdirs(str) - local path - if str:sub(1, 1) == '/' then path = '' else path = '.' end - for dir in str:gmatch('([^%/]+)') do - path = path .. '/' .. dir - lfs.mkdir(path) - end -end - - -function lib.orderedpairs(t) - local key - local i = 0 - local orderedIndex = {} - for k in pairs(t) do table.insert(orderedIndex, k) end - table.sort(orderedIndex) - return function () - i = i + 1 - key = orderedIndex[i] - if key then return key, t[key] end - end -end - - -function lib.readlinematching(s, f) - if f then - local result = '' - while result and not result:find(s) do result = f:read() end - f:close() - return result - end -end - - -function lib.splitext(str, ext) ---[[ - If 'ext' is supplied return str stripped of the given extension, - otherwise return the base and extension (if any) ---]] - return ext and (str:match('(.*)%.'..ext..'$') or str) - or (str:match('(.*)%.(%w*)$') or str) -end - - ------------------------------------- --- Engine, version, TeX distribution - -local tex_engine = {} -setmetatable(tex_engine, tex_engine) - -function tex_engine:__call() ---[[ - Defines the properties extracted from the first line of jobname.log. ---]] - local f = io.open(tex.jobname..'.log') - if not f then return end - self.engine, self.engine_version, self.dist, self.dist_version, self.format, self.format_version = - f:read():match( - 'This is ([^,]*), Version ([^%(]*) %(([^%)]*) ([^%)]*)%)%s+%(format=([^%)]*) ([^)]*)%)' - ) - f:close() - return self -end - -function tex_engine:__index(k) return rawget(self(), k) end - - -lib.tex_engine = tex_engine -return lib diff --git a/support/lyluatex/lyluatex-options.lua b/support/lyluatex/lyluatex-options.lua deleted file mode 100644 index 62ec72a3c3..0000000000 --- a/support/lyluatex/lyluatex-options.lua +++ /dev/null @@ -1,266 +0,0 @@ --- luacheck: ignore ly warn info log self luatexbase internalversion font fonts tex token kpse status -local err, warn, info, log = luatexbase.provides_module({ - name = "lyluatex-options", - version = '1.0f', --LYLUATEX_VERSION - date = "2019/05/27", --LYLUATEX_DATE - description = "Module lyluatex-options.", - author = "The Gregorio Project − (see Contributors.md)", - copyright = "2015-2019 - jperon and others", - license = "MIT", -}) - ---[[ - This module provides functionality to handle package options and make them - configurable in a fine-grained fashion as - - package options - - local options (for individual instances of commands/environments) - - changed “from here on” within a document. - --- ]] - -local lib = require(kpse.find_file("lyluatex-lib.lua") or "lyluatex-lib.lua") -local optlib = {} -- namespace for the returned table -local Opts = {options = {}} -- Options class -Opts.__index = function (self, k) return self.options[k] or rawget(Opts, k) end -setmetatable(Opts, Opts) - - -function Opts:new(opt_prefix, declarations) ---[[ - Declare package options along with their default and - accepted values. To *some* extent also provide type checking. - - opt_prefix: the prefix/name by which the lyluatex-options module is - referenced in the parent LaTeX document (preamble or package). - This is required to write the code calling optlib.set_option into - the option declaration. - - declarations: a definition table stored in the calling module (see below) - Each entry in the 'declarations' table represents one package option, with each - value being an array (table with integer indexes instead of keys). For - details please refer to the manual. ---]] - local o = setmetatable( - { - declarations = declarations, - options = {} - }, - self - ) - local exopt = '' - for k, v in pairs(declarations) do - o.options[k] = v[1] or '' - tex.sprint(string.format([[ -\DeclareOptionX{%s}{\directlua{ - %s:set_option('%s', '\luatexluaescapestring{#1}') -}}%% -]], - k, opt_prefix, k - )) - exopt = exopt..k..'='..(v[1] or '')..',' - end - tex.sprint([[\ExecuteOptionsX{]]..exopt..[[}%%]], [[\ProcessOptionsX]]) - return o -end - -function Opts:check_local_options(opts, ignore_declarations) ---[[ - Parse the given options (options passed to a command/environment), - sanitize them against the global package options and return a table - with the local options that should then supersede the global options. - If ignore_declaration is given any non-false value the sanitization - step is skipped (i.e. local options are only parsed and duplicates - rejected). ---]] - local options = {} - local next_opt = opts:gmatch('([^,]+)') -- iterator over options - for opt in next_opt do - local k, v = opt:match('([^=]+)=?(.*)') - if k then - if v and v:sub(1, 1) == '{' then -- handle keys with {multiple, values} - while select(2, v:gsub('{', '')) ~= select(2, v:gsub('}', '')) do v = v..','..next_opt() end - v = v:sub(2, -2) -- remove { } - end - if not ignore_declarations then - k, v = self:sanitize_option(k:gsub('^%s', ''), v:gsub('^%s', '')) - end - if k then - if options[k] then err('Option %s is set two times for the same score.', k) - else options[k] = v - end - end - end - end - return options -end - -function Opts:is_neg(k) ---[[ - Type check for a 'negative' option. This is an existing option - name prefixed with 'no' (e.g. 'noalign') ---]] - local _, i = k:find('^no') - return i and lib.contains_key(self.declarations, k:sub(i + 1)) -end - -function Opts:sanitize_option(k, v) ---[[ - Check and (if necessary) adjust the value of a given option. - Reject undefined options - Check 'negative' options - Handle boolean options (empty strings or 'false'), set them to real booleans ---]] - local declarations = self.declarations - if k == '' or k == 'noarg' then return end - if not lib.contains_key(declarations, k) then err('Unknown option: '..k) end - -- aliases - if declarations[k] and declarations[k][2] == optlib.is_alias then - if declarations[k][1] == v then return - else k = declarations[k] end - end - -- boolean - if v == 'false' then v = false end - -- negation (for example, noindent is the negation of indent) - if self:is_neg(k) then - if v ~= nil and v ~= 'default' then - k = k:gsub('^no(.*)', '%1') - v = not v - else return - end - end - return k, v -end - -function Opts:set_option(k, v) ---[[ - Set an option for the given prefix to be in effect from this point on. - Raises an error if the option is not declared or does not meet the - declared expectations. (TODO: The latter has to be integrated by extracting - optlib.validate_option from optlib.validate_options and call it in - sanitize_option). ---]] - k, v = self:sanitize_option(k, v) - if k then - self.options[k] = v - self:validate_option(k) - end -end - -function Opts:validate_option(key, options_obj) ---[[ - Validate an (already sanitized) option against its expected values. - With options_obj a local options table can be provided, - otherwise the global options stored in OPTIONS are checked. ---]] - local package_opts = self.declarations - local options = options_obj or self.options - local unexpected - if options[key] == 'default' then - -- Replace 'default' with an actual value - options[key] = package_opts[key][1] - unexpected = options[key] == nil - end - if not lib.contains(package_opts[key], options[key]) and package_opts[key][2] then - -- option value is not in the array of accepted values - if type(package_opts[key][2]) == 'function' then package_opts[key][2](key, options[key]) - else unexpected = true - end - end - if unexpected then - err([[ - Unexpected value "%s" for option %s: - authorized values are "%s" - ]], - options[key], key, table.concat(package_opts[key], ', ') - ) - end -end - -function Opts:validate_options(options_obj) ---[[ - Validate the given set of options against the option declaration - table for the given prefix. - With options_obj a local options table can be provided, - otherwise the global options stored in OPTIONS are checked. ---]] - for k, _ in lib.orderedpairs(self.declarations) do - self:validate_option(k, options_obj) - end -end - - -function optlib.is_alias() ---[[ - This function doesn't do anything, but if an option is defined - as an alias, its second parameter will be this function, so the - test declarations[k][2] == optlib.is_alias in Opts:sanitize_options - will return true. ---]] -end - - -function optlib.is_dim(k, v) ---[[ - Type checking for options that accept a LaTeX dimension. - This can be - - a number (integer or float) - - a number with unit - - a (multiplied) TeX length - (see error message in code for examples) ---]] - if v == '' or v == false or tonumber(v) then return true end - local n, sl, u = v:match('^%d*%.?%d*'), v:match('\\'), v:match('%a+') - -- a value of number - backslash - length is a dimension - -- invalid input will be prevented in by the LaTeX parser already - if n and sl and u then return true end - if n and lib.contains(lib.TEX_UNITS, u) then return true end - err([[ -Unexpected value "%s" for dimension %s: -should be either a number (for example "12"), -a number with unit, without space ("12pt"), -or a (multiplied) TeX length (".8\linewidth") -]], - v, k - ) -end - - -function optlib.is_neg(k, _) ---[[ - Type check for a 'negative' option. At this stage, - we only check that it begins with 'no'. ---]] - return k:find('^no') -end - - -function optlib.is_num(_, v) ---[[ - Type check for number options ---]] - return v == '' or tonumber(v) -end - - -function optlib.is_str(_, v) ---[[ - Type check for string options ---]] - return type(v) == 'string' -end - - -function optlib.merge_options(base_opt, super_opt) ---[[ - Merge two tables. - Create a new table as a copy of base_opt, then merge with - super_opt. Entries in super_opt supersede (i.e. overwrite) - colliding entries in base_opt. ---]] - local result = {} - for k, v in pairs(base_opt) do result[k] = v end - for k, v in pairs(super_opt) do result[k] = v end - return result -end - - -optlib.Opts = Opts -return optlib diff --git a/support/lyluatex/lyluatex.lua b/support/lyluatex/lyluatex.lua index 1023e20ef9..adb17a63a0 100644 --- a/support/lyluatex/lyluatex.lua +++ b/support/lyluatex/lyluatex.lua @@ -1,21 +1,20 @@ -- luacheck: ignore ly log self luatexbase internalversion font fonts tex token kpse status ly_opts local err, warn, info, log = luatexbase.provides_module({ name = "lyluatex", - version = '1.0f', --LYLUATEX_VERSION - date = "2019/05/27", --LYLUATEX_DATE + version = '1.1', --LYLUATEX_VERSION + date = "2022/10/30", --LYLUATEX_DATE description = "Module lyluatex.", author = "The Gregorio Project − (see Contributors.md)", - copyright = "2015-2019 - jperon and others", + copyright = "2015-2022 - jperon and others", license = "MIT", }) -local lib = require(kpse.find_file("lyluatex-lib.lua") or "lyluatex-lib.lua") -local ly_opts = ly_opts -- global ly_opts has been defined before in lyluatex.sty +local lib = require(kpse.find_file("luaoptions-lib.lua") or "luaoptions-lib.lua") +local ly_opts = lua_options.client('ly') local md5 = require 'md5' local lfs = require 'lfs' -local latex = {} local ly = { err = err, varwidth_available = kpse.find_file('varwidth.sty') @@ -67,19 +66,16 @@ local LY_HEAD = [[ %%File header \version "<<>>" <<>> - -<<>> - #(define inside-lyluatex #t) #(set-global-staff-size <<>>) +<<>> \header { copyright = "" tagline = ##f } \paper{ - <<>> - two-sided = ##<<>> + <<>> two-sided = ##<<>> line-width = <<>>\pt <<>> <<>> @@ -88,8 +84,7 @@ local LY_HEAD = [[ \layout{ <<>> <<>> -} -<<
>> +}<<
>> %%Follows original score ]] @@ -121,13 +116,16 @@ end local function font_default_staffsize() - return lib.fontinfo(font.current()).size/39321.6 + return lib.current_font_size()/39321.6 end local function includes_parse(list) local includes = '' if list then + includes = [[ + +]] list = list:explode(',') for _, included_file in ipairs(list) do warn(included_file) @@ -197,12 +195,11 @@ end --[[ ================ Bounding box calculations =========================== --]] -local bbox = {} -function bbox.get(filename, line_width) - return bbox.read(filename) or bbox.parse(filename, line_width) +function bbox_get(filename, line_width) + return bbox_read(filename) or bbox_parse(filename, line_width) end -function bbox.calc(x_1, x_2, y_1, y_2, line_width) +function bbox_calc(x_1, x_2, y_1, y_2, line_width) local bb = { ['protrusion'] = -lib.convert_unit(("%fbp"):format(x_1)), ['r_protrusion'] = lib.convert_unit(("%fbp"):format(x_2)) - line_width, @@ -216,7 +213,7 @@ function bbox.calc(x_1, x_2, y_1, y_2, line_width) return bb end -function bbox.parse(filename, line_width) +function bbox_parse(filename, line_width) -- get BoundingBox from EPS file local bbline = lib.readlinematching('^%%%%BoundingBox', io.open(filename..'.eps', 'r')) if not bbline then return end @@ -239,24 +236,24 @@ function bbox.parse(filename, line_width) end local f = io.open(filename .. '.bbox', 'w') f:write( - string.format("return %s, %s, %s, %s, %s", x_1, y_1, x_2, y_2, line_width) + string.format("return %f, %f, %f, %f, %f", x_1, y_1, x_2, y_2, line_width) ) f:close() - return bbox.calc(x_1, x_2, y_1, y_2, line_width) + return bbox_calc(x_1, x_2, y_1, y_2, line_width) end -function bbox.read(f) +function bbox_read(f) f = f .. '.bbox' if lfs.isfile(f) then local x_1, y_1, x_2, y_2, line_width = dofile(f) - return bbox.calc(x_1, x_2, y_1, y_2, line_width) + return bbox_calc(x_1, x_2, y_1, y_2, line_width) end end --[[ =============== Functions that output LaTeX code ===================== --]] -function latex.filename(printfilename, insert, input_file) +function latex_filename(printfilename, insert, input_file) if printfilename and input_file then if insert ~= 'systems' then warn('`printfilename` only works with `insert=systems`') @@ -267,7 +264,7 @@ function latex.filename(printfilename, insert, input_file) end end -function latex.fullpagestyle(style, ppn) +function latex_fullpagestyle(style, ppn) local function texoutput(s) tex.sprint('\\includepdfset{pagecommand='..s..'}%') end if style == '' then if ppn then texoutput('\\thispagestyle{empty}') @@ -277,7 +274,7 @@ function latex.fullpagestyle(style, ppn) end end -function latex.includeinline(pdfname, height, valign, hpadding, voffset) +function latex_includeinline(pdfname, height, valign, hpadding, voffset) local v_base if valign == 'bottom' then v_base = 0 elseif valign == 'top' then v_base = lib.convert_unit('1em') - height @@ -285,27 +282,25 @@ function latex.includeinline(pdfname, height, valign, hpadding, voffset) end tex.sprint( string.format( - [[\hspace{%fpt}\raisebox{%fpt}{\includegraphics{%s-1.pdf}}\hspace{%fpt}]], + [[\hspace{%fpt}\raisebox{%fpt}{\includegraphics{%s-1}}\hspace{%fpt}]], hpadding, v_base + voffset, pdfname, hpadding ) ) end -function latex.includepdf(pdfname, range, papersize) - local noautoscale = '' - if papersize then noautoscale = 'noautoscale' end +function latex_includepdf(pdfname, range, papersize) tex.sprint(string.format( [[\includepdf[pages={%s},%s]{%s}]], - table.concat(range, ','), noautoscale, pdfname + table.concat(range, ','), papersize and 'noautoscale' or '', pdfname )) end -function latex.includesystems(filename, range, protrusion, gutter, staffsize, indent_offset) +function latex_includesystems(filename, range, protrusion, gutter, staffsize, indent_offset) local h_offset = protrusion + indent_offset local texoutput = '\\ifx\\preLilyPondExample\\undefined\\else\\preLilyPondExample\\fi\n' texoutput = texoutput..'\\par\n' for index, system in pairs(range) do - if not lfs.isfile(filename..'-'..system..'.pdf') then break end + if not lfs.isfile(filename..'-'..system..'.eps') then break end texoutput = texoutput.. string.format([[ \noindent\hspace*{%fpt}\includegraphics{%s}%% @@ -327,13 +322,13 @@ function latex.includesystems(filename, range, protrusion, gutter, staffsize, in tex.sprint(texoutput:explode('\n')) end -function latex.label(label, labelprefix) +function latex_label(label, labelprefix) if label then tex.sprint('\\label{'..labelprefix..label..'}%%') end end ly.verbenv = {[[\begin{verbatim}]], [[\end{verbatim}]]} -function latex.verbatim(verbatim, ly_code, intertext, version) +function latex_verbatim(verbatim, ly_code, intertext, version) if verbatim then if version then tex.sprint('\\lyVersion{'..version..'}') end local content = table.concat(ly_code:explode('\n'), '\n'):gsub( @@ -372,12 +367,12 @@ function Score:bbox(system) if not self.bboxes then self.bboxes = {} for i = 1, self:count_systems() do - table.insert(self.bboxes, bbox.get(self.output..'-'..i, self['line-width'])) + table.insert(self.bboxes, bbox_get(self.output..'-'..i, self['line-width'])) end end return self.bboxes[system] else - if not self.bbox then self.bbox = bbox.get(self.output, self['line-width']) end + if not self.bbox then self.bbox = bbox_get(self.output, self['line-width']) end return self.bbox end end @@ -707,26 +702,27 @@ function Score:content() end function Score:count_systems(force) - if force or not self.system_count then - local f = io.open(self.output..'-systems.count', 'r') - if f then - self.system_count = tonumber(f:read('*all')) - f:close() - else self.system_count = 0 + local count = self.system_count + if force or not count then + count = 0 + local systems = self.output:match("[^/]*$").."%-%d+%.eps" + for f in lfs.dir(self.tmpdir) do + if f:match(systems) then + count = count + 1 + end end + self.system_count = count end - return self.system_count + return count end function Score:delete_intermediate_files() for _, filename in pairs(self.output_names) do if self.insert == 'fullpage' then os.remove(filename..'.ps') else - for i = 1, self:count_systems() do os.remove(filename..'-'..i..'.eps') end os.remove(filename..'-systems.tex') os.remove(filename..'-systems.texi') os.remove(filename..'.eps') - os.remove(filename..'.pdf') end end end @@ -785,7 +781,7 @@ end function Score:is_compiled() if self['force-compilation'] then return false end - return lfs.isfile(self.output..'.pdf') or self:count_systems(true) ~= 0 + return lfs.isfile(self.output..'.pdf') or lfs.isfile(self.output..'.eps') or self:count_systems(true) ~= 0 end function Score:is_odd_page() return tex.count['c@page'] % 2 == 1 end @@ -799,11 +795,10 @@ function Score:lilypond_cmd() input = self.output..".ly 2>&1" mode = 'r' end - local cmd = '"'..self.program..'" '.. - "-dno-point-and-click ".. - "-djob-count=2 ".. - "-dno-delete-intermediate-files " - if self['optimize-pdf'] and self:lilypond_has_TeXGS() then cmd = cmd.."-O TeX-GS " end + local cmd = '"'..self.program..'" ' + .. (self.insert == "fullpage" and "" or "-E ") + .. "-dno-point-and-click -djob-count=2 -dno-delete-intermediate-files " + if self['optimize-pdf'] and self:lilypond_has_TeXGS() then cmd = cmd.."-O TeX-GS -dgs-never-embed-fonts " end if self.input_file then cmd = cmd..'-I "'..lib.dirname(self.input_file):gsub('^%./', lfs.currentdir()..'/')..'" ' end @@ -844,6 +839,7 @@ function Score:ly_fixbadlycroppedstaffgroupbrackets() (ly:grob-set-property! grob 'Y-extent (cons (- (car Y-off) 1.7) (+ (cdr Y-off) 1.7))))) }]] + or '%% no fix for badly cropped StaffGroup brackets' end function Score:ly_fonts() @@ -859,6 +855,8 @@ function Score:ly_fonts() self.sffamily, self.ttfamily ) + else + return '%% fonts not set' end end @@ -869,11 +867,16 @@ end function Score:ly_indent() if not (self.indent == false and self.insert == 'fullpage') then return [[indent = ]]..(self.indent or 0)..[[\pt]] + else + return '%% no indent set' end end function Score:ly_language() - if self.language then return '\\language "'..self.language..'"' end + if self.language then return '\\language "'..self.language..'"'..[[ + +]] + else return '' end end function Score:ly_linewidth() return self['line-width'] end @@ -883,16 +886,16 @@ function Score:ly_staffsize() return self.staffsize end function Score:ly_margins() local horizontal_margins = self.twoside and string.format([[ - inner-margin = %s\pt]], self:tex_margin_inner()) + inner-margin = %f\pt]], self:tex_margin_inner()) or string.format([[ - left-margin = %s\pt]], self:tex_margin_left()) + left-margin = %f\pt]], self:tex_margin_left()) local tex_top = self['extra-top-margin'] + self:tex_margin_top() local tex_bottom = self['extra-bottom-margin'] + self:tex_margin_bottom() if self.fullpagealign == 'crop' then return string.format([[ - top-margin = %s\pt - bottom-margin = %s\pt + top-margin = %f\pt + bottom-margin = %f\pt %s]], tex_top, tex_bottom, horizontal_margins ) @@ -904,18 +907,18 @@ function Score:ly_margins() bottom-margin = 0\pt %s top-system-spacing = - #'((basic-distance . %s) - (minimum-distance . %s) + #'((basic-distance . %f) + (minimum-distance . %f) (padding . 0) (stretchability . 0)) top-markup-spacing = - #'((basic-distance . %s) - (minimum-distance . %s) + #'((basic-distance . %f) + (minimum-distance . %f) (padding . 0) (stretchability . 0)) last-bottom-spacing = - #'((basic-distance . %s) - (minimum-distance . %s) + #'((basic-distance . %f) + (minimum-distance . %f) (padding . 0) (stretchability . 0)) ]], @@ -940,7 +943,7 @@ end function Score:ly_paper() local system_count = - self['system-count'] == 0 and '' + self['system-count'] == '0' and '' or 'system-count = '..self['system-count']..'\n ' local papersize = '#(set-paper-size "'..(self.papersize or 'lyluatexfmt')..'")' @@ -949,33 +952,33 @@ function Score:ly_paper() local pfpn = self['print-first-page-number'] and 't' or 'f' local ppn = self['print-page-number'] and 't' or 'f' return string.format([[ -%s%s + %s%s print-page-number = ##%s print-first-page-number = ##%s - first-page-number = %s + first-page-number = %d %s]], - system_count, papersize, ppn, pfpn, - first_page_number, self:ly_margins() + system_count, papersize, ppn, pfpn, + first_page_number, self:ly_margins() ) else - if self.papersize then - papersize = papersize..[[ -]] - else - papersize = '' - end + return string.format([[%s%s]], papersize..[[ - return string.format([[%s%s]], papersize, system_count) +]], system_count) end end function Score:ly_preamble() + local result = string.format( + [[#(set! paper-alist (cons '("lyluatexfmt" . (cons (* %f pt) (* %f pt))) paper-alist))]], + self.paperwidth, self.paperheight + ) if self.insert == 'fullpage' then - return string.format( - [[#(set! paper-alist (cons '("lyluatexfmt" . (cons (* %s pt) (* %s pt))) paper-alist))]], - self.paperwidth, self.paperheight - ) - else return [[\include "lilypond-book-preamble.ly"]] + return result + else + return result..[[ + + +\include "lilypond-book-preamble.ly"]] end end @@ -984,11 +987,17 @@ function Score:ly_raggedright() if self['ragged-right'] then return 'ragged-right = ##t' else return 'ragged-right = ##f' end + else + return '%% no alignment set' end end function Score:ly_staffprops() - local clef, timing, timesig, staff = '', '', '', '' + local clef, timing, timesig, staff = + '%% no clef set', + ' %% timing not suppressed', + ' %% no time signature set', + ' %% staff symbol not suppressed' if self.noclef then clef = [[\context { \Staff \remove "Clef_engraver" }]] end if self.notiming then timing = [[\context { \Score timing = ##f }]] end if self.notimesig then timesig = [[\context { \Staff \remove "Time_signature_engraver" }]] end @@ -1015,28 +1024,29 @@ function Score:optimize_pdf() end, 'lyluatex optimize-pdf' ) - end - local pdf2ps, ps2pdf, path - for file in lfs.dir(self.tmpdir) do - path = self.tmpdir..'/'..file - if path:match(self.output) and path:sub(-4) == '.pdf' then - pdf2ps = io.popen( - 'gs -q -sDEVICE=ps2write -sOutputFile=- -dNOPAUSE '..path..' -c quit', - 'r' - ) - ps2pdf = io.popen( - 'gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile='..path..'-gs -', - 'w' - ) - if pdf2ps then - ps2pdf:write(pdf2ps:read('*a')) - pdf2ps:close() - ps2pdf:close() - os.rename(path..'-gs', path) - else - warn( - [[You have asked for pdf optimization, but gs wasn't found.]] + else + local pdf2ps, ps2pdf, path + for file in lfs.dir(self.tmpdir) do + path = self.tmpdir..'/'..file + if path:match(self.output) and path:sub(-4) == '.pdf' then + pdf2ps = io.popen( + 'gs -q -sDEVICE=ps2write -sOutputFile=- -dNOPAUSE '..path..' -c quit', + 'r' + ) + ps2pdf = io.popen( + 'gs -q -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -sOutputFile='..path..'-gs -', + 'w' ) + if pdf2ps then + ps2pdf:write(pdf2ps:read('*a')) + pdf2ps:close() + ps2pdf:close() + os.rename(path..'-gs', path) + else + warn( + [[You have asked for pdf optimization, but gs wasn't found.]] + ) + end end end end @@ -1081,9 +1091,9 @@ points to a valid LilyPond executable. err(warning) end end - -- with bbox.read check_protrusion will only execute with + -- with bbox_read check_protrusion will only execute with -- a prior compilation, otherwise it will be ignored - local do_compile = not self:check_protrusion(bbox.read) + local do_compile = not self:check_protrusion(bbox_read) if self['force-compilation'] or do_compile then repeat self.complete_ly_code = self:header()..self:content()..self:footer() @@ -1094,7 +1104,7 @@ points to a valid LilyPond executable. self:clean_failed_compilation() break end - until self:check_protrusion(bbox.get) + until self:check_protrusion(bbox_get) self:optimize_pdf() else table.insert(self.output_names, self.output) end @@ -1112,9 +1122,9 @@ end function Score:run_lily_proc(p) if self.debug then - local f = io.open(self.output..".log", 'w') - f:write(p:read('*a')) - f:close() + local f = io.open(self.output..".log", 'w') + f:write(p:read('*a')) + f:close() else p:write(self.complete_ly_code) end return p:close() @@ -1127,6 +1137,11 @@ function Score:run_lilypond() self.debug = true self.lilypond_error = not self:run_lily_proc(io.popen(self:lilypond_cmd(self.complete_ly_code))) end + local lilypond_pdf, mode = self:lilypond_cmd(self.complete_ly_code) + if lilypond_pdf:match"-E" then + lilypond_pdf = lilypond_pdf:gsub(" %-E", " --pdf") + self:run_lily_proc(io.popen(lilypond_pdf, mode)) + end end function Score:tex_margin_bottom() @@ -1140,7 +1155,7 @@ end function Score:tex_margin_inner() self._tex_margin_inner = self._tex_margin_inner or lib.convert_unit(( - tex.sp('1in') + tex.dimen.oddsidemargin + tex.dimen.hoffset + tex.sp('1in') + tex.dimen.oddsidemargin + tex.dimen.hoffset )..'sp') return self._tex_margin_inner end @@ -1174,16 +1189,16 @@ function Score:tex_margin_top() end function Score:write_latex(do_compile) - latex.filename(self.printfilename, self.insert, self.input_file) - latex.verbatim(self.verbatim, self.ly_code, self.intertext, self.addversion) + latex_filename(self.printfilename, self.insert, self.input_file) + latex_verbatim(self.verbatim, self.ly_code, self.intertext, self.addversion) if do_compile and not self:check_compilation() then return end --[[ Now we know there is a proper score --]] - latex.fullpagestyle(self.fullpagestyle, self['print-page-number']) - latex.label(self.label, self.labelprefix) + latex_fullpagestyle(self.fullpagestyle, self['print-page-number']) + latex_label(self.label, self.labelprefix) if self.insert == 'fullpage' then - latex.includepdf(self.output, self.range, self.papersize) + latex_includepdf(self.output, self.range, self.papersize) elseif self.insert == 'systems' then - latex.includesystems( + latex_includesystems( self.output, self.range, self.protrusion_left, self.leftgutter, self.staffsize, self.indent_offset ) @@ -1196,7 +1211,7 @@ This will probably cause bad output.]] end local bb = self:bbox(1) if bb then - latex.includeinline( + latex_includeinline( self.output, bb.height, self.valign, self.hpadding, self.voffset ) end @@ -1342,20 +1357,20 @@ end function ly.set_fonts(rm, sf, tt) -if ly.score.rmfamily..ly.score.sffamily..ly.score.ttfamily ~= '' then - ly.score['pass-fonts'] = 'true' - info("At least one font family set explicitly. Activate 'pass-fonts'") -end - if ly.score.rmfamily == '' then ly.score.rmfamily = ly.get_font_family(rm) - else - -- if explicitly set don't override rmfamily with 'current' font - if ly.score['current-font-as-main'] then - info("rmfamily set explicitly. Deactivate 'current-font-as-main'") - end - ly.score['current-font-as-main'] = false - end - if ly.score.sffamily == '' then ly.score.sffamily = ly.get_font_family(sf) end - if ly.score.ttfamily == '' then ly.score.ttfamily = ly.get_font_family(tt) end + if ly.score.rmfamily..ly.score.sffamily..ly.score.ttfamily ~= '' then + ly.score['pass-fonts'] = 'true' + info("At least one font family set explicitly. Activate 'pass-fonts'") + end + if ly.score.rmfamily == '' then ly.score.rmfamily = ly.get_font_family(rm) + else + -- if explicitly set don't override rmfamily with 'current' font + if ly.score['current-font-as-main'] then + info("rmfamily set explicitly. Deactivate 'current-font-as-main'") + end + ly.score['current-font-as-main'] = false + end + if ly.score.sffamily == '' then ly.score.sffamily = ly.get_font_family(sf) end + if ly.score.ttfamily == '' then ly.score.ttfamily = ly.get_font_family(tt) end end diff --git a/support/lyluatex/lyluatex.pdf b/support/lyluatex/lyluatex.pdf index adc9003791..8f546a0f9b 100644 Binary files a/support/lyluatex/lyluatex.pdf and b/support/lyluatex/lyluatex.pdf differ diff --git a/support/lyluatex/lyluatex.sty b/support/lyluatex/lyluatex.sty index f0d70d9878..e0108513d9 100644 --- a/support/lyluatex/lyluatex.sty +++ b/support/lyluatex/lyluatex.sty @@ -1,22 +1,20 @@ %Lyluatex LaTeX style. % -% Copyright (C) 2015-2019 jperon and others (see CONTRIBUTORS.md) +% Copyright (C) 2015-2022 jperon and others (see CONTRIBUTORS.md) % License: MIT % This file is part of lyluatex. \NeedsTeXFormat{LaTeX2e}% -\ProvidesPackage{lyluatex}[2019/05/27 v1.0f] %%LYLUATEX_DATE LYLUATEX_VERSION +\ProvidesPackage{lyluatex}[2022/10/30 v1.1] %%LYLUATEX_DATE LYLUATEX_VERSION % Dependencies -\RequirePackage{luatexbase} -\RequirePackage{luaotfload} -\RequirePackage{xkeyval} \RequirePackage{graphicx} \RequirePackage{minibox} \RequirePackage{environ} \RequirePackage{currfile} \RequirePackage{pdfpages} \IfFileExists{varwidth.sty}{\RequirePackage{varwidth}}{} +\RequirePackage{luaoptions} \RequirePackage{metalogo} \newcommand{\lyluatex}{\textit{ly}\LuaTeX} @@ -43,10 +41,8 @@ % Options \catcode`-=11 \directlua{ - local _opt = require( - kpse.find_file("lyluatex-options.lua") or "lyluatex-options.lua" - ) - ly_opts = _opt.Opts:new('ly_opts', { + local _opt = lua_options + lua_options.register('ly', { ['addversion'] = {'false', 'true', ''}, ['autoindent'] = {'true', 'false', ''}, ['cleantmp'] = {'false', 'true', ''}, @@ -133,7 +129,7 @@ \directlua{ ly = require(kpse.find_file("lyluatex.lua") or "lyluatex.lua") ly.make_list_file() - if ly_opts.cleantmp then + if lua_options.client('ly').cleantmp then luatexbase.add_to_callback('stop_run', ly.clean_tmp_dir, 'lyluatex cleantmp') luatexbase.add_to_callback('stop_run', ly.conclusion_text, 'lyluatex conclusion') end @@ -157,9 +153,6 @@ \setlength{\hfuzz}{\ly@old@hfuzz}% } -% Command to change options during the document -\newcommand{\lysetoption}[2]{\directlua{ly_opts:set_option([[#1]], [[#2]])}} - % How the filename of a score will look like (if printed) \newcommand{\lyFilename}[1]{\noindent #1\par\bigskip} @@ -174,7 +167,9 @@ % *current* font for optional use. \newcommand{\ly@currentfonts}{% \begingroup% - \directlua{ly_opts:set_option('current-font', ly.get_font_family(font.current()))}% + \setluaoption{ly}{current-font}{% + \directlua{ly.get_font_family(font.current())} + } \rmfamily \edef\rmfamilyid{\fontid\font}% \sffamily \edef\sffamilyid{\fontid\font}% \ttfamily \edef\ttfamilyid{\fontid\font}% @@ -188,9 +183,9 @@ % Score processing \newcommand*{\ly@compilescore}[1]{% \ly@setunits% + \setluaoption{ly}{currfiledir}{\currfiledir} + \setluaoption{ly}{twoside}{\ly@istwosided} \directlua{ - ly_opts:set_option('currfiledir', [[\currfiledir]]) - ly_opts:set_option('twoside', '\ly@istwosided') #1 ly.newpage_if_fullpage() }% diff --git a/support/lyluatex/lyluatex.tex b/support/lyluatex/lyluatex.tex index aaa95d7848..a804663555 100644 --- a/support/lyluatex/lyluatex.tex +++ b/support/lyluatex/lyluatex.tex @@ -1,38 +1,45 @@ -\PassOptionsToPackage{unicode=true}{hyperref} % options for packages loaded elsewhere +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode}{hyperref} \PassOptionsToPackage{hyphens}{url} % -\documentclass[]{lyluatexmanual} +\documentclass[ +]{lyluatexmanual} +\usepackage{amsmath,amssymb} \usepackage[]{libertine} -\usepackage{amssymb,amsmath} -\usepackage{ifxetex,ifluatex} -\usepackage{fixltx2e} % provides \textsubscript -\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex +\usepackage{iftex} +\ifPDFTeX \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} - \usepackage{textcomp} % provides euro and other symbols -\else % if luatex or xelatex + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex \usepackage{unicode-math} - \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase} + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} \fi -% use upquote if available, for straight quotes in verbatim environments +% Use upquote if available, for straight quotes in verbatim environments \IfFileExists{upquote.sty}{\usepackage{upquote}}{} -% use microtype if available -\IfFileExists{microtype.sty}{% -\usepackage[]{microtype} -\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts }{} -\IfFileExists{parskip.sty}{% -\usepackage{parskip} -}{% else -\setlength{\parindent}{0pt} -\setlength{\parskip}{6pt plus 2pt minus 1pt} -} -\usepackage{hyperref} +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +\usepackage{xcolor} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} \hypersetup{ - pdfauthor={Fr. Jacques Peron; Urs Liska; Br. Samuel Springuel}, - pdfborder={0 0 0}, - breaklinks=true} -\urlstyle{same} % don't use monospace font for urls + pdfauthor={Fr.~Jacques Peron; Urs Liska; Br. Samuel Springuel}, + hidelinks, + pdfcreator={LaTeX via pandoc}} +\urlstyle{same} % disable monospaced font for URLs \usepackage{color} \usepackage{fancyvrb} \newcommand{\VerbBar}{|} @@ -44,7 +51,7 @@ \newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} \newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}} \newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} -\newcommand{\BuiltInTok}[1]{#1} +\newcommand{\BuiltInTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{#1}} \newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} \newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}} \newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} @@ -57,7 +64,7 @@ \newcommand{\ExtensionTok}[1]{#1} \newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}} \newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}} -\newcommand{\ImportTok}[1]{#1} +\newcommand{\ImportTok}[1]{\textcolor[rgb]{0.00,0.50,0.00}{\textbf{#1}}} \newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} \newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}} \newcommand{\NormalTok}[1]{#1} @@ -71,30 +78,23 @@ \newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}} \newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}} \newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}} -\setlength{\emergencystretch}{3em} % prevent overfull lines +\setlength{\emergencystretch}{3em} % prevent overfull lines \providecommand{\tightlist}{% \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} -\setcounter{secnumdepth}{0} -% Redefines (sub)paragraphs to behave more like sections -\ifx\paragraph\undefined\else -\let\oldparagraph\paragraph -\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} -\fi -\ifx\subparagraph\undefined\else -\let\oldsubparagraph\subparagraph -\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures \fi -% set default figure placement to htbp +\title{\lyluatex} +\usepackage{etoolbox} \makeatletter -\def\fps@figure{htbp} +\providecommand{\subtitle}[1]{% add subtitle to \maketitle + \apptocmd{\@title}{\par {\large #1 \par}}{}{} +} \makeatother - - -\title{\lyluatex} -\providecommand{\subtitle}[1]{} -\subtitle{1.0f} -\author{Fr. Jacques Peron \and Urs Liska \and Br. Samuel Springuel} +\subtitle{1.1} +\author{Fr.~Jacques Peron \and Urs Liska \and Br. Samuel Springuel} \date{\lyluatexmanualdate} \begin{document} @@ -317,8 +317,8 @@ Linux with TeXLive: \begin{Shaded} \begin{Highlighting}[] -\ExtensionTok{%}\NormalTok{ export shell_escape_commands=}\VariableTok{$(}\ExtensionTok{kpsewhich}\NormalTok{ -expand-var }\StringTok{'$shell_escape_commands'}\VariableTok{)}\NormalTok{,lilypond,gs} -\ExtensionTok{%}\NormalTok{ lualatex --shell-restricted DOCUMENT.tex} +\ExtensionTok{\%}\NormalTok{ export shell\_escape\_commands=}\VariableTok{$(}\ExtensionTok{kpsewhich} \AttributeTok{{-}expand{-}var} \StringTok{\textquotesingle{}$shell\_escape\_commands\textquotesingle{}}\VariableTok{)}\NormalTok{,lilypond,gs} +\ExtensionTok{\%}\NormalTok{ lualatex }\AttributeTok{{-}{-}shell{-}restricted}\NormalTok{ DOCUMENT.tex} \end{Highlighting} \end{Shaded} @@ -347,13 +347,13 @@ The basic mode of inserting scores into text documents is the \KeywordTok{\textbackslash{}score} \KeywordTok{\{} \KeywordTok{\textbackslash{}new} \DataTypeTok{ChoirStaff}\NormalTok{ \textbackslash{}with}\KeywordTok{ \{} \DataTypeTok{instrumentName}\NormalTok{ = "}\StringTok{2 Fl."} - \KeywordTok{\}} \KeywordTok{<<} - \KeywordTok{\textbackslash{}new} \DataTypeTok{Staff} \FunctionTok{\textbackslash{}transpose c c'} \FunctionTok{\textbackslash{}music} + \KeywordTok{\}} \KeywordTok{\textless{}\textless{}} + \KeywordTok{\textbackslash{}new} \DataTypeTok{Staff} \FunctionTok{\textbackslash{}transpose c c\textquotesingle{}} \FunctionTok{\textbackslash{}music} \KeywordTok{\textbackslash{}new} \DataTypeTok{Staff} \KeywordTok{\{} \FunctionTok{\textbackslash{}clef bass} \FunctionTok{\textbackslash{}music} \KeywordTok{\}} - \KeywordTok{>>} + \KeywordTok{\textgreater{}\textgreater{}} \KeywordTok{\}} \FunctionTok{\textbackslash{}end}\KeywordTok{\{}\NormalTok{lilypond}\KeywordTok{\}} \end{Highlighting} @@ -510,23 +510,23 @@ arguments to the individual command or environments: \begin{Highlighting}[] \FunctionTok{\textbackslash{}lilypondfile}\NormalTok{[key1=value1]\{path/to/file.ly\}} -\FunctionTok{\textbackslash{}lilypond}\NormalTok{[key1=value1]\{ c' d' e' \}} +\FunctionTok{\textbackslash{}lilypond}\NormalTok{[key1=value1]\{ c\textquotesingle{} d\textquotesingle{} e\textquotesingle{} \}} \KeywordTok{\textbackslash{}begin}\NormalTok{\{}\ExtensionTok{lilypond}\NormalTok{\}[key1=value1]} \NormalTok{\{} -\NormalTok{ c' d' e'} +\NormalTok{ c\textquotesingle{} d\textquotesingle{} e\textquotesingle{}} \NormalTok{\}} \KeywordTok{\textbackslash{}end}\NormalTok{\{}\ExtensionTok{lilypond}\NormalTok{\}} \end{Highlighting} \end{Shaded} -\lyCmd{lysetoption} +\lyCmd{setluaoption{ly}} At any place in the document the value of an option can be changed using \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}lysetoption}\NormalTok{\{key\}\{new-value\}} +\FunctionTok{\textbackslash{}setluaoption}\NormalTok{\{ly\}\{key\}\{new{-}value\}} \end{Highlighting} \end{Shaded} @@ -756,7 +756,7 @@ detail. If not stated otherwise dimensions can be given in arbitrary \TeX~units, e.g. \texttt{200pt}, \texttt{1ex} or \texttt{3cm} or as \TeX~lengths, -e.g. \texttt{0.4\textbackslash{}textwidth}. +e.g.~\texttt{0.4\textbackslash{}textwidth}. \hypertarget{general}{% \paragraph{General}\label{general}} @@ -1169,7 +1169,7 @@ example: \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}lilypond}\NormalTok{\{a' b' c'\}} +\FunctionTok{\textbackslash{}lilypond}\NormalTok{\{a\textquotesingle{} b\textquotesingle{} c\textquotesingle{}\}} \end{Highlighting} \end{Shaded} @@ -1372,8 +1372,8 @@ monospace: \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyFilename}\NormalTok{\}[1]\{}\CommentTok{%} -\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}texttt}\NormalTok{\{#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{%} +\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyFilename}\NormalTok{\}[1]\{}\CommentTok{\%} +\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}texttt}\NormalTok{\{\#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{\%} \NormalTok{\}} \end{Highlighting} \end{Shaded} @@ -1425,8 +1425,8 @@ indent and prints the text blue: \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyIntertext}\NormalTok{\}[1]\{}\CommentTok{%} -\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}textcolor}\NormalTok{\{blue\}\{#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{%} +\FunctionTok{\textbackslash{}renewcommand}\NormalTok{\{}\ExtensionTok{\textbackslash{}lyIntertext}\NormalTok{\}[1]\{}\CommentTok{\%} +\FunctionTok{\textbackslash{}noindent} \FunctionTok{\textbackslash{}textcolor}\NormalTok{\{blue\}\{\#1\}}\FunctionTok{\textbackslash{}par\textbackslash{}bigskip}\CommentTok{\%} \NormalTok{\}} \end{Highlighting} \end{Shaded} @@ -1452,11 +1452,11 @@ match today is to use the \texttt{TeX} highlighting of the \begin{Shaded} \begin{Highlighting}[] -\CommentTok{% In the document header:} +\CommentTok{\% In the document header:} \BuiltInTok{\textbackslash{}usepackage}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}} -\CommentTok{% anywhere in the header or the body:} -\FunctionTok{\textbackslash{}lysetverbenv}\NormalTok{\{}\KeywordTok{\textbackslash{}begin}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}\{TeX\}\}\{\textbackslash{}end\{minted\}\}} +\CommentTok{\% anywhere in the header or the body:} +\FunctionTok{\textbackslash{}lysetverbenv}\NormalTok{\{}\KeywordTok{\textbackslash{}begin}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}\{TeX\}}\VerbatimStringTok{\}\{}\KeywordTok{\textbackslash{}end}\NormalTok{\{}\ExtensionTok{minted}\NormalTok{\}\}} \end{Highlighting} \end{Shaded} @@ -1505,9 +1505,9 @@ absolute paths in that process. \begin{Shaded} \begin{Highlighting}[] -\FunctionTok{\textbackslash{}lysetoption}\NormalTok{\{includepaths\}\{}\FunctionTok{\textbackslash{}string}\NormalTok{~/lilypond-lib\}} +\FunctionTok{\textbackslash{}setluaoption}\NormalTok{\{ly\}\{includepaths\}\{}\FunctionTok{\textbackslash{}string}\NormalTok{\textasciitilde{}/lilypond{-}lib\}} -\FunctionTok{\textbackslash{}lilypondfile}\NormalTok{[includepaths=\{}\FunctionTok{\textbackslash{}string}\NormalTok{~/lilypond-lib,/home/johndoe/project-lib\}]} +\FunctionTok{\textbackslash{}lilypondfile}\NormalTok{[includepaths=\{}\FunctionTok{\textbackslash{}string}\NormalTok{\textasciitilde{}/lilypond{-}lib,/home/johndoe/project{-}lib\}]} \end{Highlighting} \end{Shaded} @@ -1774,22 +1774,31 @@ Those examples and others may be found in \addcontentsline{toc}{subsection}{Insert Systems} \hypertarget{insert-systems}{} + \section*{Insert System-by-System} + By default scores defined by the \option{lilypond} environment or the \cmd{lilypondfile} command are inserted as a sequence of systems. + \lyluatex\ determines the vertical space between the systems as a flexible length calculated from the \emph{staff size} of the score (as opposed to from the font size) to produce an regular-looking vertical spacing: + \begin{lilypond}[] { \repeat unfold 30 { c' d' e' d' } } \end{lilypond} + The following score has a significantly smaller staff size, and consequently the inter-system space is reduced: + \begin{lilypond}[staffsize=12] { \repeat unfold 36 { c' d' e' d' } } \end{lilypond} + \subsection*{Before and After the Score} + \cmd{preLilyPondExample} and \cmd{postLilyPondExample} allow some code to be printed before and after the score. This may for example be used to wrap the resulting score in an environment. In the following example rules are printed: + \def\preLilyPondExample{% \par\bigskip \noindent Before the score: @@ -1798,35 +1807,43 @@ The following score has a significantly smaller staff size, and consequently the \par\bigskip \hrule\par\medskip\noindent After the score \par\bigskip} + \begin{verbatim} \newcommand{\preLilyPondExample}{% \par\bigskip \noindent Before the score: \par\medskip\hrule\par\medskip} + \newcommand{\postLilyPondExample}{% \par\bigskip \hrule\par\medskip\noindent After the score \par\bigskip} \end{verbatim} + \begin{lilypond}[] { \repeat unfold 30 { c' d' e' d' } } \end{lilypond} + \subsection*{Configuring the Inter-System Content} + \let\preLilyPondExample\undefined \let\postLilyPondExample\undefined + Using \cmd{betweenLilyPondSystem} it is possible to define a macro that is expanded between each system pair. It is given the index of the previous system as an argument to work with. The following example simply prints that index between the systems, but with some programming more complicated and useful things could be done, for example printing a rule after every third system or conditionally insert a page break. + \def\betweenLilyPondSystem#1{% \begin{center} System #1 \end{center} } + \begin{verbatim} \newcommand{\betweenLilyPondSystem}[1]{% \begin{center} @@ -1834,42 +1851,53 @@ System #1 \end{center} } \end{verbatim} + \bigskip + \begin{lilypond}[] { \repeat unfold 30 { c' d' e' d' } } \end{lilypond} + \let\betweenLilyPondSystem\undefined + \addcontentsline{toc}{subsection}{Insert Inline} \hypertarget{insert-inline}{} + \section*{Insert Scores Inline} + With the \option{insert=inline} option it is simple to insert arbitrary notational fragments in the \lilypond{ e'8 d'16 e' } continuous text of a document. By default the staffsize is scaled to be 2/3 of the staffsize a regular score would have at this point. This means if the \option{staffsize} option is modified globally or locally then the staffsize of the inline score is changed too. + In order to make the size of inline scores independent from the regular staffsize the option \option{inline-staffsize} can be used the same way as \option{staffsize}. \lilypond[inline-staffsize=8]{ e'8 d'16 e' } has the inline staffsize manually set to \texttt{8}. + \paragraph{Alignment and padding} By default inline scores are vertically centered to a line 1/2em above the text's baseline. \lilypond[valign=top]{ e'8 d'16 e' } but the score can also be aligned \lilypond[valign=bottom]{ e'8 d'16 e' } to the top or the baseline of the text. + Unfortunately this can only consider the borders of the \emph{image} and not those of the \emph{score} or the staff lines. To alleviate this situation a specific vertical offset can be given with \option{voffset=-3pt} (or any other \TeX\ lengths). This offset is calculated after the alignment. \lilypond[valign=bottom,voffset=-6pt]{ e'8 d'16 e' } is inserted with \option{valign=bottom,voffset=-4pt}. + Horizontally inline scores are padded by \option{hpadding=0.75ex} -- except if they happen to appear at the beginning or end of a line, as can be seen in the last score in the previous paragraph. \lilypond[hpadding=2em]{ e'8 d'16 e' } Increasing the \option{hpadding} will ensure more space around the score. + \paragraph{Bare Inline scores} \option{insert=bare-inline} will remove all the staff elements (staff symbol, time signature, clef) by implicitly applying \option{nostaff}, which is most useful for including notational symbols like @@ -1885,121 +1913,165 @@ possibility of inserting arbitrary LilyPond material without having to prepare precompiled PDF images. + \addcontentsline{toc}{subsection}{Choosing Systems} \hypertarget{print-only}{} + \def\postLilyPondExample{\par\bigskip\hrule\par\bigskip} + \section*{Print only Selected Systems or Pages} + The \texttt{print-only} and \texttt{do-not-print} options allow to limit the printed systems or pages from a score. A typical use case is to print a score interspersed with comments. The advantage of this approach is that the score is compiled only once while the individual systems are simply reused by \LaTeX. + Throughout this document we'll demonstrate the different options to select systems from the following score: + \lilypondfile[verbatim]{eight-systems.ly} + The simplest selection is a single system: \texttt{print-only=4} + \lilypondfile[print-only=4]{eight-systems.ly} + Ranges are also possible: \texttt{print-only=3-5}, with the special form of \texttt{print-only=6-} which prints from the given system throughout the end of the score. Negative ranges can be given with \texttt{print-only=7-5} + \lilypondfile[print-only=3-5]{eight-systems.ly} + \lilypondfile[print-only=6-]{eight-systems.ly} + \lilypondfile[print-only=7-5]{eight-systems.ly} + With a comma-separated list an arbitrary sequence of systems can be specified. The list has to be enclosed in curly brackets: \texttt{print-only={4,1,2}} + \lilypondfile[print-only={4,1,2}]{eight-systems.ly} + Each element of the list can include any of the forms described above:\\ \texttt{print-only={3,5-7,4,7-}} + \lilypondfile[print-only={3,5-7,4,7-}]{eight-systems.ly} + \texttt{do-not-print} does the opposite: it prevents the list of systems from being printed. It might be used alone, or in combination with \texttt{print-only}:\\ \texttt{print-only=3-,do-not-print=6} + \lilypondfile[print-only=3-,do-not-print=6]{eight-systems.ly} + The functionality is identical with fullpage scores where the selection applies to \emph{pages} instead. This can for example be used when the “score” file contains a number of individual pieces (e.g. songs for a song book), and individual selections are to be printed. + Systems have some specific behaviour with regard to \emph{indent}, but this is demonstrated in its own file \texttt{dynamic-indent.tex}. + \let\postLilyPondExample\undefined + \addcontentsline{toc}{subsection}{Dynamic Indent Handling} \hypertarget{dynamic-indent}{} + \def\postLilyPondExample{\par\bigskip\hrule\par\bigskip} + \section*{Dynamic Indent} + This document demonstrates the use of \texttt{indent} and \texttt{autoindent}, partially in combination with \texttt{print-only}. + \texttt{indent=1cm} indents the first line, but if the resulting score contains only one system this indent is suppressed (issuing a warning on the console): + \begin{lilypond}[indent=1cm] \set Staff.instrumentName = "Violin" \repeat unfold 12 { c' d' e' d' } \end{lilypond} + \begin{lilypond}[indent=1cm] { \set Staff.instrumentName = "Violin" c' d' e' d' } \end{lilypond} + If the output of a score which contains more than one system is limited to the first system using \texttt{print-only=1} then the indent is removed but the score is recompiled to ensure a full-length system. The following score shows the two-system score from above (with \texttt{indent=1cm}), limited to its first system: + \begin{lilypond}[indent=1cm,print-only=1] \set Staff.instrumentName = "Violin" \repeat unfold 12 { c' d' e' d' } \end{lilypond} + Note that this behaviour also applies when \texttt{print-only} causes the first system to be printed at another position, e.g. with \texttt{print-only={3,1,2}}. In this case the indent of the first system is suppressed in order to avoid a “hole”. Of course this is a corner case, but might be useful when a score consists of separate entities (examples, exercises) per system. + \begin{lilypond}[indent=1cm,print-only={3,1,2},max-protrusion=0.5cm] \repeat unfold 25 { c' d' e' d' } \end{lilypond} + If a protrusion limit has been set with \texttt{max-protrusion=0.5cm} and the score exceeds that limit in spite of \texttt{indent=1cm} then the whole score will appropriately be narrowed: + \begin{lilypond}[indent=1cm,max-protrusion=0.5cm] \set Staff.instrumentName = "Violin I. and II." \repeat unfold 11 { c' d' e' d' } \end{lilypond} + + This doesn't really look good because the indentation of the second system wouldn't have been necessary since only the first system exceeds the protrusion limit. The solution to this situation is the option \texttt{autoindent} which handles the indentation \emph{automatically} and set the indent to a value that will make the \emph{first} system fit into the protrusion limit and leave the remaining systems unchanged: + \begin{lilypond}[autoindent=true,max-protrusion=0.5cm] \set Staff.instrumentName = "Violin I. and II." \repeat unfold 11 { c' d' e' d' } \end{lilypond} + + However, if the protrusion limit is not only exceeded by the \emph{first} system (which should be the typical case due to the instrument name) \texttt{lyluatex} will deal with the situation by narrowing the \emph{whole} score by the appropriate amount and adjusting the indent of the first system so all systems will just fit into the protrusion limit: + \begin{lilypond}[autoindent=true,max-protrusion=0.5cm] \set Staff.instrumentName = "Violin I. and II." \set Staff.shortInstrumentName = "Violin I/II" \repeat unfold 11 { c' d' e' d' } \end{lilypond} + There is one special case to be mentioned. As described above the indent is deactivated if the first system of a score is printed at a later position. However, if this score will exceed the left protrusion limit \texttt{autoindent} will be automatically activated to avoid having the \emph{whole} score narrowed: + \begin{lilypond}[indent=1cm,print-only={3,1,2},max-protrusion=0.5cm] \set Staff.instrumentName = "Violin" \repeat unfold 25 { c' d' e' d' } \end{lilypond} + \paragraph{Right protrusion} The dynamic handling of (automatic) indent also works correctly when there is protrusion handling to the right. The following score has the ties manually shaped to exceed the staff symbol by 10, and 7 staff spaces, and \texttt{max-protrusion=1cm} . + \begin{lilypond}[nofragment,max-protrusion=1cm,] { \set Staff.instrumentName = "Violin 1 & 2" @@ -2011,42 +2083,57 @@ shaped to exceed the staff symbol by 10, and 7 staff spaces, and c' } \end{lilypond} + + \paragraph{Performance considerations} The handling of indent suppression may require up to four compilations of the score, but these are handled automatically, and the resulting intermediate stages of the score are cached just like the scores actually used in the document. + The \texttt{autoindent} option is active by default but will be deactivated if \texttt{indent} is set explicitly. It has to be noted that this option will add more LilyPond compilations and therefore compilation time. But it will only apply and be executed if the score exceeds the protrusion limit, so it can only occur in circumstances where multiple LilyPond runs are expected anyway. + \let\postLilyPondExample\undefined + \addcontentsline{toc}{subsection}{Font Handling} \hypertarget{fonts}{} + \defaultfontfeatures{Ligatures=TeX,Numbers=OldStyle,Scale=MatchLowercase} \setmainfont{Linux Libertine O} \setsansfont[BoldFont={Linux Biolinum O Bold}]{Linux Biolinum O} \setmonofont{Inconsolata} + \section*{Font Handling} + To demonstrate the font handling features of \lyluatex\ we will repeatedly include the following score from an external file. It includes roman (lyrics, instrument name), sans (rehearsal mark), and mono (tempo) text, first using LilyPond's built-in default fonts. + \lilypondfile[verbatim]{fonts} + \bigskip The current document uses \option{fontspec} to set roman font to \emph{Linux Libertine O}, sans font to \emph{Linux Biolinum O}, and mono font to \emph{Inconsolata}. So if you compile this document yourself and don't have these fonts installed you will receive unexpected results. + \subsection*{Passing Document Fonts to Score} + With \option{pass-fonts} the currently active font families for roman, sans, and mono fonts are passed to LilyPond in order to achieve the most coherent appearance between text and music. + \bigskip + \lilypondfile[pass-fonts]{fonts} + \bigskip Note that LilyPond loads fonts differently than \LaTeX\ and can only make use of fonts installed as system fonts, fonts that are only installed through a \LaTeX\ @@ -2054,11 +2141,14 @@ distribution are not accessible to it. That means that if the document fonts are not installed system-wide (e.\,g. the default fonts) LilyPond will use rather ugly fallback fonts. This can't be demonstrated here but the section about explicitly setting font families will include an example. + The inherent problem of fallback fonts, especially with \LaTeX's default settings, is the reason \option{pass-fonts} is inactive by default. But the general recommendation is to set \option{pass-fonts} as package option if the text document uses fonts that are available to LilyPond. + \bigskip + \sffamily \option{current-font-as-main} will use the font that is \emph{currently} used for typesetting as LilyPond's main (roman) font. This can make sure that the score's main font (and roman is usually the font used most in @@ -2069,9 +2159,12 @@ is one of the two others. Additionally this \emph{may} introduce an inconsistency not between the score and the surrounding text but between different scores in a document. For all these reasons the option is by default set to \texttt{false}. + \bigskip \lilypondfile[pass-fonts,current-font-as-main]{fonts} + \subsection*{Setting Score Fonts Explicitly} + With \option{rmfamily}, \option{sffamily}, and \option{ttfamily} specific families can be set to arbitrary fonts, independently from the text document. For the following score \option{ttfamily=\{TeXGyre Adventor\}} is @@ -2079,24 +2172,31 @@ used.\footnote{Note that this font (which is included in TeXLive) has to be installed if you want to successfully compile this document.} Note that this implicitly sets \option{pass-fonts=true}, and \emph{Linux Libertine O} and \emph{Linux Biolinum O} are used from the text document. + \bigskip \lilypondfile[ttfamily={TeXGyre Adventor}]{fonts} + \highlight{NOTE:} when \option{rmfamily} is set explicitly \option{current-font-as-main} is forced to \texttt{false} to ensure that the roman font is actually used. The next score sets \option{rmfamily=\{TeXGyre Adventor\}} and \option{current-font-as-main}, and despite the current font still being \cmd{sffamily} \emph{Adventor} is used as the score's main font: + \bigskip \lilypondfile[current-font-as-main,rmfamily={TeXGyre Adventor}]{fonts} + \subsection*{LilyPond's Font Fallback} + If unavailable fonts are set in a LilyPond document they will \emph{silently} be replaced with fallback fonts that tend to cause ugly results. This will be shown by setting \option{rmfamily=FantasyFontOne}, \option{sffamily=FantasyFontTwo}, and \option{tfamily=FantasyFontThree}: + \bigskip \lilypondfile[rmfamily=FantasyFontOne,% sffamily=FantasyFontTwo,% ttfamily=FantasyFontThree]{fonts} + This can happen in several contexts: apart from compiling the document on a different computer where the used fonts are missing it is most likely to occur with the \option{pass-fonts} option, when the text document uses internal @@ -2104,6 +2204,7 @@ with the \option{pass-fonts} option, when the text document uses internal family is specified explicitly with an option and the other families are passed from the text document. + \defaultfontfeatures{Ligatures=TeX,Numbers=OldStyle,Scale=MatchLowercase} \setmainfont{Linux Libertine O} \setsansfont[BoldFont={Linux Biolinum O Bold}]{Linux Biolinum O} @@ -2111,18 +2212,29 @@ from the text document. \addcontentsline{toc}{subsection}{Wrapping Commands} \hypertarget{wrappingcommands}{} + \VerbatimFootnotes + \section*{Wrapping Commands} + \subsection*{Command within commands} + \cmd{lily} can be wrapped within another command as usual: + \begin{verbatim} \newcommand\mylily[2][1]{\lily[inline-staffsize=10, #1]{#2}} + This is \mylily[voffset=10pt]{a' b' c''} an example. \end{verbatim} + \newcommand\mylily[2][1]{\lily[inline-staffsize=10, #1]{#2}} + This is \mylily[voffset=10pt]{a' b' c''} an example.\par + \subsection*{Environment within environments} + \emph{It isn't possible to wrap \highlight{ly} environment within a command.}\par + It's possible to wrap \highlight{ly} within and environment, but there are several drawbacks\footnote{% Those drawbacks are: @@ -2140,8 +2252,10 @@ Those drawbacks are: \end{itemize} \end{itemize}% }. + To avoid those drawbacks, \lyluatex\ defines a special command, \verb`\lynewenvironment`, that behaves as you'd expect from \verb`\newenvironment`. + \begin{verbatim} \lynewenvironment{myly}{% This is \emph{my} lilypond environment. @@ -2149,19 +2263,23 @@ that behaves as you'd expect from \verb`\newenvironment`. }{% \end{ly} } + \begin{myly} a b c \end{myly} \end{verbatim} + \newenvironment{myly}{% This is \emph{my} lilypond environment. \begin{ly}% }{% \end{ly} } + \begin{myly} a b c \end{myly} + \begin{verbatim} \lynewenvironment{lyfigure}[2][]{% \edef\mycaption{#2} @@ -2174,11 +2292,13 @@ that behaves as you'd expect from \verb`\newenvironment`. \end{center} \end{figure} } + \begin{lyfigure}{This is a caption} a' b' c d' e' f \end{lyfigure} \end{verbatim} + \lynewenvironment{lyfigure}[2][]{% \edef\mycaption{#2} \begin{figure} @@ -2190,10 +2310,12 @@ d' e' f \end{center} \end{figure} } + \begin{lyfigure}{This is a caption} a' b' c d' e' f \end{lyfigure} + \begin{verbatim} \lynewenvironment{lyotherfigure}[1][]{% \edef\option{#1} @@ -2206,11 +2328,13 @@ d' e' f \endcenter \endfigure } + \begin{lyotherfigure} d' e' f a' b' c \end{lyotherfigure} \end{verbatim} + \lynewenvironment{lyotherfigure}[1][]{% \edef\option{#1} \figure @@ -2222,23 +2346,28 @@ a' b' c \endcenter \endfigure } + \begin{lyotherfigure} d' e' f a' b' c \end{lyotherfigure} + \begin{verbatim} \begin{lyotherfigure}[This time with a caption] d' e' f a' b' c \end{lyotherfigure} \end{verbatim} + \begin{lyotherfigure}[This time with a caption] d' e' f a' b' c \end{lyotherfigure} + \textbf{Important note:} \verb`\lynewenvironment` is intended to insert \LaTeX\ code before and after the scores; due to the special behavior of \verb`ly` environment, it isn't possible to insert \emph{LilyPond} code that way. So this won't work: + \begin{verbatim} \lynewenvironment{myly}{% \begin{ly} @@ -2247,26 +2376,33 @@ to insert \emph{LilyPond} code that way. So this won't work: \end{ly} } \end{verbatim} + To do such a thing, \lyluatex\ defines a command and four options: \begin{itemize} \item \verb`\lysavefrag` lets one save a LilyPond fragment to be re-used afterward; \item \verb`include_header`, \verb`include_footer`, \verb`include_before_body` and \verb`include_after_body` options let one insert such fragments at designed places within inserted score. \end{itemize} + So this works: + \begin{verbatim} \begin{lysavefrag}{head} a b c \end{lysavefrag} + \begin{lysavefrag}{foot} g a' b \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + begin{ly}[ include_before_body={head,mymark,head}, include_after_body=foot, @@ -2274,17 +2410,22 @@ begin{ly}[ d e f \end{ly} \end{verbatim} + It's also possible to use \verb`\lynewenvironment` to wrap such a command: + \begin{verbatim} \begin{lysavefrag}{head} a b c \end{lysavefrag} + \begin{lysavefrag}{foot} g a' b \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + \lynewenvironment{yourly}[1][]{% {\centering test \par} \begin{ly}[ @@ -2294,19 +2435,24 @@ g a' b }{ \end{ly} } + \begin{yourly} d e f \end{yourly} \end{verbatim} + \begin{lysavefrag}{head} a b c \end{lysavefrag} + \begin{lysavefrag}{foot} g a' b \end{lysavefrag} + \begin{lysavefrag}{mymark} \mark \default \end{lysavefrag} + \lynewenvironment{yourly}[1][]{% {\centering test \par} \begin{ly}[ @@ -2316,27 +2462,34 @@ g a' b }{ \end{ly} } + \begin{yourly} d e f \end{yourly} + \addcontentsline{toc}{subsection}{Wrapping Raw PDF Filenames} \hypertarget{insert-raw-pdf}{} + \section*{Wrapping Raw PDF Filenames} + With the \option{raw-pdf} option it is possible to create wrapping commands that circumvent \lyluatex's layout considerations by working with the raw PDF filename of the generated score. This is especially useful for developing packages or personal class and style files. For this scores generated with \option{raw-pdf} define a command \cmd{lyscore} that can be used in the wrapping commands or environments. + All examples in this document could also be realized using “default” \lyluatex\ without \option{raw-pdf}, but they are intended to show how this low-level access can be used to retrieve the information from the generated score in order to build custom versions of commands that don't have to adhere to \lyluatex's pre-built strategies of including the score in the document + The easiest way to use a “raw” score is to simply access \cmd{lyscore} in a command and pass it to an \cmd{includegraphics} macro: + \begin{verbatim} \newcommand\lilyinline[2][]{% \lily[raw-pdf,% @@ -2348,27 +2501,33 @@ command and pass it to an \cmd{includegraphics} macro: \includegraphics{\lyscore{}}% } \end{verbatim} + \newcommand\lilyinline[2][]{% \lily[raw-pdf,insert=bare-inline,inline-staffsize=8,hpadding=0.25ex,#1]{ \omit Stem #2}% \includegraphics{\lyscore{}}% } + This basically is a way to provide pre-configured commands. In this case \lilyinline{ c'8 d' c' d'} it is used to pre-configure an inline type, entered as \verb+\lilyinline{ c'8 d' c' d'}+. + + \bigskip \cmd{lyscore} takes one mandatory argument which can be empty -- as in the example above --, receive a number, one of the keywords \texttt{nsystems} and \texttt{hoffset}, or any of the score's options. If passed a number it will return the filename of the N-th system. With \texttt{nsystems} the number of systems in the generated score will be returned, while \texttt{hoffset} generates the code that shifts the score to the left to accommodate protrusion. + The following example takes an optional argument with options that are passed to \lyluatex, and one mandatory argument which expects the system to be used. It prints the given system centered in a figure and uses the file name as the caption and makes use of the score's \texttt{label}. Figure \ref{centered} shows the centering of a short fragment, figure \ref{fifth} the selection of the fifth system from a larger score. + \begin{verbatim} \newenvironment{centeredlilypondsystem}[2][]{% \def\usesystem{#2} @@ -2383,13 +2542,16 @@ system from a larger score. \end{center} \end{figure} } + \begin{centeredlilypondsystem}[label=centered]{1} c'1 d' e' \end{centeredlilypondsystem} + \begin{centeredlilypondsystem}[label=fifth]{5} \repeat unfold 8 { c'1 \break } \end{centeredlilypondsystem} \end{verbatim} + \newenvironment{centeredlilypondsystem}[2][]{% \def\usesystem{#2} \begin{figure} @@ -2403,17 +2565,22 @@ system from a larger score. \end{center} \end{figure} } + \begin{centeredlilypondsystem}[label=centered]{1} c'1 d' e' \end{centeredlilypondsystem} + \begin{centeredlilypondsystem}[label=fifth]{5} \repeat unfold 8 { c'1 \break } \end{centeredlilypondsystem} + + Finally there's an example showing how to iterate over the systems of a score using \cmd{foreach} from the \option{pgffor} package. It iterates over all the systems in the given score, prints them using the protrusion adjustment seen before, and if the system is the third it prints this information, otherwise just a line break: + \begin{verbatim} \newcommand\myforlily[2][]{% \lily[insert=systems,raw-pdf,#1]{#2}% @@ -2422,10 +2589,12 @@ just a line break: \ifthenelse{\equal{\n}{3}}{\par Third system\par}{\\} }% } + \myforlily[staffsize=24]{ \set Staff.instrumentName = "Vl. " \repeat unfold 4 { c'1 \break } } \end{verbatim} + \newcommand\myforlily[2][]{% \lily[insert=systems,raw-pdf,#1]{#2}% \foreach \n in {1,...,\lyscore{nsystems}}% @@ -2433,9 +2602,11 @@ just a line break: \ifthenelse{\equal{\n}{3}}{\par\bigskip Third system\par\bigskip}{\\} }% } + \myforlily[staffsize=24]{ \set Staff.instrumentName = "Vl. " \repeat unfold 4 { c'1 \break } } + \end{document} diff --git a/support/lyluatex/lyluatexbase.cls b/support/lyluatex/lyluatexbase.cls index 1e8b048dd8..fb72c667d6 100644 --- a/support/lyluatex/lyluatexbase.cls +++ b/support/lyluatex/lyluatexbase.cls @@ -1,11 +1,11 @@ %Lyluatex LaTeX class. % -% Copyright (C) 2015-2019 jperon and others (see CONTRIBUTORS.md) +% Copyright (C) 2015-2022 jperon and others (see CONTRIBUTORS.md) % License: MIT % This file is part of lyluatex. \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{lyluatexbase}[2019/05/27 v1.0f] %%LYLUATEX_DATE LYLUATEX_VERSION +\ProvidesClass{lyluatexbase}[2022/10/30 v1.1] %%LYLUATEX_DATE LYLUATEX_VERSION \LoadClass[DIV=11]{scrartcl} \RequirePackage{lyluatex} @@ -16,7 +16,7 @@ \RequirePackage{pgffor} \RequirePackage{fancyvrb} \RequirePackage[colorlinks=true]{hyperref} -\lysetoption{includepaths}{./, ly/} +\setluaoption{ly}{includepaths}{./, ly/} % Common formatting elements for manual and examples diff --git a/support/lyluatex/lyluatexmanual.cls b/support/lyluatex/lyluatexmanual.cls index 8e1a85d290..16399004c2 100644 --- a/support/lyluatex/lyluatexmanual.cls +++ b/support/lyluatex/lyluatexmanual.cls @@ -1,11 +1,11 @@ %Lyluatex LaTeX class for the manual. % -% Copyright (C) 2015-2019 jperon and others (see CONTRIBUTORS.md) +% Copyright (C) 2015-2022 jperon and others (see CONTRIBUTORS.md) % License: MIT % This file is part of lyluatex. \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{lyluatexmanual}[2019/05/27 v1.0f] %%LYLUATEX_DATE LYLUATEX_VERSION +\ProvidesClass{lyluatexmanual}[2022/10/30 v1.1] %%LYLUATEX_DATE LYLUATEX_VERSION \LoadClass{lyluatexbase} @@ -35,7 +35,7 @@ local PC = string.char(37) local date_fmt = PC..'Y-'..PC..'m-'..PC..'d' local p = io.popen('git log -n1 --date=short --format='..PC..'"ad"', 'r') - tex.sprint(p and p:read('*a') or os.date(date_fmt)) + tex.sprint(p and p:read('*a'):sub(1,-2) or os.date(date_fmt)) if p then p:close() end } -} \ No newline at end of file +} diff --git a/systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl b/systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl index c250d49cf4..fac7466600 100644 --- a/systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl +++ b/systems/texlive/tlnet/tlpkg/installer/ctan-mirrors.pl @@ -48,12 +48,8 @@ $mirrors = { 'https://cran.asia/tex/' => 1, 'https://ftp.kaist.ac.kr/pub/tex-archive/' => 1, 'https://lab.uklee.pe.kr/tex-archive/' => 1, - 'https://mirror.kakao.com/CTAN/' => 1, 'https://mirror.navercorp.com/CTAN/' => 1, }, - 'Philippines' => { - 'http://mirror.rise.ph/ctan/' => 1, - }, 'Singapore' => { 'https://download.nus.edu.sg/mirror/ctan/' => 1, }, @@ -142,7 +138,6 @@ $mirrors = { 'https://sunsite.icm.edu.pl/pub/CTAN/' => 1, }, 'Portugal' => { - 'https://ftp.eq.uc.pt/software/TeX/' => 1, 'https://mirrors.up.pt/pub/CTAN/' => 1, }, 'Romania' => { diff --git a/systems/texlive/tlnet/tlpkg/texlive.tlpdb b/systems/texlive/tlnet/tlpkg/texlive.tlpdb index f24c2e2229..f0ea8fee1e 100644 --- a/systems/texlive/tlnet/tlpkg/texlive.tlpdb +++ b/systems/texlive/tlnet/tlpkg/texlive.tlpdb @@ -26,11 +26,11 @@ depend container_split_src_files/1 depend frozen/0 depend minrelease/2016 depend release/2022 -depend revision/64841 +depend revision/64859 name 00texlive.image category TLCore -revision 64833 +revision 64853 shortdesc TeX Live files only in the source repository longdesc The files here are not copied by the installer and containers longdesc are not built for them; they exist only in the source @@ -2116,6 +2116,7 @@ runfiles size=12950 tlpkg/tlpsrc/hep-math-font.tlpsrc tlpkg/tlpsrc/hep-math.tlpsrc tlpkg/tlpsrc/hep-paper.tlpsrc + tlpkg/tlpsrc/hep-reference.tlpsrc tlpkg/tlpsrc/hep-text.tlpsrc tlpkg/tlpsrc/hep-title.tlpsrc tlpkg/tlpsrc/hep.tlpsrc @@ -4661,7 +4662,7 @@ depend setting_available_architectures:aarch64-linux amd64-freebsd amd64-netbsd name 00texlive.installer category TLCore -revision 64830 +revision 64843 shortdesc TeX Live standalone installer package longdesc This package defines the files to go into the installer longdesc archives (install-tl-unx.tar.gz, install-tl.zip) built by the @@ -8281,7 +8282,7 @@ catalogue-version 1.9.1-2 name accanthis category Package -revision 32089 +revision 64844 shortdesc Accanthis fonts, with LaTeX support relocated 1 longdesc Accanthis No. 3 is designed by Hirwin Harendal and is suitable @@ -8290,9 +8291,9 @@ longdesc old style, Sabon, and Bembo. The support files are suitable for longdesc use with all LaTeX engines. execute addMap accanthis.map containersize 368064 -containerchecksum 9edbbdd97ea30709f0e0e1959bac7806c188d610e414f037a4115747f57ce7ad68be67b75506f9ce186c951a2c46c3bcd5b0697bb72d81fc48465906cd245be0 -doccontainersize 300384 -doccontainerchecksum efa2cbf4c11b28dc0a907b62d8818489ca48c458419e37571633adb8403f914c01d28431684705363e56cc100adf7cff6539f19fae9e4b23e6cf3dc210109810 +containerchecksum 5727125c85e06501f009267bab8c1eff674a76db618c6155fd9c6b41bb2407a3a201a008c7f5aa6d73ecf100a3fc917961d20f547c2f6040fe72760a4dcd9a44 +doccontainersize 300388 +doccontainerchecksum 6789c3c330d1e6a0d20364e4e98ef72fd1c6294655f704366b0e6c1fd081d1aea312dc9e6767fb3e076b3cd91ea5a67606e8bf62f7f92af097ba766c99ab0cff docfiles size=84 RELOC/doc/fonts/accanthis/Accanthis-Cat.pdf details="Arkandis catalogue page" language="fr" RELOC/doc/fonts/accanthis/COPYING @@ -8385,8 +8386,8 @@ runfiles size=204 RELOC/tex/latex/accanthis/accanthis.sty catalogue-contact-home http://arkandis.tuxfamily.org/adffonts.html catalogue-ctan /fonts/accanthis -catalogue-license gpl2 -catalogue-topics font font-serif font-type1 font-otf +catalogue-license gpl2+ lppl +catalogue-topics font font-body font-proportional font-serif font-type1 font-otf font-supp font-t1enc name accents category Package @@ -25062,7 +25063,7 @@ catalogue-version 0.8 name association-matrix category Package -revision 61719 +revision 64845 shortdesc LaTeX support for creating association matrices relocated 1 longdesc This package allows the creation of association matrices in an @@ -25074,11 +25075,11 @@ longdesc associated. Then, the \amxgenerate command generates a table longdesc that shows in the cells with a blip (*) where the association longdesc was added. The package depends on etoolbox, forloop, ifthen, longdesc textcomp, and xparse. -containersize 3604 -containerchecksum da84a9048985e8987d8e528533ac3fa0b307d996e159843ce8a3b3754f697191b30264b21b58e0d3dd9ee6c1fe478d84e92996ed3186c10c6d944a33f21f7db0 -doccontainersize 251112 -doccontainerchecksum 19eec11c03b3ab612a14ed2e90e850b8d2961aac85c2400d988a3c478b847dc45c61d03654b5b567978fd69d9fd6a2bfd153bc9278f38c121476e9cd098e38cc -docfiles size=71 +containersize 4188 +containerchecksum 6b87d01d5559669f6e2d63fc14427d950eba9d790070625cc6acaaf6e308282b7434bce90da78a41858b068121b75a1e1c0ec4453d287aaed94c9e6308a1b5ce +doccontainersize 268584 +doccontainerchecksum e56de37acf6d8c2b53aff0aa78999dd400b18b3bb44ea40f21a7638e463405ce4f48d2041236897f7a281099c1c5d879ffcbda9d6b08d2b0d5fb83193803d157 +docfiles size=76 RELOC/doc/latex/association-matrix/DEPENDS.txt RELOC/doc/latex/association-matrix/LICENCE RELOC/doc/latex/association-matrix/README.md details="Readme" @@ -25091,7 +25092,7 @@ catalogue-contact-repository https://github.com/whisperity/association-matrix catalogue-ctan /macros/latex/contrib/association-matrix catalogue-license lppl1.3c catalogue-topics table matrix expl3 -catalogue-version 1.0 +catalogue-version 1.1 name asternote category Package @@ -71306,7 +71307,7 @@ containerchecksum 7bacc398e20fae5da669102b699ad7dc2513abaa50b9b7969a0acf8ebe8ac5 name collection-mathscience category Collection -revision 64763 +revision 64853 shortdesc Mathematics, natural sciences, computer science packages relocated 1 depend 12many @@ -71416,6 +71417,7 @@ depend grundgesetze depend gu depend helmholtz-ellis-ji-notation depend hep +depend hep-reference depend hepnames depend hepparticles depend hepthesis @@ -71552,8 +71554,8 @@ depend youngtab depend yquant depend ytableau depend zx-calculus -containersize 1632 -containerchecksum 5f899eb88979bbcac7c780def9f108e1d6b7d6c88f7aa393ac8550bf20453db29b5ec41e2af90a557333018d778c68b38800669f2b1383f028d788c8794719e2 +containersize 1636 +containerchecksum 157a68c5e2e4fa83be6b6ad10bfaf527e55951b4c599897d48f9abdfe13a256e3cf04148f5ae8ae3ad2feb1c321a7d5f37d00edc9ec5a0307ea6055fbca54f45 name collection-metapost category Collection @@ -91230,7 +91232,7 @@ binfiles arch=x86_64-solaris size=1 name debate category Package -revision 64602 +revision 64846 shortdesc Debates between reviewers relocated 1 longdesc This package helps to organize debates between multiple @@ -91241,17 +91243,17 @@ depend pdfcol depend tcolorbox depend xcolor depend xkeyval -containersize 1680 -containerchecksum c519e285f9828fdb12ec3526eacca487e6b6b53e1ea9c1e9f557447d5557e4b1594543d2aefd8ca113f691c8a6c15bfb214877bad221003b0100e3e6c1f64601 -doccontainersize 326644 -doccontainerchecksum 215a369d23c599d9fe3aa2a7b2b75c107a1166b3196c5f04a131fd50817f4bf75496ad2978809bc05d24821f8a8548efb6258b2cb0b3e8e4d206a1a46fb75d3a -docfiles size=84 +containersize 1688 +containerchecksum 88f9ff3f473dfbd84509adfe4491d15b7c20229361afde9cbce382be0441378cd6bb7d306c9b0a424dc065f34ab2d86eca8a0334d00fd3a5bae513776c418815 +doccontainersize 285712 +doccontainerchecksum ba5e90ecc8c1733cdb78233099cdc95e09d02786df11606b3f823f2b1b60934cd2881c873ad7afa192ee1b0ff5ad91121896cb30e7405ee3ae9bc960d26e7f9c +docfiles size=74 RELOC/doc/latex/debate/DEPENDS.txt RELOC/doc/latex/debate/LICENSE.txt RELOC/doc/latex/debate/README.md details="Readme" RELOC/doc/latex/debate/debate.pdf details="Package documentation" -srccontainersize 3044 -srccontainerchecksum adbeea4f89eccabeabf13fcdcfbbc9edb3960945b099b5c3773c940bb0c8b6cd4cf846fc7910be434c3342cf938a8d474bf5f941d388938117e503a99b08a4eb +srccontainersize 3084 +srccontainerchecksum b9c0b94eea82d7b684aa358788a5ee3cb9709738137827b7a4f70ddd0d02ad92b6feecf03d0de7dd08c1ab233f17db3c973cfafef98134be33a41d6a8d7c4da6 srcfiles size=3 RELOC/source/latex/debate/debate.dtx RELOC/source/latex/debate/debate.ins @@ -91263,7 +91265,7 @@ catalogue-contact-repository https://github.com/yegor256/debate catalogue-ctan /macros/latex/contrib/debate catalogue-license mit catalogue-topics notes -catalogue-version 0.2.0 +catalogue-version 0.2.1 name decimal category Package @@ -109193,7 +109195,7 @@ catalogue-version 1.2 name eolang category Package -revision 64834 +revision 64847 shortdesc Formulas and graphs for the EO programming language relocated 1 longdesc This LaTeX package helps you write [?] -calculus formulas and @@ -109205,20 +109207,20 @@ depend iexec depend pgf depend pgfopts depend stmaryrd -containersize 3900 -containerchecksum 8fc92fa7f902ebd44768468afec85003e48512842ed8b6acb79c10763a8a10980f5f3574ddc4934ea9d2209b3b8bde353a3fd09758d7d9b03c6fbaf8b0d7f959 -doccontainersize 875488 -doccontainerchecksum 970b37bf3f0be5af3eae1a21e384375fde2584b6bdd84f11948319637b4697ef68a3db14066f818848e8ad524cb19196d5b98b2c5cbc38cbce7b456e172aa272 -docfiles size=250 +containersize 3996 +containerchecksum ea1bb9e3e6cae3186068bdb3fd7fe7844c71fbc875491f1be104eda86d0bb52810a258c32be57a9116aa1952bb7f4469539c33509a6c94ac3b35f7ab8fce3ec3 +doccontainersize 880404 +doccontainerchecksum d952dcf950f02176ba1727fa9726cf6c2577507541be8fd200adb327a41b1e72f59a61b0f2f4482839cdad67fc0b450110293941e2d11136c61552fa8770b839 +docfiles size=253 RELOC/doc/latex/eolang/DEPENDS.txt RELOC/doc/latex/eolang/LICENSE.txt RELOC/doc/latex/eolang/README.md details="Readme" RELOC/doc/latex/eolang/cactus.pdf RELOC/doc/latex/eolang/eolang.bib RELOC/doc/latex/eolang/eolang.pdf details="Package documentation" -srccontainersize 8008 -srccontainerchecksum e41ba46a23b88e259b44295928c0d2c45a60b6a4dda1dbbc86f11d47059a8cec49a310f0c05e083a00ec706d707b4e7a508703c92386b09d84b33e240f1cdad3 -srcfiles size=7 +srccontainersize 8372 +srccontainerchecksum 51c7a1705621e71b63bb19075ef598a0ac2655eb0303ba8730c9d57228d2026d9f08c3c7979011a443805489f68ac7b292cb6c67b242d98658e680eb38f5b0fb +srcfiles size=8 RELOC/source/latex/eolang/eolang.dtx RELOC/source/latex/eolang/eolang.ins runfiles size=3 @@ -109227,7 +109229,7 @@ catalogue-contact-repository https://github.com/objectionary/eolang.sty catalogue-ctan /macros/latex/contrib/eolang catalogue-license mit catalogue-topics diagram program-doc -catalogue-version 0.1.0 +catalogue-version 0.2.0 name epigrafica category Package @@ -133442,7 +133444,7 @@ catalogue-version 1.1 name gillius category Package -revision 32068 +revision 64859 shortdesc Gillius fonts with LaTeX support relocated 1 longdesc This package provides LaTeX, pdfLaTeX, XeLaTeX and LuaLaTeX @@ -133451,17 +133453,17 @@ longdesc serif fonts and condensed versions of them, designed by Hirwen longdesc Harendal. According to the designer, the fonts were inspired by longdesc Gill Sans. execute addMap gillius.map -containersize 941896 -containerchecksum 9620e63fa3a9a981bdb20cbd6d8002179c722e844df0a18566593acef864f134a894a7e1920fbc4494467b1301af0bbf9ee80fb10bcc192762e5b2505fa8becd +containersize 941916 +containerchecksum 97008aef459313dbed155ea3c5a10b1a0a6e2fd293ff9b76be15c2b41680671276b5426fa74709fc7c28d5757e9a1a6108025a6d141c64e9e89211c578a9611d doccontainersize 216008 -doccontainerchecksum df8fdeb2055b4d3383eb6ebab3dc4fb92774a96d7b31e7bdd7a238e215619710a8c0ec3fe9593213535933fd76c38947ed295df1a628aee7a7d7b21078f5ffb4 +doccontainerchecksum 16b18d9f23ce0b0d0f8e5af9985d66712bf7d3635139681b32fb8c7e695b25eda517f9d710395ca374c55d32b88748fe8f99497b89cf0967877dc4155e4c4747 docfiles size=66 RELOC/doc/fonts/gillius/COPYING RELOC/doc/fonts/gillius/Gillius-cat.pdf RELOC/doc/fonts/gillius/README details="Readme" RELOC/doc/fonts/gillius/gillius-samples.pdf details="Gillius font samples" RELOC/doc/fonts/gillius/gillius-samples.tex - RELOC/doc/fonts/gillius/gillius2-samples.pdf details="Gillius font samples" + RELOC/doc/fonts/gillius/gillius2-samples.pdf details="Gillius No. 2 font samples" RELOC/doc/fonts/gillius/gillius2-samples.tex runfiles size=628 RELOC/fonts/enc/dvips/gillius/gls_4bsedw.enc @@ -133781,8 +133783,8 @@ runfiles size=628 RELOC/tex/latex/gillius/gillius2.sty catalogue-contact-home http://arkandis.tuxfamily.org/adffonts.html catalogue-ctan /fonts/gillius -catalogue-license gpl2 -catalogue-topics font font-sans font-type1 font-otf +catalogue-license gpl2+ lppl +catalogue-topics font font-body font-proportional font-sans font-type1 font-otf font-supp font-t1enc name gincltex category Package @@ -141012,6 +141014,42 @@ catalogue-license lppl1.3c catalogue-topics physics catalogue-version 2.0 +name hep-reference +category Package +revision 64853 +shortdesc Adjustments for publications in High Energy Physics +relocated 1 +longdesc This package makes some changes to the reference, citation and +longdesc footnote macros to improve the default behavior of LaTeX for +longdesc High Energy Physics publications. +containersize 1920 +containerchecksum 1a422d571817be0264385beae73effb4ac674f2e05396289373c0d0792f591c39ebc2bac21d9e6def0e18dc389b7af9f604b6aebba133053894b2874a8dc113d +doccontainersize 461932 +doccontainerchecksum 8952bc87e4a3cb1780ce51ea402b3dbe924b5e6adc9d05c9c0b75bb2e391c8fb4b07bab0f3419dc9f21bd4e9527eca5b56f6c10ef5a6e41d6c964e15cf9a5a0c +docfiles size=162 + RELOC/doc/latex/hep-reference/README-hep-reference.md + RELOC/doc/latex/hep-reference/README.md details="Readme" + RELOC/doc/latex/hep-reference/bibliography.bib + RELOC/doc/latex/hep-reference/hep-reference-documentation.pdf details="Package documentation" + RELOC/doc/latex/hep-reference/hep-reference-documentation.tex + RELOC/doc/latex/hep-reference/hep-reference-implementation.pdf + RELOC/doc/latex/hep-reference/hep-reference-test.tex + RELOC/doc/latex/hep-reference/license.md +srccontainersize 4468 +srccontainerchecksum 3a76caf01215ec123f930e0812674e67753727d3ef2adfcba12f0df9a0291739ec9493aa1b0536f749e976463b8c8ee90add1682109d44794c79e83967564b44 +srcfiles size=4 + RELOC/source/latex/hep-reference/hep-reference-implementation.dtx + RELOC/source/latex/hep-reference/hep-reference.ins +runfiles size=1 + RELOC/tex/latex/hep-reference/hep-reference.sty +catalogue-also hep-paper +catalogue-contact-bugs https://github.com/janhajer/hep-paper/issues +catalogue-contact-repository https://github.com/janhajer/hep-paper +catalogue-ctan /macros/latex/contrib/hep-reference +catalogue-license lppl1.3c +catalogue-topics ref-latex +catalogue-version 1.1 + name hep-text category Package revision 61172 @@ -143768,7 +143806,7 @@ catalogue-version 1.1.1 name huawei category Package -revision 64718 +revision 64848 shortdesc Template for Huawei documents relocated 1 longdesc This unofficial package provides a class for creating documents @@ -143800,27 +143838,28 @@ depend tools depend ulem depend wrapfig depend xcolor -containersize 6412 -containerchecksum 132f4118cd8cf6fcc7e81e825615195949601dff32d7643860a8ae9a925c8d36a994041813c8733fe40c0dfe1e8b4b09abcd42985c3f13ca3e4f3470bdcba12f -doccontainersize 409768 -doccontainerchecksum afb0b4d8b503659240f649766fb420b13e2579f3c2d003d90b654b9bd99135fe04c95550100b0478b022f8c10e698702f148f8db8e73bee59b980f5a4c194d1c -docfiles size=104 +containersize 260132 +containerchecksum 4df31d09423aabba2d16efcaa129d4560b5d496faf8a38f1884416c257671e1d78b5318a5890b10d696d4132e5ad3712743a85a9e3a4b800288e0b307c4049c3 +doccontainersize 777364 +doccontainerchecksum c5f3a61e0e6d2b6e6aba2c26456130f58ac2270bea56bffafc710d95bb315a439f34de259c5e1386435492c3dbb2cee5788956beb850ec43514b9a5ce76be923 +docfiles size=200 RELOC/doc/latex/huawei/DEPENDS.txt RELOC/doc/latex/huawei/LICENSE.txt RELOC/doc/latex/huawei/README.md details="Readme" RELOC/doc/latex/huawei/huawei.pdf details="Package documentation" -srccontainersize 9596 -srccontainerchecksum 9e868b2a7cc02cc0995ef9a4d8612fdf3b62c003d147dadc694a9a2361d63014455383d5a6541c156fe07a1da6fdcc5750b3fd37510e86cd468c0f9db31d85be +srccontainersize 9860 +srccontainerchecksum 7b2a52afbed006f3f369c7b2131ab4d1c6f2475b31c572298e90e03c005e7ea8ea062c5cb79c0fe383054621f103b7b81a0c68e56c8cd42b60581a287773da31 srcfiles size=9 RELOC/source/latex/huawei/huawei.dtx RELOC/source/latex/huawei/huawei.ins -runfiles size=5 +runfiles size=67 + RELOC/tex/latex/huawei/huawei-cover-picture.pdf RELOC/tex/latex/huawei/huawei.cls catalogue-contact-home https://github.com/yegor256/huawei.cls catalogue-ctan /macros/latex/contrib/huawei catalogue-license mit catalogue-topics class misc-paper -catalogue-version 0.14.2 +catalogue-version 0.14.3 name huaz category Package @@ -147128,7 +147167,7 @@ catalogue-version 1.0.0 name iexec category Package -revision 64810 +revision 64849 shortdesc Execute shell commands and input their output relocated 1 longdesc With the help of the \iexec command, you can execute a shell @@ -147137,17 +147176,17 @@ longdesc package also lets you use any special symbols inside your longdesc command. depend tools depend xkeyval -containersize 2412 -containerchecksum 6d23bd5c3afd9bf791bc082684a412ae934ec919be49432c4c81f916eaaa349aef4e738ca7ff28d3c3c945934809393ffd831930fc1f02cf5b881207fb1adf72 -doccontainersize 325748 -doccontainerchecksum d29d8133bab0d052d9a8d2502fbabe2e72962fc9fa6f2b0ada83b1daf3d9af9a4117da4b1338d7903649dead98c528c0cd1c65c2d8a26dcabac5bb92c1f5a688 -docfiles size=84 +containersize 2416 +containerchecksum 3344c09f44e7797d899e9d84323fad0975d91a8dc88e8b5a05a1c4d457af2007796a81ecb27996b40d4232818385ff6d576067eca5b9b30783c1cd875135b39f +doccontainersize 325444 +doccontainerchecksum 4efe74c2a6f5933615c438ee129b9e580b997e51546c27dfba0301c993152a0b1cd095c8d9ccc509756d0ba8ad28e134d8296fe0142aed5f536fe332567282ec +docfiles size=83 RELOC/doc/latex/iexec/DEPENDS.txt RELOC/doc/latex/iexec/LICENSE.txt RELOC/doc/latex/iexec/README.md details="Readme" RELOC/doc/latex/iexec/iexec.pdf details="Package documentation" -srccontainersize 5548 -srccontainerchecksum 335c636c0cb5dee47b1b528ba583cebb91202c254c78bce694574d07ec4cb9726777b2cf0fc0ecf348b2cbd47b70e1dfab6532772f8c6e1322cd7a13af95b1d6 +srccontainersize 5612 +srccontainerchecksum e891165b9bf9ea9fa0820e4cfd5fd5415c4916046db6c058de237fb9e5edcbcaeec102224f16f461ab903911ae2777b06513d169d422c71a4eadb481edd06070 srcfiles size=5 RELOC/source/latex/iexec/iexec.dtx RELOC/source/latex/iexec/iexec.ins @@ -147157,7 +147196,7 @@ catalogue-contact-repository https://github.com/yegor256/iexec catalogue-ctan /macros/latex/contrib/iexec catalogue-license mit catalogue-topics sys-supp exec-foreign -catalogue-version 0.11.2 +catalogue-version 0.11.3 name ifallfalse category Package @@ -159098,20 +159137,21 @@ catalogue-version 1.30 name jeuxcartes category Package -revision 64827 +revision 64850 shortdesc Macros to insert playing cards relocated 1 longdesc This package provides macros to insert playing cards, single, -longdesc or hand, or random-hand, Poker or French Tarot, from png files. -containersize 5328884 -containerchecksum 7c4d94f50dda82aa950f6c66e0c0418d05f052b45f2fe34556c611113df1b8d5649c022937a1ef8ca2454c9c2fb1e9cb56ac8a2fb18eeffba48fe466f30d7748 -doccontainersize 5509864 -doccontainerchecksum 389d90b94a8ca7a9dbb322f9fc2d492ddebe101e25f3db86e02b2263ff11bc8de15a9ce03c505a53766952b58eb395f329886a0200f3b160803b8556f1d91448 -docfiles size=1391 +longdesc or hand, or random-hand, Poker or French Tarot or Uno, from png +longdesc files. +containersize 5642836 +containerchecksum d05a57bad54f62af0ff0837c591cde9fb6b4b36920e6a1673ee7ec79880d87e19719118a89a3fa05ccfef61ee1c966abf06d0b9ec02875de24b4c268946ef239 +doccontainersize 6404764 +doccontainerchecksum 773a5c7bdef5e2f7328e1bc5c18eee2378783ebfdd8c1df95eea6cac4b1ae94a61cc46635c89ff3521de2079753b696f37bb08b87c1183c9ffa3de43c1b1f2e0 +docfiles size=1636 RELOC/doc/latex/jeuxcartes/JeuxCartes-doc.pdf details="Package documentation" language="fr" RELOC/doc/latex/jeuxcartes/JeuxCartes-doc.tex RELOC/doc/latex/jeuxcartes/README.md details="Readme" -runfiles size=1425 +runfiles size=1538 RELOC/tex/latex/jeuxcartes/CaJ-Poker-10C.png RELOC/tex/latex/jeuxcartes/CaJ-Poker-10K.png RELOC/tex/latex/jeuxcartes/CaJ-Poker-10P.png @@ -159262,11 +159302,68 @@ runfiles size=1425 RELOC/tex/latex/jeuxcartes/CaJ-Tarot-VK.png RELOC/tex/latex/jeuxcartes/CaJ-Tarot-VP.png RELOC/tex/latex/jeuxcartes/CaJ-Tarot-VT.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-0B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-0J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-0R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-0V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-1B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-1J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-1R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-1V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-2B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-2J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-2R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-2V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-3B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-3J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-3R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-3V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-4B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-4J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-4R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-4V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-5B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-5J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-5R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-5V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-6B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-6J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-6R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-6V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-7B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-7J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-7R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-7V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-8B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-8J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-8R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-8V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-9B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-9J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-9R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-9V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-CSB.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-CSJ.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-CSR.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-CSV.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-Dos.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-P2B.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-P2J.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-P2R.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-P2V.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-P4.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-PTJ.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-PTR.png + RELOC/tex/latex/jeuxcartes/CaJ-Uno-PTV.png + RELOC/tex/latex/jeuxcartes/Caj-Uno-Coul.png + RELOC/tex/latex/jeuxcartes/Caj-Uno-PTB.png RELOC/tex/latex/jeuxcartes/JeuxCartes.sty +catalogue-contact-bugs https://github.com/cpierquet/JeuxCartes/issues +catalogue-contact-repository https://github.com/cpierquet/JeuxCartes catalogue-ctan /macros/latex/contrib/jeuxcartes catalogue-license lppl1.3c lgpl2.1 pd catalogue-topics games pgf-tikz -catalogue-version 0.1.2 +catalogue-version 0.1.3 name jfmutil category Package @@ -187101,23 +187198,27 @@ catalogue-version 4.3 name linguisticspro category Package -revision 54512 +revision 64858 shortdesc LinguisticsPro fonts with LaTeX support relocated 1 longdesc The package provides LaTeX, pdfLaTeX, XeLaTeX and LuaLaTeX longdesc support for the LinguisticsPro family of fonts. This family is longdesc derived from the Utopia Nova font family, by Andreas Nolda. execute addMap LinguisticsPro.map -containersize 1395864 -containerchecksum 62085ea970d1cebc752cc5dab4b84487bd99e0e99fd48a2effa44fe9ae0bb86aa91966fd81639aea7d4364d3c3d97046affcf2693d8b4be8fa016e91014604c5 -doccontainersize 42252 -doccontainerchecksum 4ece804238885fb37505222218c92c923804d032e5e150de3cfadc62f0eec73e8acc47600ddc4d5af0f7bacf9f54254b6ead43a3f4a084aeb40dfe95b53d2965 -docfiles size=14 +containersize 1377940 +containerchecksum 6bf94e8910ae03314a3ff55157e52586b5f2550c2aaca1a8989b1f02400c87363c74e00658ee953c13a44dd69cb253bda6128e66a96b865e6169310165a7f9e4 +doccontainersize 46052 +doccontainerchecksum 8f0c8937cacdec2e2ea4999dd1bb45af96a99a3707ef22b54a2bf1e0c745d663550ff0b68d80cf895e8bdfa1f279873c4725c7851af547f06155589d8e5bfde5 +docfiles size=21 + RELOC/doc/fonts/linguisticspro/COPYING.txt + RELOC/doc/fonts/linguisticspro/ChangeLog.txt + RELOC/doc/fonts/linguisticspro/LICENSE-utopia.txt RELOC/doc/fonts/linguisticspro/README details="Readme" + RELOC/doc/fonts/linguisticspro/README.txt RELOC/doc/fonts/linguisticspro/SILOpenFontLicense.txt RELOC/doc/fonts/linguisticspro/linguisticspro-samples.pdf details="Package documentation" RELOC/doc/fonts/linguisticspro/linguisticspro-samples.tex -runfiles size=697 +runfiles size=696 RELOC/fonts/enc/dvips/linguisticspro/lnpr_2dchsz.enc RELOC/fonts/enc/dvips/linguisticspro/lnpr_2io6ub.enc RELOC/fonts/enc/dvips/linguisticspro/lnpr_2mzpfv.enc @@ -241573,33 +241674,34 @@ binfiles arch=x86_64-solaris size=1 name pdflscape category Package -revision 53047 +revision 64851 shortdesc Make landscape pages display as landscape relocated 1 longdesc The package adds PDF support to the landscape environment of longdesc package lscape, by setting the PDF /Rotate page attribute. longdesc Pages with this attribute will be displayed in landscape longdesc orientation by conforming PDF viewers. -containersize 2252 -containerchecksum c343f0527f21421f26396a6210f7932786a222a437b43d6b2bf1c53339633a0aa8337843222d92048a6a5a41f0952aa2fde6e2bfb2e181cf811383a23ffadadb -doccontainersize 298264 -doccontainerchecksum 5fccb7dc5607f1196d6df6a1a68d010c0b9eea10854cdf2e133f31dc4095f101efc05abcf9e980a3e05375ba29ce319dc13385790c2261778fde54d3b94d1251 -docfiles size=75 - RELOC/doc/latex/pdflscape/README.md +containersize 2612 +containerchecksum 13c581f774e61de70e97b40c54a59054b9ab0a9fd6e1b71d94fc5d0e072aa96661d8b72bc99c083b322df974f75b2f415a6fcd8bc23f95d2d999a03ffc0a3188 +doccontainersize 314616 +doccontainerchecksum c59c598fa494e5a57d2ba058dd6d096edc96aa958bec7ea1240195022b670f0cfc45d15eea0d0b68b499975811505a6fe9a209c7630c74c861fc42ce3904284d +docfiles size=80 + RELOC/doc/latex/pdflscape/README.md details="Readme" RELOC/doc/latex/pdflscape/pdflscape.pdf details="Package documentation" -srccontainersize 6000 -srccontainerchecksum 08cc0550cb76eff49ab4cc9f357f22a7c8086b2802eb191237bbf79acce2b134a2bf3ea28a8324d0140ac785afb8a928a8f7b8cc7e58bdd7e9d8b1d3a66ee7e5 +srccontainersize 6508 +srccontainerchecksum f844e74588ae5982f1122d9826caa8a93c229d2169813a074537053e0a8387c3917b110ec1653fdddb31513124b4f6974a2e3ba4e96f714a57a03155646bf115 srcfiles size=6 RELOC/source/latex/pdflscape/pdflscape.dtx -runfiles size=2 +runfiles size=3 + RELOC/tex/latex/pdflscape/pdflscape-nometadata.sty RELOC/tex/latex/pdflscape/pdflscape.sty catalogue-also lscape catalogue-contact-bugs https://github.com/ho-tex/pdflscape/issues catalogue-contact-repository https://github.com/ho-tex/pdflscape catalogue-ctan /macros/latex/contrib/pdflscape -catalogue-license lppl1.3 +catalogue-license lppl1.3c catalogue-topics landscape layout -catalogue-version 0.12 +catalogue-version 0.13 name pdfmanagement-testphase category Package @@ -249248,7 +249350,7 @@ catalogue-topics drama-script name playfair category Package -revision 56005 +revision 64857 shortdesc Playfair Display fonts with LaTeX support relocated 1 longdesc This package provides the PlayFairDisplay family of fonts, @@ -249262,10 +249364,10 @@ longdesc heavier than the lowercase characters. This helps achieve a longdesc more even typographical colour when typesetting proper nouns longdesc and initialisms. execute addMap PlayfairDisplay.map -containersize 1679544 -containerchecksum bd9c88074757e0b34fc569e3f383c6b8045216ffe5da4ec897d0c28365063d7a66511ae190017c24dbea92782be05735f62a0684909ca76731a30f6d9855fe5b -doccontainersize 251112 -doccontainerchecksum 03dfa23f74a3f1f23b4bd4d28ff6580e248074e07f2fc515db3fd917bd10f998886e3ef987e934b8fee7be5467b9f8d9810e9ccb6844af9bf67b8726ddff9773 +containersize 1679528 +containerchecksum 2c75ccda034c607fa67993922e498347cf8a708c31360ac63d8304ebcf538e2012529864c6c3102a63b0320db68101fddae021ec396efaf0396d4d609cd0d711 +doccontainersize 251116 +doccontainerchecksum 006319162a3a7035955064d7ab99e704bf828cc7441a9c930cfccf4cb7e70ac52ff672de3ce8b415fbfb20f29a0b4c09703fe0e3715d15e38c1293973bd3a86a docfiles size=67 RELOC/doc/fonts/playfair/OFL.txt RELOC/doc/fonts/playfair/Playfair_Display_A4_specimen.pdf @@ -251922,7 +252024,7 @@ catalogue-version 3.0.1 name poiretone category Package -revision 64527 +revision 64856 shortdesc PoiretOne family of fonts with LaTeX support relocated 1 longdesc This package provides LaTeX, pdfLaTeX, XeLaTeX and LuaLaTeX @@ -251931,10 +252033,10 @@ longdesc Masharov. PoiretOne is a decorative geometric grotesque with a longdesc hint of Art Deco and constructivism. There is currently just a longdesc regular weight and an artificially emboldened bold. execute addMap PoiretOne.map -containersize 172692 -containerchecksum bb88960e42aac6f6275621cc63c913b7b8b4d79c790bfebbb4f640ff1af5c56a1aca69dba081dbf78f81baf6215cfee078c489327563d8f66f1d1953b8e570fd -doccontainersize 12968 -doccontainerchecksum b79453597539f2510a1450dcf7bfc6a31a0c3be1a48d868cf10b548fd2d597e757e2643f4f2a603431ca2e8332fdda8cafed548c0d5276ddcccc53afe22c6c2d +containersize 172672 +containerchecksum 07e1479df1d89b568388a855236d997580cb76ca6ea8f45b55622425d10584037cec5e17a734c24a0eb0a9746966e94137026c37d4696b475e641806d07a7ef5 +doccontainersize 12964 +doccontainerchecksum c164f53258e08e74cade46f03f1e6d3d538a0f65cf3086629150c2741488bd33a82fca89d91bcbb83045d126defc3ee9493fc5e1d05e2c567464d4d29afc0cd9 docfiles size=7 RELOC/doc/fonts/poiretone/OFL.txt RELOC/doc/fonts/poiretone/README details="Readme" @@ -281334,7 +281436,7 @@ catalogue-version 1.6a name simpleicons category Package -revision 64769 +revision 64855 shortdesc Simple Icons for LaTeX relocated 1 longdesc Similar to FontAwesome icons being provided on LaTeX by the @@ -281342,16 +281444,16 @@ longdesc fontawesome package, this package aims to do the same with longdesc Simple Icons. For reference, visit their website: longdesc https://simpleicons.org/. execute addMap simpleicons.map -containersize 2698076 -containerchecksum 56d888ab9f8ffebcb5131733141d20d550c50d4a73e43b6dc61cc42a790286c07fb78f4348513f639facc8b9386053a4ff9a5b0010cb238c688fc752859f969b -doccontainersize 1979080 -doccontainerchecksum 897b9fb1bcd8210816b0c8b0dc1f820ae7ddeee368a52255341e3cda40dbece66343740c42b53f388d8c826ab081fab015c260a327518ff0bb2de5813eeac5d9 -docfiles size=515 +containersize 2700300 +containerchecksum 3858ed784073fc2179a2c704f85185bee6a2feab267f7e6e807211756ec8154ae962059a61a3f00d091cdc959955941a0ff5b6f5c6786ef39ff07c5e2dec629a +doccontainersize 1982104 +doccontainerchecksum 0c320ba57476b239b8224837e4b8885e27794f8bea4a95616917a2b7b03191513f8a11b3395376482b7c37bb81f94724c805d43c07348d5af207e6ec171b6e9d +docfiles size=516 RELOC/doc/fonts/simpleicons/README.md details="Readme" RELOC/doc/fonts/simpleicons/bindings.tex RELOC/doc/fonts/simpleicons/simpleicons.pdf details="Package documentation" RELOC/doc/fonts/simpleicons/simpleicons.tex -runfiles size=1018 +runfiles size=1020 RELOC/fonts/enc/dvips/simpleicons/simpleiconsEight.enc RELOC/fonts/enc/dvips/simpleicons/simpleiconsFive.enc RELOC/fonts/enc/dvips/simpleicons/simpleiconsFour.enc @@ -281393,7 +281495,7 @@ catalogue-contact-repository https://github.com/ineshbose/simple-icons-latex catalogue-ctan /fonts/simpleicons catalogue-license cc-by-1 catalogue-topics font font-symbol font-supp-symbol font-otf font-type1 -catalogue-version 7.16.0 +catalogue-version 7.17.0 name simpleinvoice category Package @@ -309430,7 +309532,7 @@ docfiles size=376 name texlive-scripts category TLCore -revision 64830 +revision 64843 shortdesc TeX Live infrastructure programs longdesc Includes install-tl, tl-portable, rungs, etc.; not needed for longdesc tlmgr to run but still ours. Not included in tlcritical. @@ -309438,10 +309540,10 @@ depend texlive-scripts.ARCH depend texlive.infra execute addMap mathpple.map postaction shortcut type=menu name="TeX Live command-line" cmd=TEXDIR/tlpkg/installer/tl-cmd.bat -containersize 113728 -containerchecksum 17882d42a7e87b0ed0baa145ec964a14ef345b3f0f994dedf911fe0a0cf2c035f1eeb3341b08410f14f5c396a878622aedc455e40ae7d8614570edf746cc8f45 +containersize 113684 +containerchecksum 9b837fd5ce40f1db0fd4f071dfc83342b13467f73ac7bff27672366d621e362cd2325fec6a1f66c0c4a3ceee6381ffe2873d8200b4c1e3689af2f324c7a00ca5 doccontainersize 422980 -doccontainerchecksum ee545e22a0d4946ebfbf594857857a851aacfb4978341d62322241b6bb662c1f790247c70bb044a0f7454b0ed86235bc6cb63698313ccd54e5381e28d1d6918b +doccontainerchecksum 183fe65d1f59b585ad9fb80ce62b894082db3208ef9777acfad6e059ba19875f169673cb9c67433e2b0859ed4f5ac27f84a9124ef66e2cd62e574c344aec62f0 docfiles size=531 doc.html texmf-dist/doc/man/man1/fmtutil-sys.1 @@ -324736,32 +324838,35 @@ catalogue-version 1.12d name transparent category Package -revision 52981 +revision 64852 shortdesc Using a color stack for transparency with pdfTeX relocated 1 -longdesc Since version 1.40 pdfTeX supports several color stacks; the -longdesc package uses a separate colour stack for control of -longdesc transparency (which is not, of course, a colour). -containersize 1992 -containerchecksum a1b545dee3fc210d9ff39c9ad1e8015c3972b2f1655e40f828d3bca0d8ae759772e18fd180cec5fa88d45f48076d92d07bebf2e03ef26745ad53a2fd8581d9cf -doccontainersize 266624 -doccontainerchecksum 7de04001cea582db36ed0fb0b5f8382a367603d8ce8327d29d773d05af116ae76adddd678b220d2df8abf7c6c619bee9f050f51c5aa255d7b0fb9b576638e049 -docfiles size=68 +longdesc pdfTeX and LuaTeX support several color stacks. This package +longdesc shows how a separate color stack can be used for transparency, +longdesc a property besides color that works across page breaks. If the +longdesc PDF management is used it can also be used with other engines, +longdesc but without support for page breaks. +containersize 2272 +containerchecksum 58ffa6219576a994955be228a412835c8da328c351ca0cc5dfa9d3a9fdfe8b38324890ecde9ec8ed9ccc49231169786d704ef65cdd3dfd860f5aa761a18c57d9 +doccontainersize 275336 +doccontainerchecksum 73942fa07c9bcc6e8f08b91837f96a3c781f2f60443078b67232092b98e0bfaab07e57bd43e54345df7fbb9ea20bba8bbbc10c9dc58d5cf2d0b6f6bed469d894 +docfiles size=71 RELOC/doc/latex/transparent/README.md details="Readme" RELOC/doc/latex/transparent/transparent-example.tex RELOC/doc/latex/transparent/transparent.pdf details="Package documentation" -srccontainersize 5448 -srccontainerchecksum 73a5f575a644334ee5a61f740c4f5f2e09a10ee0c4c5732be70809f66f67fddc5979bafe4a7fcd8a2462e0dec2b98867e9ba1ff2d82e3be9743ecf5773cd5ab8 +srccontainersize 5284 +srccontainerchecksum b37938a27dce42366234f7ec2ad1287e4864f53426584ae72dfd801055a06dfd15cd7abffcc0908e22971b01eafe11521c01eaa36a9d0f15fa8b1e61d3d250f2 srcfiles size=5 RELOC/source/latex/transparent/transparent.dtx -runfiles size=2 +runfiles size=3 + RELOC/tex/latex/transparent/transparent-nometadata.sty RELOC/tex/latex/transparent/transparent.sty catalogue-contact-bugs https://github.com/ho-tex/transparent/issues catalogue-contact-repository https://github.com/ho-tex/transparent catalogue-ctan /macros/latex/contrib/transparent -catalogue-license lppl1.3 +catalogue-license lppl1.3c catalogue-topics typesetting -catalogue-version 1.4 +catalogue-version 1.5 name transparent-io category Package @@ -325915,18 +326020,18 @@ catalogue-version 1.3a name twemoji-colr category Package -revision 59957 +revision 64854 shortdesc Twemoji font in COLR/CPAL layered format relocated 1 longdesc This is a COLR/CPAL-based color OpenType font from the Twemoji longdesc collection of emoji images. -containersize 564740 -containerchecksum 7e186ffdd023c84419ec704034872805c81bc729b2f828a61af2c1f4cdb3ac40720315967ebd2ceb0349169ffae6ff6e202a1d9196f8c0c0811c66844bae5dc9 -doccontainersize 708 -doccontainerchecksum 368ef5dcfa3609359b154d31d753c89cbe50f377c254cbb40a30beb0757f8bf177eb3bd48ae751f66bdc8c5f95238d514653a6381984a1c9c22ed99266272b42 +containersize 581228 +containerchecksum abc9583bbfd3690ff52b2341e74166fb70eb0f6abbaf99b01b0f24b818abbe3cd7556ef9cdc3cf58c056a038fe6fc3bdd45199c437a7eab99b300622e8d7308a +doccontainersize 712 +doccontainerchecksum 90e01641e73702fe012510bf3c9cf741bbeb594d528b2eb69487bd57beeff59c27ab397902b3c42d5dd1b5745e5b69d0db80b3b2d399bb1ba67e2c85d14a88b5 docfiles size=1 RELOC/doc/fonts/twemoji-colr/README.md details="Readme" -runfiles size=352 +runfiles size=360 RELOC/fonts/truetype/public/twemoji-colr/TwemojiMozilla.ttf catalogue-contact-bugs https://github.com/mozilla/twemoji-colr/issues catalogue-contact-home https://twemoji.twitter.com/ @@ -325934,7 +326039,7 @@ catalogue-contact-repository https://github.com/mozilla/twemoji-colr catalogue-ctan /fonts/twemoji-colr catalogue-license cc-by-sa-4 apache2 catalogue-topics font font-ttf font-symbol -catalogue-version 0.6.0 +catalogue-version 0.7.0 name twemojis category Package diff --git a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 index 993f7d52be..a4be8cdf90 100644 --- a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 +++ b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.md5 @@ -1 +1 @@ -44a403404f0b9115646ff2d9b973fe40 texlive.tlpdb +f18bb6f0bb1e42e048f50c07f77fe96a texlive.tlpdb diff --git a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 index e0c269f2cc..2b3cb22384 100644 --- a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 +++ b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512 @@ -1 +1 @@ -8e2c1233627d6d69f9bd4d53e8a958f47bf5b2ca58064bac4c43318843a393bbc731c5d3b07b872a092e82338d223804db3da014410cd25f57a49ced7deb6f94 texlive.tlpdb +a53e6e4d8da1c4616235b314d60f74fa0811d42bdc47b00cc3b398d0a7b2952bf74bb25509e9403e691aa2d2220e418fade136546b0d78030d182235fbb683b1 texlive.tlpdb diff --git a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc index 54e0db817a..3ab4d29563 100644 --- a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc +++ b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.sha512.asc @@ -1,10 +1,10 @@ -----BEGIN PGP SIGNATURE----- -iQEcBAEBCgAGBQJjXGt8AAoJEEzhh34ZQ4xwH7wH/AxbagWxPaqTsnAwyysBzhPW -kAjej+2rOGEc15CAVgOdk5uA8Ydp9ptLbG7uHToC4VfQd8SID/72RV34t+0Oczxv -edpEt7+m+6qDvGtKqb6bpOlhNz2hS2Z1y5eqP6S7HsbwS8NKteBwaa0PEqif/2va -I7tOGn+X2Cr5cPgv54TAKZS1jsvr09QKAqczc0qQKDvEo/PPQ0NH6DZ6++FaTvVt -YZhPpCcWHSq7BpJsXH7aubJ6qW1iGWMkDi70lQAKZ+hY+eJHtPrODeWd/DbtDXXC -3SglSqSApOet7SPc2I/vGzctMOKp8DBHsBpwwlplYvEOfjfXtPIQliK3bqoZou4= -=SMJG +iQEcBAEBCgAGBQJjXb0OAAoJEEzhh34ZQ4xww8UH/jhZuZfr8S2QPm6wWcg+JtD+ +IavOaWl4d8HZHFBKCzBRPUboHarJ0OwTHmu5PmRdl8ZVrZxRaneOC8Ab/rE6DhAT +xJhczNp1IpbwQTkGGJp9mWtU/u3YY5QBaDhUWuCYIFszi4UBr2fs38H8WEHOU10i +xRkiZuv0xQefRT9tF/jwPvgzBxkddKafATNGuYBrPTsDkAAq5Oq/ccgcOWEB4hfY +tNpzmpSAISerHVNzDwG2Xvb6cvld9L94LWuoOM+x0LG5tv7WkP/61BR5iataWj4s +LuIQa+VNHQZ1HbYM0OZHrostX6eb9bcGbC42DhnKdRA8jgTjBFYItjl5jh0ul7I= +=GmZS -----END PGP SIGNATURE----- diff --git a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz index 534be33f79..f419b86121 100644 Binary files a/systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz and b/systems/texlive/tlnet/tlpkg/texlive.tlpdb.xz differ diff --git a/systems/win32/miktex/tm/packages/next/pr.ini b/systems/win32/miktex/tm/packages/next/pr.ini index 73180009a6..3cc154c584 100644 --- a/systems/win32/miktex/tm/packages/next/pr.ini +++ b/systems/win32/miktex/tm/packages/next/pr.ini @@ -1,13 +1,13 @@ [repository] -date=1667074589 +date=1667164587 lastupd=miktex-arctrl-bin-x64-2.9 miktex-asymptote-bin-x64-2.9 miktex-autosp-bin-x64-2.9 miktex-axohelp-bin-x64-2.9 miktex-bibarts-bin-x64-2.9 miktex-bibtex-bin-x64-2.9 miktex-bibtex8bit-bin-x64-2.9 miktex-bzip2-bin-x64-2.9 miktex-cairo-bin-x64-2.9 miktex-chktex-bin-x64-2.9 miktex-cjkutils-bin-x64-2.9 miktex-console-bin-x64-2.9 miktex-curl-bin-x64-2.9 miktex-cweb-bin-x64-2.9 miktex-devnag-bin-x64-2.9 miktex-doc miktex-dvicopy-bin-x64-2.9 miktex-dvipdfmx-bin-x64-2.9 miktex-dvipng-bin-x64-2.9 miktex-dvips-bin-x64-2.9 -lstdigest=0193f6cce2a09c97a23e8968df45d66a +lstdigest=83a1801bcb95ed60c18e976c17f58ef3 numpkg=6103 relstate=next -version=8337 +version=8338 ;;;;This configuration file is signed by a MiKTeX maintainer. The signature follows. ;;;;-----BEGIN MIKTEX SIGNATURE----- -;;;; signature/miktex: ZTk8KOC7xhTuc8aq4ocqLVnRqhhtLhBLnUy0UHBH5ngkTHWwOEZUgOL4x2J+OuiOu0j2USjs0Aj38I7KUfgC5G8L8tDSkWi5+pe+ojO+Qi0K0QdCqiA1ukOSU5CpOOp9td6FlfGwiLGi4msonzrd5HErPX9AM/oCh6Hy/XvIgpku4zycWvATYMO7PSAyxpgJhjagLfQxi69yF2/aKLMw9bKflpJVCKRl/T3REOAuaAQVSSXHmIJsLWEHShngRqwDraClLnw/BZVgWKguJEw36lrn97mBMEdkOaVxvW66rufLNPOXNj4D/XX6unhr0oIb7cA2/SGkWp9NvmNpb53eLg== +;;;; signature/miktex: Uo/QfsDNVvOZPmMzArXrTuapKIdIb+CR0XZ2/ZASBhVEX/DznSKSlpTibsXkYiZ7cUHeNaTHgStbithT0Du4Z4+1Royp4gTFy1BFkR3ovdWfweDH2+62Bsyoh3FaUCifCcDvcsxZW9Qzbmngf9caV0+SX7nx4pBWFGPBA+HyvRZscwsY0K5ZUzsGFRmSZgWeZx330FPugZvLonflGlJpte3NVq5q+++OVY+gIMAdgLFp+NB6GjxIc0dXug21UuMsouqDWN1Ivo/cIOb6KrpTFghkEgAX/lEJIUFopyxp4q5VH8gaPjKjq/WWdeRc/xkpNI2fA5DXBqpf5UP2KcZz7w== ;;;;-----END MIKTEX SIGNATURE----- diff --git a/systems/win32/miktex/tm/packages/pr.ini b/systems/win32/miktex/tm/packages/pr.ini index 4bfeba5d02..2306bc9d14 100644 --- a/systems/win32/miktex/tm/packages/pr.ini +++ b/systems/win32/miktex/tm/packages/pr.ini @@ -1,13 +1,13 @@ [repository] -date=1667074297 +date=1667164294 lastupd=pgf-periodictable pgf-periodictable__doc pgf-periodictable__source urw-base35 urw-base35__doc urw-base35__source miktex-runtime-bin-x64-2.9 standalone was was__doc was__source xcharter-math xcharter-math__doc xcharter-math__source abntexto abntexto__doc abntexto__source algpseudocodex algpseudocodex__doc algpseudocodex__source -lstdigest=682f09bbc0cdc4e808637b502c3944c5 +lstdigest=9fab14f83dd5ac67db881004ae8f9829 numpkg=6103 relstate=stable -version=8337 +version=8338 ;;;;This configuration file is signed by a MiKTeX maintainer. The signature follows. ;;;;-----BEGIN MIKTEX SIGNATURE----- -;;;; signature/miktex: AdeXt7jMOOe8cIkOBqxgrH10dMTioFdgZmnsWrQpRVlN+xA2mPVMTVH4mgqDX0vI/fCFEbo5H4FPzz13nRn0rvMMyc1Vr+6yOZYEhO8QAbHlVcyHV5CFJXjJ8idnFj96IMioQuHdvIl49/9uuvtPzC94r2NMZl0pw/ZonuC6L4z7DqQgJpf5W8a4fGzq7R29/1tdS20C5OxYP6s0vm8S5qLxw6OOZXV402Y631Dj4ofs0+XQXAOCvIZHOC6YRRHdy1Lp2kCh6w4hGdbad8FtST9lhJwU8yGx1x8YbRKLLG5oGiCe1VHh+xoJfJqh1ZIsUdwMP+IGPv/kexT+bK6mQw== +;;;; signature/miktex: F8puSUh+JylQ969v+o3Phr7VCUHn9SAz1grk3TL3OHzz2dEeip+sp/y7/ZFeFCt4u0HsGRvn48XL6gdr354XnNhFsBW0tDgCbWzlFTHibFbBQxYFS9jiOhp1lsFGRB6MlYIUT5PmzAvoL2511PG8gaeaGBKkIClde0oCAQlc81wHSSFRSChCCUAn9DrGXps1ex5dnjjsIoLfuEmOY40Htf9kxLhf9TycHvRbkVFPgIqeDeQKmJizEh8QgQo1GtdyrI5u0XW4Bma6NWanrqanMxWsD3+tIrIvtGiNOAIZTE15rC4YK2IGkGDhFxRbgpcMWZ1YHYpYbQU8O9r8K2zV1w== ;;;;-----END MIKTEX SIGNATURE----- diff --git a/timestamp b/timestamp index 25024195e0..f320f7d9e0 100644 --- a/timestamp +++ b/timestamp @@ -2,4 +2,4 @@ # The source CTAN of this site's material: dante.ctan.org # The year-month-day-hour-minute of this site's material: -2022-10-30-02-02 +2022-10-31-02-02 -- cgit v1.2.3