From 69805624b2dcb0ec30eeb57c64ffac85bfe61fff Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Sun, 26 Jul 2009 13:02:16 -0700 Subject: Switch to pandoc for all documentation pandoc can generate stand-alone HTML, an automatic TOC, and the only Markdown processor I know of capable of generating manpages. Markdown is also a more standard syntax than txt2man and appropriate for generating HTML versions of manpages. --- Makefile | 20 +++++++---- pcu-fadvise.1.txt | 101 ++++++++++++++++++++++++++++++------------------------ pcu-mincore.1.txt | 77 +++++++++++++++++++++++------------------ 3 files changed, 113 insertions(+), 85 deletions(-) diff --git a/Makefile b/Makefile index d846d32..f896181 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,10 @@ prefix = $(HOME) bindir = $(prefix)/bin mandir = $(prefix)/share/man INSTALL = install -TXT2MAN = txt2man +PANDOC = pandoc +PANDOC_OPTS = -s -f markdown --email-obfuscation=none --sanitize-html +pandoc = $(PANDOC) $(PANDOC_OPTS) +pandoc_html = $(pandoc) --toc -t html --no-wrap STRIP ?= strip GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE @./GIT-VERSION-GEN @@ -42,13 +45,17 @@ install-strip: strip $(MAKE) install %.1: %.1.txt - $(TXT2MAN) -r 'pcu $(GIT_VERSION)' \ - -v 'Page Cache Utilities Reference Manual' \ - -t $(basename $@) -s 1 < $< > $@+ + $(pandoc) -t man < $< > $@+ + mv $@+ $@ +%.1.html: %.1.txt + $(pandoc_html) -T $(basename $@) < $< > $@+ mv $@+ $@ man1 := $(addsuffix .1,$(PCU_BIN)) +html := index.html $(addsuffix .html, $(man1)) +html: $(html) man: $(man1) +doc: html man install-man: install-man1 install-man1: $(man1) $(INSTALL) -d -m 755 '$(DESTDIR)$(mandir)/man1' @@ -60,12 +67,11 @@ dist: GIT-VERSION-FILE mv $(DISTNAME).tar.gz+ $(DISTNAME).tar.gz clean: $(RM) $(PCU_BIN) $(DISTNAME).tar.gz* GIT-VERSION-FILE - $(RM) $(man1) + $(RM) $(man1) $(html) index.html: title = $(shell sed -ne 1p < $<) index.html: README - markdown $< | (tidy -q 2>/dev/null || true) | \ - sed 's,,$(title),' > $@+ + $(pandoc_html) -T "$(title)" < $< > $@+ mv $@+ $@ .PHONY: .FORCE-GIT-VERSION-FILE install install-man man diff --git a/pcu-fadvise.1.txt b/pcu-fadvise.1.txt index 9e10c8b..6a0cd1c 100644 --- a/pcu-fadvise.1.txt +++ b/pcu-fadvise.1.txt @@ -1,44 +1,57 @@ -NAME - pcu-fadvise - predeclare an access pattern on given files -SYNOPSIS - pcu-fadvise [-a advice] [-o offset] [-l length] FILE... -DESCRIPTION - A command-line interface to the posix_fadvise(2) syscall to tell - the kernel to optimize access patterns for specified files. -OPTIONS - -a advice - - File access pattern advice. - The advice must be one of the following: - - normal - sequential - random - noreuse - willneed - dontneed - - The default advice is normal. - - -o offset - - Apply advice only to the given byte offset. - This offset rounded down to the previous page offset. - The default offset is zero (beginning of the file) - - -l length - - Apply advice only to the given length in bytes. - This length is rounded up next page offset. - The default is to scan the entire file. - -OUTPUT - Errors only. -ENVIRONMENT - none -SEE ALSO - posix_fadvise(2) -BUGS - None known. Email the author if you find any. -AUTHOR - Eric Wong +% PCU-FADVISE(1) Page Cache Utilities Manual +% Eric Wong +% July 26, 2009 + +# NAME + +pcu-fadvise - predeclare an access pattern on given files + +# SYNOPSIS + +pcu-fadvise [*-a ADVICE*] [*-o OFFSET*] [*-l LENGTH*] FILE... + +# DESCRIPTION + +A command-line interface to the posix_fadvise(2) syscall to tell +the kernel to optimize access patterns for specified files. + +# OPTIONS + +-a *ADVICE* +: File access pattern advice. + +: *ADVICE* must be one of the following: + + * normal + * sequential + * random + * noreuse + * willneed + * dontneed + + The default advice is `normal`. + +-o *OFFSET* +: Apply advice only to the given byte offset. + This offset rounded down to the previous page offset. + The default offset is zero (beginning of the file). + +-l *LENGTH* +: Apply advice only to the given length in bytes. + This length is rounded up next page offset. + The default is to scan the entire file. + +# OUTPUT + +Errors only. + +# ENVIRONMENT + +none + +# SEE ALSO +[`posix_fadvise`(2)](http://linux.die.net/man/2/posix_fadvise) + +# BUGS + +None known. Email if you find any. diff --git a/pcu-mincore.1.txt b/pcu-mincore.1.txt index d2334e5..db4f071 100644 --- a/pcu-mincore.1.txt +++ b/pcu-mincore.1.txt @@ -1,34 +1,43 @@ -NAME - pcu-mincore - shows cache status for given files -SYNOPSIS - pcu-mincore [-o offset] [-l length] FILE... -DESCRIPTION - A command-line interface to the mincore(2) syscall to inspect - whether or not certain pages belonging to a file are cached in - resident memory. -OPTIONS - -o offset - - Scan only pages on or after the given offset. - This offset is rounded down to the previous page offset. - The default offset is zero (beginning of the file) - - -l length - - Check only the given length in bytes. - This length is rounded up next page offset. - The default is to scan the entire file. -OUTPUT - One line for every page scanned in the following format: - - : - - offset is a hexadecimal number for a given range of PAGE_SIZE bytes. - incore is a boolean value indicating whether or not the page beginning - at a particular offset is cached in resident memory or not. -SEE ALSO - mincore(2) -BUGS - None known. Email the author if you find any. -AUTHOR - Eric Wong +% PCU-MINCORE(1) Page Cache Utilities Manual +% Eric Wong +% July 26, 2009 + +# NAME +pcu-mincore - shows cache status for given files + +# SYNOPSIS +pcu-mincore [-o OFFSET] [-l LENGTH] FILE... + +# DESCRIPTION +A command-line interface to the mincore(2) syscall to inspect +whether or not certain pages belonging to a file are cached in +resident memory. + +# OPTIONS +-o OFFSET +: Scan only pages on or after the given offset. + This offset is rounded down to the previous page offset. + The default offset is zero (beginning of the file) + +-l LENGTH +: Check only the given length in bytes. + This length is rounded up next page offset. + The default is to scan the entire file. + +# OUTPUT +One line for every page scanned in the following format: + + \: \ \ + +offset is a hexadecimal number for a given range of PAGE_SIZE bytes. +incore is a boolean value indicating whether or not the page beginning +at a particular offset is cached in resident memory or not. + +# ENVIRONMENT +none + +# SEE ALSO +[`mincore`(2)](http://linux.die.net/man/2/mincore) + +# BUGS +None known. Email if you find any. -- cgit v1.2.3-24-ge0c7