diff options
author | Karl Berry <karl@freefriends.org> | 2017-03-24 22:42:34 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-03-24 22:42:34 +0000 |
commit | 290d4ccb69531961a454b334f0ede186ebe88396 (patch) | |
tree | 83d0719b94664b447a639185536560c09b28b42b /Master/texmf-dist/doc/support | |
parent | ae2003403c75fd90aa7273314aad1b78c1feec89 (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/CHANGES | 106 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/texosquery/Manifest.txt | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/texosquery/README.md | 233 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/texosquery/texosquery.pdf | bin | 251370 -> 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 Binary files differindex 7471094188a..a1b3862d24f 100644 --- a/Master/texmf-dist/doc/support/texosquery/texosquery.pdf +++ b/Master/texmf-dist/doc/support/texosquery/texosquery.pdf |