texlive[73090] trunk: expltools (10dec24)
commits+karl at tug.org
commits+karl at tug.org
Tue Dec 10 22:42:57 CET 2024
Revision: 73090
https://tug.org/svn/texlive?view=revision&revision=73090
Author: karl
Date: 2024-12-10 22:42:57 +0100 (Tue, 10 Dec 2024)
Log Message:
-----------
expltools (10dec24)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/expltools/explcheck.lua
trunk/Master/texmf-dist/doc/support/expltools/CHANGES.md
trunk/Master/texmf-dist/doc/support/expltools/README.md
trunk/Master/texmf-dist/doc/support/expltools/project-proposal.pdf
trunk/Master/texmf-dist/doc/support/expltools/warnings-and-errors.pdf
trunk/Master/texmf-dist/scripts/expltools/explcheck-cli.lua
trunk/Master/texmf-dist/scripts/expltools/explcheck-preprocessing.lua
trunk/Master/texmf-dist/scripts/expltools/explcheck.lua
Modified: trunk/Build/source/texk/texlive/linked_scripts/expltools/explcheck.lua
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/expltools/explcheck.lua 2024-12-10 00:42:20 UTC (rev 73089)
+++ trunk/Build/source/texk/texlive/linked_scripts/expltools/explcheck.lua 2024-12-10 21:42:57 UTC (rev 73090)
@@ -1,3 +1,7 @@
#!/usr/bin/env texlua
-- A command-line interface for the static analyzer explcheck.
+local using_luatex, kpse = pcall(require, "kpse")
+if using_luatex then
+ kpse.set_program_name("texlua", "explcheck")
+end
require("explcheck-cli")
Modified: trunk/Master/texmf-dist/doc/support/expltools/CHANGES.md
===================================================================
--- trunk/Master/texmf-dist/doc/support/expltools/CHANGES.md 2024-12-10 00:42:20 UTC (rev 73089)
+++ trunk/Master/texmf-dist/doc/support/expltools/CHANGES.md 2024-12-10 21:42:57 UTC (rev 73090)
@@ -1,5 +1,64 @@
# Changes
-## 2024-12-04
+## expltools 2024-12-09
-- The first release of the project that implements the preprocessing step.
+### explcheck v0.1.1
+
+#### Fixes
+
+- In LuaTeX, initialize Kpathsea Lua module searchers first.
+
+ (reported by @josephwright, Lars Madsen, and Philip Taylor on
+ [tex-live at tug.org][tex-live-02] and by @muzimuzhi in #9,
+ fixed on [tex-live at tug.org][tex-live-03] by @gucci-on-fleek)
+
+- Allow spaces between arguments of `\ProvidesExpl*` commands.
+ (reported by @u-fischer and @josephwright in #7, fixed in #13)
+
+ [tex-live-02]: https://tug.org/pipermail/tex-live/2024-December/050958.html
+ [tex-live-03]: https://tug.org/pipermail/tex-live/2024-December/050968.html
+
+#### Documentation
+
+- Include explcheck version in the command-line interface.
+ (reported in #10, fixed in #13)
+
+- Hint in the file `README.md` that .dtx are not well supported.
+ (reported by @josephwright in #8, added in #13)
+
+- Show in the file `README.md` how explcheck can be used from Lua code. (#13)
+
+- Include instructions about using l3build in the file `README.md`.
+ (reported in #11, added in #13)
+
+#### Continuous integration
+
+- Add `Dockerfile`, create Docker image, and mention it in the file `README.md`.
+ (discussed in #12, added in #13)
+
+## expltools 2024-12-04
+
+### explcheck v0.1
+
+#### Development
+
+- Implement preprocessing. (#5)
+
+#### Documentation
+
+- Add `README.md`. (suggested by @Skillmon in #1, fixed in #2)
+- Update to Markdown 3. (#3)
+- Use the expl3 prefix `expltools`. (#3)
+- Add project proposal. (#4)
+
+#### Continuous integration
+
+- Use small Docker image. (#3)
+
+#### Distribution
+
+- Make changes to the CTAN archive following a discussion with TeX Live developers
+ on [tex-live at tug.org][tex-live-01] and with CTAN maintainers. Many thanks
+ specifically to Petra Rübe-Pugliese, Reinhard Kotucha, and Zdeněk Wagner.
+
+ [tex-live-01]: https://tug.org/pipermail/tex-live/2024-December/050952.html
Modified: trunk/Master/texmf-dist/doc/support/expltools/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/support/expltools/README.md 2024-12-10 00:42:20 UTC (rev 73089)
+++ trunk/Master/texmf-dist/doc/support/expltools/README.md 2024-12-10 21:42:57 UTC (rev 73090)
@@ -6,9 +6,10 @@
2. [Requirements][2]
3. [Related work][3]
4. [Design][4]
+5. [First public release][5]
-On September 6, 2024, the tool has been [accepted for funding][5] by [the TeX Development Fund][6].
-The full text of the project proposal, which summarizes devlog posts 1–4 is available [here][7].
+On September 6, 2024, the tool has been [accepted for funding][6] by [the TeX Development Fund][7].
+The full text of the project proposal, which summarizes devlog posts 1–4 is available [here][8].
In the future, this repository may also contain the code of other useful development tools for expl3 programmers, such as a command-line utility similar to `grep` that will ignore whitespaces and newlines as well as other tools.
@@ -16,25 +17,78 @@
[2]: https://witiko.github.io/Expl3-Linter-2/
[3]: https://witiko.github.io/Expl3-Linter-3/
[4]: https://witiko.github.io/Expl3-Linter-4/
- [5]: https://tug.org/tc/devfund/grants.html
- [6]: https://tug.org/tc/devfund/application.html
- [7]: https://tug.org/tc/devfund/documents/2024-09-expltools.pdf
+ [5]: https://witiko.github.io/Expl3-Linter-5/
+ [6]: https://tug.org/tc/devfund/grants.html
+ [7]: https://tug.org/tc/devfund/application.html
+ [8]: https://tug.org/tc/devfund/documents/2024-09-expltools.pdf
## Usage
-You can use the tool from command-line as follows:
+You can use the tool from the command line as follows:
```
-$ explcheck [options] [filenames]
+$ explcheck [options] [.tex, .cls, and .sty files]
```
+You can also use the tool from your own Lua code by importing the corresponding files `explcheck-*.lua`.
+For example, here is Lua code that applies the preprocessing step to the code from a file named `code.tex`:
+
+``` lua
+local new_issues = require("explcheck-issues")
+local preprocessing = require("explcheck-preprocessing")
+
+-- LuaTeX users must initialize Kpathsea Lua module searchers first.
+local using_luatex, kpse = pcall(require, "kpse")
+if using_luatex then
+ kpse.set_program_name("texlua", "explcheck")
+end
+
+-- Apply the preprocessing step to a file "code.tex".
+local filename = "code.tex"
+local issues = new_issues()
+
+local file = assert(io.open(filename, "r"))
+local content = assert(file:read("*a"))
+assert(file:close())
+
+local line_starting_byte_numbers = preprocessing(issues, content)
+
+print(
+ "There were " .. #issues.warnings .. " warnings "
+ .. "and " .. #issues.errors .. " errors "
+ .. "in the file " .. filename .. "."
+)
+```
+
+You can also use the tool from continuous integration workflows using the Docker image `ghcr.io/witiko/expltools/explcheck`.
+For example, here is a GitHub Actions workflow file that applies the tool to all .tex file in a Git repository:
+
+``` yaml
+name: Check expl3 code
+on:
+ push:
+jobs:
+ typeset:
+ runs-on: ubuntu-latest
+ container:
+ image: ghcr.io/witiko/expltools/explcheck
+ steps:
+ - uses: actions/checkout at v4
+ - run: explcheck *.tex
+```
+
## Notes to distributors
-The file `explcheck.lua` should be installed in the TDS directory `scripts/expltools/explcheck`. Furthermore, it should be made executable, and either symlinked to system directories as `expltools` on Unix or have a wrapper `expltools.exe` installed on Windows.
+You can prepare the expltools bundle for distribution with the following two commands:
+- `l3build tag`: Add the current version numbers to the file `explcheck-lua.cli`.
+- `l3build ctan`: Run tests, build the documentation, and create a CTAN archive `expltools-ctan.zip`.
+
+The file `explcheck.lua` should be installed in the TDS directory `scripts/expltools/explcheck`. Furthermore, it should be made executable and either symlinked to system directories as `explcheck` on Unix or have a wrapper `explcheck.exe` installed on Windows.
+
## Authors
-- Vít Starý Novotný (<mailto:witiko at mail.muni.cz>)
+- Vít Starý Novotný (<witiko at mail.muni.cz>)
## License
Modified: trunk/Master/texmf-dist/doc/support/expltools/project-proposal.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/expltools/warnings-and-errors.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/scripts/expltools/explcheck-cli.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/expltools/explcheck-cli.lua 2024-12-10 00:42:20 UTC (rev 73089)
+++ trunk/Master/texmf-dist/scripts/expltools/explcheck-cli.lua 2024-12-10 21:42:57 UTC (rev 73090)
@@ -76,6 +76,12 @@
print("\t--warnings-are-errors\tProduce a non-zero exit code if any warnings are produced by the analysis.")
end
+local function print_version()
+ print("explcheck (expltools 2024-12-09) v0.1.1")
+ print("Copyright (c) 2024 Vít Starý Novotný")
+ print("Licenses: LPPL 1.3 or later, GNU GPL v2 or later")
+end
+
if #arg == 0 then
print_usage()
os.exit(1)
@@ -90,9 +96,12 @@
table.insert(pathnames, argument)
elseif argument == "--" then
only_pathnames_from_now_on = true
- elseif argument == "--help" then
+ elseif argument == "--help" or argument == "-h" then
print_usage()
os.exit(0)
+ elseif argument == "--version" or argument == "-v" then
+ print_version()
+ os.exit(0)
elseif argument == "--warnings-are-errors" then
warnings_are_errors = true
elseif argument:sub(1, 18) == "--max-line-length=" then
Modified: trunk/Master/texmf-dist/scripts/expltools/explcheck-preprocessing.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/expltools/explcheck-preprocessing.lua 2024-12-10 00:42:20 UTC (rev 73089)
+++ trunk/Master/texmf-dist/scripts/expltools/explcheck-preprocessing.lua 2024-12-10 21:42:57 UTC (rev 73090)
@@ -26,7 +26,7 @@
local linechar = any - newline
local spacechar = S("\t ")
local optional_spaces = spacechar^0
-local optional_spaces_and_newline_after_cs = (
+local optional_spaces_and_newline = (
optional_spaces
* (
newline
@@ -65,13 +65,16 @@
+ P("Class")
+ P("File")
)
- * optional_spaces_and_newline_after_cs
+ * optional_spaces_and_newline
* comment^0
* argument
+ * optional_spaces_and_newline
* comment^0
* argument
+ * optional_spaces_and_newline
* comment^0
* argument
+ * optional_spaces_and_newline
* comment^0
* argument
)
Modified: trunk/Master/texmf-dist/scripts/expltools/explcheck.lua
===================================================================
--- trunk/Master/texmf-dist/scripts/expltools/explcheck.lua 2024-12-10 00:42:20 UTC (rev 73089)
+++ trunk/Master/texmf-dist/scripts/expltools/explcheck.lua 2024-12-10 21:42:57 UTC (rev 73090)
@@ -1,3 +1,7 @@
#!/usr/bin/env texlua
-- A command-line interface for the static analyzer explcheck.
+local using_luatex, kpse = pcall(require, "kpse")
+if using_luatex then
+ kpse.set_program_name("texlua", "explcheck")
+end
require("explcheck-cli")
More information about the tex-live-commits
mailing list.