¶ rst2s5

2010-09-18 23:23

1. 缘起

最近讲演频繁:

  1. 100820: IntroPy - Woodpecker Wiki for CPUG
  2. 100826: TDD4Py - Woodpecker Wiki for CPUG
  3. 100918: Software Freedom Day 2010 - SZLUG
  4. ...

    俺在 S5: A Simple Standards-Based Slide Show System 中使用高桥流,幻灯页码轻易超过100! 即使有 Leo 帮助也感觉吃不住, 主要原因是直接写 HTML 太多标签干扰思維了...

    其实早就知道有 rst->s5 的工具:

2. 运用

文档的确不多,中文的就找到上述 Inet6 兄的,但是和谐后,也无法方便的直接咨询

仔细看了哈文档,发现的确不复杂;

之于俺,只是要引用原先的样式,只要:

1
2
3
4
5
6
7
8
9
#   先随便生成个默认工程
rst2s5.py --theme <base-theme> <doc>.txt <doc>.html
#   再复制原先样式过来
ui/<base-theme> to ui/<new-theme>.
#   然后聲明使用新样式就好:
rst2s5.py --theme-url ui/<new-theme> <doc>.txt <doc>.html
 
#   俺在对应目录中的实际命令就是:
python rst2s5-Pygments.py  --current-slide --theme-url=ui/freedom index.rst index.html
  • --current-slide 是要求生成页码的开关参数
  • rst2s5 --help 居然看到有几十种参数,才发现
  • Docutils Front-End Tools 实在是个丰富的工具集!
  • rst2s5-Pygments.py 是定制过的支持 Pygments 语法颜色的 rst2s5 转换脚本!

最后发布时的 s5演示目录分布是:

1
2
3
4
5
6
7
8
9
+-- i                   资源目录(图片什么的...)
|-- index.html          S5
|-- index.rst           rst撰写原文稿
|-- rst2s5-Pygments.py  定制支持 Pygments 语法颜色渲染的s5生成脚本
|-- s5defs.txt          rst2s5引用的 s5 配置文件
`-- ui                  样式入口
    +-- default         默认样式
    `-- freedom         定制样式

2.1. 初步

和S5 幻灯组织是完全对等的撰写:

  • HTML 首页:
    1
    2
    3
    <div class="slide" id="slide0">
    Blalala
    </div>
  • rST首页:
    1
    2
    3
    ==================================================================
    我的工具箱
    ==================================================================
  • HTML幻灯页:
    1
    2
    3
    4
    5
    6
    7
    <div class="slide">
    <h1>标题</h1>
    内容
        <div class="handout">
        隐藏提示
        </div>
    </div>
  • rST幻灯页:
    1
    2
    3
    4
    5
    6
    7
    8
    标题
    =========
     
    .. container:: handout
     
       隐藏提示
     
    内容

唯一注意:

2.2. rst

html->rst 的撰写只有更加 WYTIWYG 很容易习惯;

参考: http://docutils.sourceforge.net/docs/user/rst/quickref.html Quick

主要得习惯的只有:

  1. 标题和 MoinMoin 语法不同使用 ==================独立的标题引用行来聲明第几层的标题
    • 建议顺序是:= - ` : ' " ~ ^ _ * + # < >
    • 一般就用到前4个:
      1
      2
      3
      4
      5
      6
      7
      8
      大标题
      ======
      小标题
      ------
      次标题
      ''''''
      小节标
      """"""
  2. 列表项更加简单可以使用 + 以及 - 相比* 要少按个键 ;-)
  3. 链接更加灵活了:
    • 就地链接: 是也乎,是也乎`显示文字 <http://foo.org>`__ 是也乎
    • 匿名链接:
      1
      2
      3
      是也乎,是也乎`显示文字`__ 是也乎
       
      • 和行内链接聲明最近的独立URL 定义进行自动匹配
    • 全局链接:
      1
      2
      3
      4
      5
      .. _Zoom.Quiet:
       
      ...
      是也乎,是也乎`Zoom.Quiet`_ 是也乎
  4. 就地图片:
    1
    2
    3
    4
    5
    .. image:: pix/Takahashi-method.jpg
        :align: center
        :scale: 150 %
        :alt: 高橋流
    • 这个 target 就是链接! 文档中没有例子,找了半天...
  5. 全局图片:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    .. |Takahashi| image:: pix/Takahashi-method.jpg
        :align: top
        :scale: 150 %
        :alt: 高橋流
     
    ...
     
    任意文字中 |Takahashi| 嵌入图片...
    • align 这时,就是图片和文字流的行内相对位置,而不是图片在整个页面的排版,所以,只能有"top", "middle", "bottom"
    • 其实不用专门记忆,每次渲染时, rst2s5 会进行检查,比如说:
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      $ python rst2s5-Pygments.py  --current-slide --theme-url=ui/freedom index.rst index.html
      index.rst:34: (ERROR/3) Error in "image" directive:
      "center" is not a valid value for the "align" option within a substitution definition. 
      Valid values for "align" are: "top", "middle", "bottom".
      index.rst:34: (WARNING/2) Substitution definition "S5icon" empty or invalid.
       
      .. |S5icon| image:: pix/S5icon.GIF
          :align: center
          :scale: 100 %
          :target: http://www.meyerweb.com/eric/tools/s5/
      index.rst:1284: (ERROR/3) Undefined substitution referenced: "S5icon".

