diff options
| -rw-r--r-- | Docs/ManualStyleGuidelines.wiki | 282 |
1 files changed, 0 insertions, 282 deletions
diff --git a/Docs/ManualStyleGuidelines.wiki b/Docs/ManualStyleGuidelines.wiki deleted file mode 100644 index 9d2a869ba1a..00000000000 --- a/Docs/ManualStyleGuidelines.wiki +++ /dev/null @@ -1,282 +0,0 @@ -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 — 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. - |