summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/support/texosquery/texosquery.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/support/texosquery/texosquery.dtx')
-rw-r--r--Master/texmf-dist/source/support/texosquery/texosquery.dtx161
1 files changed, 137 insertions, 24 deletions
diff --git a/Master/texmf-dist/source/support/texosquery/texosquery.dtx b/Master/texmf-dist/source/support/texosquery/texosquery.dtx
index 35d3afc97cb..feda90f8680 100644
--- a/Master/texmf-dist/source/support/texosquery/texosquery.dtx
+++ b/Master/texmf-dist/source/support/texosquery/texosquery.dtx
@@ -30,7 +30,7 @@
\usepackage{metalogo}
\usepackage[colorlinks,hyperindex=false]{hyperref}
-\CheckSum{234}
+\CheckSum{269}
\RecordChanges
\PageIndex
@@ -61,8 +61,10 @@
%\DeleteShortVerb{|}
%
%\title{texosquery: query OS information from \TeX}
-%\author{Nicola L. C. Talbot\\\url{http://www.dickimaw-books.com/}}
-%\date{2016-07-08 (v1.0)}
+%\author{Nicola L. C. Talbot\\
+%\href{http://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}
+%\and Paulo Cereda}
+%\date{2016-07-14 (v1.1)}
%\maketitle
%
%\begin{abstract}
@@ -81,6 +83,10 @@
%installed to use \texttt{texosquery}.
%\end{important}
%
+%If you want to rebuild the application, instructions for
+%compiling the source code (including the code for this document)
+%are in the accompanying \texttt{README.md} file.
+%
%\tableofcontents
%
%\section{texosquery.jar: the Java application}
@@ -99,10 +105,11 @@
%
%Since the application is designed to work with \TeX, each
%function will display the result on a single line without
-%formatting. A blank line will be displayed if the information
-%isn't available. A forward slash is always used as a
-%directory divider, regardless of the operating system, so
-%the result can be used, for example, in \cs{input} or
+%formatting. (For multiple results, each line is grouped
+%from v1.1.) A blank line (or empty group) will be displayed
+%if the information isn't available. A forward slash is always
+%used as a directory divider, regardless of the operating
+%system, so the result can be used, for example, in \cs{input} or
%\cs{includegraphics}.
%
%If an input file name is required (for example, with the
@@ -193,8 +200,16 @@
%using the shell escape, you'll need to be careful of this.
%\item[\shortarg{p} \meta{file} or \longarg{path} \meta{file}]
%Displays the canonical path of the given file or a blank line if
-%the file doesn't exists or the file permissions prohibit this
+%the file doesn't exist or the file permissions prohibit this
%action.
+%\item[\shortarg{e} \meta{file} or \longarg{dirname} \meta{file}]
+%(New to v1.1.)
+%Displays the canonical path of the given file's parent (that is, the
+%directory containing \meta{file}) or a blank line if
+%the file doesn't exist or the file permissions prohibit this
+%action. Note that this is different to the Unix-like
+%\texttt{dirname} command, which will return a relative path if
+%\meta{file} isn't an absolute path.
%\item[\shortarg{h} or \longarg{help}] Displays help message and
%exits.
%\item[\shortarg{v} or \longarg{version}] Displays version
@@ -203,7 +218,41 @@
%
%If multiple options are given, they will be processed in the
%order specified in the command line invocation. Each result will
-%be displayed on a separate line.
+%be displayed on a separate line. As from v1.1, if there are
+%multiple actions, each result will be grouped. This makes it easier
+%to process the results in \TeX. For example:
+%\begin{verbatim}
+%texosquery -l
+%\end{verbatim}
+%This just produces (for me):
+%\begin{verbatim}
+%en-GB.utf8
+%\end{verbatim}
+%whereas
+%\begin{verbatim}
+%texosquery -l -n
+%\end{verbatim}
+%produces:
+%\begin{verbatim}
+%{en-GB.utf8}
+%{D:20160714112732+01'00'}
+%\end{verbatim}
+%Note that unavailable information will produce an empty group.
+%For example (assuming \texttt{nofile} doesn't exist):
+%\begin{verbatim}
+%texosquery -l -d nofile -n
+%\end{verbatim}
+%produces:
+%\begin{verbatim}
+%{en-GB.utf8}
+%{}
+%{D:20160714112732+01'00'}
+%\end{verbatim}
+%whereas
+%\begin{verbatim}
+%texosquery -d nofile
+%\end{verbatim}
+%just displays an empty line.
%
%\section{texosquery.tex: generic \TeX\ code}
%You can run \texttt{texosquery} directly from \TeX's shell escape.
@@ -247,8 +296,8 @@
%(\texttt{texosquery.jar} will replace \verb|#| with \verb|\#| in places
%where it might possibly occur in the result, but in general it's
%best to avoid these characters in file names.)
-%There are some short cut commands for convenience, described below.
%
+%There are some short cut commands for convenience, described below.
%If any of these commands cause an error message in the form:
%\begin{verbatim}
%I can't find file `|texosquery'.
@@ -280,8 +329,27 @@
%TeXOSQuery:
%\end{verbatim}
%(the control sequence \meta{cs} will be set to empty).
-%This conditional will automatically be switched on if
-%\cs{shellescape} or \cs{pdfshellescape} is 0.
+%This conditional will automatically be switched on unless
+%\cs{shellescape} or \cs{pdfshellescape} is 1. (If
+%\texttt{texosquery.jar} is later allowed on the restricted list,
+%newer versions may change this default.)
+%
+%If multiple queries are required, it's more efficient to
+%perform them all in one go. For example:
+%\begin{verbatim}
+%\TeXOSQuery{\result}{-l -n -o}
+%
+%\def\parseresult#1#2#3{%
+% Locale: #1. Now: #2. OS: #3.%
+%}
+%
+%\ifx\result\empty
+% Query failed.
+%\else
+% \expandafter\parseresult\result
+%\fi
+%\end{verbatim}
+%(Make sure you have at least v1.1 for this to work correctly.)
%
%The locale (\shortarg{l} or \longarg{locale-lcs}) information can be
%obtained using:
@@ -346,7 +414,9 @@
%\end{flushleft}
%This is provided for the benefit of users who don't have
%\cs{pdfcreationdate} defined by their \TeX\ format (for example,
-%\XeTeX).
+%\XeTeX). As from v1.1, this ensures that the initial \texttt{D} has
+%category code 12 (which won't happen if \cs{TeXOSQuery} is used
+%explicitly).
%
%\begin{important}
%The remaining commands all require extra arguments after the
@@ -373,7 +443,9 @@
%\end{flushleft}
%where \meta{filename} is the name of the file.
%This is provided for the benefit of users who don't have
-%\cs{pdffilemoddate} defined by their \TeX\ format.
+%\cs{pdffilemoddate} defined by their \TeX\ format. As from v1.1,
+%this ensures that the initial \texttt{D} has category code 12 (which
+%won't happen if \cs{TeXOSQuery} is used explicitly).
%
%The size in bytes of a file
%(\shortarg{s} or \longarg{filesize}) can be obtained using:
@@ -436,6 +508,14 @@
%\end{flushleft}
%where \meta{filename} is the name of the file.
%
+%The canonical path of a file's parent
+%(\shortarg{e} or \longarg{dirname}) can be obtained using:
+%\DescribeMacro\TeXOSQueryDirName
+%\begin{flushleft}\ttfamily
+%\cs{TeXOSQueryDirName}\marg{cs}\marg{filename}
+%\end{flushleft}
+%where \meta{filename} is the name of the file.
+%
%\StopEventually{\phantomsection
%\addcontentsline{toc}{section}{Change History}%
%\PrintChanges
@@ -491,24 +571,26 @@
%
%\begin{macro}{\ifTeXOSQueryDryRun}
%Provide a dry-run mode.
+%\changes{1.1}{2016-07-14}{dry run mode only false by default if with
+%unrestricted mode}
% \begin{macrocode}
\newif\ifTeXOSQueryDryRun
-\TeXOSQueryDryRunfalse
+\TeXOSQueryDryRuntrue
% \end{macrocode}
%\end{macro}
%
-%If shell escape is disabled, automatically switch on dry-run mode.
+%If shell escape is unrestricted, automatically switch off dry-run mode.
% \begin{macrocode}
\ifx\shellescape\undefined
\ifx\pdfshellescape\undefined
\else
- \ifnum\pdfshellescape=0\relax
- \TeXOSQueryDryRuntrue
+ \ifnum\pdfshellescape=1\relax
+ \TeXOSQueryDryRunfalse
\fi
\fi
\else
- \ifnum\shellescape=0\relax
- \TeXOSQueryDryRuntrue
+ \ifnum\shellescape=1\relax
+ \TeXOSQueryDryRunfalse
\fi
\fi
% \end{macrocode}
@@ -608,9 +690,24 @@
%\end{macro}
%
%\begin{macro}{\TeXOSQueryNow}
+%\changes{1.1}{2016-07-14}{changed catcode of D to 12}
%Query the current time stamp.
% \begin{macrocode}
-\def\TeXOSQueryNow#1{\TeXOSQuery{#1}{\string-n}}
+\def\TeXOSQueryNow#1{%
+% \end{macrocode}
+% The \texttt{D} needs category code 12. (Don't need to worry about
+% \texttt{Z} as \texttt{texosquery.jar} uses \texttt{+00'00'} for
+% UTC+0.) This change can't be done with the other catcode changes
+% in \cs{TeXOSQuery}, as this is only appropriate for the PDF dates.
+% Save and restore the catcode rather than fiddle around with
+% scoping.
+% \begin{macrocode}
+ \edef\@texosquery@restore@D{%
+ \noexpand\catcode`\noexpand\D=\the\catcode`\D\relax}%
+ \catcode`\D=12\relax
+ \TeXOSQuery{#1}{\string-n}%
+ \@texosquery@restore@D
+}
% \end{macrocode}
%\end{macro}
%
@@ -632,10 +729,16 @@
%\end{macro}
%
%\begin{macro}{\TeXOSQueryFileDate}
+%\changes{1.1}{2016-07-14}{changed catcode of D to 12}
%Query the time stamp of the file given in the second argument.
% \begin{macrocode}
-\def\TeXOSQueryFileDate#1#2{\TeXOSQuery{#1}{\string-d
- \string'\texosquerystripquotes{#2}\string'}}
+\def\TeXOSQueryFileDate#1#2{%
+ \edef\@texosquery@restore@D{%
+ \noexpand\catcode`\noexpand\D=\the\catcode`\D\relax}%
+ \catcode`\D=12\relax
+ \TeXOSQuery{#1}{\string-d \string'\texosquerystripquotes{#2}\string'}%
+ \@texosquery@restore@D
+}
% \end{macrocode}
%\end{macro}
%
@@ -685,6 +788,16 @@
% \end{macrocode}
%\end{macro}
%
+%\begin{macro}{\TeXOSQueryDirName}
+%\changes{1.1}{2016-07-14}{new}
+%Get the canonical path of the directory containing the file given
+%in the second argument.
+% \begin{macrocode}
+\def\TeXOSQueryDirName#1#2{\TeXOSQuery{#1}{\string-e
+ \string'\texosquerystripquotes{#2}\string'}}
+% \end{macrocode}
+%\end{macro}
+%
%All done.
%Restore the category code of \texttt{@}:
% \begin{macrocode}
@@ -708,7 +821,7 @@
%Identify package:
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{texosquery}[2016/07/08 v1.0 (NLCT)]
+\ProvidesPackage{texosquery}[2016/07/14 v1.1 (NLCT)]
% \end{macrocode}
%Load \texttt{texosquery.tex}:
% \begin{macrocode}