m + add manpage + improve readme2.1

Signed-off-by: Mattias Andrée <maandree@operamail.com>

4 files changed, 122 insertions, 40 deletions

diff --git a/Makefile b/Makefile
index de78779..3998b25 100644
--- a/Makefile
+++ b/Makefile
@@ -5,6 +5,8 @@ BINDIR = $(PREFIX)/bin
 DATADIR = $(PREFIX)/share
 INFODIR = $(DATADIR)/info
 DOCDIR = $(DATADIR)/doc
+MANDIR = $(DATADIR)/man
+MAN1DIR = $(MANDIR)/man1
 LICENSEDIR = $(DATADIR)/licenses
 
 COMMAND = bfind
@@ -86,7 +88,7 @@ bin/bfind.%sh-completion: obj/bfind.auto-completion
 
 
 .PHONY: install-default
-install-default: install-core install-info install-shell
+install-default: install-core install-info install-man install-shell
 
 .PHONY: install
 install: install-core install-doc install-shell
@@ -105,7 +107,7 @@ install-license:
 	install -m644 -- COPYING LICENSE "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)"
 
 .PHONY: install-doc
-install-doc: install-info install-pdf install-dvi install-ps
+install-doc: install-info install-pdf install-dvi install-ps install-man
 
 .PHONY: install-info
 install-info: bin/bfind.info
@@ -127,6 +129,11 @@ install-ps: bin/bfind.ps
 	install -dm755 -- "$(DESTDIR)$(DOCDIR)"
 	install -m644 $< -- "$(DESTDIR)$(DOCDIR)/$(PKGNAME).ps"
 
+.PHONY: install-man
+install-man: doc/man/bfind.1
+	install -dm755 -- "$(DESTDIR)$(MAN1DIR)"
+	install -m644 $< -- "$(DESTDIR)$(MAN1DIR)/$(COMMAND).1"
+
 .PHONY: install-shell
 install-shell: install-bash install-fish install-zsh
 
@@ -160,6 +167,7 @@ uninstall:
 	-rm -- "$(DESTDIR)$(DATADIR)/bash-completion/completions/$(COMMAND)"
 	-rm -- "$(DESTDIR)$(DATADIR)/fish/completions/$(COMMAND).fish"
 	-rm -- "$(DESTDIR)$(DATADIR)/zsh/site-functions/_$(COMMAND)"
+	-rm -- "$(DESTDIR)$(MAN1DIR)/$(COMMAND).1"
 
 
 
diff --git a/README b/README
index fe43022..186c069 100644
--- a/README
+++ b/README
@@ -1,49 +1,48 @@
-Minimalitic `find` using breadth-first crawling.
+NAME
+	bfind - Minimalitic find using breadth-first crawling
 
-The entire invocation syntax is:
+SYNOPSIS
+	bfind [OPTION]... [--] [DIRECTORY]
 
-    bfind [--xdev] [--hardlinks] [--symlinks] \
-          [--visible] [--print0] [--] [DIRECTORY]
+DESCRIPTION
+	bfind is a minimalitic alternative to find(1) that is
+	designed to be efficient that locating files. To
+	accomplish this, bfind uses breadth-first crawling
+	instead of depth-first crawling.
 
-With --xdev crawling will not be restricted to
-one mount point.
+	bfind is only includes the bare minimum, a few options
+	for restricting the crawlspace and an option to output
+	visited files in a safe format rather than a human-friendly
+	format. bfind will never include all features of find(1)
+	because they are excessive and some other than makes not
+	since to have in the program and can be outright dangerous.
 
-With --hardlinks bfind will be hardlink aware
-on directories.
+OPTIONS
+	-x, --xdev
+		Do not restrict crawling to one mount point.
 
-With --symlinks bfind will visit directories
-symlinks points, and directories will never
-be revisited. Visited directories will be
-memorised by absolute real path name.
+	-h, --hardlinks
+		Watch out for hardlinked directories.
 
-With --visible no files starting with a dot
-will be listed.
+	-s, --symlinks
+		Visit symbolically linked directories, but
+		never visit the same directory twice.
 
