Punctuation

First and foremost, use English punctuation in English writing and Chinese — full-width, double-byte — punctuation in Chinese writing. Please do not use English punctuation marks in Chinese text and vice versa.

Differences in Chinese and English Punctuation

Punctuation Mark

English

Chinese

Notes

Full stop (Period)

.

。

Comma

,

，

Enumeration Comma

N/A

、

Chinese punctuation mark dividing listed items within a sentence. In English, its role is fulfilled by a regular comma.

Colon

:

：

Semicolon

;

；

Question Mark

?

？

Exclamation Mark

!

！

Quotation Marks

“”

“”

The English and Chinese quotation marks might appear the same in this document.

Quotation Marks for titles

N/A

《》

Chinese punctuation mark used to signify book titles, song titles, movie titles, etc. For more details, see Section Cross-references in Chinese Text.

Parentheses

( )

（）

Tilde

~

～

English tildes are used only for ranges that include negative numbers.

However, for texts where both English and Chinese writing is used side-by-side, please follow specific rules provided in this chapter.

Spaces

General Rules

Use English spaces in the following cases:

  • Between a number and the following unit of measure

  • Between an English punctuation mark and the following English word

Example

  • Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform.

When specifying a version number of a document or software application (v+number), do not add a space between the lowercase “v” and the number.

Example

English Text

Translated Text

Download the latest document (v1.0).

下载最新版本的文档 (v1.0)。

Do not use English spaces around hyphens, dashes, and slashes.

Example

Correct

Incorrect

32-bit core

32 - bit core

AT+WPS—设置 WPS 功能

AT+WPS — 设置 WPS 功能

On/Off switch

On / Off switch

读/写

读 / 写

Add English spaces before and after the ampersand for a combination of two independent names, but do not add spaces around ampersand in abbreviations containing the word “and”. When referring to a company with an “&” in its name, such as Marks & Spencer and AT&T, please check its official corporate website or other authoritative source to confirm whether to add spaces in-between.

Example

Correct

Incorrect

Notes

Beijing & Shanghai

Beijing&Shanghai

Note that in official technical documentation, it is strongly recommended to avoid using “&” to indicate the meaning of “and”. Such expression is only acceptable in informal texts or when there is only limited space.

R&D

R & D

Note

Please pay special attention to spaces in code or commands. For example:

  • There must not be any spaces in the following AT command: AT+UART=115200,8,1,0,3.

  • However, there must be a space in the following terminal command: make flash.

Mixing Chinese Writing with Numbers and English Writing

In Chinese texts with English inserts, only use English spaces:

  • Between Chinese characters and English letters

  • Between Chinese characters and English punctuation marks

  • Between Chinese characters and numbers

Example

English Text

Translated Text

Notes

ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip.

ESP32 是集成 2.4 GHz Wi-Fi 和蓝牙 4.2 的单芯片方案。

关于 ESP-IDF 的基本使用，可参考目录下的 README (.md) 文件。

See Section Parentheses.

乐鑫 (Espressif) 是一家无晶圆厂半导体公司。

See Section Parentheses.

乐鑫研发和设计 IoT 业内集成度高、性能稳定、功耗低的无线系统级芯片。

But never use English spaces around Chinese punctuation marks.

Example

Chinese Text

Notes

ESP-WROOM-32 模组（内置了 ESP32 芯片）

See Section Parentheses.

乐鑫总部位于中国上海 (Shanghai, China)，是一家无晶圆厂半导体公司。

See Section Parentheses. Here, there is an English space before the left parenthesis, but no space after the right parenthesis as it is followed by a Chinese punctuation mark.

Parentheses

If the text enclosed in the parentheses only consists of English letters and/or numbers:

Example

  • 关于 ESP-IDF 的基本使用，可参目录下的 README (.md) 文件。

If the text enclosed in the parentheses consists of Chinese characters or, among English letters and/or numbers, includes Chinese characters:

  • Use Chinese parentheses.

  • Do not add spaces between Chinese parentheses and the text outside of them.

