search

weavejester / hiccup

Fast library for rendering HTML in Clojure
http://weavejester.github.io/hiccup
Eclipse Public License 1.0
2.68k stars 174 forks source link

Sentence needed in readme.md to clarify status of original hiccup namespaces, when using hiccup2? #212

Closed mikew1 closed 1 month ago

mikew1 commented 1 month ago

This is just an FYI, trying to be helpful.

There are three or more comments in the clojurians slack hiccup channel where people get stuck trying to use hiccup2 and are not clear if the original hiccup namespaces (e.g. hiccup.page/html5), are intended to be incompatible when using hiccup2.

If this is the intention, perhaps this could be clarified in the readme.md for this repo? (I thought it would be rude of me to edit it myself without first asking).

Specifically, when using hiccup2, what is the status of the public functions in the hiccup namespace? Is the intention that these not be used as they are awaiting new hiccup2 versions?

Many thanks for the great work! Would like to help if I know how.

weavejester commented 1 month ago

That's very helpful. I didn't realize there was an issue, since I wasn't on the hiccup slack channel and no-one has contacted me about it before. I'll add an explanation to the README.

mikew1 commented 1 month ago

Just to share an idea for a possible way to lay out the readme.

The premise is I'm assuming we would still like to explain hiccup 1 alongside, since that's a legitimate choice as well as much code being already out in the wild.

(:require [hiccup.core :as h1])
(:require [hiccup2.core :as h2])

(h1/html
  "<!DOCTYPE html>"
  [:head ]
  [:body
    [:p "Hiccup 1 does not auto escape."]])

(h2/html
  (h2/raw "<!DOCTYPE html>")
  [:head ]
  [:body
    [:p "Hiccup 2 does, so we use a call to h2/raw."]])

Also could potentially add the point that although we are now at version 2, full back compatibility is maintained for hiccup 1, which means these can be used in parallel like this should that be desired. (in case people had any doubt about hiccup 2.0.0 being a 'breaking change' of any kind).

weavejester commented 1 month ago

Fixed by 5a6d45c17728dcbcb3aeb32ea890fd9dc1508547