diff --git a/README.adoc b/README.adoc index fc30c35..de849e1 100644 --- 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 <> 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 <>, and then see <> for more information. - -Why not use autogenerated section IDs?:: -Due to many duplicate titles, custom section IDs (`+[[id]]+`) are better when being referenced (`+<>+`). - -Why not use named HTML entities?:: -Asciidoctor PDF doesn`'t support all named HTML entities (e.g. `+×+`), so you have to use entity numbers (e.g. `+×+`) 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 <> 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 <>, 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 index f74b6ee..4b16cf8 100644 --- a/docs/README-CN.adoc +++ b/docs/README-CN.adoc @@ -104,21 +104,6 @@ bundle exec rake book:html['book.adoc'] bundle exec rake book:pdf['book.adoc'] ---- -== 疑问 - -[qanda] -我需要做哪些准备工作？:: -根据 <> 部分安装环境, 接着参考 <> 部分来获取更多信息。 - -为什么不用自动生成的章节编号？:: -因为存在着许多重复的标题，自定义的章节编号（`+[[id]]+`）在被引用时会更好（`+<>+`）。 - -为什么不用 HTML 实体的名称？:: -Asciidoctor PDF 不支持所有的 HTML 实体名称（例如 `+×+`）, 所以在此处您必须使用 HTML 实体的编号（例如 `+×+`）。 - -有辅助编辑文档的工具吗？:: -https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] 仓库中有一些可能有用的工具（例如生成表格的目录的工具）。 - == 贡献 *感谢您花时间为该项目作贡献！* @@ -126,6 +111,8 @@ 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 index 6bc7547..31fc9ac 100644 --- 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,21 +119,6 @@ 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 <>, and then see <> for more information. - -Why not use autogenerated section IDs?:: -Due to many duplicate titles, custom section IDs (`+[[id]]+`) are better when being referenced (`+<>+`). - -Why not use named HTML entities?:: -Asciidoctor PDF doesn`'t support all named HTML entities (e.g. `+×+`), so you have to use entity numbers (e.g. `+×+`) 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!* @@ -141,6 +126,8 @@ See https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Too 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 new file mode 100644 index 0000000..f7e1509 --- /dev/null +++ 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]] +== 小节标题 + +参考 <> 。 +-- + +如果有很多重复的标题，不要使用自动生成的小节 ID。 + +== HTML 实体 + +Asciidoctor PDF 不支持所有命名的 HTML 实体（例如 `+×+`），所以您必须在这里使用实体编号（例如 `+×+`）。 + +== 表格 + +用以下格式来画表格（表格标题仅首字母大写）： + +[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] 仓库可能有有用的工具。 diff --git a/docs/style-guide-EN.adoc b/docs/style-guide-EN.adoc new file mode 100644 index 0000000..9f8ffa7 --- /dev/null +++ b/docs/style-guide-EN.adoc @@ -0,0 +1,121 @@ += Style Guide +:docinfodir: ../themes +:docinfo: shared +:doctype: book +:toc: left + +== Project layout + +[source] +-- +. +|-- contributors.txt # Contributors +|-- docs # Documents dir +| |-- index.adoc # Homepage on Github Pages +| |-- Document1 # Section's (Level 0) dir +| | |-- section1 # Section's (Level 1) dir +| | | |-- section1-1.adoc # Section (Level 2) +| | | `-- ... +| | |-- section1.adoc # Section (Level 1) +| | `-- ... +| |-- Document1.adoc # Section (Level 0) +| |-- README-CN.adoc # README in Chinese +| |-- README-EN.adoc # README in English +| `-- ... +|-- fonts # Fonts dir +|-- Gemfile +|-- images # Images dir +| |-- Document1 # Document1's image dir +| `-- ... +|-- LICENSE # License +|-- public # Output dir +|-- Rakefile +|-- README.adoc # README +|-- themes # Themes dir +| |-- docinfo-footer.html +| |-- html.css # HTML theme +| `-- pdf.yml # PDF theme +`-- ... +-- + +File names are all lowercase, with "`-`" instead of spaces. +The file name of the document in English/Chinese ends with "`EN`"/"`CN`". +File naming and folder structure should be consistent in the title level. + +[source] +-- += Document Title (Level 0) + +== Level 1 Section Title + +=== Level 2 Section Title + +... +-- + +== Section + +Capitalize the first letter of each word when writing a section title. + +Custom IDs must start with a letter and contain only lowercase letters and Arabic numerals and "`-`". +Put the custom section ID (`+[[id]]+`) above the section title: + +[source] +-- +[[section-id]] +== Section Title + +Refer to <>. +-- + +Do not use autogenerated section IDs if there are many duplicate titles. + +== HTML Entities + +Asciidoctor PDF doesn`'t support all named HTML entities (e.g. `+×+`), so you have to use entity numbers (e.g. `+×+`) here. + +== Tables + +Use the following format to write a table (capitalize only the first letter of the table title): + +[source] +-- +[[table-id]] +.Table title +[%header,cols="3*1"] +|=== +|Column 1 +|Column 2 +|Column 3 + +|Cell in column 1, row 2 +|Cell in column 2, row 2 +|Cell in column 3, row 2 + +|Cell in column 1, row 3 +|Cell in column 2, row 3 +|Cell in column 3, row 3 +|=== +-- + +.Table title +[%header,cols="3*1"] +|=== +|Column 1 +|Column 2 +|Column 3 + +|Cell in column 1, row 2 +|Cell in column 2, row 2 +|Cell in column 3, row 2 + +|Cell in column 1, row 3 +|Cell in column 2, row 3 +|Cell in column 3, row 3 +|=== + +== Table of Contents + +We recommend that you use tools rather than maintaining the "`List of Tables`" and the "`List of Figures`" manually. + +See https://github.com/FreeFlyingSheep/golang-asciidoc-tools[Golang AsciiDoc Tools] for tools that may be useful.