Skip navigation links
5 Conventions for Writing and Editing MySQL Documentation (“Styleguide”) »
Section Navigation      [Toggle]

4.11.3. Markup for Automatic Link Generation

For references to certain objects that can be associated with a section or paragraph in a manual, we generate links automatically. The processing for this is handled in the dbk-prep.xsl transform to add <link> elements. In this way, we get auto-linking of object references to their descriptions, which is useful for those output formats that support hyperlinking (HTML, PDF). Auto-linking is done for these objects:

  • We use the <literal> element with a role attribute to indicate the object type. We do this for SQL functions, operators, data types, and statements, and for C API functions.

  • For <command> elements, a link is generated if a section with an ID matching the element content can be found.

  • For <option> elements with a role attribute to indicate which program to which the option belongs, a link is generated to the option description.

For auto-link generation to occur, the Makefile for the directory containing the document must have the following line: 

GENERATE_AUTOLINK = 1

For <literal> elements, the attributes that identify an object as one for which a link should be generated automatically are:

  • The role attribute, if present, identifies the object type. The value should be "func" for an SQL function, "op" for an SQL operator, "type" for an SQL data type, "stmt" for an SQL statement, "sysvar" for a system variable, "statvar" for a status variable, "sqlmode" for a SQL mode, "isolevel" for a transaction isolation level, "cfunc" for a C API function, "jointype" for an optimizer join type (as seen in EXPLAIN output), or "priv" for an access privilege.

  • A condition attribute may be added as a hint. The dbk-prep.xsl transform tries to determine the ID to use for the link, using the rules described shortly. If it cannot determine the ID, the condition attribute indicates which ID to use.

When dbk-prep.xsl determines the ID for the linkend attribute when generating <link> elements, the name-to-ID mapping rule depends on the function type.

  • SQL function: Use element content up to the leading open parenthesis, with underscores converted to dashes and letters converted to lowercase. Add a function_ prefix. Some functions can be written without parentheses, so if no opening parenthesis is found, use the entire element content.

    These references both will link to an ID of function_current-timestamp: 

    <literal role="func">CURRENT_TIMESTAMP()</literal>
<literal role="func">CURRENT_TIMESTAMP</literal>

  • SQL operator: Use the entire element content, with underscores and spaces converted to dashes and letters converted to lowercase. Add an operator_ prefix.

    This reference will link to an ID of operator_binary: 

    <literal role="op">BINARY</literal>

  • SQL data type: Use the entire element content, with underscores and spaces converted to dashes and letters converted to lowercase.

    This reference will link to an ID of datetime: 

    <literal role="type">DATETIME</literal>

    Data type sections do not always correspond to the type name, so the link generator actually uses a lookup table to map types to section IDs.

  • SQL statement: Use the entire element content, with underscores and spaces converted to dashes and letters converted to lowercase.

    This reference will link to an ID of create-table: 

    <literal role="stmt">CREATE TABLE</literal>

  • INFORMATION_SCHEMA table: Use the entire element content (stripping off any INFORMATION_SCHEMA. qualifier), with underscores converted to dashes and letters converted to lowercase. Add a -table suffix.

    Either of these references will link to an ID of triggers-table: 

    <literal role="is">TRIGGERS</literal>
<literal role="is">INFORMATION_SCHEMA.TRIGGERS</literal>

  • System variable or status variable: Use the first word of the content, without lettercase conversion. Add a sysvar_ or statvar_ prefix. 

    <literal role="sysvar">autocommit</literal>
<literal role="statvar">Key_read_requests</literal>

  • SQL mode: Use the entire element content, with underscores converted to dashes and letters converted to lowercase.

    This reference will link to an ID of sqlmode_ansi_quotes: 

    <literal role="sqlmode">ANSI_QUOTES</literal>

  • Transaction isolation level: Use the entire element content, with spaces converted to dashes and letters converted to lowercase. Add an isolevel_ prefix.

    Either of these references will link to an ID of isolevel_read-committed: 

    <literal role="isolevel">READ COMMITTED</literal>
<literal role="isolevel">READ-COMMITTED</literal>

  • C API function: Use element content up to the leading open parenthesis, with underscores converted to dashes.

    This reference will link to an ID of mysql-real-connect: 

    <literal role="cfunc">mysql_real_connect()</literal>

  • Optimizer join type: Use the entire element content, with letters converted to lowercase. Add a jointype_ prefix.

    This reference will link to an ID of jointype_eq_ref: 

    <literal role="jointype">eq_ref</literal>

  • Access privilege: Use the entire element content, with letters converted to lowercase and spaces converted to dashes. Add a priv_ prefix.

    This reference will link to an ID of priv_show-view: 

    <literal role="priv">SHOW VIEW</literal>

In some cases, the content of the <literal> element is unsuitable for constructing an ID. In such cases, include a condition attribute as a hint about the ID to use. It is not necessary to add the leading function_ or operator_ for the condition attribute value. That can be determined automatically as needed because the role attribute value determines whether the element refers to a function or an operator.

A condition attribute is needed when the element contains any of the following:

  • Nonalphanumeric text: 

    Wrong: <literal role="op">*</literal>

Right: <literal role="op" condition="times">*</literal>

  • Extra text within the element that confuses the content-to-ID conversion: 

    Wrong: <literal role="op">expr REGEXP pat</literal>

Right: <literal role="op" condition="regexp">expr REGEXP pat</literal>

  • Synonyms, when a function or operator that has multiple names but the description for all is given under a single ID. For example, AsWKT() is a synonym for AsText(), but the description for both is listed under an ID of function_astext: 

    Wrong: <literal role="func">AsText()</literal>
       <literal role="func">AsWKT()</literal>

Right: <literal role="func">AsText()</literal>
       <literal role="func" condition="astext">AsWKT()</literal>

If a function reference is to some function that is not described in the manual, no attributes should be present in the <literal> tags so that no auto-linking will be attempted. For example, the printf() function in the C standard I/O library should be written as <literal>printf()</literal>.

For <command> elements, there is no special role attribute required. If the element content matches the id attribute for a <section> or <refsection> element, the link is generated. The first word within the element is used, minus any .exe suffix that might be present.

For example, the following elements all generate links to the section that describes the mysqladmin program: 

<command>mysqladmin</command>
<command>mysqladmin.exe</command>
<command>mysqladmin -h 127.0.0.1 password</command>
<command>mysqladmin.exe -h 127.0.0.1 password</command>

For <option> elements, the role attribute indicates the program to which the option belongs. The element content provides the option name (possibly after stripping leading dashes and a following =value. A condition attribute can be provided to specify the option name explicitly, which can be useful for short-form options.

For example, the following elements all generate links to the description for the --host option of the mysqld program, which has an ID of option_mysqld_host: 

<option role="mysqld">--host</option>
<option role="mysqld">--host=host_name</option>
<option role="mysqld" condition="host">-h</option>
<option role="mysqld" condition="host">-h host_name</option>

System variables can be passed as command-line options as well, so <option> can be used for those. In such cases, the role attribute is sysvar and the option content provides the variable name, possible with dashes mapped to underscores. The following elements all generate links to the description for the max_allowed_packet system variable, which has an ID of sysvar_max_allowed_packet: 

<option role="sysvar">--max_allowed_packet=1G</option>
<option role="sysvar">--max-allowed-packet=1G</option>
<option role="sysvar">max_allowed_packet=1G</option>
<option role="sysvar">max-allowed-packet=1G</option>