summaryrefslogtreecommitdiff
path: root/support/de-macro/user-guide.tex
blob: 0fc17a32e3f2efc9683bf58e7cfc63d57a4e1aaf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
\documentclass[11pt]{article}

\topmargin=0in
\oddsidemargin=0.25in
\evensidemargin=0.25in
\textwidth=6in
\textheight=8in

\setlength{\vfuzz}{4pt} % to ignore trivial vertical overfull boxes
\sloppy

\usepackage[noBBpl]{mathpazo}
\usepackage{enumerate}

 \begin{document}

 \title{DE-MACRO}

 \author{Copyright 2005-2007 P\'eter G\'acs\\
Licensed under the Academic Free Licence version 2.1}

\maketitle

Version 1.3 - this version is much more conservative about deleting
              comments and inserting or deleting blank space: tries to
              leave in all comments, adds space only when necessary, and
              tries not to delete space in the main text.
              The motivating comments came from Daniel Webb.

Version 1.2 - a syntactical bug corrected, thanks Brian de Alwis!
 
 \section*{Purpose}

This program can eliminate most private macros from a LaTeX file.
Applications:
 \begin{enumerate}[--]
  \item your publisher has difficulty dealing with many private macros
  \item you cooperate with colleagues who do not understand your macros
  \item preprocessing before a system like latex2html, which is somewhat
    unpredictable with private macros.
 \end{enumerate}
 
 \section*{Platform}

This is a Python program, which I only have tried to run under Unix.  
But the Unix dependence is minimal (for example all the directory path
references are platform-independent).  
It should be easy to adapt the
program to Windows, and also to avoid command-line arguments.

In case your Python is not in \verb`/usr/bin`, you should change the
top line (the "shebang" line) of the program accordingly.
This top line uses the \verb`-O` option for python (stands for ``optimize'').
Without it, the program may run too slowly.  
If you do not care for speed,
a number of other complications (the database, the checking for newer
versions) could be eliminated.

 \section*{Usage}

Command line:
 \begin{verbatim}
 de-macro [--defs <defs-db>] <tex-file-1>[.tex] [<tex-file-2>[.tex] ...]
 \end{verbatim}
{\bfseries Simplest example:}  \verb`de-macro testament`\\[0pt]
(As you see, the \verb`<>` is used only in the notation of this
documentation, you should not type it.)

If \verb`<tex-file-i>` contains a command 
\verb`\usepackage{<defs-file>-private}`
then the file \verb`<defs-file>-private.sty` 
will be read, and its macros will be
replaced  in \verb`<tex-file-i>` with their definitions.
The result is in \verb`<tex-file-i>-clean.tex`.

Only \verb`newcommand`, \verb`renewcommand`, 
\verb`newenvironment` and \verb`renewenvironment` are
understood (it does not matter, whether you write \verb`new` or
\verb`renew`). 
These can be nested but do not be too clever, since I do not
guarantee the same expansion order as in TeX.

 \section*{Files}

 \begin{verbatim}
<tex-file-1>.db
<tex-file>-clean.tex
<defs-file>-private.sty
 \end{verbatim}
For speed, a macro database file called \verb`<defs-file>.db` is created.
If such a file exists already then it is used.
If \verb`<defs-file>-private.sty` is older than \verb`<tex-file-1>.db` 
then it will not be used.

It is possible to specify another database filename via \verb`--defs <defs-db>`.
Then \verb`<defs-db>.db` will be used.

(Warning: with some Python versions and/or Unix platforms, the database
file name conventions may be different from what is said here.)

For each \verb`<tex-file-i>`, a file \verb`<tex-file-i>-clean.tex`
will be produced.
If \verb`<tex-file-i>-clean.tex` is newer than \verb`<tex-file-i>.tex` 
then it stays.

 \section*{Input command}

If a tex file contains a command \verb`\input{<tex-file-j>}` or 
\verb`\input <tex-file-j>`
then \verb`<tex-file-j>.tex` is processed recursively, and 
\verb`<tex-file-j>-clean.tex` will be inserted into the final output.
For speed, if \verb`<tex-file-j>-clean.tex` is newer than
\verb`<tex-file-j>.tex` then \verb`<tex-file-j>.tex` will not be
reprocessed. 

The dependency checking is not sophisticated, so if you rewrite some macros
then remove all \verb`*-clean.tex` files!

 \end{document}