The Kalem Book GitHub

This Book describes Kalem's main branch, which may be ahead of the latest release.

The command line

The command line's own help, generated when the Book is built: kalem --help, then each subcommand's. 

Kalem: a fast, text-first editor that opens every plain-text format as itself and keeps it byte for byte: Org, Markdown, LaTeX, CSV, BibTeX and code

Usage: kalem [FILE | FOLDER]      the editor: graphical where there is a display, else in the terminal
       kalem gui [FILE]           the graphical editor
       kalem tui [FILE]           the terminal editor (also kalem -t [FILE])
       kalem tui --detect         what the terminal can do
       kalem <COMMAND>            a command-line tool

Commands:
  view      Show a file that is not text through the viewer that opens it: a unit as PNG, or its text and information
  parse     Print the syntax tree of a file
  check     Check files: syntax diagnostics and round-trip verification (Org, Markdown, LaTeX, CSV and BibTeX files)
  commands  List the commands, one a line: ID, title, scope and keys; with `--type`, those that serve that text type (`org`, `python`, `csv`)
  complete  Print the completions at a place in a file, one a line: label, kind and the completer (`kalem complete notes.org:12:5`)
  fmt       Align tables and tags, and blank lines as each file has them
  export    Export Org files as Emacs's Org exporter does: `kalem export notes.org --to html` writes `notes.html` beside it (or the file `#+EXPORT_FILE_NAME` names)
  import    Convert Word, OpenDocument, Markdown, HTML, EPUB or RTF files to Org through pandoc, cleaned up: `kalem import report.docx` writes `report.org` beside it, its pictures in `report_assets`
  plugin    Plugins: `kalem plugin browse`, `install NAME|URL|PATH`, `list`, `check`, `remove ID`, `enable ID`, `new NAME`, `build [DIR]`, `dev [DIR]`
  lsp       Language servers: `kalem lsp status`, `kalem lsp check FILE`, `kalem lsp ask REQUEST FILE [LINE:COLUMN]`
  latex     LaTeX documents: `kalem latex build FILE`
  book      The Book: `kalem book build`, `kalem book check`
  table     Table formulas: `kalem table recalc FILE...`
  query     Print the headlines matching an Org match string, such as `kalem query notes.org 'TODO="NEXT"+work'`
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

  -V, --version
          Print version

Environment:
  KALEM_CONFIG_DIR  the settings, keys and plugins (~/.config/kalem; %APPDATA%\kalem on Windows)
  KALEM_STATE_DIR   the log, crash reports and caches (~/.local/state/kalem; %LOCALAPPDATA%\kalem)
  KALEM_LOG         what the log keeps: `debug`, or per module (`kalem_core=debug,info`)

1. kalem view

Show a file that is not text through the viewer that opens it: a unit as PNG, or its text and information

Usage: kalem view [OPTIONS] <FILE>

Arguments:
  <FILE>
          The file

Options:
      --unit <UNIT>
          The unit (page, frame), from 1
          
          [default: 1]

      --to <TO>
          What to write

          Possible values:
          - txt: The unit's text and the file's information
          - png: The unit as a PNG picture
          
          [default: txt]

  -o, --output <OUTPUT>
          Where to write the PNG (standard output otherwise)

  -h, --help
          Print help (see a summary with '-h')

2. kalem parse

Print the syntax tree of a file

Usage: kalem parse <FILE>

Arguments:
  <FILE>
          The Org, Markdown or LaTeX file to parse

Options:
  -h, --help
          Print help

3. kalem check

Check files: syntax diagnostics and round-trip verification (Org, Markdown, LaTeX, CSV and BibTeX files)

