diff options
Diffstat (limited to 'web/index.txt')
| -rw-r--r-- | web/index.txt | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/web/index.txt b/web/index.txt new file mode 100644 index 000000000..88b5636de --- /dev/null +++ b/web/index.txt @@ -0,0 +1,290 @@ +% Pandoc + +# Overview + +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], +[PDF], [RTF], [DocBook XML], [OpenDocument XML], [ODT], [GNU Texinfo], +[MediaWiki markup], [groff man] pages, and [S5] HTML slide shows. + +Pandoc features + +- Modular design, using separate writers and readers for each + supported format. +- A real markdown parser, not based on regex substitutions. + [More accurate] and [much faster] than `Markdown.pl`. +- Also parses (subsets of) reStructuredText, LaTeX, and HTML. +- Multiple output formats: HTML, Docbook XML, LaTeX, ConTeXt, + reStructuredText, Markdown, RTF, groff man pages, OpenDocument + XML, ODT (Open Office document), MediaWiki, GNU Texinfo, + S5 slide shows. +- Unicode support. +- Optional "smart" quotes, dashes, and ellipses. +- Automatically generated tables of contents. +- Support for displaying math in HTML. +- Extensions to markdown syntax: + + Document metadata (title, author, date). + + Footnotes, tables, and definition lists. + + Superscripts, subscripts, and strikeout. + + Inline LaTeX math and LaTeX commands. + + Markdown inside HTML blocks. + + Enhanced ordered lists: start number and numbering style + are significant. + + Delimited (unindented) code blocks with syntax highlighting. + + Compatibility mode to turn off syntax entensions and emulate + `Markdown.pl`. +- Convenient wrapper scripts: + + `markdown2pdf` converts directly from markdown to PDF, using + `pdflatex`. + + `html2markdown` makes it easy to produce a markdown version + of any web page. + + `hsmarkdown` is a drop-in replacement for `Markdown.pl`. +- Multi-platform: runs on Windows, MacOS X, Linux, Unix. +- Free software, released under the [GPL]. + +To see what pandoc can do, see the [demonstration page](examples.html), +or [try pandoc on the web](/pandoc/try). + +# Documentation + +- [User's Guide](README.html) +- Man pages + - [`pandoc(1)`](pandoc.1.html) + - [`markdown2pdf(1)`](markdown2pdf.1.html) + - [`html2markdown(1)`](html2markdown.1.html) + - [`hsmarkdown(1)`](hsmarkdown.1.html) +- [Library documentation](doc/pandoc/index.html) (for Haskell programmers) +- [Installation instructions](INSTALL.html) +- [Changelog](changelog.txt) + +# Demonstrations + +- [Examples](examples.html) +- [Try pandoc online](http://johnmacfarlane.net/pandoc/try) + +# Installing pandoc + +Pandoc is in the [MacPorts], [Debian], [Ubuntu], [Slackware], [Arch], +[NetBSD], and [FreeBSD ports] repositories. Note that the version of +pandoc in these repositories may not be the most recent. There +is also a [Windows installer]. + +If an up-to-date package is not available for your system, an +excellent way to install the latest release of pandoc is to +install the [Haskell platform] on your system, then use the `cabal` +tool: + + cabal install pandoc + +This will download and compile pandoc and all of its dependencies. If +you want syntax highlighting support, add the flag `-fhighlighting` +(this requires that the [pcre](http://www.pcre.org/) library be +installed). If you want to install the wrapper scripts `hsmarkdown` and +`markdown2pdf`, add `-fwrappers`. + +Alternatively, you can download the [source tarball] and +follow the instructions in [INSTALL](INSTALL.html). + +# Extras + +- [pandoc-mode for emacs], by Joost Kremers +- [vim syntax file for pandoc], courtesy of tao_zhyn +- [WordPress EasyFilter], by Yang Zhang, makes it easy to use pandoc + with WordPress blogs. +- [a build configuration for Pandoc that produces a standalone C-callable + system library](http://github.com/toyvo/libpandoc/tree/master), + by Anton Tayanovskyy. + +# Code repository + +Pandoc has a publicly accesible subversion repository at Google +Code (<http://code.google.com/p/pandoc>). To check out the latest, +bleeding-edge source code: + + svn checkout http://pandoc.googlecode.com/svn/trunk/ pandoc + +# Reporting bugs + +You may view existing bug reports and submit new ones at +<http://code.google.com/p/pandoc/issues/list>. + +# Mailing lists + +- [pandoc-announce]: Announcements of new releases only. +- [pandoc-discuss]: General discussion of pandoc. + +# News + +- Version 1.4 release (January 2, 2010). + + + New template system replaces old headers, giving users much + more control over pandoc's output in `--standalone` mode. + Added `--template` and `--variable` options. The `--print-default-header` + option is now `--print-default-template`. See README under + "Templates" for details. + + The old `--custom-header` option should still work, but it has + been deprecated. + + New `--reference-odt` option allows users to customize styles + in ODT output. + + Users may now put custom templates, s5 styles, and a reference + ODT in the `~/.pandoc` directory, where they will override system + defaults. See README for details. + + Unicode is now used whenever possible in HTML and XML output. Entities + are used only where necessary (`>`, `<`, `"`, `&`). + + Authors and dates may now include formatting and notes. + + Added `--xetex` option for `pandoc` and `markdown2pdf`. + + Windows installer now includes highlighting support and + `markdown2pdf` and `hsmarkdown` wrappers. + + Pandoc no longer requires Template Haskell, which should make + it more portable. + + Pandoc can now be built on GHC 6.12, as well as earlier versions. + + See README for other small improvements and bug fixes. + +- Version 1.3 release (December 10, 2009). + + + Added --id-prefix option to help prevent duplicate + identifiers when you're generating HTML fragments. + + Added --indented-code-classes option, which specifies + default highlighting syntax for indented code blocks. + + --number-sections now affects HTML output. + + Improved syntax for markdown definition lists. + + Better looking simple tables. + + Markdown tables without headers are now possible. + + New hard line break syntax: backslash followed by newline. + + Improved performance of markdown reader by ~10% by eliminating the + need for a separate parsing pass for notes. + + Improved syntax highlighting for literate Haskell. + + Support for "..code-block" directive in RST reader. + + Windows binary now includes highlighting support. + + Many bug fixes and small improvements. See [changelog] + for details. + +- Version 1.2.1 release (July 18, 2009). + + + Improved the efficiency of the markdown reader's + abbreviation parsing (should give a big performance + boost with --smart). + + HTML writer now wraps sections in divs with unique + identifiers, for easier manipulation. + + Improved LaTeX reader's coverage of math modes. + + Added a portable Haskell version of markdown2pdf (thanks + to Paolo Tanimoto). + + Made --strict compatible with --standalone and --toc. + + Many other small improvements and bug fixes. + See [changelog] for details. + +- Version 1.2 release (March 1, 2009). + + + Added support for literate Haskell. lhs support is triggered by + '+lhs' suffixes in formats. For example, 'latex+lhs' is literate + Haskell LaTeX. '.lhs' files are treated by default as literate + markdown. + + Added --email-obfuscation option. + + Brought citeproc support up to date for citeproc-hs-0.2. + + Many bugs fixed. See [changelog] for details. + +- Version 1.1 release (November 6, 2008). + + + New --jsmath option supporting use of pandoc with [jsMath]. + + Classes on HTML table output for better CSS styling. + + Windows installer no longer requires admin privileges. + + Many bugs fixed. See [changelog] for details. + +- Version 1.0 release (September 13, 2008). + + + New writers for MediaWiki, GNU Texinfo (thanks to Peter Wang), + OpenDocument XML (thanks to Andrea Rossato), and ODT (OpenOffice + document). + + New [delimited code blocks](README.html#delimited-code-blocks), + with optional syntax highlighting. + + Reorganized build system: pandoc can now be built using standard + Cabal tools. It can be compiled on Windows without Cygwin. + The tests can also be run without perl or unix tools. + + LaTeXMathML replaces ASCIIMathML for rendering math in HTML. + + Support for "displayed" math. + + Common abbreviations are now handled more intelligently, with + a non-breaking space (and not a sentence-ending space) after + the period. + + Code is -Wall clean. + + Many bug fixes and small improvements. See [changelog] for + full details. + +- Version 0.46 released (January 8, 2008). + + + Added a `--sanitize-html` option (and a corresponding parameter + in `ParserState` for those using the pandoc libraries in programs). + This option causes pandoc to sanitize HTML (in HTML or Markdown + input) using a whitelist method. Possibly harmful HTML elements + are replaced with HTML comments. This should be useful in the + context of web applications, where pandoc may be used to convert + user input into HTML. + + Made -H, -A, and -B options cumulative: if they are specified + multiple times, multiple files will be included. + + Many bug fixes and small improvements. See [changelog] for full + details. + +- Version 0.45 released (December 9, 2007). + + + Many bug fixes and structural improvements. See [changelog] for + full details. + + Improved treatment of math. Math is now rendered using unicode + by default in HTML, RTF, and DocBook output. For more accurate + display of math in HTML, `--gladtex`, `--mimetex`, and `--asciimathml` + options are provided. See the [User's Guide](README.html#math) for + details. + + Removed support for box-style block quotes in markdown. + + More idiomatic ConTeXt output. + + Text wrapping in ConTeXt and LaTeX output. + + Pandoc now correctly handles all standard line endings + (CR, LF, CRLF). + + New `--no-wrap` option that disables line wrapping and minimizes + whitespace in HTML output. + + Build process is now compatible with both GHC 6.8 and GHC 6.6. + GHC and GHC_PKG environment variables may be used to specify + which version of the compiler to use, when multiple versions are + installed. + +# Disclaimer + +Pandoc carries no warranties of any kind. + +[More accurate]: http://code.google.com/p/pandoc/wiki/PandocVsMarkdownPl +[much faster]: http://code.google.com/p/pandoc/wiki/Benchmarks + +[John MacFarlane]: http://johnmacfarlane.net/ +[markdown]: http://daringfireball.net/projects/markdown/ +[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html +[S5]: http://meyerweb.com/eric/tools/s5/ +[HTML]: http://www.w3.org/TR/html40/ +[LaTeX]: http://www.latex-project.org/ +[ConTeXt]: http://www.pragma-ade.nl/ +[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format +[PDF]: http://en.wikipedia.org/wiki/Portable_Document_Format +[ODT]: http://en.wikipedia.org/wiki/OpenDocument +[DocBook XML]: http://www.docbook.org/ +[OpenDocument XML]: http://opendocument.xml.org/ +[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting +[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html +[GNU Texinfo]: http://www.gnu.org/software/texinfo/ +[Haskell]: http://www.haskell.org/ +[GHC]: http://www.haskell.org/ghc/ +[GPL]: http://www.gnu.org/copyleft/gpl.html +[Source tarball]: http://code.google.com/p/pandoc/downloads/detail?name=pandoc-@VERSION@.tar.gz "Download source tarball from Pandoc's Google Code site" +[Windows installer]: http://code.google.com/p/pandoc/downloads/detail?name=pandoc-@VERSION@-setup.exe "Download Windows installer from Pandoc's Google Code site" +[Debian]: http://packages.debian.org/lenny/pandoc +[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver= +[Arch]: http://aur.archlinux.org/packages.php?ID=19804 +[NetBSD]: http://pkgsrc.se/wip/pandoc +[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/ +[Ubuntu]: http://www.ubuntu.com +[MacPorts]: http://db.macports.org/port/show/4218 +[pandoc-announce]: http://groups.google.com/group/pandoc-announce +[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss +[changelog]: changelog.txt +[vim syntax file for pandoc]: http://www.vim.org/scripts/script.php?script_id=2389 +[jsMath]: http://www.math.union.edu/~dpvc/jsMath/ +[WordPress EasyFilter]: http://assorted.sourceforge.net/wp-easy-filter/ +[Haskell platform]: http://hackage.haskell.org/platform/ +[pandoc-mode for emacs]: http://joostkremers.fastmail.fm/pandoc-mode.html |