summaryrefslogtreecommitdiff
path: root/Master/texmf-dist
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-09-10 19:42:49 +0000
committerKarl Berry <karl@freefriends.org>2023-09-10 19:42:49 +0000
commit66fb8277be872f30bfeee09e0fcf0974cc9e1ce5 (patch)
tree8fbde748eb5b5efbea74fb9b07eae1c53557becd /Master/texmf-dist
parent0c348ebe85171a026733f65f8517076a88a4c4fd (diff)
runtexshebang (10sep23)
git-svn-id: svn://tug.org/texlive/trunk@68232 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist')
-rw-r--r--Master/texmf-dist/doc/support/runtexshebang/LICENSE21
-rw-r--r--Master/texmf-dist/doc/support/runtexshebang/README.md175
-rwxr-xr-xMaster/texmf-dist/scripts/runtexshebang/runtexshebang.lua61
3 files changed, 257 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/runtexshebang/LICENSE b/Master/texmf-dist/doc/support/runtexshebang/LICENSE
new file mode 100644
index 00000000000..48b5cdea989
--- /dev/null
+++ b/Master/texmf-dist/doc/support/runtexshebang/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2023 Munehiro Yamamoto <munepixyz@gmail.com>
+
+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/Master/texmf-dist/doc/support/runtexshebang/README.md b/Master/texmf-dist/doc/support/runtexshebang/README.md
new file mode 100644
index 00000000000..e96825b9c18
--- /dev/null
+++ b/Master/texmf-dist/doc/support/runtexshebang/README.md
@@ -0,0 +1,175 @@
+# runtexshebang: Lua script running LaTeX document files with TeX-style shebang
+
+Lua script running LaTeX document files with a TeX-style shebang (`%#!`)
+
+## What is a TeX-style shebang (`%#!`)
+
+In short, a TeX-style shebang (`%#!`) is a special kind of TeX comment
+that you include in your TeX/LaTeX document file to tell the operating system's
+shell how to run the file for the rest of the file:
+
+``` latex
+%#!lualatex foo.tex
+\documentclass{article}
+\begin{document}
+Hello, {\LaTeX} World!
+
+Happy {\TeX}ing.
+\end{document}
+```
+
+If you are using a TeX-style shebang, it must appear on the line that
+matched 20 lines or less in your LaTeX document, and it has to start with
+a TeX comment symbol (`%`) followed by a hash sign (`#`) and an exclamation mark (`!`),
+colloquially known as the bang, hence the name shebang for TeX/LaTeX.
+
+
+## Getting started
+
+### 1. Install `runtexshebang.lua` in your TeX Live system.
+
+``` shell
+cp runtexshebang.lua /some/where/TEXMFDIST_or_TEXMFLOCAL/scripts/runtexshebang/runtexshebang.lua
+
+cd TEXLIVE_BIN_DIRECTORY
+ln -s ../../TEXMFDIST_or_TEXMFLOCAL/scripts/runtexshebang/runtexshebang.lua runtexshebang
+```
+
+### 2. Make a sample file with a TeX-style shebang.
+
+Make the following LaTeX document.
+
+``` latex
+%#!lualatex foo.tex
+\documentclass{article}
+\begin{document}
+Hello, {\LaTeX} World!
+
+Happy {\TeX}ing.
+\end{document}
+```
+
+### 3. Run the sample file.
+
+``` shell
+runtexshebang foo.tex
+```
+
+Then, it will run `lualatex foo.tex`.
+
+
+## Examples
+
+### TeXworks
+
+#### Settings
+
+1. Open "Typesetting" tab in TeXworks Preferences.
+2. Add the tool configuration "runtexshebang" in "Processing tools" as below.
+ - Name: `runtexshebang`
+ - Program: `runtexshebang`
+ - Arguments: `$fullname`
+ - ☑ View PDF after running (if necessary)
+
+#### LaTeX document in the internal editor of TeXwork
+
+`% !TEX program = ` is a magic comment of TeXworks.
+You can set one processing tool as
+`% !TEX program = <your choice of tool configuration>`.
+
+``` latex
+% !TEX program = runtexshebang
+%#! lualatex --synctex=1 foo
+```
+
+
+### LaTeX Workshop: Visual Studio Code
+
+#### Settings
+
+Nothing!
+
+#### LaTeX document in Visual Studio Code
+
+`% !TEX program = ` is a magic comment of LaTeX Workshop.
+You need another magic comment to the target LaTeX document file as below.
+
+``` latex
+% !TEX program = runtexshebang
+% !TEX options = "%DOC%".tex
+%#! lualatex --synctex=1 foo
+```
+
+
+### TeXShop
+
+#### Settings
+
+There the “Engine” settings for the command lines "TeX+dvipdfmx / TeX+dvips+distiller" as follows.
+
+* TeX: `runtexshebang`
+* LaTeX: `runtexshebang`
+
+#### LaTeX document in the internal editor of TeXShop
+
+`% !TEX program = ` is a magic comment of TeXShop.
+
+``` latex
+% !TEX program = runtexshebang
+%#! lualatex --synctex=1 foo
+```
+
+
+## Applications
+
+### What does the PATH variable set in my editor?
+
+``` latex
+%#! echo $PATH
+```
+
+### How about general configuration information for the activated TeX Live version and its configuration in my editor?
+
+``` latex
+%#! tlmgr --conf
+```
+
+### Otherwise
+
+You can run any command line on your OSs.
+For example, you can use any build tools as follows:
+`make`, `rake`, `llmk`, `latexmk`, and so on.
+
+``` latex
+%#! make foo.pdf
+
+% #! rake foo.pdf
+% #! llmk
+% #! latexmk foo
+%% and so on.
+```
+
+You can typeset a LaTeX document file in a Docker container as below.
+
+``` latex
+%#! docker run -i --rm --workdir /data --mount type=bind,src=$(pwd)/,dst=/data/ bar/foo lualatex foo
+```
+
+
+## References
+
+* [TeXworks、TeXShop、VSCodeでTeX-style shebangしてみた - Qiita](https://qiita.com/munepi/items/a30c68133cfffbf4d189) (in Japanese)
+
+
+
+Enjoy Happy TeXing!
+
+
+## License
+
+This program is licensed under the terms of the MIT License.
+
+--------------------
+
+Munehiro Yamamoto
+https://github.com/munepi
diff --git a/Master/texmf-dist/scripts/runtexshebang/runtexshebang.lua b/Master/texmf-dist/scripts/runtexshebang/runtexshebang.lua
new file mode 100755
index 00000000000..11240adfe06
--- /dev/null
+++ b/Master/texmf-dist/scripts/runtexshebang/runtexshebang.lua
@@ -0,0 +1,61 @@
+#!/usr/bin/env texlua
+
+-- This program is licensed under the terms of the MIT License.
+--
+-- Copyright (c) 2021-2023 Munehiro Yamamoto <munepixyz@gmail.com>
+--
+-- 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.
+
+if not ( #arg == 1 ) then
+ print("runtexshebang 20230909 v0.3")
+ print("")
+ print("Usage: runtexshebang [input.tex]")
+ os.exit(0)
+end
+
+local line_ctr = 0
+for line in io.lines(arg[1]) do
+ line_ctr = line_ctr + 1
+ if line_ctr > 20 then break end
+
+ if string.match(line, "^%%#!") then
+ tex_cmd, err=string.gsub(line, "%%#!", "")
+ tex_return = os.execute(tex_cmd)
+
+ -- if os.execute(texcmd) returns -1 on Windows, then
+ -- cmd.exe is not included in PATH, or some invalid string found before cmd.exe
+ if os.type == 'windows' and tex_return == -1 then
+ print("Invalid PATH setting found. Please ensure that cmd.exe can be found.\n")
+ os.exit(1)
+ end
+
+ -- if not tex_return == 0 then
+ -- print("TeX-style shebang processing of the below failed.\n" .. tex_cmd .. "\n")
+ -- os.exit(1)
+ -- end
+
+ os.exit(0)
+
+ -- else
+ -- print("TeX-style shebang not matched.\n")
+ end
+end
+
+print("TeX-style shebang not found.\n")
+os.exit(2)