Beginning with MySQL 4.1, the server supports a server-side help capability. This can be accessed from the mysql client by means of its HELP command. For example, if you enter the following command, the server returns a description for the ISNULL() function:

mysql> HELP ISNULL;
Name: 'ISNULL'
Description:
Syntax:
ISNULL(expr)

If expr is NULL, ISNULL() returns 1, otherwise it returns 0.
Examples:
mysql> SELECT ISNULL(1+1);
        -> 0
mysql> SELECT ISNULL(1/0);
        -> 1

The server gets help content from a set of tables in the mysql directory. These tables are loaded from information that is extracted from the MySQL Reference Manual.

Originally, help tags were placed in the Texinfo manual, based on an implementation devised by Victor Vagim. (The original Texinfo implementation and notes about the conversion to DocBook are described in another document, MySQL Documentation Team Historical Notes.)

To support this capability, Reference Manual documents contain embedded tags that mark content to be extracted and used for generating the contents of the help tables. These tags are based on <remark> elements, where the role attribute has a value of help-xxx that indicates tag type. Some tags also have a condition attribute to specify additional information. (“condition” has no real meaning in the context of help tagging. It was simply the most “generic” of the allowable <remark> attributes, so we press it into service for general use.)

The following discussion sets forth the allowable help tags and the rules for using them. You can examine the existing markup in the Reference Manual to see how the tags are used in practice.

These are the allowable help tags:

For any chapter that will contain help topics, you must include a help-category tag preceding any of those topics:

<remark role="help-category" condition="CATEGORY_NAME"/>

The CATEGORY_NAME value indicates the help category, and optionally the parent category. If the parent category is present, separate it from the category by an ‘@’ character. Examples:

<remark role="help-category" condition="Functions"/>
<remark role="help-category" condition="String Functions@Functions"/>

The category tag sets the context for any following help topics in the chapter until the next help-category tag.

Within a category, you mark up each topic using a small set of tags. Each topic must begin with a help-topic tag:

<remark role="help-topic" condition="TOPIC_NAME"/>

The TOPIC_NAME value indicates the topic. Examples:

<remark role="help-topic" condition="ISNULL"/>
<remark role="help-topic" condition="DELETE"/>
<remark role="help-topic" condition="DROP DATABASE"/>

The topic tag sets the context for the following keyword, syntax, description, and example tags.

To associate keywords with the topic, use a help-keywords tag and list the keywords as the content of the remark:

<remark role="help-keywords"> keyword1 keyword2 ... </remark>

Syntax, descriptive text, and examples are marked up with help-syntax, help-description, and help-example tags.

If the content for syntax, a description, or an example comprises only a single XML element, you can just precede that element with the appropriate single tag just described. If the content requires multiple elements, you should use a pair of tags, one with a -begin tag and one with an -end tag. For example, a multiple-paragraph description must be tagged using paired tags that mark the beginning and end of the description:

<remark role="help-description-begin"/>

<para>Para 1 of description</para>
<para>Para 2 of description</para>
<para>Para 3 of description</para>

<remark role="help-description-end"/>

However, a single-paragraph description can be tagged in two ways. You can use either a single (unpaired) tag, like this:

<remark role="help-description"/>

<para>Para 1 of description</para>

Or you can use paired tags, like this:

<remark role="help-description-begin"/>

<para>Para 1 of description</para>

<remark role="help-description-end"/>

Here is a complete example of a marked-up topic:

<remark role="help-topic" condition="PURGE MASTER LOGS"/>

<remark role="help-keywords">
  BEFORE TO
</remark>

<remark role="help-syntax"/>

<programlisting>
PURGE {MASTER | BINARY} LOGS TO '<replaceable>log_name</replaceable>'
PURGE {MASTER | BINARY} LOGS BEFORE '<replaceable>date</replaceable>'
</programlisting>

<remark role="help-description-begin"/>

<para>
  Deletes all the binary logs listed in the log index prior to
  the specified log or date. The logs also are removed from the
  list recorded in the log index file, so that the given log
  becomes the first.
</para>

<remark role="help-description-end"/>

<para>
  Example:
</para>

<remark role="help-example"/>

<programlisting>
PURGE MASTER LOGS TO 'mysql-bin.010';
PURGE MASTER LOGS BEFORE '2003-04-02 22:46:26';
</programlisting>

For a given help topic, the help-topic tag must be present. The other tags (for keywords, syntax, description, or examples), all are optional, although it is rare for there to be no description.

Within help topic content, only the following XML elements are allowable:

In particular, table markup cannot be used. (DocBook table markup is complex and can be difficult to deal with.) Perhaps eventually we should try to handle tables. For now, we forbid them.

Do not put help markup in the changelogs. If a topic is worth marking up for help-table content, the content is worth stating in the main chapter files.