git: 90c04a54cf - main - documentation: fix crossref macro with comma in parameter

Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Vladlen Popolitov <vladlen_at_FreeBSD.org>
Date: Tue, 07 Jul 2026 19:49:15 UTC
The branch main has been updated by vladlen:

URL: https://cgit.FreeBSD.org/doc/commit/?id=90c04a54cfad6b3fa1badffc121282721f646c1e

commit 90c04a54cfad6b3fa1badffc121282721f646c1e
Author:     Vladlen Popolitov <vladlen@FreeBSD.org>
AuthorDate: 2026-07-07 19:49:07 +0000
Commit:     Vladlen Popolitov <vladlen@FreeBSD.org>
CommitDate: 2026-07-07 19:49:07 +0000

    documentation: fix crossref macro with comma in parameter
    
    Approved by: carlavilla, ziaee
    Differential Revision: https://reviews.freebsd.org/D58046
---
 documentation/content/en/articles/hubs/_index.adoc   |  2 +-
 documentation/content/en/articles/vinum/_index.adoc  |  4 ++--
 .../books/fdp-primer/asciidoctor-primer/_index.adoc  | 12 ++++++++++++
 .../content/en/books/handbook/basics/_index.adoc     |  2 +-
 .../en/books/handbook/serialcomms/_index.adoc        |  2 +-
 .../en/books/porters-handbook/makefiles/_index.adoc  | 20 ++++++++++----------
 .../en/books/porters-handbook/plist/_index.adoc      |  4 ++--
 .../books/porters-handbook/slow-porting/_index.adoc  |  2 +-
 .../content/it/books/handbook/vinum/_index.adoc      |  4 ++--
 9 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/documentation/content/en/articles/hubs/_index.adoc b/documentation/content/en/articles/hubs/_index.adoc
index df91360857..21ad08e9d1 100644
--- a/documentation/content/en/articles/hubs/_index.adoc
+++ b/documentation/content/en/articles/hubs/_index.adoc
@@ -324,7 +324,7 @@ The short answer is: from the site that is closest to you in Internet terms, or
 ==== I Just Want to Mirror from Somewhere!
 
 If you have no special intentions or requirements, the statement in
-crossref:hubs[mirror-where-where, Ok, but Where Should I get the Stuff Now?] applies.
+crossref:hubs[mirror-where-where,"Ok, but Where Should I get the Stuff Now?"] applies.
 This means:
 
 [.procedure]
diff --git a/documentation/content/en/articles/vinum/_index.adoc b/documentation/content/en/articles/vinum/_index.adoc
index 52656f88b7..bbb7bc069d 100644
--- a/documentation/content/en/articles/vinum/_index.adoc
+++ b/documentation/content/en/articles/vinum/_index.adoc
@@ -417,7 +417,7 @@ A typical configuration file might be:
 The subdisks of the second plex are offset by two drives from those of the first plex.
 This helps to ensure that writes do not go to the same subdisks even if a transfer goes over two drives.
 
