| List: | Commits | « Previous MessageNext Message » | |
| From: | paul | Date: | April 28 2008 4:04pm |
| Subject: | svn commit - mysqldoc@docsrva: r10601 - in trunk: . mysqldoc-guide | ||
| View as plain text | |||
Author: paul Date: 2008-04-28 16:04:37 +0200 (Mon, 28 Apr 2008) New Revision: 10601 Log: r30998@frost: paul | 2008-04-28 08:51:20 -0500 Add "special markup" materal to mysqldoc-guide. (Moving from metadoc) Added: trunk/mysqldoc-guide/special-markup.xml Modified: trunk/mysqldoc-guide/formats.xml trunk/mysqldoc-guide/formatting-guide.xml Property changes on: trunk ___________________________________________________________________ Name: svk:merge - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828 7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:30997 b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:30933 + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828 7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:30998 b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:30933 Modified: trunk/mysqldoc-guide/formats.xml =================================================================== --- trunk/mysqldoc-guide/formats.xml 2008-04-28 14:04:16 UTC (rev 10600) +++ trunk/mysqldoc-guide/formats.xml 2008-04-28 14:04:37 UTC (rev 10601) Changed blocks: 2, Lines Added: 6, Lines Deleted: 2; 939 bytes @@ -137,8 +137,8 @@ <listitem> <para> - XSLT processor converts the base document into a 'prepared' - state. This builds the target + XSLT processor converts the base document into a + <quote>prepared</quote> state. This builds the target <literal>document-prepped.xml</literal>. Included in this process is the entity expansion, the incorporation of the included XML files, and any custom DocBook XML formatting @@ -295,6 +295,10 @@ section-based format below: </para> + <remark role="todo"> + Need to add a sample here + </remark> + <programlisting></programlisting> <para> Modified: trunk/mysqldoc-guide/formatting-guide.xml =================================================================== --- trunk/mysqldoc-guide/formatting-guide.xml 2008-04-28 14:04:16 UTC (rev 10600) +++ trunk/mysqldoc-guide/formatting-guide.xml 2008-04-28 14:04:37 UTC (rev 10601) Changed blocks: 1, Lines Added: 2, Lines Deleted: 0; 433 bytes @@ -2692,4 +2692,6 @@ <!-- File Names for Graphics --> + <xi:include href="special-markup.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + </chapter> Added: trunk/mysqldoc-guide/special-markup.xml =================================================================== --- trunk/mysqldoc-guide/special-markup.xml (rev 0) +++ trunk/mysqldoc-guide/special-markup.xml 2008-04-28 14:04:37 UTC (rev 10601) Changed blocks: 1, Lines Added: 1004, Lines Deleted: 0; 31764 bytes @@ -0,0 +1,1004 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + <!ENTITY % all.entities SYSTEM "all-entities.ent"> + %all.entities; +]> +<section id="special-markup"> + + <title>Special Markup</title> + + <para> + This section describes special markup that we use in the + <citetitle>MySQL Reference Manual</citetitle>: + </para> + + <itemizedlist> + + <listitem> + <para> + Markup that distinguishes sections of a document to use for + generating Unix manpages. + </para> + </listitem> + + <listitem> + <para> + Markup that distinguishes <citetitle>Reference + Manual</citetitle> content to be loaded into help tables in the + <literal>mysql</literal> database. The server uses these tables + to support its server-side help capability. + </para> + </listitem> + + <listitem> + <para> + Markup for functions, for which links to the function + descriptions can be generated automatically. + </para> + </listitem> + + </itemizedlist> + + <section id="manpage-markup"> + + <title>Markup for Unix Manpages</title> + + <para> + Some sections of the <citetitle>MySQL Reference Manual</citetitle> + describe programs, such as the sections for + <command>mysql</command> and <command>mysqladmin</command>. To + avoid writing descriptions for the programs both in the manual and + in separate Unix-style manpages (which are written using + <command>troff</command>/<command>groff</command> markup), we + generate manpages directly from the manual DocBook source. This + strategy can be used for other documents as well (for example, the + <citetitle>MySQL Test Framework Manual</citetitle>). + </para> + + <para> + Formerly, MySQL distributions contained a set of handwritten + manpage files, but these were contributed by third parties and + rarely were updated, so they became obsolete. Also, there were + some programs for which no manpages had ever been written. By + generating the manpages from the <citetitle>Reference + Manual</citetitle>, we can keep them up to date easily, and we + have a manpage for every program described in the manual. + </para> + + <note> + <para> + If the set of manpages generated from the manual changes, it's + necessary to let the build team know about it. (For example, + they need to update the <literal>.spec</literal> files used for + the RPM distributions.) Examples of changes requiring + notification of the build team: + </para> + </note> + + <itemizedlist> + + <listitem> + <para> + You mark up a new manpage in the manual. + </para> + </listitem> + + <listitem> + <para> + You change the <quote>volume</quote> for a manpage. For + example, <command>mysqld(1)</command> becomes + <command>mysqld(8)</command>. + </para> + </listitem> + + <listitem> + <para> + You remove a section from which a manpage formerly was + created. For example, <command>safe_mysqld</command> is no + longer present in MySQL 5.1. + </para> + </listitem> + + </itemizedlist> + + <para> + The DocBook XSL stylesheets have a manpage mode that can be used + for generating manpage output. The markup described here requires + at least version 1.69.0 of the stylesheets, because manpage + support was improved markedly in that version, and we use features + not supported in older versions. + </para> + + <para> + The DocBook XSL stylesheets manpage mode requires that manpage + sections be marked up using <literal><refentry></literal> + elements. One problem with using + <literal><refentry></literal> is that the DocBook DTD + prohibits <literal><refentry></literal> and + <literal><section></literal> from appearing at the same + level within a document if the document is to be considered valid. + To work around this, we wrap <literal><refentry></literal> + elements within <quote>fake</quote> + <literal><section></literal> elements so that the source + refman files pass validation. For output generation, we strip off + these fake element tags, and then either pass through the + <literal><refentry></literal> elements unchanged (for + manpage output), or map them onto regular + <literal><section></literal> elements (for all other output + formats). + </para> + + <para> + The following template shows how to mark up a section so that a + manpage can be generated from it. The + <literal><ref...></literal> tags and their subelements + should be used in the order shown, because the DTD doesn't allow + much flexibility and variations from the order shown typically + result in validation errors. + </para> + + <para> + There must be at least one <literal><refsection></literal> + element per <literal><refentry></literal>. By convention, + the first should be titled <quote>Description</quote>. If there + are further subdivisions to be made, those should also be marked + up as <literal><refsection></literal> elements. It is + permissible to nest <literal><refsection></literal> + elements. + </para> + + <para> + Here is a prototype for a manual section that generates a manpage: + </para> + +<programlisting> +<section id="fake-id-for-PROGNAME-manpage-section-wrapper"> + + <title>fake title for PROGNAME manpage section wrapper</title> + + <refentry id="PROGNAME"> + + <!-- initial index terms go here --> + + <refmeta> + <refentrytitle>PROGNAME</refentrytitle> + <manvolnum>VOLNUM</manvolnum> + <refmiscinfo class="manual">MySQL Database System</refmiscinfo> + <refmiscinfo class="source">MySQL</refmiscinfo> + <refmiscinfo class="version">VERSION</refmiscinfo> + <refmiscinfo class="refman">PURPOSE-FOR-TITLE</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>PROGNAME</refname> + <refpurpose>PURPOSE-FOR-MANPAGE</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>PROGNAME ARGUMENT-SYNTAX</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection id="PROGNAME-description"> + + <title>Description</title> + + <para> + Description of the program, how to use it, its allowable + command-line options, and so forth. + </para> + + </refsection> + + </refentry> + +</section> +</programlisting> + + <para> + In the template, make the following substitutions: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>PROGNAME</literal> = program name + </para> + + <para> + If the program name occurs within an element attribute value, + underscores in the name should be written as dashes. For + example, <literal>mysql_config</literal> becomes + <literal>mysql-config</literal>. + </para> + </listitem> + + <listitem> + <para> + <literal>VOLNUM</literal> = Unix manpage <quote>volume</quote> + number + </para> + + <para> + Most of our manpages are part of volume 1. The + <command>mysqld</command> and <command>mysqlmanager</command> + manpages are in volume 8. + </para> + </listitem> + + <listitem> + <para> + <literal>PURPOSE-FOR-TITLE</literal>, + <literal>PURPOSE-FOR-MANPAGE</literal> = short phrase + describing program purpose + </para> + + <para> + The purpose string will appear with the program name in the + output, but which of the two strings to use depends on the + output format. Manpages typically begin with a name section + that looks like this, where words in the description are not + title-capped: + </para> + +<programlisting> +.SH "NAME" +myprog \- a program for doing this and that +</programlisting> + + <para> + Here, <quote>a program for doing this and that</quote> is the + text to use for <literal>PURPOSE-FOR-MANPAGE</literal>. + </para> + + <para> + In non-manpage output, the name and description become a + section title, so words in the description should be + title-capped: + </para> + +<programlisting> +<title>myprog - A Program for Doing This and That<title> +</programlisting> + + <para> + Here, <quote>A Program for Doing This and That</quote> is the + text to use for <literal>PURPOSE-FOR-TITLE</literal>. + </para> + + <para> + To accommodate both output formats, we include both + description strings in the manpage markup. The title-capped + version is included using a + <literal><refmiscinfo></literal> element (with a + <literal>class</literal> attribute of + <literal>"refman"</literal>) that does not appear in manpage + output. The <literal><refmiscinfo></literal> element + does not allow much internal markup. In particular, + <literal><literal></literal> and + <literal><command></literal> are not allowed. + </para> + + <para> + In some cases, a manual page describes more than one program. + For example, the same material in the <citetitle>MySQL 4.1 + Reference Manual</citetitle> describes both + <command>myisamchk</command> and <command>isamchk</command>. + To handle this, include one + <literal><refnamediv></literal> element for each + program. The first such element should be for the primary + program described by the manpage. For example: + </para> + +<programlisting> +<refnamediv> + <refname>myisamchk</refname> + <refpurpose>MyISAM table-maintenance utility</refpurpose> +</refnamediv> + +<refnamediv> + <refname>isamchk</refname> + <refpurpose>ISAM table-maintenance utility</refpurpose> +</refnamediv> +</programlisting> + + <para> + When the file is processed, the manpage stylesheets will + produce a file named <filename>myisamchk.1</filename> that + contains the manpage contents, and another <quote>stub</quote> + file named <filename>isamchk.1</filename> that contains a + <literal>.so</literal> directive that simply includes the + other page: + </para> + +<programlisting> +.so man1/myisamchk.1 +</programlisting> + </listitem> + + <listitem> + <para> + <literal>VERSION</literal> = version of MySQL to which the + manual applies (4.1, 5.0, 5.1, and so forth) + </para> + + <para> + If the document is unversioned, omit the version element. + </para> + </listitem> + + <listitem> + <para> + <literal>ARGUMENT-SYNTAX</literal> = syntax for any arguments + that the program takes + </para> + + <para> + The <literal><cmdsynopsis></literal> value describes + program invocation syntax. It appears in the + <literal>SYNOPSIS</literal> section of manpage output. It does + not appear in non-manpage output. + </para> + </listitem> + + <listitem> + <para> + Where the <quote>initial index terms</quote> comment appears, + you may add <literal><indexterm></literal> elements for + index terms that apply to the program as a whole. Index terms + for specific features probably are better placed near the text + that describes the feature. + </para> + </listitem> + + </itemizedlist> + + <para> + Output generation always begins with a preprocessing step. For + non-manpage output from a source document + <filename>manual.xml</filename>, we generate + <filename>manual-prepped.xml</filename>, and then run that through + the appropriate DocBook XSL stylesheets. For manpage output, we + generate <filename>manual-manprepped.xml</filename>, and run that + through the manpage DocBook XSL stylesheets. The preprocessing in + both cases is done using the + <filename>xsl.d/dbk-prep.xsl</filename> transform, where the type + of <literal><refentry></literal> handling to be done is + handled by setting the value of the + <literal>$map.refentry.to.section</literal> parameter. See the + comments in <filename>dbk-prep.xsl</filename> for more + information. + </para> + + <para> + For manpage generation, we also have a postprocessing step that + acts on the set of mapages as a whole. The postprocessing script + is <command>tools/fixup-manpages.pl</command>. For each manpage + file, it adds this information: + </para> + + <itemizedlist> + + <listitem> + <para> + A <literal>SEE ALSO</literal> section that names every + <emphasis>other</emphasis> manpage and provides the URL to the + online <citetitle>Reference Manual</citetitle>. + </para> + </listitem> + + <listitem> + <para> + An <literal>AUTHOR</literal> section that names MySQL AB and + indicates that the software comes with no warranty. + </para> + </listitem> + + </itemizedlist> + + <para> + For the <literal>SEE ALSO</literal> section to be generated + properly, <command>fixup-manpages.pl</command> must be invoked + with the names of <emphasis>all</emphasis> manpages as its + arguments. <command>fixup-manpages.pl --help</command> shows the + help message that describes the invocation syntax. + </para> + + <remark role="todo"> + Fix these xrefs + </remark> + +<!-- + <para> + For more information on the XSL transforms and + <command>make</command> target rules for manpage processing, see + <xref linkend="make-prepped"/>, and + <xref linkend="make-manpage"/>. + </para> +--> + + </section> + + <section id="helptag-markup"> + + <title>Help Tag Markup</title> + + <para> + Beginning with MySQL 4.1, the server supports a server-side help + capability. This can be accessed from the <command>mysql</command> + client by means of its <literal>HELP</literal> command. For + example, if you enter the following command, the server returns a + description for the <literal>ISNULL()</literal> function: + </para> + +<programlisting> +mysql> <userinput>HELP ISNULL;</userinput> +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 +</programlisting> + + <para> + The server gets help content from a set of tables in the + <literal>mysql</literal> directory. These tables are loaded from + information that is extracted from the <citetitle>MySQL Reference + Manual</citetitle>. + </para> + + <para> + 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, <citetitle>MySQL Documentation Team + Historical Notes</citetitle>.) + </para> + + <para> + To support this capability, <citetitle>Reference + Manual</citetitle> 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 + <literal><remark></literal> elements, where the + <literal>role</literal> attribute has a value of + <literal>help-<replaceable>xxx</replaceable></literal> that + indicates tag type. Some tags also have a + <literal>condition</literal> attribute to specify additional + information. (<quote>condition</quote> has no real meaning in the + context of help tagging. It was simply the most + <quote>generic</quote> of the allowable + <literal><remark></literal> attributes, so we press it into + service for general use.) + </para> + + <para> + The following discussion sets forth the allowable help tags and + the rules for using them. You can examine the existing markup in + the <citetitle>Reference Manual</citetitle> to see how the tags + are used in practice. + </para> + + <para> + These are the allowable help tags: + </para> + + <itemizedlist> + + <listitem> + <para> + Begin a category: + </para> + +<programlisting> +<remark role="help-category" condition="<replaceable>CATEGORY_NAME</replaceable>"/> +</programlisting> + </listitem> + + <listitem> + <para> + Begin a topic within the current category: + </para> + +<programlisting> +<remark role="help-topic" condition="<replaceable>TOPIC_NAME</replaceable>"/> +</programlisting> + </listitem> + + <listitem> + <para> + Specify keywords for the current topic: + </para> + +<programlisting> +<remark role="help-keywords"> <replaceable>keyword1 keyword2</replaceable> ... </remark> +</programlisting> + </listitem> + + <listitem> + <para> + Specify syntax for the current topic: + </para> + +<programlisting> +<remark role="help-syntax"/> +</programlisting> + + <para> + Or: + </para> + +<programlisting> +<remark role="help-syntax-begin"/> +<remark role="help-syntax-end"/> +</programlisting> + </listitem> + + <listitem> + <para> + Specify descriptive text for the current topic: + </para> + +<programlisting> +<remark role="help-description"/> +</programlisting> + + <para> + Or: + </para> + +<programlisting> +<remark role="help-description-begin"/> +<remark role="help-description-end"/> +</programlisting> + </listitem> + + <listitem> + <para> + Provide an example for the current topic: + </para> + +<programlisting> +<remark role="help-example"/> +</programlisting> + + <para> + Or: + </para> + +<programlisting> +<remark role="help-example-begin"/> +<remark role="help-example-end"/> +</programlisting> + </listitem> + + </itemizedlist> + + <para> + For any chapter that will contain help topics, you must include a + <literal>help-category</literal> tag preceding any of those + topics: + </para> + +<programlisting> +<remark role="help-category" condition="<replaceable>CATEGORY_NAME</replaceable>"/> +</programlisting> + + <para> + The <replaceable>CATEGORY_NAME</replaceable> value indicates the + help category, and optionally the parent category. If the parent + category is present, separate it from the category by an + ‘<literal>@</literal>’ character. Examples: + </para> + +<programlisting> +<remark role="help-category" condition="Functions"/> +<remark role="help-category" condition="String Functions@Functions"/> +</programlisting> + + <para> + The category tag sets the context for any following help topics in + the chapter until the next <literal>help-category</literal> tag. + </para> + + <para> + Within a category, you mark up each topic using a small set of + tags. Each topic must begin with a <literal>help-topic</literal> + tag: + </para> + +<programlisting> +<remark role="help-topic" condition="<replaceable>TOPIC_NAME</replaceable>"/> +</programlisting> + + <para> + The <replaceable>TOPIC_NAME</replaceable> value indicates the + topic. Examples: + </para> + +<programlisting> +<remark role="help-topic" condition="<literal>ISNULL</literal>"/> +<remark role="help-topic" condition="<literal>DELETE</literal>"/> +<remark role="help-topic" condition="<literal>DROP DATABASE</literal>"/> +</programlisting> + + <para> + The topic tag sets the context for the following keyword, syntax, + description, and example tags. + </para> + + <para> + To associate keywords with the topic, use a + <literal>help-keywords</literal> tag and list the keywords as the + content of the remark: + </para> + +<programlisting> +<remark role="help-keywords"> <replaceable>keyword1 keyword2</replaceable> ... </remark> +</programlisting> + + <para> + Syntax, descriptive text, and examples are marked up with + <literal>help-syntax</literal>, + <literal>help-description</literal>, and + <literal>help-example</literal> tags. + </para> + + <para> + 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 + <literal>-begin</literal> tag and one with an + <literal>-end</literal> tag. For example, a multiple-paragraph + description must be tagged using paired tags that mark the + beginning and end of the description: + </para> + +<programlisting> +<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"/> +</programlisting> + + <para> + However, a single-paragraph description can be tagged in two ways. + You can use either a single (unpaired) tag, like this: + </para> + +<programlisting> +<remark role="help-description"/> + +<para>Para 1 of description</para> +</programlisting> + + <para> + Or you can use paired tags, like this: + </para> + +<programlisting> +<remark role="help-description-begin"/> + +<para>Para 1 of description</para> + +<remark role="help-description-end"/> +</programlisting> + + <para> + Here is a complete example of a marked-up topic: + </para> + +<programlisting> +<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> +</programlisting> + + <para> + For a given help topic, the <literal>help-topic</literal> 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. + </para> + + <para> + Within help topic content, only the following XML elements are + allowable: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal><programlisting></literal> + </para> + </listitem> + + <listitem> + <para> + <literal><para></literal> + </para> + </listitem> + + <listitem> + <para> + <literal><itemizedlist></literal> + </para> + </listitem> + + <listitem> + <para> + <literal><orderedlist></literal> + </para> + </listitem> + + </itemizedlist> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <remark role="todo"> + Fix these xrefs + </remark> + +<!-- + <para> + Help markup is processed using the XSL transforms and + <command>make</command> target rules described in + <xref linkend="make-help-table"/>. + </para> +--> + + </section> + + <section id="function-markup"> + + <title>Function Markup</title> + + <para> + For references to functions, we use the + <literal><function></literal> element. In addition, if the + function is one that has a description elsewhere in the manual + that is associated with a unique ID, we include attributes in the + opening <literal><function></literal> tag that enable the + <filename>dbk-prep.xsl</filename> transform to add a + <literal><link></literal> to the description. In this way, + we get auto-linking of the function reference to its description, + which is useful for those output formats that support hyperlinking + (HTML, PDF). + </para> + + <para> + The attributes that identify a function as one for which a link + should be generated automatically are: + </para> + + <itemizedlist> + + <listitem> + <para> + The <literal>role</literal> attribute, if present, identifies + the type of function. The value should be + <literal>"capi"</literal> for a C API function, + <literal>"sql"</literal> for a SQL function, or + <literal>"sqlop"</literal> for a SQL operator. + </para> + </listitem> + + <listitem> + <para> + A <literal>condition</literal> attribute may be added as a + hint. The <filename>dbk-prep.xsl</filename> transform tries to + determine the ID to use for the link, using the rules + described shortly. If it cannot determine the ID, the + <literal>condition</literal> attribute indicates which ID to + use. + </para> + </listitem> + + </itemizedlist> + + <para> + <filename>dbk-prep.xsl</filename> also converts + <literal><function></literal> tags to + <literal><literal></literal> to avoid the extra commas that + get added for <literal><function></literal> by the DocBook + XSL stylesheets in some cases for HTML/PDF output. + </para> + + <para> + When <filename>dbk-prep.xsl</filename> determines the ID for the + <literal>linkend</literal> attribute when generating + <literal><link></literal> elements, the name-to-ID mapping + rule depends on the function type. + </para> + + <itemizedlist> + + <listitem> + <para> + C API function: Use element content up to the leading open + parenthesis, with underscores converted to dashes. + </para> + + <para> + This reference will link to an ID of + <literal>mysql-real-connect</literal>: + </para> + +<programlisting> +<function role="capi">mysql_real_connect()</function> +</programlisting> + </listitem> + + <listitem> + <para> + SQL function: Use element content up to the leading open + parenthesis, with underscores converted to dashes and letters + converted to lowercase, then add a + <literal>function_</literal> prefix. Some functions can be + written without parentheses, so if no opening parenthesis is + found, use the entire element content. + </para> + + <para> + These references both will link to an ID of + <literal>function_current-timestamp</literal>: + </para> + +<programlisting> +<function role="sql">CURRENT_TIMESTAMP()</function> +<function role="sql">CURRENT_TIMESTAMP</function> +</programlisting> + </listitem> + + <listitem> + <para> + SQL operator: Use the entire element content, with underscores + and spaces converted to dashes and letters converted to + lowercase, then add an <literal>operator_</literal> prefix. + </para> + + <para> + This reference will link to an ID of + <literal>operator_binary</literal>: + </para> + +<programlisting> +<function role="sqlop">BINARY</function> +</programlisting> + </listitem> + + </itemizedlist> + + <para> + In some cases, the content of the + <literal><function></literal> element is unsuitable for + constructing an ID. In such cases, include a + <literal>condition</literal> attribute as a hint about the ID to + use. It is not necessary to add the leading + <literal>function_</literal> or <literal>operator_</literal> for + the <literal>condition</literal> attribute value. That can be + determined automatically as needed because the + <literal>role</literal> attribute value determines whether the + element refers to a function or an operator. + </para> + + <para> + A <literal>condition</literal> attribute is needed when the + element contains any of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Non-alphanumeric text: + </para> + +<programlisting> +Wrong: <function role="sqlop">*</function> + +Right: <function role="sqlop" condition="times">*</function> +</programlisting> + </listitem> + + <listitem> + <para> + Extra text within the element that confuses the content-to-ID + conversion: + </para> + +<programlisting> +Wrong: <function role="sqlop">expr REGEXP pat</function> + +Right: <function role="sqlop" condition="regexp">expr REGEXP pat</function> +</programlisting> + </listitem> + + <listitem> + <para> + Synonyms, when a function or operator that has multiple names + but the description for all is given under a single ID. For + example, <literal>AsWKT()</literal> is a synonym for + <literal>AsText()</literal>, but the description for both is + listed under an ID of <literal>function_astext</literal>: + </para> + +<programlisting> +Wrong: <function role="sql">AsText()</function> + <function role="sql">AsWKT()</function> + +Right: <function role="sql">AsText()</function> + <function role="sql" condition="astext">AsWKT()</function> +</programlisting> + </listitem> + + </itemizedlist> + + <para> + If a function reference is to some function that is not described + in the manual, no attributes should be present in the + <literal><function></literal> tags so that no auto-linking + will be attempted. For example, the <literal>printf()</literal> + function in the C standard I/O library should be written as + <literal><function>printf()</function></literal>. + </para> + + </section> + +</section>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r10601 - in trunk: . mysqldoc-guide | paul | 28 Apr |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.989 sec. using MySQL 5.1.14-beta-log