Adding doc around parsing and YAML (gopasspw#2244)

RELEASE_NOTES=[DOCUMENTATION] Adding doc about YAML entries and unsafe-keys

Fixes gopasspw#1940

Signed-off-by: Yolan Romailler <anomalroil@users.noreply.github.com>

docs/commands/show.md

@@ -78,7 +78,6 @@ The secrets are split into 3 categories:
     will be parsed into (with `safecontent` enabled):
    ```
     and: the keys are separated from their value by :
-    password: ******
     where: the first line is the password
 
 
@@ -103,11 +102,30 @@ The secrets are split into 3 categories:
     bill-to: map[family:Doe given:Bob]
     date: 2001-01-23 00:00:00 +0000 UTC
     invoice: 83
-    password: *****
     ship-to: map[family:Doe given:Bob]
     ```
    Note how the `0123` is interpreted as octal for 83. If you want to store a string made of digits such as a numerical
    username, it should be enclosed in string delimiters: `username: "0123"` will always be parsed as the string `0123`
    and not as octal.
 
+Both the key-value and the YAML format support so-called "unsafe-keys", which is a key-value that allows you to specify keys that should be hidden when using `gopass show` with `gopass config safecontent` set to true.
+E.g:
+```
+supersecret
+---
+age: 27
+secret: The rabbit outran the tortoise
+name: John Smith
+unsafe-keys: age,secret
+```
+will display (with safecontent enabled):
+``` 
+age: *****
+name: John Smith
+secret: *****
+unsafe-keys: age,secret
+
+```
+unless it is called with `gopass show -n` that would disable parsing of the body, but still hide the password, or `gopass show -f` that would show everything that was hidden, including the password.
+
 Notice that if the option `parsing` is disabled in the config, then all secrets are handled as plain secrets.

docs/features.md

@@ -168,7 +168,7 @@ secret1234
 otpauth://totp/golang.org:gopher?secret=ABC123
 ```
 
-Alternatively, you can use YAML (currently totp only):
+Alternatively, you can use YAML (notice the usage of the YAML separator to indicate it is a YAML secret):
 
 ```
 gopass show golang.org/gopher
@@ -375,9 +375,7 @@ Commands that support the `--store` flag:
 
 ### Directly edit structured secrets aka. YAML support
 
-Warning: YAML support is deprecated.
-
-gopass supports directly editing structured secrets (simple key-value maps or YAML).
+gopass supports directly editing structured secrets (simple key-value maps):
 
 ```bash
 $ gopass generate -n foo/bar 12
@@ -393,11 +391,30 @@ $ gopass foo/bar
 baz: zab
 ```
 
+Or even YAML:
+```bash
+secret1234
+---
+multi: |
+    text
+    more text
+octal: 0123
+date   : 2001-01-23
+bill-to: &id001
+    given  : Bob
+    family : Doe
+ship-to: *id001
+```
+
+Note that YAML entries currently support only one YAML block and **must start with the separator** `---` after the password and body text, if any. We do not support comments directly after the separator.
+
 Please note that gopass will try to leave your secret as is whenever possible,
 but as soon as you mutate the YAML content through gopass, i.e. `gopass insert secret key`,
-it will employ an YAML marshaler that may alter the order and escaping of your
+it will employ a YAML marshaler that may alter the order and escaping of your
 entries.
 
+See also [gopass show doc entry](/docs/commands/show.md#parsing-and-secrets) for more information about parsing and how to disable it.
+
 ### Edit the Config
 
 gopass allows editing the config from the command-line. This is similar to how git handles config changes through the command-line. Any change will be written to the configured gopass config file.