嗯嗯嗯, 使用 rst 进行 s5 撰写,完全是脚本组织的感觉了...连输出时的交互 error 通告都是 Python 味的..

2.3. 定制

比较囧是只有俺习惯并坚持的样式很搞:

默认的样式排版:
  • 和 s5 的默认样式100% 一致!

定制的Freedome样式:
主要的设计:
对应的rst2s5 效果:

对应的设计:
  • A: 表格的作者和版权聲明
    1
    2
    3
    4
    5
    6
    7
    8
    .. footer::
       .. class:: borderless
     
       =============  ====================================
       `Zoom.Quiet`_  |cc-byncsa15|
       -------------  ------------------------------------
       v10.09.16      推荐用 `FireFox`_ 获得最佳游览效果
       =============  ====================================
  • B: 页码/页数 提示
  • C: 当页内容提示
    1
    2
    3
    4
    5
    6
    7
    8
    标题
    =========
     
    .. container:: handout
     
       俺->工具->持续完善 |zqeye|
     
    ...
    • 嗯嗯嗯,当然的得配合CSS:
    • 注释掉默认样式ui/<theme>/s5-core.css 中的
      1
      .handout {display: none;}
    • 在专用CSSui/<theme>/takahashi.css中定制
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      div.handout{
          float: right;
          top:0;
          margin-top: -85px;
          margin-right: -30px;
          font-size: 16px; font-style : italic ;
          color: #385775;
      }
      div.handout a{
          color: #385775;
      }
       
      div.handout a:hover{
          color: orange;
          font-style : bold ;
      }
    • 还得在默认的样式调配文件ui/<theme>/slides.css中引入自个儿定制的:
      1
      2
      3
      4
      5
      @import url(s5-core.css); /* required to make the slide show run at all */
      @import url(framing.css); /* sets basic placement and size of slide components */
      @import url(pretty.css);  /* stuff that makes the slides look better than blah */
      @import url(takahashi.css);  /* stuff that makes the takahashi style slides */
      @import url(rst2s5.css);  /* stuff that support slides gen. by rst2s5 */
  • D: 专用高桥流样式, 在s5专用子聲明文件:s5defs.txt 中追加俺习惯的CSS类名:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    .. Text Sizes
       ==========
     
    .. role:: huge
    .. role:: big
    .. role:: small
    .. role:: tiny
    .. role:: takahashi0
    .. role:: takahashi1
    .. role:: takahashi2
    ...
成果对比:

3. 时间帐单

小结这次迁移的时间消耗

  1. 0.5h 试用 rst2s5
  2. 0.5h 接入样式
  3. 0.5h 重构Leo 模式
  4. 2h 定制基于 rst2s5 的样式
  5. 3h 逐一页面重写
  6. 1h 修订发布

    共计 7.5h
    • 嗯嗯嗯,主要是在重过过程中,反复调整了对应的 CSS 样式...
    • 好在一切可以快速复用到其它幻灯中了...

  • t2t渲染:: 2010-10-09 02:21:37
  • 动力源自::txt2tags

§ 写于: Sat, 18 Sep 2010 | 永久链接;源文: rdf ,rss ,raw | 分类: /utility/py4str/StructuredText §
[MailMe] [Print] Creative Commons License

作品Zoom.Quiet创作,采用知识共享署名-相同方式共享 2.5 中国大陆许可协议进行许可。 基于zoomquiet.org上的作品创作。