Moved to mysqldoc tree.

BitKeeper/deleted/.del-ManualStyleGuidelines.wiki~4e97d272fd42b393:
  Delete: Docs/ManualStyleGuidelines.wiki

Docs/ManualStyleGuidelines.wiki

-OriginalAuthor: Paul DuBois
-
-!!! ManualStyleGuidelines
-
-''Version 1.1''
-
-!! Revision History
-
-* 2002-05-17 ArjenLentz - Version 1.0, Posted to Wiki
-* 2002-06-03 ArjenLentz - Version 1.1, updates.
-
-!! 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).
-
-It's deprecated, not depricated.
-