-crossref:vinum[vinum-raid10-vol, A Mirrored, Striped [.filename]#vinum# Volume] represents the structure of this volume.
+crossref:vinum[vinum-raid10-vol,"A Mirrored, Striped [.filename]#vinum# Volume"] represents the structure of this volume.
 
 [[vinum-raid10-vol]]
 .A Mirrored, Striped [.filename]#vinum# Volume
@@ -678,7 +678,7 @@ The bsdlabel for these devices might look like:
 
 It can be observed that the `size` parameter for the faked `a` partition matches the value outlined above, while the `offset` parameter is the sum of the offset within the [.filename]#vinum# partition `h`, and the offset of this partition within the device or slice.
 This is a typical setup that is necessary to avoid the problem described in
-crossref:vinum[vinum-root-panic, Nothing Boots, the Bootstrap Panics].
+crossref:vinum[vinum-root-panic,"Nothing Boots, the Bootstrap Panics"].
 The entire `a` partition is completely within the `h` partition containing all the [.filename]#vinum# data for this device.
 
 In the above example, the entire device is dedicated to [.filename]#vinum# and there is no leftover pre-[.filename]#vinum# root partition.
diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
index d5aae7675a..67ba576464 100644
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -277,6 +277,18 @@ Do not use either the `xref` macro or its shortcut `<<` `>>`.
 They do not work well in all output formats.
 ====
 
+[IMPORTANT]
+====
+When the second parameter of the `crossref` macro contains a comma, it must be enclosed in double quotes.
+Otherwise, the comma is interpreted as a parameter separator, and the text after the comma is stripped.
+
+For example:
+....
+crossref:plist[documentation-comma, "First, second"]
+....
+Without quotes, only `First` would be used as the link text, and the rest would be lost.
+====
+
 [[asciidoctor-images-icons]]
 == Images and Icons
 
diff --git a/documentation/content/en/books/handbook/basics/_index.adoc b/documentation/content/en/books/handbook/basics/_index.adoc
index 8a488681d8..88c348a858 100644
--- a/documentation/content/en/books/handbook/basics/_index.adoc
+++ b/documentation/content/en/books/handbook/basics/_index.adoc
@@ -1324,7 +1324,7 @@ Unlike partitions and slices, disk numbering starts at 0.
 Common codes are listed in crossref:basics[disks-naming,Disk Device Names].
 
 When referring to a partition in a slice, include the disk name, `s`, the slice number, and then the partition letter.
-Examples are shown in crossref:basics[basics-disk-slice-part,Sample Disk, Slice, and Partition Names].
+Examples are shown in crossref:basics[basics-disk-slice-part,"Sample Disk, Slice, and Partition Names"].
 GPT partitions include the disk name, `p`, and then the partition number.
 
 crossref:basics[basics-concept-disk-model,Conceptual Model of a Disk] shows a conceptual model of a disk layout using MBR slices.
diff --git a/documentation/content/en/books/handbook/serialcomms/_index.adoc b/documentation/content/en/books/handbook/serialcomms/_index.adoc
index af9c67f81d..b31793384c 100644
--- a/documentation/content/en/books/handbook/serialcomms/_index.adoc
+++ b/documentation/content/en/books/handbook/serialcomms/_index.adoc
@@ -113,7 +113,7 @@ The connector can be either a DB-25 or a DB-9.
 
 A null-modem cable can be constructed using the pin connections summarized in
 crossref:serialcomms[nullmodem-db25, DB-25 to DB-25 Null-Modem Cable], crossref:serialcomms[nullmodem-db9,DB-9 to DB-9 Null-Modem Cable], and
-crossref:serialcomms[nullmodem-db9-25,DB-9 to DB-25 Null-Modem Cable, DB-9 to DB-25 Null-Modem Cable].
+crossref:serialcomms[nullmodem-db9-25,"DB-9 to DB-25 Null-Modem Cable, DB-9 to DB-25 Null-Modem Cable"].
 While the standard calls for a straight-through pin 1 to pin 1 "Protective Ground" line, it is often omitted.
 Some terminals work using only pins 2, 3, and 7, while others require different configurations.
 When in doubt, refer to the documentation for the hardware.
diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index a9ffe801b9..72aa3c5f0a 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -2355,7 +2355,7 @@ MASTER_SITES=	alpha:DEFAULT,SOME_SITE
    even if an element is postfixed with `:n`. See both
    crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-subdir,Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR`]
    and
-   crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories].
+   crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,"Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories"].
 +
 [[ports-master-sites-n-example-detailed-use-master-site-subdir]]
 .Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR`
@@ -2498,7 +2498,7 @@ PATCHFILES=	patch1:test
    with their matching group elements within both `MASTER_SITES` and
    `PATCH_SITES` which use matching group elements within both
    `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`. Check
-   crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories].
+   crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,"Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories"].
 ** `fetch-list`: works like old `fetch-list` with the exception that it groups just like `do-fetch`.
 ** `master-sites` and `patch-sites`: (incompatible with older versions) only return the elements of group `DEFAULT`; in fact, they execute targets `master-sites-default` and `patch-sites-default` respectively.
 +
@@ -3714,7 +3714,7 @@ Variables related to gmake and [.filename]#configure# are described in crossref:
 Perl related variables are described in crossref:special[using-perl,Using Perl].
 X11 variables are listed in crossref:special[using-x11,Using X11].
 crossref:special[using-gnome,Using Gnome] deals with GNOME and crossref:special[using-kde,Using KDE] with KDE related variables.
-crossref:special[using-java,Using Java] documents Java variables, while crossref:special[using-php,Web Applications, Apache and PHP] contains information on Apache, PHP and PEAR modules.
+crossref:special[using-java,Using Java] documents Java variables, while crossref:special[using-php,"Web Applications, Apache and PHP"] contains information on Apache, PHP and PEAR modules.
 Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:uses[uses-ruby,Ruby].
 crossref:special[using-sdl,Using SDL] provides variables used for SDL applications and finally, crossref:special[using-xfce,Using Xfce] contains information on Xfce.
 
