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
|
=begin
= NAME
rdswap - a multi-language RD documents support tool
= SYNOPSIS
rdswap [ -h | -v ] filename ...
= DESCRIPTION
This tool is written to support you to write multi-language documents using
the Ruby-Document-Format (RD).
The idea for such a tool was originated by Minero Aoki, how has thought
about, how to make life easier for developers who have to write and
maintain scripts in more than one language.
You have to specify at least two filenames on the command line. One
containing the Ruby script, the second containing a translated RD. If the
script does ((*not*)) end with `.rb', it has to be the first filename mentioned
on the command line! In opposition, all files containing translations
((*must not*)) ending with `.rb'! They should use a extension that describes the
language. So that would give us the following picture:
* sample.rb : Script contains the original documentation.
* sample.jp : Documentation written in Japanese.
* sample.de : Translation to German.
The tool doesn't care about the language extensions. You can name them as
you like! So the file containing the Japanese translation above, could also
be names e.g. `sample.japan' or even `japantranslation.japan'.
For every translation file, a new file will be created. The name is build
from the script filename plus the language extension. So regarding the
example above, following files would be created:
* sample.rb.jp
* sample.rb.de
or, given the alternative translation filename as mentioned above...
* sample.rb.japan
== How does it work?
The contents of all files will be split into source and RD blocks. The
source of the translation files, will be discarded! Every RD block may be
of a certain type. The type will be taken from the contents directly
following the `=begin' on the same line. If there is only a lonely `=begin'
on a line by itself, the type of the block is `nil'. That means in
# File sample.rd
:
=begin
bla bla
=end
:
=begin whatever or not
blub blub
=end
:
the first block would be of type `nil' and the second one of type `whatever
or not'.
Block types are important for the translation. If a source will be generated
from a script and a translation file, only these blocks are taken from the
translation files, that comes in the right sequence ((*and*)) contains the same
type as the block in the script! For example:
# File sample.rb
:
=begin gnark
Some comment
=end
:
=begin
block 2
=end
:
=begin
block 3
=end
:
# File sample.de
:
=begin
Block zwei
=end
:
=begin
Block drei
=end
:
Here, the first block of `sample.rb' will *not* be translated, as there is
no translation block with that type in sample.de! So the first block would
be inserted as-it-is into the translated script. The blocks afterwards,
however, are translated as the block type does match (it is `nil' there).
Attention: In a translation file, a second block will only be used, if a
first one was already used (matched). A third block will only be used, if a
second one was used already!
That means, if the first block of `sample.de' would be of type e.g. `Never
match', then no block would ever be taken to replace anyone of `sample.rb'.
== OPTIONS
: -h
shows this help text.
: -v
shows some more text during processing.
: filename
means a file, that contains RD and/or Ruby code.
== EXAMPLES
rdswap -v sample.rb sample.ja sample.de
rdswap -v sample.ja sample.rb sample.de
rdswap -v sample.ja sample.de sample.rb
rdswap -v sample.??
== AUTHORS
Clemens Hintze <c.hintze@gmx.net>.
=end
|
