Sync your README with your Haskell codebase.

Convert files between:

• Haskell (.hs)
• Literate Haskell (.lhs)
• GitHub Flavored Markdown (.md)
• TeX (.tex)

• LiterateMarkdown - lima is a fork of this abandoned project.

• pandoc - supports Literate Haskell and a ton of other formats.

• IHaskell - create Jupyter notebooks with Haskell code cells and GitHub Flavored Markdown text cells.

• lhs2tex - convert Literate Haskell to TeX.

• agda2lagda - Generate a literate Agda/Haskell script from an Agda/Haskell script. Produces LaTeX or Markdown literate scripts.

• markdown-unlit - markdown-unlit is a custom unlit program. It can be used to extract Haskell code from Markdown files.

• unlit - Tool to convert literate code between styles or to code.

• design-tools - a Pandoc filter for building a book from Markdown.

• literatex - transform literate source code to Markdown

lima focuses on converting documents between formats and allows to concatenate documents.

Other scenarios, e.g., inlining a document into a document, may require specialized tools.

.hs and .md

.hs and .lhs and .tex

• A document is a text in a supported format.
• I introduced tags into supported formats.
  • E.g., in .hs documents, tags are multiline comments written on a single line like '{- LIMA_ENABLE -}'.
• Tag names are configurable.
  • A user may set 'on' instead of 'LIMA_ENABLE'.
• A document can be parsed into a list of tokens.
• Tags affect document parsing.
• The tokens can be printed back to that document.
• Formatting a document is printing a parsed document back to itself.
  • Formatting is idempotent. In other words, formatting the document again won't change its content.
• The lima library provides a parser and a printer for each supported format.
• A composition of a printer after a parser produces a converter.
• Such a converter is usually invertible for a formatted document.
  • Converting a document A to a document B, then converting B to A doesn't change the content of A.

1. Create a test suite. README.hs may be its main file.

2. Add lima and text to its dependencies.

3. Create a test module. It may have the following content.

   import Lima.Converter (Format (..), convertTo, def)
   import Data.Text.IO qualified as T
   
   main :: IO ()
   main = T.readFile "README.hs" >>= T.writeFile "README.md" . (Hs `convertTo` Md) def

This package has three such test suites:

• readme converts README.hs to README.md. README.hs is its main file.
• readme-hs-to-md converts README.hs to README.md.
• readme-md-to-hs converts README.md to README.hs.

Here's a suggested workflow for Haskell and Markdown:

1. Edit the code in a README.hs using Haskell Language Server.
2. Convert README.hs to a README.md. Comments from README.hs become text in README.md.
3. Edit the text in README.md using markdownlint.
4. Convert README.md back to the README.hs to keep files in sync. Text from README.md becomes comments in README.hs.
5. Repeat.

Clone this repo and enter lima.

git clone https://github.com/deemp/lima
cd lima

Build

cabal update
cabal build

1. Install Nix.

2. Run a devshell and build lima using the project's cabal:

   nix develop nix-dev/
   cabal build

3. Optionally, start VSCodium:

   nix run nix-dev/#writeSettings
   nix run nix-dev/#codium .

4. Open a Haskell file there, hover over a term and wait until HLS shows hints.

5. Troubleshoot if necessary.