@@ -4177,7 +4177,7 @@ For easier access, a comprehensive list is provided:
 `PLIST_SUB`, `SUB_LIST`::
 For automatic `%%_OPT_%%` and `%%NO__OPT__%%` generation, see crossref:makefiles[options_sub, `OPTIONS_SUB`].
 +
-For more complex usage, see crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`].
+For more complex usage, see crossref:makefiles[options-variables,"Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`"].
 
 `CONFIGURE_ARGS`::
 For `--enable-_x_` and `--disable-_x_`, see crossref:makefiles[options-configure_enable, `OPT_CONFIGURE_ENABLE`].
@@ -4208,11 +4208,11 @@ See crossref:makefiles[options-qmake_on, `OPT_QMAKE_ON` and `OPT_QMAKE_OFF`].
 See crossref:makefiles[options-use, `OPT_USE` and `OPT_USE_OFF`].
 
 `*_DEPENDS`::
-See crossref:makefiles[options-dependencies, Dependencies, `OPT_DEPTYPE` and `OPT_DEPTYPE_OFF`].
+See crossref:makefiles[options-dependencies,"Dependencies, `OPT_DEPTYPE` and `OPT_DEPTYPE_OFF`"].
 
 `*` (Any variable)::
 The most used variables have direct helpers, see
-crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`].
+crossref:makefiles[options-variables,"Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`"].
 +
 For any variable without a specific helper, see crossref:makefiles[options-vars, `OPT_VARS` and `OPT_VARS_OFF`].
 
@@ -4226,7 +4226,7 @@ crossref:makefiles[options-prevents, `OPT_PREVENTS` and `OPT_PREVENTS_MSG`].
 
 Build targets::
 When an option need some extra processing, see
