Add style guide

loongson · Aug 17, 2021 · 70dab4c · 70dab4c
1 parent bd3717e
commit 70dab4c
Show file tree

Hide file tree

Showing 5 changed files with 251 additions and 176 deletions.
diff --git a/README.adoc b/README.adoc
@@ -1,6 +1,8 @@
 = LoongArch Documentation
 Loongson Technology Corporation Limited
 
+Click the links below for more details:
+
 * https://loongson.github.io/LoongArch-Documentation/README-EN.html[English]
 * https://loongson.github.io/LoongArch-Documentation/README-CN.html[中文]
 
@@ -46,148 +48,3 @@ To make it easier to download, each HTML page contains embedded CSS and images.
 ** https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-EN.html[HTML version].
 ** https://loongson.github.io/LoongArch-Documentation/LoongArch-ELF-ABI-EN.pdf[PDF version].
 ** https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-CN.pdf[Original document].
-
-== Getting Start
-
-We *strongly recommend* that you develop on Linux/UNIX or macOS.
-If you want to develop on Windows, see <<Developing on Windows>> first.
-
-. Make sure the https://www.ruby-lang.org/en/downloads[Ruby development environment] is installed.
-
-. Install bunlder:
-+
-[source]
-----
-gem install bundler
-----
-
-. Clone this project:
-+
-[source]
-----
-git clone https://github.com/loongson/LoongArch-Documentation
-----
-
-. Enter the project repo and install the gems into the project using the bundle command (this will take a while, during which time about `20MB` of data will be downloaded):
-+
-[source]
-----
-cd LoongArch-Documentation && bundle config set --local path .bundle/gems && bundle
-----
-
-. Now you can generate the documents.
-+
-* Convert AsciiDoc to both HTML and PDF:
-+
-[source]
-----
-bundle exec rake book:all
-----
-
-* Convert AsciiDoc to HTML only:
-+
-[source]
-----
-bundle exec rake book:html
-----
-
-* Convert AsciiDoc to PDF only:
-+
-[source]
-----
-bundle exec rake book:pdf
-----
-
-* Convert specified `book.adoc` to HTML:
-+
-[source]
-----
-bundle exec rake book:html['book.adoc']
-----
-
-* Convert specified `book.adoc` to PDF:
-+
-[source]
-----
-bundle exec rake book:pdf['book.adoc']
-----
-
-== Questions
-
-[qanda]
-Are there any prerequisites I need to take?::
-Install the environment refer to the <<Getting Start>>, and then see <<References>> for more information.
-
-Why not use autogenerated section IDs?::
-Due to many duplicate titles, custom section IDs (`+[[id]]+`) are better when being referenced (`+<<id,name>>+`).
-
-Why not use named HTML entities?::
-Asciidoctor PDF doesn`'t support all named HTML entities (e.g. `+&times;+`), so you have to use entity numbers (e.g. `+&#215;+`) here.
-
-Are there any convenience tools?::
-See https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] for tools that may be useful (e.g. for generating a list of tables).
-
-== Contributing
-
-*Thank you for taking the time to contribute!*
-
-You can create an issue or submit a pull request directly.
-If you submit a pull request, you can see the preview version https://loongson.github.io/LoongArch-Documentation-Preview[here] after successful rendering.
-
-The HTML versions of documents will be deployed automatically, while the PDF versions will be published manually.
-If you find an issue about the documents as found on the https://github.com/loongson/LoongArch-Documentation/releases[release page], please cross-check that it is still present in this repo.
-The issue may have already been corrected, but the changes have not been published yet.
-
-Branch `gh-pages` is generated by https://docs.github.com/en/actions[Github Actions], which is used to publish a project site by https://docs.github.com/en/pages[Github Pages].
-So you should not modify this branch directly.
-
-== References
-
-* This project was inspired by https://github.com/progit/progit2[Pro Git, Second Edition].
-
-* This project use https://asciidoctor.org[Asciidoctor] to generate HTML documents, and use https://github.com/asciidoctor/asciidoctor-pdf[Asciidoctor PDF] to generate PDF documents.
-
-* See https://docs.asciidoctor.org/asciidoc/latest[AsciiDoc Language Documentation] for AsciiDoc syntax.
-
-* See https://github.com/darshandsoni/asciidoctor-skins[
-asciidoctor-skins] for CSS stylesheets for Asciidoctor.
-See https://github.com/asciidoctor/asciidoctor-pdf/blob/main/docs/theming-guide.adoc[Asciidoctor PDF Theming Guide] for the style of a PDF file generated by Asciidoctor PDF from AsciiDoc.
-
-== Troubleshooting
-
-=== Developing on Windows
-
-Some of the file paths are so long that they exceed the 260-character limit of the Windows API, which can cause some strange problems.
-
-In Windows 10 version 1607 and later, these problems can be solved.
-If you are using an earlier version, or if you don`'t want to do some extra operations, you might consider using Docker, refer to <<Developing on Docker>> for more details.
-
-. https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later[Enable] long paths.
-
-. Use the latest https://git-scm.com/downloads[Git].
-Run `git config --global core.longpaths true` to modify the global configuration or run `git config core.longpaths true` in the repo to modify the local configuration.
-
-. Use the latest https://www.jruby.org/download[JRuby] instead of Ruby.
-
-The rest is the same as in <<Getting Start>>, but JRuby runs much slower and may have cmd popups when running commands.
-
-=== Developing on Docker
-
-We assume you know how to develop with https://www.docker.com[Docker].
-If you don`'t, please refer to the https://docs.docker.com/get-started/overview[official tutorial].
-
-You may find the official https://hub.docker.com/r/asciidoctor/docker-asciidoctor[Docker container] useful.
-
-== License
-
-link:LICENSE[License]
-
-== Contributors
-
-Since the release of the project, we have gotten several errata and content changes donated.
-Here are all the people who have contributed to https://github.com/loongson/LoongArch-Documentation[LoongArch Documentation] as an open source project.
-Thank you everyone for helping make this project better.
-
-The contributors are listed in alphabetical order:
-
-link:contributors.txt[Contributors]
diff --git a/docs/README-CN.adoc b/docs/README-CN.adoc
@@ -104,28 +104,15 @@ bundle exec rake book:html['book.adoc']
 bundle exec rake book:pdf['book.adoc']
 ----
 
