# HG changeset patch # User Steve Losh # Date 1551980549 18000 # Node ID 1efadc1bb82726ad8eaa0471de2c627adeff0991 # Parent abcdae1786b646e44ff46979faa37e1e91116b29 Fix docs diff -r abcdae1786b6 -r 1efadc1bb827 Makefile --- a/Makefile Wed Nov 21 23:21:10 2018 -0500 +++ b/Makefile Thu Mar 07 12:42:29 2019 -0500 @@ -1,6 +1,9 @@ -.PHONY: test test-sbcl test-ccl test-ecl test-abcl +.PHONY: test test-sbcl test-ccl test-ecl test-abcl pubdocs heading_printer = $(shell which heading || echo 'true') +sourcefiles = $(shell ffind --full-path --literal .lisp) +docfiles = $(shell ls docs/*.markdown) +apidocs = $(shell ls docs/*reference*.markdown) # Testing --------------------------------------------------------------------- test: test-sbcl test-ccl test-ecl test-abcl @@ -20,3 +23,18 @@ test-abcl: $(heading_printer) broadway 'ABCL' abcl --load test/run.lisp + +# Documentation --------------------------------------------------------------- +$(apidocs): $(sourcefiles) + sbcl --noinform --load docs/api.lisp --eval '(quit)' + +docs/build/index.html: $(docfiles) $(apidocs) docs/title + cd docs && ~/.virtualenvs/d/bin/d + +docs: docs/build/index.html + +pubdocs: docs + hg -R ~/src/sjl.bitbucket.org pull -u + rsync --delete -a ./docs/build/ ~/src/sjl.bitbucket.org/bobbin + hg -R ~/src/sjl.bitbucket.org commit -Am 'bobbin: Update site.' + hg -R ~/src/sjl.bitbucket.org push diff -r abcdae1786b6 -r 1efadc1bb827 README.markdown --- a/README.markdown Wed Nov 21 23:21:10 2018 -0500 +++ b/README.markdown Thu Mar 07 12:42:29 2019 -0500 @@ -18,101 +18,16 @@ `───────────' ``` -Bobbin is a simple (50 LOC) word-wrapping library for strings in Common Lisp. -It depends only on `split-sequence`. +Bobbin is a simple word-wrapping library for strings in Common Lisp. It depends +only on `split-sequence`. It aims to be simple, work nicely for the majority of cases, and degrade gracefully for edge cases. It is not particularly concerned with speed — if you need very high-performance word wrapping Bobbin is not for you. +Bobbin can be installed with Quicklisp: `(ql:quickload :bobbin)`. + * **License:** MIT -* **Documentation:** (this `README`) +* **Documentation:** * **Mercurial:** * **Git:** - -Documentation -------------- - -Bobbin's API only has a single function: - - (bobbin:wrap string-or-strings width) - -The simplest way to use Bobbin is to pass it a string: - - (bobbin:wrap "hello, world!" 10) - "hello, - world!" - -Every line in the string returned by `wrap` will contain at most `width` -characters (not including the newline itself). - -Philosophy ----------- - -Bobbin will try to break lines at whitespace. It will only break a word in the -middle if there's no other choice. It does not try to hyphenate, or parse -hyphenation: - - (bobbin:wrap "This is a test of Bobbin's line-breaking." 10) - "This is a - test of - Bobbin's - line-break - ing." - -Initial whitespace (e.g. indentation) will be preserved, unless even the first -word cannot be fit if it were included. Bobbin does not try to indent any -broken lines, but this may be added in the future: - - (bobbin:wrap " foo bar baz" 10) - " foo - bar baz" - - (bobbin:wrap " thisisjusttoolong" 10) - "thisisjust - toolong" - -Whitespace between words will be preserved, unless a line is broken at that -point. This does the right thing for those of us who put two spaces after -a period, [as God -intended](https://web.archive.org/web/20171125050610/http://www.heracliteanriver.com/?p=324): - - (bobbin:wrap "there are two spaces between these words" 12) - "there are - two spaces - between - these words" - -Existing line breaks in the text are preserved. Bobbin will only ever *add* -line breaks, never remove them: - - (bobbin:wrap (format nil "foo~%bar baz frob") 7) - "foo - bar baz - frob" - -Lists ------ - -For convenience, you can also pass `wrap` a list of strings. Each string is -treated as a separate line and wrapped as described above. The results are -returned as a (flat) list of lines, each of which will be no more than `width` -characters long: - - (bobbin:wrap '("here is a line." "" "and here is another line") 8) - ("here is" - "a line." - "" - "and here" - "is" - "another" - "line") - -TODO ----- - -* Handle tab characters. -* Handle non-printing characters. -* Handle wide characters. -* `unwrap` function to make writing paragraphs easier. -* Maybe reindent broken lines? diff -r abcdae1786b6 -r 1efadc1bb827 docs/01-usage.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/01-usage.markdown Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,92 @@ +Usage +===== + +Bobbin's API only has a single function: + + (bobbin:wrap string-or-strings width) + +The simplest way to use Bobbin is to pass it a string: + + (bobbin:wrap "hello, world!" 10) + "hello, + world!" + +Every line in the string returned by `wrap` will contain at most `width` +characters (not including the newline itself). + +Philosophy +---------- + +Bobbin will try to break lines at whitespace. It will only break a word in the +middle if there's no other choice. It does not try to hyphenate, or parse +hyphenation: + + (bobbin:wrap "This is a test of Bobbin's line-breaking." 10) + "This is a + test of + Bobbin's + line-break + ing." + +Initial whitespace (e.g. indentation) will be preserved, unless even the first +word cannot be fit if it were included. Bobbin does not try to indent any +broken lines, but this may be added in the future: + + (bobbin:wrap " foo bar baz" 10) + " foo + bar baz" + + (bobbin:wrap " thisisjusttoolong" 10) + "thisisjust + toolong" + +Whitespace between words will be preserved, unless a line is broken at that +point. This does the right thing for those of us who put two spaces after +a period, [as God +intended](https://web.archive.org/web/20171125050610/http://www.heracliteanriver.com/?p=324): + + (bobbin:wrap "there are two spaces between these words" 12) + "there are + two spaces + between + these words" + +Existing line breaks in the text are preserved. Bobbin will only ever *add* +line breaks, never remove them: + + (bobbin:wrap (format nil "foo~%bar baz frob") 7) + "foo + bar baz + frob" + +Lists +----- + +For convenience, you can also pass `wrap` a list of strings. Each string is +treated as a separate line and wrapped as described above. The results are +returned as a (flat) list of lines, each of which will be no more than `width` +characters long: + + (bobbin:wrap (list "here is a line." + "" + "and here is another line") + 8) + ("here is" + "a line." + "" + "and here" + "is" + "another" + "line") + +Possible Future Features +------------------------ + +Bobbin aims to be simple, but may grow a bit more functionality in the future +(PRs welcome): + +* Handle tab characters. +* Handle non-printing characters. +* Handle wide characters. +* `unwrap` function to make writing paragraphs easier. +* Maybe reindent broken lines? diff -r abcdae1786b6 -r 1efadc1bb827 docs/02-reference.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/02-reference.markdown Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,51 @@ +# API Reference + +The following is a list of all user-facing parts of Bobbin. + +If there are backwards-incompatible changes to anything listed here, they will +be noted in the changelog and the author will feel bad. + +Anything not listed here is subject to change at any time with no warning, so +don't touch it. + +[TOC] + +## Package `BOBBIN` + +### `WRAP` (function) + + (WRAP STRING-OR-STRINGS WIDTH) + +Wrap `string-or-strings` to `width`. + + `string-or-strings` can be a string or a list of strings. A list of strings + is treated as multiple lines. In either case the string(s) may also contain + newlines. All of these linebreaks will be included in the output — wrapping + will only add linebreaks, never remove them. + + The result with be of the same type as the argument: either a single string + (containing newlines) or a list of strings (not containing newlines). + + Examples: + + (print (wrap (format nil "foo bar baz") 3)) + foo + bar + baz + + (print (wrap (format nil "foo bar baz") 7)) + foo bar + baz + + (print (wrap (format nil "foo~%bar baz") 7)) + foo + bar baz + + (print (wrap '("foo" "bar baz") 7)) + ("foo" "bar baz") + + (print (wrap '("foo" "bar baz") 3)) + ("foo" "bar" "baz") + + + diff -r abcdae1786b6 -r 1efadc1bb827 docs/03-changelog.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/03-changelog.markdown Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,11 @@ +Changelog +========= + +Here's the list of changes in each released version. + +[TOC] + +v1.0.0 +------ + +Initial version. diff -r abcdae1786b6 -r 1efadc1bb827 docs/api.lisp --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api.lisp Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,22 @@ +(ql:quickload "cl-d-api") + +(defparameter *header* + "The following is a list of all user-facing parts of Bobbin. + +If there are backwards-incompatible changes to anything listed here, they will +be noted in the changelog and the author will feel bad. + +Anything not listed here is subject to change at any time with no warning, so +don't touch it. + +") + +(d-api:generate-documentation + :bobbin + #p"docs/02-reference.markdown" + (list "BOBBIN") + *header* + :title "API Reference") + + + diff -r abcdae1786b6 -r 1efadc1bb827 docs/footer.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/footer.markdown Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,3 @@ +Created by [Steve Losh](http://stevelosh.com). + +
Rochester Made diff -r abcdae1786b6 -r 1efadc1bb827 docs/index.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.markdown Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,13 @@ +Bobbin is a simple word-wrapping library for strings in Common Lisp. It depends +only on `split-sequence`. + +It aims to be simple, work nicely for the majority of cases, and degrade +gracefully for edge cases. It is not particularly concerned with speed — if you +need very high-performance word wrapping Bobbin is not for you. + +Bobbin can be installed with Quicklisp: `(ql:quickload :bobbin)`. + +* **License:** MIT +* **Documentation:** +* **Mercurial:** +* **Git:** diff -r abcdae1786b6 -r 1efadc1bb827 docs/title --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/title Thu Mar 07 12:42:29 2019 -0500 @@ -0,0 +1,1 @@ +Bobbin