Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/phfaist/ltxpdflinks

Extract links in PDF graphics for inclusion in LaTeX documents
https://github.com/phfaist/ltxpdflinks

Last synced: about 2 months ago
JSON representation

Extract links in PDF graphics for inclusion in LaTeX documents

Awesome Lists containing this project

README 

        
ltxpdflinks — include PDF graphics with links in LaTeX documents  

================================================================



To include fancy graphics (say a diagram) in your LaTeX document, a common

process is to design the diagram using your favorite graphics designer program,

to export the figure as a PDF graphic, and to use::



  \includegraphics[width=10cm]{my_figure}



And it works great.  Until you'd like to have figures with clickable links.  You

might even want to have links in your diagram to within the document—maybe a

clickable link to a document section, equation, or an item in your bibliography.



The ``ltxpdflinks`` tool provides a simple solution to include a PDF with its

links.  It includes ways to encode links to within the document, like you'd

obtain with ``\ref`` and ``\cite`` in LaTeX.



Quick Start

~~~~~~~~~~~



To get started:



1. Install ``ltxpdflinks``::



     pip3 install ltxpdflinks



2. Download the ``phflplx.sty`` file here:

   

   https://github.com/phfaist/ltxpdflinks/releases/latest



To compile your document:



1. Drop the file ``phflplx.sty`` in the same folder as your latex source file,

   and add to your document preamble::



     \usepackage{phflplx}

     \DeclareGraphicsExtensions{.lplx,.pdf}



   [I'm assuming you're loading the ``graphicx`` (or alternatively

   ``graphics``) and the ``hyperref`` packages, too.]



   Note: If you'd like to include also other file types in your document

   (e.g., ``.png``, ``.jpeg``, etc.), you need to add them to the

   ``\DeclareGraphicsExtensions`` argument, too.  See doc for the

   `graphicx package `_.



2. Run the ``ltxpdflinks`` command-line program for all your PDF files that

   contain links::



     > ltxpdflinks myfigure1.pdf



3. Compile your LaTeX document as usual.



How to include links to other parts of the LaTeX document:



1. When creating your figure in your favorite drawing software, create a "web

   hyperlink" with an URL of the following form::



     latexref:///



   For a link to a section, equation, etc. (when you'd use ``\ref`` /

   ``\autoref`` / ``\cref`` in LaTeX), use ``latexref://ref/``

   where you replace ```` by the LaTeX label of the object you're

   referencing (the argument of the ``\label{...}`` command in LaTeX).



   For a link to a bibliographic reference entry (as in ``\cite{...}``), use

   ``latexref://cite/``, where you replace ```` by the

   bibliographic reference key you'd like to refer to (the argument you'd use to

   the ``\cite{...}`` command).



2. These special URL links are automatically converted to LaTeX references by

   the ``ltxpdflinks`` utility and the ``phflplx`` package.



Features

~~~~~~~~



- Special link conversions::



    latexref://ref/XXXXXX   →   link to XXXXXX label as via \ref{XXXXXX}

    

    latexref://cite/XXXXXX   →   link to XXXXXX citation as via \cite{XXXXXX}



  (In the future I'll probably add ways to plug in custom link conversions.  The

  code is extendible & you can add them yourself already if you invoke

  ``ltxpdflinks`` via your own python script.)



- Full support for rotation, scaling and clipping via options to

  ``\includegraphics[...]{...}``



- Links use the format defined in the LaTeX document (colors & border relevant

  for link type URL/internal reference/citation as specified via the

  ``hyperref`` package.)



- Simple Python implementation which you can use via your own custom script if

  you'd like to add link conversions or customize the process in any way.



  To get started::



    import ltxpdflinks



    extractor = ltxpdflinks.PdfGraphicLinksExtractor(fname)

    extracted = extractor.extractGraphicLinks()



    converter = ltxpdflinks.LatexRefsLinkConverter()

    converter.convertLinks(extracted)



    lplxexporter = ltxpdflinks.LplxPictureEnvExporter()

    lplx_content = lplxexporter.export(extracted)



    with open('my_ouput_file_will_be_overwritten.lplx', 'w') as foutput:

        foutput.write(lplx_content)



Planned future improvements

~~~~~~~~~~~~~~~~~~~~~~~~~~~



- Support the possibility (as an opt-in option) to preserve link styling

  (border, color, etc.)  instead if using the document links style?



- Support for internal annotations within the PDF graphic (from one part of

  the graphic to another)?



- Support for other types of annotations?



- Support for generation of ``.pax`` files for use with the `pax LaTeX package

  `_ instead?



Existing alternatives

~~~~~~~~~~~~~~~~~~~~~



- You can also directly create your diagrams natively in LaTeX using `TiKZ

  `_.  I prefer to prepare

  diagrams with drawing software, but that's a personal preference.

    

- The `pax LaTeX package and associated utility `_

  also includes PDF links and annotations using a similar philosophy; it also

  provides a separate command-line tool to process PDF files before inclusion.



  As far as I could tell, `pax` supports more PDF annotations and preserves link

  styles.  It doesn't seem to provide link conversion to LaTeX references and

  citations for internal links.  It also doesn't seem to fully support rotation

  and clipping via options to ``\includegraphics``.  The command-line utility is

  written in Java.



  This option has been around for a while, so it might definitely be more

  stable!