summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-07-08 21:46:04 +0000
committerKarl Berry <karl@freefriends.org>2016-07-08 21:46:04 +0000
commit355a127454c52c9b592631e0b60a1e7d567960de (patch)
treea4203d9a4e308758f7315be87b28053da7df9f55 /Master/texmf-dist/doc/support
parent625406d67c04aff1f4f94c6120aa8d14b2252708 (diff)
texosquery (8jul16)
git-svn-id: svn://tug.org/texlive/trunk@41663 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/texosquery/Manifest.txt2
-rw-r--r--Master/texmf-dist/doc/support/texosquery/README.md167
-rw-r--r--Master/texmf-dist/doc/support/texosquery/texosquery.pdfbin0 -> 247702 bytes
-rw-r--r--Master/texmf-dist/doc/support/texosquery/texosquery.tex138
4 files changed, 307 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/texosquery/Manifest.txt b/Master/texmf-dist/doc/support/texosquery/Manifest.txt
new file mode 100644
index 00000000000..92d656204b2
--- /dev/null
+++ b/Master/texmf-dist/doc/support/texosquery/Manifest.txt
@@ -0,0 +1,2 @@
+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
new file mode 100644
index 00000000000..49b390d55a3
--- /dev/null
+++ b/Master/texmf-dist/doc/support/texosquery/README.md
@@ -0,0 +1,167 @@
+# 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 and codeset
+ - 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 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.
+
+## 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" %*
+```
+(or skip the `FOR` line and replace `%JARPATH%` with the full path name to
+`texosquery.jar`.) Put this file on your system's path.
+
+## Examples:
+
+Plain TeX:
+
+```tex
+% arara: pdftex: {shell: on}
+\input texosquery
+
+\TeXOSQueryLocale{\result}
+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}
+
+\TeXOSQueryLocale{\result}
+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`).
+
+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:
+```
+java/TeXOSQuery.java
+java/Manifest.txt
+classes/com/dickimawbooks/texosquery/
+```
+Then to create `texosquery.jar`, do:
+```bash
+cd java
+javac -d ../classes TeXOSQuery.java
+cd ../classes
+jar cmf ../java/Manifest.txt ../texosquery.jar com/dickimawbooks/texosquery/*.class
+```
+
+---
+
+Source on GitHub: https://github.com/nlct/texosquery
+
+Author Home Page: http://www.dickimaw-books.com/
+
+License: LPPL 1.3+
diff --git a/Master/texmf-dist/doc/support/texosquery/texosquery.pdf b/Master/texmf-dist/doc/support/texosquery/texosquery.pdf
new file mode 100644
index 00000000000..49c5401edbe
--- /dev/null
+++ b/Master/texmf-dist/doc/support/texosquery/texosquery.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/texosquery/texosquery.tex b/Master/texmf-dist/doc/support/texosquery/texosquery.tex
new file mode 100644
index 00000000000..b95300ac20d
--- /dev/null
+++ b/Master/texmf-dist/doc/support/texosquery/texosquery.tex
@@ -0,0 +1,138 @@
+%%
+%% This is file `texosquery.tex',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% texosquery.dtx (with options: `texosquery.tex,package')
+%%
+%% texosquery
+%% Copyright 2016 Nicola Talbot
+%%
+%% This work may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.3
+%% of this license of (at your option) any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% and version 1.3 or later is part of all distributions of LaTeX
+%% version 2005/12/01 or later.
+%%
+%% This work has the LPPL maintenance status `maintained'.
+%%
+%% The Current Maintainer of this work is Nicola Talbot.
+%%
+%% This work consists of the files texosquery.dtx and texosquery.ins
+%% and the derived files texosquery.sty, texosquery.tex.
+%% Additionally, the Java application texosquery.jar and bash script
+%% texosquery
+%% \CharacterTable
+%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%% Digits \0\1\2\3\4\5\6\7\8\9
+%% Exclamation \! Double quote \" Hash (number) \#
+%% Dollar \$ Percent \% Ampersand \&
+%% Acute accent \' Left paren \( Right paren \)
+%% Asterisk \* Plus \+ Comma \,
+%% Minus \- Point \. Solidus \/
+%% Colon \: Semicolon \; Less than \<
+%% Equals \= Greater than \> Question mark \?
+%% Commercial at \@ Left bracket \[ Backslash \\
+%% Right bracket \] Circumflex \^ Underscore \_
+%% Grave accent \` Left brace \{ Vertical bar \|
+%% Right brace \} Tilde \~}
+\ifnum\catcode`\@=11\relax
+ \def\@texosquery@restore@at{}%
+\else
+ \expandafter\edef\csname @texosquery@restore@at\endcsname{%
+ \noexpand\catcode`\noexpand\@=\number\catcode`\@\relax
+ }%
+ \catcode`\@=11\relax
+\fi
+\ifx\TeXOSQuery\undefined
+\else
+ \@texosquery@restore@at
+ \expandafter\endinput
+\fi
+\def\TeXOSInvokerName{texosquery}
+\ifx\@@input\undefined
+ \def\TeXOSQueryInvoker#1{\input|"\TeXOSInvokerName\space#1" }
+\else
+ \def\TeXOSQueryInvoker#1{\@@input|"\TeXOSInvokerName\space#1" }
+\fi
+\newif\ifTeXOSQueryDryRun
+\TeXOSQueryDryRunfalse
+\ifx\shellescape\undefined
+ \ifx\pdfshellescape\undefined
+ \else
+ \ifnum\pdfshellescape=0\relax
+ \TeXOSQueryDryRuntrue
+ \fi
+ \fi
+\else
+ \ifnum\shellescape=0\relax
+ \TeXOSQueryDryRuntrue
+ \fi
+\fi
+\def\TeXOSQuery#1#2{%
+ \ifTeXOSQueryDryRun
+ \begingroup
+ \newlinechar=`\^^J
+ \message{^^JTeXOSQuery: \TeXOSInvokerName\space#2^^J}%
+ \endgroup
+ \def#1{}%
+ \else
+ \begingroup
+ \endlinechar=-1\relax
+ \catcode`\-=12\relax
+ \catcode`\_=12\relax
+ \catcode`\^=12\relax
+ \catcode`\~=12\relax
+ \catcode`\$=12\relax
+ \catcode`\&=12\relax
+ \catcode`\"=12\relax
+ \catcode`\'=12\relax
+ \catcode`\.=12\relax
+ \catcode`\/=12\relax
+ \catcode`\:=12\relax
+ \catcode`\;=12\relax
+ \catcode`\%=12\relax
+ \everyeof{\noexpand}\relax
+ \edef\x{\endgroup\def\noexpand#1{\TeXOSQueryInvoker{#2}}}\x
+ \fi
+}
+\def\TeXOSQueryLocale#1{\TeXOSQuery{#1}{\string-l}}
+\def\TeXOSQueryCwd#1{\TeXOSQuery{#1}{\string-c}}
+\def\TeXOSQueryHome#1{\TeXOSQuery{#1}{\string-m}}
+\def\TeXOSQueryTmpDir#1{\TeXOSQuery{#1}{\string-t}}
+\def\TeXOSQueryVersion#1{\TeXOSQuery{#1}{\string-r}}
+\def\TeXOSQueryArch#1{\TeXOSQuery{#1}{\string-a}}
+\def\TeXOSQueryName#1{\TeXOSQuery{#1}{\string-o}}
+\def\TeXOSQueryNow#1{\TeXOSQuery{#1}{\string-n}}
+\def\texosquerystripquotes#1{%
+ \@texosquery@stripquotes#1\@mid@texosquery@stripquotes
+ "\relax"\relax\@end@texosquery@stripquotes
+}
+\def\@texosquery@stripquotes#1"#2"{%
+ \@@texosquery@stripquotes#1#2%
+}
+\def\@@texosquery@stripquotes#1\@mid@texosquery@stripquotes#2\@end@texosquery@stripquotes{%
+ #1%
+}
+\def\TeXOSQueryFileDate#1#2{\TeXOSQuery{#1}{\string-d
+ \string'\texosquerystripquotes{#2}\string'}}
+\def\TeXOSQueryFileSize#1#2{\TeXOSQuery{#1}{\string-s
+ \string'\texosquerystripquotes{#2}\string'}}
+\def\TeXOSQueryFileList#1#2#3{\TeXOSQuery{#1}{%
+ \string-i \string'#2\string'
+ \string'\texosquerystripquotes{#3}\string'}}
+\def\TeXOSQueryFilterFileList#1#2#3#4{\TeXOSQuery{#1}{%
+ \string-f \string'#2\string' \string'#3\string'
+ \string'\texosquerystripquotes{#4}\string'}}
+\def\TeXOSQueryFileURI#1#2{\TeXOSQuery{#1}{\string-u
+ \string'\texosquerystripquotes{#2}\string'}}
+\def\TeXOSQueryFilePath#1#2{\TeXOSQuery{#1}{\string-p
+ \string'\texosquerystripquotes{#2}\string'}}
+\@texosquery@restore@at
+\endinput
+%%
+%% End of file `texosquery.tex'.