Merge pull request #3033 from tarleb/github-readme

PoC: GitHub-optimized README

12 files changed, 145 insertions, 26 deletions

diff --git a/.gitignore b/.gitignore
index 9b7630a4c..0e2686c83 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,7 @@
 *~
 dist/*
-README.*
-!README.Debian
+MANUAL.*
+!MANUAL.txt
 INSTALL.*
 .configure-stamp
 .cabal-sandbox
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f39acab10..31d786214 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,7 +29,7 @@ Out of scope?
 -------------
 
 A less than perfect conversion does not necessarily mean there's
-a bug in pandoc.  Quoting from the README:
+a bug in pandoc.  Quoting from the MANUAL:
 
 > Because Pandoc's intermediate representation of a document is less
 > expressive than many of the formats it converts between, one should
@@ -124,7 +124,7 @@ Please follow these guidelines:
     below under [Tests](#tests).)  If you are adding a new writer or reader,
     you must include tests.
 
-7.  If you are adding a new feature, include updates to the README.
+7.  If you are adding a new feature, include updates to the README and MANUAL.
 
 8.  All code must be released under the general license governing pandoc
     (GPL v2).
@@ -259,7 +259,7 @@ The library is structured as follows:
   - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
   - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
   - `Text.Pandoc.Slides` contains functions for splitting a markdown document
-    into slides, using the conventions described in the README.
+    into slides, using the conventions described in the MANUAL.
   - `Text.Pandoc.Templates` defines pandoc's templating system.
   - `Text.Pandoc.UTF8` contains functions for converting text to and from
     UTF8 bytestrings (strict and lazy).
@@ -270,7 +270,7 @@ The library is structured as follows:
 
 [pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
 [issue tracker]: https://github.com/jgm/pandoc/issues
-[User's Guide]: http://pandoc.org/README.html
+[User's Guide]: http://pandoc.org/MANUAL.html
 [FAQs]:  http://pandoc.org/faqs.html
 [EditorConfig]: http://editorconfig.org/
 [Haskell platform]: http://www.haskell.org/platform/
diff --git a/INSTALL b/INSTALL
index bfb548913..87be44eca 100644
--- a/INSTALL
+++ b/INSTALL
@@ -95,7 +95,7 @@ Quick install with cabal
 
 The `pandoc.1` man page will be installed automatically.  cabal shows
 you where it is installed: you may need to set your `MANPATH`
-accordingly. If `README` has been modified, the man page can be
+accordingly. If `MANUAL.txt` has been modified, the man page can be
 rebuilt: `make man/pandoc.1`.
 
 The `pandoc-citeproc.1` man page will also be installed automatically.
diff --git a/README b/MANUAL.txt
index 8d5be98f8..8d5be98f8 100644
--- a/README
+++ b/MANUAL.txt
diff --git a/Makefile b/Makefile
index 00eb51321..19d0a50af 100644
--- a/Makefile
+++ b/Makefile
@@ -56,7 +56,7 @@ pandoc-$(version)-windows.msi:
 	osslsigncode sign -pkcs12 ~/Private/ComodoCodeSigning.exp2017.p12 -in pandoc.msi -i http://johnmacfarlane.net/ -t http://timestamp.comodoca.com/ -out $@ -askpass
 	rm pandoc.msi
 
-man/pandoc.1: README man/pandoc.1.template
+man/pandoc.1: MANUAL.txt man/pandoc.1.template
 	pandoc $< -t man -s --template man/pandoc.1.template \
 		--filter man/capitalizeHeaders.hs \
 		--filter man/removeNotes.hs \
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..95918e221
--- /dev/null
+++ b/README.md
@@ -0,0 +1,119 @@
+Pandoc
+======
+
+The universal markup converter
+------------------------------
+
+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], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
+[MultiMarkdown], and (subsets of) [Textile], [reStructuredText], [HTML],
+[LaTeX], [MediaWiki markup], [TWiki markup], [Haddock markup], [OPML], [Emacs
+Org mode], [DocBook], [txt2tags], [EPUB], [ODT] and [Word docx]; and it can
+write plain text, [Markdown], [CommonMark], [PHP Markdown Extra],
+[GitHub-Flavored Markdown], [MultiMarkdown], [reStructuredText], [XHTML],
+[HTML5], [LaTeX] (including [`beamer`] slide shows), [ConTeXt], [RTF], [OPML],
+[DocBook], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki
+markup], [DokuWiki markup], [ZimWiki markup], [Haddock markup],
+[EPUB] (v2 or v3), [FictionBook2], [Textile], [groff man] pages,
+[Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI Simple], and [Slidy],
+[Slideous], [DZSlides], [reveal.js] or [S5] HTML slide shows. It can also
+produce [PDF] output on systems where LaTeX, ConTeXt, or `wkhtmltopdf` is
+installed.
+
+Pandoc's enhanced version of Markdown includes syntax for footnotes, tables,
+flexible ordered lists, definition lists, fenced code blocks, superscripts and
+subscripts, strikeout, metadata blocks, automatic tables of contents, embedded
+LaTeX math, citations, and Markdown inside HTML block elements. (These
+enhancements, described in the manual under *pandoc's Markdown*, can be
+disabled using the `markdown_strict` input or output format.)
+
+In contrast to most existing tools for converting Markdown to HTML, which
+use regex substitutions, 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, 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.
+
+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.
+
+[Markdown]: http://daringfireball.net/projects/markdown/
+[CommonMark]: http://commonmark.org
+[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
+[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
+[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
+[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+[S5]: http://meyerweb.com/eric/tools/s5/
+[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
+[Slideous]: http://goessner.net/articles/slideous/
+[HTML]: http://www.w3.org/html/
+[HTML5]: http://www.w3.org/TR/html5/
+[XHTML]: http://www.w3.org/TR/xhtml1/
+[LaTeX]: http://latex-project.org
+[`beamer`]: https://ctan.org/pkg/beamer
+[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf
+[ConTeXt]: http://contextgarden.net/
+[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
+[DocBook]: http://docbook.org
+[txt2tags]: http://txt2tags.org
+[EPUB]: http://idpf.org/epub
+[OPML]: http://dev.opml.org/spec2.html
+[OpenDocument]: http://opendocument.xml.org
+[ODT]: http://en.wikipedia.org/wiki/OpenDocument
+[Textile]: http://redcloth.org/textile
+[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
+[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
+[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
+[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
+[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
+[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
+[Haskell]: https://www.haskell.org
+[GNU Texinfo]: http://www.gnu.org/software/texinfo/
+[Emacs Org mode]: http://orgmode.org
+[AsciiDoc]: http://www.methods.co.nz/asciidoc/
+[DZSlides]: http://paulrouget.com/dzslides/
+[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx
+[PDF]: https://www.adobe.com/pdf/
+[reveal.js]: http://lab.hakim.se/reveal-js/
+[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
+[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
+[TEI Simple]: https://github.com/TEIC/TEI-Simple
+
+[![license](https://img.shields.io/badge/license-GPLv2+-brightgreen.svg)](https://www.gnu.org/licenses/gpl.html)
+[![hackage release](https://img.shields.io/hackage/v/pandoc.svg?label=current+release)](http://hackage.haskell.org/package/pandoc)
+[![stackage LTS package](http://stackage.org/package/pandoc/badge/lts)](http://stackage.org/lts/package/pandoc)
+[![github release](https://img.shields.io/github/release/jgm/pandoc.svg?label=github+release)](https://github.com/jgm/pandoc/releases)
+[![travis build status](https://img.shields.io/travis/jgm/pandoc.svg)](https://travis-ci.org/jgm/pandoc)
+
+
+Documentation
+-------------
+
+The full documentation can be found [online](https://pandoc.org/MANUAL.html)
+and as pandoc-flavored Markdown in the file `MANUAL.txt`.
+
+
+Contributing
+------------
+
+Pull requests, bug reports, and feature requests are welcome.  Please make
+sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a
+new issue.
+
+
+License
+-------
+
+© 2006-2016 John MacFarlane (jgm@berkeley.edu). Released under the
+[GPL], version 2 or greater.  This software carries no warranty of
+any kind.  (See COPYRIGHT for full copyright and warranty notices.)
+
+[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
diff --git a/appveyor.yml b/appveyor.yml
index 7ce7dc171..e7728dba5 100644
--- a/appveyor.yml
+++ b/appveyor.yml
@@ -37,7 +37,7 @@ after_test:
     # .\ in the stack commandline seems to be .\windows\ (where the stack-appveyor.yaml is)
   - cd windows
   - 7z a "pandoc.zip" pandoc.exe
-  - .\pandoc.exe -s -S --toc ..\README -o README.html
+  - .\pandoc.exe -s -S --toc ..\MANUAL.txt -o MANUAL.html
   - .\pandoc.exe -s -S ..\COPYING -o COPYING.rtf
   - copy ..\COPYRIGHT COPYRIGHT.txt
   - |
diff --git a/pandoc.cabal b/pandoc.cabal
index 140390c98..9599f4f80 100644
--- a/pandoc.cabal
+++ b/pandoc.cabal
@@ -105,10 +105,10 @@ Data-Files:
                  -- bash completion template
                  data/bash_completion.tpl
                  -- documentation
-                 README, COPYRIGHT
+                 MANUAL.txt, COPYRIGHT
 Extra-Source-Files:
                  -- documentation
-                 INSTALL, BUGS, CONTRIBUTING.md, changelog
+                 INSTALL, BUGS, README.md, CONTRIBUTING.md, changelog
                  man/pandoc.1
                  -- stack build plan
                  stack.yaml
diff --git a/src/Text/Pandoc/Data.hsb b/src/Text/Pandoc/Data.hsb
index d408bf510..8786647c5 100644
--- a/src/Text/Pandoc/Data.hsb
+++ b/src/Text/Pandoc/Data.hsb
@@ -12,4 +12,4 @@ dataFiles = map (\(fp, contents) ->
   (Posix.joinPath (splitDirectories fp), contents)) dataFiles'
 
 dataFiles' :: [(FilePath, B.ByteString)]
-dataFiles' = ("README", %blob "README") : %blobs "data"
+dataFiles' = ("MANUAL.txt", %blob "MANUAL.txt") : %blobs "data"
diff --git a/src/Text/Pandoc/Shared.hs b/src/Text/Pandoc/Shared.hs
index cc834a69a..bd299a802 100644
--- a/src/Text/Pandoc/Shared.hs
+++ b/src/Text/Pandoc/Shared.hs
@@ -873,7 +873,7 @@ readDefaultDataFile fname =
         go as     x    = x : as
 #else
   getDataFileName fname' >>= checkExistence >>= BS.readFile
-    where fname' = if fname == "README" then fname else "data" </> fname
+    where fname' = if fname == "MANUAL.txt" then fname else "data" </> fname
 
 checkExistence :: FilePath -> IO FilePath
 checkExistence fn = do
@@ -1071,7 +1071,7 @@ blocksToInlinesWithSep sep blks = intercalate sep $ map blockToInlines blks
 
 blocksToInlines :: [Block] -> [Inline]
 blocksToInlines = blocksToInlinesWithSep [Space, Str "¶", Space]
-        
+
 
 --
 -- Safe read
diff --git a/windows/make-windows-installer.bat b/windows/make-windows-installer.bat
index 892a61cdc..75fd01b4f 100644
--- a/windows/make-windows-installer.bat
+++ b/windows/make-windows-installer.bat
@@ -2,7 +2,7 @@
 stack install --test

 if %errorlevel% neq 0 exit /b %errorlevel%

 for /f "delims=" %%a in ('stack path --local-bin-path') do @set BINPATH=%%a

-%BINPATH%\pandoc.exe -s -S --toc ..\README -o README.html

+%BINPATH%\pandoc.exe -s -S --toc ..\MANUAL -o MANUAL.html

 if %errorlevel% neq 0 exit /b %errorlevel%

 %BINPATH%\pandoc.exe -s ..\COPYING -t rtf -S -o COPYING.rtf

 if %errorlevel% neq 0 exit /b %errorlevel%

@@ -14,7 +14,7 @@ for /f "tokens=1-2 delims= " %%a in ('%BINPATH%\pandoc.exe --version') do (
 :next

 if "%VERSION%" == "" (

   echo Error: could not determine version number.

-  exit /b 1 

+  exit /b 1

 )

 echo Detected version %VERSION%

 echo Creating msi...

diff --git a/windows/pandoc.wxs b/windows/pandoc.wxs
index 50a686e55..dcdd3f582 100644
--- a/windows/pandoc.wxs
+++ b/windows/pandoc.wxs
@@ -57,8 +57,8 @@
 
           <Component Id="Documentation"
                      Guid="A8D54A76-1A3D-4647-8327-81B69D39D8A3">
-            <File Id="pandocREADME" Name="Pandoc User's Guide.html"
-                  Source="README.html" KeyPath="yes">
+            <File Id="pandocMANUAL" Name="Pandoc User's Guide.html"
+                  Source="MANUAL.html" KeyPath="yes">
               <Shortcut Id="ApplicationStartMenuShortcut"
                         Directory="ApplicationProgramsFolder"
                         Name="Pandoc User’s Guide" Advertise="yes" />
@@ -123,18 +123,18 @@
       </Feature>
     </Feature>
 
-    
+
     <!-- Set properties for add/remove programs -->
     <Property Id="ARPURLINFOABOUT" Value="http://pandoc.org" />
     <Property Id="ARPHELPLINK" Value="http://pandoc.org" />
     <Property Id="ARPNOREPAIR" Value="yes" Secure="yes" />    <!-- Remove repair -->
     <Property Id="ARPNOMODIFY" Value="yes" Secure="yes" />    <!-- Remove modify -->
 
-      
+
     <!--Needed for WixUI_Advanced-->
     <Property Id="ApplicationFolderName" Value="Pandoc" />
     <Property Id="WixAppFolder" Value="WixPerUserFolder" />
-    
+
     <!--For Single Package for dual purpose i.e. per User/Machine-->
     <!--<Property Id="ALLUSERS" Value="2" Secure="yes" />-->
     <Property Id="MSIINSTALLPERUSER" Value="1" />
@@ -145,7 +145,7 @@
     <CustomAction Id="SetExitDialogOptText"
                       Property="WIXUI_EXITDIALOGOPTIONALTEXT"
                       Value="!(loc.ExitDialogText)" />
-    
+
     <!--Offer Per User installs only on workstations (block on servers)-->
     <!--Unless ALLUSERS=1 is specified on command line-->
     <SetProperty Id="WixUISupportPerUser" Value="0" Before="FindRelatedProducts">
@@ -177,12 +177,12 @@
         NOT Installed
       </Custom>
     </InstallUISequence>
-    
+
     <UIRef Id="WixUI_Advanced_Custom"/>
     <!--Enable better description when debug logging-->
     <UIRef Id="WixUI_ErrorProgressText" />
-    
+
   </Product>
-  
-  
+
+
 </Wix>