summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-03-24 22:42:34 +0000
committerKarl Berry <karl@freefriends.org>2017-03-24 22:42:34 +0000
commit290d4ccb69531961a454b334f0ede186ebe88396 (patch)
tree83d0719b94664b447a639185536560c09b28b42b /Master/texmf-dist/doc/support
parentae2003403c75fd90aa7273314aad1b78c1feec89 (diff)
texosquery (24mar17)
git-svn-id: svn://tug.org/texlive/trunk@43596 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/texosquery/CHANGES106
-rw-r--r--Master/texmf-dist/doc/support/texosquery/Manifest.txt2
-rw-r--r--Master/texmf-dist/doc/support/texosquery/README.md233
-rw-r--r--Master/texmf-dist/doc/support/texosquery/texosquery.pdfbin251370 -> 488948 bytes
4 files changed, 286 insertions, 55 deletions
diff --git a/Master/texmf-dist/doc/support/texosquery/CHANGES b/Master/texmf-dist/doc/support/texosquery/CHANGES
index 86ae40b460c..ba18c85d3d5 100644
--- a/Master/texmf-dist/doc/support/texosquery/CHANGES
+++ b/Master/texmf-dist/doc/support/texosquery/CHANGES
@@ -1,3 +1,109 @@
+1.2 (2017/03/23):
+
+ * Now has three .jar files depending on the Java installation:
+
+ - texosquery-jre8.jar
+
+ Full application. May be used with the CLDR locale provider
+ (Unicode Consortium's Common Locale Data Repository).
+ Requires at least Java 8 (use with
+ java -Djava.locale.providers=CLDR,JRE or
+ add "java.locale.providers=CLDR,JRE" to the
+ JAVA_TOOLS_OPTIONS environment variable to access the CLDR)
+
+ - texosquery.jar
+
+ The default version of the application. Can't be used with
+ CLDR. Less locale support. Requires at least Java 7.
+
+ - texosquery-jre5.jar
+
+ Cut-down version of the application with significantly less
+ locale support. Provided for old systems that can't upgrade,
+ but not recommended. (Use of Java 5 or 6 is deprecated.)
+ Requires at least Java 5.
+
+ * Corresponding scripts that run the appropriate .jar file
+ are bundled in texosquery.dtx and extracted using:
+
+ tex texosquery.ins
+
+ - Unix-like (run `chmod +x texosquery*.sh`):
+
+ texosquery-jre8.sh : runs texosquery-jre8.jar with
+ -Djava.locale.providers=CLDR,JRE
+
+ texosquery.sh : runs texosquery.jar
+
+ texosquery-jre5.sh : runs texosquery-jre5.jar
+
+ (I recommend the removal of the '.sh' extension
+ for more convenient invocation.)
+
+ - Windows (rename texosquery*.batch to texosquery*.bat):
+
+ texosquery-jre8.bat : runs texosquery-jre8.jar with
+ -Djava.locale.providers=CLDR,JRE
+
+ texosquery.bat : runs texosquery.jar
+
+ texosquery-jre5.bat : runs texosquery-jre5.jar
+
+ You can edit these files if additional Java settings
+ are required (e.g. -Dfile.encoding=UTF-8). Alternatively
+ set the JAVA_TOOLS_OPTIONS environment variable.
+
+ * New texosquery.cfg configuration file. Edit the definition
+ of \TeXOSInvokerName to indicate which application you
+ need to use. For example, if Java 8 is installed:
+
+ \def\TeXOSInvokerName{texosquery-jre8}
+
+ See the installation section of the manual.
+
+ * New command line switches:
+
+ Actions:
+
+ --bcp47 / -b
+ --codeset-lcs / -C
+ --locale-data / -D
+ --numeric / -N
+ --date-time / -M
+ --time-zones / -Z
+ --list-dir / -ld
+ --list-regular / -lr
+ --filterlist-dir / -fd
+ --filterlist-regular / -fr
+ --walk / -w
+
+ Options:
+
+ --debug [⟨n⟩]
+ --nodebug
+ --compatible ⟨n⟩ / -compat ⟨n⟩
+
+ * Actions --list (-i) and --filterlist (-f) now have an
+ optional argument to indicate the sort order.
+
+ * When accessing file information, the TEXMF openin_any
+ setting is first checked to determine if read access is
+ permitted.
+
+ * Returned values now include some shorthand markup that's
+ internally converted when read in by \TeXOSQuery. For
+ example "texosquery -n" now returns
+
+ \pdfd \fcln 20161113161156\fpls 00\fcsq 00\fcsq
+
+ instead of
+
+ D:20161113161156+00'00'
+
+ To restore the original behaviour use --compatible 1
+
+ See the manual for further details.
+
1.1 (2016-07-14):
* texosquery.jar:
diff --git a/Master/texmf-dist/doc/support/texosquery/Manifest.txt b/Master/texmf-dist/doc/support/texosquery/Manifest.txt
deleted file mode 100644
index 92d656204b2..00000000000
--- a/Master/texmf-dist/doc/support/texosquery/Manifest.txt
+++ /dev/null
@@ -1,2 +0,0 @@
-Main-Class: com/dickimawbooks/texosquery/TeXOSQuery
-Class-Path: .
diff --git a/Master/texmf-dist/doc/support/texosquery/README.md b/Master/texmf-dist/doc/support/texosquery/README.md
index 49b390d55a3..bad3733503a 100644
--- a/Master/texmf-dist/doc/support/texosquery/README.md
+++ b/Master/texmf-dist/doc/support/texosquery/README.md
@@ -4,7 +4,8 @@ TeX's shell escape mechanism.
The application can query the following:
- - locale and codeset
+ - locale information
+ - default file encoding
- current working directory
- user home directory
- temporary directory
@@ -24,42 +25,162 @@ The application can query the following:
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 TeX documents:
+There are files provided for easy access in (La)TeX documents:
- `texosquery.tex` : generic TeX code
- `texosquery.sty` : LaTeX package
-This provides commands 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.
+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`.
## Installation
-The actual Java application is in `texosquery.jar`.
-The `.tex` and `.sty` files can be extracted from `texosquery.dtx`
-using `tex texosquery.ins`. In the following, replace TEXMF with the
-path to your TEXMF directory.
-
- - Move `texosquery.tex` to `TEXMF/tex/generic/texosquery/`
- - Move `texosquery.sty` to `TEXMF/tex/latex/texosquery/`
- - Move `texosquery.pdf` to `TEXMF/doc/generic/texosquery/`
- - Move `texosquery.jar` to `TEXMF/scripts/texosquery/`
-
-Unix-like users: move the bash script `texosquery` to somewhere on
-your path.
-
-Windows users: TeX Live's generic wrapper should be able to locate
-the `texosquery.jar` file, but if not or you're not using TL,
-then (untested) create a file called `texosquery.bat` that contains:
-```dos
-@ECHO OFF
-FOR /F %%I IN ('kpsewhich --progname=texosquery --format=texmfscripts texosquery.jar') DO SET JARPATH=%%I
-START javaw -jar "%JARPATH%\texosquery.jar" %*
+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
```
-(or skip the `FOR` line and replace `%JARPATH%` with the full path name to
-`texosquery.jar`.) Put this file on your system's path.
+
+### 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)
+
+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.
+
+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. Note that these versions of Java are
+deprecated.
+
+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:
@@ -69,8 +190,11 @@ Plain TeX:
% arara: pdftex: {shell: on}
\input texosquery
+\TeXOSQuery{\result}{-b}
+IEFT BCP 47 language tag: \result.
+
\TeXOSQueryLocale{\result}
-locale: \result.
+POSIX locale: \result.
\TeXOSQueryCwd{\result}
cwd: {\tt \result}.
@@ -98,8 +222,11 @@ LaTeX:
\begin{document}
+\TeXOSQuery{\result}{-b}
+IEFT BCP 47 language tag: \result.
+
\TeXOSQueryLocale{\result}
-locale: \result.
+POSIX locale: \result.
\TeXOSQueryCwd{\result}
cwd: \texttt{\result}.
@@ -125,39 +252,39 @@ All jpg and png files in current directory:
For a full list of available commands, see the documentation
(`texosquery.pdf`).
-You can omit `texosquery.tex` and directly use `texosquery`
-in TeX's shell escape, but take care of special characters
-occurring in the result or if double-quotes occur in
-`\jobname`.
-
## Source code
-The `.tex` and `.sty` files and documentation are contained in
-`texosquery.dtx`. To compile the documentation:
-```bash
-pdflatex texosquery.dtx
-makeindex -s gglo.ist -t texosquery.glg -o texosquery.gls texosquery.glo
-makeindex -s gind.ist texosquery.idx
-pdflatex texosquery.dtx
-pdflatex texosquery.dtx
-```
-
-The Java source is in `TeXOSQuery.java` and the manifest for the
-`.jar` file is `Manifest.txt`. Assuming the following directory
-structure:
+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/Manifest.txt
+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.jar`, do:
+Then to create `texosquery-jre8.jar`, do (for JDK version 1.8):
```bash
cd java
-javac -d ../classes TeXOSQuery.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.txt ../texosquery.jar com/dickimawbooks/texosquery/*.class
+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
diff --git a/Master/texmf-dist/doc/support/texosquery/texosquery.pdf b/Master/texmf-dist/doc/support/texosquery/texosquery.pdf
index 7471094188a..a1b3862d24f 100644
--- a/Master/texmf-dist/doc/support/texosquery/texosquery.pdf
+++ b/Master/texmf-dist/doc/support/texosquery/texosquery.pdf
Binary files differ