From 96ac054392bca821f0d177d6ad3a5aef07a1e45b Mon Sep 17 00:00:00 2001
From: Roipoussiere <roipoussiere@protonmail.com>
Date: Tue, 6 Jun 2023 21:33:32 +0200
Subject: [PATCH] metadata: improve doc

---
 website/src/pages/learn/code.mdx     |  2 +-
 website/src/pages/learn/metadata.mdx | 75 ++++++++++++++++++++++++----
 2 files changed, 67 insertions(+), 10 deletions(-)

diff --git a/website/src/pages/learn/code.mdx b/website/src/pages/learn/code.mdx
index 8551a8a2..5e2b37b4 100644
--- a/website/src/pages/learn/code.mdx
+++ b/website/src/pages/learn/code.mdx
@@ -68,7 +68,7 @@ Try uncommenting this line by deleting `//` and refreshing the pattern.
 You can also use the keyboard shortcut `cmd-/` to toggle comments on and off.
 
 You might noticed that some comments in the REPL samples include some words starting with a "@", like `@title` or `@license`.
-Those are just a convention to define some information about the music. We will talk about it in the _metadata_ section.
+Those are just a convention to define some information about the music. We will talk about it in the [Music metadata](/learn/metadata) section.
 
 # Strings
 
diff --git a/website/src/pages/learn/metadata.mdx b/website/src/pages/learn/metadata.mdx
index 47a19c1e..2f3be348 100644
--- a/website/src/pages/learn/metadata.mdx
+++ b/website/src/pages/learn/metadata.mdx
@@ -8,24 +8,81 @@ import { JsDoc } from '../../docs/JsDoc';
 
 # Music metadata
 
-You can optionally add some music metadata in your Strudel code, by using tags in code comments like this:
+You can optionally add some music metadata in your Strudel code, by using tags in code comments:
 
-```
-// @license: CC BY-NC-SA 4.0 https://creativecommons.org/licenses/by-nc-sa/4.0/
-// @author: Felix Roos
-// @details: Inspired by Friendship - Let's not talk about it (1979) :)
+```js
+// @title Hey Hoo
+// @by Sam Tagada
+// @license CC BY-NC-SA
 ```
 
 Like other comments, those are ignored by Strudel, but it can be used by other tools to retrieve some information about the music.
 
 It is for instance used by the [swatch tool](https://github.com/tidalcycles/strudel/tree/main/my-patterns) to display pattern titles in the [examples page](https://strudel.tidalcycles.org/examples/).
 
+## Alternative syntax
+
+You can also use comment blocks:
+
+```js
+/*
+@title Hey Hoo
+@by Sam Tagada
+@license CC BY-NC-SA
+*/
+```
+
+Or define multiple tags in one line:
+
+```js
+// @title Hey Hoo @by Sam Tagada @license CC BY-NC-SA
+```
+
+## Tags list
+
 Available tags are:
 
 - `@title`: music title
-- `@by`: music author(s), separated with comma, eventually followed with a link in `<>` (ex: `@author john doe <https://example.com>`)
-- `@license`: music license
+- `@by`: music author(s), separated by comma, eventually followed with a link in `<>` (ex: `@by John Doe <https://example.com>`)
+- `@license`: music license(s)
 - `@details`: some additional information about the music
-- `@url`: web page related to the music (git repo, soundcloud link, etc.)
-- `@genre`: music genre (pop, jazz, etc)
+- `@url`: web page(s) related to the music (git repo, soundcloud link, etc.)
+- `@genre`: music genre(s) (pop, jazz, etc)
 - `@album`: music album name
+
+## Multiple values
+
+Some of them accepts several values, using the comma or new line separator, or duplicating the tag:
+
+```js
+/*
+@by Sam Tagada
+    Jimmy
+@genre pop, jazz
+@url https://example.com
+@url https://example.org
+*/
+```
+
+You can also add optinal prefixes and use tags where you want:
+
+```js
+/*
+song @by Sam Tagada
+samples @by Jimmy
+*/
+...
+note("a3 c#4 e4 a4") // @by Sandy
+```
+
+## Multiline
+
+If a tag doesn't accept a list, it can take multi-line values:
+
+```js
+/*
+@details I wrote this song in February 19th, 2023.
+         It was around midnight and I was lying on
+         the sofa in the living room.
+*/
+```