| List: | Commits | « Previous MessageNext Message » | |
| From: | plavin | Date: | August 30 2007 10:57pm |
| Subject: | svn commit - mysqldoc@docsrva: r7615 - trunk/userguide | ||
| View as plain text | |||
Author: plavin Date: 2007-08-30 22:57:55 +0200 (Thu, 30 Aug 2007) New Revision: 7615 Log: Write 'This is Not the Manual' and 'Target Audience' sections, reorganize and add dynamic docs appendices Added: trunk/userguide/userguide.ent Modified: trunk/userguide/Makefile.depends trunk/userguide/all-entities.ent trunk/userguide/introduction.xml trunk/userguide/mysql-client-programs.xml trunk/userguide/userguide.xml Modified: trunk/userguide/Makefile.depends =================================================================== --- trunk/userguide/Makefile.depends 2007-08-30 17:43:15 UTC (rev 7614) +++ trunk/userguide/Makefile.depends 2007-08-30 20:57:55 UTC (rev 7615) Changed blocks: 8, Lines Added: 17, Lines Deleted: 8; 2844 bytes @@ -1,7 +1,8 @@ basic_administration_INCLUDES = \ ../common/fixedchars.ent \ ../refman-common/urls.ent \ - all-entities.ent + all-entities.ent \ + userguide.ent basic_administration_IMAGES = basic_administration_SOURCES = basic-administration.xml $(basic_administration_INCLUDES) basic_administration_IDMAPS = @@ -17,7 +18,8 @@ disaster_prevention_INCLUDES = \ ../common/fixedchars.ent \ ../refman-common/urls.ent \ - all-entities.ent + all-entities.ent \ + userguide.ent disaster_prevention_IMAGES = disaster_prevention_SOURCES = disaster-prevention.xml $(disaster_prevention_INCLUDES) disaster_prevention_IDMAPS = @@ -33,7 +35,8 @@ excel_mysql_INCLUDES = \ ../common/fixedchars.ent \ ../refman-common/urls.ent \ - all-entities.ent + all-entities.ent \ + userguide.ent excel_mysql_IMAGES = excel_mysql_SOURCES = excel-mysql.xml $(excel_mysql_INCLUDES) excel_mysql_IDMAPS = @@ -80,7 +83,8 @@ introduction_INCLUDES = \ ../common/fixedchars.ent \ ../refman-common/urls.ent \ - all-entities.ent + all-entities.ent \ + userguide.ent introduction_IMAGES = introduction_SOURCES = introduction.xml $(introduction_INCLUDES) introduction_IDMAPS = @@ -111,7 +115,8 @@ ../refman-common/urls.ent \ all-entities.ent \ images/logfiles-slow-query-log-administrator-settings.png \ - images/logfiles-slow-query-log-administrator-view.png + images/logfiles-slow-query-log-administrator-view.png \ + userguide.ent log_files_IMAGES = \ images/logfiles-slow-query-log-administrator-settings.png \ images/logfiles-slow-query-log-administrator-view.png @@ -142,10 +147,12 @@ mysql_client_programs_INCLUDES = \ ../common/fixedchars.ent \ ../refman-common/urls.ent \ - all-entities.ent + all-entities.ent \ + userguide.ent mysql_client_programs_IMAGES = mysql_client_programs_SOURCES = mysql-client-programs.xml $(mysql_client_programs_INCLUDES) -mysql_client_programs_IDMAPS = +mysql_client_programs_IDMAPS = \ + metadata/userguide.idmap mysql-client-programs.validpure: $(mysql_client_programs_SOURCES) mysql-client-programs.titles: $(mysql_client_programs_SOURCES) mysql-client-programs.useless: $(mysql_client_programs_SOURCES) @@ -158,7 +165,8 @@ mysql_server_programs_INCLUDES = \ ../common/fixedchars.ent \ ../refman-common/urls.ent \ - all-entities.ent + all-entities.ent \ + userguide.ent mysql_server_programs_IMAGES = mysql_server_programs_SOURCES = mysql-server-programs.xml $(mysql_server_programs_INCLUDES) mysql_server_programs_IDMAPS = @@ -245,6 +253,7 @@ querying.xml \ storage-engines.xml \ stored-procedures.xml \ + userguide.ent \ views.xml userguide_IMAGES = \ images/indexing-displaying-administrator.png \ Modified: trunk/userguide/all-entities.ent =================================================================== --- trunk/userguide/all-entities.ent 2007-08-30 17:43:15 UTC (rev 7614) +++ trunk/userguide/all-entities.ent 2007-08-30 20:57:55 UTC (rev 7615) Changed blocks: 1, Lines Added: 2, Lines Deleted: 0; 522 bytes @@ -6,5 +6,7 @@ --> <!ENTITY % fixedchars.entities SYSTEM "../common/fixedchars.ent"> <!ENTITY % urls.entities SYSTEM "../refman-common/urls.ent"> +<!ENTITY % userguide.entities SYSTEM "userguide.ent"> %fixedchars.entities; %urls.entities; +%userguide.entities; Modified: trunk/userguide/introduction.xml =================================================================== --- trunk/userguide/introduction.xml 2007-08-30 17:43:15 UTC (rev 7614) +++ trunk/userguide/introduction.xml 2007-08-30 20:57:55 UTC (rev 7615) Changed blocks: 3, Lines Added: 173, Lines Deleted: 85; 9252 bytes @@ -19,9 +19,7 @@ [SH] The following was sent in by community member Vangelis Katsikaros on the mysqldoc list. Even if we might not want to use his text we should have a short introduction to the client/server - principle. - - intoduction to the client/server architecture MySQL + principle. intoduction to the client/server architecture MySQL follows the client/server architecture and as a consequence, MySQL consists of two parts: the server and the client(s). They communicate over a well-defined interface but let's not describe @@ -58,41 +56,56 @@ programming language client the report is stored in a variable for further manipulation with the programming language. </remark> - + <section> - - <title>MySQL On the Web</title> - + + <title>Client and Server</title> + <para></para> - + </section> - + + </section> + + <section> + + <title>MySQL Applications</title> + <section> - + + <title>MySQL On the Web</title> + + <para> + phpMyAdmin - also refer to appendix + </para> + + </section> + + <section> + <title>MySQL Enterprise Applications</title> - + <para></para> - + </section> - + <section> - + <title>MySQL Desktop Applications</title> - + <para></para> - + </section> - + <section> - + <title>Main Features</title> - + <para></para> - + </section> - + </section> - <!-- END WHAT IS MYSQL --> @@ -105,92 +118,167 @@ </section> <!-- END WHY USE MYSQL --> + <section> - - <title>Example Applications</title> - - <para></para> - - </section> - - <section> - - <title>About This Book</title> - - - <section> - - <title>This is Not the Manual</title> - + + <title>About This Book</title> + + <section id="userguide-not-the-manual"> + + <title>This is <emphasis>Not</emphasis> the Manual</title> + <para> - On the MySQL documentation web page (<ulink url="&base-url-docs;"/>) - you'll find the various versions of the MySQL manual. - At the time of writing there are three different - versions of the manual each one running to about 2,000 pages in PDF - format. These manuals are meant to be the definitive reference - books for each specific manual. You should be able to find the answer for - any question you have about any version of MySQL. + On the MySQL documentation web page + (<ulink url="&base-url-docs;"/>) you'll find the various + versions of the MySQL manual. At the time of writing there are + three different versions, each one running to about 2,000 pages + in PDF format. These manuals are meant to be the definitive + reference books for each specific server version; they should + provide the answer to any question you have about any version of + MySQL. </para> - + <para> - This is - can be difficult to see the forest for the trees. + The manuals are an excellent resource but they can be very + intimidating for users who are new to MySQL, especially for + those who have no previous experience with a Relational Database + Management System (RDMS). Even for users familiar with other + RDMSs, the wealth of information contained in the manuals makes + it easy to lose sight of the forest for the trees. For this + reason the focus of the &userguide; is strictly circumscribed; + as far as possible, this book aims to be OS-neutral and MySQL + version specific. </para> - + <para> - where necessary point to the manual + This book deals with MySQL version 5.0 [5.1 if it is GA] only. + Concentrating on one server version makes for greater simplicity + and using version 5.0 means we can take advantage of the + improved feature set of the newest production version. </para> - + <para> - specific notes about features or usage when introduced etc won't - be here + MySQL's popularity is partly due to the fact that it is + supported on numerous operating systems. However, this also adds + a level of complexity to the manual — exactly the kind of + thing we aim to reduce. For this reason, as far as is possible, + this book ignores any OS-specific features of MySQL. For + instance, <literal>mysqlhotcopy</literal> is a very useful + utility but it is not supported under Windows or Mac OS X so + will not be discussed here. Concentrating on features common to + all OSs removes one of the distractions inherent in reading the + MySQL manual. </para> - + <para> - for the sake of simplicity only deals with version 5.0 + In no way is this book meant to be a definitive treatment of + MySQL but therein lies its strength. It should speed + up the process of getting you up and running with MySQL. For + those questions it doesn't answer, see the manual. </para> - + + <para> + MySQL is a flexible RDMS useful in many circumstances. At one + end of the spectrum it is suitable for enterprise applications + and at the other it can also be used for simple desktop + applications. Regardless of how you plan to use MySQL, the + &userguide; should prove to be a good + introduction to MySQL. + </para> + </section> - - <section> - + + <section id="userguide-target-audience"> + <title>Target Audience</title> - + <para> - users new to databases in general and users new to - MySQL + When describing the nature of the &userguide; in + <xref linkend="userguide-not-the-manual"/> we hinted at the + kinds of readers that this book should appeal to; users new to + databases in general and users new to MySQL in particular. </para> - + <para> - regardless of operating system many users are unfamiilar with - working from the command line - will make no assumptions in this respect + It is also probably a fair assumption that many of our readers, + regardless of the OS they are using, + will be more familiar working within a GUI environment than from + the command line. There's no getting around the fact that being + capable from the command line is an advantage when using MySQL. + The primary tool for interacting with a MySQL server, + <literal>mysql</literal>, is command-line based. </para> - + + <para> + Mastering MySQL from the command line will allow you to operate + in environments where there is no GUI, the majority of web + servers for example. Besides some command-line tools are + unquestionably superior. There's no quicker way of creating a + database than issuing the command, <userinput>mysqladmin create + <replaceable>db_name</replaceable></userinput>. + <remark>[PL] bear with us ...</remark> + </para> + + <para> + However, whenever possible we'll make use of MySQL Administrator + and MySQL Query Browser, open source MySQL GUI Tools. Creating + database objects is made especially easy using the Table Editor, + a feature of the Query Browser also common to other GUI Tools. + By pointing and clicking you can quickly build a table without + knowing anything about data definition language (DDL). Not only + will the table editor help you work more quickly, but it's a + good way to learn MySQL's implementation of SQL. Any alterations + made to a table using the graphical interface are shown as SQL + statements, making it easy to learn the appropriate SQL command. + </para> + </section> - - </section> - - <section> - - <title>Version of MySQL Used</title> - - <section> - - <title>Operating Systems Supported</title> - + + <section id="userguide-external-submissions"> + + <title>External Submissions</title> + <para></para> - + </section> - + + </section> + + <section> + + <title>Operating Systems Supported</title> + + <para> + <remark> + [PL]This section should probably move + </remark> + </para> + <section> - + <title>Variations Between Operating Systems</title> - - <para></para> - + + <para> + In some circumstances, discussions of the differences between + operating systems is inevitable; when talking about file + permissions for example. ... + </para> + + <para> + localhost/127.0.0.1 + </para> + + <para> + autocompletion? + </para> + + <para> + GUI Tools implementation different by OS + </para> + </section> - </section> + </section> + </chapter> <!-- END INTRODUCTION CHAPTER --> Modified: trunk/userguide/mysql-client-programs.xml =================================================================== --- trunk/userguide/mysql-client-programs.xml 2007-08-30 17:43:15 UTC (rev 7614) +++ trunk/userguide/mysql-client-programs.xml 2007-08-30 20:57:55 UTC (rev 7615) Changed blocks: 5, Lines Added: 7, Lines Deleted: 5; 2106 bytes @@ -207,6 +207,7 @@ <literal>root</literal>, as the user name. There is no password for this default user. For information on creating additional users see <xref>. + <remark>Difference between 127.0.0.1 and localhost on Unix?</remark> </para> </note> @@ -467,7 +468,7 @@ <para> As noted earlier, only selected <command>mysql</command> options are discussed here. For a complete list see - <ulink url="&base-url-refman;5.0/en/mysql.html"/> or, at the + <xref linkend="userguide-options-tables-utilities"/> or, at the command line simply type <userinput>mysql -?</userinput>. </para> @@ -605,7 +606,7 @@ when issued without an argument, outputs a list of all the commands but no options. For a complete list of all the available commands see - <ulink url="&base-url-refman;5.0/en/mysql-commands.html"/>, or + <xref linkend="userguide-options-tables-utilities"/>, or from the <command>mysql</command> shell, issue the command <userinput>?</userinput>. </para> @@ -732,7 +733,7 @@ for complete coverage of this utility see <ulink url="&base-url-refman;5.0/en/mysqladmin.html"/>. The more advanced commands and options of <command>mysqladmin</command> - will be discussed in more detail in <xref>. + will be discussed in more detail in <xref>. </para> <!-- start options --> @@ -821,8 +822,9 @@ </para> <para> - For a complete list of all the available options and commands - see <ulink url="&base-url-refman;5.0/en/mysqladmin.html"/>. + Find a complete + list of all the options and commands in <xref + linkend="userguide-options-tables-utilities"/>. </para> </section> Added: trunk/userguide/userguide.ent =================================================================== --- trunk/userguide/userguide.ent (rev 0) +++ trunk/userguide/userguide.ent 2007-08-30 20:57:55 UTC (rev 7615) Changed blocks: 1, Lines Added: 5, Lines Deleted: 0; 358 bytes @@ -0,0 +1,5 @@ +<?xml version='1.0' encoding='utf-8'?> +<!ENTITY userguide "MySQL User Guide"> +<!ENTITY version "1.0"> + + Modified: trunk/userguide/userguide.xml =================================================================== --- trunk/userguide/userguide.xml 2007-08-30 17:43:15 UTC (rev 7614) +++ trunk/userguide/userguide.xml 2007-08-30 20:57:55 UTC (rev 7615) Changed blocks: 2, Lines Added: 32, Lines Deleted: 1; 1185 bytes @@ -606,7 +606,7 @@ <part label="VI"> - <title>Appendices</title> + <title>Appendixes</title> <appendix> @@ -657,6 +657,37 @@ <para></para> </appendix> + + <appendix id="userguide-date-format-specifiers"> + + <title>Date Format Specifiers Table</title> + + <para> + <remark>Use dynamic docs to generate</remark> + </para> + + </appendix> + + <appendix id="userguide-functions-operators"> + + <title>Functions and Operators Table</title> + + <para> + <remark>Use dynamic docs to generate</remark> + </para> + + </appendix> + + <appendix id="userguide-options-tables-utilities"> + + <title>Options Tables for MySQL Utilities</title> + + <para> + <remark>Use dynamic docs to generate, separate table for + each utility referenced in this book</remark> + </para> + + </appendix> <appendix>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r7615 - trunk/userguide | plavin | 30 Aug |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.488 sec. using MySQL 5.1.14-beta-log