latex-makefile and docstrip

[Matthew Leingang]

Hi,

Thanks for writing this makefile. It's astounding.

I keep my sources in docstrip (.dtx) file. It's TeX code with guards
that allow conditional inclusion and exclusion of code. Traditionally
it's used to keep a package's source code and its documentation in the
same file. The documentation can be stripped out and compiled
separately.

But I use it to keep similar files identical except for minor
changes. For instance, an exam and its solutions, or other versions
of the exam with some different numbers, etc. So my .tex files depend
on the .dtx file, and a single tex run on the .dtx file produces all
the .tex files.

How can I integrate this into the latex-makefile's operations? One
method I tried was to use the first run of tex, that produces the tex
files from the dtx files, to also write make rules in another file
that Makefile.ini could include. Then I have to run a configure
script that makes this makefile fragment. Is there a more automatic
way? The documentation for latex-makefile indicates that if
foo.tex.sh is present then foo.tex will depend on foo.tex.sh. But if
foo.dtx produces foo-A.tex and foo-B.tex, what's the best way for make
to know that foo.dtx needs to be texed?

TIA and good day.

Best,
Matthew Leingang

[Chris Monson]

On Tue, Mar 1, 2011 at 7:49 PM, Matthew Leingang <leinga...@gmail.com> wrote:

Hi,

Thanks for writing this makefile.  It's astounding.

Thanks :)

 

I keep my sources in docstrip (.dtx) file.  It's TeX code with guards
that allow conditional inclusion and exclusion of code.  Traditionally
it's used to keep a package's source code and its documentation in the
same file.  The documentation can be stripped out and compiled
separately.

Yeah, I've used those before.  I don't use them for individual works, but I have definitely seen them in the context of package installation, for example.

 

But I use it to keep similar files identical except for minor
changes.  For instance, an exam and its solutions, or other versions
of the exam with some different numbers, etc.  So my .tex files depend
on the .dtx file, and a single tex run on the .dtx file produces all
the .tex files.

Interesting!

 

How can I integrate this into the latex-makefile's operations?  One
method I tried was to use the first run of tex, that produces the tex
files from the dtx files, to also write make rules in another file
that Makefile.ini could include.  Then I have to run a configure
script that makes this makefile fragment.  Is there a more automatic
way?  The documentation for latex-makefile indicates that if
foo.tex.sh is present then foo.tex will depend on foo.tex.sh.  But if
foo.dtx produces foo-A.tex and foo-B.tex, what's the best way for make
to know that foo.dtx needs to be texed?

There are some things we can try, and then depending on what works, we may be able to add native support for this in the makefile.

In your Makefile.ini, you might try doing something like this (make sure to use tabs instead of leading spaces):

# make tex files depend on running docstrip - the cookie might

# not be necessary, but it makes it easy to see what's happening.

file1.tex: docstrip.cookie

file2.tex: docstrip.cookie

file3.tex: docstrip.cookie

# The cookie file is generated by a run of latex on the dtx file, which also has the other side effects above.

docstrip.cookie: mydocstripfile.dtx

  latex mydocstripfile.dtx && touch docstrip.cookie

# Add clean-docstrip as a clean dependency, so that running "make clean" will also run "make clean-docstrip"

clean: clean-docstrip

# Add the clean-docstrip rule that actually removes the cookie file.

# Note that we should probably remove file?.tex as well, but I don't do that here for safety in this test.

.PHONY: clean-docstrip

clean-docstrip:

  rm docstrip.cookie

Now, that should work just fine.  Regarding the .tex.sh approach, that should *also* work... I would need a little more detail on how you are using docstrip to give you a good recommendation there, but I'm pretty sure we can do that.

The disadvantage of using the .tex.sh approach is that there is no dependency detection done, so a change to your .dtx will not automatically trigger a rebuild of the .tex files.  I get around that by *always* building the .tex files, but that means you lose some of the benefit of the makefile in the first place: incremental builds.  So, it's a tradeoff at the moment.  We may very well come up with a good solution for this, though.