Add rmgrdesc README

In the README, briefly explain what rmgrdesc functions are, and why
they are in a separate directory. Commit c03c2eae0a added some
guidelines on the preferred output format; move that to the README
too.

Reviewed-by: Melanie Plageman, Peter Geoghegan
Discussion: https://www.postgresql.org/message-id/9159daf7-f42d-781b-458f-1b2cf32cb256%40iki.fi

1 files changed, 0 insertions, 44 deletions

diff --git a/src/include/access/rmgrdesc_utils.h b/src/include/access/rmgrdesc_utils.h
index bd414699f21..c754d55621b 100644
--- a/src/include/access/rmgrdesc_utils.h
+++ b/src/include/access/rmgrdesc_utils.h
@@ -12,50 +12,6 @@
 #ifndef RMGRDESC_UTILS_H_
 #define RMGRDESC_UTILS_H_
 
-/*
- * Guidelines for rmgrdesc routine authors:
- *
- * The goal of these guidelines is to avoid gratuitous inconsistencies across
- * each rmgr, and to allow users to parse desc output strings without too much
- * difficulty.  This is not an API specification or an interchange format.
- * (Only heapam and nbtree desc routines follow these guidelines at present,
- * in any case.)
- *
- * Record descriptions are similar to JSON style key/value objects.  However,
- * there is no explicit "string" type/string escaping.  Top-level { } brackets
- * should be omitted.  For example:
- *
- * snapshotConflictHorizon: 0, flags: 0x03
- *
- * Record descriptions may contain variable-length arrays.  For example:
- *
- * nunused: 5, unused: [1, 2, 3, 4, 5]
- *
- * Nested objects are supported via { } brackets.  They generally appear
- * inside variable-length arrays.  For example:
- *
- * ndeleted: 0, nupdated: 1, deleted: [], updated: [{ off: 45, nptids: 1, ptids: [0] }]
- *
- * Try to output things in an order that faithfully represents the order of
- * fields from the underlying physical WAL record struct.  Key names should be
- * unique (at the same nesting level) to make parsing easy.  It's a good idea
- * if the number of items in the array appears before the array.
- *
- * It's okay for individual WAL record types to invent their own conventions.
- * For example, Heap2's PRUNE record descriptions use a custom array format
- * for the record's "redirected" field:
- *
- * ... redirected: [1->4, 5->9], dead: [10, 11], unused: [3, 7, 8]
- *
- * Arguably the desc routine should be using object notation for this instead.
- * However, there is value in using a custom format when it conveys useful
- * information about the underlying physical data structures.
- *
- * This ad-hoc format has the advantage of being close to the format used for
- * the "dead" and "unused" arrays (which follow the standard desc convention
- * for page offset number arrays).  It suggests that the "redirected" elements
- * shown are just pairs of page offset numbers (which is how it really works).
- */
 extern void array_desc(StringInfo buf, void *array, size_t elem_size, int count,
 					   void (*elem_desc) (StringInfo buf, void *elem, void *data),
 					   void *data);