-With --print0 a NUL (\0) character will be
-printed at end of file names rather than
-a LF (\n).
+	-v, --visible
+		No files starting with a dot will be listed.
 
+	-0, --print0
+		Terminate lines with NUL rather than LF.
 
-Short option alternatives:
+RATIONALE
+	While bfind is not as fast as find(1) for large
+	hierarchies, it will probably give your results faster
+	if you are looking for a file (rather than listing files),
+	because the file you are looking for is probably
+	near the directory you are searching from.
 
-    -x --xdev
-    -h --hardlinks
-    -s --symlinks
-    -v --visible
-    -0 --print0
+SEE ALSO
+	find(1), grep(1)
 
-    Short options can be combined
-
-
-Each line will always start with DIRECTORY.
-
-
-Why bfind? While bfind is not as fast as find*,
-it will probably give your results faster if
-you are looking for a file (not list files),
-because the file you are looking for is probably
-near the directory you are searching from.
-
-
-* For large hierarchies.
+	Full documentation available locally via: info '(bfind)'
 
diff --git a/doc/man/bfind.1 b/doc/man/bfind.1
new file mode 100644
index 0000000..3265717
--- /dev/null
+++ b/doc/man/bfind.1
@@ -0,0 +1,75 @@
+.TH BFIND 1 BFIND
+.SH NAME
+bfind - Minimalitic find using breadth-first crawling
+.SH SYNOPSIS
+.BR bfind
+.RI [ OPTION ]...
+[--]
+.RI [ DIRECTORY ]
+.IR PASSPHRASE_LIST
+.SH DESCRIPTION
+.BR bfind
+is a minimalitic alternative to
+.BR find (1)
+that is designed to be efficient that locating files.
+To accomplish this,
+.BR bfind
+uses breadth-first crawling instead of depth-first crawling.
+.PP
+.BR bfind
+is only includes the bare minimum, a few options for
+restricting the crawlspace and an option to output
+visited files in a safe format rather than a human-friendly
+format.
+.BR bfind
+will never include all features of
+.BR find (1)
+because they are excessive and some other than makes
+not since to have in the program and can be outright
+dangerous.
+.SH OPTIONS
+.TP
+.BR \-x ,\  \-\-xdev
+Do not restrict crawling to one mount point.
+.TP
+.BR \-h ,\  \-\-hardlinks
+Watch out for hardlinked directories.
+.TP
+.BR \-s ,\  \-\-symlinks
+Visit symbolically linked directories, but
+never visit the same directory twice.
+.TP
+.BR \-v ,\  \-\-visible
+No files starting with a dot will be listed.
+.TP
+.BR \-0 ,\  \-\-print0
+Terminate lines with NUL rather than LF.
+.SH RATIONALE
+While
+.BR bfind
+is not as fast as
+.BR find (1)
+for large hierarchies, it will probably give your
+results faster if you are looking for a file (rather
+than listing files), because the file you are looking
+for is probably near the directory you are searching
+from.
+.SH "SEE ALSO"
+.BR find (1),
+.BR grep (1)
+.PP
+Full documentation available locally via: info \(aq(bfind)\(aq
+.SH AUTHORS
+Principal author, Mattias Andrée.  See the COPYING file for the full
+list of authors.
+.SH LICENSE
+Copyright \(co 2013, 2015  Mattias Andrée
+.br
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+.br
+There is NO WARRANTY, to the extent permitted by law.
+.SH BUGS
+Please report bugs to https://github.com/maandree/passcheck/issues or to
+maandree@member.fsf.org
diff --git a/src/bfind.auto-completion b/src/bfind.auto-completion
index f1f74e2..ecc95f8 100644
--- a/src/bfind.auto-completion
+++ b/src/bfind.auto-completion
@@ -1,6 +1,6 @@
 (bfind
 	(unargumented  (options -x --xdev)  (complete --xdev)
-	(desc 'Do not crawl across mount points'))
+	(desc 'Crawl across mount points'))
 
 	(unargumented  (options -h --hardlinks)  (complete --hardlinks)
 	(desc 'Be aware of hardlinked directories'))