basis/wrap/words/words-docs.factor

   1 ! Copyright (C) 2009 Daniel Ehrenberg
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup math kernel ;
   4 IN: wrap.words
   5
   6 ABOUT: "wrap.words"
   7
   8 ARTICLE: "wrap.words" "Word object wrapping"
   9 "The " { $vocab-link "wrap.words" } " vocabulary implements word wrapping on abstract word objects, which have certain properties making it a more suitable input representation than strings."
  10 { $subsections
  11     wrap-words
  12     word
  13     <word>
  14 } ;
  15
  16 HELP: wrap-words
  17 { $values { "words" { "a sequence of " { $instance word } "s" } } { "line-max" integer } { "line-ideal" integer } { "lines" "a sequence of sequences of words" } }
  18 { $description "Divides the words into lines, where the sum of the lengths of the words on a line (not counting breaks at the end of the line) is at most the given maximum. The returned set of lines is optimized to minimize the square of the deviation of each line from the ideal width. It is not guaranteed to be the minimal number of lines. Every line except for the first one starts with a non-break, and every one but the last ends with a break." } ;
  19
  20 HELP: word
  21 { $class-description "A word is a Factor object annotated with a length (in the " { $snippet "width" } " slot) and knowledge about whether it is an allowable position for an optional line break (in the " { $snippet "break?" } " slot). Words can be created with " { $link <word> } "." }
  22 { $see-also wrap-words } ;
  23
  24 HELP: <word>
  25 { $values { "key" object } { "width" integer } { "break?" { { $link t } " or " { $link POSTPONE: f } } } { "word" word } }
  26 { $description "Creates a " { $link word } " object with the given parameters." }
  27 { $see-also wrap-words } ;