From e7feece6d9655b940af821fa5a4592cc49a986a1 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Sun, 28 May 2023 10:40:18 -0700 Subject: Add markdown README. * README.md, LICENSE: New files. * who.tl: Add copyright notice. --- LICENSE | 29 +++++++++++++ README.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ who.tl | 1 + 3 files changed, 168 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c1f6f6a --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +TL-WHO +Fork of CL-WHO + +Copyright (c) 2003-2009, Dr. Edmund Weitz. All rights reserved. +Copyright (c) 2023, Kaz Kylheku. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE AUTHOR 'AS IS' AND ANY EXPRESSED +OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..9565161 --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ +## What is TL-WHO? + +TL-WHO is a translation of the Common Lisp library CL-WHO to TXR Lisp. +It is a derived work of CL-WHO, copyrighted by the original authors and +carrying their licensing notices, + +TL-WHO provides a macro for generating HTML using Lisp syntax. + +Unlike some HTML generating libraries, TL-WHO works by translating the +syntax into code that writes HTML to a stream, rather that translating +the syntax into code which constructs a nested data structure, which is then +traversed to produce HTML. TL-WHO merges strings as much as possible. + +For instance, here is what happens when we use it on syntax which is +entirely static (contains no computations whose results are to be +inserted into the HTML): + + ::text + 1> (tl-who:with-html-output (*stdout* nil :indent t) + (:table (:tr (:td (:span "foo"))))) + + + + + +
+ foo + +
+ +And here the code which produces the HTML: + + ::text + 2> (expand '(tl-who:with-html-output (*stdout* nil :indent t) + (:table (:tr (:td (:span "foo")))))) + (let ((*stdout* (sys:dvbind *stdout* + *stdout*))) + (put-string "\n\n \n \n \n
\n foo\n \n
" + *stdout*)) + +What is noteworthy here is that a single string is produced out of the nested +Lisp syntax, and that string is therefore sent to the `*stdout*` stream +using a single call to the `put-string` function. + +## Documentation + +Users of TL-WHO may rely on the original CL-WHO API documentation. + +Here are the differences to be aware of: + +* The symbol package is `tl-who` not `cl-who`. It is case-sensitive; + the symbol `TL-WHO:WITH-HTML-OUTPUT` refers to a non-existent + package, and so cannot even be read. + +* The `*downcase-tokens-p*` variable does not exist in TL-WHO. It is + replaced by `*upcase-tokens-p*`, whose default value is `nil`. + TXR Lisp is case sensitive and lower-case is preferred for symbols. + A symbol like `:table` in TXR Lisp has the name `"table"` rather + than `"TABLE"`. And HTML is usually written in lower case nowadays, + so no case conversion is required to turn `:table` into ``. + Therefore, in TL-WHO it is better to have a case conversion + variable that is off by default. + +* Because TXR Lisp is case-sensitive, a symbol like `:TABLE` will + produce a `
` tag in upper case, whereas `:table` will + produce `
`. They are different symbols. Thus it is possible to + control case on a case by case basis, no pun intended. If the + *upcase-tokens-p*` variable is bound to `t`, then both will + produce `
`. + +* All of the elaborate HTML escaping support featured in CL-WHO is + absent in TL-WHO. These symbols do not exist: `escape-string`, + `escape-char`, `*escape-char-p*`, `escape-string-minimal`, + `escape-string-minimal`, `escape-string-minimal-plus-quotes`, + `escape-string-iso-8859-1`, `escape-string-all`, + `escape-char-minimal`, `escape-char-minimal-plus-quotes`, + `escape-char-iso-8859-1` and `escape-char-all`. + TL-WHO uses the TXR Lisp standard function `html-encode`, + which has no options to control its behavior. + +* 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. + +Additionally, users (of 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. + +## Dependencies + +TL-WHO has no external dependencies other than TXR itself. + +It requires version 287 or newer. + +## Installation/Use + +To use TL-WHO, you just have to put the code somewhere and `load` +the `tl-who.tl` file (or its compiled version, if you compile the code). + + ::text + (load "path/to/tl-who") + +TXR Lisp's `load` is intelligent; the `tl-who` loader module easily loads the +needed files, which it finds in the same directory as itself. + +TL-WHO symbols are in a package called `tl-who`, which is case sensitive. + +Its private symbols are in `tl-who-priv`. + +Two TL-WHO symbols have the same names as standard TXR library symbols, +namely `fmt` and `str`. Code which references the `tl-who` package in +preference to the `usr` package (for instance by putting `tl-who` first +in the package `:fallback` list) must use `usr:fmt` and `usr:str` to refer to +the TXR Lisp`fmt` functions, because the unprefixed tokens will produce +`tl-who:fmt` and `tl-who:str`, which are different symbols. + +## License + +TL-WHO is distributed under the two-clause BSD license. +[`LICENSE`](../tree/LICENSE) file. diff --git a/who.tl b/who.tl index 3ea8d80..0449b86 100644 --- a/who.tl +++ b/who.tl @@ -1,4 +1,5 @@ ;; Copyright (c) 2003-2009, Dr. Edmund Weitz. All rights reserved. +;; Copyright (c) 2023, Kaz Kylheku. All rights reserved. ;; ;; Redistribution and use in source and binary forms, with or without ;; modification, are permitted provided that the following conditions -- cgit v1.2.3