-crossref:makefiles[options-targets, Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`].
+crossref:makefiles[options-targets,"Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`"].
 
 [[options_sub]]
 ==== `OPTIONS_SUB`
@@ -4751,7 +4751,7 @@ Provides a generic way to set and append to variables.
 [WARNING]
 ====
 Before using `OPT_VARS` and `OPT_VARS_OFF`, see if there is already a more
-specific helper available in crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`].
+specific helper available in crossref:makefiles[options-variables,"Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`"].
 ====
 
 When option _OPT_ is selected, and `OPT_VARS` defined, `_key_=_value_` and `_key_+=_value_` pairs are evaluated from `OPT_VARS`.
@@ -5092,7 +5092,7 @@ There are three different variables to register a conflict between packages and
 
 [NOTE]
 ====
-The conflict variables automatically set the variable `IGNORE`, which is more fully documented in crossref:porting-dads[dads-noinstall,Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`].
+The conflict variables automatically set the variable `IGNORE`, which is more fully documented in crossref:porting-dads[dads-noinstall,"Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`"].
 ====
 
 When removing one of several conflicting ports, it is advisable to retain `CONFLICTS` in those other ports for a few months to cater for users who only update once in a while.
@@ -5336,7 +5336,7 @@ post-install:
 ....
 
 On the other hand, if there is a DOCS option in the port, install the documentation in a `post-install-DOCS-on` target.
-These targets are described in crossref:makefiles[options-targets, Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`].
+These targets are described in crossref:makefiles[options-targets,"Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`"].
 
 Here are some handy variables and how they are expanded by default when used in the [.filename]#Makefile#:
 
diff --git a/documentation/content/en/books/porters-handbook/plist/_index.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc
index 9a76a8e3e8..ea8cd92d84 100644
--- a/documentation/content/en/books/porters-handbook/plist/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc
@@ -503,7 +503,7 @@ For example, [.filename]#/var/db/${PORTNAME}# needs to have a `@dir` entry where
 ==== `@exec` _command_, `@unexec` _command_ (Deprecated)
 
 Execute _command_ as part of the installation or deinstallation process.
-Please use crossref:plist[plist-keywords-base-exec, `@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_] instead.
+Please use crossref:plist[plist-keywords-base-exec,"`@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_"] instead.
 
 [[plist-keywords-base-dirrm]]
 ==== `@dirrm` _directory_ (Deprecated)
@@ -615,7 +615,7 @@ actions: [file(1)]
 
 These keywords contains a man:sh[1] script to be executed before or after installation, deinstallation, or upgrade of the package.
 In addition to the usual `@exec %_foo_` placeholders described in
-crossref:plist[plist-keywords-base-exec, `@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_], there is a new one, `%@`, which represents the argument of the keyword.
+crossref:plist[plist-keywords-base-exec,"`@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_"], there is a new one, `%@`, which represents the argument of the keyword.
 
 [[plist-keywords-examples]]
 ==== Custom Keyword Examples
diff --git a/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
index 5db01cfdd9..e3e0de9c2a 100644
--- a/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
@@ -306,7 +306,7 @@ EXTRA_PATCHES=	${PATCHDIR}/extra-patch-fbsd10
 [example]
 ====
 When an crossref:makefiles[makefile-options,option] requires a patch, use ``opt_EXTRA_PATCHES`` and ``opt_EXTRA_PATCHES_OFF`` to make the patch conditional on the `opt` option.
-See crossref:makefiles[options-variables,Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`] for more information.
+See crossref:makefiles[options-variables,"Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`"] for more information.
 
 [.programlisting]
 ....
diff --git a/documentation/content/it/books/handbook/vinum/_index.adoc b/documentation/content/it/books/handbook/vinum/_index.adoc
index a312e40cc4..c848d4edff 100644
--- a/documentation/content/it/books/handbook/vinum/_index.adoc
+++ b/documentation/content/it/books/handbook/vinum/_index.adoc
@@ -678,14 +678,14 @@ Alla richiesta di un filesystem di root da montare, ogni periferica che contenga
 
 ==== Si Carica Solo l'Avvio Primario
 
-Se [.filename]#/boot/loader# non si carica, ma l'avvio primario si carica comunque (si capisce dal singolo trattino nella colonna di sinistra dello schermo subito dopo l'inizio dell'avvio), si può tentare di fermare l'avvio primario in questo punto, premendo il tasto kbd:[spazio]. Questo fermerà l'avvio nella seconda fase, vedi crossref:boot[boot-boot1,Stadio Uno, /boot/boot1, e Stadio Due, /boot/boot2]. Qua si può fare un tentativo di caricare una differente partizione, ad esempio la partizione contenente il precedente filesystem di root `"a"`, prima di sostituirlo come sopra indicato.
+Se [.filename]#/boot/loader# non si carica, ma l'avvio primario si carica comunque (si capisce dal singolo trattino nella colonna di sinistra dello schermo subito dopo l'inizio dell'avvio), si può tentare di fermare l'avvio primario in questo punto, premendo il tasto kbd:[spazio]. Questo fermerà l'avvio nella seconda fase, vedi crossref:boot[boot-boot1,"Stadio Uno, /boot/boot1, e Stadio Due, /boot/boot2"]. Qua si può fare un tentativo di caricare una differente partizione, ad esempio la partizione contenente il precedente filesystem di root `"a"`, prima di sostituirlo come sopra indicato.
 
 [[vinum-root-panic]]
 ==== Non si Carica Niente, l'Avvio va in Panico
 
 Questa situazione accade quando l'installazione di Vinum ha distrutto il codice di avvio. Sfortunatamente Vinum lascia solo 4 KB liberi all'inizio della sua partizione prima di scrivere il proprio header. Purtroppo le due fasi dell'avvio e la disklabel compresa tra le due attualmente occupa 8 KB, quindi se la partizione Vinum è creata con spiazzamento 0 in una slice o disco che dovrebbe essere avviabile, la configurazione di Vinum distruggerà il codice di avvio.
 
-Similmente, se la situazione sopra descritta è stata risolta avviando da un disco di "Fixit", e il codice di avvio re-installato usando `disklabel -B` come descritto in crossref:boot[boot-boot1,Stadio Uno, /boot/boot1, e Stadio Due, /boot/boot2], il codice di avvio distruggerà l'header di Vinum, che non saprà più trovare i propri dischi. Benché nessun dato, di configurazione o contenuto, sia distrutto da questo processo, che risulta quindi recuperabile reinserendo la stessa configurazione di Vinum, la situazione è in realtà di difficile risoluzione: sarebbe necessario spostare l'intera partizione Vinum di almeno 4 KB, in modo da lasciare abbastanza spazio sia per il codice di avvio che per l'header Vinum.
+Similmente, se la situazione sopra descritta è stata risolta avviando da un disco di "Fixit", e il codice di avvio re-installato usando `disklabel -B` come descritto in crossref:boot[boot-boot1,"Stadio Uno, /boot/boot1, e Stadio Due, /boot/boot2"], il codice di avvio distruggerà l'header di Vinum, che non saprà più trovare i propri dischi. Benché nessun dato, di configurazione o contenuto, sia distrutto da questo processo, che risulta quindi recuperabile reinserendo la stessa configurazione di Vinum, la situazione è in realtà di difficile risoluzione: sarebbe necessario spostare l'intera partizione Vinum di almeno 4 KB, in modo da lasciare abbastanza spazio sia per il codice di avvio che per l'header Vinum.
 
 [[vinum-root-4x]]
 === Differenze per FreeBSD 4.X