Style guide

Revision as of 03:18, 8 July 2021 by WikiSysop (talk | contribs) (→‎Example sentences)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This page gives example code and advice for styling the wiki. If editors stick to these guidelines, the Chinese Grammar Wiki will have a consistent style and appearance, which is beneficial to users.

Chinese Grammar Wiki articles always have an introduction, and there is usually a grammar structure section, an example sentences section, and a further reading (sources) section. As long as you have two or more sections, there will be a "contents" box that automatically comes up.

Most articles follow this basic pattern, though some do not. Some basic grammar patterns in A1 and many of the comparison articles follow different patterns, though they are based on the above framework. Some articles may deviate from the basic pattern a bit more, like basic grammar articles, comparison articles, and more difficult/complex grammar articles.

Introductory Section

Every article begins with an introduction that summarizes the grammar point. In the introduction paragraph, when the grammar point is first introduced, the pinyin is provided in parentheses. Like this: 例子 (lìzi). This section can sometimes include ways that the pattern is commonly translated or explanations of an English phrase that is similar, such as in this example

For more information on this, check out what Wikipedia has to say in its explanation of the article lead section.

Grammar Structure

After the introduction, there is a section for the grammar structure (or pattern). They are set in a special code called "jiegou."

Wrap structures (or patterns) in a <div> with class jiegou. Be sure to leave a blank line after opening the <div> and before closing it with a </div>.

Subj. + 把 + Obj. + Verb

Note that the text inside the "structures" class is enlarged, but no spaces are collapsed, as they are with tables and lists with the class liju.

Usually the grammar structure section uses linguistic terms like "subject," "object," "verbs" etc., however we can be flexible sometimes. For example, grammar patterns like this one use terms like "cause" and "effect."

When writing an example, some parts of speech are too long and should be abbreviated:

  • Noun, Verb, Number, Predicate, Measure Word are all okay to spell out
  • Subject, Object, Adjective, Adverb all have well-known, unambiguous abbreviations which should be used: Subj., Obj., Adj., Adv. (include the period after the abbreviation!)
  • For the ellipses included in grammar patterns and the "Structure" box, use the Chinese floating 6-dot ellipsis: ⋯⋯ (this is actually 2 characters)

Make sure to put a space between between each element of the grammar pattern (between each word and symbol, including both plus signs (+) and slashes (/), for ease of reading).

EX: Subj. + 在 + Location + Verb Phrase

Besides the grammar pattern, this section may also include other information that would be helpful, such as context, situations the grammar pattern is used in, or potential variations or omissions. Basically, we are trying to show them where it can be used before we give them examples of those situations.

Example sentences

Example sentences are a vital part of the Chinese Grammar Wiki. To effectively use them, make sure you do the following.

Lists

Example sentences usually come together as a group of lists.

Wrap the entire list (or lists, if you want separate sections) in a <div> with class liju. Separate words with spaces. Be sure to leave a blank line after opening the <div> and before closing it with a </div>.

A single list of example sentences:

  • 你 有 没有 记住 我的 名字?
  • 他 是 不 是 我们 昨天 看到 的 人?

A group of lists with example sentences:

  • 谁 能 把 ‘ 打喷嚏 ’ 的 ‘ 嚏 ’ 写 对
  • 我们 刚才 听到 的 音乐 是 哪个 乐队 的 ?
  • 你 有 没有 记住 我的 名字?
  • 他 是 不 是 我们 昨天 看到 的 人?

A list of example sentences, some of which are correct, and some of which are incorrect. Note: for this type of list, an HTML list must be used instead of the normal wiki shorthand list so that the individual list item elements (<li>) can be styled with the proper CSS classes.

  • 你 把 作业 了 吗 ?
  • 作业 做 完 了 吗 ? This is a comment to add some explanation.
  • 你 把 作业 做 做 完 了 吗 ? This is a comment to add some explanation.
  • 作业 做 完 了 吗 ?
  • 作业 做 做 完 了 吗 ?
  • 作业 做 完 了 吗 ?

Note the "(This is a comment to add some explanation.)" in the above examples. This is a bit of text that can be used to set up a context or add other details that puts the example sentence into a proper perspective.

If you ever need to add spaces back into text inside a list which is wrapped in a <div> with class liju, there are two ways to do it:

  1. For small chunks of texts, wrap the target text in a <span> tag with class spaced. Note that class expl has its own style, which includes normal spacing between words (see the code above).
  2. For entire lines in cases where you're using an HTML list, simply add the class spaced to the appropriate <li> elements. You can add multiple classes to one element, as long as you put a space in between the names (example: <li class="x spaced">).

Remember: if most of the list is in Chinese (as should be the case with examples sentences), wrap the whole list in a <div> with class liju to get the proper style, then target the English content with a <span> tag with class spaced. If most of the table is in English, don't wrap the whole table in a <div> with class liju; instead just target the Chinese content with a <span> tag with class liju. (Note that in this case, the style of the list will look totally different.)

Translations

