[pdftex] Man page for pdftosrc

[Frank Küster]

Dear pdftex developers,

the pdftosrc program included in pdftex has no documentation so far.  A
year ago, Hilmar Preusse has started to write one and asked on this list
about comments on his draft, but unfortunately nobody stepped up to have
a look at it.

May I ask you again to review the attached draft man page?

Many thanks in advance, 
Frank


-- 
Frank Küster
Inst. f. Biochemie der Univ. Zürich
Debian Developer

-------------- next part --------------
.\" Hey, Emacs!  This is an -*- nroff -*- source file.
.\" 
.\" Copyright (C) 2004 Hilmar Preusse <hille42 at web.de>
.\" 
.\" This is free software; you can redistribute it and/or modify it under
.\" the terms of the GNU General Public License as published by the Free
.\" Software Foundation; either version 2, or (at your option) any later
.\" version.
.\" 
.\" This 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.
.\" 
.\" You should have received a copy of the GNU General Public License with
.\" your Debian GNU/Linux system, in /usr/share/common-licenses/GPL, or with
.\" the dpkg source package as the file COPYING.  If not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\" 
.\"
.\" =====================================================================
.\" HELP!!!! I found no convenient way to include the TeX source code
.\" verbatim. If there is a better way to do that, feel free to improve!
.\" =====================================================================
.\"
.\"
.TH "PDFTOSRC" "1" "July 2004" "Debian/GNU Linux" ""
.SH "NAME"
pdftosrc \- extracts stream objects from pdf\-Files.
.SH "SYNOPSIS"
\fBpdftosrc\fR \fI<PDF\-file>\fR [<stream\-object\-number>]
.SH "DESCRIPTION"
A pdf\-file simply consists of a set of different kind of objects,
which are linked to each other and refer to each other. One special
kind of object are stream objects. \fBpdftosrc\fR is written to extract
single stream objects out of a pdf file.
.br 
The idea behind that program is that one can include the TeX-source code
(or parts of it) into the pdf file as stream object.
pdfTeX provides the low level command \fB\\pdfobj\fR to put objects
into a pdf-file. Further there exist \fB\\pdflastobj\fR to return the
number of the object created.
.P
A simple example could look like:
.P
 \\documentclass{minimal}
 \\usepackage{times}

 \\begingroup\\pdfcompresslevel=0
 \\immediate\\pdfobj 
 stream attr {/Type /SourceFile /SourceName 
 (The TeX sources)}
 file{\\jobname.tex}
 \\pdfcatalog{/SourceObject \\the\\pdflastobj\\space 0 R}
 \\endgroup

 \\begin{document}
 test
 \\end{document}
.P
Call "\fBpdftosrc\fR \fI<PDF\-file>\fR 1" to extract the first stream
object, which contains the complete TeX-Code of the compiled pdf.
.br
\\pdfcompresslevel=0 were used to make sure the included streams will
not be compressed (and hence will be unreadable by human) when written
into the pdf\-file. \fBpdftosrc\fR will automatically
uncompress compressed streams, when they are extracted, so this is only
necessary if anybody wants to view at the pdf\-file using a text editor.
.br
\\usepackage{times} were used to get a font, which comes with Acrobat\*R
(and Ghostscript) and to not clutter up the pdf\-file by too much binary
stuff, because no fonts have to be included.
.br 
A more complete example can be found in the section \fBEXAMPLE\fR.
.SH "SEE ALSO"
.BR pdftex (1),
.BR pdflatex (1),
The pdfTeX user manual,
PDF specification by Adobe.
.SH "EXAMPLE"
The example was contributed by C. V. Radhakrishnan and later simplified.
Thanks! Stream 1 is the complete source code. Stream 2-4 are the 3
equations of the document.
.P
 \\documentclass[a4paper]{article}

 \\begingroup\\pdfcompresslevel=0
  \\immediate\\pdfobj
  stream attr {/Type /SourceFile /SourceName
  (The TeX sources)}
  file{\jobname.tex}
  \\pdfcatalog{/SourceObject \\the\\pdflastobj\\space 0 R}
 \\endgroup

 \\begin{document}

 \\pdfcompresslevel=9
 \\makeatletter

 \\def\\keepsrc{%
  \\begingroup\\pdfcompresslevel=0
   \\immediate\\pdfobj
   stream attr {/Type /SourceFile /SourceName
   (The TeX sources)}
   file{tmp.tex}
   \\pdfcatalog{/SourceObject \\the\\pdflastobj\\space 0 R}
  \\endgroup
 }
 \\newwrite\\srcout

 \\long\\def\\srceqn#1{\\def\\next{#1}
  \\immediate\\openout\\srcout=src.tex
  \\immediate\\write\\srcout
   {\\expandafter\\strip at prefix\\meaning\\next}
  \\immediate\\closeout\\srcout
  \\keepsrc
 #1}

 \\makeatother

 \\srceqn{\\[
 a+b=c
 \\]}

 \\srceqn{\\[
 c-a=b
 \\]}

 \\srceqn{\\[
 c-b=a
 \\]}

\\end{document}
.SH "AUTHOR"
This manual page was written by Hilmar Preusse <hille42 at web\&.de>, for
the Debian GNU/Linux system\&.  It may be used by other distributions
without contacting the author\&.  Any mistakes or omissions in the
manual page are my fault; inquiries about or corrections to this
manual page should be directed to me (and not to the primary author)\&.
.SH "THANKS TO"
C. V. Radhakrishnan (for the example code),
Frank K\(:uster.
.\" David H. Silber, 
.\" Carl Streeter.