Merge pull request #49 from phi-gamma/master

man page

3 files changed, 148 insertions, 9 deletions

diff --git a/Makefile b/Makefile
index 467891d..ded3418 100644
--- a/Makefile
+++ b/Makefile
@@ -4,22 +4,27 @@ NAME         = luaotfload
 DOC          = $(NAME).pdf
 DTX          = $(NAME).dtx
 OTFL         = $(wildcard luaotfload-*.lua) luaotfload-blacklist.cnf $(GLYPHS)
-SCRIPT       = luaotfload-tool.lua
 
 GLYPHSCRIPT  = mkglyphlist
 GLYPHSOURCE  = glyphlist.txt
 
-GRAPH  = filegraph
-DOTPDF = $(GRAPH).pdf
-DOT    = $(GRAPH).dot
+SCRIPTNAME   = luaotfload-tool
+SCRIPT       = $(SCRIPTNAME).lua
+MANSOURCE	 = $(SCRIPTNAME).rst
+MANPAGE   	 = $(SCRIPTNAME).1
+
+GRAPH  		 = filegraph
+DOTPDF 		 = $(GRAPH).pdf
+DOT    		 = $(GRAPH).dot
 
 # Files grouped by generation mode
 GLYPHS      = font-age.lua
 GRAPHED     = $(DOTPDF)
+MAN			= $(MANPAGE)
 COMPILED    = $(DOC)
 UNPACKED    = luaotfload.sty luaotfload.lua
-GENERATED   = $(GRAPHED) $(UNPACKED) $(COMPILED) $(GLYPHS)
-SOURCE 		= $(DTX) $(OTFL) README Makefile NEWS $(SCRIPT) $(GLYPHSCRIPT)
+GENERATED   = $(GRAPHED) $(UNPACKED) $(COMPILED) $(GLYPHS) $(MAN)
+SOURCE 		= $(DTX) $(MANSOURCE) $(OTFL) README Makefile NEWS $(SCRIPT) $(GLYPHSCRIPT)
 
 # test files
 TESTDIR 		= tests
@@ -30,7 +35,8 @@ TESTFILES_TL 	= $(filter-out $(TESTFILES_SYS), $(TESTFILES))
 # Files grouped by installation location
 SCRIPTFILES = $(SCRIPT) $(GLYPHSCRIPT)
 RUNFILES    = $(UNPACKED) $(OTFL)
-DOCFILES    = $(DOC) README NEWS
+DOCFILES    = $(DOC) $(DOTPDF) README NEWS
+MANFILES	= $(MANPAGE)
 SRCFILES    = $(DTX) Makefile
 
 # The following definitions should be equivalent
@@ -42,6 +48,7 @@ FORMAT = luatex
 SCRIPTDIR = $(TEXMFROOT)/scripts/$(NAME)
 RUNDIR    = $(TEXMFROOT)/tex/$(FORMAT)/$(NAME)
 DOCDIR    = $(TEXMFROOT)/doc/$(FORMAT)/$(NAME)
+MANDIR    = $(TEXMFROOT)/doc/man/man1/
 SRCDIR    = $(TEXMFROOT)/source/$(FORMAT)/$(NAME)
 TEXMFROOT = $(shell kpsewhich --var-value TEXMFHOME)
 
@@ -54,13 +61,15 @@ DO_TEX 		  	= tex --interaction=batchmode $< >/dev/null
 DO_LATEX 	  	= latexmk -pdf -e '$$pdflatex = q(lualatex %O %S)' -silent $< >/dev/null
 DO_GRAPHVIZ 	= dot -Tpdf -o $@ $< > /dev/null
 DO_GLYPHLIST 	= texlua ./mkglyphlist > /dev/null
+DO_DOCUTILS 	= rst2man2 $< >$@ 2>/dev/null
 
 all: $(GENERATED)
 graph: $(GRAPHED)
-doc: $(GRAPHED) $(COMPILED)
+doc: $(GRAPHED) $(COMPILED) $(MAN)
+manual: $(MAN)
 unpack: $(UNPACKED)
 glyphs: $(GLYPHS)
-ctan: check $(CTAN_ZIP)
+ctan: $(CTAN_ZIP)
 tds: $(TDS_ZIP)
 world: all ctan
 
@@ -76,6 +85,9 @@ $(COMPILED): $(DTX)
 $(UNPACKED): $(DTX)
 	$(DO_TEX)
 
+$(MAN): $(MANSOURCE)
+	$(DO_DOCUTILS)
+
 $(CTAN_ZIP): $(SOURCE) $(COMPILED) $(TDS_ZIP)
 	@echo "Making $@ for CTAN upload."
 	@$(RM) -- $@
@@ -86,6 +98,7 @@ define run-install
 @mkdir -p $(RUNDIR) && cp $(RUNFILES) $(RUNDIR)
 @mkdir -p $(DOCDIR) && cp $(DOCFILES) $(DOCDIR)
 @mkdir -p $(SRCDIR) && cp $(SRCFILES) $(SRCDIR)
