From ed00ffbaa86a8ef1c25fccd16e96315ca5d2505e Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Wed, 9 Aug 2023 16:33:58 +0100
Subject: doc: Add record-ref convenience function.

* doc/skribilo.scm (record-ref): New public function.
* doc/forge.skb: Use record-ref.
---
 doc/forge.skb    | 24 +++++++++++-------------
 doc/skribilo.scm |  7 +++++++
 2 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/doc/forge.skb b/doc/forge.skb
index e8b535f..3095947 100644
--- a/doc/forge.skb
+++ b/doc/forge.skb
@@ -192,9 +192,8 @@ repeated below for your reference.])
     (description
      (record-documentation "guix/forge/forge.scm" '<forge-configuration>
        (record-field "projects"
-         [List of ,(ref :mark "<forge-project>" :text
-(code [<forge-project>])) objects describing projects managed by
-guix-forge]))
+         [List of ,(record-ref "<forge-project>") objects describing
+projects managed by guix-forge]))
      (record-documentation "guix/forge/forge.scm" '<forge-project>
        (record-field "name"
          [Name of the project])
@@ -215,7 +214,7 @@ user. The idea is that the website is built by a Guix derivation as a
 store item and a symbolic link to that store item is created in the
 parent directory.])
        (record-field "ci-jobs"
-         [List of ,(ref :mark "<forge-laminar-job>") objects
+         [List of ,(record-ref "<forge-laminar-job>") objects
 describing ,(abbr :short "CI" :long "continuous integration") jobs to
 configure])
        (record-field "ci-jobs-trigger"
@@ -268,8 +267,8 @@ respectively. The any address is ,(code ["0.0.0.0"]) and ,(code
        (record-field "package"
          [,(code [gunicorn]) package to use])
        (record-field "apps"
-         [List of ,(ref :mark "<gunicorn-app>" :text (code
-[<gunicorn-app>])) objects describing gunicorn apps to run]))
+         [List of ,(record-ref "<gunicorn-app>") objects describing
+gunicorn apps to run]))
      (record-documentation "guix/forge/gunicorn.scm" '<gunicorn-app>
        (record-field "name"
          [Name of the app])
@@ -278,9 +277,8 @@ respectively. The any address is ,(code ["0.0.0.0"]) and ,(code
        (record-field "wsgi-app-module"
          [WSGI app module passed to gunicorn])
        (record-field "sockets"
-         [List of ,(ref :mark "<forge-ip-socket>" :text (code
-[<forge-ip-socket>])) or ,(ref :mark "<forge-unix-socket>" :text (code
-[<forge-unix-socket>])) objects describing sockets to listen on])
+         [List of ,(record-ref "<forge-ip-socket>") or ,(record-ref
+"<forge-unix-socket>") objects describing sockets to listen on])
        (record-field "workers"
          [Number of worker processes])
        (record-field "environment-variables"
@@ -294,13 +292,13 @@ gunicorn is run in.]))
        (record-field "package"
          [,(code [webhook]) package to use])
        (record-field "socket"
-         [Socket, a ,(ref :mark "<forge-ip-socket>" :text (code
-[<forge-ip-socket>])) object, to listen on.])
+         [Socket, a ,(record-ref "<forge-ip-socket>") object, to listen
+on.])
        (record-field "log-directory"
          [Directory to write log files to])
        (record-field "hooks"
-         [List of ,(ref :mark "<webhook-hook>" :text (code
-[<webhook-hook>])) objects describing hooks to configure]))
+         [List of ,(record-ref "<webhook-hook>") objects describing
+hooks to configure]))
      (record-documentation "guix/forge/webhook.scm" '<webhook-hook>
        (record-field "id"
          [Identifier of the webhook. This hook is triggered at ,(ref
diff --git a/doc/skribilo.scm b/doc/skribilo.scm
index 4058e62..c3b8efc 100644
--- a/doc/skribilo.scm
+++ b/doc/skribilo.scm
@@ -44,6 +44,7 @@
             source-ref
             record-documentation
             record-field
+            record-ref
             docstring-function-documentation))
 
 ;; Constants
@@ -294,6 +295,12 @@ are a list of <record-field> objects."
                                 (record-field-documentation documented-field))))
                       fields)))))
 
+(define (record-ref identifier)
+  "Link to record documentation of record identified by
+@var{identifier}."
+  (ref #:ident identifier
+       #:text (code identifier)))
+
 (define-record-type <function>
   (function name arguments docstring)
   function?
-- 
cgit v1.2.3