SAC手册网页版任务列表 #102

seisman · 2016-07-23T12:04:50Z

用pandoc将latex源码转换成了markdown源码，但还存在很多问题，因而需要人工一一检查并修正。

markdown源码位于 gitbook 分支，网页版地址为：https://seisman.github.io/SAC_Docs_zh/ 。

以下是所有需要检查的markdown文件。请通过 @ 自己来认领某一任务，待文件检查完毕后记得来这里打钩。

自动转换得到的markdown源码已知会存在如下问题：

图片的路径不对，正确的使用方式是 ![图标题](/figures/xxxx.png)
大部分的表格转换都有问题，需要重新做
markdown只支持有序列表和无序列表，不支持定义列表，因而所有定义列表都需要修改。在每个命令的语法说明中，介绍选项时都使用的是定义列表，因而选项要如何介绍还需要讨论
命令的语法介绍部分转换存在问题，需要手动修改
网页版的脚注感觉很丑，考虑是否要去掉所有的脚注
数学公式存在问题。gitbook 是支持数学公式的，目前尚不确定为何不支持
C、Perl等代码没有被包含进去 (解决办法见 sacio/sacio-in-c.md)

文档风格：

从文件中插入代码： [include](filename.c)
插入图片： ![标题](/figures/filename.png)
插入数学公式：
1. 行内公式： 文字 $$x^2+y^2=x^2$$ 文字
2. 行间公式
```
文字
$$x^2+y^2=z^2$$
文字
```
链接到某一章： [地震数据处理](/data-process) 会链接到地震数据处理一章
链接到某一节/某个文件：[write](/commands/write.md) 会直接链接到 write 命令
SAC很多命令和选项都有简写形式，在原先的PDF中，是通过将某些字母变成灰色来表示简写形式。在markdown中不可能做到，因而需要用其他方式来表示简写形式。目前采取的方式是将命令的语法写两遍，第一遍写完整版，第二遍写简写版，可以参考 commands/taper.md 的写法
SAC中在介绍选项时使用的是定义列表，即 description 环境，而markdown 不支持，故而只能将其转换为无序列表，可以参考 commands/taper.md 的写法

introduction/what-is-sac.md @seisman
introduction/variants.md @seisman
introduction/request.md @seisman
introduction/history.md @seisman
introduction/linux-install.md @seisman
introduction/maillist.md @seisman
introduction/README.md @seisman
introduction/mac-install.md @seisman

fileformat/README.md add readme @likueimo
fileformat/header-variables.md
fileformat/binary-and-alphanumeric.md
fileformat/header-structure.md
~~fileformat/intro-to-fileformat.md~~ @likueimo
fileformat/sac-time.md

graphics/README.md add readme @likueimo
graphics/begin-devices.md
graphics/format-conversion.md
graphics/save-image.md
graphics/graphic-devices.md @seisman
graphics/composite-plots.md
graphics/plot-appearance.md
graphics/plot-commands.md
graphics/plot-contour.md

call-in-script/README.md @seisman
call-in-script/call-sac-in-python.md @seisman
call-in-script/call-sac-in-bash.md @seisman
~~call-in-script/intro-to-scripts.md~~ @seisman
call-in-script/call-sac-in-perl.md @seisman

libs/README.md added by @seisman
libs/call-libsacio.md
libs/intro-to-libs.md
libs/call-libsac.md

sacio/README.md @seisman
sacio/sacio-in-c.md @seisman
sacio/sacio-in-matlab.md @seisman
~~sacio/intro-to-sacio.md~~ @seisman
sacio/sacio-in-python.md @seisman
sacio/sacio-in-fortran.md @seisman

请参考 command/taper.md 的处理方式。

The text was updated successfully, but these errors were encountered:

seisman · 2016-07-23T12:30:27Z

使用pandoc将latex转换成了markdown。由于原latex源码中使用了很多自定义的命令，因而给转换带来了困难，需要做一些预处理。以下是预处理所需的命令：

# 将 !text! 转换为 \verb|text| 
perl -pi -e 's/!(.*?)!/\\verb|$1|/g' *.tex
# 将 \nameref{cmd:xxx} 转换为 \href{/commands/xxx.md}
perl -pi -e 's/\\nameref\{cmd:(.*?)\}/\\href{\/commands\/$1.md}{$1}/g' *.tex
# 将其他的 nameref 等转换为纯文本，因为pandoc 无法处理交叉引用，所以需要手动处理
perl -pi -e 's/\\.*ref\{(.*?):(.*?)\}/nameref-$1-$2/g' *.tex
# 将 SACCode 转换为minted 环境
perl -pi -e 's/\\begin\{SACCode}/\\begin\{minted\}\{bash\}/g' *.tex
perl -pi -e 's/\\end\{SACCode\}/\\end\{minted\}/g' *.tex
# 将SACCMD 转换为 section
perl -pi -e 's/SACCMD/section/g' *.tex
# 将 SACTitle 转换为 subsection
perl -pi -e 's/SACTitle/subsection/g' *.tex

处理之后的latex源码使用如下命令进行转换：

pandoc -t markdown --base-header-level=2 --atx-headers xxxx.tex -o xxxx.md

seisman · 2016-07-23T16:40:42Z

多人协作流程：

通过在某个任务之后 @ 自己以认领任务
仔细检查并修改文件
commit 并 push
在任务前打钩，表示该任务已完成

若 push 时发现因为已经有人做了其他提交，导致自己的版本与远程的版本不同而出现如下无法提交的错误：

To git@github.com:seisman/SAC_Docs_zh.git
 ! [rejected]        gitbook -> gitbook (fetch first)
error: failed to push some refs to 'git@github.com:seisman/SAC_Docs_zh.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

可以使用如下方式解决此问题：

git fetch origin gitbook
git rebase origin/gitbook
git push

seisman added enhancement Pull Request Welcomed labels Jul 23, 2016

seisman closed this as completed Jul 27, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SAC手册网页版任务列表 #102

SAC手册网页版任务列表 #102

seisman commented Jul 23, 2016 •

edited

seisman commented Jul 23, 2016 •

edited

seisman commented Jul 23, 2016 •

edited

SAC手册网页版任务列表 #102

SAC手册网页版任务列表 #102

Comments

seisman commented Jul 23, 2016 • edited

seisman commented Jul 23, 2016 • edited

seisman commented Jul 23, 2016 • edited

seisman commented Jul 23, 2016 •

edited

seisman commented Jul 23, 2016 •

edited

seisman commented Jul 23, 2016 •

edited