For development, am I missing anything by testing with "src/main/bin/dita"?

[chrispy-snps]

In a cloned DITA-OT repository, after I run the following commands:

./gradlew
./gradlew dist

there is a .zip file built at the following path:

./build/distributions/dita-ot-${VERSION}.zip

The DITA-OT in this .zip file includes both the native and bundled plugins:

$ ./build/distributions/dita-ot-3.7.3/bin/dita plugins
org.dita.base
org.dita.eclipsehelp
org.dita.html5
org.dita.htmlhelp
org.dita.index
org.dita.normalize
org.dita.pdf2
org.dita.pdf2.axf
org.dita.pdf2.fop
org.dita.pdf2.xep
org.dita.specialization.dita11
org.dita.xhtml
org.lwdita
org.oasis-open.dita.techcomm.v2_0
org.oasis-open.dita.v1_2
org.oasis-open.dita.v1_3
org.oasis-open.dita.v2_0
org.oasis-open.xdita.v0_2_2

but the src/main/dita command in the DITA-OT repository directory includes only the native plugins:

$ ./src/main/bin/dita plugins
org.dita.base
org.dita.html5
org.dita.htmlhelp
org.dita.pdf2
org.dita.pdf2.fop
org.dita.xhtml
org.oasis-open.dita.v1_3

When I was testing a fix for #4017, I found that src/main/dita rendered <indexterm> elements directly into in the pdf2 PDF output (possibly because the org.dita.index plugin was missing?), but the DITA-OT distribution in the .zip file handled them properly. So I had to repeatedly unarchive and use the .zip file distribution to develop and test the fix.

I previously thought that src/main/dita was a complete representation of the resulting DITA-OT distribution, but that seems to be incorrect. Is there a way to augment src/main/dita to match the full DITA-OT distribution? Or is it a best practice to always unarchive the distribution .zip file and use that for testing fixes?

Thanks!

[infotexture]

Is there a way to augment src/main/dita to match the full DITA-OT distribution?
Or is it a best practice to always unarchive the distribution .zip file and use that for testing fixes?

You can either Use a fresh worktree for distribution builds, or install each of the bundled plug-ins manually via src/main/bin/dita install <plug-in> to test in your local clone without running the distribution build.

If you install the bundled plug-ins this way, they'll appear in your local clone as untracked files
— which should not be committed.

You can add them to a local exclude file with entries like this:

# Ignore entries for 'bundled' external plugins per `build.gradle`
# https://github.com/dita-ot/dita-ot/blob/develop/build.gradle#L181-L191
# These are installed into distribution builds when `gradle dist` runs, but no longer included in the repo
# For local use with `src/main/bin/dita`, each must be installed with `dita install`
src/main/plugins/org.dita.eclipsehelp
src/main/plugins/org.lwdita
src/main/plugins/org.dita.normalize
src/main/plugins/org.dita.specialization.dita11
src/main/plugins/org.oasis-open.dita.v1_2
src/main/plugins/org.oasis-open.dita.v2_0
src/main/plugins/org.oasis-open.dita.techcomm.v2_0
src/main/plugins/org.oasis-open.xdita.*
src/main/plugins/org.dita.index
src/main/plugins/org.dita.pdf2.axf
src/main/plugins/org.dita.pdf2.xep

Details on .git/info/exclude

See git-scm.com/docs/gitignore:

Patterns which are specific to a particular repository but which do not need to be shared with other related repositories (e.g., auxiliary files that live inside the repository but are specific to one user’s workflow) should go into the $GIT_DIR/info/exclude file.

[infotexture]

🎗️ Keep in mind that if you install bundled plug-ins into your clone like this, you'll need to remove and re-install them to pick up any later changes to these plug-ins, as they aren't updated with the usual Git mechanisms.

[chrispy-snps]

@infotexture - thank you! Now I understand what's happening.

After gradlew dist completes, it looks like I should be running my testcases against build/tmp/dist/bin/dita instead of src/main/bin/dita if functionality from the bundled plugins is needed.

The worktree stuff is pretty cool. I have been using git clean -fdx to completely clean the repository to the current HEAD state, but creating a separate worktree allows me to keep any temporary/working files in place.