Looking for the latest version? Download seppdflatex (77.7 kB)
Name Modified Size Downloads / Week Status
Totals: 4 Items   23.0 kB 1
doc 2014-06-19 11 weekly downloads
bin 2014-06-19 11 weekly downloads
latex_examples 2014-01-21 22 weekly downloads
README 2014-06-19 23.0 kB 11 weekly downloads
===================== README - seppdflatex ===================== INSTALLATION: ------------- * You should have installed perl (cpan) and texlive or another LaTeX distribution. * Download seppdflatex * Make it executable and stick it in your $PATH * You need a bunch of perl modules, you can get them from cpan. * You need a TeX distro, pdflatex, a bunch of CTAN packages, and pdftk and pdfsam-console. All are free software. * Once all that is installed you can `cd` to a working latex project directory and try the script ... First read, seppdflatex --help * ... however, it works with a particular style of LaTeX source file, a working example is provided at sourceforge from my mathematics puzzle textbook. The gist is that in the preamble you need (a) a special <project>-toc.tex file with a bunch of special zref-xr package commands in it. The script seppdflatex will attempt to create this for you. (b) in your main .tex source you need a minimal set of commands for including chapters, like the following: %%%%%%%%%%%%%%%% Lines to have in your main .tex preamble %%%%%%%%%%%%%%%%%%%%%%%%%%% \usepackage{xr} \externaldocument{<ch1>} % one for each chapter \usepackage{zref-abspage,zref-thepage} \makeatletter \newcommand*{\pagevaluelabel}[1]{% \zref@labelbyprops{toc}{abspage}% } \makeatother \AtBeginDocument{% \addtocontents{toc}{\string\providecommand\string\pagevaluelabel[1]{}}% \addtocontents{toc}{\string\pagevaluelabel{toc}}% } \newcommand*{\tocinclude}[1]{% \setcounter{tocdepth}{2}% \begingroup \makeatletter \def\@prj{#1}% \let\contentsline\foreign@contentsline \input{../\@prj/\@prj.toc}% \endgroup } \def\foreign@contentsline#1#2#3#4{% \ifx\\#4\\% \csname l@#1\endcsname{#2}{#3}% \else \ifHy@linktocpage \csname l@#1\endcsname{{#2}}{% \hyper@linkfile{#3}{\@prj.pdf}{#4}% }% \else \csname l@#1\endcsname{% \hyper@linkfile{#2}{\@prj.pdf}{#4}% }{#3}% \fi \fi }% \includonly{<ch1>,<ch2>} % to only process these chapters ... \begin{document} ... \input{<ch1} % one for each chapter ... \end{document} %%%%%%%%%%%%%%%% Lines to have in your main .tex preamble %%%%%%%%%%%%%%%%%%%%%%%%%%% POD Documentation: ------------------ PROGRAM: seppdflatex Version 1.0 TIPS (a mini trouble-shooting section) UPFRONT ANNOYANCES and WARNINGS External Hyperlinks Bibliography Commands Must go in 'bibliography.tex' Acknowledgements Should go in 'acknowledgements.tex' Preamble Must go in '_headers_essential_.tex' Using \input{...} is Problematic Frontspieces and Backpieces \chapter*{...} Sections Will Not Necessarily Split SYNOPSIS Why this Script? Some Details EXAMPLES Example 1 Example 2 Example 3 ARGUMENTS OPTIONS SOME INTERNALS Splitting Chapters Modifying TESTING CAVEATS REQUIREMENTS Subroutines makeMainEdition and makeAltEdition Requires Usage Subroutine hashKeyNum Requires Usage Subroutine hashValNum Requires Usage INFO TODO Collect Frontpieces and Backpieces AUTHOR COPYRIGHT AND DISCLAIMER PROGRAM: seppdflatex Creates a separate document for each chapter in a (presumably) huge book or volume or collection. An idiosyncracy is that in the project I wrote this script for I use two types of edition, a "Teachers" and a "Students" edition, and so I do a little jig with the file names and the Makefile. It should not affect a generic one-book project though. You can turn off this double edition mode wth the cmd option -s. Version 1.0 Hey, skip to the SYNOPSIS why don't ya! TIPS (a mini trouble-shooting section) Tip 1. If external refs stuff things up delete the chapter *.aux files and run the script again. Tip 2. If you see pdfsam-console error messages, just try running the seppdflatex command again, because it may have been that the chapter bookmarks were not found. Tip 3. Most users will run this script from a console (bash terminal), but if your terminal application does not allow easy searching through the stdout history you might like to log all the output, for this you can use the pipe to a tee command. For example, for my project radd-maths_teachers.tex I might run, seppdflatex -n "1 2 3" radd-maths_teachers |tee seppdflatex.log this way you also record the LaTeX and BibTeX warnings and errors. UPFRONT ANNOYANCES and WARNINGS Ahhh, so many Kuldges, so little time to be pure. This scrpt does what I needed. External Hyperlinks To link sections and labels across files I use a custom LaTeX command, lref, which I define in the preamble for a project, \newcommand{\lref}[2]{\href{file:#1}{#2}} it is useful since a script like seppdflatex can then edit the preamble and temporarily redefine the camoond to make all the \href command internal. That's need when you wish to build a singe all-in-one PDF. Currently I do not use this facility in seppdflatex, but I think it should be a future option used with the switch -b. The default definition is used in markup as follows, \lref{<chapterfile>\#<link_label>}{<name for the link>} so, for example, if I want a link to a section labeled lnk_prime_numbers in the file number.pdf but have this link appear in the Algebra chapter, then in the algebra.tex file where I want the link I will write, \lref{number\#lnk_prime_numbers}{Prime Numbers} Bibliography Commands Must go in 'bibliography.tex' Since this will get split out into a separate chapter by pdfsam-consolve, and I like to be able to find it's file name easily, so make it a separate source file. Usually it's simple, something like, \clearpage \phantomsection \addcontentsline{toc}{chapter}{References} \bibliographystyle{amsalpha} \bibliography{edu,maths} The file name is not important, just the fact it is included as a source with \input{...}. Acknowledgements Should go in 'acknowledgements.tex' (Or a similar file, name is not important.) Same reasons as above. Preamble Must go in '_headers_essential_.tex' Currently I ask that you put some of your LaTeX preeamble into a separate file '_headers_essential_.tex'. It needen't be everything, just whatever you want for your titlepage, page layout, LOT, LOT, TOC pages formatting. Warning! DO NOT PUT ANY \include{..} or \input{...} commands in this '_headers_essential_.tex' file. And at the first few lines of '_headers_essential_.tex' it it might pay to remind yourself: %% Essential Preamble for a LaTeX project to be built with `seppdflatex` %% WARNING! DO NOT PUT ANY \include{..} or \input{...} commands in this file. The reason is that it makes the order of chapters too messy to determine, although not impossible. Anyway, I've avoided this issue by making sure all \inpput and \include> chapters are only in the <master>.tex <master>-toc.tex files (and even allowing them across two files like this is a pain!). Using \input{...} is Problematic We use pdfsam-console to split a document into chapters. The default is to split at bookmarks defined by \chapter{...} commands in the LaTeX sources. So you had better not use more than one \chapter{...} command per \include{...} or \input{...} files, ok!! Got it?! Also, we have to be careful about \include{...} and \input{...} commands in the <master>*.tex document, since we will not wish to over or under count the number of expected splits, since this will mess-up the renaming of the output files. Frontspieces and Backpieces See Collect Frontpieces and Backpieces. At the moment everything with a top level TOC entry gets split into it's own PDF. Bit of a shame. But not too big a deal. It actually works for my tastes (e.g., see the next note Sections Will Not Necessarily Split. \chapter*{...} Sections Will Not Necessarily Split pdfsam-console does not split at a \chapter*{foo} section, unless it is IMMEDIATELY PRECEEEDING a proper \chapter{foo} Section. So we have to advance the counting of chapter titles if we hit a \chapter*{foo} type of sectioning. This is noted at the appropriate code line in the script. So if you actually want to split up even your C\chapter*{...}> unnumberd chapter sections, then =you will need some addiitonal hacks. Not sure what to suggest. Perhaps use \chapter{foo} and put up with the new numbering, or hack the section numbering from within your LaTeX sources? SYNOPSIS Searches for chapter inputs in a master LaTeX source file. Processes each chapter separately, and includes the title page only with the Frontspieces (TOC, LOF, LOT). Subsequent chapters are standalone PDF files. The nice thing is the file with the TOC opens the external links to the chapter files. Why this Script? Why? So you can build a massive project of thouands of pages and oodles of illustrations, and allow users to pull up a small PDF document one at a time. Some Details Output is separate PDF files, but with external hyperlinks and cross-references all working, so clicking on a cross-reference should open the PDF file with the target and also send you directly to the page which contains the link target. By DEFAULT the PDF fiels are moved to a subfolder .chapters/, but you can change this with the -o option. You need the LaTeX subfiles package and in the master doocument (say this is mytexbook for this discussion) preamble, use, \usepackage{subfiles} \usepackage{xr} \externaldocument{foo} using one \externaldocument line for each chapter subfile. This allows the hyperlinks and cross-references to open the relevant chapter file. This opens in a new gui Window if your hyperref package directives have the pdfnewwindow={true} option. The default hyperref package option is pdfnewwindow={false} false, so you need to make this excplicit in your master LaTeX preamble. But it may not work in some PDF readers. It should work with Foxit, Adobe AcrobatReader and evince, but in okular it opens in the same windown and you cannot click to go back to where the link/cross-refernence came from, so please Okular developers could you fix this! Could be a minor Okular config tweak I don't know about?) And then instead of \include{foo} for your chapter files, instead use, \subfile{foo} and then in every such subfile add a line near the top of the file, \documentclass[mytexbook]{subfiles} \begin{document} and at the end of each subfile add a line, \end{document} which will allow this script and the Makefile called Makefile_Radd which it uses to compile every chapter (subfile) file separately to the mian document, but with all hyperlinks and crossreferences preserved. You can still \input or \include commands to compile sources, but they will end up as part of the main document, toegtehr with the title-pages and TOC and so forth. When running seppdflatex foo the master document foo.tex gets processed, and all \subfile{...} inclusions get compiled into separate PDF books. =head2 USAGE Pass the script a master file name (the one with your LaTeX preamble): seppdflatex <latexfile> [options] EXAMPLES Example 1 seppdflatex Find the first LaTeX master file in the pwd and processes the chapters, identified by \input{filename} or \include{filename} lines that are not commented out. If you have commented out some included files then they will not be compiled. You can compile even the commented out \include files using the -a option, see Example 2. Example 2 seppdflatex <latexfile> -a Generates all chapters as separate PDF files, all hyperlinked. Example 3 seppdflatex <latexfile> -n "<ch1> <ch2> <ch3>... " Here the chn are the chapter numbers desired, alternatively they can be the fielnames with or without the .tex extension. The output will be separate PDF files but only for the list of chapters. The chapter numbering is not by file name, but by the ORDER in which the input sources occur in the LaTeX master file. ARGUMENTS <latexfile> Currently this is mandatory, but TODO will be to search the pwd for a master file, identified by a \documentclass line. We'll just default to the first such file found with a .tex extension. OPTIONS See --help for more options. Here are the mian ones: -a Process all input files for the master document, i.e., make all chapters. (This can take a while to run if you have a huge lot of LaTeX sources.) This only compiles included subfiles that are in uncommented lines. -b Build a single large document, i.e., all chapters together. But only include chapters specified by -n \"<list>\" or all uncommented ones as per the switch -a option. NOTE: -b overrides the -x option. -n "ch1 [ch2 ch3 ...]" Just generate PDF chapters for the numbered input fles. Numbers tell the scrip the order in which the chapter files appear in the master file. The alternative is a filename look-up if the list is not numeric integers. -o <dir> (Optional) output directory where compiled PDF files are moved to. DEFAULT = ./chapters -s Tells the script you only wish to process the 'student' edition volume. DEFAULT assumes a double edition, one for "Teachers" with a filneame pattern *_teachers.tex from which a Student version is built, sans the '_teachers' substring in the output filename. -t Option to build BOTH the student and teacher editions. DEFAULT is to build only the Teacher edition. -g | --view Open a PDF viewer (if one can be found), it should open the main PDF with the TOC as well as the first chapter which was coompiled by the Makefile. Why the command opt -g ? Since -p is taken by podoc, and -v is for version. --book <seriestitle> Short title of the book volume, used to stamp the PDF Info. --author <yourname> Author's name, used to stamp the PDF Info. --aux Stop building after making the auxiliary *.toc, *.lof, *.lot, chapter files. --toc Stop building after making the master *-toc.pdf file. --build Stop building after makingall the PDF files, but before moving them t the output directory for viewing. --inc Build only chapters the user has ALREADY speciied on their \includeonly{...} line. THat is, don't edit this for them even if they have used the -n "..." option. --dry Run the script without calling any pdflatex builds. Useful for testing when all the fiels ave been built previously. --pod Refresh this POD html documentation. --help Or -h. Displays a help message then quits. --version Or -v. Displays a brief version message then quits. In addiiton, there are some lines in the script a user may wish to edit once per project: The pair of lines, our $edition_main="_teachers"; our $edition_alt="_students"; set the files name substituions for the two possible editions supported by this script. In this defalts case I have a "student" adnd a a"teacher" edition. So if you are running a project with some other kind of twin, version, say "Users Guide" and "Developers Guide", then you might edit these lines to be, our $edition_main="_users"; our $edition_alt="_devs"; or whatever, according to your needs. SOME INTERNALS Splitting Chapters At the time of wiritng these notes I had given up on hacking the subfiles package method since you have to grab page numbers and shit. It's easier, I found, to build all the documet with all the chapters, minus the Frontspieces, then split by chapter level using pdfsam-console. The generic command is, pdfsam-console -s BLEVEL -bl 1 -o ./ -p ch_ -f <masterfile>.pdf split the output will then be in the form, <page>_ch_<masterfile>.pdf the script then works out which chapter is which by the page numbering and the order of the \includeonly{...} and any \input{...} files in master.tex. It's a bit ugly this way, and a weirdly strucutred LaTeX project could break the script. The alternative is to go back to using subfiles or some pure LaTeX-only solution, e.g, pdflatex -jobname=ch_<foo> <master> but this gives chapters their own numbering, so it's a pain (but not impossible) to reset the counters to make a split single volume proper. Splitting into chapters is easy really, and the purpose of this script is not that, butrather to get also a nice exernally links TOC and LOF and LOF document as well as separate chapters with continued page numbering. (If you've written 9000 pages a la Proust then why not showit?) Modifying Most Perl afficionados or even novices can hack this script easily. One of the main internal things is the choice of whether to use the CTAN package subfiles or the native LaTeX \includeonly idiom. Either way the purpose is to create *.aux files for each chapter. This script then generates TOC, LOF, LOF files from these *.aux files. To my knowledge there is no difference between the two methods in outcome. We just want the external hyperlinks to work! When Method A (the includeonly idiom) is used, the script expects to see at least one line un-commented, of the regex form, \includeonly{.* (that's with a backslash character to begin the line). If such a line has been commented-out then this script will just be including all chapter files indiscriminantly. TESTING There aare a few partial build switches. --aux, --toc. The switch --inc is useful when testing, it allows a lazy run of the script that only processes the already written \includeonly{...} chapters. If you have a master file master.tex with several chapters iput as \include{...} lines, then running seppdflatex master --aux stops the build at the stage where the chapter auxilliary files are created. This should create chapter.toc, chapter.lof, chapter.lot files as well as the precursor chapter.aux files. To stop building afer the TOC PDF files is generated use, seppdflatex master --toc Otherwise just run a complete build, seppdflatex master and see if the results are satisfying, and if not modify the script as needed. CAVEATS The author (that's me right) is not a programmer. So he does not apologise for any bugs. I started writing this script to allow cross-platform operability, but I'm far too tied into GNU+Linux. All the tools however are free software which can be installed from, say, Debian repositories. We take no responsibilioty for files that get deleted or over-written or for your LaTeX source syntax errors and such-like. We only claim this script does what it says it will do provided you set up your LaTeX project correctly with the appropriate CTAN subfile package commands. I also do not under many circumstances claim this script will not crash your computer if your memory is low, since building a large heavily cross-references LaTeX document is fairly memory intensive. The PDF Viewer option only supports *nix systems with the GNU tool which to check for executables. REQUIREMENTS Quite a few CPAN Perl modules are required. You'll see @INCL error messages if any of these are missing. Install them from repos, e.g., run (as su), # perl -MCPAN -e shell and at the cpan> prompt install the packages, e.g., to get the highly useful Getopt package, cpan> install Getopt:Mixed You will need (minimally) pdfsam-console pdftk and the CTAN packages, xr hyperref zref-xr zref-abspage zref-thepage in order to cleanly separate chapters with page number continuity and working external links. And of course you will already have a TeX distro of some sort, with pdflatex etc. Subroutines makeMainEdition and makeAltEdition These are subroutines for bundling plain latex builds --- whole thing, not just single chapters but without any \includeonly{...} editing, just build "as is". Purpose is to eliminate need for Makefiles. This project is too simple to require Makefile power. Requires This is just a local packaging of stuff to do, so it uses global variables and a hard-coded regex. Usage makeAltEdition uses the strings $edition_main and $edition_alt to make appropriate replacement file names for the alternative edition of the book. By default I also make a substitution teachertrue --> teacherfalse for the alternate edition, since this was original the purpose of the alternate book, a studnet edition of the volume with all the solutions. I'm sorry a user might have to alter this to suit their needs. But I am not going to automate this script to handle arbitrary edition idiosyncracies. As far as I am concerned, there are just two editions for a LaTeX project, the teachers and the students! Subroutine hashKeyNum Allows a hash table to be accessed like an ordered array. See also Subroutine hashValNum. Requires Tie::IxHash; Usage tie my %hitems, 'Tie::IxHash'; %hitems = ( "KeyA", "a", "KeyB", "b", "KeyC","c" ); print "Hash table key[0] = ".&hashKeyNum(0, %hitems)."\n"; # will print 'Hash table key[0] = 'KeyA' Subroutine hashValNum Allows a hash table to be accessed like an ordered array. See also Subroutine hashKeyNum. Requires Tie::IxHash; Usage tie my %hitems, 'Tie::IxHash'; %hitems = ( "KeyA", "a", "KeyB", "b", "KeyC","c" ); print "Hash table key[0] = ".&hashKeyVal(0, %hitems)."\n"; # will print 'Hash table value[0] = "a" INFO TODO 1. The PDF annotations are not liked by the evince reader, but okular does not complain. Not sure what the problem is. 2. One the other hand okular does not open externally linked PDF documents in a separate windwo, whreas evince does, so evince is better here. Some other things to improve are noted in comments in the script. Collect Frontpieces and Backpieces At the moment pdfsam-consolve separates all the top level TOC parts. But it would be nice to merge back, (1) the Titlepage+TOC, with the Manfesto and Introduction (as the single frontspiece) and then also (2) the Acknowledgements and Bibliography (as thesingle backpiece). But then this would break the TOC hyperlinking. So I haven't yet figured this out. AUTHOR Bijou M. Smith <achrononmaster@gmail.com> COPYRIGHT AND DISCLAIMER This program is Copyright 2014 by Bijou M. Smith . This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 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. See the GNU General Public License for more details. If you do not have a copy of the GNU General Public License write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Alternatively, you can access it over the web at http://www.gnu.org/licenses/gpl.html.
Source: README, updated 2014-06-19

Thanks for helping keep SourceForge clean.

Screenshot instructions:
Red Hat Linux   Ubuntu

Click URL instructions:
Right-click on ad, choose "Copy Link", then paste here →
(This may not be possible with some types of ads)

More information about our ad policies

Briefly describe the problem (required):

Upload screenshot of ad (required):
Select a file, or drag & drop file here.

Please provide the ad click URL, if possible:

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks