+ Improved man page for pandoc and markdown2pdf.

+ Changed README to recommend iconv on both input and output.
+ Added TODO items.


git-svn-id: https://pandoc.googlecode.com/svn/trunk@53 788f1e2b-df1e-0410-8736-df70ead52e1b

4 files changed, 206 insertions, 31 deletions

diff --git a/README b/README
index 68a6714fa..30193edb7 100644
--- a/README
+++ b/README
@@ -87,38 +87,39 @@ and many other command-line options, see below.)
 
 Unfortunately, due to limitations in GHC, `pandoc` does not automatically
 detect the system's local character encoding.  Hence, all input and
-output is assumed to be in the UTF-8 encoding.  If you use accented or
-foreign characters, you should convert the input file to UTF-8 before
-processing it with `pandoc`.  This can be done by piping the input through
-[`iconv`]: for example,
+output is assumed to be in the UTF-8 encoding.  If your local character
+encoding is not UTF-8 and you use accented or foreign characters,
+you should pipe the input and output through [`iconv`]. For example,
 
-	iconv -t utf-8 source.txt | pandoc > output.html
+	iconv -t utf-8 source.txt | pandoc | iconv -f utf-8 > output.html
 
 will convert `source.txt` from the local encoding to UTF-8, then
-convert it to HTML, putting the output in `output.html`.
+convert it to HTML, then convert back to the local encoding,
+putting the output in `output.html`.
 
 [`iconv`]: http://www.gnu.org/software/libiconv/
 
-The shell scripts (described below) automatically convert the source
-from the local encoding to UTF-8 before running them through `pandoc`.
+The shell scripts (described below) automatically convert the input 
+from the local encoding to UTF-8 before running them through `pandoc`,
+then convert the output back to the local encoding.
 
 # The shell scripts 
 
 For convenience, five shell scripts have been included that make it
 easy to run `pandoc` without remembering all the command-line options.
-All of the scripts presuppose that `pandoc` is in the path, and
-some have additional requirements.  (For example, `html2markdown`
-uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
+All of the scripts use `iconv` to convert to and from the local
+character encoding.  All of the scripts presuppose that `pandoc`
+is in the path, and some have additional requirements.  (For example,
+`html2markdown` uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
 
-1.  `markdown2html` converts markdown to HTML, running `iconv` first to
-	convert the file to UTF-8.  (This can be used as a replacement for
-	`Markdown.pl`.)
+1.  `markdown2html` converts markdown to HTML. (This can be used
+    as a replacement for `Markdown.pl`.)
 
 2.	`html2markdown` can take either a filename or a URL as argument.  If
 	it is given a URL, it uses `curl`, `wget`, or an available text-based
     browser to fetch the contents of the specified URL, then filters this
-	through `tidy` to straighten up the HTML and convert to UTF-8,
-	and finally passes this HTML to `pandoc` to produce markdown text:
+	through `tidy` to straighten up the HTML, and finally passes
+	this HTML to `pandoc` to produce markdown text:
 
 	    html2markdown http://www.fsf.org
 
@@ -126,7 +127,7 @@ uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
 
 	    html2markdown subdir/mylocalfile.html
 
-3. 	`latex2markdown` converts a LaTeX file to markdown. 
+3. 	`latex2markdown` converts a LaTeX file to markdown:
 
 	    latex2markdown mytexfile.tex
 
@@ -134,7 +135,7 @@ uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
 
 	    markdown2latex mytextfile.txt
 
-5.	`markdown2pdf` converts markdown to PDF using `pdflatex`.  Example:
+5.	`markdown2pdf` converts markdown to PDF using `pdflatex`:
 
 	    markdown2pdf mytextfile.txt
 
diff --git a/TODO b/TODO
index b6dbda7f3..8416e36a4 100644
--- a/TODO
+++ b/TODO
@@ -1,2 +1,29 @@
 # TODO
 
+- create a changelog in root, with a symlink to it in debian
+  (only the top entry needs the sig.)
+>     pandoc (0.3) unstable; urgency=low
+>
+>     [ John MacFarlane ]
+>     * Revised RTF writer:
+>       + made default font Helvetica
+>       + added \f0 to each \pard, so that font resizing works correctly
+> 
+>     [ Recai Oktaş ]
+>     * Created proper debian package
+>     * Revamped build system:
+>       + [describe changes in targets]
+>     * Modified wrapper scripts to make them more robust.
+>       + added --output option to markdown2pdf
+>
+>      -- Recai Oktaş <roktas@debian.org>  Tue, 24 Oct 2006 07:48:30 +0300
+
+- make a proper man page for pandoc, with documentation of all options
+- uninstall script in Mac package; add information about it to Welcome?
+- create a compressed disk image containing Mac pkg
+- website target
+- put web templates and osx stuff in separate directories
+- look into warnings on pdflatex concerning ucs packages
+- change all versions to 0.3
+- iconv on both input and output in wrappers
+
diff --git a/man/man1/markdown2pdf.1 b/man/man1/markdown2pdf.1
index 894d05ec3..a33431353 100644
--- a/man/man1/markdown2pdf.1
+++ b/man/man1/markdown2pdf.1
@@ -1,4 +1,4 @@
-.TH PANDOC 1 "AUGUST 2006" Linux "User Manuals"
+.TH PANDOC 1 "NOVEMBER 2006" Linux "User Manuals"
 .SH NAME
 markdown2pdf \- converts markdown-formatted text to PDF, using pdflatex 
 .SH SYNOPSIS
@@ -15,4 +15,3 @@ John MacFarlane <jgm at berkeley.edu>
 .SH "SEE ALSO"
 pandoc (1), markdown2html (1), html2markdown (1), markdown2latex (1),
 latex2markdown (1)
-
diff --git a/man/man1/pandoc.1 b/man/man1/pandoc.1
index 8fb4afe5e..447b09033 100644
--- a/man/man1/pandoc.1
+++ b/man/man1/pandoc.1
@@ -1,20 +1,168 @@
-.TH PANDOC 1 "AUGUST 2006" Linux "User Manuals"
+.TH PANDOC 1 "November 1, 2006" Linux "User Manuals"
 .SH NAME
 pandoc \- general markup converter
 .SH SYNOPSIS
-.B pandoc [options] [input-files]
+.B pandoc [
+.I options
+] [
+.I input-files
+]
+
 .SH DESCRIPTION
-.B pandoc
+.I Pandoc
 converts files from one markup format to another. It can read markdown
-and (with some limitations) reStructuredText, HTML, and LaTeX, and it
-can write markdown, reStructuredText, HTML, LaTeX, RTF, and S5 HTML
-slide shows. 
+and (subsets of) reStructuredText, HTML, and LaTeX, and it can write
+markdown, reStructuredText, HTML, LaTeX, RTF, and S5 HTML slide shows.
+.PP
+If no 
+.I input-files
+are specified, input is read from STDIN.  Otherwise, the
+.I input-files
+are concatenated (with a blank line between each) and used
+as input.  Output goes to STDOUT.  Use redirection to produce
+a file:
+.IP
+.B pandoc input.txt > output.html
+.PP
+The default behavior of 
+.I Pandoc
+is to convert the
+input from markdown-formatted plain text to HTML.  Different
+input and output formats can be specified using command-line
+options.
+.PP
+.I Pandoc
+uses the UTF-8 character encoding for both input and output.
+If your local character encoding is not UTF-8, you should pipe
+input and output through
+.B iconv
+:
+.IP
+.B iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
+
 .SH OPTIONS
-For full usage information, including command-line options,
-type
-.B pandoc -h
+.TP
+.B \-v, \-\-version
+Print version.
+.TP
+.B \-h, \-\-help
+Show usage message.
+.TP
+.B \-f FORMAT, \-r FORMAT, --from=FORMAT, --read=FORMAT
+Specify input format.
+.I FORMAT
+can be
+.I native
+(native Haskell),
+.I markdown
+(markdown or plain text),
+.I rst
+(reStructuredText),
+.I html
+(HTML),
+or 
+.I latex
+(LaTeX).
+.TP
+.B \-t FORMAT, \-w FORMAT, --to=FORMAT, --write=FORMAT
+Specify output format.
+.I FORMAT
+can be
+.I native
+(native Haskell),
+.I markdown
+(markdown or plain text), 
+.I rst
+(reStructuredText),
+.I html
+(HTML),
+.I latex
+(LaTeX),
+.I s5
+(S5 HTML and javascript slide show),
+or
+.I rtf
+(rich text format).
+.TP
+.B \-s, \-\-standalone
+Produce output with an appropriate header and footer (e.g. a
+standalone HTML, LaTeX, or RTF file, not a fragment).
+.TP
+.B \-p, \-\-preserve-tabs
+Preserve tabs instead of converting them to spaces.
+.TP
+.B \-\-tab-stop=TABSTOP
+Specify tab stop (default is 4).
+.TP
+.B \-R, \-\-parse-raw
+Parse untranslatable HTML codes and LaTeX environments as raw HTML or
+LaTeX, instead of ignoring them.
+.TP
+.B \-S, \-\-smartypants
+Use smart quotes, dashes, and ellipses in HTML output.
+.TP
+.B \-m, \-\-asciimathml
+Use ASCIIMathML to display embedded LaTeX math in HTML output.
+.TP
+.B \-i, \-\-incremental
+Make list items in S5 display incrementally (one by one).
+.TP
+.B \-N, \-\-number-sections
+Number section headings in LaTeX output.  (Default is not to number them.)
+.TP
+.B \-c CSS, \-\-css=CSS
+Link to a CSS style sheet.
+.I CSS
+is the pathname of the style sheet.
+.TP
+.B \-H FILENAME, \-\-include-in-header=FILENAME
+Include contents of
+.I FILENAME
+at the end of the header.  Implies
+.B \-s.
+.TP
+.B \-B FILENAME, \-\-include-before-body=FILENAME
+Include contents of
+.I FILENAME
+at the beginning of the document body.
+.TP
+.B \-A FILENAME, \-\-include-after-body=FILENAME
+Include contents of
+.I FILENAME
+at the end of the document body.
+.TP
+.B \-\-custom-header=FILENAME
+Use contents of 
+.I FILENAME
+as the document header (overriding the default header, which can be
+printed by using the
+.B \-D
+option).  Implies
+.B \-s.
+.TP
+.B \-D FORMAT, \-\-print-default-header=FORMAT
+Print the default header for 
+.I FORMAT
+(
+.I html, s5, latex, markdown, rst, rtf
+).
+.TP
+.B \-T STRING, \-\-title-prefix=STRING
+Specify 
+.I STRING
+as a prefix to the HTML window title.
+
 .SH AUTHOR
-John MacFarlane <jgm at berkeley.edu>
+John MacFarlane
+
 .SH "SEE ALSO"
-markdown2html (1), html2markdown (1), markdown2latex (1), latex2markdown (1), markdown2pdf (1)
+markdown2html (1), html2markdown (1), markdown2latex (1), latex2markdown (1), markdown2pdf (1), iconv (1)
+
+The
+.B README
+file distributed with Pandoc contains full documentation.
+
+The Pandoc source code and all documentation may be downloaded from
+.B http://sophos.berkeley.edu/macfarlane/pandoc/
+.