This tortured and broken sentence in the docs cost me hours of troubleshooting.

### Describe your use-case which is not covered by existing documentation. I've just spent a few hours pouring over whatever documentation I could find and permuting my `build.gradle` trying to get shadow to merge several `META-INF/hk2-locator/default` files in a way that doesn't break their syntax. Getting ServiceFileTransformer to combine them was easy enough, but the empty lines between groups of entries in h2k-locator files are semantically significant, and ServiceFileTransformer does not preserve them. > The [ResourceTransformer](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-resource-transformer/)s like [ServiceFileTransformer](https://gradleup.com/shadow/api/shadow/com.github.jengelman.gradle.plugins.shadow.transformers/-service-file-transformer/) will not work as expected as the duplicate resource files fed for them are excluded beforehand. However, this behavior might be what you expected for duplicate foo/bar files, preventing them from being included. [from configuration/merging](https://gradleup.com/shadow/configuration/merging/) On my several passes through the documentation, I read this to mean that `DuplicatesStrategy` should not be used with `ResourceTransformer`s that merge files, as they somehow interfere with eachother. None of the usages I could find of the transformers appeared to combine `append` with `duplicatesStrategy = DuplicatesStrategy.INCLUDE`, and thanks to this section of the documentation counter-indicating combining duplicatesStrategy with "transformers like ServiceFileTransformer" I didn't think to try it. I was finally working on just writing a bespoke transformer implementation when I got a strange feeling and decided to just try doing the opposite of what the docs seem to say here, and low and behold: ``` tasks.named('shadowJar', com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar) { filesMatching ('META-INF/hk2-locator/default') { duplicatesStrategy = DuplicatesStrategy.INCLUDE } append 'META-INF/hk2-locator/default' } ``` was exactly what I needed. ### Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration. _No response_ ### Are you interested in contributing to the documentation? I'd write a pull request fixing the docs, but this whole experience has left me so confused that I'm still not sure I 100% understand the behavior here, beyond the fact that this specific incantation I came up with works. Am I missing something?