1 min read

Steem Handbook Writing Rules Revised - 《Steem 指南》写作规范增补版

原文链接: steemit, cnsteem, busy, chainbb, steemdb, steemd, busy, markdown

This post is a contribution to the open source project Steem Handbook. Details could be found in the post Steem Handbook Calls for Support.

《Steem 指南》项目启动时,我们制订过写作规范,目的是为了各位作者步调尽可能一致,减少将来统稿的麻烦。随着编写工作逐渐展开,出现了一些事先没考虑到的地方,特此增补。

下面是向书稿的 GitHub 项目提交稿件的注意事项。文末给出了示例模板。

  • markdown

  • @ 符号

    • 由于书稿的源代码编译成书的过程里,@符号会做特殊处理,所以需要在原文里用\@来代替。例如,如果需要在成书里呈现”@steemh”,那么书稿里要写成“ \@steemh”。
  • 分段换行

    • 连续两个回车来分段。也就是说,在文本文件里,两段之间要有个空行。
  • 署名

    • 各章节的作者、编辑、校对,请自行以脚注形式在原稿章节标题处署名。标题处插入脚注的 markdown 语法是:“# 标题 ^[作者:\@deanliu;编辑:\@dapeng;校对:\@meixia。]
  • 原文链接

    • 如果是已经发布在 Steem 上的文章,那么建议在章节标题处以脚注形式注明出处,例如:“# 标题 ^[原文链接:https://steemit.com/steem/@steemh/steem-handbook-calls-for-support] ”。
  • 章节

    • 书稿生成程序会自动给章节编号,所以请勿手动编号。
    • 章标题和节标题之间不要有正文。也就是说,所有的正文文字都从属于某个节。
    • 建议(并非强制)各章最多分到三级标题(即“小节”),也就是 markdown 里的三个 # 号。尽量不要出现四级标题。如果需要的话,用粗体表示更低一级的标题即可。
    • 务必不要用 # 的方式把某段文字加粗或扩大字号。# 开头仅用作章节标题。
    • 建议(并非强制)每个章节标题后面添加个花括号,填入一些用来生成该节网页的文件名称,可以用标题拼音的首字母,也可以用英文,例如“# Steem 十讲{#lecture10}”。这样做有两个用处:(1)该章节的网址会以此命名;(2)方便交叉引用。例如在别处提到这一章节时,只需写“正如第 \@ref(lecture10) 章所述……”,这样,在编译生成书稿时会自动替换为该章节的编号。如果将来章节顺序有调整,则会自动更新。
  • 插图

    • 请插入本地图片,不要插入网络图片。如果需要插入网络图片,请先把图片下载到本地。同时注意不要侵犯别人图片的版权。
    • 本地图片的文件名请用”章节编号开头+后面随意”,但只能包含数字、字母、下划线、短横线,切勿使用中文。例如第三章的某图,文件名可以是 03_1_fig_title.jpg
    • 图片文件上传到项目主页的 images文件夹。使用 markdown 标准语法来插入图片,如 “![](images/03_1_fig_title.jpg)”。
    • 尽量使用静态图片(jpg,png),避免使用动态图片(gif);当然,如果动态图片对展示内容效果更好的话,也无???,但请备好能够替代的静态图片。这是为了方便做 pdf 和纸质书。
  • 索引

    • 在需要索引的地方加入\index{条目名称}即可。书后会自动添加索引条目,页码会自动生成。
    • 索引可以在统稿时集中添加。初稿里不建议添加索引。
  • 标点符号

    • 请按照中文的标点符号规则书写。例如,省略号是“……”而不是“......”,也不是“。。。”。
    • 最好不要用像“:)”的表情符号,除非十分有必要——想想印在纸质书里的感觉。
    • 简单规范见《中文文案排版指北》。详细规范见《中文排版需求》
  • 发布方式

    • 初稿首发在 Steem 上(标签:cn steem-guides),以便接受读者的修改意见。建议每帖 1000 到 2000 字为宜。
    • 修订稿由作者本人提交 PR 到 GitHub 项目(@rileyge 的教程 1教程 2,@evathinking 的教程)。
    • 项目会将书稿编译成网页pdfepub 三种格式,发布在网站 steemh.org。
  • 简单模板

# 基本常识 {#jbsc}

## 什么是 SBD ^[作者:\@steemh; 编辑:\@dapeng;校对: \@meixia。原文链接:https://steemit.com/cn/@deanliu/steem]

SBD 就是那啥啥(见 steemit [官方网站](http://steemit.com))。

下面是个图示。

![](images/03_1_fig_title.jpg)

相关链接: