doc: Update README document

hotoo · Apr 7, 2022 · 7e2e57a · 7e2e57a
1 parent 6ffaa03
commit 7e2e57a
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 22 deletions.
diff --git a/README-v2.en-US.md b/README-v2.en-US.md
@@ -1,11 +1,13 @@
-# pīnyīn for Han （汉字） (v3)
+# pīnyīn (v2)
+
+pinyin, The convert tool of chinese pinyin.
 
 ---
 
 [![NPM version][npm-badge]][npm-url]
 [![Build Status][build-badge]][build-url]
 [![Coverage Status][coveralls-badge]][coveralls-url]
-[![Gittip][gittip-image]][gittip-url]
+[![Language Grade: JavaScript][lgtm-badge]][lgtm-url]
 [![NPM downloads][npm-downloads]][npm-url]
 
 
@@ -16,12 +18,14 @@
 [build-url]: https://github.com/hotoo/pinyin/actions
 [coveralls-badge]: https://coveralls.io/repos/hotoo/pinyin/badge.svg?branch=master
 [coveralls-url]: https://coveralls.io/r/hotoo/pinyin
-[gittip-image]: https://img.shields.io/gittip/hotoo.svg?style=flat-square
-[gittip-url]: https://www.gittip.com/hotoo/
+[lgtm-badge]: https://img.shields.io/lgtm/grade/javascript/g/hotoo/pinyin.svg?logo=lgtm&logoWidth=18
+[lgtm-url]: https://lgtm.com/projects/g/hotoo/pinyin/context:javascript
+
+
+Web Site: [简体中文](/README-v2) | English
 
-[中文文档网站](/README-v2)
+README: [简体中文](README-v2.md) | English
 
-[中文 README](README-v2.md)
 
 Convert Han to pinyin. useful for phonetic notation, sorting, and searching.
 

diff --git a/README-v2.md b/README-v2.md
@@ -1,4 +1,4 @@
-# README (v2)
+# pīnyīn (v2)
 
 pīnyīn, 汉字拼音转换工具。
 
@@ -22,9 +22,10 @@ pīnyīn, 汉字拼音转换工具。
 [lgtm-url]: https://lgtm.com/projects/g/hotoo/pinyin/context:javascript
 
 
-[English Documention Site](/en-US/README-v2)
+Web Site: 简体中文 | [English](/en-US/README-v2)
+
+README: 简体中文 | [English](README-v2.en-US.md)
 
-[English README](README-v2.en-US.md)
 
 转换中文字符为拼音。可以用于汉字注音、排序、检索。
 

diff --git a/README.en-US.md b/README.en-US.md
@@ -1,11 +1,13 @@
-# pīnyīn for Han （汉字） (v3)
+# pīnyīn (v3)
+
+pinyin, The convert tool of chinese pinyin.
 
 ---
 
 [![NPM version][npm-badge]][npm-url]
 [![Build Status][build-badge]][build-url]
 [![Coverage Status][coveralls-badge]][coveralls-url]
-[![Gittip][gittip-image]][gittip-url]
+[![Language Grade: JavaScript][lgtm-badge]][lgtm-url]
 [![NPM downloads][npm-downloads]][npm-url]
 
 
@@ -16,12 +18,14 @@
 [build-url]: https://github.com/hotoo/pinyin/actions
 [coveralls-badge]: https://coveralls.io/repos/hotoo/pinyin/badge.svg?branch=master
 [coveralls-url]: https://coveralls.io/r/hotoo/pinyin
-[gittip-image]: https://img.shields.io/gittip/hotoo.svg?style=flat-square
-[gittip-url]: https://www.gittip.com/hotoo/
+[lgtm-badge]: https://img.shields.io/lgtm/grade/javascript/g/hotoo/pinyin.svg?logo=lgtm&logoWidth=18
+[lgtm-url]: https://lgtm.com/projects/g/hotoo/pinyin/context:javascript
+
 
-[中文文档网站](/)
+Web Site: [简体中文](/) | English
+
+README: [简体中文](README.md) | English
 
-[中文 README](README.md)
 
 Convert Han to pinyin. useful for phonetic notation, sorting, and searching.
 
@@ -49,25 +53,33 @@ npm install pinyin@alpha --save
 
 for developer:
 
