"Wikified" Manual_style_guidelines.txt
This commit is contained in:
unknown
parent
2f91c6c3c9
commit
cf8433e4fe
@ -1,4 +1,14 @@
|
||||
MySQL Manual style guidelines
|
||||
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>
|
||||
|
||||
@ -9,15 +19,16 @@ 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
|
||||
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.
|
||||
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).
|
||||
@ -28,12 +39,12 @@ 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
|
||||
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
|
||||
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:
|
||||
@ -44,7 +55,9 @@ 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
|
||||
@ -64,12 +77,9 @@ 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.
|
||||
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".
|
||||
|
||||
@ -87,14 +97,14 @@ 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:
|
||||
Some commonly occurring misspelling:
|
||||
|
||||
Correct Incorrect
|
||||
---------------------------
|
||||
publicly publically
|
||||
statically staticly
|
||||
dynamically dynamicly
|
||||
automatically automaticly
|
||||
Correct Incorrect
|
||||
---------------------------
|
||||
publicly publically
|
||||
statically staticly
|
||||
dynamically dynamicly
|
||||
automatically automaticly
|
||||
|
||||
There is no hyphen after "ly" words. Write statically linked, not
|
||||
statically-linked.
|
||||
@ -102,8 +112,8 @@ 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
|
||||
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")
|
||||
@ -118,11 +128,11 @@ 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:
|
||||
Use this format:
|
||||
@uref{url} (WWW)
|
||||
Not this format:
|
||||
Not this format:
|
||||
@uref{url, WWW}
|
||||
Similarly for FTP sites.
|
||||
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.)
|
||||
@ -188,7 +198,9 @@ 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.
|
||||
Loading…
x
Reference in New Issue
Block a user