From afe0aae3d464cce1c9ee2b3d6e044b2f0468e67c Mon Sep 17 00:00:00 2001
From: Erik Schierboom <erik_schierboom@hotmail.com>
Date: Tue, 6 Feb 2024 14:43:18 +0100
Subject: [PATCH] roman-numerals: sync (#789)

* Sync the `roman-numerals` exercise's docs with the latest data.

* Sync the `roman-numerals` exercise's metadata with the latest data.
---
 .../roman-numerals/.docs/instructions.md      | 45 +++-----------
 .../roman-numerals/.docs/introduction.md      | 59 +++++++++++++++++++
 .../practice/roman-numerals/.meta/config.json |  2 +-
 3 files changed, 68 insertions(+), 38 deletions(-)
 create mode 100644 exercises/practice/roman-numerals/.docs/introduction.md

diff --git a/exercises/practice/roman-numerals/.docs/instructions.md b/exercises/practice/roman-numerals/.docs/instructions.md
index 247ea089..50e2f5bf 100644
--- a/exercises/practice/roman-numerals/.docs/instructions.md
+++ b/exercises/practice/roman-numerals/.docs/instructions.md
@@ -1,41 +1,12 @@
-# Instructions
+# Introduction
 
-Write a function to convert from normal numbers to Roman Numerals.
+Your task is to convert a number from Arabic numerals to Roman numerals.
 
-The Romans were a clever bunch.
-They conquered most of Europe and ruled it for hundreds of years.
-They invented concrete and straight roads and even bikinis.
-One thing they never discovered though was the number zero.
-This made writing and dating extensive histories of their exploits slightly more challenging, but the system of numbers they came up with is still in use today.
-For example the BBC uses Roman numerals to date their programs.
+For this exercise, we are only concerned about traditional Roman numerals, in which the largest number is MMMCMXCIX (or 3,999).
 
-The Romans wrote numbers using letters - I, V, X, L, C, D, M.
-(notice these letters have lots of straight lines and are hence easy to hack into stone tablets).
+~~~~exercism/note
+There are lots of different ways to convert between Arabic and Roman numerals.
+We recommend taking a naive approach first to familiarise yourself with the concept of Roman numerals and then search for more efficient methods.
 
-```text
- 1  => I
-10  => X
- 7  => VII
-```
-
-The maximum number supported by this notation is 3,999.
-(The Romans themselves didn't tend to go any higher)
-
-Wikipedia says: Modern Roman numerals ... are written by expressing each digit separately starting with the left most digit and skipping any digit with a value of zero.
-
-To see this in practice, consider the example of 1990.
-
-In Roman numerals 1990 is MCMXC:
-
-1000=M
-900=CM
-90=XC
-
-2008 is written as MMVIII:
-
-2000=MM
-8=VIII
-
-Learn more about [Roman numerals on Wikipedia][roman-numerals].
-
-[roman-numerals]: https://wiki.imperivm-romanvm.com/wiki/Roman_Numerals
+Make sure to check out our Deep Dive video at the end to explore the different approaches you can take!
+~~~~
diff --git a/exercises/practice/roman-numerals/.docs/introduction.md b/exercises/practice/roman-numerals/.docs/introduction.md
new file mode 100644
index 00000000..6fd942fe
--- /dev/null
+++ b/exercises/practice/roman-numerals/.docs/introduction.md
@@ -0,0 +1,59 @@
+# Description
+
+Today, most people in the world use Arabic numerals (0–9).
+But if you travelled back two thousand years, you'd find that most Europeans were using Roman numerals instead.
+
+To write a Roman numeral we use the following Latin letters, each of which has a value:
+
+| M    | D   | C   | L   | X   | V   | I   |
+| ---- | --- | --- | --- | --- | --- | --- |
+| 1000 | 500 | 100 | 50  | 10  | 5   | 1   |
+
+A Roman numeral is a sequence of these letters, and its value is the sum of the letters' values.
+For example, `XVIII` has the value 18 (`10 + 5 + 1 + 1 + 1 = 18`).
+
+There's one rule that makes things trickier though, and that's that **the same letter cannot be used more than three times in succession**.
+That means that we can't express numbers such as 4 with the seemingly natural `IIII`.
+Instead, for those numbers, we use a subtraction method between two letters.
+So we think of `4` not as `1 + 1 + 1 + 1` but instead as `5 - 1`.
+And slightly confusingly to our modern thinking, we write the smaller number first.
+This applies only in the following cases: 4 (`IV`), 9 (`IX`), 40 (`XL`), 90 (`XC`), 400 (`CD`) and 900 (`CM`).
+
+Order matters in Roman numerals!
+Letters (and the special compounds above) must be ordered by decreasing value from left to right.
+
+Here are some examples:
+
+```text
+ 105 => CV
+---- => --
+ 100 => C
++  5 =>  V
+```
+
+```text
+ 106 => CVI
+---- => --
+ 100 => C
++  5 =>  V
++  1 =>   I
+```
+
+```text
+ 104 => CIV
+---- => ---
+ 100 => C
++  4 =>  IV
+```
+
+And a final more complex example:
+
+```text
+ 1996 => MCMXCVI
+----- => -------
+ 1000 => M
++ 900 =>  CM
++  90 =>    XC
++   5 =>      V
++   1 =>       I
+```
diff --git a/exercises/practice/roman-numerals/.meta/config.json b/exercises/practice/roman-numerals/.meta/config.json
index 7dd48517..c5a7728b 100644
--- a/exercises/practice/roman-numerals/.meta/config.json
+++ b/exercises/practice/roman-numerals/.meta/config.json
@@ -16,7 +16,7 @@
       ".meta/example.lisp"
     ]
   },
-  "blurb": "Write a function to convert from normal numbers to Roman Numerals.",
+  "blurb": "Convert modern Arabic numbers into Roman numerals.",
   "source": "The Roman Numeral Kata",
   "source_url": "https://codingdojo.org/kata/RomanNumerals/"
 }