RDSWAP(1)

💖 NAME 💖

okay bestie, say hi to rdswap — it's a multi-language RD documents support tool ✨ like, a whole little helper for writing docs in more than one language at once. no cap.

---

🌸 SYNOPSIS 🌸

rdswap [ -h | -v ] filename ...

---

🦋 DESCRIPTION 🦋

So the whole point of this tool is to support you while you write multi-language documents using the Ruby-Document-Format (aka RD). 🎀

The idea for a tool like this came from Minero Aoki, who was literally thinking about how to make life easier for developers who have to write and maintain scripts in more than one language. king behavior, fr fr. 👑

Here's the vibe check on how you run it: you have to give at least two filenames on the command line. One of them contains the Ruby script, and the second one contains a translated RD. 📝

• if the script does not end with .rb, then it has to be the first filename you mention on the command line! (first in line or it doesn't count 💅)
• on the flip side, every file containing translations must not end with .rb! nope. they should use an extension that describes the language. sooo that gives us this whole picture:
• sample.rb : the script that contains the original documentation.
• sample.jp : documentation written in Japanese.
• sample.de : the translation to German.

And here's the gag: the tool genuinely doesn't care about the language extensions. you can name them literally whatever you want! so that Japanese translation file up there could also be named, like, sample.japan or even japantranslation.japan. the name is yours, go off. 🙈

For every translation file, a new file gets created. the name is built from the script filename plus the language extension. so taking the example from above, you'd end up with:

• sample.rb.jp
• sample.rb.de

or, if you went with that alternative translation filename mentioned earlier…

• sample.rb.japan

---

✨ How does it work? ✨

The contents of all the files get split into source blocks and RD blocks. and whenever a file is a translation file, its source gets discarded! bye 👋 straight in the bin, not sorry.

Every RD block may be of a certain type. that type is taken from the contents directly following the =begin on the same line. but if there's just a lonely little =begin sitting on a line all by itself, then the type of that block is nil. so like, in here:

# 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 would be of type whatever or not. slay.

Block types are so important for the translation, bestie, like genuinely the main character of this whole thing. 🫶 If a source is being generated from a script and a translation file, then only those blocks get taken from the translation files that come in the right sequence and contain 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
:

So here, the first block of sample.rb will *not* be translated, because there's no translation block with that type in sample.de! which means that first block just gets inserted as-it-is into the translated script. untouched. iconic. ✨ The blocks afterwards, though? those do get translated, because the block type matches (it's nil there). 🎯

⚠️ Attention: in a translation file, a second block will only ever be used if a first one was already used (matched). and a third block will only be used if a second one was used already! it's a strict little queue, no skipping allowed. 💀

Which means: if the first block of sample.de were of type, say, Never match, then no block would ever be taken to replace any of sample.rb. rip. 😭

---

🌈 OPTIONS 🌈

• -h — shows this help text. cute, right? 💖
• -v — shows some more text during processing. she's chatty and we love that. 🗣️
• 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.??

look at those little wildcards go. so versatile. ✨

---

👑 AUTHORS 👑

Clemens Hintze <c.hintze@gmx.net>. thank you for your service, we are obsessed. 🫶

---

and that's the whole page, babes — this was from the RDSWAP(1) manual, General Commands Manual, dated May 2026, version RDSWAP(1). go translate something gorgeous. 💅🎀🦋