-```js
+```typescript
 import pinyin from "pinyin";
 
 console.log(pinyin("中心"));    // [ [ 'zhōng' ], [ 'xīn' ] ]
+
 console.log(pinyin("中心", {
   heteronym: true                // Enable heteronym mode.
 }));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]
+
 console.log(pinyin("中心", {
   heteronym: true,              // Enable heteronym mode.
   segment: true                 // Enable Chinese words segmentation, fix most heteronym problem.
 }));                            // [ [ 'zhōng' ], [ 'xīn' ] ]
+
 console.log(pinyin("我喜欢你", {
   segment: true,                // Enable segmentation. Needed for grouping.
   group: true                   // Group pinyin segments
 }));                            // [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]
+
 console.log(pinyin("中心", {
   style: pinyin.STYLE_INITIALS, // Setting pinyin style.
   heteronym: true
 }));                            // [ [ 'zh' ], [ 'x' ] ]
+
+console.log(pinyin("华夫人", {
+  mode: "surname",              // 姓名模式。
+}));                            // [ ['huà'], ['fū'], ['rén'] ]
 ```
 
 for cli:
@@ -78,6 +90,59 @@ zhōng xīn
 $ pinyin -h
 ```
 
+## Types
+
+### IPinyinOptions
+
+The types for the second argument of pinyin method.
+
+```typescript
+export interface IPinyinOptions {
+  style?: IPinyinStyle; // output style of pinyin.
+  mode?: IPinyinMode, // mode of pinyin.
+  segment?: IPinyinSegment | boolean;
+  heteronym?: boolean;
+  group?: boolean;
+  compact?: boolean;
+}
+```
+
+### IPinyinStyle
+
+The output style of pinyin.
+
+```typescript
+export type IPinyinStyle =
+  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | // Suggest.
+  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" |
+  0        | 1      | 2       | 5       | 3          | 4;               // compatibility.
+```
+
+### IPinyinMode
+
+The mode of pinyin.
+
+```typescript
+// - NORMAL: Default mode is normal mode.
+// - SURNAME: surname mode, for chinese surname.
+export type IPinyinMode =
+  "normal" | "surname" |
+  "NORMAL" | "SURNAME";
+```
+
+### IPinyinSegment
+
+The segment method.
+
+- Default is disable segment: `false`，
+- If set `true`, use "segmentit" module for segment in Web, use "nodejieba" for segment in Node.
+- Also specify follow string for segment (bug just "segmentit" in web):
+
+```typescript
+export type IPinyinSegment = "nodejieba" | "segmentit" | "@node-rs/jieba";
+```
+
+
 ## API
 
 ### `<Array> pinyin(words[, options])`

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# README (v3)
+# pīnyīn (v3)
 
 pīnyīn, 汉字拼音转换工具。
 
@@ -22,9 +22,10 @@ pīnyīn, 汉字拼音转换工具。
 [lgtm-url]: https://lgtm.com/projects/g/hotoo/pinyin/context:javascript
 
 
-[English Documention Site](/en-US/)
+Web Site: 简体中文 | [English](/en-US/)
+
+README: 简体中文 | [English](README.en-US.md)
 
-[English README](README.en-US.md)
 
 转换中文字符为拼音。可以用于汉字注音、排序、检索。
 
@@ -119,7 +120,7 @@ export interface IPinyinOptions {
 
 输出拼音格式。可以从直接使用以下字符串或数字，也兼容 v2 版本中 `pinyin.STYLE_TONE` 这样的形式。
 
-```
+```typescript
 export type IPinyinStyle =
   "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | // 推荐使用小写，和输出的拼音一致
   "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | // 方便老版本迁移
@@ -130,7 +131,7 @@ export type IPinyinStyle =
 
 拼音模式，默认普通模式，可以指定人名模式。
 
-```
+```typescript
 // - NORMAL: 普通模式
 // - SURNAME: 姓氏模式，优先使用姓氏的拼音。
 export type IPinyinMode =
@@ -146,7 +147,7 @@ export type IPinyinMode =
 - 也可以设置为 `true` 开启，Web 版中使用 "segmentit" 分词，Node 版中使用 "nodejieba" 分词。
 - 也可以声明以下字符串来指定分词算法。但目前 Web 版只支持 "segmentit" 分词。
 
-```
+```typescript
 export type IPinyinSegment = "nodejieba" | "segmentit" | "@node-rs/jieba";
 ```