Interpretation of generate.copy.outer and outer.control when input file is a topic rather than a map

[kirkilj]

The doc descriptions for generate.copy.outer and outer.control refer to "content [that] is located outside the directory containing the DITA map". See doc section here.

But what happens if the input file is a single topic instead of a DITA map? Should the documentation be reworded from "containing the DITA map" to "containing the input file"? Are the same outer conditions applied when the input file is a map vs a topic?

I'm trying to use the --resource parameter to point to a variables.ditamap that is higher in the directory hierarchy than the topic I'm trying to render. Our topics can be nested quite deeply in a directory structure, but the resource maps are often near the top of the hierarchy. I'm getting different types of errors if running from the command line or from within Oxygen. I'm still doing more testing today, but if anyone has any knowledge of the intended behavior for topic-only builds, I'd appreciate your perspective.

[raducoravu]

@kirkilj can you reproduce the problem if you put together a very small sample DITA project?
The Oxygen transformation scenarios have in the Parameters list a param named fix.external.refs.com.oxygenxml parameter. Does enabling this parameter seem to help?
Other than that the DITA OT bundled with Oxygen has various patches, we officially name it the "Oxygen Publishing Engine" as it would be incorrect to name it the DITA OT because it has extra plugins, patches so it may have different behaviors when publishing.

[kirkilj]

@raducoravu, using Oxygen's HTML5 transform with:

args.resources=${rootMapFile}
fix.eternal.refs.com.oxygenxml=false
generate.copy.outer=3
outer.control=fail

it rendered the attached project successfully for both the sample_simple_topic.dita and sample_complex_topic.dita. It worked if either sample_document.ditamap or sample_variables.ditamap was in focus in the DITA Maps Manager.

If I set generate.copy.outer to 1, it failed the build reporting the out of directory scope error.

Question: The fix.external.refs was not needed in this case, so is it meant for other cases besides resource files?

If I set generate.copy.outer to 1, it failed the build reporting the out of directory scope error.

So it looks to me like generate.copy.outer is also needed for --resource attributes and that the OT documentation should replace "containing the DITA map" to "containing the input file, whether it be a map or an individual topic"

Attachment: dt-projtest.zip

[raducoravu]

@kirkilj I can reproduce your findings.
You can also publish using outer.control=warn and generate.copy.outer=1.
About:

 The fix.external.refs was not needed in this case, so is it meant for other cases besides resource files?

This is an Oxygen specific publishing parameters (works only when publishing from Oxygen, does not work from the command line) and it's mostly to handle cases when the DITA map is not on the topmost level of the folder hierarchy:
https://www.oxygenxml.com/doc/versions/25.1/ug-editor/topics/dita-ot-external-refs.html

[jelovirt]

This works a bit differently in preprocess and preprocess2. The old preprocess with resource files doesn't seem to respect generate.copy.outer correctly, but e.g. in this example case it will copy images to outer directory, which is kinda correct because otherwise the output would be broken. The processing is a bit inconsistent here 🤷🏽

Regardless of the bugs, @infotexture you decide if you want to fix the documentation to say "directory containing the DITA map" or "directory containing the input file". The most correct wording would in "input resource", but end users may understand "DITA map" more easily.

[infotexture]

Updated parameter descriptions in #4211.