23df0ed176
structure. Key and Note blocks have been removed. Link and image URLs
are now stored directly in Link and Image inlines, and note blocks
are stored in Note inlines. This requires changes in both parsers
and writers. Markdown and RST parsers need to extract data from key
and note blocks and insert them into the relevant inline elements.
Other parsers can be simplified, since there is no longer any need to
construct separate key and note blocks. Markdown, RST, and HTML writers
need to construct lists of notes; Markdown and RST writers need to
construct lists of link references (when the --reference-links option
is specified); and the RST writer needs to construct a list of image
substitution references. All writers have been rewritten to use the
State monad when state is required. This rewrite yields a small speed
boost and considerably cleaner code.
* Text/Pandoc/Definition.hs:
+ blocks: removed Key and Note
+ inlines: removed NoteRef, added Note
+ modified Target: there is no longer a 'Ref' target; all targets
are explicit URL, title pairs
* Text/Pandoc/Shared.hs:
+ Added 'Reference', 'isNoteBlock', 'isKeyBlock', 'isLineClump',
used in some of the readers.
+ Removed 'generateReference', 'keyTable', 'replaceReferenceLinks',
'replaceRefLinksBlockList', along with some auxiliary functions
used only by them. These are no longer needed, since
reference links are resolved in the Markdown and RST readers.
+ Moved 'inTags', 'selfClosingTag', 'inTagsSimple', and 'inTagsIndented'
to the Docbook writer, since that is now the only module that uses
them.
+ Changed name of 'escapeSGMLString' to 'escapeStringForXML'
+ Added KeyTable and NoteTable types
+ Removed fields from ParserState; 'stateKeyBlocks', 'stateKeysUsed',
'stateNoteBlocks', 'stateNoteIdentifiers', 'stateInlineLinks'.
Added 'stateKeys' and 'stateNotes'.
+ Added clause for Note to 'prettyBlock'.
+ Added 'writerNotes', 'writerReferenceLinks' fields to WriterOptions.
* Text/Pandoc/Entities.hs: Renamed 'escapeSGMLChar' and
'escapeSGMLString' to 'escapeCharForXML' and 'escapeStringForXML'
* Text/ParserCombinators/Pandoc.hs: Added lineClump parser: parses a raw
line block up to and including following blank lines.
* Main.hs: Replaced --inline-links with --reference-links.
* README:
+ Documented --reference-links and removed description of --inline-links.
+ Added note that footnotes may occur anywhere in the document, but must
be at the outer level, not embedded in block elements.
* man/man1/pandoc.1, man/man1/html2markdown.1: Removed --inline-links
option, added --reference-links option
* Markdown and RST readers:
+ Rewrote to fit new Pandoc definition. Since there are no longer
Note or Key blocks, all note and key blocks are parsed on a first pass
through the document. Once tables of notes and keys have been constructed,
the remaining parts of the document are reassembled and parsed.
+ Refactored link parsers.
* LaTeX and HTML readers: Rewrote to fit new Pandoc definition. Since
there are no longer Note or Key blocks, notes and references can be
parsed in a single pass through the document.
* RST, Markdown, and HTML writers: Rewrote using state monad new Pandoc
and definition. State is used to hold lists of references footnotes to
and be printed at the end of the document.
* RTF and LaTeX writers: Rewrote using new Pandoc definition. (Because
of the different treatment of footnotes, the "notes" parameter is no
longer needed in the block and inline conversion functions.)
* Docbook writer:
+ Moved the functions 'attributeList', 'inTags', 'selfClosingTag',
'inTagsSimple', 'inTagsIndented' from Text/Pandoc/Shared, since
they are now used only by the Docbook writer.
+ Rewrote using new Pandoc definition. (Because of the different
treatment of footnotes, the "notes" parameter is no longer needed
in the block and inline conversion functions.)
* Updated test suite
* Throughout: old haskell98 module names replaced by hierarchical module
names, e.g. List by Data.List.
* debian/control: Include libghc6-xhtml-dev instead of libghc6-html-dev
in "Build-Depends."
* cabalize:
+ Remove haskell98 from BASE_DEPENDS (since now the new hierarchical
module names are being used throughout)
+ Added mtl to BASE_DEPENDS (needed for state monad)
+ Removed html from GHC66_DEPENDS (not needed since xhtml is now used)
git-svn-id: https://pandoc.googlecode.com/svn/trunk@580 788f1e2b-df1e-0410-8736-df70ead52e1b
195 lines
6 KiB
Groff
195 lines
6 KiB
Groff
.TH PANDOC 1 "December 15, 2006" Pandoc "User Manuals"
|
|
.SH NAME
|
|
pandoc \- general markup converter
|
|
.SH SYNOPSIS
|
|
\fBpandoc\fR [\fIoptions\fR] [\fIinput\-file\fR]...
|
|
.SH DESCRIPTION
|
|
\fIPandoc\fR 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, DocBook
|
|
XML, and S5 HTML slide shows.
|
|
.PP
|
|
If no \fIinput\-file\fR is specified, input is read from STDIN.
|
|
Otherwise, the \fIinput\-files\fR are concatenated (with a blank
|
|
line between each) and used as input. Output goes to STDOUT by
|
|
default. For output to a file, use the \fB\-o\fR option:
|
|
.IP
|
|
.B pandoc \-o output.html input.txt
|
|
.PP
|
|
The input and output formats may be specified using command-line options
|
|
(see \fBOPTIONS\fR, below, for details). If these formats are not
|
|
specified explicitly, \fIPandoc\fR will attempt to determine them
|
|
from the extensions of the input and output filenames. If input comes
|
|
from STDIN or from a file with an unknown extension, the input is assumed
|
|
to be markdown. If no output filename is specified using the \fB\-o\fR
|
|
option, or if a filename is specified but its extension is unknown,
|
|
the output will default to HTML. Thus, for example,
|
|
.IP
|
|
.B pandoc -o chap1.tex chap1.txt
|
|
.PP
|
|
converts \fIchap1.txt\fR from markdown to LaTeX. And
|
|
.IP
|
|
.B pandoc README
|
|
.PP
|
|
converts \fIREADME\fR from markdown to HTML.
|
|
.PP
|
|
Pandoc's version of markdown is an extended variant of standard
|
|
markdown: the differences are described in the \fIREADME\fR file in
|
|
the user documentation. If standard markdown syntax is desired, the
|
|
\fB\-\-strict\fR option may be used.
|
|
.PP
|
|
\fIPandoc\fR 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 \fBiconv\fR:
|
|
.IP
|
|
.B iconv \-t utf\-8 input.txt | pandoc | iconv \-f utf\-8
|
|
.PP
|
|
\fIPandoc\fR's HTML parser is not very forgiving. If your input is
|
|
HTML, consider running it through \fBtidy\fR(1) before passing it
|
|
to Pandoc. Or use \fBhtml2markdown\fR(1), a wrapper around \fBpandoc\fR.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-f \fIFORMAT\fB, \-r \fIFORMAT\fB, \-\-from=\fIFORMAT\fB, \-\-read=\fIFORMAT\fB
|
|
Specify input format.
|
|
.I FORMAT
|
|
can be
|
|
.B native
|
|
(native Haskell),
|
|
.B markdown
|
|
(markdown or plain text),
|
|
.B rst
|
|
(reStructuredText),
|
|
.B html
|
|
(HTML),
|
|
or
|
|
.B latex
|
|
(LaTeX).
|
|
.TP
|
|
.B \-t \fIFORMAT\fB, \-w \fIFORMAT\fB, \-\-to=\fIFORMAT\fB, \-\-write=\fIFORMAT\fB
|
|
Specify output format.
|
|
.I FORMAT
|
|
can be
|
|
.B native
|
|
(native Haskell),
|
|
.B markdown
|
|
(markdown or plain text),
|
|
.B rst
|
|
(reStructuredText),
|
|
.B html
|
|
(HTML),
|
|
.B latex
|
|
(LaTeX),
|
|
.B docbook
|
|
(DocBook XML),
|
|
.B s5
|
|
(S5 HTML and javascript slide show),
|
|
or
|
|
.B 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 \-o FILE, \-\-output=FILE
|
|
Write output to \fIFILE\fR instead of STDOUT. If \fIFILE\fR is
|
|
`\-', output will go to STDOUT.
|
|
.TP
|
|
.B \-p, \-\-preserve-tabs
|
|
Preserve tabs instead of converting them to spaces.
|
|
.TP
|
|
.B \-\-tab-stop=\fITABSTOP\fB
|
|
Specify tab stop (default is 4).
|
|
.TP
|
|
.B \-\-strict
|
|
Use strict markdown syntax, with no extensions or variants.
|
|
.TP
|
|
.B \-\-reference\-links
|
|
Use reference-style links, rather than inline links, in writing markdown
|
|
or reStructuredText.
|
|
.TP
|
|
.B \-R, \-\-parse-raw
|
|
Parse untranslatable HTML codes and LaTeX environments as raw HTML
|
|
or LaTeX, instead of ignoring them.
|
|
.TP
|
|
.B \-S, \-\-smart
|
|
Use smart quotes, dashes, and ellipses. (This option is significant
|
|
only when the input format is \fBmarkdown\fR. It is selected automatically
|
|
when the output format is \fBlatex\fR.)
|
|
.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 \fICSS\fB, \-\-css=\fICSS\fB
|
|
Link to a CSS style sheet.
|
|
.I CSS
|
|
is the pathname of the style sheet.
|
|
.TP
|
|
.B \-H \fIFILE\fB, \-\-include-in-header=\fIFILE\fB
|
|
Include contents of \fIFILE\fR at the end of the header. Implies
|
|
\fB\-s\fR.
|
|
.TP
|
|
.B \-B \fIFILE\fB, \-\-include-before-body=\fIFILE\fB
|
|
Include contents of \fIFILE\fR at the beginning of the document
|
|
body.
|
|
.TP
|
|
.B \-A \fIFILE\fB, \-\-include-after-body=\fIFILE\fB
|
|
Include contents of \fIFILE\fR at the end of the document body.
|
|
.TP
|
|
.B \-C \fIFILE\fB, \-\-custom-header=\fIFILE\fB
|
|
Use contents of \fIFILE\fR as the document header (overriding the
|
|
default header, which can be printed by using the \fB\-D\fR option).
|
|
Implies \fB-s\fR.
|
|
.TP
|
|
.B \-D \fIFORMAT\fB, \-\-print-default-header=\fIFORMAT\fB
|
|
Print the default header for \fIFORMAT\fR (\fBhtml, s5, latex, docbook,
|
|
markdown, rst, rtf\fR).
|
|
.TP
|
|
.B \-T \fISTRING\fB, \-\-title-prefix=\fISTRING\fB
|
|
Specify \fISTRING\fR as a prefix to the HTML window title.
|
|
.TP
|
|
.B \-\-dump\-args
|
|
Print information about command\-line arguments to STDOUT, then exit.
|
|
The first line of output contains the name of the output file specified
|
|
with the \fB\-o\fR option, or `\-' (for STDOUT) if no output file was
|
|
specified. The remaining lines contain the command\-line arguments,
|
|
one per line, in the order they appear. These do not include regular
|
|
Pandoc options and their arguments, but do include any options appearing
|
|
after a `\-\-' separator at the end of the line.
|
|
This option is intended primarily for use in wrapper scripts.
|
|
.TP
|
|
.B \-\-ignore\-args
|
|
Ignore command\-line arguments (for use in wrapper scripts).
|
|
Regular Pandoc options are not ignored. Thus, for example,
|
|
.IP
|
|
.B pandoc \-\-ignore\-args \-o foo.html \-s foo.txt -- -e latin1
|
|
.IP
|
|
is equivalent to
|
|
.IP
|
|
.B pandoc \-o foo.html \-s
|
|
.TP
|
|
.B \-v, \-\-version
|
|
Print version.
|
|
.TP
|
|
.B \-h, \-\-help
|
|
Show usage message.
|
|
|
|
.SH "SEE ALSO"
|
|
\fBhtml2markdown\fR(1),
|
|
\fBmarkdown2pdf\fR(1).
|
|
The
|
|
.I README
|
|
file distributed with Pandoc contains full documentation.
|
|
|
|
The Pandoc source code and all documentation may be downloaded from
|
|
<http://sophos.berkeley.edu/macfarlane/pandoc/>.
|
|
.SH AUTHOR
|
|
John MacFarlane
|