Obsolete print_bracket_link_prepared()

This function was used in MantisBT 1.x to display links surrounded by
square brackets for menus. With MantisBT Modern UI, it has been replaced
with CSS styling, to display the links as buttons.

One use case was not properly migrated, when displaying links on View
Issues Page (processing the EVENT_MENU_ISSUE hook).

The problem cannot be fixed properly within MantisBT code, it requires
an update of the Plugin's hook (returning an array of `label => link`
pairs instead of cooked links).

Consequently, the function has been marked as obsolete so that a warning
is displayed, to inform plugin developers that they should update their
code.

Fixes #23694

core/print_api.php

@@ -1450,8 +1450,15 @@ function print_form_button( $p_action_page, $p_label, array $p_args_to_post = nu
  * print brackets around a pre-prepared link (i.e. '<a href' html tag).
  * @param string $p_link The URL to link to.
  * @return void
+ * @deprecated 2.21.0
  */
 function print_bracket_link_prepared( $p_link ) {
+	error_parameters(
+		__FUNCTION__,
+		'print button functions or, in the context of an EVENT_MENU_ITEM hook, return link as associative array'
+	);
+	trigger_error( ERROR_DEPRECATED_SUPERSEDED, DEPRECATED );
+
 	echo '<span class="bracket-link">[&#160;' . $p_link . '&#160;]</span> ';
 }
 

docbook/Developers_Guide/en-US/Events_Reference_Output.xml

@@ -221,7 +221,21 @@
 
 				<itemizedlist>
 					<title>Return Value</title>
-					<listitem><para>&lt;Array&gt;: List of HTML links for the documents menu.</para></listitem>
+					<listitem>
+						<para>&lt;Array&gt;: List of HTML links for the issue page menu.</para>
+						<para>This is an associative array, with the link's label as key
+							and the link target as value, e.g. <programlisting>
+array( plugin_lang_get( 'mypage_label' ) => plugin_page( 'mypage' );
+</programlisting>
+						</para>
+						<para>For compatibility with MantisBT versions before 2.21.0,
+							it is also possible to return an array of cooked links :
+							<programlisting>
+array( '&lt;a href="' . plugin_page( 'mypage' ) . '">' . plugin_lang_get( 'mypage_label' ) . '&lt;/a>' );
+</programlisting>
+							However, this usage is deprecated.
+						</para>
+					</listitem>
 				</itemizedlist>
 			</blockquote>
 		</blockquote>