+@mkdir -p $(MANDIR) && cp $(MANFILES) $(MANDIR)
 endef
 
 $(TDS_ZIP): TEXMFROOT=./tmp-texmf
diff --git a/README b/README
index 4730e88..aec8e24 100644
--- a/README
+++ b/README
@@ -53,6 +53,12 @@ Here are the recommended installation methods (preferred first).
 
 4. Try to figure it out by looking at the Makefile and comments in the sources.
 
+Prerequisites
+-------------------------------------------------------------------------------
+
+Typesetting the documentation requires LuaTeX and GraphViz. The Docutils are
+needed to generate the manpage.
+
 License
 -------------------------------------------------------------------------------
 
diff --git a/luaotfload-tool.rst b/luaotfload-tool.rst
new file mode 100644
index 0000000..13842e2
--- /dev/null
+++ b/luaotfload-tool.rst
@@ -0,0 +1,120 @@
+=======================================================================
+                            luaotfload-tool
+=======================================================================
+
+-----------------------------------------------------------------------
+         generate and query the Luaotfload font names database
+-----------------------------------------------------------------------
+
+:Date:      2013-05-06
+:Copyright: GPL v2.0
+:Version:   2.2
+:Manual section: 1
+:Manual group: text processing
+
+SYNOPSIS
+=======================================================================
+
+**luaotfload** [ -cfFiquvVh ]
+
+**luaotfload** --update [ --force ] [ --find ] [ --quiet ] [ --verbose ]
+
+**luaotfload** --find=filename [ --fuzzy ] [ --info ]
+
+**luaotfload** --flush-cache
+
+**luaotfload** --help
+
+**luaotfload** --version
+
+DESCRIPTION
+=======================================================================
+
+luaotfload-tool accesses the font names database that is required by
+the *Luaotfload* package. There are two general modes: **update** and
+**query**.
+
++ **update**:  update the database or rebuild it entirely;
++ **query**:   resolve a font name or display close matches.
+
+A third mode for clearing the lookup cache is currently experimental.
+
+Note that if the script is named ``mkluatexfontdb`` it will behave like
+earlier versions (<=1.3) and always update the database first. Also,
+the verbosity level will be set to 2.
+
+OPTIONS
+=======================================================================
+
+update mode
+-----------------------------------------------------------------------
+--update, -u            Update the database; indexes new fonts.
+--force, -f             Force rebuilding of the database; re-indexes
+                        all fonts.
+
+query mode
+-----------------------------------------------------------------------
+--find=<name>           Resolve a font name; this looks up <name> in
+                        the database and prints the file name it is
+                        mapped to.
+--fuzzy, -F             Show approximate matches to the file name if
+                        the lookup was unsuccessful (requires ``--find``).
+--info, -i              Display basic information to a resolved font
+                        file (requires ``--find``).
+
+lookup cache
+-----------------------------------------------------------------------
+--flush-cache           Clear font name lookup cache (experimental).
+
+miscellaneous
+-----------------------------------------------------------------------
+--verbose=<n>, -v       Set verbosity level to *n* or the number of
+                        repetitions of ``-v``.
+--quiet                 No verbose output (log level set to zero).
+--log=stdout            Redirect log output to terminal (for database
+                        troubleshooting).
+
+--version, -V           Show version number and exit.
+--help, -h              Show help message and exit.
+
+
+FILES
+=======================================================================
+
+The font name database is usually located in the directory
+``texmf-var/luatex-cache/generic/names/`` (``$TEXMFCACHE`` as set in
+``texmf.cnf``) of your *TeX Live* distribution as
+``luaotfload-names.lua``.  The experimental lookup cache will be
+created as ``luaotfload-lookup-cache.lua`` in the same directory.
+Both files are safe to delete, at the cost of regenerating them with
+the next run of *LuaTeX*.
+
+SEE ALSO
+=======================================================================
+
+**luatex** (1), **lua** (1)
+
+* ``texdoc luaotfload`` to display the manual for the *Luaotfload*
+  package
+* Luaotfload development `<https://github.com/lualatex/luaotfload>`_
+* LuaLaTeX mailing list  `<http://tug.org/pipermail/lualatex-dev/>`_
+* LuaTeX                 `<http://luatex.org/>`_
+* ConTeXt                `<http://wiki.contextgarden.net>`_
+* Luaotfload on CTAN     `<http://ctan.org/pkg/luaotfload>`_
+
+BUGS
+=======================================================================
+
+Tons, probably.
+
+AUTHORS
+=======================================================================
+
+*Luaotfload* is maintained by the LuaLaTeX dev team
+(`<https://github.com/lualatex/>`__).
+The fontloader code is provided by Hans Hagen of Pragma ADE, Hasselt
+NL (`<http://pragma-ade.com/>`__).
+
+This manual page was written by Philipp Gesang
+<philipp.gesang@alumni.uni-heidelberg.de>.
+