# What path provide in a .dtx file (located in source/ folder) to reach files located in doc/ folder?

For a class I want to upload on CTAN, I'd like the provided files to be organized as follows when installed by TeX distributions:

``````〈ROOT PATH〉/doc/latex/myclass/
myclass.pdf
sample/sample.tex
sample/sample.pdf
...
〈ROOT PATH〉/tex/latex/myclass/
myclass.cls
...
〈ROOT PATH〉/source/latex/myclass
myclass.dtx
myclass.ins
...
``````

where `〈ROOT PATH〉` will be the TeX distribution root path.

The source documentation file, `〈ROOT PATH〉/source/latex/myclass/myclass.dtx`, contains some code examples and "screenshots" coming from the auxiliary files:

• `〈ROOT PATH〉/doc/latex/myclass/sample/sample.tex`
• `〈ROOT PATH〉/doc/latex/myclass/sample/sample.pdf`

For maintenance reasons of the class' development version, these code examples and "screenshots" are directly imported in the `myclass.dtx` source file from the `sample.tex` and `sample.pdf` auxiliary files, thanks to something like:

``````\lstinputlisting[linerange=...-...]{〈hard coded ROOT PATH〉/doc/latex/myclass/sample/sample.pdf}
...
\includegraphics[page=...]{〈hard coded ROOT PATH〉/doc/latex/myclass/sample/sample.pdf}
``````

where `〈hard coded ROOT PATH〉` is my own `texmf` tree. This works pretty well.

The trouble is that, when distributed by TeX distributions, this workflow will fail because, AFAIU, I'm likely unable to anticipate what TeX distribution `〈hard coded ROOT PATH〉` should be specified in `\lstinputlisting` and `\includegraphics` above, as it depends on:

• the TeX distributions,
• the OS.

Hence the user couldn't pro­duc­e the doc­u­men­ta­tion by run­ning the `.dtx` file.

Do you see a way to circumvent this problem?

## Unpacking

As far as I see the source is

``````myclass.dtx
``````

Optionally a docstrip installation file can be provided:

``````myclass.ins
``````

In my packages the `.ins` file is embedded in the `.dtx` file anyway and I added an engine switch in `myclass.dtx`: If plain TeX is used, then the installation driver (`myclass.ins`) is triggered and the files unpacked. LaTeX on the other hand generates the documentation.

Then the `docstrip` run generates:

``````myclass.cls
sample.tex
myclass.drv % documentation driver
myclass.ins % install driver
``````

## Building the documentation

When the documentation is build, first `sample.pdf` is generated, e.g.:

``````pdflatex sample
% further runs of pdflatex, makeindex, biber, ...
% as needed to generate the final sample.
% (This also can serve as test for some basic features of the class.)
``````

Then we have the prerequisites in the working directory:

``````sample.tex
sample.pdf
``````

And `myclass.dtx` only uses the file names:

``````\lstinputlisting[linerange=...-...]{sample.tex}
\includegraphics[page=...]{sample.pdf}
``````

The main documentation is compiled:

``````pdflatex myclass.drv
% pdflatex, makeindex, biber, bibtex, ...
``````

## TDS installation

In the next step the files are sorted into the TDS tree:

``````myclass.dtx → TDS:source/latex/myclass/myclass.dtx
myclass.ins → TDS:source/latex/myclass/myclass.ins
myclass.cls → TDS:tex/latex/myclass/myclass.cls
myclass.pdf → TDS:doc/latex/myclass/myclass.pdf
``````

If there are many sample files:

``````sample.tex  → TDS:doc/latex/myclass/sample/sample.tex
sample.pdf  → TDS:doc/latex/myclass/sample/sample.pdf
``````

For just two sample files, I consider a separate directory for samples an unnecessary complication:

``````sample.tex  → TDS:doc/latex/myclass/sample.tex
sample.pdf  → TDS:doc/latex/myclass/sample.pdf
``````

If the `TDS:` is an empty directory `texmf`, then you can easily generate `myclass.tds.zip` for CTAN:install/macros/latex/contrib/myclass.tds.zip:

``````(cd texmf && zip -9r ../myclass.tds.zip *)
``````

For the CTAN upload, you will need a fresh directory `myclass`. There goes the files that should appear in `CTAN:macros/latex/contrib/myclass/`, eg.:

``````cp myclass.{dtx,ins,pdf} myclass/
``````

Also a file `README` is preferred by CTAN. Unhappily docstrip (TeX) cannot easily generate file names without extension, because the default extension `.tex` kicks in: * Thus `README` can be a separate file that goes into:

``````    README → TDS:doc/latex/myclass/README
``````
• If it should be embedded into the `.dtx` file, then it could be named `readme.txt` or `00readme.txt` and renamed for CTAN, e.g.:

``````00readme.txt → myclass/README
``````

Now all components for the CTAN upload are present to generate `myclass.zip` for the upload:

``````zip -9r myclass.zip myclass/ myclass.tds.zip
``````

## Remarks

• The user, who only wants to regenerate the documentation starts with the initial steps, until `myclass.pdf` is build.

• Also I would avoid installed files of `myclass` for compiling the documentation. Otherwise the risk rises that files from an older `myclass` installation with a different version are used by accident.

• @DenisBitouzé: Most `.dtx` files I have seen contain a docstrip tag section `%<*driver>` ... `%</driver>` that is written by the `.ins` file to a file `.drv` and contains the code to generate the documentation (`\documentclass{ltxdoc}`...). But generating a separate `.drv` file is not necessarily mandatory. – Heiko Oberdiek May 24 '14 at 14:24