/ 
App-PDF-Link-0.25
River stage zero No dependents
/ App::PDF::Link

NAME

pdflink - insert document links in PDF

SYNOPSIS

pdflink [options] pdf-file [csv-file]

pdflink [options] --targets=file1;file2 pdf-file [pdf-file ...]

Inserts document links in PDF

Options:
   --output=XXX	name of the new PDF (default __new__.pdf)
   --embed		embed the data files instead of linking
   --attach		attach the data files instead of linking
   --xpos=NN		X-position for links
   --ypos=NN		Y-position for links relative to top
   --iconsize=NN	size of the icons, default 50
   --icons=type=XXX	add icon image XXX for this type
   --padding=NN	padding between icons, default 0
   --vertical		stacks icons vertically
   --border		draws a border around the links
   --gfunder		draws the images behind the page
   --targets=XXX	specifies the target(s) to link to
   --ident		shows identification
   --help		shows a brief help message and exits
   --man               shows full documentation and exits
   --verbose		provides more verbose information

DESCRIPTION

When invoked without a --targets option, this program will process the PDF document using the associated CSV as table of contents.

For every item in the PDF that has one or more additional files (files with the same name as the title, but differing extensions), clickable icons are added to the first page of the item. When clicked in a suitable PDF viewing tool, the corrresponding file will be activated.

For example, if the CSV contains

title;pages;
Blue Moon;24;

And the following files are present in the current directory

Blue Moon.html
Blue Moon.mscz

Then two clickable icons will be added to page 24 of the document, leading to these two files.

Upon completion, the updated PDF is written out under the specified name.

When invoked with the --targets option, all specified PDF files get links inserted to the targets on the first page. If there is only one PDF file you can use the --pdf option to designate the name of the new PDF document, otherwise all PDF files are updated (rewritten.

OPTIONS

Note that all sizes and dimensions are in points (72 points per inch).

--pdf=XXX

Specifies the updated PDF to be written.

--embed

Normally links are inserted into the PDF document that point to files on disk. To use the links from the PDF document, the target files must exist on disk.

With --embed, the target files are embedded (as file attachments) to the PDF document. The resultant PDF document will be usable on its own, no other files needed.

--attach

This is similar to --embed, but the files are attached to the PDF document and no icons are placed on the pages.

--all

Normally, only files with known types (extensions) are taken into account. Currently, these are html for iRealPro, mscz for MuseScore, sib for Sibelius, mxl and musicxml for MusicXML, abc for ABC and XML for generic XML documents.

With --all, all files that have matching names will be processed. However, files with unknown extensions will get a neutral document icon.

--xpos=NN

Horizontal position of the icons.

If the value is positive, icon placement starts relative to the left side of the page.

If the value is negative, icon placement starts relative to the right side of the page.

Default is 0 (zero); icon placement begins against the left side of the page.

Icons are always placed from the outside of the page towards the inner side.

An xpos value may also be specified in the CSV file, in a column with title xpos. If present, this value is added to position resulting from the command line / default values.

--ypos=NN

If the value is positive, icon placement starts relative to the top of the page.

If the value is negative, icon placement starts relative to the bottom of the page.

Default is 0 (zero); icon placement begins against the top of the page.

Icons are always placed from the outside of the page towards the inner side.

An ypos offset value may also be specified in the CSV file, in a column with title ypos. If present, this value is added to position resulting from the command line / default values. This is especially useful if there are songs in the PDF that do not start at the top of the page, e.g., when there are multiple songs on a single page.

--iconsize=NN

Desired size of the link icons. Default is 50.

--padding=NN

Space between icons. Default is to place the icons adjacent to each other.

--vertical

Stacks the icons vertically.

--border

Requests a border to be drawn around the links.

Borders are always drawn for links without icons.

--gfunder

Drawing the icon images uses the page transformations in effect at the end of the page. If these were not neatly restored, the graphics may be misplaced/scaled/flipped.

By using --gfunder, the images are placed behind the page but this only works for transparent pages.

This option is only relevant when adding links to external files. With --embed the problem does not occur.

--targets=FILE1 [ ; FILE2 ... ]

Explicitly specifies the target files to link to. In this case no CSV is processed and the input PDF(s) are updated (rewritten) unless --pdf is used to designate the output PDF name.

--help

Prints a brief help message and exits.

--man

Prints the manual page and exits.

--ident

Prints program identification.

--version

Prints program identification and exits.

--verbose

Provides more verbose information.

directory

The directory to process. Defaults to the current directory.

ICONS

pdflink has a number of icons built-in for common file types. Associations between a filename extension and an icon can be made with the --icons command line option.

For example,

--icons=pdf=builtin:PDF

This will associate the built-in icon PDF with filename extension pdf.

Alternatively, an image file may be specified to add user defined icons.

--icons=pdf=builtin:myicons/pdficon.png

The following icons are built-in. By default, only MuseScore and iRealPro icons are associated and all other filename extensions will be skipped. When pdflink is run with command line option --all, all built-in icons will be associated and all matching files will get linked.

PDF

Associated to filename extension pdf (generic PDF document).

PNG

Associated to filename extension png (PNG image).

JPG

Associated to filename extensions jpg and jpeg (JPG image).

MuseScore

Associated to filename extension mscz (MuseScore document).

iRealPro

Associated to filename extension html (iRealPro link in HTML document).

While technically this is wrong, this is the way iRealPro data is handled on Android and iPad.

BandInABox

Associated to filename extensions mgu, mg1 and so on (Band-In-A-Box document).

MXL

Associated with filename extension xml and musicxml (MusicXML).

XML

Associated with filename extension xml (generic XML document).

Document

Fallback icon for unknown filename extensions.

Border

Alternative fallback icon for unknown filename extensions.

LIMITATIONS

Some PDF files cannot be processed. If this happens, try converting the PDF to PDF-1.4 or PDF/A.

Files with extension html are assumed to be iRealPro files and will get the iRealPro icon.

Unknown extensions will get an empty square box instead of an icon.

Since colon : and slash / are not allowed in file names, they are replaced with @ characters.

If the icons come out at the wrong place or upside down, try --gfunder.

AUTHOR

Johan Vromans <jvromans@squirrel.nl>

COPYRIGHT

Copyright 2016,2020 Johan Vromans. All rights reserved.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Johan Vromans <jv at CPAN dot org >

SUPPORT

PDFlink development is hosted on GitHub, repository https://github.com/sciurius/pdflink.

Please report any bugs or feature requests to the GitHub issue tracker, https://github.com/sciurius/pdflink/issues.