commit 49c87d325f4a4e83960a1c4d34a13a85c6186c01
parent 3d7acc24cd060bad84fa3e7dbf008409925bb863
Author: Ed van Bruggen <edvb@uw.edu>
Date: Sat, 12 Jan 2019 18:18:23 -0800
Use markman to create man page
Move markdown and man pages to doc/ directory. Add more info to README.
Diffstat:
| Makefile | | | 15 | +++------------ |
| README.md | | | 59 | ----------------------------------------------------------- |
| README.md | | | 2 | ++ |
| doc/tisp.1 | | | 168 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| doc/tisp.1.md | | | 197 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| tisp.1 | | | 70 | ---------------------------------------------------------------------- |
6 files changed, 370 insertions(+), 141 deletions(-)
diff --git a/Makefile b/Makefile
@@ -49,7 +49,6 @@ install: all
@chmod 755 $(DESTDIR)$(PREFIX)/bin/$(EXE)
@echo installing manual page to $(DESTDIR)$(MANPREFIX)/man1
@mkdir -p $(DESTDIR)$(MANPREFIX)/man1
- @sed "s/VERSION/$(VERSION)/g" < $(EXE).1 > $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
@chmod 644 $(DESTDIR)$(MANPREFIX)/man1/$(EXE).1
@echo installing libraries to $(DESTDIR)$(PREFIX)/lib/tisp
@mkdir -p $(DESTDIR)$(PREFIX)/lib/tisp
@@ -70,16 +69,8 @@ test: $(OBJ) $(LIB) test.o
@./test
man:
- @echo -n updating man page $(EXE).1 ...
- @(head -1 README.md | sed "s/$(EXE)/$(EXE) 1 \"`date +%B\ %Y`\" \"$(EXE)\ $(VERSION)\"\n\n##NAME\n\n&/"; \
- echo "\n##SYNOPSIS\n"; \
- ./$(EXE) -h 2>&1 | sed -E 's/(\<[_A-Z][_A-Z]+\>)/\*\1\*/g' | \
- sed -E 's/(-[a-Z]+\>)/\*\*\1\*\*/g' | \
- sed -E 's/(\<$(EXE)\>)/\*\*\1\*\*/g' | \
- sed 's/_/\\_/g' | sed 's/:/:\ /g'| cut -d' ' -f2-; \
- echo "\n##DESCRIPTION"; \
- tail +2 README.md;) | \
- md2roff - | sed "9s/]/]\ /g" | sed "9s/|/|\ /g" > $(EXE).1
- @echo \ done
+ @echo updating man page doc/$(EXE).1
+ @markman -nCD -t TISP -V "$(VERSION)" -d "`date '+%B %Y'`" \
+ -s "`./$(EXE) -h 2>&1 | cut -d' ' -f2-`" doc/$(EXE).1.md > doc/$(EXE).1
.PHONY: all options clean install uninstall test man
diff --git a/README.md b/README.md
@@ -1,59 +0,0 @@
-# tisp \- tiny lisp
-
-[](https://travis-ci.org/edvb/tisp)
-
-Tiny lisp implementation, still in heavy development, barely even "useable."
-Designed to be scheme-like, ie very minimalist.
-
-## OPTIONS
-
-#### -h
-
-Print help and exit
-
-#### -v
-
-Print version info and exit
-
-## USAGE
-
-Run the program from the command line to launch the REPL, type a command and
-press enter to see the result.
-
-```
-$ tisp
-> (+ (+ 1 2) 3)
-6
-> (+ 1 2 3)
-6
-```
-
-Alternatively you can pass a file name which will be opened and run, outputting
-the result before exiting.
-
-```
-$ echo '(+ 1 2 3)' > add.lisp
-$ tisp add.lisp
-6
-```
-
-Commands can also be piped directing into tisp through the command line.
-
-```
-$ echo '(+ 1 2 3)' | tisp
-6
-```
-
-## AUTHOR
-
-Ed van Bruggen <edvb@uw.edu>
-
-## SEE ALSO
-
-See project page at <https://edryd.org/projects/tisp.html>
-
-View source code at <https://git.edryd.org/tisp>
-
-## LICENSE
-
-zlib License
diff --git a/README.md b/README.md
@@ -0,0 +1 @@
+doc/tisp.1.md+
\ No newline at end of file
diff --git a/doc/tisp.1 b/doc/tisp.1
@@ -0,0 +1,168 @@
+.TH TISP 1 "January 2019" "0.0.0"
+.PP
+.SH NAME
+tisp \- tiny lisp
+.PP
+.SH SYNOPSIS
+tisp [-hv] [FILENAME]
+.PP
+.SH DESCRIPTION
+.PP
+
+.PP
+tisp is a tiny lisp library designed to to be lightweight and easy to embedded in other programs. Simply drop the 'tisp.c' and 'tisp.h' files into your project and include the header file in order to use the necessary functions for your program. An example command line interpreter is provided in 'main.c'.
+.PP
+.SH OPTIONS
+.TP
+\fB-h\fP
+Print help and exit
+.PP
+.TP
+\fB-v\fP
+Print version info and exit
+.PP
+.SH USAGE
+.PP
+Run the program from the command line to launch the REPL, type a command and press enter to see the result.
+.PP
+.RS 4
+.EX
+
+$ tisp
+> (+ (+ 1 2) 3)
+6
+> (+ 1 2 3)
+6
+
+.EE
+.RE
+Alternatively you can pass a file name which will be opened and run, outputting the result before exiting.
+.PP
+.RS 4
+.EX
+
+$ echo '((lambda (x) (+ x 1)) 10)' > inc.lisp
+$ tisp inc.lisp
+11
+
+.EE
+.RE
+Commands can also be piped directing into tisp through the command line.
+.PP
+.RS 4
+.EX
+
+$ echo '(= "foo" "foo")' | tisp
+t
+
+.EE
+.RE
+.SH LANGUAGE
+.PP
+tisp is mainly based off of scheme, with minor features borrowed from other lisps.
+.PP
+.SS GENERAL
+.TP
+\fBComments\fP
+Single line comments with a semicolon, \fBeg\fP '(cons 1 2) ; ingnored by tisp until new line'.
+.PP
+.SS TYPES
+.TP
+\fBNil\fP
+Nil, null, empty, or false, represented as an empty list, \fBeg\fP '()'.
+.PP
+.TP
+\fBIntegers\fP
+Whole real numbers, positive or negative with optional '+' or '-' prefixes repressively. Also supports scientific notation with a capital or lowercase 'e'. The exponent also needs to be integer which can be positive or negative. \fBeg\fP '1', '-48', '+837e4', '3E-2'.
+.PP
+.TP
+\fBFloating Pointing\fP
+Floating point numbers, as know as decimals, are integers followed by a period and an optional integer with leading integers. Like integers can be positive or negative with scientific notation, but still need an integer as an exponent. \fBeg\fP '1.', '+3.14', '-43.00', '800.001e-3'.
+.PP
+.TP
+\fBRationals\fP
+Fraction type, a ratio of two integers. Similar rules apply for numerator and dominator as integers (real positive or negative), expect for scientific notation. Will try to simplify fraction where possible, and will through error on division by zero. \fBeg\fP '1/2', '4/3' '-1/2', '01/-30', '-6/-3'.
+.PP
+.TP
+\fBStrings\fP
+String of characters contained inside two double quotes. \fBeg\fP '"foo"', '"foo bar"'.
+.PP
+.TP
+\fBSymbols\fP
+Case sensitive symbols which can be used as variable names. Supports lower and upper case letters, numbers, as well as the characters '_+-*/=<>?'. First character can not be a number, if the first character is a '+' or '-' then the second digit cannot be a number either. Unlike all the previously listed types, symbols are not self evaluating, but instead return the value they are defined to. Throws an error if a symbol is evaluated without it being previously assigned a value. \fBeg\fP 'foo', 'foo-bar', 'cat9', '+', '>=', 'nil?'.
+.PP
+.TP
+\fBLists\fP
+Lists composed of one or more element of any other types, including lists them selves. Expressed with surrounding parentheses and each element is separated by white space. When evaluated runs the first element as function with the rest of the elements as arguments. Technically list is not a type, but simply a nil-terminating chain of nested pairs. A pair is a group of two and only two elements, normally represented as '(a . b)', with 'a' being the first element (car) and 'b' being the second element (cdr). for example '(a b c)' is actually '(a . (b . (c . ())))'. But it is often easier just to think of them as lists.
+.PP
+.TP
+\fBFunctions\fP
+Lambda functions created within tisp itself. Called using list syntax where the first element is the function name and any proceeding elements are the arguments. For example '(cadr '(1 2 3))' is a list of elements 'cadr' and ''(1 2 3)'. It calls the function 'cadr' which returns the 2nd element of the first argument given, here a list of size 3. In this case it return a '2'.
+.PP
+.TP
+\fBPrimitives\fP
+Functions built in to the language written in C. Called like regular functions, see primitives section for more details.
+.PP
+.SS PRIMITIVES
+.PP
+Built in primitives included by default.
+.PP
+.TP
+\fBcar\fP
+Returns first element of given list
+.PP
+.TP
+\fBcdr\fP
+Return rest of the given list, either just the second element if it is of size 2 or a pair, or a new list with the first element removed.
+.PP
+.TP
+\fBcons\fP
+Creates a new pair with the two given arguments, first one as the car, second as the cdr.
+.PP
+.TP
+\fB=\fP
+Tests if multiple values equal. Returns nil if any are not, and 't' otherwise.
+.PP
+.TP
+\fBquote\fP
+Returns the given argument unevaluated.
+.PP
+.TP
+\fBcond\fP
+Evaluates each expression if the given condition corresponding to it is true. Runs through any arguments, each is a list with the first element as the condition which needs to be 't' after evaluated, and the second element is the expression to be run if and only if the condition is met.
+.PP
+.TP
+\fBlambda\fP
+Creates function, first argument is a list of elements representing the symbol name for any arguments for the new function. Next argument is code to be run with the supplied arguments.
+.PP
+.TP
+\fBdefine\fP
+Create variable with the name of the first argument, with the value of the second.
+.PP
+.TP
+\fBload\fP
+Loads the library, given as a string.
+.PP
+.SS DIFFERENCES FROM OTHER LISPS
+.PP
+In tisp there are no boolean types, much like common lisp, true is represented by the self evaluating symbol 't' and false is nil, represented as '()', an empty list.
+.PP
+tisp also only has one equality primitive, '=', which tests integers, symbols, strings, and objects which occupy the same space in memory, such as primitives. It also accepts any number of arguments to compare.
+.PP
+Symbols are also case sensitive following the Unix way, unlike many other lisps.
+.PP
+.SH AUTHOR
+.PP
+Ed van Bruggen <edvb@uw.edu>
+.PP
+.SH SEE ALSO
+.PP
+See project page at <https://edryd.org/projects/tisp.html>
+.PP
+View source code at <https://git.edryd.org/tisp>
+.PP
+.SH LICENSE
+.PP
+zlib License
+.PP
+
diff --git a/doc/tisp.1.md b/doc/tisp.1.md
@@ -0,0 +1,197 @@
+# tisp \- tiny lisp
+
+[](https://travis-ci.org/edvb/tisp)
+
+tisp is a tiny lisp library designed to to be lightweight and easy to embedded
+in other programs. Simply drop the `tisp.c` and `tisp.h` files into your
+project and include the header file in order to use the necessary functions for
+your program. An example command line interpreter is provided in `main.c`.
+
+## Options
+
+#### -h
+
+Print help and exit
+
+#### -v
+
+Print version info and exit
+
+## Usage
+
+Run the program from the command line to launch the REPL, type a command and
+press enter to see the result.
+
+```
+$ tisp
+> (+ (+ 1 2) 3)
+6
+> (+ 1 2 3)
+6
+```
+
+Alternatively you can pass a file name which will be opened and run, outputting
+the result before exiting.
+
+```
+$ echo '((lambda (x) (+ x 1)) 10)' > inc.lisp
+$ tisp inc.lisp
+11
+```
+
+Commands can also be piped directing into tisp through the command line.
+
+```
+$ echo '(= "foo" "foo")' | tisp
+t
+```
+
+## Language
+
+tisp is mainly based off of scheme, with minor features borrowed from other
+lisps.
+
+### General
+
+#### Comments
+
+Single line comments with a semicolon, **eg** `(cons 1 2) ; ingnored by tisp until new line`.
+
+### Types
+
+#### Nil
+
+Nil, null, empty, or false, represented as an empty list, **eg** `()`.
+
+#### Integers
+
+Whole real numbers, positive or negative with optional `+` or `-` prefixes
+repressively. Also supports scientific notation with a capital or lowercase
+`e`. The exponent also needs to be integer which can be positive or negative.
+**eg** `1`, `-48`, `+837e4`, `3E-2`.
+
+#### Floating Pointing
+
+Floating point numbers, as know as decimals, are integers followed by a period
+and an optional integer with leading integers. Like integers can be positive or
+negative with scientific notation, but still need an integer as an exponent. **eg**
+`1.`, `+3.14`, `-43.00`, `800.001e-3`.
+
+#### Rationals
+
+Fraction type, a ratio of two integers. Similar rules apply for numerator and
+dominator as integers (real positive or negative), expect for scientific
+notation. Will try to simplify fraction where possible, and will through error
+on division by zero. **eg** `1/2`, `4/3` `-1/2`, `01/-30`, `-6/-3`.
+
+#### Strings
+
+String of characters contained inside two double quotes. **eg** `"foo"`, `"foo bar"`.
+
+#### Symbols
+
+Case sensitive symbols which can be used as variable names. Supports lower and
+upper case letters, numbers, as well as the characters `_+-*/=<>?`. First
+character can not be a number, if the first character is a `+` or `-` then the
+second digit cannot be a number either. Unlike all the previously listed types,
+symbols are not self evaluating, but instead return the value they are defined
+to. Throws an error if a symbol is evaluated without it being previously
+assigned a value. **eg** `foo`, `foo-bar`, `cat9`, `+`, `>=`, `nil?`.
+
+#### Lists
+
+Lists composed of one or more element of any other types, including lists them
+selves. Expressed with surrounding parentheses and each element is separated by
+white space. When evaluated runs the first element as function with the rest of
+the elements as arguments. Technically list is not a type, but simply a
+nil-terminating chain of nested pairs. A pair is a group of two and only two
+elements, normally represented as `(a . b)`, with `a` being the first element
+(car) and `b` being the second element (cdr). for example `(a b c)` is actually
+`(a . (b . (c . ())))`. But it is often easier just to think of them as lists.
+
+#### Functions
+
+Lambda functions created within tisp itself. Called using list syntax where the
+first element is the function name and any proceeding elements are the
+arguments. For example `(cadr '(1 2 3))` is a list of elements `cadr` and `'(1
+2 3)`. It calls the function `cadr` which returns the 2nd element of the first
+argument given, here a list of size 3. In this case it return a `2`.
+
+#### Primitives
+
+Functions built in to the language written in C. Called like regular functions,
+see primitives section for more details.
+
+### Primitives
+
+Built in primitives included by default.
+
+#### car
+
+Returns first element of given list
+
+#### cdr
+
+Return rest of the given list, either just the second element if it is of size
+2 or a pair, or a new list with the first element removed.
+
+#### cons
+
+Creates a new pair with the two given arguments, first one as the car, second
+as the cdr.
+
+#### quote
+
+Returns the given argument unevaluated.
+
+#### =
+
+Tests if multiple values equal. Returns nil if any are not, and `t` otherwise.
+
+#### cond
+
+Evaluates each expression if the given condition corresponding to it is true.
+Runs through any arguments, each is a list with the first element as the
+condition which needs to be `t` after evaluated, and the second element is the
+expression to be run if and only if the condition is met.
+
+#### lambda
+
+Creates function, first argument is a list of elements representing the symbol
+name for any arguments for the new function. Next argument is code to be run
+with the supplied arguments.
+
+#### define
+
+Create variable with the name of the first argument, with the value of the
+second.
+
+#### load
+
+Loads the library, given as a string.
+
+### Differences From Other Lisps
+
+In tisp there are no boolean types, much like common lisp, true is represented
+by the self evaluating symbol `t` and false is nil, represented as `()`, an
+empty list.
+
+tisp also only has one equality primitive, `=`, which tests integers, symbols,
+strings, and objects which occupy the same space in memory, such as primitives.
+It also accepts any number of arguments to compare.
+
+Symbols are also case sensitive following the Unix way, unlike many other lisps.
+
+## Author
+
+Ed van Bruggen <edvb@uw.edu>
+
+## See Also
+
+See project page at <https://edryd.org/projects/tisp.html>
+
+View source code at <https://git.edryd.org/tisp>
+
+## LICENSE
+
+zlib License
diff --git a/tisp.1 b/tisp.1
@@ -1,70 +0,0 @@
-.\" x-roff document
-.do mso man.tmac
-.TH tisp 1 "March 2018" "tisp 0.0.0"
-.PP
-.SH NAME
-tisp - tiny lisp
-.PP
-.SH SYNOPSIS
-\fBtisp\fP [\fB-hv\fP] [\fIFILENAME\fP]
-.PP
-.SH DESCRIPTION
-Tiny lisp implementation, still in heavy development, barely even "useable." Designed to be scheme-like, ie very minimalist.
-.PP
-.SH OPTIONS
-.TP
-\fB-h
-\fRPrint help and exit
-.PP
-.TP
-\fB-v
-\fRPrint version info and exit
-.PP
-.SH USAGE
-Run the program from the command line to launch the REPL, type a command and press enter to see the result.
-.PP
-.RS 4
-.EX
-
-$ tisp
-> (+ (+ 1 2) 3)
-6
-> (+ 1 2 3)
-6
-
-.EE
-.RE
-.PP
-Alternatively you can pass a file name which will be opened and run, outputting the result before exiting.
-.PP
-.RS 4
-.EX
-
-$ echo '(+ 1 2 3)' > add.lisp
-$ tisp add.lisp
-6
-
-.EE
-.RE
-.PP
-Commands can also be piped directing into tisp through the command line.
-.PP
-.RS 4
-.EX
-
-$ echo '(+ 1 2 3)' | tisp
-6
-
-.EE
-.RE
-.PP
-.SH AUTHOR
-Ed van Bruggen <edvb@uw.edu>
-.PP
-.SH SEE ALSO
-See project page at <https://edryd.org/projects/tisp.html>
-.PP
-View source code at <https://git.edryd.org/tisp>
-.PP
-.SH LICENSE
-zlib License
