Giter VIP home page Giter VIP logo

document-style-guide's Introduction

document-style-guide's People

Contributors

alancutflim avatar alwayshacking avatar fengh0409 avatar geometryolife avatar hktang avatar kohunglee avatar lichao-cobo avatar nuomi1 avatar oldj avatar passionpenguin avatar pythias avatar ricosmall avatar ruanyf avatar ryanxingql avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

document-style-guide's Issues

关于引号的建议

在 Markdown 中使用中文引号时,编辑状态效果与最终显示效果会有所差异。引号放在单行代码中是这样的 “ ” ‘’,这确实符合日常书面使用的形式。但在 Markdown 中,引号放在单行代码中使用并非常态,比较常见的使用场景如下所示:
中文输入法全角状态的双引号及单引号:
“例子”
‘例子’
英文输入法半角状态的双引号及单引号:
'例子'
"例子"
以上例子中在 Atom 等 Markdown 格式编辑器中测试,只有英文状态的引号在预览界面能够以原生状态体现。因此,建议中文的引号使用『』(双引号),「」(单引号),这个型式的引号,编辑状态效果与最终显示效果是一致的,即使放到单行代码中,相比之下也没有太多差异。
『例子』
「例子」

数值与中文单位之间是否要加空格?

第一组

A. 体重是 68公斤。
B. 体重是 68 公斤。

第二组

A. 今年是 2016年。
B. 今年是 2016 年。

第三组

A. 今天是 9月 1日。
B. 今天是 9 月 1 日。

第四组

A. 现在是 8点 36分。
B. 现在是 8 点 36 分。

上面四种情况,A 句是数字与中文单位之间没有空格,B 句是有空格。大家觉得,哪种写法比较可取?

文档规范的根据是什么?

比如

全角中文字符与半角阿拉伯数字之间,有没有半角空格都可,但必须保证风格统一,不能两种风格混杂。 -- https://github.com/ruanyf/document-style-guide/blob/master/docs/text.md

这里的依据是风格统一

那么以下的根据是什么?美学吗?

英文单位若不翻译,单位前的阿拉伯数字与单位间不留空格。
错误:一部容量为 16 GB 的智能手机
正确:一部容量为 16GB 的智能手机

当遇到文档中没有说明的或者模棱两可的情况,我们该依据什么来选择?

读书笔记的写作规范

读书笔记的定义:对于一篇文章的某些段落或句子甚至词汇,想写下自己的一些东西。

文章原文会占据绝大部分,而读书笔记可能并不多。那么还要对文章原文进行 “>” 引用吗?还是不引用文章原文,而着重强调读书笔记?

关于中英文混用时的标点符号

中英文句子混用的时候括号和引号是该使用全角还是半角呢?

1. 服务器磁盘通常使用磁盘阵列(RAID)来组建。
2. 服务器磁盘通常使用磁盘阵列(RAID)来组建。
3. 中文里的“它”应该写成"it",而不是"he"。
4. 中文里的“它”应该写成“it”,而不是“he”。

请问一下老师,您认为哪种是正确的。

句子内包含中英文共存的术语,如何控制字间距?

A. TCP/IP 协议族有两个核心协议。
B. TCP/IP协议族 有两个核心协议。
C. TCP/IP协议族有两个核心协议。
A. TCP/IP 模型和 OSI 模型的区别。
B. TCP/IP模型 和 OSI模型 的区别。
C. TCP/IP模型和OSI模型的区别。

A 句是英文字符和中文字符有空格;B 句是整个术语前后带空格;C 句是不带任何空格。
请问哪种写法比较规范?

推荐工具:lint-md

lint-md 是基于阮老师的文档规范来的,将其中一些规则直接工具 lint 化。组织地址:https://github.com/lint-md

  • lint-md 提供 lint、fix 的核心 API
  • cli 命令行工具
  • eslint 扩展
  • vscode 副局插件

阮老师可以看看,然后给个推荐呗~

讨论:列表末尾的符号应该是“无”、“分号”还是“句号”?

如题。对于以下段落,大家觉得哪种表现形式更好?


无标点,只适用于一行中没有句号的情况:

  • 一个段落只能有一个主题,或一个中心句子
  • 段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务
  • 段落之间使用一个空行隔开
  • 段落开头不要留出空白字符

分号,最后一行句号:

  • 一个段落只能有一个主题,或一个中心句子;
  • 段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务;
  • 段落之间使用一个空行隔开;
  • 段落开头不要留出空白字符。

每行都是句号:

  • 一个段落只能有一个主题,或一个中心句子。
  • 段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务。
  • 段落之间使用一个空行隔开。
  • 段落开头不要留出空白字符。

标题文中“后者”指代不明确

标题一文第4点中
“示例:下面的结构二要好于结构一。后者适用的场景,主要是较长篇幅的内容。”
这里的“后者”指代不明确,建议改为“结构一”

怎么打印或者下载?

阮老师好,偶然间看到您的标点符号规范。
请问怎么下载或者打印这份规范?这样阅读起来方便一些。GitHub打开太麻烦了

英文省略号可否使用?

英文中,省略号是...,如果是中英文混排中,是否应该保留英文省略号?如:

  1. 下面是一句不完全的引用:“This is an incomplete quote ...omitted in the middle.”。
  2. 下面是一句不完全的引用:“This is an incomplete quote omitted in the end....”。
  3. 下面是一句不完全的引用:“...is an incomplete quote omitted in the head.”。

这三句的英文省略号分别在段中、端末和段首。而且是在引用中,是否应该遵循英文规范而保留省略号。

文章中 标点符号 -- 省略号 未提及英文省略号的使用,我有点不确定在中英文混排中,是否应该保留。还是说,应该规避这样的写法。

建议规范英文逗号和中文顿号的用法

这个出现的频率比较高,并且使用方式有争议,大家可以讨论下

中文和中文之间使用中文顿号,这个应该没争议

A. 英文和英文之间使用英文逗号
B. 英文和英文之间使用中文顿号
C. 以上皆可

使用的技术包括 JavaScript, CSS 和 HTML
使用的技术包括 JavaScript、CSS 和 HTML

X. 英文和中文之间使用英文逗号
Y. 英文和中文之间使用中文顿号
Z. 以上皆可

我最欣赏的科技公司有 Google, Facebook, 腾讯和阿里等
我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等

当引用部分复杂时,如何引用并评论?

在 MarkDown 中,可以使用 > 来表示引用,在引用部分是整段文字的时候,使用 > 没有什么问题。但是当引用部分含有多个段落及样式的时候,就难以引用,比如我引用下面的内容,并加入我自己的评论,如何做会比较好?

引用自:https://github.com/ruanyf/document-style-guide/edit/master/docs/paragraph.md
引用第三方内容时,应注明出处。

One man’s constant is another man’s variable. — Alan Perlis

如果是全篇转载,请在全文开头显著位置注明作者和出处,并链接至原文。

本文转载自 WikiQuote

使用外部图片时,必须在图片下方或文末标明来源。

本文部分图片来自 Wikipedia

句号的非必要性

句号的本质其实是分割符号,如果有换行分割就不必要句号,显得非常多余

建议章节放到 issues

阿里的文档是这样做的,方便评论和建议。当然放到 issues 就不方便 clone 了。

建议把所有章节都放到 README 文件里

把所有内容放到 README,这样读起来比较方便,不用每读一个章节就点开一个文件。如果你觉得可以的话,我可以帮忙整合,然后给你发个 pull request。

