From 992a49839f7219f58969fce09e19e0118ead559b Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Mon, 21 Sep 2009 15:33:21 -0400 Subject: [PATCH 01/45] help: inserted a blank line between the title and the article content. --- basis/help/help.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/help/help.factor b/basis/help/help.factor index e31c705e26..8f8ad35bf4 100644 --- a/basis/help/help.factor +++ b/basis/help/help.factor @@ -125,7 +125,7 @@ M: word set-article-parent swap "help-parent" set-word-prop ; : print-topic ( topic -- ) >link last-element off - [ $title ] [ article-content print-content nl ] bi ; + [ $title ] [ nl article-content print-content nl ] bi ; SYMBOL: help-hook From 66a6108d421611451776a303ee41a54a71ecb746 Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Mon, 21 Sep 2009 15:35:16 -0400 Subject: [PATCH 02/45] help.markup: added $subsections markup and consolidated $link implementations - Created a new markup element, $subsections, which is a plural variant of $subsection. The advantage is that it automatically inserts a blank line after the final subsection which makes help articles considerably easier to read. - Consolidated the implementation of $link, $long-link and $pretty-link - Moved $definition-icons from definition.icons to help.markup - Moved $pretty-link from help.vocabs to help.markup --- basis/definitions/icons/icons.factor | 13 +--- basis/help/crossref/crossref.factor | 2 +- basis/help/markup/markup.factor | 90 +++++++++++++++++++--------- basis/help/vocabs/vocabs.factor | 18 ++---- 4 files changed, 72 insertions(+), 51 deletions(-) diff --git a/basis/definitions/icons/icons.factor b/basis/definitions/icons/icons.factor index 3c4dad5be7..63ea2d6093 100644 --- a/basis/definitions/icons/icons.factor +++ b/basis/definitions/icons/icons.factor @@ -1,8 +1,8 @@ ! Copyright (C) 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: assocs classes.predicate fry generic io.pathnames kernel -macros sequences vocabs words words.symbol words.constant -lexer parser help.topics help.markup namespaces sorting ; +USING: assocs classes.predicate fry generic help.topics +io.pathnames kernel lexer macros namespaces parser sequences +vocabs words words.constant words.symbol ; IN: definitions.icons GENERIC: definition-icon ( definition -- path ) @@ -41,10 +41,3 @@ ICON: topic help-article ICON: runnable-vocab runnable-vocab ICON: vocab open-vocab ICON: vocab-link unopen-vocab - -: $definition-icons ( element -- ) - drop - icons get >alist sort-keys - [ [ <$link> ] [ definition-icon-path <$image> ] bi* swap ] assoc-map - { "" "Definition class" } prefix - $table ; \ No newline at end of file diff --git a/basis/help/crossref/crossref.factor b/basis/help/crossref/crossref.factor index 46f9561605..5e4922c7ad 100644 --- a/basis/help/crossref/crossref.factor +++ b/basis/help/crossref/crossref.factor @@ -10,7 +10,7 @@ IN: help.crossref collect-elements [ >link ] map ; : article-children ( topic -- seq ) - { $subsection } article-links ; + { $subsection $subsections } article-links ; : help-path ( topic -- seq ) [ article-parent ] follow rest ; diff --git a/basis/help/markup/markup.factor b/basis/help/markup/markup.factor index c64f315d6d..b438c97084 100644 --- a/basis/help/markup/markup.factor +++ b/basis/help/markup/markup.factor @@ -1,10 +1,11 @@ ! Copyright (C) 2005, 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: accessors arrays definitions generic io kernel assocs -hashtables namespaces make parser prettyprint sequences strings -io.styles vectors words math sorting splitting classes slots fry -sets vocabs help.stylesheet help.topics vocabs.loader quotations -combinators see present ; +USING: accessors arrays assocs classes colors.constants +combinators definitions definitions.icons effects fry generic +hashtables help.stylesheet help.topics io io.styles kernel make +math namespaces parser present prettyprint +prettyprint.stylesheet quotations see sequences sets slots +sorting splitting strings vectors vocabs vocabs.loader words ; FROM: prettyprint.sections => with-pprint ; IN: help.markup @@ -156,45 +157,73 @@ ALIAS: $slot $snippet : write-link ( string object -- ) link-style get [ write-object ] with-style ; -: ($link) ( article -- ) - [ [ article-name ] [ >link ] bi write-link ] ($span) ; +: link-icon ( topic -- ) + definition-icon 1array $image ; -: $link ( element -- ) - first ($link) ; - -: ($definition-link) ( word -- ) +: link-text ( topic -- ) [ article-name ] keep write-link ; -: $definition-link ( element -- ) - first ($definition-link) ; +: link-effect ( topic -- ) + dup word? [ + stack-effect [ effect>string ] [ effect-style ] bi + [ write ] with-style + ] [ drop ] if ; -: ($long-link) ( object -- ) - [ article-title ] [ >link ] bi write-link ; +: inter-cleave ( x seq between -- ) + [ [ call( x -- ) ] with ] dip swap interleave ; inline -: $long-link ( object -- ) - first ($long-link) ; +: (($link)) ( topic words -- ) + [ dup topic? [ >link ] unless ] dip + [ [ bl ] inter-cleave ] ($span) ; inline + +: ($link) ( topic -- ) + { [ link-text ] } (($link)) ; + +: $link ( element -- ) first ($link) ; + +: ($long-link) ( topic -- ) + { [ link-text ] [ link-effect ] } (($link)) ; + +: $long-link ( element -- ) first ($long-link) ; + +: ($pretty-link) ( topic -- ) + { [ link-icon ] [ link-text ] } (($link)) ; + +: $pretty-link ( element -- ) first ($pretty-link) ; + +: ($long-pretty-link) ( topic -- ) + { [ link-icon ] [ link-text ] [ link-effect ] } (($link)) ; + +: $long-pretty-link ( element -- ) first ($long-pretty-link) ; + +: <$pretty-link> ( definition -- element ) + 1array \ $pretty-link prefix ; : ($subsection) ( element quot -- ) [ - subsection-style get [ - bullet get write bl - call - ] with-style + subsection-style get [ call ] with-style ] ($block) ; inline +: $subsection* ( topic -- ) + [ + [ ($long-pretty-link) ] with-scope + ] ($subsection) ; + +: $subsections ( children -- ) + [ $subsection* ] each nl ; + : $subsection ( element -- ) - [ first ($long-link) ] ($subsection) ; + first $subsection* ; : ($vocab-link) ( text vocab -- ) >vocab-link write-link ; : $vocab-subsection ( element -- ) [ - first2 dup vocab-help dup [ - 2nip ($long-link) - ] [ - drop ($vocab-link) - ] if + first2 dup vocab-help + [ 2nip ($long-pretty-link) ] + [ [ >vocab-link link-icon bl ] [ ($vocab-link) ] bi ] + if* ] ($subsection) ; : $vocab-link ( element -- ) @@ -390,3 +419,10 @@ M: array elements* : <$snippet> ( str -- element ) 1array \ $snippet prefix ; + +: $definition-icons ( element -- ) + drop + icons get >alist sort-keys + [ [ <$link> ] [ definition-icon-path <$image> ] bi* swap ] assoc-map + { "" "Definition class" } prefix + $table ; \ No newline at end of file diff --git a/basis/help/vocabs/vocabs.factor b/basis/help/vocabs/vocabs.factor index d8f351f57d..0aa17ef676 100644 --- a/basis/help/vocabs/vocabs.factor +++ b/basis/help/vocabs/vocabs.factor @@ -3,25 +3,17 @@ USING: accessors arrays assocs classes classes.builtin classes.intersection classes.mixin classes.predicate classes.singleton classes.tuple classes.union combinators -definitions effects fry generic help help.markup help.stylesheet -help.topics io io.files io.pathnames io.styles kernel macros -make namespaces prettyprint sequences sets sorting summary -vocabs vocabs.files vocabs.hierarchy vocabs.loader -vocabs.metadata words words.symbol definitions.icons ; +effects fry generic help help.markup help.stylesheet +help.topics io io.pathnames io.styles kernel macros make +namespaces sequences sorting summary vocabs vocabs.files +vocabs.hierarchy vocabs.loader vocabs.metadata words +words.symbol ; FROM: vocabs.hierarchy => child-vocabs ; IN: help.vocabs : about ( vocab -- ) [ require ] [ vocab help ] bi ; -: $pretty-link ( element -- ) - [ first definition-icon 1array $image " " print-element ] - [ $definition-link ] - bi ; - -: <$pretty-link> ( definition -- element ) - 1array \ $pretty-link prefix ; - : vocab-row ( vocab -- row ) [ <$pretty-link> ] [ vocab-summary ] bi 2array ; From f9bb7edf3d64db4a39a495b9f60a7059a94001a5 Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Mon, 21 Sep 2009 15:38:55 -0400 Subject: [PATCH 03/45] prettyprint.stylesheet: stack effect highlighting is now a darker green --- basis/prettyprint/stylesheet/stylesheet.factor | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/basis/prettyprint/stylesheet/stylesheet.factor b/basis/prettyprint/stylesheet/stylesheet.factor index a593f23d99..580049160d 100644 --- a/basis/prettyprint/stylesheet/stylesheet.factor +++ b/basis/prettyprint/stylesheet/stylesheet.factor @@ -1,6 +1,6 @@ ! Copyright (C) 2009 Keith Lazuka. ! See http://factorcode.org/license.txt for BSD license. -USING: assocs colors.constants combinators +USING: assocs colors colors.constants combinators combinators.short-circuit hashtables io.styles kernel literals namespaces sequences words words.symbol ; IN: prettyprint.stylesheet @@ -43,4 +43,5 @@ PRIVATE> dim-color colored-presentation-style ; : effect-style ( effect -- style ) - COLOR: DarkGreen colored-presentation-style ; + 0 0.2 0 1 colored-presentation-style + { { font-style plain } } assoc-union ; From c4419ba4a3cdac7665580b1587474900de1ae50c Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Mon, 21 Sep 2009 15:41:04 -0400 Subject: [PATCH 04/45] help.markup: made $nl less promiscuous with its newlines --- basis/help/markup/markup.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/help/markup/markup.factor b/basis/help/markup/markup.factor index b438c97084..0201e86b3f 100644 --- a/basis/help/markup/markup.factor +++ b/basis/help/markup/markup.factor @@ -71,7 +71,7 @@ ALIAS: $slot $snippet ] ($span) ; : $nl ( children -- ) - nl nl drop ; + nl last-block? [ nl ] unless drop ; ! Some blocks : ($heading) ( children quot -- ) From 9982ce4e95cdc0c583be1aedf2ab550588c52ecf Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Mon, 21 Sep 2009 15:42:58 -0400 Subject: [PATCH 05/45] urls.encoding: fix for error found by help-lint --- basis/urls/encoding/encoding-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/urls/encoding/encoding-docs.factor b/basis/urls/encoding/encoding-docs.factor index a021bd6d23..c8eddc55ac 100644 --- a/basis/urls/encoding/encoding-docs.factor +++ b/basis/urls/encoding/encoding-docs.factor @@ -1,5 +1,5 @@ IN: urls.encoding -USING: strings help.markup help.syntax assocs multiline ; +USING: strings help.markup help.syntax assocs multiline urls ; HELP: url-decode { $values { "str" string } { "decoded" string } } From c4ed7f38b7efb772819489464b343ea9b80c52ca Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Mon, 21 Sep 2009 15:46:34 -0400 Subject: [PATCH 06/45] help: added documentation for $subsections --- basis/help/help-docs.factor | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/basis/help/help-docs.factor b/basis/help/help-docs.factor index be521eb93a..32d60851bd 100644 --- a/basis/help/help-docs.factor +++ b/basis/help/help-docs.factor @@ -148,9 +148,30 @@ HELP: :help HELP: $subsection { $values { "element" "a markup element of the form " { $snippet "{ topic }" } } } -{ $description "Prints a large clickable link to the help topic named by the first string element of " { $snippet "element" } "." } +{ $description "Prints a large clickable link to the help topic named by the first item in " { $snippet "element" } ". The link is printed along with its associated definition icon." } { $examples - { $code "{ $subsection \"sequences\" }" } + { $markup-example { $subsection "sequences" } } + { $markup-example { $subsection nth } } + { $markup-example { $subsection each } } +} ; + +HELP: $subsections +{ $values { "children" "a " { $link sequence } " of one or more " { $link topic } "s or, in the case of a help article, the article's string name." } } +{ $description "Prints a large clickable link for each of the listed help topics in " { $snippet "children" } ". The link is printed along with its associated definition icon." } +{ $examples + { $markup-example { $subsections "sequences" nth each } } +} ; + +{ $subsection $subsections $link } related-words + +HELP: $vocab-subsection +{ $values { "element" "a markup element of the form " { $snippet "{ title vocab }" } } } +{ $description "Prints a large clickable link for " { $snippet "vocab" } ". If " { $snippet "vocab" } " has a main help article, the link will point at that article and the " { $snippet "title" } " input will be ignored. Otherwise, the link text will be taken from " { $snippet "title" } " and point to " { $snippet "vocab" } "'s automatically generated documentation." +$nl +"The link will be printed along with its associated definition icon." } +{ $examples + { $markup-example { $vocab-subsection "SQLite" "db.sqlite" } } + { $markup-example { $vocab-subsection "Alien" "alien" } } } ; HELP: $index From d552ce8ef60a1fef9fdaf9725ef17bfe1a29c392 Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Tue, 22 Sep 2009 09:06:56 -0400 Subject: [PATCH 07/45] html.streams: the 'image' character stream style now generates an HTML element NOTE: You must manually copy your image resources to your web server such that the images are available from the "/images" root URL. For example, if your resource is "vocab:definitions/icons/normal-word.tiff" then it should be copied such that it is available via the following URL: "http://myserver.org/images/basis/definitions/icon/normal-word.tiff" (the original path is first normalized and then the Factor root prefix is stripped away). NOTE: Factor's definition-icons are in TIFF format, which appears to be supported out-of-the-box by very few web browsers (namely Safari). Perhaps we should switch from TIFF to GIF or PNG? Are these vocabs ready to be used? --- basis/html/html.factor | 3 +++ basis/html/streams/streams.factor | 24 +++++++++++++++++++----- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/basis/html/html.factor b/basis/html/html.factor index e446c66d8c..12cf3549f4 100644 --- a/basis/html/html.factor +++ b/basis/html/html.factor @@ -22,3 +22,6 @@ IN: html : simple-link ( xml url -- xml' ) url-encode swap [XML ><-> XML] ; + +: simple-image ( url -- xml ) + url-encode [XML /> XML] ; \ No newline at end of file diff --git a/basis/html/streams/streams.factor b/basis/html/streams/streams.factor index 26a3d5f391..0ddc09bf54 100644 --- a/basis/html/streams/streams.factor +++ b/basis/html/streams/streams.factor @@ -1,8 +1,9 @@ ! Copyright (C) 2004, 2009 Slava Pestov. ! See http://factorcode.org/license.txt for BSD license. -USING: accessors kernel assocs io io.styles math math.order math.parser -sequences strings make words combinators macros xml.syntax html fry -destructors ; +USING: accessors assocs combinators destructors fry html io +io.backend io.pathnames io.styles kernel macros make math +math.order math.parser namespaces sequences strings words xml +xml.syntax ; IN: html.streams GENERIC: url-of ( object -- url ) @@ -87,9 +88,22 @@ MACRO: make-css ( pairs -- str ) : emit-html ( quot stream -- ) dip data>> push ; inline +: image-resource-path ( path -- images-path ) + normalize-path current-directory get drop-prefix drop + "/images" prepend ; + +: img-tag ( xml style -- xml ) + image swap at [ nip image-resource-path simple-image ] when* ; + : format-html-span ( string style stream -- ) - [ [ span-tag ] [ href-link-tag ] [ object-link-tag ] tri ] - emit-html ; + [ + { + [ span-tag ] + [ href-link-tag ] + [ object-link-tag ] + [ img-tag ] + } cleave + ] emit-html ; TUPLE: html-span-stream < html-sub-stream ; From bea4aa76624e94a66360ae9b79afc8b938e6a65f Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Tue, 22 Sep 2009 15:22:34 -0400 Subject: [PATCH 08/45] docs: updated some docs to use new markup --- basis/grouping/grouping-docs.factor | 18 +- basis/math/functions/functions-docs.factor | 125 +++--- .../combinators/combinators-docs.factor | 21 +- basis/regexp/regexp-docs.factor | 42 ++- core/combinators/combinators-docs.factor | 140 +++---- core/math/parser/parser-docs.factor | 24 +- core/sequences/sequences-docs.factor | 357 +++++++++--------- core/sorting/sorting-docs.factor | 14 +- 8 files changed, 356 insertions(+), 385 deletions(-) diff --git a/basis/grouping/grouping-docs.factor b/basis/grouping/grouping-docs.factor index 07250058ae..d64745b834 100644 --- a/basis/grouping/grouping-docs.factor +++ b/basis/grouping/grouping-docs.factor @@ -3,17 +3,13 @@ IN: grouping ARTICLE: "grouping" "Groups and clumps" "Splitting a sequence into disjoint, fixed-length subsequences:" -{ $subsection group } +{ $subsections group } "A virtual sequence for splitting a sequence into disjoint, fixed-length subsequences:" -{ $subsection groups } -{ $subsection } -{ $subsection } +{ $subsections groups } "Splitting a sequence into overlapping, fixed-length subsequences:" -{ $subsection clump } +{ $subsections clump } "A virtual sequence for splitting a sequence into overlapping, fixed-length subsequences:" -{ $subsection clumps } -{ $subsection } -{ $subsection } +{ $subsections clumps } "The difference can be summarized as the following:" { $list { "With groups, the subsequences form the original sequence when concatenated:" @@ -29,11 +25,11 @@ ARTICLE: "grouping" "Groups and clumps" } } } +$nl "A combinator built using clumps:" -{ $subsection monotonic? } +{ $subsections monotonic? } "Testing how elements are related:" -{ $subsection all-eq? } -{ $subsection all-equal? } ; +{ $subsections all-eq? all-equal? } ; ABOUT: "grouping" diff --git a/basis/math/functions/functions-docs.factor b/basis/math/functions/functions-docs.factor index d61ad9a14a..2735fa3903 100644 --- a/basis/math/functions/functions-docs.factor +++ b/basis/math/functions/functions-docs.factor @@ -3,102 +3,95 @@ sequences quotations math.functions.private ; IN: math.functions ARTICLE: "integer-functions" "Integer functions" -{ $subsection align } -{ $subsection gcd } -{ $subsection log2 } -{ $subsection next-power-of-2 } +{ $subsections + align + gcd + log2 + next-power-of-2 +} "Modular exponentiation:" -{ $subsection ^mod } -{ $subsection mod-inv } +{ $subsections ^mod mod-inv } "Tests:" -{ $subsection power-of-2? } -{ $subsection even? } -{ $subsection odd? } -{ $subsection divisor? } ; +{ $subsections + power-of-2? + even? + odd? + divisor? +} ; ARTICLE: "arithmetic-functions" "Arithmetic functions" "Computing additive and multiplicative inverses:" -{ $subsection neg } -{ $subsection recip } +{ $subsections neg recip } "Complex conjugation:" -{ $subsection conjugate } +{ $subsections conjugate } "Tests:" -{ $subsection zero? } -{ $subsection between? } +{ $subsections zero? between? } "Control flow:" -{ $subsection if-zero } -{ $subsection when-zero } -{ $subsection unless-zero } +{ $subsections + if-zero + when-zero + unless-zero +} "Sign:" -{ $subsection sgn } +{ $subsections sgn } "Rounding:" -{ $subsection ceiling } -{ $subsection floor } -{ $subsection truncate } -{ $subsection round } +{ $subsections + ceiling + floor + truncate + round +} "Inexact comparison:" -{ $subsection ~ } +{ $subsections ~ } "Numbers implement the " { $link "math.order" } ", therefore operations such as " { $link min } " and " { $link max } " can be used with numbers." ; ARTICLE: "power-functions" "Powers and logarithms" "Squares:" -{ $subsection sq } -{ $subsection sqrt } +{ $subsections sq sqrt } "Exponential and natural logarithm:" -{ $subsection exp } -{ $subsection cis } -{ $subsection log } -{ $subsection log1+ } -{ $subsection log10 } +{ $subsections + exp + cis + log + log1+ + log10 +} "Raising a number to a power:" -{ $subsection ^ } -{ $subsection 10^ } +{ $subsections ^ 10^ } "Converting between rectangular and polar form:" -{ $subsection abs } -{ $subsection absq } -{ $subsection arg } -{ $subsection >polar } -{ $subsection polar> } ; +{ $subsections + abs + absq + arg + >polar + polar> +} ; ARTICLE: "trig-hyp-functions" "Trigonometric and hyperbolic functions" "Trigonometric functions:" -{ $subsection cos } -{ $subsection sin } -{ $subsection tan } +{ $subsections cos sin tan } "Reciprocals:" -{ $subsection sec } -{ $subsection cosec } -{ $subsection cot } +{ $subsections sec cosec cot } "Inverses:" -{ $subsection acos } -{ $subsection asin } -{ $subsection atan } +{ $subsections acos asin atan } "Inverse reciprocals:" -{ $subsection asec } -{ $subsection acosec } -{ $subsection acot } +{ $subsections asec acosec acot } "Hyperbolic functions:" -{ $subsection cosh } -{ $subsection sinh } -{ $subsection tanh } +{ $subsections cosh sinh tanh } "Reciprocals:" -{ $subsection sech } -{ $subsection cosech } -{ $subsection coth } +{ $subsections sech cosech coth } "Inverses:" -{ $subsection acosh } -{ $subsection asinh } -{ $subsection atanh } +{ $subsections acosh asinh atanh } "Inverse reciprocals:" -{ $subsection asech } -{ $subsection acosech } -{ $subsection acoth } ; +{ $subsections asech acosech acoth } ; ARTICLE: "math-functions" "Mathematical functions" -{ $subsection "integer-functions" } -{ $subsection "arithmetic-functions" } -{ $subsection "power-functions" } -{ $subsection "trig-hyp-functions" } ; +{ $subsections + "integer-functions" + "arithmetic-functions" + "power-functions" + "trig-hyp-functions" +} ; ABOUT: "math-functions" diff --git a/basis/regexp/combinators/combinators-docs.factor b/basis/regexp/combinators/combinators-docs.factor index a49b16b585..20d5624025 100644 --- a/basis/regexp/combinators/combinators-docs.factor +++ b/basis/regexp/combinators/combinators-docs.factor @@ -18,20 +18,21 @@ ARTICLE: "regexp.combinators.intro" "Regular expression combinator rationale" ARTICLE: "regexp.combinators" "Regular expression combinators" "The " { $vocab-link "regexp.combinators" } " vocabulary defines combinators which can be used to build up regular expressions to match strings. This complements the traditional syntax defined in the " { $vocab-link "regexp" } " vocabulary." -{ $subsection "regexp.combinators.intro" } +{ $subsections "regexp.combinators.intro" } "Basic combinators:" -{ $subsection } -{ $subsection } +{ $subsections } "Higher-order combinators for building new regular expressions from existing ones:" -{ $subsection } -{ $subsection } -{ $subsection } -{ $subsection } -{ $subsection } +{ $subsections + + + + + +} "Derived combinators implemented in terms of the above:" -{ $subsection } +{ $subsections } "Setting options:" -{ $subsection