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! MySQL Reference Manual Style Guidelines 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. 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", 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.