[vcpkg manifest] Add documentation! (#13488)

* [vcpkg docs] add docs for manifest files

These are just for the maintainer docs,
not user docs.

* [vcpkg] EBNF-ify platform expression parsing

this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.

* [vcpkg docs] add manifest mode example

* [wip] docs for augustin

also fix tabs

* [vcpkg manifest] switch to using maps for features

* Apply suggestions from code review

* un-experimentize format-manifest

* flesh out the user manifest mode docs

* CRs

* billy CRs

* final personal pass-thru

2 files changed, 16 insertions, 19 deletions

diff --git a/toolsrc/include/vcpkg/base/json.h b/toolsrc/include/vcpkg/base/json.h
index 54f84f611..66d147918 100644
--- a/toolsrc/include/vcpkg/base/json.h
+++ b/toolsrc/include/vcpkg/base/json.h
@@ -475,6 +475,20 @@ namespace vcpkg::Json
         }
 
         template<class Type>
+        Optional<Type> visit_map_field(StringView key, const Value& value, IDeserializer<Type>& visitor)
+        {
+            m_path.push_back(key);
+            auto res = internal_visit(value, visitor);
+            m_path.pop_back();
+            return std::move(res);
+        }
+        template<class Type>
+        Optional<Type> visit_map_field(StringView key, const Value& value, IDeserializer<Type>&& visitor)
+        {
+            return visit_map_field(key, value, visitor);
+        }
+
+        template<class Type>
         Optional<std::vector<Type>> array_elements(const Array& arr, IDeserializer<Type>& visitor)
         {
             std::vector<Type> result;
diff --git a/toolsrc/include/vcpkg/platform-expression.h b/toolsrc/include/vcpkg/platform-expression.h
index 43ae6e89d..5de13b7a2 100644
--- a/toolsrc/include/vcpkg/platform-expression.h
+++ b/toolsrc/include/vcpkg/platform-expression.h
@@ -76,24 +76,7 @@ namespace vcpkg::PlatformExpression
         Allow,
     };
 
-    // platform expression parses the following :
-    // <platform-expression>:
-    //     <platform-expression.not>
-    //     <platform-expression.and>
-    //     <platform-expression.or>
-    // <platform-expression.simple>:
-    //     ( <platform-expression> )
-    //     <platform-expression.identifier>
-    // <platform-expression.identifier>:
-    //     A lowercase alpha-numeric string
-    // <platform-expression.not>:
-    //     <platform-expression.simple>
-    //     ! <platform-expression.simple>
-    // <platform-expression.and>
-    //     <platform-expression.not>
-    //     <platform-expression.and> & <platform-expression.not>
-    // <platform-expression.or>
-    //     <platform-expression.not>
-    //     <platform-expression.or> | <platform-expression.not>
+    // platform expression parses a platform expression; the EBNF of such is defined in
+    // /docs/maintainers/manifest-files.md#supports
     ExpectedS<Expr> parse_platform_expression(StringView expression, MultipleBinaryOperators multiple_binary_operators);
 }