Example

  • ESP32 集成了 Wi-Fi（2.4 GHz 带宽）和蓝牙 4.2。

  • 准备一台 PC（安装 Windows 操作系统）

Hyphens and Dashes

Hyphens and Dashes

Name

Symbol

Keyboard Shortcut

Windows

Linux

macOS

LaTeX

Hyphen

-

-

-

-

-

En dash

–

–

–

Option + -

Option + -

Em dash

—

—

—

Shift + Option + -

—

When to Use Hyphens

This section introduces some common cases where hyphenation is needed.

Use hyphens in a compound modifier preceding the modified word. A compound modifier is a string of two or more words that function together as an adjective and cannot be separated. Hyphenation in this case aids clarity and readability.

Example

Compound Modifier (Preceding a Noun)

Predicative Expression (Part of a Verb Phrase)

We are using state-of-the-art technology.

The technology we use is state of the art.

The company develops Wi-Fi-enabled toys.

The toys the company develops are Wi-Fi enabled.

Hyphenate compound modifiers preceding nouns in the following cases:

  • The modifier consists of a noun or adjective and a present or past participle.

    Example

    Preferred

    Avoid

    small-sized development board

    small sized development board

    Wi-Fi-enabled toy

    Wi-Fi enabled toy

  • The modifier consists of a number, single letter, or fraction and a noun or participle.

    Example

    Preferred

    Avoid

    2-bit data length

    2 bit data length

    y-coordinate value

    y coordinate value

    half-duplex mode

    half duplex mode

  • Confusion might occur without the hyphen.

    Example

    Preferred

    Avoid

    built-in operating system

    built in operating system

    on­-board PCB antenna

    on board PCB antenna

    state-of-the-art technology

    state of the art technology

Do not hyphenate in the following cases:

  • Do not hyphenate a predicative adjective modifying the subject of a sentence that follows a verb unless it is an established hyphenated compound.

    Example

    Preferred

    Avoid

    Note

    The camera is built in.

    The camera is built-in.

    The module is small sized.

    The module is small-sized.

    It determines whether individual eFuse parameters are write-protected.

    It determines whether individual eFuse parameters are write protected.

    Write-protected is an established term widely used in the industry.

  • Do not use hyphens when the words preceding nouns do not function collectively as a compound modifier. In such cases, the words before a noun can be separated and function independently. For example, when the modifiers consist of an adverb and an adjective where the adverb modifies the adjective. In such cases, the modifier may start with the word “very” or other adverbs ending in “ly”.

    Example

    Preferred

    Avoid

    very similar APIs

    very-similar APIs

    highly integrated platform

    highly-integrated platform

  • Do not use hyphens between different units of modifier that modify the same noun.

    Example

    Preferred

    Avoid

    Note

    high-level programming language

    high-level-programming language

    thirty-two 32-bit general-purpose registers

    thirty-two 32-bit-general-purpose registers

    It is suggested to avoid using consecutive compound modifiers for better readability and only use them where white space is at a premium.

  • Do not add hyphens between the noun and its modifier.

    Example

    Preferred

    Avoid

    in Station mode

    in Station-mode

    Light-sleep mode

    Light-sleep-mode

  • Do not form hyphenated modifiers from one-word adjectives. If you are not sure whether the word is a one-word adjective, refer to Merriam-Webster’s Collegiate Dictionary or go to Documentation Team Site > Section Something You Might Find Useful > Espressif Term Base. You can also consult Documentation team members.

    Example

    Preferred

    Avoid

    uppercase and lowercase letters

    upper-case and lower-case letters

  • Do not hyphenate a compound modifier that includes an open compound. Instead, use an en dash.

    Example

    Preferred

    Avoid

    Windows 10–compatible products

    Windows 10-compatible products

The above examples may not cover all situations. If you are not sure whether the hyphenation is needed, always refer to Documentation Team Site > Section Something You Might Find Useful > Espressif Term Base and authorized dictionaries such as Merriam-Webster’s Collegiate Dictionary, or consult Documentation team members.

When using a suspended compound modifier, include a hyphen with both adjectives and follow the first hyphen with a space.

