+ 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
This commit is contained in:
fiddlosopher
parent
aeb250f28d
commit
76bd231a70
4 changed files with 211 additions and 36 deletions
37
README
37
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
|
||||
|
||||
|
|
|
|||
27
TODO
27
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue