fix(core): remove duplicate titling of help manual (#391)

Resolves #390 Before: <img width="502" alt="Screenshot 2024-09-17 at 2 03 33 PM" src="https://github.com/user-attachments/assets/c1d94fb2-8d17-4b3c-b64e-6c224f7af811"> After: <img width="524" alt="Screenshot 2024-09-17 at 2 02 59 PM" src="https://github.com/user-attachments/assets/3fdb3725-c03f-403b-b4e0-ae5a545898f8"> Co-authored-by: Ryan Schumacher <[email protected]>
opentdf · Sep 26, 2024 · cb8db69 · cb8db69
1 parent 326e74b
commit cb8db69
Show file tree

Hide file tree

Showing 49 changed files with 46 additions and 142 deletions.
diff --git a/docs/man/policy/_index.md b/docs/man/policy/_index.md
@@ -12,8 +12,6 @@ command:
       default: 'false'
 ---
 
-# Manage platform policy
-
 Policy is a set of rules that are enforced by the platform. Specific to the the data-centric
 security, policy revolves around data attributes (referred to as attributes). Within the context
 of attributes are namespaces, values, subject-mappings, resource-mappings, key-access-server grants,

diff --git a/docs/man/policy/attributes/_index.md b/docs/man/policy/attributes/_index.md
@@ -7,8 +7,6 @@ command:
     - attribute
 ---
 
-# Manage attributes
-
 Commands to manage attributes within the platform.
 
 Attributes are used to to define the properties of a piece of data. These attributes will then be

diff --git a/docs/man/policy/attributes/create.md b/docs/man/policy/attributes/create.md
@@ -1,5 +1,5 @@
 ---
-title: Create an attribute
+title: Create an attribute definition
 command:
   name: create
   aliases:
@@ -33,8 +33,6 @@ command:
       default: ''
 ---
 
-# Create an attribute definition
-
 Under a namespace, create an attribute with a rule.
 
 ### Rules

diff --git a/docs/man/policy/attributes/deactivate.md b/docs/man/policy/attributes/deactivate.md
@@ -1,5 +1,5 @@
 ---
-title: Deactivate an attribute
+title: Deactivate an attribute definition
 command:
   name: deactivate
   flags:
@@ -11,8 +11,6 @@ command:
       description: Force deactivation without interactive confirmation (dangerous)
 ---
 
-# Deactivate an attribute definition
-
 Deactivation preserves uniqueness of the attribute and values underneath within policy and all existing relations,
 essentially reserving them.
 

diff --git a/docs/man/policy/attributes/get.md b/docs/man/policy/attributes/get.md
@@ -1,5 +1,5 @@
 ---
-title: Get an attribute
+title: Get an attribute definition
 command:
   name: get
   aliases:
@@ -10,8 +10,6 @@ command:
       description: ID of the attribute
 ---
 
-# Get an attribute
-
 Retrieve an attribute along with its metadata, rule, and values.
 
 For more general information about attributes, see the `attributes` subcommand.
diff --git a/docs/man/policy/attributes/list.md b/docs/man/policy/attributes/list.md
@@ -1,5 +1,5 @@
 ---
-title: List attributes
+title: List attribute definitions
 command:
   name: list
   aliases:
@@ -15,8 +15,6 @@ command:
       default: active
 ---
 
-# List the known attributes
-
 By default, the list will only provide `active` attributes if unspecified, but the filter can be controlled with the `--state` flag.
 
 For more general information about attributes, see the `attributes` subcommand.
diff --git a/docs/man/policy/attributes/namespaces/_index.md b/docs/man/policy/attributes/namespaces/_index.md
@@ -7,8 +7,6 @@ command:
     - namespace
 ---
 
-# Manage attribute namespaces
-
 A namespace is the root (parent) of a set of platform policy. Like an owner or an authority, it fully qualifies attributes and their values,
 resource mapping groups, etc. As the various mappings of a platform are to attributes or values, a namespace effectively "owns" the
 mappings as well (transitively if not directly).

diff --git a/docs/man/policy/attributes/namespaces/create.md b/docs/man/policy/attributes/namespaces/create.md
@@ -17,8 +17,6 @@ command:
       default: ''
 ---
 
-# Create an attribute namespace
-
 Creation of a `namespace` is required to add attributes or any other policy objects beneath.
 
 For more information, see the `namespaces` subcommand.
diff --git a/docs/man/policy/attributes/namespaces/deactivate.md b/docs/man/policy/attributes/namespaces/deactivate.md
@@ -11,8 +11,6 @@ command:
       description: Force deactivation without interactive confirmation (dangerous)
 ---
 
-# Deactivate an attribute namespace
-
 Deactivating an Attribute Namespace will make the namespace name inactive as well as any attribute definitions and values beneath.
 
 Deactivation of a Namespace renders any existing TDFs of those attributes inaccessible.

diff --git a/docs/man/policy/attributes/namespaces/get.md b/docs/man/policy/attributes/namespaces/get.md
@@ -10,5 +10,4 @@ command:
       description: ID of the attribute namespace
 ---
 
-# Get an attribute namespace
-
+For more information, see the `namespaces` subcommand.
diff --git a/docs/man/policy/attributes/namespaces/list.md b/docs/man/policy/attributes/namespaces/list.md
@@ -11,6 +11,4 @@ command:
       description: Filter by state [active, inactive, any]
 ---
 
-# List attribute namespaces
-
 For more general information, see the `namespaces` subcommand.
diff --git a/docs/man/policy/attributes/namespaces/unsafe/_index.md b/docs/man/policy/attributes/namespaces/unsafe/_index.md
@@ -8,8 +8,6 @@ command:
       required: false
 ---
 
-# Unsafe Changes to Attribute Namespaces
-
 Unsafe changes are dangerous mutations to Policy that can significantly change access behavior around existing attributes
 and entitlement.
 

diff --git a/docs/man/policy/attributes/namespaces/update.md b/docs/man/policy/attributes/namespaces/update.md
@@ -18,8 +18,6 @@ command:
       default: false
 ---
 
-# Update an Attribute Namespace
-
 Attribute Namespace changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`).
 
 For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `namespaces` subcommand.
diff --git a/docs/man/policy/attributes/unsafe/_index.md b/docs/man/policy/attributes/unsafe/_index.md
@@ -8,8 +8,6 @@ command:
       required: false
 ---
 
-# Unsafe Changes to Attribute Definitions
-
 Unsafe changes are dangerous mutations to Policy that can significantly change access behavior around existing attributes
 and entitlement.
 

diff --git a/docs/man/policy/attributes/update.md b/docs/man/policy/attributes/update.md
@@ -1,5 +1,5 @@
 ---
-title: Update an attribute
+title: Update an attribute definition
 command:
   name: update
   aliases:
@@ -18,8 +18,6 @@ command:
       default: false
 ---
 
-# Update an attribute
-
 Attribute Definition changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`).
 
 For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `attributes` subcommand.

diff --git a/docs/man/policy/attributes/values/_index.md b/docs/man/policy/attributes/values/_index.md
@@ -7,8 +7,6 @@ command:
     - value
 ---
 
-# Manage attribute values 
-
 Attribute values are the individual units tagged on TDFs containing Resource Data.
 
 They are mapped to entitle person and non-person entities through Subject Mappings, to varied terms for tagging providers
@@ -26,6 +24,7 @@ Giving data multiple Attribute Values across the same or multiple Definitions/Na
 by an Entity's mapped Entitlements to result in key release, decryption, and resulting access to TDF'd data.
 
 For more information on:
+
 - values, see the `attributes values` subcommand
 - attribute definitions, see the `attributes` subcommand
-- namespaces, see the `attributes namespaces` subcommand
+- namespaces, see the `attributes namespaces` subcommand
diff --git a/docs/man/policy/attributes/values/create.md b/docs/man/policy/attributes/values/create.md
@@ -19,8 +19,6 @@ command:
       default: ''
 ---
 
-# Create an attribute value
-
 Add a single new value underneath an existing attribute.
 
 For a hierarchical attribute, a new value is added in lowest hierarchy (last).

diff --git a/docs/man/policy/attributes/values/deactivate.md b/docs/man/policy/attributes/values/deactivate.md
@@ -8,8 +8,6 @@ command:
       description: The ID of the attribute value to deactivate
 ---
 
-# Deactivate an attribute value
-
 Deactivation preserves uniqueness of the attribute value within policy and all existing relations, essentially reserving it.
 
 However, a deactivation of an attribute value means it cannot be entitled in an access decision.

diff --git a/docs/man/policy/attributes/values/get.md b/docs/man/policy/attributes/values/get.md
@@ -10,8 +10,6 @@ command:
       description: The ID of the attribute value to get
 ---
 
-# Get an attribute value
-
 Retrieve an attribute value along with its metadata.
 
-For more general information about attribute values, see the `values` subcommand.
+For more general information about attribute values, see the `values` subcommand.
diff --git a/docs/man/policy/attributes/values/list.md b/docs/man/policy/attributes/values/list.md
@@ -19,8 +19,6 @@ command:
       default: active
 ---
 
-# List attribute values
-
 By default, the list will only provide `active` values if unspecified, but the filter can be controlled with the `--state` flag.
 
 For more general information about attribute values, see the `values` subcommand.
diff --git a/docs/man/policy/attributes/values/unsafe/_index.md b/docs/man/policy/attributes/values/unsafe/_index.md
@@ -8,8 +8,6 @@ command:
       required: false
 ---
 
-# Unsafe Changes to Attribute Values
-
 Unsafe changes are dangerous mutations to Policy that can significantly change access behavior around existing attributes
 and entitlement.
 

diff --git a/docs/man/policy/attributes/values/update.md b/docs/man/policy/attributes/values/update.md
@@ -12,14 +12,12 @@ command:
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
+      default: ''
     - name: force-replace-labels
       description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
       default: false
 ---
 
-# Update an attribute value
-
 Attribute Value changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`).
 
 For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `values` subcommand.

diff --git a/docs/man/policy/kas-grants/_index.md b/docs/man/policy/kas-grants/_index.md
@@ -8,8 +8,6 @@ command:
     - kas-grant
 ---
 
-## Background
-
 Once Key Access Servers (KASs) have been registered within a platform's policy,
 they can be assigned grants to various attribute objects (namespaces, definitions, values).
 

diff --git a/docs/man/policy/kas-grants/assign.md b/docs/man/policy/kas-grants/assign.md
@@ -36,8 +36,6 @@ command:
       default: false
 ---
 
-# Assign a grant to a KAS
-
 Assign a registered Key Access Server (KAS) to an attribute namespace, definition, or value.
 
-For more information, see `kas-registry` and `kas-grants` manuals.
+For more information, see `kas-registry` and `kas-grants` manuals.
diff --git a/docs/man/policy/kas-grants/unassign.md b/docs/man/policy/kas-grants/unassign.md
@@ -27,8 +27,6 @@ command:
       description: Force the unassignment with no confirmation
 ---
 
-# Unassign a grant to a KAS
-
 Unassign a registered Key Access Server (KAS) to an attribute namespace, definition, or value.
 
 For more information, see `kas-registry` and `kas-grants` manuals.
diff --git a/docs/man/policy/kas-registry/_index.md b/docs/man/policy/kas-registry/_index.md
@@ -7,8 +7,6 @@ command:
     - kas-registries
 ---
 
-# Manage Key Access Servers registered to the platform
-
 The Key Access Server (KAS) registry is a record of KASes safeguarding access and maintaining public keys.
 
 The registry contains critical information like each server's uri, its public key (which can be

diff --git a/docs/man/policy/kas-registry/create.md b/docs/man/policy/kas-registry/create.md
@@ -23,8 +23,6 @@ command:
       default: ''
 ---
 
-# Create a KAS registration
-
 Public keys can be stored as either `remote` or `cached` under the following JSON structure.
 
 ### Remote
@@ -36,19 +34,19 @@ can be retrieved for the registered KAS under the `remote` key, such as `https:/
 
 ```json5
 {
-  "cached": {
+  cached: {
     // One or more known public keys for the KAS
-    "keys":[
+    keys: [
       {
         // x509 ASN.1 content in PEM envelope, usually
-        "pem": "<your PEM certificate>",
-        // key identifier 
-        "kid": "<your key id>",
+        pem: '<your PEM certificate>',
+        // key identifier
+        kid: '<your key id>',
         // key algorithm (see table below)
-        "alg": 1
-      }
-    ]
-  }
+        alg: 1,
+      },
+    ],
+  },
 }
 ```
 

