From 2e5ec1a87b614dfce7d9105e841b71d18691b98a Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Thu, 1 Jun 2023 07:20:52 -0700 Subject: README: rearrange. * README.mt: Move the sections on escaping earlier, since it's a very important difference. --- README.md | 102 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 32a5f1a..8ef3b5c 100644 --- a/README.md +++ b/README.md @@ -114,56 +114,6 @@ Here are the differences to be aware of: to be inserted into attributes; `html-encode*` is used by `esc` and `fmt`. -* The CL-WHO `conc` function is missing. TXR Lisp has a function - like this, which is called `join`, and that is what is used in TL-WHO. - -* There is no generic function `convert-tag-to-string-list`. - It is an ordinary function. There is no support for customizing - its behavior. TXR Lisp doesn't have CLOS, and thus no generic functions - or methods. A mechanism for customizing the conversion of tags to - string lists may be adopted by TL-WHO in the future. - -* Numerous instances of internal unused code that in CL-WHO do - not appear at all in TL-WHO; they have been pruned. Code depending - on internal CL-WHO functions that are not present in TL-WHO - will not work and must be ported in an alternative way. - -* TXR Lisp isn't Common Lisp and so CL-WHO examples which use ANSI CL - idioms like the `loop` macro will not work. All Lisp code - embedded in a CL-WHO expression has to be translated to TXR Lisp - in order for that expression to work as TL-WHO; the TL-WHO - library doesn't translate embedded Common Lisp to TXR Lisp; - it only translates the markup syntax to HTML in the same way as CL-WHO. - -* The variable `*attribute-quote-char*` will not work if it is bound by - `let` around a `with-html-output-form`. The reason is that TL-WHO - interpolates this character at macro-expansion time, even for - HTML attributes whose values are calculated at run-time. - The binding construct `expander-let` must be used, or else the - variable's global binding must be assigned. - -* CL-WHO has some bugs around attribute handling. When the value of an - attribute is a constant expression, only the specific values `T` - and `NIL` are treated properly, not constant expressions which evaluate - to `T` and `NIL`. Then we see the mistaken attribute values `'NIL` and `'T'`: - This works properly in TL-WHO: - - ::text - [1]> (in-package :cl-who) - # - WHO[2]> (with-html-output-to-string (str) - (:foo :bar t)) - "" - WHO[3]> (with-html-output-to-string (str) - (:foo :bar (quote t))) - "" - WHO[4]> (with-html-output-to-string (str) - (:foo :bar nil)) - "" - WHO[5]> (with-html-output-to-string (str) - (:foo :bar 'nil)) - "" - * TL-WHO fixes the issue that CL-WHO doesn't HTML-escape the values of of constant string material, of attributes, and of material added by local macro `fmt`. @@ -218,7 +168,57 @@ Here are the differences to be aware of: a mess of the output if used; unlike CL-WHO, TL-WHO warns when they are used in attributes. -Additionally, users (of CL-WHO and TL-WHO alike) are advised to watch for the +* The CL-WHO `conc` function is missing. TXR Lisp has a function + like this, which is called `join`, and that is what is used in TL-WHO. + +* There is no generic function `convert-tag-to-string-list`. + It is an ordinary function. There is no support for customizing + its behavior. TXR Lisp doesn't have CLOS, and thus no generic functions + or methods. A mechanism for customizing the conversion of tags to + string lists may be adopted by TL-WHO in the future. + +* Numerous instances of internal unused code that in CL-WHO do + not appear at all in TL-WHO; they have been pruned. Code depending + on internal CL-WHO functions that are not present in TL-WHO + will not work and must be ported in an alternative way. + +* TXR Lisp isn't Common Lisp and so CL-WHO examples which use ANSI CL + idioms like the `loop` macro will not work. All Lisp code + embedded in a CL-WHO expression has to be translated to TXR Lisp + in order for that expression to work as TL-WHO; the TL-WHO + library doesn't translate embedded Common Lisp to TXR Lisp; + it only translates the markup syntax to HTML in the same way as CL-WHO. + +* The variable `*attribute-quote-char*` will not work if it is bound by + `let` around a `with-html-output-form`. The reason is that TL-WHO + interpolates this character at macro-expansion time, even for + HTML attributes whose values are calculated at run-time. + The binding construct `expander-let` must be used, or else the + variable's global binding must be assigned. + +* CL-WHO has some bugs around attribute handling. When the value of an + attribute is a constant expression, only the specific values `T` + and `NIL` are treated properly, not constant expressions which evaluate + to `T` and `NIL`. Then we see the mistaken attribute values `'NIL` and `'T'`: + This works properly in TL-WHO: + + ::text + [1]> (in-package :cl-who) + # + WHO[2]> (with-html-output-to-string (str) + (:foo :bar t)) + "" + WHO[3]> (with-html-output-to-string (str) + (:foo :bar (quote t))) + "" + WHO[4]> (with-html-output-to-string (str) + (:foo :bar nil)) + "" + WHO[5]> (with-html-output-to-string (str) + (:foo :bar 'nil)) + "" + +Additionally, users (of both CL-WHO and TL-WHO alike) are advised to watch for the following issue: the CL-WHO documentation is not accurately maintained and makes some references to material that no longer exists in CL-WHO, such as the macro `show-html-expansion`, which was removed from CL-WHO in 2009. -- cgit v1.2.3