README.rd

# 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, 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+