diff --git a/docs/man/policy/kas-registry/delete.md b/docs/man/policy/kas-registry/delete.md
@@ -11,8 +11,6 @@ command:
       description: Force deletion without interactive confirmation (dangerous)
 ---
 
-# Delete a registered KAS
-
 Removes knowledge of a KAS (registration) from a platform's policy.
 
 If resource data has been TDFd utilizing key splits from the registered KAS, deletion from

diff --git a/docs/man/policy/kas-registry/get.md b/docs/man/policy/kas-registry/get.md
@@ -11,6 +11,4 @@ command:
       required: true
 ---
 
-# Get a registered Key Access Server
-
 For more information about registration of Key Access Servers, see the manual for `kas-registry`.
diff --git a/docs/man/policy/kas-registry/list.md b/docs/man/policy/kas-registry/list.md
@@ -6,6 +6,4 @@ command:
     - l
 ---
 
-# List KASes registered within a platform
-
 For more information about registration of Key Access Servers, see the manual for `kas-registry`.
diff --git a/docs/man/policy/kas-registry/update.md b/docs/man/policy/kas-registry/update.md
@@ -27,8 +27,6 @@ command:
       default: false
 ---
 
-# Update a registered KAS
-
 Update the `uri`, `metadata`, or key material (remote/cached) for a KAS registered to the platform.
 
 If resource data has been TDFd utilizing key splits from the registered KAS, deletion from

diff --git a/docs/man/policy/resource-mappings/_index.md b/docs/man/policy/resource-mappings/_index.md
@@ -8,8 +8,6 @@ command:
     - resource-mapping
 ---
 
-# Manage Resource Mappings
-
 Resource mappings are used to map resources to their respective attribute values based on the terms
 that are related to the data. Alone, this service is not very useful, but when combined with a PEP
 or PDP that can use the resource mappings it becomes a powerful tool for automating access control.

diff --git a/docs/man/policy/resource-mappings/create.md b/docs/man/policy/resource-mappings/create.md
@@ -8,19 +8,17 @@ command:
     - c
   flags:
     - name: attribute-value-id
-      description: The ID of the attribute value to map to the resource
-      default: ""
+      description: The ID of the attribute value to map to the resource.
+      default: ''
     - name: terms
-      description: The synonym terms to match for the resource mapping
-      default: ""
+      description: The synonym terms to match for the resource mapping.
+      default: ''
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
+      default: ''
 ---
 
-# Create a resource mapping
-
 Associate an attribute value with a set of plaintext string terms.
 
-For more information about resource mappings, see the `resource-mappings` subcommand.
+For more information about resource mappings, see the `resource-mappings` subcommand.
diff --git a/docs/man/policy/resource-mappings/delete.md b/docs/man/policy/resource-mappings/delete.md
@@ -10,6 +10,4 @@ command:
       description: Force deletion without interactive confirmation (dangerous)
 ---
 
-# Delete a resource mapping
-
 For more information about resource mappings, see the `resource-mappings` subcommand.
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,4 @@ command: @@
         - l
     ---
-    # List KASes registered within a platform
     For more information about registration of Key Access Servers, see the manual for `kas-registry`.