Doczen用户指南

Doczen是神马东西

Doczen的中文名字为：文档之禅 (doc是文档，zen是禅)。 它是为t2t增加了链接的文档生成系统。

目前所支持的文档转换类型

格式	需要安装的软件
html	无
t2t	txt2tags
txt	txt2tags
tex	txt2tags
pdf	xelatex

Doczen的作者 ShopEx 王磊(flaboy) 现在Doczen由chenxiaoxiao维护, 如有问题RTX找chenxiaoxiao或发邮件chenxiaoxiao@shopex.cn

获取方式

微盘 点击下载

svn形式获取

• doczen for all

  https://svn.dev.shopex.cn/ecos-edu/doczen/trunk
  

• doczen for ued

  https://svn.dev.shopex.cn/ecos-edu/doczen/branches/ued/doczen-ued
  

文档相关

• 《基于ECOS的ECStore开发配置指南》

  https://svn.dev.shopex.cn/docs/ecos/ecosdoc
  

环境配置

window

1. 安装php, 并将php可执行文件放在系统环境变量（PATH）中
2. 下载linux命令工具 UnxUtils, 解压之后把目录中的 usr/local/wbin 目录的绝对路径添加到系统环境变量（PATH）的最前面

测试

进入doczen目录输入

doczen.bat

显示如下所示表示配置成功

Usage: ========================================
        doczen make-doc:
            生成t2t格式

        doczen make-tex:
            生成tex格式

        doczen make-txt:
            生成txt格式

        doczen make-pdf:
            生成pdf格式

        doczen init:
            初始化文档

linux

注意权限问题

以ubuntu为例

1. 安装配置php环境

   sudo apt-get install php5 php5-cgi php5-cli
   

测试

进入doczen目录输入

./doczen

显示如下所示表示配置成功

Usage: ========================================
        doczen make-doc:
            生成t2t格式

        doczen make-tex:
            生成tex格式

        doczen make-txt:
            生成txt格式

        doczen make-pdf:
            生成pdf格式

        doczen init:
            初始化文档

使用手册

重要

需要掌握txt2tags; 语法简单, 轻松上手。

txt2tags

• 中文文档
• 用户指南

建立文档

• 主要分为四个步骤
  1. 创建你的文档目录
  2. 编写文档(t2t格式)
  3. 使用 doczen 编译

以后每次改动文档文件, 只需要在文档主目录make一下就好了。清除命令是make clean

第一步

创建文档目录

doczen目录树如下:

|~mydoc/
| |+build/
| |~site/
| | `-index.html
| |~source/
| | |~_static/
| | | |-basic.css
| | | |-default.css
| | | `-pygments.css
| | |~_template/
| | | `-default.tpl
| | `-doc.t2t
| |-config.mk
| `-Makefile

目录结构介绍

• mydoc
  • 文档目录名称
• build
  • Doczen编译之后自动生成, html文档目录
• site
  • index.html 设置文档首页

    <script>
        window.location="doc.html";
    </script>
    

• source
  • t2t文档目录, 我们把编写的文档文件都存放在这里。文档文件为t2t格式, 当我们编写的文档完成之后由 doczen 统一编译为最终的格式。
  • source 里面的 _static 和 _template 目录主要是针对编译之后生成 html 类型文档的外观设置
    • _static : 文档的 css 样式
    • _template : 文档的 html 模板
• config.mk

  DOCZEN   = /host/icore/data/svn/doczen/doczen # Doczen 可执行文件路径
  DOC_PATH = /host/icore/data/svn/mydoc         # 文档目录
  PHP_CMD  = php                                # 需要 php 环境, 此处可以直接跟php可执行文件的全路径
  

• Makefile

  include config.mk
  all: html
      @echo done
  html:
      ${DOCZEN} make-html doc.t2t
  doc:
  	${DOCZEN} make-doc doc.t2t
  txt:
  	make doc
  	txt2tags -t txt ${DOC_PATH}/build/doc/doc.t2t
  tex:
  	make doc
  	txt2tags -t tex --toc --enum-title --encoding=utf8 --style=fontspec,xunicode,xltxtra,shopex ${DOC_PATH}/build/doc/doc.t2t
  	sed -i -e 's@phics{@phics\[scale=0.6\]{${DOC_PATH}/build/doc/@g' ${DOC_PATH}/build/doc/doc.tex
  	sed -i -e 's/section\*/section/g' ${DOC_PATH}/build/doc/doc.tex
  pdf:
  	make tex
  	mkdir ${DOC_PATH}/build/pdf
  	cd ${DOC_PATH}/build/pdf; xelatex ${DOC_PATH}/build/doc/doc.tex; xelatex ${DOC_PATH}/build/doc/doc.tex
  clean:
      rm -rf build
  

第二步

新建第一个文档

进入工作路径

/mydoc/source/

新建文件 doc.t2t

我的文档
ShopEx
Wed Aug 31 18:32:59

Hi! This is my test document.

注: doc.t2t 这个文件通常是用来关联所有单个 t2t 文档。

第三步

doczen 编译

终端或者cmd进入文档主目录, 输入'make'

cd mydoc/
make html

用浏览器打开文档首页

build/html/doc.html

链接文档

doczen 会把所有单个 t2t 文档关联到一起。

关联文件通常使用 source下的 doc.t2t

语法:

%!link your_name.t2t max-depth=n

假如 source 中的目录结构是这样的

  | | | |~source/
  | | | | |~test2/
  | | | | | |-append-a.t2t
  | | | | | |-append-b.t2t
  | | | | | `-index.t2t
  | | | | |-doc.t2t
  | | | | `-test1.t2t

这里 doc.t2t 中的内容如下:

我的文档
ShopEx
Wed Aug 31 17:29:07

%!link test1.t2t max-depth=1
%!link test2/index.t2t max-depth=2

注:

1. 在 doc.t2t 中链接文档 test1.t2t , 层级显示级别为1级
2. 在 doc.t2t 中链接文档 test2 目录中的 index.t2t , 层级显示级别为2级

source/test2/index.t2t 中的内容如下:

test2


%!link *.t2t max-depth=2