For articles in A1, A2, B1, and B2, add translations to each example sentence. Translations are added by adding a bit of extra code after each example sentence. See the example below:

<div class="liju">
(*) 他 <em></em> 美国 人。<span class="trans">He is an American.</span>
</div>

turns into

  • 美国 人。He is an American.

Individual Sentences

Sometimes you may need to just use a single sentence as an example (specifically, within other texts). Style individual example sentences as described below.

The wiki uses mainly <div> tags to enclose groups of sample sentences in tables or lists, but occasionally also makes use of <span> tags for snippets of Chinese within other text. Whether it's a <div> tag or a <span> tag, however, both should take the CSS class liju to apply the appropriate styles.

Example of a <span> tag (normally used within a block of text):

<span class="liju">Chinese would go here.</span>

Example of a <div> tag (normally used to enclose an entire table or list):

<div class="liju">
A table or list full of Chinese would go here.
</div>

Further usage of these is covered below. In either case, separate words in the sentence with spaces to allow browser plugins and other software to parse them more accurately. The CSS class will not show these spaces, so the sentence will still display correctly.

Tables

Sometimes instead of writing up a list of example sentences, you may want to draw up a table. To do so, do follow these steps:

Wrap the whole table in a <div> with class liju, and add the class wikitable to the table. Specify width in ems, allotting roughly 10em per column. Separate Chinese words with spaces (but not the Chinese character space!). Leave a column for punctuation at the end if your table consists of columns that form sentences.

Be sure to leave a blank line after opening the <div> and before closing it with a </div>.

Result complements with aspect particles
Subject RC compound verb Aspect particle Object
看到
看见 那 个 有名的 人
听见 这 个 声音

If you ever need to add spaces back into text inside a table which is wrapped in a <div> with class liju, there are two ways to do it:

  1. For small chunks of texts, or possibly whole cells if you're using the simple wiki table, wrap the target text in a <span> tag with class spaced.
  2. For entire rows or cells in cases where you're using a complex HTML table, simply add the class spaced to the apropriate <tr> or <td> elements.

Remember: if most of the table is in Chinese, go ahead and wrap the whole table in a <div> with class liju, then target the English content with class spaced. If most of the table is in English, don't wrap the whole table in a <div> with class liju; instead just target the Chinese content with a <span> tag with class liju.

Rules for spacing words

Make sure that all example sentences have spaces between words.

Separating words with spaces in the example sentences helps software to parse them more accurately. The CSS style ensures that the user sees a nicely displayed sentence that is not broken up by spaces. (Just make sure that you add the spaces while using an English input, and not while using Chinese input. The Chinese input will add "Chinese spaces" which will not be properly handled by the CSS.)

  • Separate all parts of speech (nouns, verbs, adjectives etc.).
    我喜欢红色的自行车。⇒ 我 喜欢 红色 的 自行车。
  • Separate all particles,
    吃饭了吗? ⇒ 吃饭 了 吗?
  • Separate numbers and measure words,
    一个苹果。⇒ 一 个 苹果。

References/Sources and Further Reading

It's important that the Chinese Grammar Wiki is fully referenced throughout. That make this section pretty important!

Make smaller subsection for books and websites. Make sure that we use the Amazon affiliate links when referencing books. For more information on citations, please refer to this section of the Editor Instructions.

Grammar Box

You may notice that in the corner of each article there is a box with a few items. This is the Grammar Box, and it is used to help us organize the article by placing it in its category, adding key words and characters to help search, and adding other bits of information that would be helpful. It also facilitates connecting articles that share similar grammar qualities.

The grammar box code itself is in the beginning of the top of the edit page (in special parentheses) and the rest is located at the bottom of the edit page. The section at the bottom can hold links to similar articles, word/character tags for search, English word tags, or other helpful bits of information. The bottom also includes code to help organize the article into the Grammar Point index (category, sub-category, grammar structure, example sentence, and database code.)

Special note on "Similar to" tags

When linking articles with the "similar to" tag, make sure that both articles are linked to each other this way, or else the "similar to" link will not come up for either of them!

Styling elements within the text

  • Put double quotation marks (") around whole sentences in English or Chinese.
  • Leave individual Chinese words or characters as they are. They naturally look different to the surrounding text.
  • Put technical terms in italics (two single quotes on each side).
  • Put key words (i.e. terms that are central to the content of the article, and are likely to be repeated) in bold italics (three single quotes on each side).

Custom styling (Advanced)

Sometimes you need to apply styling to individual elements that MediaWiki markup doesn't allow. In particular, <li> and <tr>. If you need to style these individually, you have to insert an HTML list or table, still wrapped in the appropriate div described above, and then style the elements manually.

There's also custom CSS which can be edited on the wiki. (Do not edit this if you don't know what you're doing!)

Practice Makes Perfect 熟能生巧

If any of the above instructions seem confusing, don't worry! The best way to learn how articles are set up is take a look at the code in the article by clicking on "edit“. Some articles that are good examples to look at are:


Looking at the edit page of this article is another good way to see how the code is set up.