README.rd

# -*- mode: rd; coding: utf-8; indent-tabs-mode: nil -*-
=begin
= RDtool 0.6.39
== What is RDtool

RD is Ruby's POD. RDtool is formatter for RD.

== What is Changed

See HISTORY.

== How to Install

Install the released gem:

  % gem install rdtool

For development:

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

If you want to use utils/rd-mode.el, install it ((*by hand*)).

The legacy ((%ruby setup.rb%)) flow is kept only for compatibility.

== How to use

Simply,
  % rd2 rdfile.rd > outputfile

If you want to indicate format-library, do
  % rd2 -r library rdfile.rd > outputfile

Use ((% rd2 --help %)) for more options.

For options depend on format-library, enter ((%--help%)) after
the indication of format-library. For example,

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

rd2 load "${HOME}/.rd2rc" when it runs.

Bundled format libraries include:

:((%rd/rd2html-lib%))
  XHTML-style HTML output. Main options include ((%--with-css=FILE%)),
  ((%--html-charset=CHARSET%)), ((%--html-lang=LANG%)),
  ((%--html-title=TITLE%)), ((%--html-link-rel=REL%)),
  ((%--html-link-rev=REV%)), and ((%--output-rbl%)).

:((%rd/rd2html-ext-lib%))
  Extended HTML output with headline numbering and related features.
  Main additional options include ((%--ref-extension%)),
  ((%--headline-title%)), ((%--headline-secno%)),
  ((%--enable-br%)), ((%--native-inline%)), and ((%--head-element%)).

:((%rd/rd2html5-lib%))
  HTML5 output. It accepts the same main options as ((%rd/rd2html-lib%)),
  such as ((%--with-css=FILE%)), ((%--html-charset=CHARSET%)),
  ((%--html-lang=LANG%)), and ((%--html-title=TITLE%)).

:((%rd/rd2man-lib%))
  man page output. The main option is ((%--man-section=SECTION%)).

:((%rd/rd2rdo-lib%))
  Dumps the parsed RD tree as Marshal data.

:((%rd/rd2rmi-lib%))
  Outputs method index data for reference lookup.

For example, to generate HTML explicitly:

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

To generate HTML5 or a man page:

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

To check detailed options for a specific formatter, run:

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

RDtool also includes ((%rdswap.rb%)), which merges translated RD blocks
back into a Ruby script. This is intended for maintaining one source
script with embedded RD comments and generating language-specific copies.
For example:

  % rdswap.rb sample.rb sample.ja

This generates ((%sample.rb.ja%)) while keeping Ruby code from
((%sample.rb%)) and replacing matching RD blocks with translated ones
from ((%sample.ja%)).

== How to write RD?

Please read doc/rd-draft.rd.

== About bug report

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>)).

== Copyright and License

You can use/re-distribute/change RDtool under Ruby's License or GPL-2+.
see LICNESE.txt and COPYING.txt. This distribution of RDtool include
files that are copyrighted by somebody else, and these files can be
re-distributed under those own license.

These files include the condition of those licenses in themselves. The
license information for every files is as follows.

 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