Usage: kalem check [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Files to check; a folder stands for those under it

Options:
      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

      --deny-warnings
          Exit with status 1 when there are warnings

      --unrendered
          For LaTeX files, also list the commands and environments the editor shows as source, most frequent first

  -h, --help
          Print help

4. kalem commands

List the commands, one a line: ID, title, scope and keys; with `--type`, those that serve that text type (`org`, `python`, `csv`)

Usage: kalem commands [OPTIONS]

Options:
      --type <TEXT_TYPE>
          A text type

  -h, --help
          Print help

5. kalem complete

Print the completions at a place in a file, one a line: label, kind and the completer (`kalem complete notes.org:12:5`)

Usage: kalem complete <PLACE>

Arguments:
  <PLACE>
          `FILE:LINE:COLUMN` (1-based; the column in characters)

Options:
  -h, --help
          Print help

6. kalem fmt

Align tables and tags, and blank lines as each file has them

Usage: kalem fmt [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Org and LaTeX files, and code whose language has a formatter, to format in place; other files are left as they are, with a note

Options:
      --check
          Change nothing; list the files that would change and fail if there are any (for CI)

      --align
          LaTeX: line up the `&` of tables and alignments

  -h, --help
          Print help

7. kalem export

Export Org files as Emacs's Org exporter does: `kalem export notes.org --to html` writes `notes.html` beside it (or the file `#+EXPORT_FILE_NAME` names)

Usage: kalem export [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Org files to export

Options:
      --to <TO>
          The format

          Possible values:
          - html:  HTML
          - md:    Markdown, as Emacs's `ox-md` writes it (tables as HTML)
          - gfm:   GitHub Flavored Markdown: pipe tables, fenced code, `~~strike~~`
          - org:   Strict Org, without what earlier versions of Kalem added to it
          - latex: LaTeX, as Emacs's `ox-latex` writes it
          - txt:   Plain text, as Emacs's `ox-ascii` writes it
          - utf8:  Plain text with UTF-8 lines, bullets and quotes
          - pdf:   PDF through LaTeX (`latexmk`, the TeX engine or `tectonic`)
          - docx:  Word, through pandoc
          - odt:   OpenDocument text, through pandoc
          - epub:  EPUB, through pandoc
          - rtf:   Rich Text Format, through pandoc
          
          [default: html]

  -o, --output <OUTPUT>
          Where to write (one input file only); `-` for standard output

      --body-only
          Only the document's body, without the page around it

      --subtree <HEADLINE>
          Only the subtree of this headline (its title, or `#` and its `CUSTOM_ID`), with its `EXPORT_` properties, as `C-c C-e C-s`

      --source-lines
          LaTeX: a `%% org:LINE` comment before each element, giving the line of the Org file it comes from

  -h, --help
          Print help (see a summary with '-h')

8. kalem import

Convert Word, OpenDocument, Markdown, HTML, EPUB or RTF files to Org through pandoc, cleaned up: `kalem import report.docx` writes `report.org` beside it, its pictures in `report_assets`

Usage: kalem import [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Files to convert

Options:
  -o, --output <OUTPUT>
          Where to write (one input file only); `-` for standard output

      --force
          Replace an Org file that exists

  -h, --help
          Print help

9. kalem diff-pandoc

Compares the structure Kalem reads in LaTeX files with pandoc's LaTeX reader: headings, formulas, citations, footnotes, figures, tables, code blocks and list items (development)

Usage: kalem diff-pandoc [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          LaTeX files to compare

Options:
      --summary
          Print how many files agree in each category

      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

  -h, --help
          Print help

10. kalem latex-coverage

How much of a corpus of LaTeX sources the rendered view covers: by field (the folders under DIR), the share of the body shown as source, and the most frequent commands and environments (development)

Usage: kalem latex-coverage [OPTIONS] <DIRS>...

Arguments:
  <DIRS>...
          Folders of sources: DIR/FIELD/PAPER/*.tex

Options:
      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

      --top <TOP>
          How many commands and environments to list
          
          [default: 200]

  -h, --help
          Print help

11. kalem plugin

Plugins: `kalem plugin browse`, `install NAME|URL|PATH`, `list`, `check`, `remove ID`, `enable ID`, `new NAME`, `build [DIR]`, `dev [DIR]`

Usage: kalem plugin <COMMAND>

Commands:
  browse   The plugins of the index (`plugins.index`), and which are installed
  install  Installs a plugin: a name from the index (`elixir`), a GitHub folder or repository link, an archive link, or a folder or archive on disk. Shows what it is and asks first
  list     The installed plugins
  check    Starts every installed component viewer once, as opening a file would, and loads every installed extension plugin as starting it would, without activating it; exits 1 when one cannot run with this Kalem (built for another version of the plugin API)
  new      Starts a plugin: in a checkout of getkalem/plugins its template as `plugins/NAME`, elsewhere a crate of its own in `NAME/`
  build    Builds the plugin in DIR (the current folder by default): Cargo compiles it for wasm32-unknown-unknown, and the module becomes the component `main` names in plugin.json
  dev      Builds the plugin in DIR (the current folder by default) with its functions' names kept, installs it, and builds and installs it again whenever its sources change, until stopped: a Kalem running opens files with the new build
  remove   Removes an installed plugin
  enable   Turns on again a plugin Kalem turned off after it stopped three times (a trap, its time or its memory spent)
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

11.1. kalem plugin browse

The plugins of the index (`plugins.index`), and which are installed

Usage: kalem plugin browse

Options:
  -h, --help
          Print help

11.2. kalem plugin install

Installs a plugin: a name from the index (`elixir`), a GitHub folder or repository link, an archive link, or a folder or archive on disk. Shows what it is and asks first

Usage: kalem plugin install [OPTIONS] <SOURCE>

Arguments:
  <SOURCE>
          The plugin

Options:
  -y, --yes
          Install without asking

  -h, --help
          Print help

11.3. kalem plugin list

The installed plugins

Usage: kalem plugin list

Options:
  -h, --help
          Print help

11.4. kalem plugin check

Starts every installed component viewer once, as opening a file would, and loads every installed extension plugin as starting it would, without activating it; exits 1 when one cannot run with this Kalem (built for another version of the plugin API)

Usage: kalem plugin check

Options:
  -h, --help
          Print help

11.5. kalem plugin new

Starts a plugin: in a checkout of getkalem/plugins its template as `plugins/NAME`, elsewhere a crate of its own in `NAME/`

Usage: kalem plugin new <NAME>

Arguments:
  <NAME>
          Its name: lower-case letters, digits and hyphens

Options:
  -h, --help
          Print help

11.6. kalem plugin build

Builds the plugin in DIR (the current folder by default): Cargo compiles it for wasm32-unknown-unknown, and the module becomes the component `main` names in plugin.json

Usage: kalem plugin build [DIR]

Arguments:
  [DIR]
          The plugin's folder

Options:
  -h, --help
          Print help

11.7. kalem plugin dev

Builds the plugin in DIR (the current folder by default) with its functions' names kept, installs it, and builds and installs it again whenever its sources change, until stopped: a Kalem running opens files with the new build

Usage: kalem plugin dev [DIR]

Arguments:
  [DIR]
          The plugin's folder

Options:
  -h, --help
          Print help

11.8. kalem plugin remove

Removes an installed plugin

Usage: kalem plugin remove <ID>

Arguments:
  <ID>
          Its ID

Options:
  -h, --help
          Print help

11.9. kalem plugin enable

Turns on again a plugin Kalem turned off after it stopped three times (a trap, its time or its memory spent)

Usage: kalem plugin enable <ID>

Arguments:
  <ID>
          Its ID

Options:
  -h, --help
          Print help

12. kalem lsp

Language servers: `kalem lsp status`, `kalem lsp check FILE`, `kalem lsp ask REQUEST FILE [LINE:COLUMN]`

Usage: kalem lsp <COMMAND>

Commands:
  status  The language plugins, and what serves FILE: its language, root and server, or why there is none
  check   The diagnostics of the files' language servers, once they settle; exits 1 when there are errors
  ask     Asks the server about a place: `hover`, `definition`, `references`, `symbols`, `signature`, `completion` (as typing there would), `format` (prints the formatted text), or a request of the server's own by the command that sends it (`code.expandMacro`, `code.openDocs` prints the address, `edit.newline` the text after Enter there)
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

12.1. kalem lsp status

The language plugins, and what serves FILE: its language, root and server, or why there is none

Usage: kalem lsp status [FILE]

Arguments:
  [FILE]
          A code file

Options:
  -h, --help
          Print help

12.2. kalem lsp check

The diagnostics of the files' language servers, once they settle; exits 1 when there are errors

Usage: kalem lsp check [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Code files

Options:
      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

      --wait <WAIT>
          Seconds to wait for the server
          
          [default: 120]

      --log
          Print the server's log (its messages and standard error) to standard error

  -h, --help
          Print help

12.3. kalem lsp ask

Asks the server about a place: `hover`, `definition`, `references`, `symbols`, `signature`, `completion` (as typing there would), `format` (prints the formatted text), or a request of the server's own by the command that sends it (`code.expandMacro`, `code.openDocs` prints the address, `edit.newline` the text after Enter there)

Usage: kalem lsp ask [OPTIONS] <REQUEST> <FILE> [PLACE]

Arguments:
  <REQUEST>
          The request

  <FILE>
          A code file

  [PLACE]
          LINE:COLUMN, from 1
          
          [default: 1:1]

Options:
      --wait <WAIT>
          Seconds to wait for the server
          
          [default: 120]

      --input <NAME=TEXT>
          What the request asks, as NAME=TEXT: `--input 'search=foo($a)' --input 'replace=bar($a)'` for `code.structuralReplace`

  -h, --help
          Print help

13. kalem latex

LaTeX documents: `kalem latex build FILE`

Usage: kalem latex <COMMAND>

Commands:
  build  Build the PDF of a LaTeX document: its project's root document, with `latexmk` or the engine it names, and the problems of the log at their files and lines; exits 1 when LaTeX reports an error
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

13.1. kalem latex build

Build the PDF of a LaTeX document: its project's root document, with `latexmk` or the engine it names, and the problems of the log at their files and lines; exits 1 when LaTeX reports an error

Usage: kalem latex build [OPTIONS] <FILE>

Arguments:
  <FILE>
          A LaTeX file of the project

Options:
      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

      --engine <ENGINE>
          The engine (`pdflatex`, `xelatex`, `lualatex`, `tectonic`), instead of the one the document asks for

      --outdir <OUTDIR>
          Where the output goes, relative to the root document

  -h, --help
          Print help

14. kalem book

The Book: `kalem book build`, `kalem book check`

Usage: kalem book <COMMAND>

Commands:
  build  Build the Book as a static site: every chapter of `index.org` exported to HTML in the theme's page, with a search index
  check  Check the Book: every chapter exports, and every link inside it leads to one of its pages
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

14.1. kalem book build

Build the Book as a static site: every chapter of `index.org` exported to HTML in the theme's page, with a search index

Usage: kalem book build [OPTIONS] [DIR]

Arguments:
  [DIR]
          The Book's folder
          
          [default: book]

Options:
      --out <OUT>
          Where the site goes
          
          [default: target/book]

  -h, --help
          Print help

14.2. kalem book check

Check the Book: every chapter exports, and every link inside it leads to one of its pages

Usage: kalem book check [OPTIONS] [DIR]

Arguments:
  [DIR]
          The Book's folder
          
          [default: book]

Options:
      --changed <BASE>
          Instead: the chapters `book/chapters.toml` maps to code changed since this Git revision, which have to change too

  -h, --help
          Print help

15. kalem table

Table formulas: `kalem table recalc FILE...`

Usage: kalem table <COMMAND>

Commands:
  recalc  Recalculate every table that has a `#+TBLFM` line, as Emacs does with `org-table-recalculate-buffer-tables`, and align it
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

15.1. kalem table recalc

Recalculate every table that has a `#+TBLFM` line, as Emacs does with `org-table-recalculate-buffer-tables`, and align it

Usage: kalem table recalc [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Org files to recalculate in place

Options:
      --iterate
          Recalculate until the tables no longer change (at most ten times), as `C-u C-u C-c *`

      --check
          Change nothing; list the files whose tables would change and fail if there are any (for CI)

  -h, --help
          Print help

16. kalem query

Print the headlines matching an Org match string, such as `kalem query notes.org 'TODO="NEXT"+work'`

Usage: kalem query [OPTIONS] <FILE>... <MATCH>

Arguments:
  <FILE>...
          Org files

  <MATCH>
          The match string, as Emacs's tags and property matches write it

Options:
      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

  -h, --help
          Print help

17. kalem dump

Dump the parse tree in the JSON of `tests/emacs/dump.el` (development)

Usage: kalem dump [OPTIONS] <FILE>

Arguments:
  <FILE>
          The Org file to dump

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - emacs-json: The JSON format of `tests/emacs/dump.el`
          
          [default: emacs-json]

  -h, --help
          Print help (see a summary with '-h')

18. kalem diff-emacs

Compare the parse with Emacs's org-element (development)

Usage: kalem diff-emacs [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          Org files to compare

Options:
      --emacs-dumps <EMACS_DUMPS>
          Directory with precomputed dumps (`FILE.json`), instead of running Emacs

      --dump-el <DUMP_EL>
          Path to `dump.el` (default: search `tests/emacs/dump.el` upwards from the current directory)

      --emacs <EMACS>
          The Emacs executable
          
          [default: emacs]

      --show <SHOW>
          How many differences to print per file
          
          [default: 20]

      --summary
          Only print the summary

      --model
          Compare the document model (tags, properties, TODO sets, matches) through `tests/emacs/model.el` instead of the syntax tree

      --format <FORMAT>
          Output format
          
          [default: text]
          [possible values: text, json]

  -h, --help
          Print help