summaryrefslogtreecommitdiff
path: root/support/texosquery/README.md
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texosquery/README.md
Initial commit
Diffstat (limited to 'support/texosquery/README.md')
-rw-r--r--support/texosquery/README.md413
1 files changed, 413 insertions, 0 deletions
diff --git a/support/texosquery/README.md b/support/texosquery/README.md
new file mode 100644
index 0000000000..ce37682edd
--- /dev/null
+++ b/support/texosquery/README.md
@@ -0,0 +1,413 @@
+# texosquery
+Cross-platform Java application to query OS information designed for use in
+TeX's shell escape mechanism.
+
+The application can query the following:
+
+ - locale information
+ - default file encoding
+ - current working directory
+ - user home directory
+ - temporary directory
+ - OS name, arch and version
+ - Current date and time in PDF format
+ (for TeX formats that don't provide `\pdfcreationdate`)
+ - Date-time stamp of a file in PDF format
+ (for TeX formats that don't provide `\pdffilemoddate`)
+ - Size of a file in bytes
+ (for TeX formats that don't provide `\pdffilesize`)
+ - Contents of a directory (captured as a list)
+ - Directory contents filtered by regular expression
+ (captured as a list)
+ - URI of a file
+ - Canonical path of a file
+
+All paths use a forward slash as directory divider so results
+can be used, for example, in commands like `\includegraphics`.
+
+There are files provided for easy access in (La)TeX documents:
+
+ - `texosquery.tex` : generic TeX code
+ - `texosquery.sty` : LaTeX package
+
+This provides the command `\TeXOSQuery` to run `texosquery` using
+TeX's shell escape mechanism and capture the result in a control
+sequence. The category code of most of TeX's default special
+characters (and some other potentially problematic characters) is
+temporarily changed to 12 while reading the result. Some of the
+`texosquery` output contains short markup commands (such as `\wrp`)
+which are internally converted within `\TeXOSQuery`.
+
+## Important Notes
+
+The TeX code uses a piped shell escape to capture the result from
+`texosquery`. This means that you must have the piped shell escape
+enabled to make use of this feature. MiKTeX users need the
+`--enable-pipes` option on the TeX command line to enable this.
+The alternative is to run `texosquery` outside of TeX and
+capture the output in a temporary file, which can then be
+read using `\TeXOSQueryFromFile`.
+
+You need to correctly set up the configuration file `texosquery.cfg`
+to match your system. The TeX package managers can't do this for you
+automatically. Copy the file to either your `TEXMFHOME` or
+`TEXMFLOCAL` tree to prevent it from being overwritten by subsequent
+updates.
+
+`texosquery-jre8` is on the restricted list for TeX Live 2017. To
+take advantage of this, you must have at least Java 8 installed and
+edit the `texosquery.cfg` file to:
+```tex
+\def\TeXOSInvokerName{texosquery-jre8}
+\TeXOSQueryAllowRestricted
+```
+(Note that the second line above has been uncommented.)
+
+Note that due to TeX's security measures, quotes can't be used in the
+restricted mode's shell escape. This means that if you need to pass
+a file name containing a space as an argument to `texosquery`,
+you'll have to use the unrestricted mode.
+
+## Installation
+
+Installation is best done using your TeX package manager.
+Manual installation instructions are described below.
+For more detail, see the documentation.
+
+### Compiling the Documentation
+
+To compile the documentation:
+```bash
+pdflatex texosquery.dtx
+makeglossaries texosquery
+makeindex -s gglo.ist -t texosquery.glg -o texosquery.gls texosquery.glo
+pdflatex texosquery.dtx
+makeindex -s gind.ist texosquery.idx
+pdflatex texosquery.dtx
+pdflatex texosquery.dtx
+```
+
+### Extracting the Files
+
+Except for the `.jar` files, the `texosquery` files are all
+bundled inside `texosquery.dtx` with the extraction commands
+provided in `texosquery.ins`. To extract all the files do:
+```bash
+tex texosquery.ins
+```
+
+The `.sh` files are bash scripts for Unix-like users. These will
+need to be set to executable using `chmod`. I recommend
+that you also remove the `.sh` extension. Windows users can
+deleted these files.
+
+The `.batch` files are batch scripts for Windows users. Unix-like
+users can delete these files. These files are given the extension
+`.batch` as TeX on Windows doesn't allow the creation of `.bat`
+files. The extension will need to be changed to `.bat` after the
+files have been extracted.
+
+### Installing the Application
+
+In the following, replace _TEXMF_ with the path to your TEXMF directory.
+You can find your home TEXMF directory using
+```bash
+kpsewhich -var-value=TEXMFHOME
+```
+
+There are now three Java applications provided by this package:
+
+ - `texosquery.jar` (requires at least Java 7)
+ - `texosquery-jre8.jar` (requires at least Java 8)
+ - `texosquery-jre5.jar` (requires at least Java 5)
+
+(See the ["Security"](#security) section below.)
+
+There are corresponding bash scripts for Unix-like users (the `.sh`
+extension added by `texosquery.ins` should be removed and the files
+made executable):
+
+ - `texosquery`
+ - `texosquery-jre8`
+ - `texosquery-jre5`
+
+There are also corresponding batch scripts for Windows users (the `.batch`
+extension created by the `.ins` file should be changed to `.bat`):
+
+ - `texosquery.bat`
+ - `texosquery-jre8.bat`
+ - `texosquery-jre5.bat`
+
+Each script uses `kpsewhich` to find the corresponding `.jar` file
+and runs it.
+
+Put the `.jar` files in _TEXMF_`/scripts/texosquery/` and the
+bash or `.bat` files somewhere on your path. You may or may not need
+to refresh the TeX database.
+
+To test the installation, run
+```bash
+texosquery -v
+```
+in the command prompt or terminal. (Also try with `texosquery-jre8`
+and `texosquery-jre5`.)
+
+If successful, it should show the version number.
+
+### Installing the TeX Code
+
+The `.tex`, `.cfg` and `.sty` files should all be extracted from `texosquery.dtx`
+with `tex texosquery.ins` as described above.
+
+ - Move `texosquery.tex` to _TEXMF_`/tex/generic/texosquery/`
+ - Move `texosquery.cfg` to _TEXMF_`/tex/generic/texosquery/`
+ - Move `texosquery.sty` to _TEXMF_`/tex/latex/texosquery/`
+ - Move `texosquery.pdf` to _TEXMF_`/doc/generic/texosquery/`
+
+The `texosquery.cfg` file allows you to specify which application you
+want to use. First check which version of the Java Runtime
+Environment (JRE) you have installed:
+```bash
+java -version
+```
+This should display the version information. (For example, `"1.8.0_92"`)
+
+If the version number starts with `1.8` ("Java 8"), then you can use `texosquery-jre8.jar`.
+This is the full application. You can use `texosquery` or
+`texosquery-jre5` as well, but there's less locale support with them.
+The `texosquery-jre8` bash script and `texosquery-jre8.bat` batch script invokes Java with
+`-Djava.locale.providers=CLDR,JRE`.
+
+If Windows users have simply been supplied with an executable versions
+of the `texosquery-jre8.jar` file (`texosquery-jre8.exe`) then you'll have to set the
+`JAVA_TOOL_OPTIONS` environment variable instead.
+
+This `java.locale.providers` setting allows Java to access locale
+information from the [Unicode Common Locale Data Repository
+(CLDR)](http://cldr.unicode.org/) installed on their system. The
+pending Java 9 should include this by default, so this will only be
+relevant to Java 8. Earlier versions of Java (7 or below) don't have
+this option, which limits the locale support to that which is
+natively provided by the JRE. Note that Java 7 and earlier versions
+[have reached their end of life](http://www.oracle.com/technetwork/java/eol-135779.html) and are now **deprecated**.
+
+If the version information starts with `1.7` ("Java 7"), then you can use
+`texosquery.jar`. This is the default application and provides most
+of the functions of the full application, but there's less locale support.
+You can also use the even more limited `texosquery-jre5`, but you can't use
+`texosquery-jre8`, so you can't take advantage of the CLDR.
+
+If the version information starts with `1.5` ("Java 5") or `1.6`
+("Java 6"), then you can _only_ use `texosquery-jre5`. The locale
+support is significantly reduced in this case and there's no support
+for language scripts.
+
+Once you have determined which application you want to use, edit the
+`texosquery.cfg` so that `\TeXOSInvokerName` is defined to the appropriate invocation. For example, with Java 8:
+```tex
+\def\TeXOSInvokerName{texosquery-jre8}
+```
+or with Java 5 or 6:
+```tex
+\def\TeXOSInvokerName{texosquery-jre5}
+```
+(bash users will have to add the `.sh` extension if it hasn't
+been removed, as per the above instructions.)
+
+## Examples:
+
+Plain TeX:
+
+```tex
+% arara: pdftex: {shell: on}
+\input texosquery
+
+\TeXOSQuery{\result}{-b}
+IEFT BCP 47 language tag: \result.
+
+\TeXOSQueryLocale{\result}
+POSIX locale: \result.
+
+\TeXOSQueryCwd{\result}
+cwd: {\tt \result}.
+
+\TeXOSQueryNow{\result}
+now: \result.
+
+\TeXOSQueryFileDate{\result}{\jobname.tex}
+file date: \result.
+
+\TeXOSQueryFileSize{\result}{\jobname.tex}
+file size: \result bytes.
+
+\bye
+```
+
+LaTeX:
+
+```latex
+% arara: pdflatex: {shell: on}
+\documentclass{article}
+
+\usepackage{texosquery}
+\usepackage{etoolbox}
+
+\begin{document}
+
+\TeXOSQuery{\result}{-b}
+IEFT BCP 47 language tag: \result.
+
+\TeXOSQueryLocale{\result}
+POSIX locale: \result.
+
+\TeXOSQueryCwd{\result}
+cwd: \texttt{\result}.
+
+\TeXOSQueryNow{\result}
+now: \result.
+
+\TeXOSQueryFileDate{\result}{\jobname.tex}
+file date: \result.
+
+\TeXOSQueryFileSize{\result}{\jobname.tex}
+file size: \result bytes.
+
+\TeXOSQueryFilterFileList{\result}{,}{.+\string\.(png|jpg)}{.}
+All jpg and png files in current directory:
+
+\renewcommand{\do}[1]{\texttt{#1}.\par}
+\expandafter\docsvlist\expandafter{\result}
+
+\end{document}
+```
+
+For a full list of available commands, see the documentation
+(`texosquery.pdf`).
+
+## Troubleshooting
+
+If something goes wrong with the call to `texosquery`, the control
+sequence will be set to empty. If this happens, here are the steps
+to diagnose the problem:
+
+ 1. Check the log file for any lines starting with `TeXOSQuery:`
+ For example: `TeXOSQuery: texosquery-jre8 --pdfnow`
+ If found, this means that the dry run mode was on and the shell
+ escape wasn't used. Ensure that the shell escape is
+ enabled when you build the document.
+ 2. If the log file contains `(|texosquery` _options_`)` then the
+ shell escape was used but `texosquery` returned an empty value.
+ In this case, copy the part between `(|` and `)` and paste it
+ into a command prompt or terminal but insert `--debug` at the
+ start of the options list. For example, if the log file
+ contains `(|texosquery-jre8 --cwd)` then run
+```sh
+texosquery-jre8 --debug --cwd
+```
+
+This should now display an error message explaining the
+problem. (For example, read access forbidden or file not found
+or a security exception.)
+
+## Security
+
+As from version 1.2, all variants of `texosquery` (JRE5, 7 and 8)
+obey TeX Live's `openin_any` setting. Any of the actions that involve
+reading file information won't work if read access is forbidden by
+`openin_any` or by the operating system. MiKTeX doesn't use the
+`openin_any` setting, so if not set `texosquery` will assume `a`
+(any).
+
+In addition to obeying `openin_any`, the file listing actions (such
+as `--list`) for the JRE7 and 8 variants also prohibit listing the
+contents outside of the current working directory's path. This means
+that you can't, for example, list the contents of `..` (the current
+working directory's parent) nor can you try walking the entire file
+system. The `--walk` action additionally won't descend hidden
+directories. This extra restriction is designed to prevent malicious
+code from trying to use `texosquery` to look around your filing
+system.
+
+The Java 5 version `texosquery-jre5` is the least secure and doesn't
+have this additional restriction on the file listing actions. However,
+it still obeys `openin_any`. The `--walk` action is not available
+with `texosquery-jre5`.
+
+Examples:
+```bash
+texosquery-jre8 --debug --walk ',' '.*' /
+```
+This action is forbidden:
+```
+texosquery-jre8: Can't walk directory: /
+```
+Changing `/` to `.` is allowed, but not for `texosquery-jre5`:
+```bash
+texosquery-jre5 --debug --walk ',' '.*' .
+```
+returns:
+```
+texosquery-jre5: walk requires at least JRE 7 version
+```
+With `openin_any=a`, the `--userhome` action is usually allowed
+(depends on the operating system and Java's security manager).
+```bash
+texosquery-jre8 --debug --userhome
+```
+returns
+```
+\fslh home\fslh nlct
+```
+(which `\TeXOSQuery` converts to `/home/nlct`.)
+
+However, unless this also happens to be the current working
+directory, it's not possible to obtain a file listing:
+```bash
+texosquery-jre8 --debug --list ',' /home/nlct
+```
+returns
+```
+texosquery-jre8: Unable to list contents of: /home/nlct
+texosquery-jre8: Listing outside cwd path not permitted: /home/nlct
+```
+
+## Source code
+
+The Java source is in the `.java` files and the manifest for each
+`.jar` file is `Manifest*.txt` (`Manifest-jre8.txt` for `texosquery-jre8` etc).
+Assuming the following directory structure:
+```
+java/TeXOSQuery.java
+java/TeXOSQueryJRE5.java
+java/TeXOSQueryJRE7.java
+java/TeXOSQueryJRE8.java
+java/QueryAction.java
+java/QueryActionType.java
+java/FileSortType.java
+java/FileSortComparator.java
+java/FileListType.java
+java/FileWalkVisitor.java
+java/Manifest-jre5.txt
+java/Manifest-jre7.txt
+java/Manifest-jre8.txt
+classes/com/dickimawbooks/texosquery/
+```
+Then to create `texosquery-jre8.jar`, do (for JDK version 1.8):
+```bash
+cd java
+javac -d ../classes TeXOSQuery.java QueryAction.java QueryActionType.java TeXOSQueryJRE8.java FileSortType.java FileSortComparator.java FileListType.java FileWalkVisitor.java
+cd ../classes
+jar cmf ../java/Manifest-jre8.txt ../texosquery-jre8.jar com/dickimawbooks/texosquery/*.class
+```
+
+Similarly for the other `.jar` files, replacing `8` with `7` or `5`.
+(The Java 7 version should really be `texosquery-jre7.jar`, but is
+simply named `texosquery.jar` in the distribution for backward compatibility reasons. If you compile the code, the `.jar` name is your choice.)
+
+---
+
+Source on GitHub: https://github.com/nlct/texosquery
+
+Author Home Page: http://www.dickimaw-books.com/
+
+License: LPPL 1.3+