From 741a76147611947e8488c10048c143c34c675a4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Georges=20Dup=C3=A9ron?= Date: Tue, 16 May 2017 00:26:48 +0200 Subject: [PATCH] Quick documentation & passable LaTeX support --- diff1.rkt | 44 ++++++++++++++------- info.rkt | 3 +- scribblings/diff1-example.hl.rkt | 65 +++++++++++++++++++++++++++++++- scribblings/hyper-literate.scrbl | 5 ++- 4 files changed, 100 insertions(+), 17 deletions(-) diff --git a/diff1.rkt b/diff1.rkt index b0cc51ea..23aaf9e6 100644 --- a/diff1.rkt +++ b/diff1.rkt @@ -10,6 +10,7 @@ syntax/srcloc) scribble/core scribble/html-properties + scribble/latex-properties scribble/base) ;; For debugging. @@ -41,30 +42,47 @@ (define the-css-addition #" -.el-hlite-dim { +.HyperLiterateNormal { + filter: initial; + background: none; +} + +.HyperLiterateDim { filter: brightness(150%) contrast(30%) opacity(0.7); background: none; /* rgba(82, 103, 255, 0.36); */ } -.el-hliteadd{ +.HyperLiterateAdd{ filter: initial; background: rgb(202, 226, 202); } -.el-hliterm { +.HyperLiterateRemove { filter: initial; background: rgb(225, 182, 182); -} - -.el-hlite-normal { - filter: initial; - background: none; }") +(define the-latex-addition + #" +%\\usepackage{framed}% \begin{snugshade}\end{snugshade} +\\definecolor{HyperLiterateDimColor}{RGB}{210,210,210} +\\definecolor{HyperLiterateAddColor}{RGB}{202,226,202} +\\definecolor{HyperLiterateRemoveColor}{RGB}{225,182,182} + +\\def\\HyperLiterateNormal#1{#1} +\\def\\HyperLiterateDim#1{\\colorbox{HyperLiterateDimColor}{% + \\vphantom{\\RktPn{(}\\RktValDef{Xj}}#1}} +\\def\\HyperLiterateAdd#1{\\colorbox{HyperLiterateAddColor}{% + \\vphantom{\\RktPn{(}\\RktValDef{Xj}}#1}} +\\def\\HyperLiterateRemove#1{\\colorbox{HyperLiterateRemoveColor}{% + \\vphantom{\\RktPn{(}\\RktValDef{Xj}}#1}} +") + (define (init) (elem #:style (style #f - (list (css-addition the-css-addition))))) + (list (css-addition the-css-addition) + (tex-addition the-latex-addition))))) (begin-for-syntax (define (stx-null? e) @@ -95,10 +113,10 @@ [(null? g) '()])) (define (mode→style m) (case m - [(/) "el-hlite-dim"] - [(=) "el-hlite-normal"] - [(-) "el-hliterm"] - [(+) "el-hliteadd"])) + [(/) "HyperLiterateDim"] + [(=) "HyperLiterateNormal"] + [(-) "HyperLiterateRemove"] + [(+) "HyperLiterateAdd"])) (define simplified-guide (simplify-guide #'guide1)) (define (syntax-e? v) (if (syntax? v) (syntax-e v) v)) diff --git a/info.rkt b/info.rkt index 5197607e..fe2ffa11 100644 --- a/info.rkt +++ b/info.rkt @@ -17,7 +17,8 @@ (define build-deps '("scribble-lib" "racket-doc" "rackunit-doc" - "scribble-doc")) + "scribble-doc" + "rackunit-doc")) (define scribblings '(("scribblings/hyper-literate.scrbl" ()) ("test/test.hl.rkt" () (omit-start)) ("test/test2.hl.rkt" () (omit-start)))) diff --git a/scribblings/diff1-example.hl.rkt b/scribblings/diff1-example.hl.rkt index 4de7da8a..44b4bbbc 100644 --- a/scribblings/diff1-example.hl.rkt +++ b/scribblings/diff1-example.hl.rkt @@ -1,7 +1,68 @@ #lang hyper-literate #:♦ racket/base ♦;(dotlambda/unhygienic . racket/base) -♦title{testttt} +♦title{Highlighting added, removed and existing parts in literate programs} + +♦defmodule[hyper-literate/diff1] + +Highly experimental. Contains bugs, API may change in the future. + +♦defproc[(init) any/c]{ + + For now, the ♦racket[init] function must be called somewhere in documents + which use ♦racketmodname[hyper-literate/diff1]. It produces helper values + which must be inserted in the scribble document. Simply adding this to the + document should be enough: + + ♦codeblock|{ + #lang hyper-literate #:♦ racket/base + ♦(init)}|} + +♦defform[(hlite name pat . body)]{ + + Like ♦racket[chunk], but highlights parts of the ♦racket[body] according to + the pattern ♦racket[pat]. + + The ♦racket[pat] should cover the whole ♦racket[body], which can contain + multiple expressions. The ♦racket[pat] can use the following symbols: + + ♦itemlist[ + ♦item{♦racket[=] to indicate that the following elements are ``normal'' and + should not be highlighted in any special way.} + ♦item{♦racket[/] to indicate that the following elements were already + existing in previous occurrences of the code (the part is dimmed)} + ♦item{♦racket[+] to indicate that the following elements are new (highlighted + in green)} + ♦item{♦racket[-] to indicate that the following elements are removed + (highlighted in red). Removed elements are also removed from the actual + executable source code. If a removed element contains one or more normal, new + or dimmed elements, these children are spliced in place of the removed + element.} + ♦item{Other symbols are placeholders for the elements}] + + In the following example, the ♦racket[1] is highlighted as removed (and will + not be present in the executable code), the ♦racket[π] is highlighted as + added, and the rest of the code is dimmed: + + ♦codeblock|{ + #lang hyper-literate #:♦ racket/base + ♦hlite[ {/ (def args (_ - _ + _ / . _))} + (define (foo v) + (+ 1 π . v))]}| + + It produces the result shown below:} + +♦require[hyper-literate/diff1] +♦(init) + +♦hlite[ {/ (def args (_ - _ + _ / . _))} + (define (foo v) + (+ 1 π . v))] + +♦section{Example} + +You can look at the source code of this document to see how this example is +done. ♦require[hyper-literate/diff1] ♦(init) @@ -69,4 +130,4 @@ The whole program is therefore: (check-equal? '() '(2 3 4)) (check-equal? '(0 1) '(0 x z 1)) (check-equal? ' '(0 x . z)) - (check-equal? ' '(0 x . z))] \ No newline at end of file + (check-equal? ' '(0 x x . z))] \ No newline at end of file diff --git a/scribblings/hyper-literate.scrbl b/scribblings/hyper-literate.scrbl index 57329f48..3149c448 100644 --- a/scribblings/hyper-literate.scrbl +++ b/scribblings/hyper-literate.scrbl @@ -267,4 +267,7 @@ present). "@(chunks-toc-prefix '((lib \"pkg/scribblings/main.scrbl\")\n" " (lib \"pkg/program.hl.rkt\")))\n" "@chunk[<*>\n" - " 'program-code-here]\n"]}]} \ No newline at end of file + " 'program-code-here]\n"]}]} + +@include-section[(submod (lib "hyper-literate/scribblings/diff1-example.hl.rkt") + doc)] \ No newline at end of file