<?xml version="1.0" encoding="UTF-8"?> <rss
version="2.0"
xmlns:content="http://purl.org/rss/1.0/modules/content/"
xmlns:wfw="http://wellformedweb.org/CommentAPI/"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
xmlns:slash="http://purl.org/rss/1.0/modules/slash/"
><channel><title>群英汇博客 &#187; 文档格式化</title> <atom:link href="http://blog.ossxp.com/category/%e6%8a%80%e6%9c%af%e6%96%87%e7%ab%a0/%e6%96%87%e6%a1%a3%e6%a0%bc%e5%bc%8f%e5%8c%96/feed/" rel="self" type="application/rss+xml" /><link>http://blog.ossxp.com</link> <description></description> <lastBuildDate>Wed, 14 Sep 2011 03:52:03 +0000</lastBuildDate> <generator>http://wordpress.org/?v=2.9.2</generator> <language>en</language> <sy:updatePeriod>hourly</sy:updatePeriod> <sy:updateFrequency>1</sy:updateFrequency> <item><title>reST 输出文档中页眉和页脚的定制</title><link>http://blog.ossxp.com/2010/07/1600/</link> <comments>http://blog.ossxp.com/2010/07/1600/#comments</comments> <pubDate>Wed, 28 Jul 2010 12:39:46 +0000</pubDate> <dc:creator>蒋 鑫</dc:creator> <category><![CDATA[文档格式化]]></category> <category><![CDATA[DocBones]]></category> <category><![CDATA[reST]]></category><guid
isPermaLink="false">http://blog.ossxp.com/?p=1600</guid> <description><![CDATA[群英汇采用 reStructuredText（简称 reST）文本标记语言进行文档维护。在 cuirui 解决了 rst2pdf 对 reST 转换 PDF 的图片缩放问题之后，如何让生成的 PDF 更有表现力，下了一番功夫去研究。页眉和页脚根据转换的格式（HTML，PDF），自动进行选择
PDF 的页眉显示章节标题以及页码，而页脚则显示文档标题和公司名称及相关链接
HTML 的页眉显示文档标题以及到官方文档的链接（公司网站该文档的安装位置），页脚显示网址
文档版本号和文档编译时间由 Debian 软件包配置文件中的 changelog 动态替换PDF页眉、页脚和 HTML 不兼容
软件 rst2pdf 为 reST 添加了许多扩展，例如在页眉或者页脚中使用 “###Page### ”插入页码，但是 python-docutils 中的  rst2html 并不支持。这也难怪，HTML 本身并无页码的概念。
那么一个难题就出现了，在 reST 格式书写的文档中，如何能够让 HTML 和 PDF 输出显示不同的页眉和页脚，难道我们要被迫选择最大公约数？
reST 文本的宏替换实现
实际上，在研究自适应的页眉和页脚实现之前，我们就已经根据需要增加了宏替换的功能。
如果编译的文档文件名为 filename.rst.in，则启动宏替换脚本，将 filename.rst.in 文件替换为 filename.rst。会将其中的 @ENV(NAME)@ 用相应的环境变量进行替换。
例如：模板文件 abc.rst.in：
:版本: &#124;doc_rev&#124;
:日期: &#124;doc_date&#124;.. &#124;doc_rev&#124; replace::  @ENV(DOC_REV)@
.. &#124;doc_date&#124; replace:: @ENV(DOC_DATE)@会根据编译文档时的传参，进行替换。例如用命令：
$ DOC_REV=1.2.5 <a
href="http://blog.ossxp.com/2010/07/1600/" class="more-link">阅读全部内容 &#187;</a>]]></description> <wfw:commentRss>http://blog.ossxp.com/2010/07/1600/feed/</wfw:commentRss> <slash:comments>0</slash:comments> </item> <item><title>在 reST 格式文档中，嵌入 Creative Commons 授权信息</title><link>http://blog.ossxp.com/2010/07/1422/</link> <comments>http://blog.ossxp.com/2010/07/1422/#comments</comments> <pubDate>Fri, 09 Jul 2010 06:23:17 +0000</pubDate> <dc:creator>蒋 鑫</dc:creator> <category><![CDATA[文档格式化]]></category> <category><![CDATA[reST]]></category><guid
isPermaLink="false">http://blog.ossxp.com/?p=1422</guid> <description><![CDATA[群英汇的用户手册文档以 Creative Commons 许可协议发布，但是仅仅在文档中用两个单词“Creative Commons”进行标识是不够的，因为：Creative Commons 不是一个，而是一组（六个）License 组成的许可协议家族
要在网站上的许可协议上，建立链接。链接到 creativecommons.org 网站上对应许可协议只有在页面中建立到 creativecommons.org 的链接，才能被搜索引擎识别出网页/资源对应的许可协议
只有建立链接后，也才可能让您的共享资源，在 Search@CC 上搜索到如何使用 reStructuredText 格式（简称 reST）编写的文档中嵌入 CC 许可证链接呢？我们公司的很多文档都是用 reST 格式维护的。
为了在 reST 格式的文档中嵌入 CC 许可证，我们尝试了不同的方法：
选择适合的许可协议
Creative Commons 提供一个许可协议选择网页，通过页面表单很容易的选定最终许可协议，并能够给出页面嵌入的代码。
例如获取到的代码：
&#60;a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"&#62;
&#60;img alt="知识共享许可协议" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /&#62;&#60;/a&#62;&#60;br /&#62;
本作品由&#60;a xmlns:cc="http://creativecommons.org/ns#" href="http://www.ossxp.com/" property="cc:attributionName" rel="cc:attributionURL"&#62;
北京群英汇信息技术有限公司&#60;/a&#62;创作，采用&#60;a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"&#62;
知识共享署名-相同方式共享 3.0 Unported许可协议&#60;/a&#62;进行许可。
显示在页面中为：本作品由北京群英汇信息技术有限公司创作，采用知识共享署名-相同方式共享 3.0 Unported许可协议进行许可。
上述代码中，我们最感兴趣和有用的，最主要的是那个漂亮的图片以及图片指向 Creative Commons 许可协议的链接。
方法一：使用 raw html，直接使用 Creative Commons给出的链接
最直接的想法，就是把上面获取到的 HMTL 源代码直接加入 reST 格式文档中。
文档头部包含和授权信息相关内容，示例如下：
================
单点登录用户手册
================.. <a
href="http://blog.ossxp.com/2010/07/1422/" class="more-link">阅读全部内容 &#187;</a>]]></description> <wfw:commentRss>http://blog.ossxp.com/2010/07/1422/feed/</wfw:commentRss> <slash:comments>0</slash:comments> </item> <item><title>能否突破 reST 表格语法的局限</title><link>http://blog.ossxp.com/2010/01/153/</link> <comments>http://blog.ossxp.com/2010/01/153/#comments</comments> <pubDate>Mon, 11 Jan 2010 10:29:45 +0000</pubDate> <dc:creator>蒋 鑫</dc:creator> <category><![CDATA[文档格式化]]></category> <category><![CDATA[reST]]></category><guid
isPermaLink="false">http://blog.ossxp.com/?p=153</guid> <description><![CDATA[reST 表格的局限
reST, reStructuredText 是也。今天写了一条博文：《团队致胜之道——群英汇的解决方案》。其中博文最后嵌入的表格，是用 reST 写的，然后用 DocBones 转换为 HTML。但是只能将表格的第一行设置为 Table Header，想同时将第一列也设置为表头格式，没有成功。利用 reST 目前对表格的支持，写成如下的 reST 文本：+-----------+--------------------+-----------------------------------------+
&#124;           &#124; 个人               &#124; 团队/组织         <a
href="http://blog.ossxp.com/2010/01/153/" class="more-link">阅读全部内容 &#187;</a>]]></description> <wfw:commentRss>http://blog.ossxp.com/2010/01/153/feed/</wfw:commentRss> <slash:comments>0</slash:comments> </item> <item><title>reST编号列表的语法注意事项</title><link>http://blog.ossxp.com/2010/01/134/</link> <comments>http://blog.ossxp.com/2010/01/134/#comments</comments> <pubDate>Sun, 10 Jan 2010 03:50:06 +0000</pubDate> <dc:creator>蒋 鑫</dc:creator> <category><![CDATA[技术文章]]></category> <category><![CDATA[文档格式化]]></category> <category><![CDATA[reST]]></category><guid
isPermaLink="false">http://blog.ossxp.com/?p=134</guid> <description><![CDATA[昨天用 DocBones 工具创建了一个新文档 Subversion ChangeLog，并将部分内容贴在这里，即博文：Subversion 1.6 修改记录。即先用 reST 格式写文档，然后转换为 HTML，再将转换后的 HTML 粘贴在博客中。
本来准备在每个章节内，首先是编号列表，编号列表内是符号列表，但是出现了下面的问题：#. 列表1
* 子列表
* 子列表
#. 列表2
#. 列表3
期待的输出结果是：列表1子列表
子列表列表2 （编号续前，应该为2）
列表3结果却显示为：列表1子列表
子列表列表2（编号重新开始了！显示为1）
列表3最后求助于崔锐，今天上午得到答案。原来是缩进不够，导致的问题。即编号列表下再创建bullet list（符号列表），符号列表的起始应该在编号列表文件之后。即，正确的 reST 写法应该是：
#. 列表1
* 子列表 （星号和上一级编号列表的文字对齐，或者往下缩进，即可）
* 子列表
#. 列表2
#. 列表3
]]></description> <wfw:commentRss>http://blog.ossxp.com/2010/01/134/feed/</wfw:commentRss> <slash:comments>0</slash:comments> </item> </channel> </rss>
<!-- Performance optimized by W3 Total Cache. Learn more: http://www.w3-edge.com/wordpress-plugins/

Minified using disk
Page Caching using disk (user agent is rejected)
Database Caching 8/14 queries in 0.393 seconds using disk

Served from: blog.ossxp.com @ 2012-02-11 06:26:07 -->
