自动化文档管理方案

基本思路

1. 使用简单的 t2t 标记进行文档编写
2. 使用 subversion 对这些文档进行版本控制
3. 使用 GNU Make 实现自动化管理
4. 文档编写之后使用 txt2tags 进行文档转换为其它格式(通过调用相应 Makefile target 实现)
5. 使用 mutt/msmtp 自动发送转换后文本到某个邮件列表(相应 make target)
6. 自动同步到在线文档系统？
7. 自动作图？(目前可用 dia)
8. 上传图片？
9. 对项目，自动生成站点层级页面？

目前已实现前面五点，后续功能方案研究中...

我使用的系统环境为

  $ uname
CYGWIN_NT-5.1

所以任何 Linux/UNIX 系统都是合适的。

略去部分

• txt2tags 比较简单，参考官方文档大概 <20min>
• subversion 使用广泛，在此也不赘述

mutt/msmtp

mutt/msmtp 在 Cygwin 似乎不太稳定，但基本可以使用：

  mutt-1.4.2.2-2
msmtp-1.4.13-1

mutt 是 MUA，它需要一个 MTA 来为它发送邮件，默认情况下它会使用 sendmail 或 postfix 的 sendmail 命令，但安装和配置一个 sendmail/postfix 太麻烦了，对于这种小应用不合适，所以使用 msmtp，它是一个轻量级的 MTA。

因为只需要在命令行调用 mutt，所以不需要进行太复杂的设置，编写 mutt 和 msmtp 相应的配置文件如下：

  sh$ cat ~/.mutt/private.muttrc
# SMTP
set sendmail="/usr/bin/msmtp -f someone@gmail.com"

sh$ cat ~/.msmtprc
account private
host smtp.gmail.com
port 587
protocol smtp
auth on
from someone@gmail.com
user someone@gmail.com
password "********"
tls on
tls_starttls on
tls_certcheck off

~/.mutt/private.muttrc 指明了使用 msmtp 及其参数，-f 即 .msmtprc 中的 from 内容，用这个来标识要使用哪个账号来发送邮件，因为我们可能要使用多个账号发不同的邮件，比如对工作的内容要使用另一个账号，这也是为什么没有使用标准的 ~/.muttrc 或 ~/.mutt/muttrc 作为 mutt 配置的原因，下面会将到如何使用其他账号。

可以先尝试一下是否发送会成功：

  sh$ echo "testing mutt..." | mutt -s "Mutt" -F ~/.mutt/private.muttrc $mail_address

到另一个邮箱 $mail_address 看看是否确实收到了邮件。

将工作时使用的邮箱加入 ~/.msmtprc 后如下：

  $ cat ~/.msmtprc
account private
host smtp.gmail.com
port 587
protocol smtp
auth on
from someone@gmail.com
user someone@gmail.com
password "********"
tls on
tls_starttls on
tls_certcheck off

account default
host ssl.alibaba-inc.com
port 465
protocol smtp
auth on
from someone@company.com
user someone
password "********"
tls on
tls_starttls off
tls_certcheck off
# tls_force_sslv3 on

注意公司的邮箱使用 ironport，参数 tls_starttls off 与 gmail 邮箱的不同，为了使用这个设置，需要另一个 mutt 配置文件：

  sh$ cat ~/.mutt/work.muttrc
# Header
my_hdr From: someone@company.com
# SMTP
set sendmail="/usr/bin/msmtp -f someone@company.com"

因为公司账号没有域名后缀，所以发出去的邮件 header 部分将没有域名部分，故在 ~/.mutt/work.muttrc 中增加 my_hdr 让 mutt 帮补上。

可再用前述方法试验一下是否能够正确发送邮件。

Makefile

邮件客户端配置成功后，就可以在文档目录下编写一个 Makefile。此时正确的目录结构很重要，方便我们进行管理：

  docs/
 index.t2t, 用来生成结构化文档
 *.t2t, 生成单独文档到 html/ 和 text/ 下
 html/*.html, 转换后的 html 文件
 text/*.txt, 转换后的 txt文件
 _mail/work, 使用 work 邮箱时的时间戳文件
 _mail/private, 使用私有邮箱时的时间戳文件
 _release, 发布文档列表，只有在这个列表中的文件发生变更后才会发送邮件和进行在线同步
 Makefile -> ../Makefile, 可制成符号链接到父目录 Makefile，这样可以用同一个 Makefile 管理大量分类文档

Makefile 内容如下：

  SA_MAIL := sa@list.company.com

html: *.t2t
 for f in $?; do fn=`echo $$f | awk -F. '{print $$1}'` && txt2tags -t html -o html/$$fn.html $$f; done

txt: *.t2t
 for f in $?; do fn=`echo $$f | awk -F. '{print $$1}'` && txt2tags -t txt -o text/$$fn.txt $$f; done

_mail/work: *.t2t
 for f in $?; do \
  grep $$f _release >/dev/null && \
  ( \
   echo "mail $$f ..."; \
   fn=`echo $$f | awk -F. '{print $$1}'`; \
   title=`sed -n '1p' $$f`; \
   cat text/$$fn.txt | mutt -F ~/.mutt/work.muttrc -s "$$title" -a html/$$fn.html $(SA_MAIL); \
  )  || \
  echo "skip $$f ..."; \
 done
 touch _mail/work

当运行make html或make txt这两个 target 时就会分别在 html/ 或 text/ 下生成转换文档，运行make _mail/work后会用工作邮箱发送邮件到邮件列表 SA_MAIL，邮件内容为生成 txt 内容，附件为生成 html 文件。