General ⇒ Including tex files

[davidcollins001]

Thanks for your replies.

I have read through those links and there is some good stuff to note. I really wanted to make sure that I wasn't missing out on a standard and easy way of doing things but it seems like there isn't any particular way that is easiest.

At the moment I have each chapter folder in the root folder with each chapters images in that chapter.I thought the images was going to be a pain to get to work so I could test a chapter or the whole document with out changing anything. My solution is to use "make" to compile the document. Each chapter has its own Makefile that calls the root Makefile but only compiles itself, but calling the root Makefile compiles the whole document.

David

[Ted]

The problem is that TeX will resolve file paths relative to the main input file (or rather to the current working directory). This of course will create problems if you have nested directory structure and want to use just a part of it (like chapter1 subdirectory). And you can't change the working directory from within your source file, AFAIK.

The solution to this, that I found to be workable, is to keep everything in 1-level deep directory structure.

I'm really shocked that no one has mentioned the import package, which is the standard way to handle this problem in LaTeX. This package is a required part of any LaTeX distribution. It's old and written by one of the major LaTeX contributors, Donald Arseneau.

http://www.ctan.org/tex-archive/help/Ca ... mport.html

The package introduces an \import{path}{file} to replace \input{path/file}. Within file, all calls to \input, \include, and \includegraphics will be relative to its own directory. You can use a \subimport command within that file if you have even more nested directories.

Similarly, there is an \includefrom{path}{file} that works like \include{path/file}.

See the top of import.sty on your own system for its official documentation. On my OS X system, I can execute:

Code: Select all

locate import.sty|head -1|xargs less

to view it. If you're on a Windows system, you just have to find where your packages are stored and open it with a text editor. However, it's very straightforward to use. You probably won't need to consult the documentation.

It really is the standard way of solving this problem.

[T3.]

Hi Ted,
Thanks for your contribution to this thread.

I'm really shocked that no one has mentioned the import package, which is the standard way to handle this problem in LaTeX. This package is a required part of any LaTeX distribution. It's old and written by one of the major LaTeX contributors, Donald Arseneau.

I know about this package but I think that it actually adds more complexity to the project management than it solves, so I don't feel that positive about recommending it. Here are some reservations that I have about it:

• while it comes together with all the major distributions, at least according to this site it's not one of the standard packages;
• some editors parse sources for input and include commands to provide easy access to project files - I doubt that there is even one looking for import commands
• for nested imports you have to use different command (subimport); this is rather inconvenient, I would even say that it defeats the whole purpose of this package;
• the only documentation for this package is the package .sty file itself (rather unusual for a "standard" package);
• I very rarely see this package mentioned and even more seldom hear that someone actually uses it; I don't know of any textbook (even for advanced users) that would even metion this package, so calling it the standard solution is a little bit of a stretch.

I think that it is much easier to make use of TEXINPUTS approach than import package. The only drawbacks are that your sources don't compile straight away if you send them to somebody else and most editors (if not all) don't make use of TEXINPUTS variable when searching for files. In the former case I found an easy soulution - just zip everything without retaining the directory structure. After unzipping all the files will be in the same directory so TeX will have no problem finding them (but for a large project there might be hundreds of them so this is far from perfect as well).

Cheers,

Tomek

[Stefan Kottwitz]

Hi Ted,

On my OS X system, I can execute:

Code: Select all

locate import.sty|head -1|xargs less

to view it.

Usually I write

Code: Select all

less `kpsewhich import.sty`

for this purpose. kpsewhich finds the file that TeX uses, locate ... |head -1 may find a different file if there exist more than one. Because of the backticks I don't need xargs.

Stefan

[Ted]

Hi Ted,

Code: Select all

locate import.sty|head -1|xargs less

Usually I write

Code: Select all

less `kpsewhich import.sty`

for this purpose. kpsewhich finds the file that TeX uses, locate ... |head -1 may find a different file if there exist more than one. Because of the backticks I don't need xargs.

I specifically use xargs in order to avoid the use of backticks.

I make use of several TeX distributions, and kpsewhich is only going to care about whichever one I've got linked as active. That doesn't help me when one distribution doesn't include something that I need.

[Ted]

• I very rarely see this package mentioned and even more seldom hear that someone actually uses it; I don't know of any textbook (even for advanced users) that would even metion this package, so calling it the standard solution is a little bit of a stretch.

I think that it is much easier to make use of TEXINPUTS approach than import package.

See the official TeX FAQ for information on the use of the package. It specifically mentions it as a BETTER alternative to using TEXINPUTS.

• TeX FAQ: Bits of document from other directories

That FAQ page discourages people from using TEXINPUTS (the "path extension" technique) for this purpose:

It may be appropriate to use the “path extension” technique used in temporary installations to deal with this problem. However, if there several files with the same name in your document, such as chapter1/fig1.eps and chapter2/fig1.eps, you’re not giving TeX any hint as to which you’re referring to when in the main chapter file you say \input{sect1}; while this is readily soluble in the case of human-prepared files (just don’t name them all the same), automatically produced files have a way of having repetitious names, and changing them is a procedure prone to error.

Additionally, that FAQ page introduces the chapterfolder package:

http://ctan.org/pkg/chapterfolder

chapterfolder introduces commands like \cfpart and \cfsection which work just like \part and \section but include a file from a subdirectory and then setup that subdirectory as the "current directory" for that file.

Regarding your other comments, both of these packages have long been a part of TeXLive and the other popular distributions. They're well known among the central TeX community, and they provide elegant solutions. Also, if you think about it, I think you'll see why commands like \subimport were included for flexibility.

[T3.]

Ted,

You bring a valid point about auto-generated file names. However, to be fair it should be mentioned that the basic \import and \subimport commands suffer from the same problem. From import.sty:

% Depending on on how your \TeX\ system is configured, if a file with the
% same name as the import file exists in the current directory or in the
% TEXINPUTS path, that other file will be read in preference to one in the
% import directory.
[...]
% To avoid searching the TEXINPUTS path when importing files, use the `star'
% versions of the commands: "\import*" and "\subimport*".

So there are eight commands provided in total (when counting starred variants; \includefrom* and \subincludefrom* are defiend as well even though they are not mentioned in the documentation) instead of (or shall I say in addition to) the traditional two: \input and \include. You say that this is for the added flexibility but it makes things even more confusing. But this is not the worst part.

Prompted by your arguments I did some experimentation with the import package to find out if it is really a superior approach. Here are some problems I've noticed:

If I use \includefrom on a file that have a full path input '\input{F:/temp/dir1/dir2/file}' it fails with "! LaTeX Error: File `F:/temp/dir1/dir2/file.tex' not found" even though this file exists (but with '\input F:/temp/dir1/dir2/file' it doesn't fail). Why? Using either \import or \subimport instead of \includefrom works.

The worst, however, is this: if I have a main file with '\import{dir1/}{foo}' and 'foo.tex' contains '\subimport{dir2/}{bar}' but the file 'dir1/dir2/bar.tex' does not exist and instead 'dir1/bar.tex' exists then, rather than get an error about missing file, this 'dir1/bar.tex' gets picked up! This happens also for the starred versions of the commands. I don't know if this is the expected behaviour but I find it confusing as hell. Why 'dir1' is even searched for 'bar.tex'? It's not a working directory nor it is specified in TEXINPUTS.

What are your thoughts about this? Do you still feel that this package is worth recommending? Do you use it yourself and have you encountered any such problems?

Cheers,

Tomek

Edit:
One more thing. If imported file uses TeX's \input primitive directly as in '\input subdir/file' instead of '\input{subdir/file}' then LaTeX's hooking into \input command is bypassed and consequently the import fails. This caveat is not mentioned in the documentation.

Edit 2: typos and grammar in edit 1

[Ted]

If I use \includefrom on a file that have a full path input '\input{F:/temp/dir1/dir2/file}' it fails with "! LaTeX Error: File `F:/temp/dir1/dir2/file.tex' not found" even though this file exists (but with '\input F:/temp/dir1/dir2/file' it doesn't fail). Why? Using either \import or \subimport instead of \includefrom works.

Do you have minimal code examples? I have no trouble doing

Code: Select all

\includefrom{/Users/tpavlic/temp/}{temp.tex}

Additionally, there is no reason why LaTeX should even care if that file exists (review the LaTeX semantics for \include). If you drill down into the short import.sty, you'll see that the actual file I/O is still done by the standard LaTeX macros.

if I have a main file with '\import{dir1/}{foo}' and 'foo.tex' contains '\subimport{dir2/}{bar}' but the file 'dir1/dir2/bar.tex' does not exist and instead 'dir1/bar.tex' exists then, rather than get an error about missing file, this 'dir1/bar.tex' gets picked up!

I'll grant that I hadn't thought of this case, but if you look at the import.sty, it seems clear that the author intended this behavior. Rather than REPLACING the path, he augments it, and so it still contains the current directory.

I speculate that the author views this as a feature. That is, it lets me continue to import some global things from the root directory. I speculate that the author figured that more conflicts would be caused by the opposite behavior, and overall this feature would hardly ever be noticed either way.

[ I realize that if I wanted to import something from the main directory, I would not use subimport... but maybe the author was considering how things would work if I move things OUT of a subdirectory and back into the main directory (i.e., after realizing that I didn't need the whole subdirectory) ]

I'll post a message on CTT asking for comments about this.

What are your thoughts about this? Do you still feel that this package is worth recommending? Do you use it yourself and have you encountered any such problems?

I don't view these as problems. I think it's a useful package. I think it's implementation is simple, portable, robust, and (nearly) transparent.

Additionally, I think that for most users who are more comfortable with LaTeX than their own operating systems, a solution buried inside their LaTeX source is better than a solution that fits somewhere else. Plus, Windows users are rarely going to use Makefiles, and so I speculate that most would have to play with their global TEXINPUTS variable, and that seems way overkill and not very portable (imagine collaborating on a document -- every author would have to make these hacks).

Did you try playing with chapterfolder? I think import is a great solution for this thread, but maybe chapterfolder is even better.

• http://ctan.org/pkg/chapterfolder

(FYI, notice the "new" format of CTAN package URLs. The CTAN organizers are pushing people to use these (rather than the old long ones))

[T3.]

Do you have minimal code examples? I have no trouble doing

Code: Select all

\includefrom{/Users/tpavlic/temp/}{temp.tex}

My bad here, I had a typo in my test file. It does work OK.

Additionally, there is no reason why LaTeX should even care if that file exists (review the LaTeX semantics for \include). If you drill down into the short import.sty, you'll see that the actual file I/O is still done by the standard LaTeX macros.

One would expect so, however, I've came across a TeX system where '\include{../dir/file}' failed while '\let\include=\input \include{../dir/file}' worked, so you never know.

I'll grant that I hadn't thought of this case, but if you look at the import.sty, it seems clear that the author intended this behavior. Rather than REPLACING the path, he augments it, and so it still contains the current directory.

I speculate that the author views this as a feature.

I call this kind of "features" bugs. And note that the file in my example is not picked up from the current directory but from the location "on the way" to the intended directory. I think that using '\import{dir/}{foo} should be logically equivalent to prefixing with 'dir/' of all the arguments of \input commands in 'foo.tex' (and files loaded by it). If after such an operation compilation would fail then so it should fail with using import. No picking up stuff from current directory or TEXINPUTS path or, God forbid, from some random places "on the way" to the intended location. If the user would want to rely on the current directory or TEXINPUTS then he/she wouldn't use \import command in the first place.

I think it's a useful package. I think it's implementation is simple, portable, robust, and (nearly) transparent.

I agree with the first part but beg to differ with the rest. I had to reread the provided short documentation several times, study the code itself and do some experimentation to figure out what's actually going on. And I'm still not sure that I got to the bottom of it. See also my note added in the edit to the previous post about using \input with braced vs. non-braced argument. I think it's fair to say that it takes a knowledge beyond a novice to troubleshoot something like this.

So in conclusion I would say that it's a useful package but for someone understanding and willing to put up with it's quirks. If you will see my other posts in this thread then you will know that I'm not a big fun of TEXINPUTS either but I find it by far more intuitive then the import package.

Did you try playing with chapterfolder?

No, and I don't think I will. I don't like overly complicated solutions where something much simpler will do. I have a poor memory when it comes to all those LaTeX commands and introducing some new ones will not help.

Cheers,

Tomek

[Ted]

You bring a valid point about auto-generated file names.

Note that having "fig#" type names may not only be due to autogeneration. Several publishing houses require figures to use this naming convention on electronic submission.

One more thing. If imported file uses TeX's \input primitive directly as in '\input subdir/file' instead of '\input{subdir/file}' then LaTeX's hooking into \input command is bypassed and consequently the import fails. This caveat is not mentioned in the documentation.

It makes sense. \input without curly braces is a TeX primitive.

In LaTeX, use of \input without curly braces is deprecated. I'm always surprised when I see users (especially novice users starting on LaTeX as opposed to seasoned users who perhaps started with TeX) omitting the curly braces with \input. That being said, because of the evident preponderance of such users, I agree that this should be mentioned in the documentation. In fact, I agree that the documentation should be completely rewritten in a "proper" form. If CTAN had a more collaborative structure, I'm sure that would have been done by now.

Nevertheless, this whole discussion forgets that many users are going to apply import to inclusion of graphics in chapters and not so much subparts.

I still feel that for the average user, import is straightforward. I feel strongly that it's more straightforward and portable than the other options, especially when collaborating on large documents. For example, I have a Mercurial repository organizing contributions from five different book authors, and some use Windows and others use OS X, and they all use a different development environment. It's hard enough for me to get everyone to configure their respective editing tools to call out to a Makefile (in fact, I decided to not even try it). It's much more attractive for me to confine the subdirectory handling within the main TeX file. Everyone builds it however they like and everything works fine.