diff options
Diffstat (limited to 'Master/texmf-dist/source/support/texosquery/texosquery.dtx')
-rw-r--r-- | Master/texmf-dist/source/support/texosquery/texosquery.dtx | 161 |
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} |