RD is Ruby's POD, embedable documentation format in script file.
RD is influenced mainly from plain2, a program to translate from plain text to some mark-up language. So, RD looks like plain text, and its simpleness and neatness make it easy to read and write.
Ruby's interpreter, ruby
, simply ignores texts between a line beginning
with "=begin
" and one beginning with "=end
". So, not only RD is
embeddable. You can write anything between =begin
and =end
. RD is
one of them, but RD will be a standard one.*1
We will use a term "Element" for features of RD which add information of document structure to text. In addition, we use a term "Block" for Elements for large and global structures, and a term "Inline" for ones for small and local decorations.
Paragraph, headline or list is a Block. RD use indent and special characters to describe Blocks. You can also write complicated structure to nest Blocks. And this style of Block looks naturally like plain text format. See Block for more details.
Emphasis, code or reference is an Inline. Parentheses and special characters, like ((? ... ?)), are used for Inline. Almost all Inline can nest each other. See Inline for more details.
Block has line oriented syntax. i.e. each character of same line belong to a same Block. And indent of line represent nesting level and type of Block. First character of line represent type of Block.
Baseline is standard depth of indent. relative depth between indent of one line and Baseline affects type of its Block.
Head Char is first character of line, but except white spaces.
STRINGLINE is line which consists of strings.
STRINGLINE doesn't have "*
", "(num)
", ":
", "=
"
nor "+
" as Head Char. But if line is indented, "=
" and "+
"
can be Head Char.
WHITELINE is a line consists of white spaces, "\s
", "\t
" and
"\n
".
A line which is matched with /^#/
is regarded as comment.
In top level, Baseline is at left end, indent 0. In List, Baseline is defined by first Block of ListItem. For example,
Example: "|" means Baseline |Regard this line as one of TextBlock's in top level. |<- So this Baseline is at left most. *|it is in List. (1) |<- this Baseline is defined by (1) line. * |Differnt Item of List can have different Baseline inside. |<- So this Baseline differ from one of first item's.
|Regard this line as one of TextBlock's in top level. |<- So this Baseline is at left most.
If one Block is nested in other Block, Baseline of inside Blocks is deeper than Baseline of outside Blocks.
Relative position bitween Baseline and indent affect on type of Block. If a STRINGLINE has same indent with Baseline, it belongs to TextBlock, otherwise, i.e. it has deeper indent than Baseline, it belongs to Verbatim.
Headline consists of a line which Head Char is "=
" or
"+
". And Headline can't include more than one line. Headline can
be on only top level.
Example: |<- Regard this as top level Baseline. = Headline 1. === Headline 1.1.1. + Headline 1.1.1.1.1.
Headline Mark represents level of Headline. See following figure. fisrt Mark is biggest one, and last Mark os smallest one.
Fig: Headline Marks = == === ==== + ++
Text which follows Mark is title of Headline. It is also used as Label of Reference.
Title of Headline can contain Inlines except for Reference and Footnote.
Include is a line that line head "<<<
" and included file name.
You can input from other file text, both RD and target format, with Include.
When you include RD file, included file name have to have ".rd" or ".rb" as
suffix, like "foo.rd", and write full name (not full path) of file after
"<<<
". For example,
<<< foo.rd
When you include target format file, include file name have to have suffix
of target format standard one, for example ".html" in the case of outputting
HTML, ".texi" in the case of outputting Texinfo, and write base name of file
after "<<<
". For example,
<<< foo
RD formatter include "foo.html" to output HTML, and include "foo.texi" to output Texinfo. If you want to use Include for target format, you should prepare plural type of included file.
TextBlock is composed of STRINGLINEs, but the STRINGLINEs must have same indent with Baseline. If its indent is deeper than Baseline, the STRINGLINE belongs to Verbatim.
TextBlock can include Inline inside.
Example: | This is TextBlock. Second line of same TextBlock. This line is not TextBlock, but Verbatim. * And this line is List. (But this line is exactly TextBlock in ListItem.)
And this example is formatted such like:
This is TextBlock. Second line of same TextBlock.
This line is not TextBlock, but Verbatim.
You can use Verbatim to cite Ruby script. Verbatim is composed of
STRINGLINEs, and they must be indented deeper than
Baseline. Verbatim can also include a line whose Head Char is
"*
", "(1)
" and ":
", But it can't be first line of
Verbatim, it is regarded as List. Verbatim can't include a line
which is indented shallower than first line. Verbatim can include
WHITELINE.
You can't use Inline in Verbatim.
Example: This is Verbatim. Even if a line is indented deeper than first line, it is also in same Verbatim. * A line seems like list is also included in Verbatim. But if the line is indented shallower, it is not in same Verbatim. It is in other Verbatim.
And this example is formatted such like:
This is Verbatim. Even if a line is indented deeper than first line, it is also in same Verbatim. * A line seems like list is also included in Verbatim.
But if the line is indented shallower, it is not in same Verbatim. It is in other Verbatim.
List is special Block. List is composed of ListItems, and ListItem is composed of Blocks. So List can include Blocks inside, even also List itself.*2
ListItem can include WHITELINE, and TextBlock can't include WHITELINE, so when you want to write 2 TextBlock inside ListItem, put a WHITELINE between TextBlocks.
There is 3 type of List, "ItemList", "EnumList", "DescList" and "MethodList.
ItemList is simple and not numbered List. ItemListItem begins by a line
whose Head Char is "*
", and first Block of ItemListItem must be
TextBlock.
Example: * first item of parent list * first item of sub list * second item of sub list text block ( line of first item of parent list)
And this example is formatted such like:
first item of parent list
text block ( line of first item of parent list)
EnumList is numbered List. EnumListItem starts with a line whose
Head Char is "(num)
"(num is integer). EnumList
is same as ItemList on other points.
Example: (1) first line of parent list * first line of sub list(ItemList) (2) second list of parent list (10) number is ignored...
And this example is formatted such like:
first line of parent list
DescList is List for descriptions. DescListItem has 2 part. One is Term part, the other is Description part. Term of DescListItem is also used as Label for Reference.
Term part is composed of a line whose Head Char is ":
",
and Term part is same as Headline, except that a line of Term
part can be indented.
Description part is starts with next line of Term part. Baseline of Description part must be deeper than term of Term part of its pair. For example, following style is illegal.
Example: : |Term |Description.
Description part can include Blocks. List can be first Block of Description part. Term part can contain Inlines except for Reference and Footnote.
Example: :Term first line of Description second line of Description :Term2 * also include List * ...
And this example is formatted such like:
first line of definition. second line of definition
MethodList is the special type of DescList for explanation methods of your classes. MethodList is similar with DescList in almost all part, but it is labeled differently. RD formatters know it is some kind of program code, e.g. method or constants of class in Ruby or function prototype in C..., which is on Term part of MethodList. So, MethodList is labeled without the part which seems to be parameters of methods. See Label and Reference for more detail.
Each item of MethodList has Term part and Description part like
DescList. And its Term part start with its Head Char,
"---
". Its Description part can contain TextBlock,
Verbatim and List. But you shouldn't write MethodList
in any kind of List. RD will come to deny it possibly in
future.
Example: --- Array#each {|i| ... } # => labeled as "Array#each" yield block for each item. --- Array#index(val) # => labeled as "Array#index" return index of first item which equals with ((|val|)). if it hasn't same item, return (({nil})).
And this example is formatted such like:
Array#each {|i| ... }
yield block for each item.
Array#index(val)
return index of first item which equals with val. if it hasn't
same item, return nil
.
Some formatter assumes it is Ruby's methods, constants or etc. which is in Term part of MethodList. it can format term part of MethodList intelligently, but you have to write according as specific formula to make the best of its feature.
Standard Ruby class reference formula is suggested such like:
instance method method of class Class
Class#method(its params ...) { parameter block }
class method method of class Class
Class.method(its params ...) { parameter block }
constant Const of class Class
Class::Const
function func
function#func(its params ...) { parameter block }
Ruby use some symbol characters (e.g. [], []=, +, - or <<) for the names of methods. ruby, Ruby interpreter, parses them with different manner from normal methods, but write them as same as others in this formula.
Example: --- Array#[](key) return value which in at index ((|key|)). --- Array#[]=(key, value) put ((|value|)) into cell of index ((|key|)). --- Array#+(other) return concatenated (({Array})).
You can use Inline in TextBlock, Headline and Term part of DescList. Common style of parentheses is used for Inline. Inline can nest each other.
in following list of Inlines, preformatted text is on left hand side and postformatted text is on right hand side.
Emphasis.
while gets...
Code.
Var.*3
Keyboard.
Term of Index.
Link, Reference. See Label and Reference for more detail.
Footnote.
Inline Verbatim.
Reference needs Label. In RD, only title of Headline and Term of DescList and MethodList is regarded as Label. So, you must choose different titles for different Headlines. This problem has not resolved yet.
Title of Headline and Term part of DescList and MethodList are regarded as Label. But they can contain Inlines, so the situation isn't so simple.
First, MethodList is special in the part of Labeling. Term part of MethodList can't contain Inlines, and RD assumes it is method reference or such thing which is in Term part of MethodList. So it is Labeled under following rules.
(
" or
"{
".*5
Following example will help you to understand how this rule works. the Label
which is generated from the term part of MethodList is after mark of
"# =>
".
Example: --- Array.new([size[, val]]) # => Array.new --- Array#[]=(key, val) # => Array#[]= --- Array#each { ... } # => Array#each --- void rb_define_method(VALUE class, ...) # => void rb_define_method
Second, in the case of title of Headline or term part of DescList, there is not such a special rule. But you can use Inlines for text on them, so there are rules to strip Inline mark-ups from text.
Any Inline mark-ups makes any difference to Label. So, both
= ((*Headline*))
and
= Headline
are Labeled as "Headline".
But white spaces which is after open parenthesis and before close parenthesis of Inline are striped when RD generates Label from it. So, both
= ((* Headline *))
and
= ((*Headline*))
are Labeled as "Headline".
You can refer Labeled element with Reference which is a kind of Inline marked up with ((<...>)).
Most simple use of Reference is to write Label inside parenthesis.
((<Label>))
This works as reference to Label of "Label" and text "Label" is used also for display such like: Label.*6
When you want to refer a resource pointed with URL, write such like:
((<URL:www.ruby-lang.org/en/raa.html>))
RD formatter will format it as hyper-link to its URL if possible such like:<URL:http://www.ruby-lang.org/en/raa.html>.
When you want to use other text than Label for display, write such like:
((<Text for display|Label>))
"Text for display" is used for display and "Label" is used as Label to refer such like: Text for display
Text for display can contain some Inline, except for Footnotes and Reference, and when you want to write "|" inside it, you should write such like:
((<Bar (('|')) inside display text|Label>))
Bar | inside display text
Of course, you can use display text part for Reference to URL resource.
((<Ruby Application Archive|URL:http://www.ruby-lang.org/en/raa.html>))
When display text part is omitted, you can use Inline for Label.
((<((*Label*))>))
Label
We are discussing now about some topic of RD. Some of then is like followings.
Please join our discussion in ruby-list and ruby-talk ML. Get more information at <URL:http://www.ruby-lang.org/en/ml.html> in English, and <URL:http://www.ruby-lang.org/ja/ml.html> in Japanese.
*1 If you are interested in others,
see rubyapi2
<URL:http://www.ueda.info.waseda.ac.jp/~igarashi/ruby/xml.html#rubyapi2>
for example.
*2 But List can't include Headline
nor Include.
*3 You can read very good explanation about Var in texinfo.info.
*4Footnote
*5 text inside "(...)
" is regarded as parameters
of method, and text inside "{...}
" is regarded as parameter
block of methods.
*6 There is no element Labeled
"Label", so it doesn't seems to be Reference probably.