Debian Codegraph @

texmf-dist/source/latex/pdfpc-movie/pdfpc-movie-doc.dtx

raw
1 %\iffalse
2 % Doc-Source file to use with LaTeX2e
3 % Copyright (C) 2018 Sebastian Friedl
4 %
5 % This work is subject to the LaTeX Project Public License, Version 1.3c or -- at
6 % your option -- any later version of this license.
7 % This work consists of the files pdfpc-movie.dtx, pdfpc-movie.ins, pdfpc-movie-doc.dtx
8 % and the derived file pdfpc-movie.sty.
9 %
10 % This work has the LPPL maintenance status 'maintained'.
11 % Current maintainer of the work is Sebastian Friedl.
12 %
13 % -------------------------------------------------------------------------------------------
14 %
15 % Provides a \pdfpcmovie command for linking movies in a way compatible to the
16 % PDF Presenter Console.
17 %
18 % -------------------------------------------------------------------------------------------
19 %
20 % Please report bugs and other problems as well as suggestions for improvements
21 % to my email address ([email protected]).
22 %
23 % -------------------------------------------------------------------------------------------
24 %\fi
25
26 % !TeX spellcheck=en_US
27
28
29 \documentclass[11pt]{ltxdoc}
30
31 \usepackage{iftex}
32 \RequireLuaTeX
33
34 \usepackage[no-math]{fontspec}
35 \usepackage{polyglossia}
36 \setdefaultlanguage{english}
37 \usepackage[english]{selnolig}
38
39 \usepackage{array}
40 \usepackage{csquotes}
41 \usepackage{hologo}
42 \usepackage[unicode, pdfborder={0 0 0}, linktoc=all, hyperindex=false]{hyperref}
43 \usepackage{bookmark}
44
45
46 \parindent0pt
47
48 \usepackage[erewhon]{newtxmath}
49 \setmainfont{erewhon}
50 \setsansfont[Scale=MatchLowercase]{Source Sans Pro}
51 \setmonofont[Scale=MatchLowercase]{Hack}
52
53 \usepackage[a4paper,left=4.50cm,right=2.75cm,top=3.25cm,bottom=2.75cm,nohead]{geometry}
54
55
56 \hyphenation{}
57
58
59 \MakeShortVerb{"}
60 \CheckSum{0}
61
62
63 \newcommand*{\sty}[1]{\textsf{#1}}
64
65 \def\param#1{\textit{\rmfamily\mdseries\ensuremath{\langle}#1\ensuremath{\rangle}}}
66
67
68 \RecordChanges
69
70
71
72
73 \title{The \sty{pdfpc-movie} package \\ {\large\url{https://gitlab.com/SFr682k/pdfpc-movie}}}
74 \author{Sebastian Friedl \\ \href{mailto:[email protected]}{\ttfamily [email protected]}}
75 \date{2018/07/21 (v1.0)}
76
77 \hypersetup{pdftitle={The pdfpc-movie package}, pdfauthor={Sebastian Friedl}}
78
79 \begin{document}
80 \maketitle
81 \thispagestyle{empty}
82
83
84 \medskip
85 \begin{abstract}
86 \noindent%
87 This package provides a "\pdfpcmovie" command for hyperlinking movies in a way compatible to the \href{http://pdfpc.github.io/}{PDF Presenter Console (\texttt{pdfpc}), a GPL2 licensed multi-monitor PDF presentation viewer application available on GitHub}\footnote{\url{http://pdfpc.github.io/}}.
88 \end{abstract}
89
90
91 \tableofcontents
92
93
94
95
96
97 \clearpage
98 \subsection*{Dependencies and other requirements}
99 \addcontentsline{toc}{subsection}{Dependencies and other requirements}
100 \sty{pdfpc-movie} requires the use of \LaTeXe. \\
101 It depends on the following packages:
102 \begin{multicols}{3}\sffamily\centering
103 etoolbox \\ hyperref \\ pgfkeys
104 \end{multicols}
105
106
107
108 \subsection*{Installation}
109 \addcontentsline{toc}{subsection}{Installation}
110 Extract the \textit{package} file first:
111 \begin{enumerate}
112 \item Run \LaTeX\ over the file "pdfpc-movie.ins"
113 \item Move the resulting ".sty" file to "TEXMF/tex/latex/pdfpc-movie/"
114 \end{enumerate}
115
116 Then, you can compile the \textit{documentation} yourself by executing \\[\smallskipamount]
117 "lualatex pdfpc-movie-doc.dtx" \\
118 "makeindex -s gind.ist pdfpc-movie-doc.idx" \\
119 "makeindex -s gglo.ist -o pdfpc-movie-doc.gls pdfpc-movie-doc.glo" \\
120 "lualatex pdfpc-movie-doc.dtx" \\
121 "lualatex pdfpc-movie-doc.dtx"
122
123 \smallskip
124 or just use the precompiled documentation shipped with the source files. \\
125 In both cases, copy the files "pdfpc-movie-doc.pdf" and "README.md" to \\
126 "TEXMF/doc/latex/pdfpc-movie/"
127
128
129
130 \subsection*{License}
131 \addcontentsline{toc}{subsection}{License}
132 \textcopyright\ 2018 Sebastian Friedl
133
134 \smallskip
135 This work may be distributed and/or modified under the conditions of the \LaTeX\ Project Public License, either version 1.3c of this license or (at your option) any later version.
136
137 \smallskip
138 The latest version of this license is available at \url{http://www.latex-project.org/lppl.txt} and version 1.3c or later is part of all distributions of \LaTeX\ version 2008-05-04 or later.
139
140 \smallskip
141 This work has the LPPL maintenace status \enquote*{maintained}. \\
142 Current maintainer of this work is Sebastian Friedl.
143
144 \medskip
145 This work consists of the following files:
146 \begin{itemize}\itemsep 0pt
147 \item "pdfpc-movie.dtx",
148 \item "pdfpc-movie.ins",
149 \item "pdfpc-movie-doc.dtx" and
150 \item the derived file "pdfpc-movie.sty".
151 \end{itemize}
152
153
154
155
156
157 % DOCUMENTATION PART ----------------------------------------------------------------------
158 \clearpage
159 \part{The documentation}
160 \section*{Loading \sty{pdfpc-movie}}
161 \addcontentsline{toc}{subsection}{Loading \sty{pdfpc-movie}}
162 Load \sty{pdfpc-movie} as any other package by adding "\usepackage{pdfpc-movie}" to your preamble.
163 There are no package options available.
164
165
166 \section*{Including movie files}
167 \addcontentsline{toc}{subsection}{Including movie files}
168 The package provides a "\pdfpcmovie" command using the syntax
169 \begin{center}\DescribeMacro{\pdfpcmovie}%
170 "\pdfpcmovie["\param{options}"]{"\param{poster material}"}{"\param{path to movie file}"}"
171 \end{center}
172
173 It creates a hyperlink to a movie with \param{path to movie file} being the path of the movie file relative to the PDF it is linked from. These hyperlinks are evaluated by "pdfpc", so that the movie (usually) starts playing when clicking onto \param{poster material}. \\
174 It will \emph{not} embed the movie into the PDF file in the sense that it is part of the "foo.pdf" file. Hence, the file must be copied and passed along with the PDF file in a manner allowing the viewer application to find the file at \param{path to movie file}. \\
175 As a recommendation, \param{path to movie file} should \emph{not} contain any \enquote{special} characters or spaces.
176
177 \bigskip
178 The \param{poster material} is placed inside a "\hbox" for determining and changing the space occupied by the poster material; therefore, it is not possible to insert any line breaks or similar \LaTeX\ code not allowed inside "\hbox"es. \\
179 The movie will playback in the area taken by the \param{poster material} or set via the "width"/"height" keys. Using a frame of the movie as \param{poster material} will ensure the correct aspect ratio.
180
181 \bigskip
182 The following \param{options} may be given as comma-separated list:
183 \begin{description}\itemsep0pt
184 \item[\texttt{width=\param{\TeX\ dimension}}]%
185 Overrides the width of \param{poster material} and sets it to the given \param{\TeX~dimension}
186
187 \item[\texttt{height=\param{\TeX\ dimension}}]%
188 Overrides the height of \param{poster material} and sets it to the given \param{\TeX~dimension}
189
190 \item[\texttt{depth=\param{\TeX\ dimension}}]%
191 Overrides the depth of \param{poster material} and sets it to the given \param{\TeX~dimension}
192
193 \item[\texttt{autostart}]%
194 Causes the movie to start playing immediately when the page is shown. \\[\smallskipamount]
195 A test with version 4.1.2 of "pdfpc" lead to the result that it is possible to autostart multiple movies placed on the same page; however, it turned out that they didn't play synchronously, but slightly \enquote{shifted} (by approximately 0.25\,s).
196
197 \item[\texttt{loop}]
198 Let the movie start again when the end has been reached. \\
199 Normally, the movie just stops there.
200
201 \item[\texttt{noprogress}]
202 Instructs "pdfpc" to avoid showing the progress bar below the movie. \\
203 As of "pdfpc" version 4.1.2, the progress bar will still be shown when the cursor is moved across the movie's bottom margin.
204
205 \item[\texttt{start=\param{time}}]
206 Makes the movie start at \param{time}~seconds. \\
207 \param{time} has to be an integer value without suffixes. For example, "start=2" is valid, while "start=4.2" and "start=1s" aren't.
208
209 \item[\texttt{stop=\param{time}}]
210 Makes the movie stop (and eventually restart) when the playback position has reached \param{time}~seconds. \\
211 As above, \param{time} has to be an integer value without suffixes.
212 \end{description}
213
214 If you don't need any options, you may omit the optional "["\param{options}"]" parameter.
215
216
217 \subsubsection*{Examples}
218 "\pdfpcmovie{\includegraphics[width=\textwidth]{foo}}{foo.mp4}"
219
220 {\leftskip2.5em%
221 Creates a link to the movie "foo.mp4", using an image as poster material. \\
222 The poster image will be replaced by the movie when clicking it.
223 \par}
224
225
226 \medskip
227 "\pdfpcmovie[autostart, width=8cm, height=4.5cm]{Restart}{bar.avi}"
228
229 {\leftskip2.5em%
230 Creates a link to the movie "bar.avi". \\
231 The movie is started as soon as the page is displayed and takes an area of 8\,cm width and 4.5\,cm height. \\
232 The movie stops after playing.
233 \par}
234
235
236 \medskip
237 "\pdfpcmovie[autostart, start=2, stop=5, loop]%" \\
238 " {\includegraphics[height=3cm]{res/baz}}{res/baz.mov}"
239
240 {\leftskip2.5em%
241 Creates a link to the movie "baz.mov" residing in the sub-directory "res/". \\
242 As soon as the page is displayed, the movie starts at 2~seconds and restarts when the playback position has reached 5~seconds.
243 \par}
244
245
246
247
248
249 % Start determining the checksum from here
250 \StopEventually{%
251 \clearpage
252 \PrintChanges}
253 \clearpage
254
255
256
257
258 \part{The package code}
259 \CodelineNumbered
260 \DocInput{pdfpc-movie.dtx}
261
262
263 \Finale
264 \end{document}
265