diff options
author | Karl Berry <karl@freefriends.org> | 2023-09-10 19:42:49 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-09-10 19:42:49 +0000 |
commit | 66fb8277be872f30bfeee09e0fcf0974cc9e1ce5 (patch) | |
tree | 8fbde748eb5b5efbea74fb9b07eae1c53557becd /Master/texmf-dist/doc | |
parent | 0c348ebe85171a026733f65f8517076a88a4c4fd (diff) |
runtexshebang (10sep23)
git-svn-id: svn://tug.org/texlive/trunk@68232 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/support/runtexshebang/LICENSE | 21 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/runtexshebang/README.md | 175 |
2 files changed, 196 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 |