From 563a6cd9ede15ab51302b479fcd64b9a78333ec8 Mon Sep 17 00:00:00 2001 From: lread Date: Sun, 18 Sep 2022 15:52:09 -0400 Subject: [PATCH] docs: user guide: windows & newlines Thanks @ikappaki for raising #187 I'll leave the issue open for a bit to gather more feedback but at least we've documented the behaviour for now. --- README.adoc | 3 ++- doc/01-user-guide.adoc | 9 ++++++++- doc/contributors.edn | 4 +++- doc/generated/contributors/ikappaki.png | Bin 0 -> 6304 bytes 4 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 doc/generated/contributors/ikappaki.png diff --git a/README.adoc b/README.adoc index 23da53b..b888015 100644 --- a/README.adoc +++ b/README.adoc @@ -1,6 +1,6 @@ :notitle: // num-contributors is updated automatically by doc-readme-update bb task -:num-contributors: 54 +:num-contributors: 55 :figure-caption!: :imagesdir: ./doc :project-src-coords: clj-commons/rewrite-clj @@ -133,6 +133,7 @@ image:fazzone.png[fazzone,role="left",width=250,link="https://github.com/fazzone image:ferdinand-beyer.png[ferdinand-beyer,role="left",width=250,link="https://github.com/ferdinand-beyer"] image:green-coder.png[green-coder,role="left",width=250,link="https://github.com/green-coder"] image:guoyongxin.png[guoyongxin,role="left",width=250,link="https://github.com/guoyongxin"] +image:ikappaki.png[ikappaki,role="left",width=250,link="https://github.com/ikappaki"] image:immoh.png[immoh,role="left",width=250,link="https://github.com/immoh"] image:ivarref.png[ivarref,role="left",width=250,link="https://github.com/ivarref"] image:luxbock.png[luxbock,role="left",width=250,link="https://github.com/luxbock"] diff --git a/doc/01-user-guide.adoc b/doc/01-user-guide.adoc index 75e8efd..1913c51 100644 --- a/doc/01-user-guide.adoc +++ b/doc/01-user-guide.adoc @@ -702,9 +702,16 @@ This is convenient when navigating through the source, but when we want to logic == Parsing Peculiarities -Rewrite-clj can, in some specific cases, parse technically invalid Clojure. +Rewrite-clj might suprise Windows users and can, in some specific cases, parse technically invalid Clojure. Some folks have come to rely on this over the years, so these are behaviours we will preserve. +=== Newlines Always Normalize to `\n` +Window users might be suprised that `\r\n` newlines are converted to `\n` by rewrite-clj. + +Rewrite-clj makes use of https://github.com/clojure/tools.reader[Clojure's tools.reader] to parse Clojure code. +The `tools.reader` normalizes all recognized newline variants to `\n`. +Rewrite-clj picks up this behaviour. + [[unbalanced-maps]] === Unbalanced Maps An unbalanced map is one where there is a key with no value. diff --git a/doc/contributors.edn b/doc/contributors.edn index 09fce5c..dd1de65 100644 --- a/doc/contributors.edn +++ b/doc/contributors.edn @@ -99,7 +99,9 @@ {:github-id "NoahTheDuke" :contributions [:issue :encouragement]} {:github-id "ferdinand-beyer" - :contributions [:code-rewrite-clj-v1]}] + :contributions [:code-rewrite-clj-v1]} + {:github-id "ikappaki" + :contributions [:issue]}] :founders [{:github-id "xsc" :contributions [:original-author :doc :design :issue :review :support :code-rewrite-clj-v0]} diff --git a/doc/generated/contributors/ikappaki.png b/doc/generated/contributors/ikappaki.png new file mode 100644 index 0000000000000000000000000000000000000000..b5871ecda880ce87d3837462274e3819fc8de57e GIT binary patch literal 6304 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 literal 0 HcmV?d00001