4 ms·

Tintin – A soft documentation website generator for Haskell

41 points by NickSeagull 8y ago

YuukiRey 8y ago
I started learning Haskell a few months ago and am currently going through the later chapters of Haskell from first principle. A major hurdle when it comes to libraries like quick check or Trifecta (the topic of the current chapter) is precisely what is alluded to in the readme for Tintin: type signatures are probably totally fine for experts, but for someone still relatively new to programming and especially new to Haskell they are kind of the 2nd step. The first one is just figuring out where to start and what are the typical use cases for the library. Which type signatures should I even be looking at first, what is typically used together,and so forth. If more Haskell libraries had just a bit of soft documentation at least I would be extremely happy about that. It's pretty much my major hurdle when it comes to Haskell. The syntax I not only got used to, but really love now. The concepts that are taught are just complicated. Frankly monads expressed in my primary language, Javascript, are even harder to understand because of all the syntax noise. But the one thing that at least personally consider needlessly complicated is the lack of beginner friendly documentation.
- NickSeagull 8y ago
  Thanks for the comment! I felt like you when I started with Haskell, and I hope Tintin brings more newbie-friendly docs.
- kccqzy 8y ago
  Wow I didn't realize Haskell beginners would learn to use Trifecta. Megaparsec is much more beginner friendly (and expert-friendly too). It has tutorials that guide you gently through the process of writing a parser. See https://markkarpov.com/megaparsec/parsing-simple-imperative-language.html https://markkarpov.com/megaparsec/parsing-simple-imperative-...
Y_Y 8y ago
Haddock documentation tends to be fairly inscrutable at first glance, so I'm in favour of anyone trying to remedy that. On the other hand the Haddock aesthetic and simplicity is awesome, whereas I find the Tintin website nauseating.
- makapuf 8y ago
  Just in case anyone missed it, tintin is a quintessential European comic character and its adventures with his dog milou and his friend captain haddock. See : https://en.m.wikipedia.org/wiki/The_Adventures_of_Tintin https://en.m.wikipedia.org/wiki/The_Adventures_of_Tintin
- andrepd 8y ago
  I'm with you on both counts. I mean, look at those shades of colour on the sidebar to the left: https://theam.github.io/tintin/01-getting-started.html https://theam.github.io/tintin/01-getting-started.html Give me something concise (and designed for desktop: small fonts, small buttons).
- NickSeagull 8y ago
  Fixed contrasts.
kroltan 8y ago
The site theme could use a bunch more contrast. In the docs sidebar, I can literally not read the section names until I hover, and then squint some.
gnl 8y ago
I'd just like to point out, in case OP hasn't already considered it, that TinTin++ is one of the most popular MUD clients (not that MUDs are particularly popular these days).
- vesak 8y ago
  >not that MUDs are particularly popular these days There's no good reason for that though. Shameless plug: http://icesus.org http://icesus.org (we need players :-/)
  - gnl 8y ago
    Probably shouldn't be upvoting this as it doesn't have much to do with the topic, but I will anyway cause you're fighting for a lost art worth saving.
banashark 8y ago
I'm a big fan of fssnip. http://www.fssnip.net/u/title/Pipeline-list-processing http://www.fssnip.net/u/title/Pipeline-list-processing Hover over the lines and you get type information right there. One of the cool features of F# that I wish was present when reading docs in other languages.
- andrepd 8y ago
  Oh wow, that's great!
q3k 8y ago
Fair warning: doesn't work at all with JS disabled or disabled for cross-origin (which is somewhat sad, especially for tech documentation).
- NickSeagull 8y ago
  We are in the process of fixing it, see https://github.com/theam/tintin/issues/7 https://github.com/theam/tintin/issues/7
- NickSeagull 8y ago
  Fixed in the last version

41 points by NickSeagull 8y ago

I started learning Haskell a few months ago and am currently going through the later chapters of Haskell from first principle. A major hurdle when it comes to libraries like quick check or Trifecta (the topic of the current chapter) is precisely what is alluded to in the readme for Tintin: type signatures are probably totally fine for experts, but for someone still relatively new to programming and especially new to Haskell they are kind of the 2nd step. The first one is just figuring out where to start and what are the typical use cases for the library. Which type signatures should I even be looking at first, what is typically used together,and so forth. If more Haskell libraries had just a bit of soft documentation at least I would be extremely happy about that. It's pretty much my major hurdle when it comes to Haskell. The syntax I not only got used to, but really love now. The concepts that are taught are just complicated. Frankly monads expressed in my primary language, Javascript, are even harder to understand because of all the syntax noise. But the one thing that at least personally consider needlessly complicated is the lack of beginner friendly documentation.

NickSeagull 8y ago
Thanks for the comment! I felt like you when I started with Haskell, and I hope Tintin brings more newbie-friendly docs.
kccqzy 8y ago
Wow I didn't realize Haskell beginners would learn to use Trifecta. Megaparsec is much more beginner friendly (and expert-friendly too). It has tutorials that guide you gently through the process of writing a parser. See https://markkarpov.com/megaparsec/parsing-simple-imperative-language.html https://markkarpov.com/megaparsec/parsing-simple-imperative-...

Y_Y 8y ago

Haddock documentation tends to be fairly inscrutable at first glance, so I'm in favour of anyone trying to remedy that. On the other hand the Haddock aesthetic and simplicity is awesome, whereas I find the Tintin website nauseating.

makapuf 8y ago
Just in case anyone missed it, tintin is a quintessential European comic character and its adventures with his dog milou and his friend captain haddock. See : https://en.m.wikipedia.org/wiki/The_Adventures_of_Tintin https://en.m.wikipedia.org/wiki/The_Adventures_of_Tintin
andrepd 8y ago
I'm with you on both counts. I mean, look at those shades of colour on the sidebar to the left: https://theam.github.io/tintin/01-getting-started.html https://theam.github.io/tintin/01-getting-started.html Give me something concise (and designed for desktop: small fonts, small buttons).
NickSeagull 8y ago
Fixed contrasts.

kroltan 8y ago

The site theme could use a bunch more contrast. In the docs sidebar, I can literally not read the section names until I hover, and then squint some.

gnl 8y ago

I'd just like to point out, in case OP hasn't already considered it, that TinTin++ is one of the most popular MUD clients (not that MUDs are particularly popular these days).

vesak 8y ago
>not that MUDs are particularly popular these days There's no good reason for that though. Shameless plug: http://icesus.org http://icesus.org (we need players :-/)
- gnl 8y ago
  Probably shouldn't be upvoting this as it doesn't have much to do with the topic, but I will anyway cause you're fighting for a lost art worth saving.

banashark 8y ago

I'm a big fan of fssnip. http://www.fssnip.net/u/title/Pipeline-list-processing http://www.fssnip.net/u/title/Pipeline-list-processing Hover over the lines and you get type information right there. One of the cool features of F# that I wish was present when reading docs in other languages.

andrepd 8y ago
Oh wow, that's great!

q3k 8y ago

Fair warning: doesn't work at all with JS disabled or disabled for cross-origin (which is somewhat sad, especially for tech documentation).

NickSeagull 8y ago
We are in the process of fixing it, see https://github.com/theam/tintin/issues/7 https://github.com/theam/tintin/issues/7
NickSeagull 8y ago
Fixed in the last version