From 76bd231a70a29034bf420153f6ee5d1195a3fe7f Mon Sep 17 00:00:00 2001
From: fiddlosopher <fiddlosopher@788f1e2b-df1e-0410-8736-df70ead52e1b>
Date: Wed, 1 Nov 2006 04:32:00 +0000
Subject: [PATCH] + 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
---
README | 37 +++++----
TODO | 27 ++++++
man/man1/markdown2pdf.1 | 3 +-
man/man1/pandoc.1 | 180 ++++++++++++++++++++++++++++++++++++----
4 files changed, 211 insertions(+), 36 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]
-.SH DESCRIPTION
-.B 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.
-.SH OPTIONS
-For full usage information, including command-line options,
-type
-.B pandoc -h
-.SH AUTHOR
-John MacFarlane <jgm at berkeley.edu>
-.SH "SEE ALSO"
-markdown2html (1), html2markdown (1), markdown2latex (1), latex2markdown (1), markdown2pdf (1)
+.B pandoc [
+.I options
+] [
+.I input-files
+]
+
+.SH DESCRIPTION
+.I Pandoc
+converts files from one markup format to another. It can read markdown
+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
+.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
+
+.SH "SEE ALSO"
+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/
+.