rdtool/README.rd.ja at master · uwabami/rdtool · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# -*- mode: rd; coding: utf-8; indent-tabs-mode: nil -*-
=begin
= RDtool 0.6.39
== RDってなに？

RDはRubyにおけるPOD(Plain Old Documentation)のようなものです。
RDtoolはRDのフォーマッタであり、RDをHTMLなどに変換できます。

== 何が変わった？

HISTORYを見てください。

== インストールの方法

公開された gem を使うなら:

  % gem install rdtool

開発時は:

  % bundle install
  % bundle exec rake test
  % bundle exec rake build

utils/rd-mode.el を使いたいなら、
それらは((*手で*))インストールします。

従来の ((%ruby setup.rb%)) 方式は互換性のために残してあります。

== どうやって使うか。

基本的には、こんな感じ。
  % rd2 rdfile.rd > outputfile

フォーマットライブラリを指定したい時は、こう。
  % rd2 -r library rdfile.rd > outputfile

((% rd2 --help %))でオプションの詳細がでます。

フォーマットライブラリ依存のオプションは先にフォーマットライブラリの
指定をしてから((%--help%))。例えば、

  % rd2 -r rd/rd2html-lib.rb --help

rd2はホームディレクトリにある".rd2rc"というファイルを読み込みます。
これはRubyスクリプトです。

同梱されている主なフォーマットライブラリは次の通りです。

:((%rd/rd2html-lib%))
  XHTML 風の HTML を出力します。主なオプションは
  ((%--with-css=FILE%)), ((%--html-charset=CHARSET%)),
  ((%--html-lang=LANG%)), ((%--html-title=TITLE%)),
  ((%--html-link-rel=REL%)), ((%--html-link-rev=REV%)),
  ((%--output-rbl%)) です。

:((%rd/rd2html-ext-lib%))
  見出し番号などを追加した拡張 HTML を出力します。
  主な追加オプションは ((%--ref-extension%)),
  ((%--headline-title%)), ((%--headline-secno%)),
  ((%--enable-br%)), ((%--native-inline%)),
  ((%--head-element%)) です。

:((%rd/rd2html5-lib%))
  HTML5 を出力します。主なオプションは ((%rd/rd2html-lib%)) と同様で、
  ((%--with-css=FILE%)), ((%--html-charset=CHARSET%)),
  ((%--html-lang=LANG%)), ((%--html-title=TITLE%)) などが使えます。

:((%rd/rd2man-lib%))
  man page を出力します。主なオプションは
  ((%--man-section=SECTION%)) です。

:((%rd/rd2rdo-lib%))
  解析済みの RD tree を Marshal data として出力します。

:((%rd/rd2rmi-lib%))
  参照解決用の method index data を出力します。

例えば HTML を明示的に生成するなら:

  % rd2 -r rd/rd2html-lib rdfile.rd > output.html

HTML5 や man page を生成するなら:

  % rd2 -r rd/rd2html5-lib rdfile.rd > output.html
  % rd2 -r rd/rd2man-lib rdfile.rd > output.1

各 formatter の詳細なオプションを確認するには、例えば:

  % rd2 -r rd/rd2html-ext-lib --help
  % rd2 -r rd/rd2man-lib --help

また、RDtool には ((%rdswap.rb%)) も含まれています。
これは翻訳済みの RD block を Ruby スクリプトへ差し戻すための
ツールです。RD コメントを埋め込んだ 1 つの Ruby スクリプトを保ちつつ、
言語ごとのコピーを生成する用途を想定しています。例えば:

  % rdswap.rb sample.rb sample.ja

これにより、((%sample.rb%)) の Ruby コードを保ったまま、
対応する RD block を ((%sample.ja%)) の内容で置き換えた
((%sample.rb.ja%)) を生成します。

== RDの書き方

doc/rd-draft.rdを読んでください。

== バグ報告

If you find a bug in RDtool, please add new
((<"issues at gihtub"|URL:https://github.com/uwabami/rdtool/issues>)),
or E-mail me ((<URL:mailto:uwabami@gfd-dennou.org>)).


バグを見付けた時は、
((<"github の issues"|URL:https://github.com/uwabami/rdtool/issues>))
に報告するか、
次のアドレスまでメールを下さると幸いです:
((<URL:mailto:uwabami@gfd-dennou.org>))

== ライセンス

RDtoolはRuby's LicenseかGPL-2+の下で使用/配布/改造してください。
RDtoolのパッケージにはTosh以外の人が著作権を持つファイルが含まれています。
それらのファイルについての配布条件はファイル自体に書かれたライセンスの下で
行ってください。

ファイル毎のライセンス表記は以下の通りです。

 Files: */
   * Copyright: 2004 MoonWolf <moonwolf@moonwolf.com>
                2011-2012 Youhei SASAKI <uwabami@gfd-dennou.org>
   * License: Ruby's License or GPL-2+
 Files: lib/rd/rd2man-lib.rb
   * Copyright: 2000  WATANABE Hirofumi
                2012 Youhei SASAKI <uwabami@gfd-dennou.org>
   * License: Ruby's License or GPL-2+
 Files: lib/rd/{head-filter,rd2html-ext-lib,rd2html-ext-opt}.rb
   * Copyright: 2003 Rubikitch
   * License: Ruby's License or GPL-2+
 Files: bin/rdswap
   * Copyright: 1999 C.Hintze
   * License: Ruby's License or GPL-2+
 Files: setup.rb
   * Copyright: 2000-2006 Minero Aoki
   * License: LGPL-2.1
 Files: utils/rd-mode.el
   * Copyright: 1999 Koji Arai, Toshiro Kuwabara.
   * License: GPL-2+

=end