From 8ef0593fdf5e6397b6cca91bd8fb300ce3fbdbbf Mon Sep 17 00:00:00 2001 From: Daniel Gnoutcheff Date: Wed, 29 Sep 2021 22:11:18 -0400 Subject: Write README, cleanup packaging --- ChangeLog.md | 3 --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++- app/Main.hs | 11 +++++++++-- fast-pandoc.cabal | 40 -------------------------------------- ikiwiki-fast-pandoc.cabal | 40 ++++++++++++++++++++++++++++++++++++++ package.yaml | 4 ++-- 6 files changed, 99 insertions(+), 48 deletions(-) delete mode 100644 ChangeLog.md delete mode 100644 fast-pandoc.cabal create mode 100644 ikiwiki-fast-pandoc.cabal diff --git a/ChangeLog.md b/ChangeLog.md deleted file mode 100644 index 69ab8a3..0000000 --- a/ChangeLog.md +++ /dev/null @@ -1,3 +0,0 @@ -# Changelog for fast-pandoc - -## Unreleased changes diff --git a/README.md b/README.md index d570b2f..89a0439 100644 --- a/README.md +++ b/README.md @@ -1 +1,48 @@ -# fast-pandoc +# ikiwiki-fast-pandoc + +An "external" (XML-RPC) [IkiWiki][] plugin for rendering Markdown +fragments with [Pandoc][], replacing the default [mdwn][] plugin. + +[ikiwiki-pandoc][] has the same purpose as this plugin, and is easier +to install, more mature, and more featureful. However, fast-pandoc +can be significantly faster, especially if you use directives like +`\[[!table]]` and `\[[!report]]` that generate many Markdown fragments +that IkiWiki will htmlize individually. Whereas [ikiwiki-pandoc][] +will fork+exec the pandoc binary for every fragment, fast-pandoc +embeds pandoc in a co-process that runs alongside IkiWiki. At +[SFLC][], switching to fast-pandoc sped up rebuilds of an internal +wiki by 25-30%. + +[IkiWiki]: https://ikiwiki.info/ +[Pandoc]: https://pandoc.org/ +[mdwn]: https://ikiwiki.info/plugins/mdwn/ +[ikiwiki-pandoc]: https://github.com/sciunto-org/ikiwiki-pandoc +[SFLC]: https://softwarefreedom.org + +## Build and install + +Install git and [Haskell Stack](http://haskellstack.org/), then do: + +``` +git clone git://code.softwarefreedom.org/git/fast-pandoc +cd fast-pandoc +stack build +``` + +To make fast-pandoc available to your wiki, locate its "extra library +and plugin directory" (the `libdir` option in the *.setup file), +create a `plugins` subdirectory (if it doesn't already exist), and +install the `fast-pandoc` binary into it. (See also +.) Many wikis put their libdir +at `~/.ikiwiki`. + +``` +mkdir -p ~/.ikiwiki/plugins/ +stack install --local-bin-path ~/.ikiwiki/plugins +``` + +Finally, add `fast-pandoc` to the `add_plugins` list: + +``` +ikiwiki --changesetup ~/wiki.setup --plugin fast-pandoc +``` diff --git a/app/Main.hs b/app/Main.hs index c1ebbbd..299032d 100644 --- a/app/Main.hs +++ b/app/Main.hs @@ -6,8 +6,15 @@ -- -- Copyright (C) 2021 Software Freedom Law Center -- --- Licensed under the terms of the GNU General Public Licence (GPL) version 3 --- or (at your option) any later version. +-- This program is free software: you can redistribute it and/or modify +-- it under the terms of the GNU General Public License as published by +-- the Free Software Foundation, either version 3 of the License, or +-- (at your option) any later version. +-- +-- This program is distributed in the hope that it will be useful, +-- but WITHOUT ANY WARRANTY; without even the implied warranty of +-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +-- GNU General Public License for more details. module Main (main) where diff --git a/fast-pandoc.cabal b/fast-pandoc.cabal deleted file mode 100644 index a0fb105..0000000 --- a/fast-pandoc.cabal +++ /dev/null @@ -1,40 +0,0 @@ -cabal-version: 1.12 - --- This file has been generated from package.yaml by hpack version 0.34.4. --- --- see: https://github.com/sol/hpack - -name: fast-pandoc -version: 0.1.0.0 -description: Faster pandoc plugin for IkiWiki -author: Daniel Gnoutcheff -maintainer: gnoutchd@softwarefreedom.org -copyright: 2021 Software Freedom Law Center -license: GPL3 -build-type: Simple -extra-source-files: - README.md - ChangeLog.md - -executable fast-pandoc - main-is: Main.hs - other-modules: - XMLParse - Paths_fast_pandoc - hs-source-dirs: - app - ghc-options: -threaded -rtsopts -with-rtsopts=-N -Wall - build-depends: - HaXml - , base >=4.7 && <5 - , bytestring - , exceptions - , filepath - , haxr - , mtl - , pandoc - , pandoc-types - , polyparse - , split - , text - default-language: Haskell2010 diff --git a/ikiwiki-fast-pandoc.cabal b/ikiwiki-fast-pandoc.cabal new file mode 100644 index 0000000..8df9b83 --- /dev/null +++ b/ikiwiki-fast-pandoc.cabal @@ -0,0 +1,40 @@ +cabal-version: 1.12 + +-- This file has been generated from package.yaml by hpack version 0.34.4. +-- +-- see: https://github.com/sol/hpack + +name: ikiwiki-fast-pandoc +version: 0.1.0.0 +description: Faster pandoc plugin for IkiWiki +author: Daniel Gnoutcheff +maintainer: gnoutchd@softwarefreedom.org +copyright: 2021 Software Freedom Law Center +license: GPL3 +build-type: Simple +extra-source-files: + README.md + COPYING + +executable fast-pandoc + main-is: Main.hs + other-modules: + XMLParse + Paths_ikiwiki_fast_pandoc + hs-source-dirs: + app + ghc-options: -threaded -rtsopts -with-rtsopts=-N -Wall + build-depends: + HaXml + , base >=4.7 && <5 + , bytestring + , exceptions + , filepath + , haxr + , mtl + , pandoc + , pandoc-types + , polyparse + , split + , text + default-language: Haskell2010 diff --git a/package.yaml b/package.yaml index 9c94637..a9b9e08 100644 --- a/package.yaml +++ b/package.yaml @@ -1,4 +1,4 @@ -name: fast-pandoc +name: ikiwiki-fast-pandoc version: 0.1.0.0 license: GPL3 author: "Daniel Gnoutcheff" @@ -7,7 +7,7 @@ copyright: "2021 Software Freedom Law Center" extra-source-files: - README.md -- ChangeLog.md +- COPYING # Metadata used when publishing your package # synopsis: Short description of your package -- cgit v1.2.1