--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/_doc.rs	Wed Jun 25 00:59:24 2025 -0400
@@ -0,0 +1,165 @@
+//! A place to stick documentation stuff.
+
+/// Generates text lists of reference links for docs.
+///
+/// Use this with the other doc macros for the correct link names.
+///
+/// # Examples
+///
+/// ```
+/// #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
+/// ///
+/// /// ...use it with link references, like the below...
+/// ///
+/// #[doc = _stdlinks!(3 pam_get_authtok)]
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! _linklist {
+    ($func:ident: adg$(, $rest:ident)*) => {
+        concat!(
+            "- [Application Developers' Guide on `", stringify!($func), "`][adg]\n",
+            $crate::_linklist!($func: $($rest),*)
+        )
+    };
+    ($func:ident: mwg$(, $rest:ident)*) => {
+        concat!(
+            "- [Module Writers' Guide on `", stringify!($func), "`][mwg]\n",
+            $crate::_linklist!($func: $($rest),*)
+        )
+    };
+    ($func:ident: _std$(, $rest:ident)*) => {
+        $crate::_linklist!($func: man7, manbsd, xsso$(, $rest)*)
+    };
+    ($func:ident: man7$(, $rest:ident)*) => {
+        concat!(
+            "- [Linux-PAM manpage for `", stringify!($func), "`][man7]\n",
+            $crate::_linklist!($func: $($rest),*)
+        )
+    };
+    ($func:ident: manbsd$(, $rest:ident)*) => {
+        concat!(
+            "- [OpenPAM manpage for `", stringify!($func), "`][manbsd]\n",
+            $crate::_linklist!($func: $($rest),*)
+        )
+    };
+    ($func:ident: xsso$(, $rest:ident)*) => {
+        concat!(
+            "- [X/SSO spec for `", stringify!($func), "`][xsso]",
+            $crate::_linklist!($func: $($rest),*)
+        )
+    };
+    ($func:ident:$(,)?) => { "" };
+}
+
+/// Generates a Markdown link reference to one of the PAM guides.
+///
+/// # Examples
+///
+/// ```
+/// #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! _guide {
+    ($name:ident: $page_link:literal) => {
+        concat!(
+            "[",
+            stringify!($name),
+            "]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/",
+            $page_link
+        )
+    };
+}
+
+/// Generates a Markdown link reference to the Linux man pages on man7.org.
+///
+/// # Examples
+///
+/// ```
+/// // Both of these formulations create a link reference named `man7`.
+/// #[doc = _man7!(3 fn_name)]
+/// #[doc = _man7!(5 thing_name "SECTION")]
+/// // This one creates a link reference named `link_name`.
+/// #[doc = _man7!(link_name: 1 prog_name "SECTION")]
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! _man7 {
+    ($n:literal $fn:ident $($anchor:literal)?) => {
+        $crate::_man7!(man7: $n $fn $($anchor)?)
+    };
+    ($name:ident: $n:literal $fn:ident $($anchor:literal)?) => {
+        concat!(
+            "[", stringify!($name), "]: ",
+            "https://man7.org/linux/man-pages/man", $n, "/",
+            stringify!($fn), ".", $n, ".html", $("#", $anchor)?
+        )
+    };
+}
+
+/// Generates a Markdown link reference to the NetBSD man pages.
+///
+/// # Examples
+///
+/// ```
+/// // Both of these formulations create a link named `manbsd`.
+/// #[doc = _manbsd!(3 fn_name)]
+/// #[doc = _manbsd!(5 thing_name "SECTION")]
+/// // This one creates a link named `link_name`.
+/// #[doc = _manbsd!(link_name: 1 prog_name "SECTION")]
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! _manbsd {
+    ($n:literal $func:ident $($anchor:literal)?) => {
+        $crate::_manbsd!(manbsd: $n $func $($anchor)?)
+    };
+    ($name:ident: $n:literal $func:ident $($anchor:literal)?) => {
+        concat!("[", stringify!($name), "]: ",
+            "https://man.netbsd.org/", stringify!($func), ".", $n,
+            $("#", $anchor)?
+        )
+    };
+}
+
+/// Generates a Markdown link reference to the X/SSO specification.
+///
+/// # Examples
+///
+/// ```
+/// // Both of these formulations create a link reference named `xsso`.
+/// // A link to the X/SSO specification for the `pam_set_item` function.
+/// #[doc = _xsso!(pam_set_item)]
+/// // A link to the HTML page with the given name.
+/// #[doc = _xsso!("some_page.htm#section-id")]
+///
+/// // This one creates a link reference named `spec_toc`.
+/// #[doc = _xsso!(spec_toc: "toc.htm")]
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! _xsso {
+    ($func:ident) => { $crate::_xsso!(xsso: concat!(stringify!($func), ".htm")) };
+    ($page:literal) => { $crate::_xsso!(xsso: $page) };
+    ($name:ident: $page:expr) => {
+        concat!("[", stringify!($name), "]: https://pubs.opengroup.org/onlinepubs/8329799/", $page)
+    };
+}
+
+/// Generates Markdown link references to Linux-PAM, OpenPAM, and X/SSO.
+///
+/// A shortcut to `_man7!`, `_manbsd!`, and `_xsso!`.
+///
+/// # Examples
+///
+/// ```
+/// #[doc = _stdlinks!(3 pam_get_item)]
+/// ```
+#[macro_export]
+#[doc(hidden)]
+macro_rules! _stdlinks {
+    ($n:literal $func:ident) => {
+        concat!($crate::_man7!($n $func), "\n", $crate::_manbsd!($n $func), "\n", $crate::_xsso!($func))
+    };
+}