1 files changed, 279 insertions, 0 deletions
diff --git a/Docs/ManualStyleGuidelines.wiki b/Docs/ManualStyleGuidelines.wiki
new file mode 100644
index 00000000000..3329370411c
--- /dev/null
+++ b/Docs/ManualStyleGuidelines.wiki
@@ -0,0 +1,279 @@
+OriginalAuthor: PaulDuBois
+
+!!! ManualStyleGuidelines
+
+''Version 1.0''
+
+!! Revision History
+
+* 2002-05-17 ArjenLentz - Version 1.0, Posted to Wiki
+
+!! MySQL Manual Style Guidelines
+
+Paul DuBois <paul@snake.net>
+
+The following list of guidelines contains items that I've been jotting
+down over time as style questions have come up in relation to the
+MySQL manual. I wouldn't say they're exactly "official", but they
+do reflect current working practice. Arjen asked me to post this
+on the list some time ago so that it can be discussed with a view
+to adding it (or something like it) to the source tree. So here it is!
+
+Present in the mysql-4.0 source tree: Docs/ManualStyleGuidelines.wiki
+
+
+The manual is written in UK English, not American English. This means:
+
+ colour, not color
+ behaviour, not behavior
+ authorise, not authorize
+ optimise, not optimize
+ etc.
+
+Write MySQL, not @strong{MySQL} (the manual used to use the latter, but no
+more).
+
+Write Unix, not UNIX.
+
+Use uppercase for SQL keywords, functions names, etc., when writing
+SQL statement examples.
+
+To write a list of items, add commas after all items preceding the last one:
+ Correct: Features, products, and services
+ Incorrect: Features, products and services
+
+How to pluralize keywords that are enclosed in @code:
+ Correct: @code{SELECT}s
+ Incorrect: @code{SELECTs} or @code{SELECT}'s or @code{SELECT}:s
+
+Use "its" and "it's" correctly. These words are exceptions to
+the normal use of "'s" to indicate possession:
+
+it's = it is (e.g., "one of the strengths of MySQL is that it's fast")
+its = possession (e.g., "MySQL is fast, which is one of its strengths")
+
+"a lot" is two words. "alot" is rebarbative.
+
+Write lowercase, not lower case
+
+Write uppercase, not upper case
+
+Write lettercase, not letter case
+
+Write "web site" (two words), not "website", and "web page" rather
+than "webpage".
+
+The word "data" is problematic. It's commonly used both in plural and in
+singular form. The manual uses it as plural, which means you use "data are"
+rather than "data is". It's unfortunate that no matter which form we use, it
+will look incorrect to some people. But we can at least be internally
+consistent.
+(Paul: I think that the O'Reilly proofread might have caught one or two of these; could you please pick up on these but don't change them back straight away until the book is finished? Thanks; Arjen).
+
+Write "press Enter", not "hit Return" or "hit Enter".
+
+When reproducing program output, reproduce it exactly, even if it contains
+typos. Don't "fix" it. (If the output is produced by a MySQL program, then
+fix the source for the program to write the output correctly without the
+typo, then update the manual to match.)
+
+Use "okay" rather than "ok" or "Ok" or "OK" in sentences. Exceptions:
+* When describing instructions for a GUI with buttons that say "OK", then use "OK". That is, use the label that the GUI uses.
+* When showing the output from a program, show the output exactly; don't change "ok" to "okay", etc.
+
+Write "Open Source" (inside @code{}), not "open source".
+
+To put something in quotes, do it ``like this,'' not "like this"
+or 'like this.' In the latter two cases, the quotes will come
+out looking rotten in printed formats.
+Exception: quotes in code examples should be written using whatever
+contention the program language requires.
+
+Table types should be written using @code{}; write @code{MyISAM}, not
+MyISAM.
+
+When possible, use table names that are singular, not plural.
+For example, use "item" rather than "items", or "person" rather than
+"people". Sometimes you can add "_list" (as in "item_list") to make it
+more clear that the name refers to a collection of items.
+
+ Some commonly occurring misspelling:
+
+ Correct         Incorrect
+ ---------------------------
+ publicly        publically
+ statically      staticly
+ dynamically     dynamicly
+ automatically   automaticly
+
+There is no hyphen after "ly" words. Write statically linked, not
+statically-linked.
+
+To refer to ASCII codes, use ASCII n, not ASCII(n), unless you're
+referring to the ASCII() function, which case you use @code{ASCII()}.
+
+ ASCII 13             indicates ASCII character code 13
+ @code{ASCII(13)}     indicates a function call
+
+backup is a noun or adjective (as in "a backup file"), back up is a verb
+(as in "to back up a database")
+rollback is a noun or adjective (as in "a rollback operation"), roll back
+is a verb (as in "roll back a transaction")
+
+core dump is a noun or a verb (as in "a core dump file" or "a program
+core dumps when it fails"). In the latter case, however, it's better say
+say "a program dumps core when it fails").
+
+Write character set names in @code{}, e.g., @code{latin1}, @code{win1251}.
+
+To prevent problems with various output formats, there should be no link
+titles in a @uref{}. So @uref{url} is allowed, @uref{url,blabla} is not.
+ Use this format:
+		@uref{url} (WWW)
+ Not this format:
+		@uref{url, WWW}
+ Similarly for FTP sites.
+
+URLs ending in a domain name or directory should have a "/" at the end.
+(For example, the URLs for all mirror sites should be written that way.)
+
+Privilege names are written using @strong and lowercase, as in "the
+@strong{process} privilege". Column names in the grant tables are
+written using @code and the lettercase found in the table definition,
+as in "the @code{Process_priv} column".
+
+Write "e-mail", not "email". Exceptions are the @email{} construct, and
+the Email attribute name in X509 certificate strings.
+
+Write thread-safe, transaction-safe, replication-safe, not thread safe,
+transaction safe, replication safe.
+
+Write wildcard, not wild card or wild-card.
+
+Use "indexes", not "indices": Adding indexes to a table will improve the
+performance of SELECT statements.
+Exception: when returning to array elements, use "indices": The elements
+of the array may be accessed using numeric indices, where the index
+values ranges from 0 to n.
+
+Write "heavy-load production systems" (used as an adjective),
+but "...used under heavy load" (used on its own).
+
+Write PostScript, not Postscript.
+
+When writing a list like "A, B, and C", include a comma before the last and.
+
+Write case-sensitive and case-insensitive (hyphenated).
+
+Write runtime, not run time.
+
+Write backward-compatible, not backward compatible or backwards compatible.
+
+Write application-related, not application related.
+
+Write filesystem, not file system.
+
+Write file-size, not file size.
+
+Write datafile, not data file.
+
+Write power-start, not power start.
+
+Write percent, not per cent.
+
+Write "toward", "and onward", not "towards", "onwards".
+
+Write third-party, not third party.
+
+Write turnkey, not turn-key.
+
+Write "the Net" (capitalised) if referring to the Internet in that way.
+
+Write long-awaited, not long awaited.
+
+Write natural-language, not natural language.
+
+Write low-volume <something> (when used as an adjective).
+
+Write platform-dependent, not platform dependent.
+
+Write something like "mentioned previously" instead of "above", and "later in this section" instead of "below" when making such relative references in your text.
+
+Write "... shown here", not "... shown below".
+
+Write "following some", not "something [shown] below".
+
+Write high-priority <something> (when used as an adjective), not high priority.
+
+Write "whether", not "whether or not".
+
+Write hand-held, not hand held.
+
+Write rewriting, not re-writing.
+
+Write re-issue(ing), not reissue(ing).
+
+Write command-line, not command line.
+
+Write server-side, not server side.
+
+Write "<blabla> only", not "only <blabla>".
+
+Write floating-point, not floating point.
+
+Write heavy-duty, not heavy duty.
+
+Write online, not on-line.
+
+Write user-defined, not user defined.
+
+Write multi-user, not multi user.
+
+Write multi-thread(ed), not multithread(ed).
+
+Write memory-based, not memory based.
+
+Write long-time <something> (when used as an adjective), not long time.
+
+Write 32-bit, not 32 bit or 32 bits. (Same goes for 64-bit, of course! ;-)
+
+Write "different from [what] ...", not "different than ...".
+
+Write "@-e.g., " instead of " e.g. " in the middle of a sentence. (The @- will be turned into a dash, or &mdash; for DocBook output.)
+Following "e.g." by a comma, not a space or a colon.
+
+Write "@-" if you need to put a dash in a text, no surrounding spaces.
+
+Similar story for "for example" as for "e.g."
+
+Write CPU, not cpu (it's an acronym, not a word! ;-)
+
+Write "... uses ... CPU time", not "... uses ... CPU" (unless you're referring the processor itself.)
+
+If a (comment) is at the end of a sentence, start the comment with lowercase and put the . after the closing ), such as (like this).
+If a comment is separate, start with uppercase and put the . inside the closing ). (Like this.)
+
+Write "something cannot do something", not "something can not something".
+
+Write "otherwise, ..." (with the comma) at the start of a sentence.
+
+Paul, could you please check "honoring"... is this proper British English? Thanks, Arjen.
+
+Write "byte-swapping", not "byte swapping".
+
+Write "Note:", not "NOTE:". And then continue with lowercase, it is not the start of a new sentence.
+
+Write "single-CPU" and "multiple-CPU", not "single CPU" and "multiple CPU".
+
+Paul, I think we should also decide whether to write Version or version, and in what situation. I am not changing much now because there's lots of funny instances and I don't want to risk getting it wrong. Thanks, Arjen.
+
+After a semicolon, don't use uppercase. It is NOT the start of a new sentence!
+
+It's "unstable", not "instable". ;-)
+
+It's "full-text", not "fulltext".
+
+Logical NOT/OR/AND are operators, not functions, so they take operands, not arguments.
+
+It's NetWare, not Netware (as per Novell's trademark guidelines).
+