Example

Preferred

Avoid

upper- or lower-right corner

upper or lower-right corner

in a byte-, half-word-, or word-aligned manner

in a byte, half-word, or word-aligned manner

Note

When the hyphenated words need to be capitalized, e.g., if it is included in a heading title, capitalize the first word and any subsequent words that are not articles, prepositions, or coordinating conjunctions. For example, use Read-Only Mode in a heading instead of Read-only Mode.

When to Use En Dashes

  • To indicate a minus sign (for example, “1–2”)

    Exception

    Use hyphens when writing code.

  • To indicate negative numbers, for example, “–1”

  • To contrast values, or illustrate a relationship between two things, for example, “Pycom–EspressifHackathon”

  • To connect words in a compound modifier that includes an open compound

    Example

    • Windows 10–compatible products

  • To indicate a range of values in English documentation, without spaces before and after unless there is a measurement unit before it

    Example

    Preferred

    Avoid

    GPIO21–GPIO23

    GPIO21 – GPIO23

    pp. 38–55

    pp. 38 – 55

    2.3 V – 3.6 V

    2.3 V–3.6 V

    However, for ranges that include negative numbers, a tilde (~) may also be used to avoid ambiguity or awkwardness (e.g., a temperature range of −40 °C ~ +85 °C).

    Note

    In Chinese documentation, use tildes instead of en dashes to indicate ranges. Spaces are not needed before and after the tilde unless there is a measurement unit before it (e.g., 2.3 V ～ 3.6 V).

    Note

    Do not use tildes to represent the word “about”.

    Example

    Preferred

    Avoid

    The drive strength of the internal pull-up (wpu) and pull-down (wpd) is about 75 μA.

    The drive strength of the internal pull-up (wpu) and pull-down (wpd) is ~75 μA.

    See also Section Time and Date Ranges.

When to Use Em Dashes

Use an em dash to denote a break in a sentence or to set off parenthetical statements.

Example

  • The information in your spreadsheet—numbers, formulas, and text—is stored in cells.

Slashes

The word slash usually implies the forward slash ” / ” which is used in writing and computer coding. However, there is also the backslash ” \ ” which is used in computer coding only.

Use a slash character in the following cases:

  • In constructions that imply a combination

    • I/O pad

    • read/write operation

  • For fractions

    • 1/3

  • As a separator for compound units of measure

    • 100 Mbit/s

  • As the path separator in OS Linux and other Unix systems

    • cd ~/esp/hello_world

  • For website URLs

Use a backslash character in the following cases:

  • As the path separator in MS Windows

    • cd C:\Users\%userprofile%\esp\hello_world

Do not use slashes in the following cases:

  • A substitute for “or”

    Example

    Preferred

    Avoid

    Notes

    Some embedded memories can be accessed via the data bus or the instruction bus.

    Some embedded memories can be accessed via the data/instruction bus.

    Not clear if the slash mark indicates “or” or “and”.

Quotation Marks

Differentiate between single quotation marks and double quotation marks.

In English, divide a quote from the surrounding text with double quotes. If you add a quotation within an already quoted text, use single quotation marks. This concept can be represented as “… ‘…’ …”.

If the text enclosed in quotation marks only consists of English letters and/or numbers:

  • Use English quotation marks.

  • Separate the text outside of English quotation marks with one English space. See Section Mixing Chinese Writing with Numbers and English Writing.

    Example

    • 如果引导加载程序二进制文件过大，则引导加载程序构建将失败并显示 “Bootloader binary size [..] is too large for partition table offset” 的错误。

Please note the text here is no UI element. For UI elements, see Chapter Writing Instructions.

If the text enclosed in quotation marks consists of Chinese characters or, among English letters and/or numbers, includes Chinese characters:

  • Use Chinese quotation marks.

  • Do not add spaces between Chinese quotation marks and the text outside of them.

Brackets

Square Brackets

Use square brackets as follows:

  • Within parenthetic text . Use square brackets when nested parentheses are needed.

    • （不能是简单 Type [如 string 或 Guid]）

  • For optional command-line entries . Use to indicate an optional parameter or other types of entries.

    • idf.py -p PORT [-b BAUD] flash

