1. 15
  1.  

  2. 6

    Ok, trying to follow along that little getElementById section, I totally see where people are coming from that say Purescript documentation is terrible.

    1. getElementById has no documentation at all besides the types. Ok, I know the JavaScript version, but what’s NonElementParentNode? Clicking the type doesn’t help because actually we’re already on the page with the type definition. Also zero explanation. How do we make a NonElementParentNode?
    2. Ok, let’s cheat, the article spoiled that this argument might be document (does it have to be? how does getElementById actually use this argument?). So we find Web.DOM.Document in the same package. Oh look, some documentation text! And if we scan through the list of undocumented functions, we can tell that, yes, a Document gives us a NonElementParentNode via toNonElementParentNode.
    3. Alright, following that text at the start of the Web.DOM.Document, let’s look up the package purescript-web-html and look for the document. No meaningful introductory documentation, and the main module Web.HTML is even worse with just a long list of re-exports.
    4. So lets scan the list of 90(!) modules for something relevant. Web.HTML.HTMLDocument sounds like it might help. Hmm, no, just another long list of boilerplate.
    5. So let’s scroll further through the module list. window is kind of like document, and there’s a plain Web.HTML.Window module. Oh look, we got lucky! If we have a Window, we can now get a HTMLDocument via document :: Window -> Effect HTMLDocument. But wait, we wanted a Document, not a HTMLDocument. Luckily, that list of boilerplate functions in Web.HTML.HTMLDocument comes with toDocument :: HTMLDocument -> Document.
    6. We still need a Window, though, and Web.HTML.Window doesn’t seem to give us one. At this point I’m lost for a couple minutes, randomly click back to the top-level Web.HTML, and see that besides all the re-export boilerplate, hiding in plain site we have window :: Effect Window!
    1. 2

      Sounds like my experience with purescript. Also don’t forget to you first have to pick your framework, and then find a version which actually works with the purescript version you want to use.

    2. 3

      There’s a good comment at the bottom of the article from a contributor using Nix for the first time. A nix setup that works is great for getting new contributors on board. I wonder if there’s a good way to spread the meme that nix is easy to use in these situations (where you don’t have to get your hands dirty on the nix code itself)?

      1. 2

        Nice little taste of what’s it like. Would appreciate a deeper dive if you ever get into it.

        Off topic but regarding the static site that rib produces and, as far as I could tell from my little research prompted by your blog post, most Zettelkasten systems: don’t you find it annoying to have these IDs as the link text everywhere (e.g. “2011401”). They don’t look like they are meant to mean something to people, or am I wrong about that? Installing neuron as we speak so may have a better understanding soon.

        1. 2

          Neuron supports custom alphanumeric IDs as well, but it is not yet documented. You can create a zettel called “foo-bar.md” (becomes yoursite.com/foo-bar.html) and it should work fine.

          don’t you find it annoying to have these IDs as the link text everywhere (e.g. “2011401”)

          My links almost always contain an annotation:

          [2011401](z://foo-bar)
          

          So I haven’t found it to be an issue in practice. Using consistent IDs like this have a certain appeal, and practical advantanges (not having to think about filenames every time you create a zettel; and consistency in the web UI).

          1. 1

            I guess I am wondering: why not hide the ID when you have a link anyway?

            1. 2

              To very clearly distinguish (visually) a zettel link from a normal link. Also, linking the ID (instead of title) keeps them vertically aligned nicely in a list of zettel links (example). It is mostly a subjective preference of the author (me).