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 auto-link.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. We also do this for NDB node configuration parameters, NDB API class and method names, ndbinfo table names, and MySQL Cluster Manager client commands.

  • 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, is for an INFORMATION_SCHEMA table, ps for a performance_schema table, se for a storage engine, sysvar for a system variable, statvar for a status variable, sqlmode for an 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), priv for an access privilege, ndbapi (or possibly ndbapi:$class_name; see below) for an NDB API class, class member, type, or struct, mgmapi for an MGM API function, ndbinfo for the ndbinfo database or one of its tables, or mcmcmd for a MySQL Cluster Manager client command.

    Auto-linking of MySQL Cluster configuration parameters is also supported. For these, the role value starts with the prefix ndbparam:; this is explained further later in this section.

  • A condition attribute may be added as a hint. The auto-link.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 auto-link.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>
    
  • performance_schema table: Use the entire element content (stripping off any performance_schema. qualifier), with underscores converted to dashes and letters converted to lowercase. Then add a -table suffix, in most cases. IDs for sections describing performance_schema tables do not always correspond to the table name, so the link generator actually uses a lookup table to map table names to section IDs.

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

    <literal role="ps">threads</literal>
    <literal role="ps">performance_schema.threads</literal>
    
  • Storage engine. Convert the element content to lowercase and use a lookup table to map engine names to section IDs. The following reference links to an ID of innodb-storage-engine:

    <literal role="se">InnoDB</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>
    
  • MySQL Cluster configuration parameter: The role is constructed and used somewhat differently from the others just described. A configuration parameter is used in one or more specific sections of the MySQL Cluster config.ini file; some parameters have differing characteristics depending on the config.ini section in which they occur, and a given parameter does not necessarily apply in all sections of the file. Each valid mapping between a parameter name and a config.ini section type (often referred to simply as the parameter's type) is described separately in MySQL Cluster Configuration Files, where each such description provides a target having a unique identifier. These IDs take the form ndbparam-type-name, where type is the parameter type (that is, the config.ini section to which it applies), and name is the parameter's name converted to lowercase.

    For an NDB configuration parameter, the role value takes the form ndbparam:type, where type is the parameter type (which corresponds to the name of a section of config.ini). Because there is no way to determine the parameter type automatically, the type must be specified by the author. Possible types are shown in the following list:

    • api

    • computer

    • mgmd

    • ndbd

    • ndbmtd

    • sci

    • shm

    • tcp

    • system (not currently used or supported for end users)

    For example, <literal role="ndbparam:ndbd">HostName<literal> generates a link to the target having the ID ndbparam-ndbd-hostname, and <literal role="ndbparam:tcp">NodeIdServer<literal> generates a link to the target whose ID is ndbparam-tcp-nodeidserver.

  • NDB API class, class member, type, or struct (MySQL Cluster): First, replace any underscores in the element text with dashes, and remove any parentheses (we refer to this modified string as $dashes hereafter).

    If the role attribute does not contain a ':' character, handle as follows:

    Does $dashes contain the string '::'? If not, use the entire text of $dashes for the ID; that is, we assume the original element text is the name of an NDB API class or struct. Otherwise (if $dashes does contain '::'), replace '::' with a dash and use this for the ID.

    If the role attribute does contain a colon character (':'), handle as follows:

    We assume that the element text is the unqualified name of a class member. In this case, the name of the parent class is supplied in the role as the portion following the colon; we can represent the entire role attribute value as ndbapi:$class. We split $class from the role attribute, then convert $class to lowercase and replace any underscores it contains to dashes. We use the result of this conversion, followed by a dash, and then by $dashes as the ID.

    Finally, we prefix the ID obtained previously with ndb-.

    Example 1: The following reference links to the ID ndb-table:

    <literal role="ndbapi">Table</literal>
    

    Example 2: Each of the following 2 references links to the ID ndb-table-singleusermode:

    <literal role="ndbapi">Table::SingleUserMode</literal>
    
    <literal role="ndbapi:Table">SingleUserMode</literal>
    

    In the second case just shown, the name of the parent class (Table) is supplied as part of the role attribute.

    Example 3: The following reference links to the ID ndb-ndb-cluster-connection (note that ndb-ndb- is not a typo!):

    <literal role="ndbapi">Ndb_cluster_connection</literal>
    

    Example 4: Each of the following 2 references links to the ID ndb-ndb-cluster-connection-wait-until-ready (again, ndb-ndb- is correct):

    <literal role="ndbapi">Ndb_cluster_connection::wait_until_ready()</literal>
    
    <literal role="ndbapi:Ndb_cluster_connection">wait_until_ready()</literal>
    

    In the second case just shown, the name of the parent class (Ndb_cluster_connection) is supplied as part of the role attribute.

  • MGM API function, type or struct (MySQL Cluster): Replace any underscores in the element text with dashes, and remove any parentheses (and anything between them, if necessary). Convert to lowercase. Prefix the result with mgm-.

    Example 1. The following generates a link to the ID mgm-ndb-mgm-create-handle:

    <literal role="mgmapi">ndb_mgm_create_handle()</literal>
    

    Example 2. The following generates a link to the ID mgm-ndbmgmhandle:

    <literal role="mgmapi">NdbMgmHandle</literal>
    
  • ndbinfo database or table: Prefix with mysql-cluster-. If the element text contains a period: Strip it and any text leading up to it. If the remainder (call it r) is not the string "ndbinfo", add ndbinfo- to the prefix. Convert any underscores contained in the remainder (r) to dashes, and use the result.

    Example 1. The following generates a link to the ID mysql-cluster-ndbinfo:

    <literal role="ndbinfo">ndbndbinfo</literal>
    

    Example 2. Each of the following generates a link to the ID mysql-cluster-ndbinfo-config-params:

    <literal role="ndbinfo">ndbinfo.config_params</literal>
    
    <literal role="ndbinfo">config_params</literal>
    
  • MySQL Cluster Manager client command: Prefix with mcm-. Convert the element text to lowercase, as well as spaces and underscores to dashes. If this result matches a section ID in the current document, use it. Otherwise, check for a nonempty condition attribute; if one is found, prefix it with mcm- and use this instead.

    Example. Each of the following generates a link pointing to section having the ID mcm-stop-agents:

    <literal role="mcmcmd">stop agents</literal>
    
    <literal role="mcmcmd" condition="stop-agents">stop agents mysite</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>
    

    Exceptions: 1. role attribute values for NDB configuration parameters must contain a colon (:). 2. role attribute values for NDB API class members may contain a colon (:) when there is a need to specify the parent class. Important: condition is neither used nor supported for marking up NDB configuration parameters or for NDB API classes, class members, or structs; any condition attribute value is simply ignored in both cases.

  • 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 normally no special role attribute required. If the element content matches the id attribute for a <section> or <refsection> element within the current document, the link is generated. Only the first word within the element is used, minus any .exe suffix that might be present; lettercasing is preserved.

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>

MySQL Cluster programs. MySQL Cluster programs such as ndbd, ndb_mgmd, and ndb_mgm are also auto-linked. These programs can be identified in virtue of the fact that all of their names begin with ndb; when this prefix is found in the element text, the name of the executable is handled as above, then prefixed with mysql-cluster-programs- to produce the correct ID.

Examples. The following elements generate links to, respectively, mysql-cluster-programs-ndbd, mysql-cluster-programs-ndb-mgm, mysql-cluster-programs-ndb-error-reporter, and mysql-cluster-programs-ndb-size-pl:

<command>ndbd -e "ALL REPORT MemoryUsage"</command>
<command>ndb_mgm.exe</command>
<command>ndb_error_reporter</command>
<command>ndb_size.pl</command>

Normally, links for <command> elements are generated to IDs found within the current document only. However, there may be times when you wish to allow links to be generated to program descriptions residing in other documents. For example, you may wish for instances of <command>mysql</command> in the MySQL Cluster Manager documentation to generate links to the element having the ID mysql, even though that node is located in the MySQL manual. To bypass the in-document check normally used, you can set the following in the document's Makefile:

GENERATE_CROSSBOOK_COMMAND_AUTOLINK = 1

This setting works only if GENERATE_AUTOLINK is also set to 1 in the same Makefile; otherwise, it is ignored.

With GENERATE_CROSSBOOK_COMMAND_AUTOLINK enabled, links are generated for all <command> elements in the document; bad IDs are caught only when building the -prepped target or an end-user format such as PDF. If the external document's directory is not already listed in the Makefile' IDMAP_REFS variable, you may need to add it (and possibly to run make idmap afterwards). You can suppress link generation for a given <command> element by adding a role="nolink" attribute to it, like this:

<command role="nolink">mysql</command>

role="nolink" has no effect otherwise, and is ignored unless both GENERATE_CROSSBOOK_COMMAND_AUTOLINK and GENERATE_AUTOLINK are set to 1.

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=<replaceable>host_name</replaceable></option>
<option role="mysqld" condition="host">-h</option>
<option role="mysqld" condition="host">-h <replaceable>host_name</replaceable></option>

MySQL Cluster program options. Some options for MySQL Cluster programs are common to all MySQL Cluster programs. For these, you must use ndb_common as the value of the role attribute.

Examples. The two elements shown in the first line following generate links to option_ndb_common_version; the element on the second line generates a link to option_ndb_common_connect-string:

<option role="ndb_common">--version</option> (short form <option role="ndb_common">-V</option>)
<option role="ndb_common">--connect-string="nodeid=2;host=ndb_mgmd.mysql.com:1186"</option>

For a listing of options common to all MySQL Cluster programs, see Options Common to MySQL Cluster Programs — Options Common to MySQL Cluster Programs.

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>