Inconsistencies in edit-config/config-file documentation involving plist files
- Dominant language
- JavaScript
- Stars
- 353
- Forks
- 565
- Avg merge
- 7h 15m
- Merged PRs (30d)
- 5
Description
# Bug Report
## Problem
plist files are handled differently than XML files when used as the target of an `edit-config` or `config-file` tag (see https://github.com/apache/cordova-ios/issues/613#issuecomment-560923150 for details). In short: the tag content is matched and merged into the target node. That behavior is actually the same, whether you use an `edit-config` or `config-file` tag and it also does not change with the mode of the `edit-config` tag. And to make things worse, this behavior is _different_ from the behavior of any of those tag variants when working with normal XML files.
There [are](https://cordova.apache.org/docs/en/9.x/reference/cordova-plugin-camera/index.html) [various](https://cordova.apache.org/docs/en/9.x/reference/cordova-plugin-media-capture/index.html) [core](https://cordova.apache.org/docs/en/9.x/reference/cordova-plugin-media/index.html) [plugins](https://cordova.apache.org/docs/en/9.x/reference/cordova-plugin-geolocation/index.html) that use `` in their docs. At first it seems a natural choice, since `edit-config` and `merge` is exactly what is going to happen. However, `edit-config` actually only edits _attributes_ for other XML files. This is also clearly stated in [its docs](https://cordova.apache.org/docs/en/9.x/plugin_ref/spec.html#edit-config).
This has been the source of some confusion (see https://github.com/apache/cordova-ios/issues/613 and https://github.com/apache/cordova-cli/issues/496), as people expected to be able to change the `mode` to achieve a different result. But as stated above that is not possible.
So I think the current situation needs to be documented more clearly and consistently.
Contributor guide
Research direction
Start with the edit-config section at docs/en/9.x/plugin_ref/spec.html#edit-config and compare its XML behavior with the plist examples in the cordova-plugin-camera, media-capture, media, and geolocation documentation. Clarify how edit-config and config-file behave for plist and XML targets, including whether edit-config modes change the result; done means the documentation is consistent and removes the reported ambiguity.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100