Skip to content

Latest commit

 

History

History
89 lines (68 loc) · 3.04 KB

CONTRIBUTING.org

File metadata and controls

89 lines (68 loc) · 3.04 KB
Raw

Contributing documentation

The documentation provided here is written in Org mode files. The primary file is the crafted-emacs.org file. Each module has it’s own Org file as well, but each is included in the primary file.

The crafted-docs.el file contains useful tools for working with the docs. To ensure the export is reproducible and independent from your Emacs configuration, there are two ways of exporting a clean info file.

Note that it is discouraged to run M-x org-texinfo-export-to-info RET or using org-export-dispatch directly. This is because it can introduce unnecessary diffs depending on certain Emacs configuration settings.

Interactively from Emacs

Requirements:

  • emacs in your $PATH

Evaluating this block will load the crafted-docs.el file into your Emacs:

(load (expand-file-name "crafted-docs.el"))

Afterwards, the info file can be exported by running M-x crafted-docs-export RET.

If you’re using Crafted Emacs and develop inside the repository you cloned, you can set crafted-docs-export-use-crafted-emacs-home to t to utilize the crafted-emacs-home path to auto-find the documentation when running M-x crafted-docs-export RET.

Using make

Requirements:

  • emacs in your $PATH
  • make in your $PATH

If you’re familiar with make and already have a workflow using for example the compile command in Emacs, you can use it in the docs/ directory:

make docs

Running make docs will automatically build the crafted-emacs.info file unless the info file is already up-to-date.

Documenting a Crafted Emacs module

Add an Org file named for the module. Once you are ready to include it in the crafted-emacs.org file, add it to the modules section following the pattern provided there, here is an example:

#+include: crafted-defaults.org

Once you have added the module documentation, export the info file and submit a PR for inclusion.

Guidelines

  • Provide examples.
  • Make sure your grammar is correct.
  • Spellcheck your work.
  • Use consistent formatting in the org docs:
    use === for
    • file paths, e.g. init.el
    • buffer names, e.g. *Messages*
    • values (except numbers, which stay plain), e.g. nil
    • keystrokes or keybindings, e.g. C-n
    • text (to be) entered into the minibuffer (unless it is a complete command name), e.g. buf
    • info nodes, e.g. (emacs)Just Spaces
    use ~ for
    • module names, e.g. crafted-defaults-config
    • variable names, incl. external ones, e.g. load-prefer-newer, $PATH
    • function names, e.g. car
    • command names, incl. external ones, e.g. find-file, make
    • package names, incl. ones that are shaped like a file name, e.g. denote, package.el
  • Preview the info document in Emacs to make sure the formatting works.
  • Use @@texinfo:@code{}@@ or @@texinfo:@samp{}@@ tags in places where org formatting does not directly translate correctly.