apache / apache/cordova-docs

Inconsistencies in edit-config/config-file documentation involving plist files

Open
#1,029 0 comments 2 reactions 0 assignees View on GitHub
bug discussion
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.