Debian Codegraph @

texmf-dist/source/latex/svn-multi/svn-multi-pl.dtx

raw
1 % \iffalse
2 %<*driver>
3 \iffalse
4 %</driver>
5 #!/usr/bin/perl
6 # --------------------------------------------------------------
7 # svn-multi.pl for the svn-multi v2.0 LaTeX package
8 # version 0.1, Mar 1st, 2009
9 # --------------------------------------------------------------
10 #
11 # Copyright (C) 2006-2012 Martin Scharrer
12 # E-mail: [email protected]
13 # Code repository: https://bitbucket.org/martin_scharrer/svn-multi
14 #
15 # This program works only in combination with the LaTeX package 'svn-multi' and
16 # generates .svx files with '\svnidlong' macros holding Subversion keywords for
17 # files declared with '\svnexternal' inside the LaTeX document.
18 #
19 # This program is free software under the GPL v3 and LPPL v1.3c or later.
20 #
21 #
22 # GPL v3:
23 # This program is free software: you can redistribute it and/or modify
24 # it under the terms of the GNU General Public License as published by
25 # the Free Software Foundation, either version 3 of the License, or
26 # (at your option) any later version.
27 #
28 # This program is distributed in the hope that it will be useful,
29 # but WITHOUT ANY WARRANTY; without even the implied warranty of
30 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 # GNU General Public License for more details.
32 #
33 # You should have received a copy of the GNU General Public License
34 # along with this program. If not, see <http://www.gnu.org/licenses/>.
35 #
36 #
37 # LPPL v1.3c:
38 # This work may be distributed and/or modified under the
39 # conditions of the LaTeX Project Public License, either version 1.3c
40 # of this license or (at your option) any later version.
41 # The latest version of this license is in
42 # http://www.latex-project.org/lppl.txt
43 # and version 1.3c or later is part of all distributions of LaTeX
44 # version 2008/05/04 or later.
45 #
46 # This work has the LPPL maintenance status `maintained'.
47 #
48 # The Current Maintainer of this work is Martin Scharrer.
49 #
50 # This work consists of the files svn-multi.dtx, svn-multi-pl.dtx and
51 # svn-multi.ins and the derived files svn-multi.sty, svnkw.sty and svn-multi.pl.
52 #
53 # The file 'svn-multi.pl' may be renamed to 'svn-multi' for installation
54 # purposes.
55 #
56 #
57 %<*driver>
58 \fi
59 \makeatletter
60 % $Id: svn-multi-pl.dtx 1873 2010-07-26 15:31:45Z martin $
61 \def\svnmultipl@version {v0.1a}
62 \def\svnmultipl@rev $#1: #2 ${\def\svnmultipl@rev{#2}}
63 \def\svnmultipl@date $#1: #2-#3-#4 #5 ${%
64 \def\svnmultipl@today{{\year#2\month#3\day#4\today}}%
65 \def\svnmultipl@date{#2/#3/#4}%
66 }
67 \svnmultipl@rev $Rev: 1873 $
68 \svnmultipl@date $Date: 2010-07-26 17:31:45 +0200 (Mon, 26 Jul 2010) $
69
70 \ProvidesFile{svn-multi-pl.dtx}
71 [\svnmultipl@date\space\svnmultipl@version\space SVN Keywords extractor for svn-multi]
72
73 \documentclass{ltxdoc}
74 \usepackage{ifpdf}
75 \ifpdf
76 % use hypdoc if you have it, hyperref else
77 %\usepackage[hyperfootnotes=false]{hyperref}
78 \usepackage{hypdoc}
79 \else\let\url=\texttt\fi
80 \usepackage{xspace}
81 \newcommand{\ie}{i.e.\@\xspace}
82 \newcommand{\eg}{e.g.\@\xspace}
83
84 \newenvironment{sub}{\begin{macro}}{\end{macro}}
85 \newcommand{\parni}{\par\noindent}
86 \newlength{\origparindent}
87 \setlength{\origparindent}{\parindent}
88 \setlength{\parindent}{0pt}
89 \let\origpar=\par
90 \def\par{\parindent=\origparindent\origpar\parindent=0pt}
91
92 %\EnableCrossrefs
93 \DisableCrossrefs
94 \CodelineIndex
95 %\PageIndex
96 %\RecordChanges
97 \begin{document}
98 %\OnlyDescription
99 \DocInput{\jobname.dtx}%
100 %\PrintChanges
101 %\clearpage
102 %\PrintIndex
103 \end{document}
104 %</driver>
105 %<*script>
106 %\fi
107 %
108 % \CheckSum{66}
109 %
110 % {\makeatother
111 % \CharacterTable
112 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
113 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
114 % Digits \0\1\2\3\4\5\6\7\8\9
115 % Exclamation \! Double quote \" Hash (number) \#
116 % Dollar \$ Percent \% Ampersand \&
117 % Acute accent \' Left paren \( Right paren \)
118 % Asterisk \* Plus \+ Comma \,
119 % Minus \- Point \. Solidus \/
120 % Colon \: Semicolon \; Less than \<
121 % Equals \= Greater than \> Question mark \?
122 % Commercial at \@ Left bracket \[ Backslash \\
123 % Right bracket \] Circumflex \^ Underscore \_
124 % Grave accent \` Left brace \{ Vertical bar \|
125 % Right brace \} Tilde \~}
126 % }
127 % \iffalse " \fi
128 %
129 % \title{The \textsf{svn-multi.pl} Script}
130 % \author{Martin Scharrer \\ \url{[email protected]} \\
131 % \url{http://latex.scharrer-online.de/svn-multi} \\
132 % CTAN: \url{http://tug.ctan.org/pkg/svn-multi}}
133 % \date{Version \expandafter\@gobble\svnmultipl@version\\[0.5ex]\svnmultipl@today}
134 %
135 %
136 % \ifpdf
137 % \hypersetup{
138 % pdfauthor={Martin Scharrer <[email protected]>},
139 % pdftitle={The svn-multi.pl script},
140 % pdfsubject={Documentation of Perl script svn-multi.pl which allows the
141 % typesetting of external Subversion keywords in multi-file LaTeX documents},
142 % pdfkeywords={svn-multi, svnkw, LaTeX, Subversion, keywords, Version
143 % Control, Id, script}
144 % }
145 % \fi
146 % \maketitle
147 %
148 % \textbf{Note:} This document is work in progress.\par
149 % \section{Usage}
150 % See the section in the |svn-multi| package manual or the
151 % \hyperlink{usage}{\texttt{usage}} function below.
152 %
153 % \StopEventually{}
154 % \section{Implementation}
155 %
156 % \subsection{Script Head}
157 % Loading of required Modules.
158 % \begin{macrocode}
159 use strict;
160 use warnings;
161 use File::Basename;
162 % \end{macrocode}
163 % Declaration of constants VERSION, REV and DATE for script info output:
164 % \begin{macrocode}
165 my $VERSION = "0.2";
166 my ($REV,$DATE) =
167 (split ' ','$Id$')[2,3];
168 % \end{macrocode}
169
170 % Declaration of other global constants and variables:
171 % \begin{macrocode}
172 my $dollar = '$';
173 my @PATH;
174 my %EXCLUDE = map { $_ => 1 } qw(sty tex aux log out toc fff ttt svn svx);
175 % \end{macrocode}
176
177 % Subfunction prototypes:
178 % \begin{macrocode}
179 sub create_svxfile ($@);
180 sub usage;
181 % \end{macrocode}
182
183 % Check if help was requested:
184 % \begin{macrocode}
185 if (!@ARGV or grep { $_ eq '--help' or $_ eq '-h' } @ARGV) {
186 usage();
187 }
188 % \end{macrocode}
189
190 % Print identification line like other TeX related programs:
191 % \begin{macrocode}
192 print STDOUT "This is svn-multi.pl, Version $VERSION-$REV, $DATE\n";
193 % \end{macrocode}
194
195 % The first argument is taken as the jobname. To be more userfriendly the name
196 % can include some standard extension and a path which are stripped.
197 % \begin{macrocode}
198 my ($jobname, $dir, $suffix) = fileparse(shift @ARGV, qr/\.(tex|ltx|dtx|svn)$/);
199 % \end{macrocode}
200 % If a directory was specified this program is changing into it because the
201 % file paths in the |.aux| file are relative to it.
202 % \begin{macrocode}
203 if ($dir && $dir ne './') {
204 printf STDOUT "Main directory is '$dir'.\n";
205 chdir($dir);
206 }
207 % \end{macrocode}
208 % \begin{macrocode}
209
210 if ($jobname =~ /^-/) {
211 usage();
212 }
213 my $outfile = "$jobname.svx";
214
215 my %external;
216
217 % \end{macrocode}
218 % Regular expressions to read the |.aux| file:
219 % \paragraph{svnexternalpath:} The format is:\\
220 % \hspace*{2em}|\@svnexternalpath{{patha}{pathb}{...}{pathd}}|
221 % \begin{macrocode}
222 my $resvnexternalpath = qr/
223 ^ # at begin of line
224 \s* # allow for spaces
225 \\\@svnexternalpath # the macro name
226 \s*
227 { # begin token group
228 \s*
229 (?: # paths:
230 { # { of first path
231 (.*) # everything else, e.g: 'patha}{pathb}{pathc'
232 } # } of last path
233 | # or nothing
234 )
235 \s*
236 } # end token group
237 \s*
238 $ # end of line
239 /x;
240 % \end{macrocode}
241
242 % \paragraph{svnexternal:} The format is:\\
243 % \hspace*{2em}|\@svnexternal[group name]{{filea}{fileb}{...}{filed}}|
244 % \begin{macrocode}
245 my $resvnexternal = qr/
246 ^ # at begin of line
247 \s* # allow for spaces
248 \\\@svnexternal # the macro name
249 \s*
250 (?: # optional:
251 \[ # opening [
252 ([^\]]*) # group name (everything until ])
253 \] # closing ]
254 )?
255 \s*
256 { # begin token group
257 ([^}]+) # file name (everything until })
258 } # end token group
259 \s*
260 { # begin token group
261 \s*
262 (?: # paths:
263 { # { of first file
264 (.*) # everything else, e.g: 'filea}{fileb}{filec'
265 } # } of last file
266 | # or nothing
267 )
268 \s*
269 } # end token group
270 \s*
271 $ # end of line
272 /x;
273 % \end{macrocode}
274
275 % \begin{macrocode}
276 if (-e "$jobname.aux" and open( my $svnfh, '<', "$jobname.aux")) {
277 print STDOUT "Reading '$jobname.aux'.\n";
278 while (<$svnfh>) {
279 chomp;
280 if (/$resvnexternalpath/) {
281 push @PATH, ( split /}\s*{/, $1 );
282 }
283 elsif (/$resvnexternal/) {
284 my ($group,$file,$list) = ($1||"",$2,$3||"");
285 $file =~ s/^\.\///;
286 push @{$external{$file}{$group} ||= []}, ( split /}\s*{/, $list );
287 }
288 }
289 close ($svnfh);
290 }
291 else {
292 warn "No .aux file found for '$jobname'!\n";
293 }
294
295 # Add TEXINPUTS to path
296 push @PATH, map { $_ =~ s/(?<!\/)$/\//; $_ } grep { $_ }
297 split(':', $ENV{'TEXINPUTS'}||"");
298
299 my @mainfilepairs;
300 my $maintex = "$jobname.tex";
301 if (exists $external{$maintex}) {
302 while ( my ($group,$list) = each %{$external{$maintex}} ) {
303 push @mainfilepairs, [ $group, [ @$list ] ];
304 }
305 delete $external{$maintex};
306 }
307
308 push @mainfilepairs, parse_args(@ARGV);
309 create_svxfile("$jobname.svx", @mainfilepairs )
310 if @mainfilepairs;
311
312 foreach my $file (keys %external) {
313 my @pairs;
314 my $svxfile = $file;
315 $svxfile =~ s/\.(tex|ltx)$/.svx/;
316 while ( my ($group,$list) = each %{$external{$file}} ) {
317 push @pairs, [ $group, [ @$list ] ];
318 }
319 create_svxfile($svxfile, @pairs);
320 }
321 % \end{macrocode}
322
323 % \subsection{Functions}
324
325 % \begin{sub}{parse args}
326 % Parses the arguments and builds a list of (group,(files)) pairs.
327 % \begin{macrocode}
328 sub parse_args {
329 my @args = @_;
330 my $group = '';
331 my @files;
332 my $readfg;
333 my @pairs;
334
335 foreach my $arg (@args) {
336 if ($readfg) {
337 $readfg = 0;
338 $group = $arg;
339 $group =~ s/^["']|["']$//; # '
340 }
341 elsif ($arg =~ /^--group|^-?-fg/) {
342 push @pairs, [ $group, [ @files ] ];
343 @files = ();
344 if ($arg =~ /^--group=(.*)/) {
345 $group = $1;
346 $group =~ s/^["']|["']$//; # '
347 }
348 else {
349 $readfg = 1;
350 }
351 }
352 elsif ($arg =~ /^--fls/) {
353 push @files, read_fls("$jobname.fls");
354 }
355 else {
356 push @files, $arg;
357 }
358 }
359 push @pairs, [ $group, [ @files ] ] if @files;
360 return @pairs;
361 }
362 % \end{macrocode}
363 % \end{sub}
364
365 % \begin{sub}{path search}
366 % Search all directories in |PATH| to find the given file and return the first
367 % own found.
368 % \begin{macrocode}
369 sub path_search {
370 my $file = shift;
371 $file =~ s/##/#/g;
372 return $file if not $file or -e $file or not @PATH;
373
374 foreach my $dir (@PATH) {
375 if (-e "$dir$file") {
376 return "$dir$file";
377 }
378 }
379
380 return $file;
381 }
382 % \end{macrocode}
383 % \end{sub}
384
385 % \begin{sub}{ceate svxfile}
386 % Creates the |.svx| file named by the first argument. The second argument is a
387 % list of (group name/files) pairs.
388 % \begin{macrocode}
389 sub create_svxfile ($@) {
390 my ($svxfile, @fgpair) = @_;
391 my $lastgroup;
392 my $fgused = 0;
393 my %seen;
394 return if not @fgpair or not $svxfile;
395
396 open(my $svxfh, '>', $svxfile) or do {
397 warn "ERROR: Could not create SVX file '$svxfile'!\n";
398 return;
399 };
400 print STDOUT "Generating .svx file '$svxfile'.\n";
401 select $svxfh;
402 print "% Generated by svn-multi.pl v$VERSION\n\n";
403
404 while ( my ($group, $files) = @{shift @fgpair||[]}) {
405 no warnings 'uninitialized';
406 if ( (not defined $lastgroup and $group) or ($group ne $lastgroup) ) {
407 print "\\svngroup{$group}\n";
408 }
409 use warnings;
410 if ($group) {
411 $fgused = 1;
412 }
413
414 foreach my $file (@$files) {
415 $file = path_search($file);
416
417 # Only print the file once per group and .svx file
418 next if $seen{$group}{$file};
419 $seen{$group}{$file} = 1;
420
421 open(my $infoh, '-|', "svn info '$file' 2>/dev/null") or next;
422 my %info = map { chomp; split /\s*:\s*/, $_, 2 } <$infoh>;
423 close($infoh);
424 if (not keys %info) {
425 print "% Could not receive keywords for '$file'!\n\n";
426 next;
427 }
428 print "% Keywords for '$file'\n";
429 print svnidlong(\%info);
430 print "\\svnexternalfile";
431 print "[$group]" if $group;
432 print "{$file}\n";
433 print "\n"
434 }
435
436 $lastgroup = $group;
437 }
438 print "\n";
439 close ($svxfh);
440 }
441 % \end{macrocode}
442 % \end{sub}
443
444 % \begin{sub}{svnid}
445 % Generates \cs{svnid} macro lines. Awaits a hash with the information
446 % received from |svn|. The |$| sign is masked to avoid keyword extension by
447 % Subversion inside this source file.
448 % Additional modules are needed to produce the date format used by |$||Id$|.
449 % \begin{macrocode}
450 sub svnid {
451 use Date::Parse;
452 use Date::Format;
453 my $href = shift;
454 return "" if (not defined $href->{Name});
455 my $date = time2str("%Y-%m-%d %XZ", str2time($href->{'Last Changed Date'}), 'Z');
456 return <<"EOT";
457 \\svnid{${dollar}Id: $href->{Name} $href->{'Last Changed Rev'} $date $href->{'Last Changed Author'} \$}
458 EOT
459 }
460 % \end{macrocode}
461 % \end{sub}
462
463 % \begin{sub}{svnidlong}
464 % Generates \cs{svnidlong} macro lines. Awaits a hash with the information
465 % received from |svn|. The |$| sign is masked to avoid keyword extension by
466 % Subversion inside this source file.
467 % \begin{macrocode}
468 sub svnidlong {
469 my $href = shift;
470 return <<"EOT";
471 \\svnidlong
472 {${dollar}HeadURL: $href->{URL} \$}
473 {${dollar}LastChangedDate: $href->{'Last Changed Date'} \$}
474 {${dollar}LastChangedRevision: $href->{'Last Changed Rev'} \$}
475 {${dollar}LastChangedBy: $href->{'Last Changed Author'} \$}
476 EOT
477 }
478 % \end{macrocode}
479 % \end{sub}
480
481 % \begin{sub}{read fls}
482 % Reads the |.fls| file and looks for |INPUT relativedir/file| lines.
483 % The file is ignored if its extension is in the |EXCLUDE| list.
484 % \begin{macrocode}
485 sub read_fls {
486 my $fls = shift;
487 my %stack;
488 open (my $fh, '<', $fls) or return;
489 while (<$fh>) {
490 chomp;
491 if (/^INPUT ([^\/].*)$/) {
492 my $file = $1;
493 my $ext = substr($file, rindex($file,'.')+1);
494 $stack{$1} = 1 if not exists $EXCLUDE{$ext};
495 }
496 }
497 close($fh);
498 return keys %stack;
499 }
500 % \end{macrocode}
501 % \end{sub}
502
503 % \begin{sub}{usage}
504 % \hypertarget{usage}{}%
505 % Prints usage information.
506 % \begin{macrocode}
507 sub usage {
508 print STDOUT <<'EOT';
509 Usage:
510 svn-multi.pl jobname[.tex] [--fls] [--group|-g <group name>] [input_files] ...
511 ... [--group|-g <group name>] [input_files] ...
512
513 Description:
514 This LaTeX helper script collects Subversion keywords from non-(La)TeX files
515 and provides it to the 'svn-multi' package using '.svx' files. It will first
516 scan the file '<jobname>.aux' for files declared by the '\svnextern' macro but
517 also allows to provide additional files including the corresponding groups. The
518 keywords for the additional files will be written in the file '<jobname>.svx'.
519
520 Options:
521 jobname[.tex] : The LaTeX `jobname`, i.e. the basename of your main LaTeX file.
522 --group <GN> : Use given group name <GN> for all following files,
523 or -g <GN> including the one read by a '--fls' option, until the next
524 group is specified.
525 --fls : Read list of (additional) files from the file '<jobname>.fls'. This
526 file is produced by LaTeX when run with the '--recorder' option and
527 contains a list of all input and output files used by the LaTeX main
528 file. Only input files with a relative path will be used. A
529 previously selected group will be honoured.
530
531 Examples:
532 The main LaTeX file here is 'mymainlatexfile.tex'.
533
534 svn-multi.pl mymainlatexfile
535 Creates Subversion keywords for all files declared by '\svnextern' inside
536 the LaTeX code.
537
538 svn-multi.pl mymainlatexfile --group=FLS --fls
539 Creates Subversion keywords for all files declared by '\svnextern' inside
540 the LaTeX code. In addition it does the same for all relative input files
541 mentioned in the .fls file which are placed in the 'FLS' group.
542
543 svn-multi.pl mymainlatexfile a b c --group=B e d f
544 In addition to the '\svnextern' declared files the keywords for the files
545 'a', 'b' and 'c' will be added without a specific group, i.e. the last group
546 specified in the LaTeX file before the '\svnextern' macro will be used. The
547 keywords for 'e', 'd', 'f' will be part of group 'B'.
548
549 svn-multi.pl mymainlatexfile --group=A a --group=B b --group='' c
550 File 'a' is in group 'A', 'b' is in 'B' and 'c' is not in any group.
551
552 Further Information:
553 See the svn-multi package manual for more information about this script.
554 EOT
555 exit(0);
556 }
557 % \end{macrocode}
558 % \end{sub}
559
560 % End of File
561 % \begin{macrocode}
562 __END__
563 % \end{macrocode}
564 %
565 % \Finale
566 % \iffalse
567 %</script>
568 % \fi
569 % ^^A \iffalse vim: ft=perl,sw=2,ts=2
570 % ^^A \fi