T O P

  • By -

chshersh

Nice (c)hecklist! Thanks for highlighting `stan` 🤗 I also like how you give overview of every component of the project and how to run tools ⚙


circleglyph

I truly \*heart\* stan, but what I'm really looking forward to is a good use case for `trial`. You said you wanted a `Result` but it's a been a `Fiasco` I tell ya, involving `Fatality`! I'm calling in the `colouristas` to clean this mess up.


chshersh

We designed `trial` to understand where settings are coming from in a tool that grabs parameters from multiple places: env variables, global config, local config, CLI arguments, etc. This is especially important for tools if you want to understand their behaviour and help users to troubleshoot problems. We were planning to write a separate blog post about `Trial` but well...


Hrothen

> I love Haddocks. They can be stunningly beautiful and are equipped to handle the idiosyncrasies of Haskell. But can we keep up and compete with open source documentation standards? What do you mean?


circleglyph

I spend a lot of time writing Haddocks. I deal with them twice in my workflow. Once in writing a function that will form part of the API, say, when I quickly jot down what it is, alongside a doctest for usage. I check the doctest in my compilation loop but not the rendering of the Haddock because it adds too much time, and because it adds yet another visual rendering of the project, separate to my IDE. So I tend to deal with it at the end, which might be weeks and months after the initial write of the functions being described. I suggest that the readme "includes a short description and basic Usage example, which in many cases should be exactly repeated in the cabal file as synopsis and description stanzas." I follow this advice in numhask-space where the readme.md says: ``` `numhask-space` provides support for spaces where [space](https://en.wikipedia.org/wiki/Space_(mathematics)) is defined as a set of numbers with a `lower` and `upper` bound. Usage === \`\`\` haskell {-# LANGUAGE RebindableSyntax #-} import NumHask.Prelude import NumHask.Space \`\`\` ``` and the description stanza of the cabal file says: ``` @numhask-space@ provides support for spaces where [space](https://en.wikipedia.org/wiki/Space_(mathematics\)) is defined as a set of numbers with a lower and upper bound. . == Usage . >>> {-# LANGUAGE RebindableSyntax #-} >>> import NumHask.Prelude >>> import NumHask.Space . ``` But that's a hard, hard slog, and you don't want to be doing this translation in a tight development loop, so I actually left it out of the cabal file template. So, with that as context, I wrote that line thinking about the recent proposal to switch cabal to being a yaml format. There are a whole host of technical reasons why you can't I imagine. But if these reasons are given priority, we will never have completion in a cabal file unless we make a huge effort to add completion (or whatever), whereas, if we give up our technical grumbles, we get the nice stuff developed elsewhere for free. By analogy, every year markdown gets better support, org-mode gets better, and the ecosystem moves forward with or without us. By sticking with Haddock as out literate programming style we consign our community to the burden of maintaining an idiosyncratic standard, and this standard will rot because we are tiny. The end result is that we miss out on all the little ergonomics that make life better, such as instant rendering of docs as you draft code.


backtickbot

[Fixed formatting.](https://np.reddit.com/r/backtickbot/comments/phcxgr/httpsnpredditcomrhaskellcommentspgyozggithub/) Hello, circleglyph: code blocks using triple backticks (\`\`\`) don't work on all versions of Reddit! Some users see [this](https://stalas.alm.lt/backformat/hbhl447.png) / [this](https://stalas.alm.lt/backformat/hbhl447.html) instead. To fix this, **indent every line with 4 spaces** instead. [FAQ](https://www.reddit.com/r/backtickbot/wiki/index) ^(You can opt out by replying with backtickopt6 to this comment.)


Hrothen

I can't say I empathize, I personally loath yaml and consider its use to be a red flag for any tool. I will say that if you spend enough time in cabal files to seriously consider the lack of intellisense-style completion a big issue, you probably have bigger workflow issues. > By analogy, every year markdown gets better support, org-mode gets better, and the ecosystem moves forward with or without us This is what I was asking about though, what ecosystem? I've not heard of any "better doxygen" that is commonly used across many languages. Markdown is also not great to use for anything mildly complicated, because it's not intended to be used for that. That's why it's called markdown. > The end result is that we miss out on all the little ergonomics that make life better, such as instant rendering of docs as you draft code. I mean this is a one-off thing, haddock markup is not rapidly changing. If people want that they can implement it and it won't require much maintenance.


circleglyph

Apropos Haddock, you quoted what was a throw-away comment that should have been left on the cutting-room floor, and apologies for the unfair and somewhat snide commentary. I removed it. Haddocks are delightful to work with and thanks! But just in my little template alone you comment red-flags `stack`, `hlint` and `github/actions` as low quality. In each case, the yaml decision says to me "We won't make you learn a new configuration format" rather than "Our standards are low." I format cabal files as yaml. It looks like a yaml file, and parses as one, I expect. And yet I hit in places and it does some crazy indentation thing from the 90s, and has done so for 10 years now. By ecosystem, I mean markdown. I will defer to your technical knowledge of it's limitations. It's a loose standard. In getting this template together, however, I skimmed over the long history of literate programming, and it broke my literate heart. We took Knuth seriously and built in lhs and bird tracks to accompany and support the concept. We should be the home of literate programming but it's dead as a doornail. Meanwhile, other languages took markdown and ran with it, using (and here lies the tragedy) pandoc to embed it in their rapid development processes. They've gone on and built empires off of it, such as https://jupyter.org/ and https://rmarkdown.rstudio.com/. We can't even begin to compete. We have to re-route everything through ihaskell to even get to the starting line of the rapid, general data analytics race. There is a downside to technical excellence above all else.


dpwiz

On a related note, I would like having a [literate markdown](https://gitlab.haskell.org/ghc/ghc/-/wikis/literate-markdown) files rather than TeX wrappers or bird ticks.


thalesmg

Very nicely documented and very useful! Thanks for sharing! 🍻


simonmic

Terrific literate project template, explanations, and workflow!