How to copy docfiles with directory structure respected?

[muzimuzhi]

For large doc target, its supplement files may live in sub-directories like ./image, ./chapters. Currently when specified as docfiles = { "image/*.jpg", "chapters/*.tex" }, the matched files will be copied directly to typesetdir, with a flat directory structure.

This will break usages like \include{chapters/chap01.tex} in doc file. Although this use case can be resolved by appending chapters to \input@path or \l_file_search_path_seq and removing path prefix chapter/, some \input-derived package macros may not respect \input@path yet, among which pgf's \pgfutil@IfFileExists is an example, see #1238.

In pgf-tikz/pgf#1239 (comment) I found specifying just directory names in docfiles seems to work, for example docfiles = { "image", "chapter" }, but not sure if this is officially supported.

Taking ./examples/Simple-Tree in this repository as an example

First, create dummy files ./doc/images/a.jpg and ./doc/images/b.jpg

mkdir doc/images
touch doc/images/a.jpg doc/images/b.jpg

Now the structure of ./doc becomes

doc
├── images
│   ├── a.jpg
│   └── b.jpg
├── simple-tree-doc.pdf
├── simple-tree-doc.tex
└── simple-tree.pdf

• If docfiles = { "images/*.jpg" } is appended to build.lua

  echo 'docfiles      = { "images/*.jpg" }' >> build.lua
  

  then after l3build doc the structure of ./build/doc will be

  build/doc
  ├── a.jpg
  ├── b.jpg
  ├── simple-tree-doc.aux
  ├── simple-tree-doc.log
  ├── simple-tree-doc.pdf
  ├── simple-tree-doc.tex
  ├── simple-tree.aux
  └── ...
  

• If instead docfiles = { "images" } is appended to build.lua

  echo 'docfiles      = { "images" }' >> build.lua
  

  then after l3build doc the structure of ./build/doc will be

  build/doc
  ├── images
  │   ├── a.jpg
  │   └── b.jpg
  ├── simple-tree-doc.aux
  ├── simple-tree-doc.log
  ├── simple-tree-doc.pdf
  ├── simple-tree-doc.tex
  ├── simple-tree.aux
  └── ...
  

[josephwright]

I think that's an artefact of how it's set up, but I'd be happy to document that it works - although the team tend to favour 'flat' structures as that's how TeX works ...