Merge branch 'master' into groff_reader

1 files changed, 37 insertions, 1 deletions

diff --git a/README.template b/README.template
index cf664647a..7b5d0b7b9 100644
--- a/README.template
+++ b/README.template
@@ -19,9 +19,44 @@ Pandoc
 The universal markup converter
 ------------------------------
 
-::: description
+Pandoc is a [Haskell] library for converting from one markup format to
+another, and a command-line tool that uses this library.  It can convert *from*
+
+::: {#input-formats}
 :::
 
+It can convert *to*
+
+::: {#output-formats}
+:::
+
+Pandoc can also produce PDF output via LaTeX, Groff ms, or HTML.
+
+Pandoc's enhanced version of Markdown includes syntax for tables,
+definition lists, metadata blocks, footnotes, citations, math,
+and much more.  See the User's Manual below under
+[Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown).
+
+Pandoc has a modular design: it consists of a set of readers, which parse
+text in a given format and produce a native representation of the document
+(an _abstract syntax tree_ or AST), and a set of writers, which convert
+this native representation into a target format. Thus, adding an input
+or output format requires only adding a reader or writer. Users can also
+run custom pandoc filters to modify the intermediate AST (see
+the documentation for [filters](https://pandoc.org/filters.html)
+and [lua filters](https://pandoc.org/lua-filters.html)).
+
+Because pandoc's intermediate representation of a document is less
+expressive than many of the formats it converts between, one should
+not expect perfect conversions between every format and every other.
+Pandoc attempts to preserve the structural elements of a document, but
+not formatting details such as margin size.  And some document elements,
+such as complex tables, may not fit into pandoc's simple document
+model.  While conversions from pandoc's Markdown to all formats aspire
+to be perfect, conversions from formats more expressive than pandoc's
+Markdown can be expected to be lossy.
+
+
 Installing
 ----------
 
@@ -52,3 +87,4 @@ License
 any kind.  (See COPYRIGHT for full copyright and warranty notices.)
 
 [GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
+[Haskell]: http://haskell.org