| List: | Internals | « Previous MessageNext Message » | |
| From: | paul | Date: | July 21 2005 1:36am |
| Subject: | bk commit - mysqldoc@docsrva tree (paul:1.3094) | ||
| View as plain text | |||
Below is the list of changes that have just been committed into a local mysqldoc repository of paul. When paul does a push these changes will be propagated to the main repository and, within 24 hours after the push, to the public repository. For information on how to access the public repository see http://www.mysql.com/doc/I/n/Installing_source_tree.html ChangeSet 1.3094 05/07/20 18:36:20 paul@stripped +4 -0 Improve manpage markup processing. xsl.d/dbk-prep.xsl 1.8 05/07/20 18:36:18 paul@stripped +125 -47 Update manpage markup preprocessing. tools/fix-manpages.pl 1.2 05/07/20 18:36:18 paul@stripped +0 -1 Delete debugging message. refman/mysql-apis.xml 1.17 05/07/20 18:36:18 paul@stripped +225 -207 Update manpage markup. make.d/xml-prep 1.5 05/07/20 18:36:17 paul@stripped +1 -1 Change manpage make rule. # This is a BitKeeper patch. What follows are the unified diffs for the # set of deltas contained in the patch. The rest of the patch, the part # that BitKeeper cares about, is below these diffs. # User: paul # Host: frost.snake.net # Root: /Volumes/frost2/MySQL/bk/mysqldoc --- 1.4/make.d/xml-prep 2005-07-16 13:17:14 -05:00 +++ 1.5/make.d/xml-prep 2005-07-20 18:36:17 -05:00 @@ -19,7 +19,7 @@ %-manprepped.xml: %.xml $(DBK_PREP_XSL_DEPS) $(BUG_PREP) $(XSLTPROC) \ - --param map.refentry.to.section 0 \ + --param generate.manpages 1 \ $(DBK_PREP_XSL) $< | $(BUG_PREP) > $@ clean:: --- 1.1/tools/fix-manpages.pl 2005-07-16 17:37:35 -05:00 +++ 1.2/tools/fix-manpages.pl 2005-07-20 18:36:18 -05:00 @@ -67,7 +67,6 @@ warn "processing $file...\n"; my ($basename) = $file =~ m|([^/]+)$|; my $in_man; - warn $basename, "\n"; { open IN, $file or die "Cannot open $file for reading: $!\n"; --- 1.7/xsl.d/dbk-prep.xsl 2005-07-16 13:17:16 -05:00 +++ 1.8/xsl.d/dbk-prep.xsl 2005-07-20 18:36:18 -05:00 @@ -17,11 +17,14 @@ - <title> within <glossdiv> becomes the <title> of the <variablelist>. - Map <glossentry>, <glossterm>, <glossdef> to <varlistentry>, <term>, <listitem>. -- Strip comments. Also, if the comment is followed by a text node that - begins with a newline, remove the newline as well. The effect of that - is to completely remove the last line on which the comment occurs, - which helps to prevent extraneous blank lines in <programlisting> - elements. +- Handle <refentry> elements differentially for manpage and non-manpage + output. (Depends on the setting of the $generate.manpages parameter.) +- Strip comments (by not processing them). Also, if the comment is + followed by a text node that begins with a newline, remove the + newline as well. The effect of that is to completely remove the + last line on which the comment occurs, which helps to prevent + extraneous blank lines in <programlisting> elements that contain + comments. Other whitespace is preserved @@ -39,71 +42,150 @@ <xsl:preserve-space elements="*"/> <!-- -Whether to map <refentry> (manpage) elements to <section> elements. -The default is 1 (true), which allows subsequently invoked stylesheets that -use this preprocessor not to have to know about <refentry> structure. -Set to 0 (false) for generating manpages, which need to see <refentry> -elements. + Whether to generate output for manpage production. The default is + 0 (false); that is, map <refentry> elements to <section> elements. + This allows subsequently invoked stylesheets that use this preprocessor + not to have to know about <refentry> structure. Set to 1 (true) + for generating manpages, which are based on <refentry> elements. + +TODO: +At some point, could change the later processors to know about refentry +directly. Then the only thing that would need to be done here would be +to strip off the wrapper <section> elements. --> -<xsl:param name="map.refentry.to.section" select="1"/> +<xsl:param name="generate.manpages" select="0"/> <!-- -Handle <refentry> by either passing it through unchanged, or mapping -it to a <section> + <section> and <refentry> cannot appear at the same level within + their parent. To get around this so that valid source documents + can be written, sections from which manpages can be generated are + represented as <refentry> children of a <section>. That is, the + <section> (and required <title> element) are used as a "wrapper." + + However, if such documents were formatted as is, we'd end up with + an extraneous level in the TOC. Also, we don't want refentry markup + when not formatting manpage output. So we preprocess <section> + elements that have one or more <refentry> children as follows: + + - If $generate.manpages is 0, discard the "wrapper" <section> and <title> + and map the <refentry> markup onto <section>. The result has only + <section> elements and no <refentry> elements. + - If $generate.manpages is not 0, discard the "wrapper" <section> and + <title>, and pass through the <refentry> children. Note that the + resulting document may be invalid, because it might have a mix of + <section> and <refentry> at the same level. However, we don't care + at this point because the document will be used only for generating + manpage output and we don't care about the <section> elements, or + indeed even about validity. I suppose we could actually preprocess + by producing output consisting *only* of the <refentry> elements, but + that might mess up <xref> resolution... + + One additional subtlety: + + In a manual page, the first section typically is a general description. + For non-manpage production, write out this information without write + any <section> tags. That way, we don't have: + + <section> + <title>program-name - program-purpose</title> + <section> + <para>description of program ... </para> + </section> + <section> other sections ... </section> + <section> other sections ... </section> + + We have this instead: + + <section> + <title>program-name - program-purpose</title> + <para>description of program ... </para> + <para>description of program ... </para> + <section> other sections ... </section> + <section> other sections ... </section> + + By doing this, we avoid an "empty" first page that has only the + title and the TOC for the other sections. +--> + +<!-- + For a <section> that contains <refentry> elements, process only + those elements. This has the effect of discarding the <section> + and its <title>. The <refentry> elements are handled differentially + depending on the $generate.manpages setting. +--> + +<xsl:template match="section[child::refentry]"> + <!-- process refentry children --> + <xsl:apply-templates select="refentry"/> +</xsl:template> + +<!-- + Handle <refentry>. + If $generate.manpages is 0: + Map <refentry> to <section>, using <refnamediv> information to + generate the <title> and ignoring everything else but <refsection>. + Also, for the first <refsection>, omit only the non-<title> content, + which has the effect of stripping the <refsection> tags and the <title>. + Otherwise: + Pass <refentry> through unchanged. --> <xsl:template match="refentry"> <xsl:choose> - <xsl:when test="$map.refentry.to.section = 0"> - <!-- pass refentry through unchanged --> - <refentry> - <xsl:copy-of select="@*"/> - <xsl:copy-of select="node()"/> - </refentry> - </xsl:when> - <xsl:otherwise> + <xsl:when test="$generate.manpages = 0"> <!-- map refentry to section --> - <!-- use refmeta and refnamediv elements for title --> <section> <xsl:copy-of select="@*"/> <title> + <!-- program-name — program-purpose --> <xsl:apply-templates select="refnamediv/refname/node()"/> - <!-- — --> <xsl:text> — </xsl:text> - <xsl:apply-templates select="refmeta/refmiscinfo/node()"/> + <xsl:apply-templates select="refnamediv/refpurpose/node()"/> </title> <xsl:text>
</xsl:text> - <xsl:apply-templates select="refsection"/> + <xsl:apply-templates select="refsection[1]/node()[not(self::title)]"/> + <xsl:apply-templates select="refsection[position() > 1]"/> </section> + </xsl:when> + <xsl:otherwise> + <refentry> + <xsl:copy-of select="@*"/> + <xsl:apply-templates/> + </refentry> </xsl:otherwise> </xsl:choose> - <xsl:text>
</xsl:text> </xsl:template> +<!-- + Handle <refsection>. + If $generate.manpages is 0: + Map <refsection> to <section> + Otherwise: + Pass <refsection> through unchanged. +--> + <xsl:template match="refsection"> <xsl:choose> - <xsl:when test="$map.refentry.to.section = 0"> - <!-- pass refsection through unchanged --> - <refentry> - <xsl:copy-of select="@*"/> - <xsl:copy-of select="node()"/> - </refentry> - </xsl:when> - <xsl:otherwise> + <xsl:when test="$generate.manpages = 0"> <!-- map refsection to section --> <section> <xsl:copy-of select="@*"/> <xsl:apply-templates/> </section> + </xsl:when> + <xsl:otherwise> + <refsection> + <xsl:copy-of select="@*"/> + <xsl:apply-templates/> + </refsection> </xsl:otherwise> </xsl:choose> - <xsl:text>
</xsl:text> </xsl:template> <!-- -Match text elements that are the first child of <programlisting> -and chop any leading newline. + Match text elements that are the first child of <programlisting> + and chop any leading newline. --> <xsl:template match="text()[1][parent::programlisting]"> @@ -171,15 +253,11 @@ </para> </xsl:template> -<!-- Strip comments --> - -<xsl:template match="comment()"/> - <!-- -Match text nodes that follow a comment. If the text begins with a -newline, remove the newline. + Match text nodes that follow a comment. If the text begins with a + newline, remove the newline. -Matching rule uses node(), not *, because * does not include comment(). + Matching rule uses node(), not *, because * does not include comment(). --> <xsl:template match="text()[preceding-sibling::node()[1][self::comment()]]"> @@ -195,10 +273,10 @@ <!-- -Copy everything else. + Copy everything else. -Matching rules use * and text(), not node(), because node() includes -comment(). + Matching rules use * and text(), not node(), because node() includes + comment(). --> <xsl:template match="/ | * | text() | @* | processing-instruction()"> --- 1.16/refman/mysql-apis.xml 2005-07-20 16:59:39 -05:00 +++ 1.17/refman/mysql-apis.xml 2005-07-20 18:36:18 -05:00 @@ -87,48 +87,52 @@ </itemizedlist> - <refentry id="msql2mysql"> + <section id="fake-id-for-msql2mysql-manpage-section-wrapper"> - <indexterm type="concept"> - <primary><command>msql2mysql</command></primary> - </indexterm> - - <refmeta> - <refentrytitle>msql2mysql</refentrytitle> - <manvolnum>man</manvolnum> - <refmiscinfo>Convert MySQL Programs for Use with MySQL</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>msql2mysql</refname> - <refpurpose>convert MySQL programs for use with MySQL</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>msql2mysql<replaceable>C-source-file</replaceable> …</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection id="msql2mysql-description"> - - <title>Description</title> - - <para> - Initially, the MySQL C API was developed to be very similar to - that for the mSQL database system. Because of this, mSQL - programs often can be converted relatively easily for use with - MySQL by changing the names of the C API functions. - </para> - - <para> - The <command>msql2mysql</command> utility performs the - conversion of mSQL C API function calls to their MySQL - equivalents. <command>msql2mysql</command> converts the input - file in place, so make a copy of the original before - converting it. For example, use <command>msql2mysql</command> - like this: - </para> + <title>fake title for msql2mysql manpage section wrapper</title> + + <refentry id="msql2mysql"> + + <indexterm type="concept"> + <primary><command>msql2mysql</command></primary> + </indexterm> + + <refmeta> + <refentrytitle>msql2mysql</refentrytitle> + <manvolnum>man</manvolnum> + <refmiscinfo>Convert MySQL Programs for Use with MySQL</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>msql2mysql</refname> + <refpurpose>convert MySQL programs for use with MySQL</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>msql2mysql<replaceable>C-source-file</replaceable> …</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection id="msql2mysql-description"> + + <title>Description</title> + + <para> + Initially, the MySQL C API was developed to be very similar + to that for the mSQL database system. Because of this, mSQL + programs often can be converted relatively easily for use + with MySQL by changing the names of the C API functions. + </para> + + <para> + The <command>msql2mysql</command> utility performs the + conversion of mSQL C API function calls to their MySQL + equivalents. <command>msql2mysql</command> converts the + input file in place, so make a copy of the original before + converting it. For example, use + <command>msql2mysql</command> like this: + </para> <programlisting> shell> <userinput>cp client-prog.c client-prog.c.orig</userinput> @@ -136,158 +140,170 @@ client-prog.c converted </programlisting> - <para> - Then examine <filename>client-prog.c</filename> and make any - post-conversion revisions that may be necessary. - </para> - - <para> - <command>msql2mysql</command> uses the - <command>replace</command> utility to make the function name - substitutions. See <xref linkend="replace-utility"/>. - </para> - - </refsection> - - </refentry> - - <refentry id="mysql-config"> - - <indexterm type="concept"> - <primary><command>mysql_config</command></primary> - </indexterm> - - <refmeta> - <refentrytitle>mysql_config</refentrytitle> - <manvolnum>man</manvolnum> - <refmiscinfo>Get Compile Options for Compiling Clients</refmiscinfo> - </refmeta> - - <refnamediv> - <refname>mysql_config</refname> - <refpurpose>get compile options for compiling clients</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>mysql_config <replaceable>options</replaceable></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection id="mysql-config-description"> - - <title>Description</title> - - <para> - <command>mysql_config</command> provides you with useful - information for compiling your MySQL client and connecting it - to MySQL. - </para> - - <para> - <command>mysql_config</command> supports the following - options: - </para> - - <itemizedlist> - - <listitem> - <para> - <option>--cflags</option> - </para> - - <para> - Compiler flags to find include files and critical compiler - flags and defines used when compiling the - <literal>libmysqlclient</literal> library. - </para> - </listitem> - - <listitem> - <para> - <option>--include</option> - </para> - - <para> - Compiler options to find MySQL include files. (Note that - normally you would use <option>--cflags</option> instead - of this option.) - </para> - </listitem> - - <listitem> - <para> - <option>--libmysqld-libs</option>, - <option>---embedded</option> - </para> - - <para> - Libraries and options required to link with the MySQL - embedded server. - </para> - </listitem> - - <listitem> - <para> - <option>--libs</option> - </para> - - <para> - Libraries and options required to link with the MySQL - client library. - </para> - </listitem> - - <listitem> - <para> - <option>--libs_r</option> - </para> - - <para> - Libraries and options required to link with the - thread-safe MySQL client library. - </para> - </listitem> - - <listitem> - <para> - <option>--port</option> - </para> - - <para> - The default TCP/IP port number, defined when configuring - MySQL. - </para> - </listitem> - - <listitem> - <para> - <option>--socket</option> - </para> - - <para> - The default Unix socket file, defined when configuring - MySQL. - </para> - </listitem> - - <listitem> - <para> - <option>--version</option> - </para> - - <para> - Version number and version for the MySQL distribution. - </para> - </listitem> - - </itemizedlist> - - <para> - If you invoke <command>mysql_config</command> with no options, - it displays a list of all options that it supports, and their - values: - </para> + <para> + Then examine <filename>client-prog.c</filename> and make any + post-conversion revisions that may be necessary. + </para> + + <para> + <command>msql2mysql</command> uses the + <command>replace</command> utility to make the function name + substitutions. See <xref linkend="replace-utility"/>. + </para> + + </refsection> + + </refentry> + + </section> + + <section id="fake-id-for-mysql-config-manpage-section-wrapper"> + + <title>fake title for mysql-config manpage section wrapper</title> + + <refentry id="mysql-config"> + + <indexterm type="concept"> + <primary><command>mysql_config</command></primary> + </indexterm> + + <refmeta> + <refentrytitle>mysql_config</refentrytitle> + <manvolnum>man</manvolnum> + <refmiscinfo>Get Compile Options for Compiling Clients</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>mysql_config</refname> + <refpurpose>get compile options for compiling clients</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>mysql_config <replaceable>options</replaceable></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsection id="mysql-config-description"> + + <title>Description</title> + + <para> + <command>mysql_config</command> provides you with useful + information for compiling your MySQL client and connecting + it to MySQL. + </para> + + </refsection> + + <refsection id="mysql-config-options"> + + <title>Options</title> + + <para> + <command>mysql_config</command> supports the following + options: + </para> + + <itemizedlist> + + <listitem> + <para> + <option>--cflags</option> + </para> + + <para> + Compiler flags to find include files and critical + compiler flags and defines used when compiling the + <literal>libmysqlclient</literal> library. + </para> + </listitem> + + <listitem> + <para> + <option>--include</option> + </para> + + <para> + Compiler options to find MySQL include files. (Note that + normally you would use <option>--cflags</option> instead + of this option.) + </para> + </listitem> + + <listitem> + <para> + <option>--libmysqld-libs</option>, + <option>---embedded</option> + </para> + + <para> + Libraries and options required to link with the MySQL + embedded server. + </para> + </listitem> + + <listitem> + <para> + <option>--libs</option> + </para> + + <para> + Libraries and options required to link with the MySQL + client library. + </para> + </listitem> + + <listitem> + <para> + <option>--libs_r</option> + </para> + + <para> + Libraries and options required to link with the + thread-safe MySQL client library. + </para> + </listitem> + + <listitem> + <para> + <option>--port</option> + </para> + + <para> + The default TCP/IP port number, defined when configuring + MySQL. + </para> + </listitem> + + <listitem> + <para> + <option>--socket</option> + </para> + + <para> + The default Unix socket file, defined when configuring + MySQL. + </para> + </listitem> + + <listitem> + <para> + <option>--version</option> + </para> + + <para> + Version number and version for the MySQL distribution. + </para> + </listitem> + + </itemizedlist> + + <para> + If you invoke <command>mysql_config</command> with no + options, it displays a list of all options that it supports, + and their values: + </para> <programlisting> shell> <userinput>mysql_config</userinput> @@ -306,28 +322,30 @@ -lcrypt -lnsl -lm -lpthread -lrt] </programlisting> - <para> - You can use <command>mysql_config</command> within a command - line to include the value that it displays for a particular - option. For example, to compile a MySQL client program, use - <command>mysql_config</command> as follows: - </para> + <para> + You can use <command>mysql_config</command> within a command + line to include the value that it displays for a particular + option. For example, to compile a MySQL client program, use + <command>mysql_config</command> as follows: + </para> <programlisting> shell> <userinput>CFG=/usr/local/mysql/bin/mysql_config</userinput> shell> <userinput>sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"</userinput> </programlisting> - <para> - When you use <command>mysql_config</command> this way, be sure - to invoke it within backtick ('<literal>`</literal>') - characters. That tells the shell to execute it and substitute - its output into the surrounding command. - </para> + <para> + When you use <command>mysql_config</command> this way, be + sure to invoke it within backtick ('<literal>`</literal>') + characters. That tells the shell to execute it and + substitute its output into the surrounding command. + </para> + + </refsection> - </refsection> + </refentry> - </refentry> + </section> </section>
| Thread | ||
|---|---|---|
| • bk commit - mysqldoc@docsrva tree (paul:1.3094) | paul | 21 Jul |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.714 sec. using MySQL 5.1.14-beta-log