Swim::Design(3)

💖 Swim::Design 💖

ok so bestie, welcome to the Swim::Design page — it lives in section 3 of the User Contributed Perl Documentation, and it's basically the vibe manifesto for the Swim markup format. This is where we spill the goals and the design decisions, no cap. 🫶

This document describes the Swim markup format, its goals and its specific design decisions. ✨

---

🌈 Swim Goals 🌈

okay so here's the whole dream, laid out:

• Beautiful input syntax and beautiful output renderings 💅
• (re)Use the best existing markup syntaxes
• Render to many formats
  • HTML
  • Plain text
  • Other common text markups (Markdown, Pod, etc)
• Core info model supports most common, useful constructs
• Support everything else via pluggable extension syntax 🔥

---

🦋 The Swim Informational Model 🦋

So Swim defines an information model for text documents, and the 2 main generic components are blocks and phrases. It's giving very much the HTML concepts of divs and spans, fr fr.

The model is roughly expressed by this grammar:

# A document is a set of blocks
document: block*
# A block is /either/ a set of more blocks /or/ a set of phrases
block: block* | phrase*
# A phrase is moer or less a sentence fragement
phrase: bold | italic | link | … | plain-text

And Swim is literally defined by this grammar:

# A document is a set of blocks
document: block*
# A block is /either/ a set of more blocks /or/ a set of phrases
block: block* | phrase*
# A phrase is moer or less a sentence fragement
phrase: bold | italic | link | … | plain-text

🎀 yes queen, that's the actual grammar, typos and all, and we are not touching it — it's iconic, periodt.

---

and that's the whole page bestie!! 🧚 this lil masterpiece is from perl v5.42.0, dated 2025-07-25, and it's Swim::Design(3) in the User Contributed Perl Documentation — slay, mwah, bye!! 💖🌸🦋👑