Clarify that the output_file directory is relative to the input directory

[billdenney]

I just hit an unexpected issue that appears to be documentation related.

It appears that the directory for the output_file should be relative to the directory of input rather than relative to the current working directory where rmarkdown::render() is run. I think that this could be clarified by adding "The output_dir is relative to the directory for input and not relative to the current directory."

And, that clarification would go about here:

rmarkdown/R/render.R

Lines 171 to 178 in f2bfeec

	#' @param output_file The name of the output file. If using \code{NULL} then the
	#' output filename will be based on filename for the input file. If a filename
	#' is provided, a path to the output file can also be provided. Note that the
	#' \code{output_dir} option allows for specifying the output file path as well,
	#' however, if also specifying the path, the directory must exist. If
	#' \code{output_file} is specified but does not have a file extension, an
	#' extension will be automatically added according to the output format. To
	#' avoid the automatic file extension, put the \code{output_file} value in

[cderv]

"The output_dir is relative to the directory for input and not relative to the current directory."

output_dir is relative to the current directory as setwd() was not yet called on input directory.

rmarkdown/R/render.R

Lines 339 to 345 in f2bfeec

	# resolve output directory before we change the working directory in
	# preparation for rendering the document
	if (!is.null(output_dir)) {
	if (!dir_exists(output_dir))
	dir.create(output_dir, recursive = TRUE)
	output_dir <- normalize_path(output_dir)
	}

It appears that the directory for the output_file should be relative to the directory of input rather than relative to the current working directory where rmarkdown::render() is run.

output_file is relative to the output_dir is this is specified

rmarkdown/R/render.R

Lines 493 to 497 in f2bfeec

	# if an output_dir was specified then concatenate it with the output file
	if (!is.null(output_dir)) {
	output_file <- file.path(output_dir, basename(output_file))
	}
	output_dir <- dirname(output_file)

Paths handling in rmarkdown is quite complex and we have encountered some limitations already (https://github.com/rstudio/rmarkdown/issues?q=is%3Aopen+label%3A%22theme%3A+paths%22+sort%3Aupdated-desc). Technically, there is even nothing that prevents the paths to be absolute too or relative but in a parent folder (e.g ../<dir>), however we've seen with time that paths handling is tricky and using non relative dir / file can cause side effect (example #2024). So it is a recommandation to use dir / files relative to input file, but not mandatory.

I just hit an unexpected issue that appears to be documentation related.

What was the issue exactly ? This may yet be another limitation we have.

[billdenney]

I recognize that file paths are complex here. Having worked on something vaguely similar in the past (though FAR less complex), I know it's nontrivial to keep all the parts moving correctly. (That's why I indicated this as a documentation issue rather than a bug.)

The reprex is below. When I traced the "The directory 'issue2370' does not exist" error, it was looking for an issue2370/issue2370 directory under tempdir().

The thing for me is that I did not specify output_dir, so by my reading of the help, output_file without output_dir should have an output_file location relative to getwd().

This is on Windows 10, R 4.1.2, rmarkdown 2.14.

tempdir()
#> [1] "C:\\Users\\BILLDE~1\\AppData\\Local\\Temp\\Rtmpwdx1y6"
newdir <- file.path(tempdir(), "issue2370")
dir.create(newdir)
setwd(file.path(newdir, ".."))
file_to_create <- "issue2370/foo.Rmd"
cat("---\ntitle: 'Untitled'\nauthor: 'William Denney'\ndate: '2022-06-06'\noutput: pdf_document\n---\n\nfoo\n", file=file_to_create)
rmarkdown::render(input=file_to_create, output_file="issue2370/foo.pdf")
#> Error: The directory 'issue2370' does not not exist.

^{Created on 2022-06-06 by the reprex package (v2.0.1)}

[cderv]

Thanks I'll look into this, and adapt the documentation