Debian Codegraph @

texmf-dist/doc/support/de-macro/user-guide.tex

raw
1 \documentclass[11pt]{article}
2
3 \topmargin=0in
4 \oddsidemargin=0.25in
5 \evensidemargin=0.25in
6 \textwidth=6in
7 \textheight=8in
8
9 \setlength{\vfuzz}{4pt} % to ignore trivial vertical overfull boxes
10 \sloppy
11
12 \usepackage[noBBpl]{mathpazo}
13 \usepackage{enumerate}
14
15 \begin{document}
16
17 \title{DE-MACRO}
18
19 \author{Copyright 2005-2007 P\'eter G\'acs\\
20 Licensed under the Academic Free Licence version 2.1}
21
22 \maketitle
23
24 Version 1.4 - Luca Citi made it python2.7 and python3 compatible.
25 Peter Gacs improved the parsing of \verb`\input{<filename>}`,
26 and made @ a letter in the style files.
27
28 Version 1.3 - this version is much more conservative about deleting
29 comments and inserting or deleting blank space: tries to
30 leave in all comments, adds space only when necessary, and
31 tries not to delete space in the main text.
32 The motivating comments came from Daniel Webb.
33
34 Version 1.2 - a syntactical bug corrected, thanks Brian de Alwis!
35
36 \section*{Purpose}
37
38 This program can eliminate most private macros from a LaTeX file.
39 Applications:
40 \begin{enumerate}[--]
41 \item your publisher has difficulty dealing with many private macros
42 \item you cooperate with colleagues who do not understand your macros
43 \item preprocessing before a system like latex2html, which is somewhat
44 unpredictable with private macros.
45 \end{enumerate}
46
47 \section*{Platform}
48
49 This is a Python program, which I only have tried to run under Unix.
50 But the Unix dependence is minimal (for example all the directory path
51 references are platform-independent).
52 It should be easy to adapt the
53 program to Windows, and also to avoid command-line arguments.
54
55 In case your Python is not in \verb`/usr/bin`, you should change the
56 top line (the "shebang" line) of the program accordingly.
57 This top line uses the \verb`-O` option for python (stands for ``optimize'').
58 Without it, the program may run too slowly.
59 If you do not care for speed,
60 a number of other complications (the database, the checking for newer
61 versions) could be eliminated.
62
63 \section*{Usage}
64
65 Command line:
66 \begin{verbatim}
67 de-macro [--defs <defs-db>] <tex-file-1>[.tex] [<tex-file-2>[.tex] ...]
68 \end{verbatim}
69 {\bfseries Simplest example:} \verb`de-macro testament`\\[0pt]
70 (As you see, the \verb`<>` is used only in the notation of this
71 documentation, you should not type it.)
72
73 If \verb`<tex-file-i>` contains a command
74 \verb`\usepackage{<defs-file>-private}`
75 then the file \verb`<defs-file>-private.sty`
76 will be read, and its macros will be
77 replaced in \verb`<tex-file-i>` with their definitions.
78 The result is in \verb`<tex-file-i>-clean.tex`.
79
80 Only \verb`newcommand`, \verb`renewcommand`,
81 \verb`newenvironment` and \verb`renewenvironment` are
82 understood (it does not matter, whether you write \verb`new` or
83 \verb`renew`).
84 These can be nested but do not be too clever, since I do not
85 guarantee the same expansion order as in TeX.
86
87 \section*{Files}
88
89 \begin{verbatim}
90 <tex-file-1>.db
91 <tex-file>-clean.tex
92 <defs-file>-private.sty
93 \end{verbatim}
94 For speed, a macro database file called \verb`<defs-file>.db` is created.
95 If such a file exists already then it is used.
96 If \verb`<defs-file>-private.sty` is older than \verb`<tex-file-1>.db`
97 then it will not be used.
98
99 It is possible to specify another database filename via \verb`--defs <defs-db>`.
100 Then \verb`<defs-db>.db` will be used.
101
102 (Warning: with some Python versions and/or Unix platforms, the database
103 file name conventions may be different from what is said here.)
104
105 For each \verb`<tex-file-i>`, a file \verb`<tex-file-i>-clean.tex`
106 will be produced.
107 If \verb`<tex-file-i>-clean.tex` is newer than \verb`<tex-file-i>.tex`
108 then it stays.
109
110 \section*{Input command}
111
112 If a tex file contains a command \verb`\input{<tex-file-j>}` or
113 \verb`\input <tex-file-j>`
114 then \verb`<tex-file-j>.tex` is processed recursively, and
115 \verb`<tex-file-j>-clean.tex` will be inserted into the final output.
116 For speed, if \verb`<tex-file-j>-clean.tex` is newer than
117 \verb`<tex-file-j>.tex` then \verb`<tex-file-j>.tex` will not be
118 reprocessed.
119
120 The dependency checking is not sophisticated, so if you rewrite some macros
121 then remove all \verb`*-clean.tex` files!
122
123 \end{document}