两章节连接号说明不一致和参考链接优化建议

  1. 《数值》一节的 数值范围 部分中的说明

    表示数值范围时,用 —— 连接

    和《标点符号》一节的 连接号 部分中的说明

    数值范围(例如日期、时间或数字)应该使用波浪连接号() 。

    两处的说明并不一致。应该统一这两处的说明。

    而且根据现行最新国家标准 GB/T 15834—2011 《标点符号用法》

    4.13.3.2 标示下列各种情况,一般用一字线,有时也可用浪纹线:
    ……
    b) 标示数值范围(由阿拉伯数字或汉字数字构成)的起止。
    示例 4:25~30 g
    示例 5:第五~八课

    并无用两个 (U+2014 Em Dash)标示数值范围的起止的用法。

  2. 为什么要往 参考链接 中添加两个《出版物上数字用法》(即 PDF 版百度百科词条)?
    个人认为没必要。而且该百度百科词条的连名称都是错的,虽然标准号写着是 GB/T 15834-2011,但内容是不完全一致的。
    如果是希望能直接在线预览,完全可以随便在百度文库里找一个,或者直接用国家标准全文公开系统的 在线预览

文件夹应该如何命名

请问对于文件夹,是否有推荐的命名格式?

  • 首字母大写,单词之间空格
  • 和文件一样全部小写并用-连接
  • 或者其它更推荐的方式?

issue/标题-标点符号

标题中符号判断有误:

首先要弄清楚的是,标题末尾能不能用问号。

黄伯荣、廖序东主编的《现代汉语》对标点符号的用法作了如下的说明:

"现在通行的标点符号有十四种,分为点号和标号两大类。句号、问号、感叹号、逗号、顿号、分号、冒号属于点号,引号、括号、破折号、省略号、书名号、着重号、间隔号属于标号。
"点号主要是表示语言中种种停顿的。标号主要是标明词语或句子的性质和作用的。
"也就是说,由于文章标题末尾是不需要停顿的,因此不能用逗号、句号等点号;但表明句子性质和作用的标号是可以用的,常用的如省略号。
"而问号和感叹号两种点号也兼属标号:就它表示问句、感叹句末了的停顿而言,是点号;就它表示疑问、感叹的性质而言,是标号。"

(同上)据此可知,标题末尾是可以用问号、省略号、叹号的。


建议在标点符号处添加标号点号在标题中的使用规范 ψ(`∇´)ψ

文档引用请求

首先说声对不起,因为我的英文很烂,所以我使用中文提问(在您的个人资料显示是**),我最近计划录制如何书写技术类笔记相关的视频,在阅读了您的文章之后觉得很棒,想在视频中引用,需要先征得您的同意或者其他建议

标题与加粗的选择

什么情况下使用标题,什么情况下使用加粗,是否存在选用两者都合适的情况?
比如在以太坊白皮书中,有

  • Namecoin - created in 2010,

换用

Namecoin

Created in 2010,

是否也合适?

一个小疑问

做前端的经常谈到浏览器兼容性问题,这时候我们会说:IE 8 以上或者 IE 8+。
这时候会有歧义,是否包含 IE 8 在内。
这种情况怎么解决?

阮老师怎么看待用 asciidoc 来写书?

最近计划写书, 打算用 asciidoc 写原稿, word 交付出版社.

然后, 来到这里把相关规范重新又读了一遍.

想看看 阮老师对 asciidoc 的看法, 因为, 好像阮老师的书都是 markdown 的. 之前有考虑过用 asciidoc 吗?

我个人觉得 asciidoc 跟 markdown 很类似, 而且功能更加丰富, 并且, 像 o'reilly 这种出版社还官方推荐 asciidoc. 想听听阮老师看法.

关于“英文单位若不翻译,单位前的阿拉伯数字与单位间不留空格”

根据国际单位制的标准 5.4.3,数字与单位之间还有需要一个空格的,这个空格理解成数字与标点之间的乘法。唯一的例外是表示角度的度、角和分。

同样,GB 3100-1993 国际单位制及其应用 6.2.4 规定了

单位符号应写在全部数值之后,并与数值间留适当的空隙。

所以在没有比如 CSS 样式处理“空隙”的情况下,在数字与单位间还是得加上一个空格。

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.