Reorganize the headers to isolate the nonstandard routines

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021, PMIx
+Copyright (c) 2021-2022, PMIx
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,2 +1,27 @@
-# pmix-abi
-PMIx Headers for ABI Compatibility
+# PMIx Standard ABI Headers
+
+## Layout of the headers
+
+ * `pmix_types.h` : PMIx Standard types, constants, and callback functions
+ * `pmix_macros.h` : PMIx Standard macros
+   * `pmix_abi_support.h` : Non-standard support functions (prefixed with `pmixabi_`) to support the macro definitions
+   * `pmix_abi_support_bottom.h` : Non-standard support functions (prefixed with `pmixabi_`) to support the macro definitions. These few functions also use the macros. As such, they need to be included at the bottom of `pmix_macros.h`
+ * `pmix_fns.h` : PMIx Standard API function pointer declarations for PMIx Standard APIs
+   * The goal of this header to ease the incorporation of PMIx routines for applications and tools that wish to `dlopen()` a PMIx Standard compliant library and then `dlsym()` the various functions.
+
+
+```mermaid
+flowchart TB
+    subgraph macros["pmix_macros.h"]
+    direction TB
+    s1["pmix_abi_support.h (Non-Standard)"] --- mid["PMIx Standard Macros"]
+    mid --- s2["pmix_abi_support_bottom.h (Non-Standard)"]
+    end
+    pmix_types.h == Included by ==> macros
+    macros == Included by ==> pmix_fns.h
+    macros == Included by ==> pmix.h
+```
+
+## Using dlopen/dlsym
+
+If your application intends to use the headers with `dlopen()` and `dlsym()` then the `pmix_fns.h` header is all that you need to include to use the PMIx Standard interface. The function pointer signatures are defined in `pmix_fns.h` in a form approprate for `dlsym()`