From aba1dbabcf35be21a60191f0088912f82530c523 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philipp=20Br=C3=BCschweiler?= <blei42@gmail.com>
Date: Wed, 11 Feb 2009 20:56:09 +0100
Subject: [PATCH 1/6] infix: added meta information and fixed up docs somewhat

---
 extra/infix/ast/ast.factor                   |  2 +
 extra/infix/authors.txt                      |  1 +
 extra/infix/infix-docs.factor                | 55 +++++++++++++++++++-
 extra/infix/infix-tests.factor               |  2 +
 extra/infix/infix.factor                     |  2 +
 extra/infix/parser/parser-tests.factor       |  2 +
 extra/infix/parser/parser.factor             |  2 +
 extra/infix/summary.txt                      |  1 +
 extra/infix/tags.txt                         |  1 +
 extra/infix/tokenizer/tokenizer-tests.factor |  2 +
 extra/infix/tokenizer/tokenizer.factor       |  2 +
 11 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 extra/infix/authors.txt
 create mode 100644 extra/infix/summary.txt
 create mode 100644 extra/infix/tags.txt

diff --git a/extra/infix/ast/ast.factor b/extra/infix/ast/ast.factor
index 0bc22feeb7..1908b3d39b 100644
--- a/extra/infix/ast/ast.factor
+++ b/extra/infix/ast/ast.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 IN: infix.ast
 
 TUPLE: ast-number value ;