Do not put spaces between brackets and the text that these brackets enclose, for example, [Module Name].

Angle Brackets

Use angle brackets and lowercase letters for tags, for example, the <h1> tag, the <font> tag.

You can use a right-angle bracket “>” to show navigation in menus. Put a space before and after the bracket.

Example

  • Click File > Export To > PDF.

Punctuation in Lists

The following notes on punctuation in lists should be made:

  • Place a colon “:” at the end of an introductory phrase.

  • Use a full stop at the end of each item in a list of complete sentences, such as this one.

  • Omit punctuation at the end of each item in a list of sentence fragments.

  • If a list has at least one complete sentence, use a full stop at the end of each item, regardless of whether it is a fragment or a full sentence.

Here is an example of a list consisting of sentence fragments. Its characteristic features are as follows:

  • Short items

  • Absence of active verbs

  • Abundance of Participial phrases

Use the following capitalization rules:

  • Capitalize the first letter of each item in a list of complete sentences.

  • Preferably capitalize the first letter of each item in a list of sentence fragments.

  • In a list of single words, preferably do not capitalize the first letter of each item.

  • If at least one item in a list is capitalized, capitalize all the other items.

Rules of Using Commas

Punctuation plays an indispensable role in conveying information clearly and concisely. In particular, missing or misplaced commas may introduce a lot of confusion in sentences.

In some cases, the need to add a comma is self-evident. In other cases, there is some degree of flexibility in how to use commas. Yet in other cases, you need to have a clear grasp of some rules.

The guidelines below will help you brush up on how to properly use commas.

Cases in which you SHOULD use commas:

1. Separating items in a series of three or more nouns or two or more coordinate adjectives.

Example

  • It helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.

It is recommended that you use the serial comma before the final “and” or “or” in the list of several items. This kind of serial comma is usually called the Oxford comma. Whether or not you decide to use it, please be consistent. Keep in mind, however, that there are cases in which the Oxford comma might affect the meaning – please refer to Section Intricacies of Using the Oxford Comma.

2. Surrounding nonessential appositives (those that add information to a sentence but can be omitted without changing its meaning).

Example

  • The module can be completely independent, which means it does not rely on the implementation of other modules.

3. Before a coordinating conjunction (e.g., and/but/so/yet/nor/for).

Example

  • The function will be used repeatedly in the module, so it is reasonable to add this function to the design.

But you do not need a comma if both independent clauses are relatively short and similar in meaning.

Example

  • Try them out and see the diagram instantly rendering below.

4. After introductory elements.

Example

  • On top of that, we have created a couple of custom add-ons and extensions to help integrate documentation in the ESP-IDF repository.

5. After the abbreviations i.e. (which means “that is” or “in other words”) and e.g. (which means “for example”).

Example

  • After it starts up, the timer can generate a specific event, e.g., the Alarm Event.

  • The code coverage data is stored internally on the target (i.e., in trace memory).

6. In a complex sentence, use a comma to separate a dependent clause that comes BEFORE an independent clause.

Example

  • If you want to use these features, you need to ensure that ESP32 supports them.

Essentially, the main function of a comma is to add a pause. There is a simple trick to test the placement of commas. Whenever you write something, read it aloud as it is written, then read it aloud as you intend it to sound. If you find any inconsistencies, you might need to add or remove some commas to introduces the required pauses or to emphasize important parts.

Intricacies of Using the Oxford Comma

The Oxford comma is a comma that is used before the conjunction that joins the last two enumerated items within a sentence. The Oxford comma helps to prevent confusion with regard to whether the last two items in a series are related.

Example

Preferred

Avoid

Notes

The table should provide separate columns for user IDs, their first names, and last names.

The table should provide separate columns for user IDs, their first names and last names.

The phrase their first names and last names does not make it clear whether first names and last names should be placed in one column or in separate columns. Adding the Oxford comma before and, disambiguates the situation. Now it is clear that you need two separate columns.

Provide feedback about this document