本仓库图书使用CC-BY-NC-ND授权协议。
集体写一本书,这真是一件令人振奋的事情。如果一本不过瘾,那就写两本。
- 《FreeSWITCH案例大全》 fsbook-case-study
- 《FreeSWITCH参考手册》 fsbook-references
源文件使用Markdown格式,排版使用Pandoc和Latex。参见《我在Mac上的写作工具链》以及《技术图书排版》。
关于Markdown格式请参考已有的内容。欢迎大家配置好自己的Pandoc环境,我们推荐使用我们的docker镜像生成PDF,这样可以检查自己的Markdown语法等。但配置不起来也没什么问题。我们会有专人负责格式。
根据自己的来表示,可以生成PDF或HTML来查看转换效果,推荐生成PDF,以下是基本使用方法。
- 生成全书。分别进入每本书的主目录然后执行
make:
cd fsbook-case-stuby
make
cd fsbook-references
make
- 每章生成单个PDF。速度会比生成全书要快。进入书的主目录,然后执行:
make pdfs
- 仅生成单个PDF
make out/chapter2.pdf
- 按照《FreeSWITCH实例解析》的格式来写。
- 有些内容是跟时间和空间有关的,建议在开头注明写作时间和作者,如
2016年10月22日/Seven。
主要内容:
- 模块 (杜金房)
- 通道变量
- API参考
- App参考
一般来说,章命名为chapter-xxx.md,节命名为section-xxx.md,所有章节参见各书Makefile中的SRC部分。
注意排版。
- 使用UNIX换行符,(不要使用Windows记事本编辑,可以使用Notepad++、Sublime或VSCode等)。
- 使用Markdown格式,如果本规范中未规定的,参考已有的内容。
- 正文中使用中文标点。
- 使用
#及##等定义标题,标题后要有空行。 - 章从
#起,节从##起。 - 自己写的章节写上自己的名字,以
>空格开始以便排版,如> Seven Du/2019-08。 - 图片要专门占一行。
- 代码有专门的格式,如
code,代码段:
// this is a comment line in code
// 这是一行注释
代码段必须为如下格式,必须有语言部分以保证语法加亮及自动换行。
```c
int main(int argc, char **argv);
```
或有语法加亮功能的代码段:
/* 这是一段很长很长的代码 */ int a, b c; char *freeswitch;
- 如果代码需要加行号,可以用
nl命令,如,我在Mac上有一个脚本,可以加亮后直接Copy到剪贴板上:
#!bin/bash nl -b a $@ | pbcopy
- 图片、抓屏等,尽量只抓必要的部分。把重要的内容放大后抓取。由于排版限制,尽量使用宽高比大于或等于
2:1的图片(必要情况下可以两侧加白边),在排版中会有较好的效果。如,以下命令可以使用ImageMagic把现有图片两侧加白边(需要先用identify找到图像大小,再把宽度加大:
convert -gravity center -background white -extent 1200x700 autotools.png autotools-2.png
插入图片可参考如下代码片断:
接着在命令控制台上输入以下命令,便会看到一辆小火车开过,如图\ref{fig:cluechoo}: freeswitch> cluechoo 
引用
可以用\label{}和\ref{}引用。在编译时,会自动根据标题内容生成Lable信息,如\label{switch_core_video.c}。但对于中文的标题,自进行一些编译操作。为了获取编码后的标题,可以执行make tex,查看out/*.tex文件中的相关Lable,如《源代码分析》第一章:
\chapter{源代码导读及编译指南}\label{ux6e90ux4ee3ux7801ux5bfcux8bfbux53caux7f16ux8bd1ux6307ux5357}
脚注,示例如下(为防止有人在复制时连句号复制上,脚注中的URL后面可以不用加标点符号)。
下面我们来讲一下FreeSWITCH[^freeswitch]。 [^freeswitch]: 参见<https://freeswitch.org>
在多人写作过程中,可能有一些冲突。为避免不必要的冲突,我们建议使用如下流程:
- 先在群里跟大家讨论要写的内容
- 如果一个内容有多个人同时写,则可以有一个主要负责人,其它人统一由这个负责人协调
- 想象一下这是一个多线程的事情,因此每个人在访问共享资源的时候要先获取一个"锁"。
- 更新WORKING.md以获取锁。
以《源代码分析》为例。在当前版本上开发,如当前版本为5,发布时,更新HISTORY.md,更新header.tex里的发布日期和版次,编译,Commit,并打上Tag,如src5。然后就可以将Makefile中的VER改成6了。
如果在使用过程中发现版本5中的错误需要更新,则基于src5开出一个临时分支,修改,提交,打上Tag src5.1,发布。然后将该分支合并到master分支,并删除临时分支。
- 本仓库是私有的,不要Fork和公开本仓库。
- 所有提交都提交到Master分支上。注意尽量避免冲突。当然,如果不确定,也可以自己创建分支,并提交pr,由杜老师审核。
- 可以直接在 https://git.xswitch.cn 上提交。
- 可以在Windows系统上工作,但要使用UNIX换行符。文件尾部必须有换行符。
- 中文使用UTF-8编码。需要一个称手的编辑器。可以使用Sublime Text之类的编辑器。不要用Windows记事本。
- 每次修改前都先
pull最新的,以减少冲突。为了保持一个清淅的提交历史,建议使用rebase方式更新master,如,修改.git/config:
[branch "master"] remote = origin merge = refs/heads/master rebase = true
生成API命令列表:
gcc -E mod_commands.c | grep ADD_API | sed -e 's/^[^,]*, "//' | sort | pbcopy
生成APP列表:
gcc -E mod_dptools.c | grep ADD_APP | sed -e 's/^[^,]*, "//' | sort | pbcopy
取得所有可能的通道变量:
cd src find . -name "*.c" -exec grep switch_channel_get_variable {} \; | sed -e 's/^.*switch_channel_get_variable[^,]*, *"*\([0-9a-zA-Z_]*\).*$/1円/' | sort | uniq find . -name "*.c" -exec grep switch_channel_get_variable {} \; | sed -e 's/^.*switch_channel_get_variable[^,]*, *"*\([0-9a-zA-Z_]*\).*$/1円/' | sort | uniq > /tmp/a.c
在a.c加入#include <switch_types.h>:
gcc -Iinclude/ -E /tmp/a.c
在Mac上和Windows上安装docker后,可以比较方便的生成PDF。
如果有make,直接执行make docker会
make dockerrun便可以进入Linux环境,然后执行make就可以生成PDF了。
如果在Windows上,也可以使用docker。如拉取docker镜像:
docker pull dujinfang/texlive_pandoc
以下命令将d:\fsbooks目录映射到docker里面的/team目录,并进入bash Shell环境。
docker run --rm -it -v d:\fsbooks:/team dujinfang/texlive_pandoc bash
进入Shell后,就可以按通常的方法执行make了。
Pandoc可将Markdown格式的文件转换成HTML形式(参考/fsbooks/fsbook-case-study/html.bat文件)。
在Windows上成功配置Pandoc后,进入命令行界面。转到/fsbooks/fsbook-case-study/目录下,编辑html.bat文件,并在命令行下运行html.bat,即可生成相应的html文件。
html.bat文件内容如下:
xcopy /y images out\images\ pandoc -o out/fsbook-case-study.html -V book="FreeSWITCH案例大全" -V title="FreeSWITCH案例大全" --template cover.html preface.md chapter1.md chapterx.md postface.md
- 第一条指令为:复制相关图片到生成路径下。(章节中调用的图片和生成的html文件在一个文件夹下,比如都在out/下)
- 第二条指令为:将
.md文件依照cover.html格式转换并输出到out文件夹下,并命名为fsbook-case-study.html。 - 执行
.bat文件如果出现标题文字乱码,主要是编码格式不对,可先用记事本编辑.bat文件,保存时编码选择"ANSI"即可。 --template cover.html后面可以随时添加章节chapterX.md转换
本仓库图书使用CC-BY-NC-ND授权协议。