Documented OpenDocument writer and markdown2odt in README.
Folded "Requirements" section into description of shell scripts. git-svn-id: https://pandoc.googlecode.com/svn/trunk@1267 788f1e2b-df1e-0410-8736-df70ead52e1b
This commit is contained in:
fiddlosopher
parent
b8cdc13a92
commit
9420982b1a
1 changed files with 48 additions and 45 deletions
93
README
93
README
|
|
@ -1,14 +1,14 @@
|
|||
% Pandoc User's Guide
|
||||
% John MacFarlane
|
||||
% January 8, 2008
|
||||
% March 24, 2008
|
||||
|
||||
Pandoc is a [Haskell] library for converting from one markup format to
|
||||
another, and a command-line tool that uses this library. It can read
|
||||
[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX], and
|
||||
it can write [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt],
|
||||
[RTF], [DocBook XML], [GNU Texinfo], [groff man] pages, and [S5] HTML
|
||||
slide shows. Pandoc's version of markdown contains some enhancements,
|
||||
like footnotes and embedded LaTeX.
|
||||
[RTF], [DocBook XML], [OpenDocument XML], [GNU Texinfo], [groff man]
|
||||
pages, and [S5] HTML slide shows. Pandoc's version of markdown contains
|
||||
some enhancements, like footnotes and embedded LaTeX.
|
||||
|
||||
In contrast to existing tools for converting markdown to HTML, which
|
||||
use regex substitutions, Pandoc has a modular design: it consists of a
|
||||
|
|
@ -25,6 +25,7 @@ or output format requires only adding a reader or writer.
|
|||
[ConTeXt]: http://www.pragma-ade.nl/
|
||||
[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
|
||||
[DocBook XML]: http://www.docbook.org/
|
||||
[OpenDocument XML]: http://opendocument.xml.org/
|
||||
[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
|
||||
[Haskell]: http://www.haskell.org/
|
||||
[GNU Texinfo]: http://www.gnu.org/software/texinfo/
|
||||
|
|
@ -37,41 +38,6 @@ scripts), Peter Wang (Texinfo writer), Andrea Rossato (OpenDocument writer).
|
|||
|
||||
[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
The `pandoc` program itself does not depend on any external libraries
|
||||
or programs.
|
||||
|
||||
The wrapper script `html2markdown` requires
|
||||
|
||||
- `pandoc` (which must be in the PATH)
|
||||
- a POSIX-compliant shell (installed by default on all linux and unix
|
||||
systems, including Mac OS X, and in [Cygwin] for Windows),
|
||||
- `HTML Tidy`
|
||||
- `iconv` (for character encoding conversion). (If `iconv` is absent,
|
||||
`html2markdown` will still work, but it will treat everything as UTF-8.)
|
||||
|
||||
The wrapper script `markdown2pdf` requires
|
||||
|
||||
- `pandoc` (which must be in the PATH)
|
||||
- a POSIX-compliant shell
|
||||
- `pdflatex`, which should be part of any [LaTeX] distribution
|
||||
- the following LaTeX packages (available from [CTAN], if they
|
||||
are not already included in your LaTeX distribution):
|
||||
+ `unicode`
|
||||
+ `fancyhdr` (if you have verbatim text in footnotes)
|
||||
+ `graphicx` (if you use images)
|
||||
+ `array` (if you use tables)
|
||||
+ `ulem` (if you use strikeout text)
|
||||
|
||||
The wrapper script `hsmarkdown` requires only a POSIX-compliant shell.
|
||||
|
||||
[Cygwin]: http://www.cygwin.com/
|
||||
[HTML Tidy]: http://tidy.sourceforge.net/
|
||||
[`iconv`]: http://www.gnu.org/software/libiconv/
|
||||
[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
|
||||
|
||||
Using Pandoc
|
||||
============
|
||||
|
||||
|
|
@ -151,10 +117,10 @@ then convert the output back to the local encoding.
|
|||
Shell scripts
|
||||
=============
|
||||
|
||||
Three shell scripts, `markdown2pdf`, `html2markdown`, and `hsmarkdown`,
|
||||
are included in the standard Pandoc installation. (They are not included
|
||||
in the Windows binary package, as they require a POSIX shell, but they
|
||||
may be used in Windows under Cygwin.)
|
||||
Four shell scripts, `markdown2pdf`, `markdown2odt`, `html2markdown`, and
|
||||
`hsmarkdown`, are included in the standard Pandoc installation. (They
|
||||
are not included in the Windows binary package, as they require a POSIX
|
||||
shell, but they may be used in Windows under Cygwin.)
|
||||
|
||||
1. `markdown2pdf` produces a PDF file from markdown-formatted
|
||||
text, using `pandoc` and `pdflatex`. The default
|
||||
|
|
@ -173,7 +139,35 @@ may be used in Windows under Cygwin.)
|
|||
If no input file is specified, input will be taken from STDIN.
|
||||
All of `pandoc`'s options will work with `markdown2pdf` as well.
|
||||
|
||||
2. `html2markdown` grabs a web page from a file or URL and converts
|
||||
`markdown2pdf` assumes that `pdflatex` is in the path. It also
|
||||
assumes that the following LaTeX packages are available:
|
||||
`unicode`, `fancyhdr` (if you have verbatim text in footnotes),
|
||||
`graphicx` (if you use images), `array` (if you use tables),
|
||||
and `ulem` (if you use strikeout text). If they are not already
|
||||
included in your LaTeX distribution, you can get them from
|
||||
[CTAN].
|
||||
|
||||
2. `markdown2odt` produces an ODT file from markdown-formatted
|
||||
text, using `pandoc` and `pdflatex`. (ODT is "OpenDocument
|
||||
Text," the default format for the OpenOffice.org Writer.)
|
||||
The default behavior of `markdown2odt` is to create a file with the
|
||||
same base name as the first argument and the extension `odt`; thus,
|
||||
for example,
|
||||
|
||||
markdown2odt sample.txt endnotes.txt
|
||||
|
||||
will produce `sample.odt`. (If `sample.odt` exists already,
|
||||
it will be backed up before being overwritten.) An output file
|
||||
name can be specified explicitly using the `-o` option:
|
||||
|
||||
markdown2odt -o book.odt chap1 chap2
|
||||
|
||||
If no input file is specified, input will be taken from STDIN.
|
||||
All of `pandoc`'s options will work with `markdown2odt` as well.
|
||||
|
||||
`markdown2odt` requires `zip`, which must be in the path.
|
||||
|
||||
3. `html2markdown` grabs a web page from a file or URL and converts
|
||||
it to markdown-formatted text, using `tidy` and `pandoc`.
|
||||
|
||||
All of `pandoc`'s options will work with `html2markdown` as well.
|
||||
|
|
@ -198,7 +192,11 @@ may be used in Windows under Cygwin.)
|
|||
available program (`wget`, `curl`, or a text-mode browser) to fetch
|
||||
the contents of a URL.
|
||||
|
||||
3. `hsmarkdown` is designed to be used as a drop-in replacement for
|
||||
`html2markdown` requires [HTML Tidy], which must be in the path.
|
||||
It uses [`iconv`] for character encoding conversions; if `iconv`
|
||||
is absent, it will still work, but it will treat everything as UTF-8.
|
||||
|
||||
4. `hsmarkdown` is designed to be used as a drop-in replacement for
|
||||
`Markdown.pl`. It forces `pandoc` to convert from markdown to
|
||||
HTML, and to use the `--strict` flag for maximal compliance with
|
||||
official markdown syntax. (All of Pandoc's syntax extensions and
|
||||
|
|
@ -214,6 +212,11 @@ may be used in Windows under Cygwin.)
|
|||
under Cygwin, due to problems with its simulation of symbolic
|
||||
links.
|
||||
|
||||
[Cygwin]: http://www.cygwin.com/
|
||||
[HTML Tidy]: http://tidy.sourceforge.net/
|
||||
[`iconv`]: http://www.gnu.org/software/libiconv/
|
||||
[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
|
||||
|
||||
Command-line options
|
||||
====================
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue