5

I want to have a link in my PDF generated by pdflatex which executes a shell script, and this part works great.

The problem I am running into is that I need the link in the PDF to be able to pass parameters to the shell script. I think has to do with escaping characters but I don't know how to resolve it.

Warnings

  • If you are not totally familiar with Unix shell scripts using the Terminal app, you may not want to run this. Not that I am aware of any dangers in running this as is, but just don't want to alarm anyone when the Termimal app launches.
  • Depending on your Preferences for Terminal you may need to close the Terminal window that launches.
  • Executing the script (by clicking on the links in the output PDF) will overwrite ~/TempFile.txt even though I have specified /tmp/TempFile.txt. Not sure why this is the case.
  • The MyScript.command file will get created in the directory where you run pdflatex, so you may need to manually delete it once done with this test case.

To run MWE:

To be able to use this MWE on Mac OS (can't comment on other platforms):

  1. pdflatex the MWE
  2. Locate the file MyScript.command in Finder and select File/Get Info and make sure it is set to open with Terminal.app. This did not seem necessary for me once I changed the file name extension from .sh to .command, but am documenting it here in case some one else has different settings or wants to use a different file extension.
  3. Then go back to the PDF generated by the MWE and try clicking on the links.

The PDF generated looks like:

enter image description here

Clicking on the first link will open up the file TempFile.txt containing:

Start of additional parameters

End of additional parameters

Clicking on the second link should produce (once it works):

Start of additional parameters
xyz
abc
End of additional parameters

Notes:

  • At this time, I am only interested in MacOS, but non-Mac solutions are welcome in case others want to do something like this, or I need to get this working on Windows at some other time.

References:

MWE

\documentclass{article}
\usepackage[colorlinks=true]{hyperref}

%\usepackage{filecontents}% Commented to prevent overwriting files


\newcommand{\TempFile}{/tmp/TempFile.txt}%
\newcommand{\MyExecutableScript}{MyScript.command}%
\newcommand*{\MyExecutableScriptRunTimeParameters}{abc xyz}%


\begin{filecontents}{\MyExecutableScript}
    #!/bin/bash
    echo "Start of additional parameters"  > \TempFile
    echo $2 >> \TempFile
    echo $1 >> \TempFile
    echo "End of additional parameters"  >> \TempFile
    open \TempFile
    exit 0
\end{filecontents}


\begin{document}
\immediate\write18{chmod +x \MyExecutableScript}%   make file executable


\href{run:\MyExecutableScript}{Click to execute \MyExecutableScript}% <-- This works


\href{run:\MyExecutableScript\space \MyExecutableScriptRunTimeParameters}%
        {Click to execute \MyExecutableScript\space with parameters}% <-- This not so much :-(


\end{document}
Community
  • 1
Peter Grill
  • 223,288

1 Answers1

3

According to the PDF specification for PDF 1.7 (ISO 32000-1:2008), you are out of luck. The action dictionary for Launch actions defines the following keys for options:

Win dictionary (Optional) A dictionary containing Windows-specific launch parameters (see Table 204).
Mac (undefined) (Optional) Mac OS-specific launch parameters; not yet defined.
Unix (undefined) (Optional) UNIX-specific launch parameters; not yet defined.

For Windows, the parameters can be specified after # in the launch specification of \href:

\href{run:\MyExecutableScript#\MyExecutableScriptRunTimeParameters}{...}

A clumsy workaround for the other operating systems would be to encode the parameters in the script name and the script looks for its name and decodes the arguments. An example, where I have implemented this way, can be seen in project vpe.

Heiko Oberdiek
  • 271,626
  • Ok, thanks. Seems as if encoding the parameters in the script name means that I need a separate script for each case. I just need the script to be able to detect which file invoked it. My current plan for a workaround is to have each file execute its own script that gets created by pdflatex, and that script will invoke the main script with the appropriate parameters, which I guess is similar to what you suggested. Thanks again Heiko. – Peter Grill May 15 '15 at 17:07
  • Whow. I want to do exaclty what vpe offers. Maybe you can tell me if it is possible with vpe: I have Markdown files *.md (my "source files") which I process with a python to LaTeX *.tex. That I process with latex, dvi2ps and ps2pdf. hyperrref with \href{run:/usr/bin/emacsclient +22 /path/to/text.md} does not seem to work with evince or acroread. Can vpe help me somehow? My python script could emit tex-help-commands... – towi Dec 03 '16 at 20:14
  • Options for launch actions are not supported in the case of Unix. vpe is just a workaround, which uses the parameters encoded in the script name. Maybe you want take a look at SyncTeX. It is AFAIK supported by evince (but not acroread). – Heiko Oberdiek Dec 06 '16 at 17:03
  • @PeterGrill You don't need a separate script. You just create symbolic links with the relevant names to a single script. At least, that is how these things usually work. I don't know about doing it from PDF, but I assume it would work the same as it is just passing off to the shell, I guess. – cfr May 19 '17 at 22:46
  • @cfr: Yep, that makes sense. But, this still necessites a file for each link, which for me is equivalent since my scripts are auto-generated. – Peter Grill May 19 '17 at 23:44
  • @PeterGrill In the sense that a link is a file, of course. Fewer bytes, though. But yes, it is more important when maintaining them manually, of course, since you don't have to worry about keeping them in sync. – cfr May 19 '17 at 23:51
  • 1
    A comment some years later. There's always the option of writing the argument to some predefined file, then let the script read from that file. Of course the requirement is that the script is written by you. – user202729 Jul 04 '22 at 17:12