1efadc1bb827

Fix docs
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Thu, 07 Mar 2019 12:42:29 -0500
parents abcdae1786b6
children a9ab8d792a4d
branches/tags (none)
files Makefile README.markdown docs/01-usage.markdown docs/02-reference.markdown docs/03-changelog.markdown docs/api.lisp docs/footer.markdown docs/index.markdown docs/title

Changes

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:** <http://github.com/sjl/bobbin/> (this `README`)
+* **Documentation:** <https://sjl.bitbucket.io/bobbin/>
 * **Mercurial:** <http://bitbucket.org/sjl/bobbin/>
 * **Git:** <http://github.com/sjl/bobbin/>
-
-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).
+
+<br/><a id='rochester-made' href='http://rochestermade.com' title='Rochester Made'><img src='http://rochestermade.com/media/images/rochester-made-dark-on-light.png' alt='Rochester Made' title='Rochester Made' /></a>
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:** <https://sjl.bitbucket.io/bobbin/>
+* **Mercurial:** <http://bitbucket.org/sjl/bobbin/>
+* **Git:** <http://github.com/sjl/bobbin/>
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