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

Question

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
    README
    ...
〈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?

Answer 1

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

CTAN upload

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
    README → 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.