-== 疑问
-
-[qanda]
-我需要做哪些准备工作？::
-根据 <<getting-start,开始>> 部分安装环境, 接着参考 <<references,引用>> 部分来获取更多信息。
-
-为什么不用自动生成的章节编号？::
-因为存在着许多重复的标题，自定义的章节编号（`+[[id]]+`）在被引用时会更好（`+<<id,name>>+`）。
-
-为什么不用 HTML 实体的名称？::
-Asciidoctor PDF 不支持所有的 HTML 实体名称（例如 `+&times;+`）, 所以在此处您必须使用 HTML 实体的编号（例如 `+&#215;+`）。
-
-有辅助编辑文档的工具吗？::
-https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] 仓库中有一些可能有用的工具（例如生成表格的目录的工具）。
-
 == 贡献
 
 *感谢您花时间为该项目作贡献！*
 
 您可以直接创建一个 issue 或发起一个 pull request。
 如果您提交了一个 pull request，在成功渲染后，您可以在 https://loongson.github.io/LoongArch-Documentation-Preview[这里] 看到预览版本。
 
+编写文档时请遵循 link:style-guide-CN.html[风格指南] 。
+
 HTML 版本的文档会被自动部署，而 PDF 版本的文档则由手动发布。
 如果您在 https://github.com/loongson/LoongArch-Documentation/releases[release 页面] 上的文档中发现问题，请复查它是否依然在该仓库中存在。
 这个问题可能已经被更正，而修改的内容还未发布。

diff --git a/docs/README-EN.adoc b/docs/README-EN.adoc
@@ -7,7 +7,7 @@ Loongson Technology Corporation Limited
 
 == Introduction
 
-This is the English translation of LoongArch documentation.
+The official documentation for LoongArch.
 
 * You can find documents online https://loongson.github.io/LoongArch-Documentation[here].
 
@@ -119,28 +119,15 @@ bundle exec rake book:html['book.adoc']
 bundle exec rake book:pdf['book.adoc']
 ----
 
-== Questions
-
-[qanda]
-Are there any prerequisites I need to take?::
-Install the environment refer to the <<Getting Start>>, and then see <<References>> for more information.
-
-Why not use autogenerated section IDs?::
-Due to many duplicate titles, custom section IDs (`+[[id]]+`) are better when being referenced (`+<<id,name>>+`).
-
-Why not use named HTML entities?::
-Asciidoctor PDF doesn`'t support all named HTML entities (e.g. `+&times;+`), so you have to use entity numbers (e.g. `+&#215;+`) here.
-
-Are there any convenience tools?::
-See https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] for tools that may be useful (e.g. for generating a list of tables).
-
 == Contributing
 
 *Thank you for taking the time to contribute!*
 
 You can create an issue or submit a pull request directly.
 If you submit a pull request, you can see the preview version https://loongson.github.io/LoongArch-Documentation-Preview[here] after successful rendering.
 