diff --git a/extra/infix/authors.txt b/extra/infix/authors.txt
new file mode 100644
index 0000000000..156a81af57
--- /dev/null
+++ b/extra/infix/authors.txt
@@ -0,0 +1 @@
+Philipp Brüschweiler
diff --git a/extra/infix/infix-docs.factor b/extra/infix/infix-docs.factor
index 7a4febb514..4a2ec963ee 100644
--- a/extra/infix/infix-docs.factor
+++ b/extra/infix/infix-docs.factor
@@ -1,4 +1,6 @@
-USING: help.syntax help.markup prettyprint locals ;
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.syntax help.markup math prettyprint locals sequences ;
 IN: infix
 
 HELP: [infix
@@ -36,3 +38,54 @@ HELP: [infix|
 } ;
 
 { POSTPONE: [infix POSTPONE: [infix| } related-words
+
+ARTICLE: "infix" "Infix notation"
+"The " { $vocab-link "infix" } " vocabulary implements support for infix notation in Factor source code."
+{ $subsection POSTPONE: [infix }
+{ $subsection POSTPONE: [infix| }
+$nl
+"The usual infix math operators are supported:"
+{ $list
+    { $link + }
+    { $link - }
+    { $link * }
+    { $link / }
+    { { $snippet "%" } ", which is the infix operator for " { $link mod } "." }
+}
+"The standard precedence rules apply: Grouping with parentheses before " { $snippet "*" } ", " { $snippet "/" } "and " { $snippet "%" } " before " { $snippet "+" } " and " { $snippet "-" } "."
+{ $example
+    "USING: infix prettyprint ;"
+    "[infix 5-40/10*2 infix] ."
+    "-3"
+}
+$nl
+"You can call Factor words in infix expressions just as you would in C. There are some restrictions on which words are legal to use though:"
+{ $list
+    "The word must return exactly one value."
+    "The word name must consist of the letters a-z, A-Z, _ or 0-9, and the first character can't be a number."
+}
+{ $example
+    "USING: infix locals math math.functions prettyprint ;"
+    ":: binary_entropy ( p -- h )"
+    "    [infix -(p*log(p) + (1-p)*log(1-p)) / log(2) infix] ;"
+    "[infix binary_entropy( sqrt(0.25) ) infix] ."
+    "1.0"
+}
+$nl
+"You can access " { $vocab-link "sequences" } " inside infix expressions with the familiar " { $snippet "arr[index]" } " notation."
+{ $example
+    "USING: arrays infix prettyprint ;"
+    "[infix| myarr [ { 1 2 3 4 } ] | myarr[4/2]*3 infix] ."
+    "9"
+}
+"Please note: in Factor " { $emphasis "fixnums are sequences too." } " If you are not careful with sequence accesses you may introduce subtle bugs:"
+{ $example
+    "USING: arrays infix locals prettyprint ;"
+    ":: add-2nd-element ( x y -- res )"
+    "    [infix x[1] + y[1] infix] ;"
+    "{ 1 2 3 } 5 add-2nd-element ."
+    "3"
+}
+;
+
+ABOUT: "infix"
diff --git a/extra/infix/infix-tests.factor b/extra/infix/infix-tests.factor
index 5ee6468131..7e8e2dfcc9 100644
--- a/extra/infix/infix-tests.factor
+++ b/extra/infix/infix-tests.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 USING: infix infix.private kernel locals math math.functions
 tools.test ;
 IN: infix.tests
diff --git a/extra/infix/infix.factor b/extra/infix/infix.factor
index 31cd1cbe1f..3e2ba49e3c 100644
--- a/extra/infix/infix.factor
+++ b/extra/infix/infix.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 USING: accessors assocs combinators combinators.short-circuit
 effects fry infix.parser infix.ast kernel locals.parser
 locals.types math multiline namespaces parser quotations
diff --git a/extra/infix/parser/parser-tests.factor b/extra/infix/parser/parser-tests.factor
index 0a0288c41b..d6b5d0559c 100644
--- a/extra/infix/parser/parser-tests.factor
+++ b/extra/infix/parser/parser-tests.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 USING: infix.ast infix.parser infix.tokenizer tools.test ;
 IN: infix.parser.tests
 
diff --git a/extra/infix/parser/parser.factor b/extra/infix/parser/parser.factor
index beaf3c335d..2f9ab03d18 100644
--- a/extra/infix/parser/parser.factor
+++ b/extra/infix/parser/parser.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 USING: infix.ast infix.tokenizer kernel math peg.ebnf sequences
 strings vectors ;
 IN: infix.parser
diff --git a/extra/infix/summary.txt b/extra/infix/summary.txt
new file mode 100644
index 0000000000..63d366d203
--- /dev/null
+++ b/extra/infix/summary.txt
@@ -0,0 +1 @@
+Support for infix notation in Factor programs
diff --git a/extra/infix/tags.txt b/extra/infix/tags.txt
new file mode 100644
index 0000000000..f4274299b1
--- /dev/null
+++ b/extra/infix/tags.txt
@@ -0,0 +1 @@
+extensions
diff --git a/extra/infix/tokenizer/tokenizer-tests.factor b/extra/infix/tokenizer/tokenizer-tests.factor
index 7e1fb005ef..f9c908414a 100644
--- a/extra/infix/tokenizer/tokenizer-tests.factor
+++ b/extra/infix/tokenizer/tokenizer-tests.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 USING: infix.ast infix.tokenizer tools.test ;
 IN: infix.tokenizer.tests
 
diff --git a/extra/infix/tokenizer/tokenizer.factor b/extra/infix/tokenizer/tokenizer.factor
index 8c1a1b4a18..f5bce4b6d7 100644
--- a/extra/infix/tokenizer/tokenizer.factor
+++ b/extra/infix/tokenizer/tokenizer.factor
@@ -1,3 +1,5 @@
+! Copyright (C) 2009 Philipp Brüschweiler
+! See http://factorcode.org/license.txt for BSD license.
 USING: infix.ast kernel peg peg.ebnf math.parser sequences
 strings ;
 IN: infix.tokenizer

From e8657995b650b3eab66a5310aca126e444de61c8 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Wed, 11 Feb 2009 18:35:08 -0600
Subject: [PATCH 2/6] code annotations toy

---
 extra/annotations/annotations.factor | 41 ++++++++++++++++++++++++++++
 extra/annotations/authors.txt        |  2 ++
 extra/annotations/summary.txt        |  1 +
 extra/annotations/tags.txt           |  2 ++
 4 files changed, 46 insertions(+)
 create mode 100644 extra/annotations/annotations.factor
 create mode 100644 extra/annotations/authors.txt
 create mode 100644 extra/annotations/summary.txt
 create mode 100644 extra/annotations/tags.txt

diff --git a/extra/annotations/annotations.factor b/extra/annotations/annotations.factor
new file mode 100644
index 0000000000..5102a36a71
--- /dev/null
+++ b/extra/annotations/annotations.factor
@@ -0,0 +1,41 @@
+! (c)2009 Joe Groff, Doug Coleman. see BSD license
+USING: accessors combinators.short-circuit definitions functors
+kernel lexer namespaces parser prettyprint sequences words ;
+IN: annotations
+
+<<
+
+: (parse-annotation) ( accum -- accum )
+    lexer get [ line-text>> parsed ] [ next-line ] bi ;
+
+: (non-annotation-usage) ( word -- usages )
+    smart-usage
+    [ { [ word? ] [ vocabulary>> "annotations" = not ] } 1&& ]
+    filter ;
+
+FUNCTOR: define-annotation ( NAME -- )
+
+(NAME) DEFINES (${NAME})
+!NAME  DEFINES !${NAME}
+NAMEs  DEFINES ${NAME}s
+NAMEs. DEFINES ${NAME}s.
+
+WHERE
+
+: (NAME) ( str -- ) drop ; inline
+: !NAME (parse-annotation) \ (NAME) parsed ; parsing
+
+: NAMEs ( -- usages )
+    \ (NAME) (non-annotation-usage) ;
+: NAMEs. ( -- )
+    NAMEs sorted-definitions. ;
+
+;FUNCTOR
+
+{
+    "XXX" "TODO" "FIXME" "BUG" "REVIEW" "LICENSE"
+    "AUTHOR" "BROKEN" "HACK" "LOL" "NOTE"
+} [ define-annotation ] each
+
+>>
+
diff --git a/extra/annotations/authors.txt b/extra/annotations/authors.txt
new file mode 100644
index 0000000000..0bc3c5ad4d
--- /dev/null
+++ b/extra/annotations/authors.txt
@@ -0,0 +1,2 @@
+Joe Groff
+Doug Coleman
diff --git a/extra/annotations/summary.txt b/extra/annotations/summary.txt
new file mode 100644
index 0000000000..732ed6f988
--- /dev/null
+++ b/extra/annotations/summary.txt
@@ -0,0 +1 @@
+Code annotation comment syntax
diff --git a/extra/annotations/tags.txt b/extra/annotations/tags.txt
new file mode 100644
index 0000000000..278296de5e
--- /dev/null
+++ b/extra/annotations/tags.txt
@@ -0,0 +1,2 @@
+comments
+annotation

From 6c723642bd5ae573ded152c9bee1bdfa50178fd3 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Wed, 11 Feb 2009 18:42:01 -0600
Subject: [PATCH 3/6] annotations tests

---
 extra/annotations/annotations-tests.factor | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 extra/annotations/annotations-tests.factor

diff --git a/extra/annotations/annotations-tests.factor b/extra/annotations/annotations-tests.factor
new file mode 100644
index 0000000000..72fd0f8b74
--- /dev/null
+++ b/extra/annotations/annotations-tests.factor
@@ -0,0 +1,17 @@
+USING: annotations math sorting tools.test ;
+IN: annotations.tests
+
+: three ( -- x )
+    !BROKEN find a dictionary
+    "threa" ;
+
+: four ( -- x )
+    !BROKEN this code is broken
+    2 2 + 1+ ;
+
+: five ( -- x )
+    !TODO return 5
+    f ;
+
+[ { four three } ] [ BROKENs natural-sort ] unit-test
+[ { five } ] [ TODOs ] unit-test

From 87c9ab72c325d2ea376a9ea5dd45bbd6db161b9e Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Wed, 11 Feb 2009 18:58:42 -0600
Subject: [PATCH 4/6] don't want to filter nonword annotation usages

---
 extra/annotations/annotations-tests.factor | 16 +++++++++++++---
 extra/annotations/annotations.factor       |  2 +-
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/extra/annotations/annotations-tests.factor b/extra/annotations/annotations-tests.factor
index 72fd0f8b74..d5a13e48d8 100644
--- a/extra/annotations/annotations-tests.factor
+++ b/extra/annotations/annotations-tests.factor
@@ -1,9 +1,12 @@
-USING: annotations math sorting tools.test ;
+USING: accessors annotations combinators.short-circuit
+io.pathnames kernel math sequences sorting tools.test ;
 IN: annotations.tests
 
+!NOTE testing toplevel form 
+
 : three ( -- x )
-    !BROKEN find a dictionary
-    "threa" ;
+    !BROKEN english plz
+    "þrij" ;
 
 : four ( -- x )
     !BROKEN this code is broken
@@ -13,5 +16,12 @@ IN: annotations.tests
     !TODO return 5
     f ;
 
+[ t ] [
+    NOTEs {
+        [ length 1 = ]
+        [ first string>> file-name "annotations-tests.factor" = ]
+    } 1&&
+] unit-test
+
 [ { four three } ] [ BROKENs natural-sort ] unit-test
 [ { five } ] [ TODOs ] unit-test
diff --git a/extra/annotations/annotations.factor b/extra/annotations/annotations.factor
index 5102a36a71..c61250b89d 100644
--- a/extra/annotations/annotations.factor
+++ b/extra/annotations/annotations.factor
@@ -10,7 +10,7 @@ IN: annotations
 
 : (non-annotation-usage) ( word -- usages )
     smart-usage
-    [ { [ word? ] [ vocabulary>> "annotations" = not ] } 1&& ]
+    [ { [ word? ] [ vocabulary>> "annotations" = ] } 1&& not ]
     filter ;
 
 FUNCTOR: define-annotation ( NAME -- )

From ff33f38a0296c5122f89080312f0fab4e656536e Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Wed, 11 Feb 2009 19:58:28 -0600
Subject: [PATCH 5/6] annotations docs

---
 extra/annotations/annotations-docs.factor | 42 +++++++++++++++++++++++
 extra/annotations/annotations.factor      |  6 ++--
 2 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100644 extra/annotations/annotations-docs.factor

diff --git a/extra/annotations/annotations-docs.factor b/extra/annotations/annotations-docs.factor
new file mode 100644
index 0000000000..c340554119
--- /dev/null
+++ b/extra/annotations/annotations-docs.factor
@@ -0,0 +1,42 @@
+USING: accessors arrays combinators definitions generalizations
+help help.markup help.topics kernel sequences sorting vocabs
+words ;
+IN: annotations
+
+<PRIVATE
+: comment-word ( base -- word ) "!" prepend "annotations" lookup ; 
+: comment-usage-word ( base -- word ) "s" append "annotations" lookup ; 
+: comment-usage.-word ( base -- word ) "s." append "annotations" lookup ; 
+PRIVATE>
+
+"Code annotations"
+{
+    "The " { $vocab-link "annotations" } " vocabulary provides syntax for comment-like annotations that can be looked up with Factor's " { $link usage } " mechanism."
+}
+annotation-tags natural-sort
+[
+    [ \ $subsection swap comment-word 2array ] map append
+    "To look up annotations:" suffix
+] [
+    [ \ $subsection swap comment-usage.-word 2array ] map append
+] bi
+<article> "annotations" add-article
+
+"annotations" vocab "annotations" >>help drop
+
+annotation-tags [
+    {
+        [ [ \ $syntax ] dip "!" " your comment here" surround 2array ]
+        [ [ \ $description "Treats the rest of the line after the exclamation point as a code annotation that can be looked up with the " \ $link ] dip comment-usage.-word 2array " word." 4array ]
+        [ [ \ $unchecked-example ] dip ": foo ( x y z -- w )\n    !" " --w-ó()ò-w-- kilroy was here\n    + * ;" surround 2array 3array ]
+        [ comment-word set-word-help ]
+
+        [ [ \ $description "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 4array 1array ]
+        [ comment-usage.-word set-word-help ]
+
+        [ [ { $values { "usages" sequence } } \ $description "Returns a list of words, help articles, and vocabularies that contain " \ $link ] dip [ comment-word 2array " annotations. For a more user-friendly display, use the " \ $link ] [ comment-usage.-word 2array " word." 6 narray 2array ] bi ]
+        [ comment-usage-word set-word-help ]
+
+        [ [ comment-word ] [ comment-usage-word ] [ comment-usage.-word ] tri 3array related-words ]
+    } cleave
+] each
diff --git a/extra/annotations/annotations.factor b/extra/annotations/annotations.factor
index c61250b89d..6685e4e036 100644
--- a/extra/annotations/annotations.factor
+++ b/extra/annotations/annotations.factor
@@ -32,10 +32,12 @@ WHERE
 
 ;FUNCTOR
 
-{
+CONSTANT: annotation-tags {
     "XXX" "TODO" "FIXME" "BUG" "REVIEW" "LICENSE"
     "AUTHOR" "BROKEN" "HACK" "LOL" "NOTE"
-} [ define-annotation ] each
+}
+
+annotation-tags [ define-annotation ] each
 
 >>
 

From 0bc16d0cf82757516eff54ab37bb8823c52901cc Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Wed, 11 Feb 2009 20:11:33 -0600
Subject: [PATCH 6/6] documentation ambiguity

---
 basis/math/blas/vectors/vectors-docs.factor | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/basis/math/blas/vectors/vectors-docs.factor b/basis/math/blas/vectors/vectors-docs.factor
index 296437c32b..badc317189 100644
--- a/basis/math/blas/vectors/vectors-docs.factor
+++ b/basis/math/blas/vectors/vectors-docs.factor
@@ -93,7 +93,7 @@ HELP: Viamax
 
 HELP: Vamax
 { $values { "x" blas-vector-base } { "max" number } }
-{ $description "Return the value of the element in " { $snippet "x" } " with the largest norm-1. If more than one element has the same norm-1, returns the first element. Corresponds to the IxAMAX routines in BLAS." } ;
+{ $description "Return the value of the element in " { $snippet "x" } " with the largest norm-1. If more than one element has the same norm-1, returns the element closest to the beginning. Corresponds to the IxAMAX routines in BLAS." } ;
 
 { Viamax Vamax } related-words