+Please follow the link:style-guide-EN.html[Style Guide] when writing documents.
+
 The HTML versions of documents will be deployed automatically, while the PDF versions will be published manually.
 If you find an issue about the documents as found on the https://github.com/loongson/LoongArch-Documentation/releases[release page], please cross-check that it is still present in this repo.
 The issue may have already been corrected, but the changes have not been published yet.

diff --git a/docs/style-guide-CN.adoc b/docs/style-guide-CN.adoc
@@ -0,0 +1,123 @@
+= 风格指南
+:docinfodir: ../themes
+:docinfo: shared
+:doctype: book
+:toc: left
+:toc-title: 目录
+:scripts: cjk
+
+== 项目布局
+
+[source]
+--
+.
+|-- contributors.txt            # 贡献者
+|-- docs                        # 文档目录
+|   |-- index.adoc              # Github Pages 上的主页
+|   |-- Document1               # 小节（级别 0）目录
+|   |   |-- section1            # 小节（级别 1）目录
+|   |   |   |-- section1-1.adoc # 小节（级别 2）
+|   |   |   `-- ...
+|   |   |-- section1.adoc       # 小节（级别 1）
+|   |   `-- ...
+|   |-- Document1.adoc          # 小节（级别 0）
+|   |-- README-CN.adoc          # 中文版 README
+|   |-- README-EN.adoc          # 英文版 README
+|   `-- ...
+|-- fonts                       # 字体目录
+|-- Gemfile
+|-- images                      # 图像目录
+|   |-- Document1               # Document1 的图像目录
+|   `-- ...
+|-- LICENSE                     # 许可证
+|-- public                      # 输出目录
+|-- Rakefile
+|-- README.adoc                 # README
+|-- themes                      # 主题目录
+|   |-- docinfo-footer.html
+|   |-- html.css                # HTML 主题
+|   `-- pdf.yml                 # PDF 主题
+`-- ...
+--
+
+文件名全部使用小写字母，用 “-” 来替代空格。
+英文/中文文档以 “EN”/“CN” 结尾。
+文件命名和目录结构应该和标题级别保持一致。
+
+[source]
+--
+= 文档标题（级别 0）
+
+== 级别 1 小节标题
+
+=== 级别 2 小节标题
+
+...
+--
+
+== 小节
+
+在写小节标题时大写每个单词的首字母。
+
+自定义的 ID 必须以英文字母开头，且内容只包含小写字母、阿拉伯数字和 “-”。
+把自定义的小节 ID（`+[[id]]+`）放到小节标题上面：
+
+[source]
+--
+[[section-id]]
+== 小节标题
+
+参考 <<section-id,小节标题>> 。
+--
+
+如果有很多重复的标题，不要使用自动生成的小节 ID。
+
+== HTML 实体
+
+Asciidoctor PDF 不支持所有命名的 HTML 实体（例如 `+&times;+`），所以您必须在这里使用实体编号（例如 `+&#215;+`）。
+
+== 表格
+
+用以下格式来画表格（表格标题仅首字母大写）：
+
+[source]
+--
+[[table-id]]
+.表格标题
+[%header,cols="3*1"]
+|===
+|列 1
+|列 2
+|列 3
+
+|列 1，行 2 的单元格
+|列 2，行 2 的单元格
+|列 3，行 2 的单元格
+
+|列 1，行 3 的单元格
+|列 2，行 3 的单元格
+|列 3，行 3 的单元格
+|===
+--
+
+.表格标题
+[%header,cols="3*1"]
+|===
+|列 1
+|列 2
+|列 3
+
+|列 1，行 2 的单元格
+|列 2，行 2 的单元格
+|列 3，行 2 的单元格
+
+|列 1，行 3 的单元格
+|列 2，行 3 的单元格
+|列 3，行 3 的单元格
+|===
+
+== 目录
+
+我们推荐您使用工具而不是手动维护“表目录”和“图目录”。
+
+https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] 仓库可能有有用的工具。