<commit_before>#+TITLE: EMACS

* HELP

Take time to read the opening screen on Emacs it explains all the help
available to you.

Most of emacs help is accessed using the <C-h> prefix and then a further
command to refine the type of help you need.

In Emacs ~info~ is your frield you can view a list of all the manual avaiable
with ~<C-h i>~

In emacs just pressing ~<C-h>~ and pausing will explain ~?~ gives further
information on help available

** Summary of help commands (also see Emacs opening screen)

- ~<C-h t>~ :: Emacs introductory tutorial
- ~<C-h r>~ :: Emacs manual
- ~<C-h i>~ :: Browse Manuals (the lisp tutorial and reference manual is here)
- ~<C-h ?>~ :: List all available help options

* Universal Arguments / Numeric Arguments
The various ways you can pass numeric arguments to Emacs are:

- C-u - each press represent the the power of 4 you want as your command
  - C-u (4 ** 1) represents 4
  - C-u C-u (4 ** 2) represents 16
  - C-u C-u C-u (4 ** 3) represents 64 and so on
- C--, M--, C-M-- all pass in a negative argument
- C-<Number>, M-<Number>, C-M-<Number> all pass in number arguments
  - this is really useful when trying to work efficiently as you can use
    same key modifiers as the next command. Terminal emacs seems to have
    problems with Ctrl arguments but Ctrl and Meta arguments are accepted
    so you could do this then release the Meta key for a ctrl key argument.

Always think of ways negative arguments can increase your efficiency.
This allows you to delete backwards without using the ~<M- <Backspace>>~ eg.

 ~<M--> <M-d>~
 ~<M--> <M-3> <M-d>~

This also works with zap-to-char (~M-z~) which is a great vi replacement
for the change commands (~ct~). Remember that you can repeat commands with
~C-x z~ if you get the count wrong, but does repeat with the same numberic
argument.

* Point after incremental search

When searching backwards ~C=r~ the point always finished at the start
of the word you are searching for.  When searching forwards ~C-s~ the point
rests after the characters searched for.  In many cases this is part
of the way through a word, and in many cases the desired behaviour
would be to have the point at the start of the word so the word can be
easily edited without first having to move the point.
One solution is to write a custom function to change emacs behaoviour,
see the dicsussion [[https://www.emacswiki.org/emacs/IncrementalSearch][here]].
Alternatively just hitting ~C-r RET~ after your forward search will bring
the point back to the start of the word.
In Vim it is common to search forward ~/~ and change a word ~cw~ then
continue to search forward ~/~ and repeat the last change ~.~. This allows
you to make quick edits interactively.
In Emacs a better approach would be query search and replace ~M-%~.

* Transposing text
Emacs allows text to be transposed with the following commands

| Key Binding | Command                                   |
|-------------+-------------------------------------------|
| C-t         | Transpose characters                      |
| M-t         | Transpose words                           |
| C-M-t       | Transpose s-expressions                   |
| C-x C-t     | Transpose lines                           |
| M-x         | transpose-paragraphs Transpose paragraphs |
| M-x         | transpose-sentences Transpose sentences   |
|-------------+-------------------------------------------|

* Filling text
Emacs will take a long line of text and reformat it to multiples lines
of text not exceeding a certain size. That size is determined by the
~fill width~.

| Key Binding        | Command                           |
|--------------------+-----------------------------------|
| M-q                | Refills the paragraph point is in |
| C-x f              | Sets the fill column width        |
| C-x .              | Sets the fill prefix              |
| M-x auto-fill-mode | Toggles auto-filling              |
|--------------------+-----------------------------------|

* Commenting
Emacs has the following features for easily commenting code

| Key Binding     | Command                                                          |
|-----------------+------------------------------------------------------------------|
| M-;             | Intelligently comment buffer                                     |
| C-x C-;         | toggle line comment                                              |
| M-x comment-box | Comment region in a comment box                                  |
| M-j, C-M-j      | Break line at point and indent, continuing comment if within one |
|-----------------+------------------------------------------------------------------|

* Removing lines
Over and above Emacs' standard process of killing lines, you can
remove or keep all lines in a file based on a pattern

| Command         | Description                                         |
|-----------------+-----------------------------------------------------|
| M-x flush-lines | remove all lines in a region that match the pattern |
| M-x keep-lines  | keep all lines in a regions that match the pattern  |
|-----------------+-----------------------------------------------------|

* Joining and splitting lines
The joining and splitting lines commands are as follows.

| Key Binding | Description                                                                                |
|-------------+--------------------------------------------------------------------------------------------|
| C-o         | Splits the line after point                                                                |
| C-x C-o     | Deletes all blank lines between current line and next line of text                         |
| C-M-o       | Splits the line after point indenting new line to position of point                        |
| M-^         | Join the line point is on with the point above if given an argument joins with line below. |
|-------------+--------------------------------------------------------------------------------------------|

* Capitalisation
Emacs can change the case of words and regions.
Capitalisation of words is fairly common but regions less so.

** Prefixes
Prefixed arguments do what you would expect to the word commands.
Numbered arguments change the number of words affected.
Negative argument affect previous words.

| Key Bindings               | Description                        |
|----------------------------+------------------------------------|
| M-c                        | Capitalise next (previous) word(s) |
| M-u                        | Uppercases next (previous) word(s) |
| M-l                        | Lowercase next (previous) word(s)  |
| M-x upcase-initials-region | Capitalize region                  |
| C-x C-u                    | Uppercase region                   |
| C-x C-l                    | Lowercase region                   |
|----------------------------+------------------------------------|

* Adjusting font size on the fly
Adjusting font size in a buffer is controlled with the function
~text-scale-adjust~, ~text-scale-increase~ and ~text-scale-decrease~

| Key Bindings | Description                |
|--------------+----------------------------|
| C-x +        | Zoom in                    |
| C-x =        | Zoom in                    |
| C-x -        | Zoom Out                   |
| C-x 0        | Restore Original text size |
|--------------+----------------------------|

* Helm
Helm is an incremental and selection narrowing framework for Emacs.
The github repository is [[https://github.com/emacs-helm/helm][here]].
It can be installed from melpa. It seems to freeze on certain versions
of Emacs.

It can be very useful to map some of its functionality to standard keys,
replacing the standard out of the box functionality of emacs.

#+BEGIN_SRC elisp
(require 'helm-config)

(define-key helm-map (kbd "<tab") 'helm-execute-persistent-action)

(global-set-key (kbd "C-x b") 'helm-buffers-list)
(global-set-key (kbd "C-x r b") 'helm-bookmarks)
(global-set-key (kbd "C-x m") 'helm-M-x)
(global-set-key (kbd "M-y") 'helm-show-kill-ring)
(global-set-key (kbd "C-x C-f") 'helm-find-files)
#+END_SRC

* Org mode

Org mode is a very large topic. It has a number of manuals dedicated
to its use so this is just a small summary of its most handy features.

** Formatting text

You can format text by surrounding it with certain characters. These
characters determine the type of formatting.

| Style            | Character |
|------------------+-----------|
| *Bold*           | *         |
| /italic/         | /         |
| _underlined_     | _         |
| =code=           | =         |
| ~verbatim~       | ~         |
| +strike-through+ | +         |
|------------------+-----------|


** Org files for config

Babel in org mode allows emacs_lisp to be sourced from an org file and
loaded. This makes it possible to put most of an emacs configuration
in an org mode file and bootstrap it from a minimal ~init.el~ file.
This gives the advantage of being able to efficiently document the
configuration file so that it is easier to understand and maintain.

*** Useful key bindings

| key binding | description                                |
|-------------+--------------------------------------------|
| <s<TAB>     | create a BEGIN_SRC / END_SRC block         |
| <C-c>'      | move to mode specific buffer to write code |
|-------------+--------------------------------------------|


** Export to pdf

Exporting to pdf requires that you have the necessary latex binaries
installed.

The texlive website has a [[https://www.tug.org/texlive/quickinstall.html][quick install page]] that describes how to get
setup.

** OSX texlive install

The link above recommends installing [[https://www.tug.org/mactex/][MacTEX]] but I installed the
relevant packages using ~ports~

- install [[https://www.macports.org/install.php][macports]]
- sudo port install texlive
- sudo port install texlive-latex-extra

This installed all the packages I needed to export to pdf from org
mode and to export to pdf from Rmarkdown in RStudio.

* Showing line number

Line numbers can be toggled using linum-mode

To toggle line numbering in the current buffer
<commit_msg>Add instruction for installing MikTex on windows.<commit_after>#+TITLE: EMACS

* HELP

Take time to read the opening screen on Emacs it explains all the help
available to you.

Most of emacs help is accessed using the <C-h> prefix and then a further
command to refine the type of help you need.

In Emacs ~info~ is your frield you can view a list of all the manual avaiable
with ~<C-h i>~

In emacs just pressing ~<C-h>~ and pausing will explain ~?~ gives further
information on help available

** Summary of help commands (also see Emacs opening screen)

- ~<C-h t>~ :: Emacs introductory tutorial
- ~<C-h r>~ :: Emacs manual
- ~<C-h i>~ :: Browse Manuals (the lisp tutorial and reference manual is here)
- ~<C-h ?>~ :: List all available help options

* Universal Arguments / Numeric Arguments
The various ways you can pass numeric arguments to Emacs are:

- C-u - each press represent the the power of 4 you want as your command
  - C-u (4 ** 1) represents 4
  - C-u C-u (4 ** 2) represents 16
  - C-u C-u C-u (4 ** 3) represents 64 and so on
- C--, M--, C-M-- all pass in a negative argument
- C-<Number>, M-<Number>, C-M-<Number> all pass in number arguments
  - this is really useful when trying to work efficiently as you can use
    same key modifiers as the next command. Terminal emacs seems to have
    problems with Ctrl arguments but Ctrl and Meta arguments are accepted
    so you could do this then release the Meta key for a ctrl key argument.

Always think of ways negative arguments can increase your efficiency.
This allows you to delete backwards without using the ~<M- <Backspace>>~ eg.

 ~<M--> <M-d>~
 ~<M--> <M-3> <M-d>~

This also works with zap-to-char (~M-z~) which is a great vi replacement
for the change commands (~ct~). Remember that you can repeat commands with
~C-x z~ if you get the count wrong, but does repeat with the same numberic
argument.

* Point after incremental search

When searching backwards ~C=r~ the point always finished at the start
of the word you are searching for.  When searching forwards ~C-s~ the point
rests after the characters searched for.  In many cases this is part
of the way through a word, and in many cases the desired behaviour
would be to have the point at the start of the word so the word can be
easily edited without first having to move the point.
One solution is to write a custom function to change emacs behaoviour,
see the dicsussion [[https://www.emacswiki.org/emacs/IncrementalSearch][here]].
Alternatively just hitting ~C-r RET~ after your forward search will bring
the point back to the start of the word.
In Vim it is common to search forward ~/~ and change a word ~cw~ then
continue to search forward ~/~ and repeat the last change ~.~. This allows
you to make quick edits interactively.
In Emacs a better approach would be query search and replace ~M-%~.

* Transposing text
Emacs allows text to be transposed with the following commands

| Key Binding | Command                                   |
|-------------+-------------------------------------------|
| C-t         | Transpose characters                      |
| M-t         | Transpose words                           |
| C-M-t       | Transpose s-expressions                   |
| C-x C-t     | Transpose lines                           |
| M-x         | transpose-paragraphs Transpose paragraphs |
| M-x         | transpose-sentences Transpose sentences   |
|-------------+-------------------------------------------|

* Filling text
Emacs will take a long line of text and reformat it to multiples lines
of text not exceeding a certain size. That size is determined by the
~fill width~.

| Key Binding        | Command                           |
|--------------------+-----------------------------------|
| M-q                | Refills the paragraph point is in |
| C-x f              | Sets the fill column width        |
| C-x .              | Sets the fill prefix              |
| M-x auto-fill-mode | Toggles auto-filling              |
|--------------------+-----------------------------------|

* Commenting
Emacs has the following features for easily commenting code

| Key Binding     | Command                                                          |
|-----------------+------------------------------------------------------------------|
| M-;             | Intelligently comment buffer                                     |
| C-x C-;         | toggle line comment                                              |
| M-x comment-box | Comment region in a comment box                                  |
| M-j, C-M-j      | Break line at point and indent, continuing comment if within one |
|-----------------+------------------------------------------------------------------|

* Removing lines
Over and above Emacs' standard process of killing lines, you can
remove or keep all lines in a file based on a pattern

| Command         | Description                                         |
|-----------------+-----------------------------------------------------|
| M-x flush-lines | remove all lines in a region that match the pattern |
| M-x keep-lines  | keep all lines in a regions that match the pattern  |
|-----------------+-----------------------------------------------------|

* Joining and splitting lines
The joining and splitting lines commands are as follows.

| Key Binding | Description                                                                                |
|-------------+--------------------------------------------------------------------------------------------|
| C-o         | Splits the line after point                                                                |
| C-x C-o     | Deletes all blank lines between current line and next line of text                         |
| C-M-o       | Splits the line after point indenting new line to position of point                        |
| M-^         | Join the line point is on with the point above if given an argument joins with line below. |
|-------------+--------------------------------------------------------------------------------------------|

* Capitalisation
Emacs can change the case of words and regions.
Capitalisation of words is fairly common but regions less so.

** Prefixes
Prefixed arguments do what you would expect to the word commands.
Numbered arguments change the number of words affected.
Negative argument affect previous words.

| Key Bindings               | Description                        |
|----------------------------+------------------------------------|
| M-c                        | Capitalise next (previous) word(s) |
| M-u                        | Uppercases next (previous) word(s) |
| M-l                        | Lowercase next (previous) word(s)  |
| M-x upcase-initials-region | Capitalize region                  |
| C-x C-u                    | Uppercase region                   |
| C-x C-l                    | Lowercase region                   |
|----------------------------+------------------------------------|

* Adjusting font size on the fly
Adjusting font size in a buffer is controlled with the function
~text-scale-adjust~, ~text-scale-increase~ and ~text-scale-decrease~

| Key Bindings | Description                |
|--------------+----------------------------|
| C-x +        | Zoom in                    |
| C-x =        | Zoom in                    |
| C-x -        | Zoom Out                   |
| C-x 0        | Restore Original text size |
|--------------+----------------------------|

* Helm
Helm is an incremental and selection narrowing framework for Emacs.
The github repository is [[https://github.com/emacs-helm/helm][here]].
It can be installed from melpa. It seems to freeze on certain versions
of Emacs.

It can be very useful to map some of its functionality to standard keys,
replacing the standard out of the box functionality of emacs.

#+BEGIN_SRC elisp
(require 'helm-config)

(define-key helm-map (kbd "<tab") 'helm-execute-persistent-action)

(global-set-key (kbd "C-x b") 'helm-buffers-list)
(global-set-key (kbd "C-x r b") 'helm-bookmarks)
(global-set-key (kbd "C-x m") 'helm-M-x)
(global-set-key (kbd "M-y") 'helm-show-kill-ring)
(global-set-key (kbd "C-x C-f") 'helm-find-files)
#+END_SRC

* Org mode

Org mode is a very large topic. It has a number of manuals dedicated
to its use so this is just a small summary of its most handy features.

** Formatting text

You can format text by surrounding it with certain characters. These
characters determine the type of formatting.

| Style            | Character |
|------------------+-----------|
| *Bold*           | *         |
| /italic/         | /         |
| _underlined_     | _         |
| =code=           | =         |
| ~verbatim~       | ~         |
| +strike-through+ | +         |
|------------------+-----------|


** Org files for config

Babel in org mode allows emacs_lisp to be sourced from an org file and
loaded. This makes it possible to put most of an emacs configuration
in an org mode file and bootstrap it from a minimal ~init.el~ file.
This gives the advantage of being able to efficiently document the
configuration file so that it is easier to understand and maintain.

*** Useful key bindings

| key binding | description                                |
|-------------+--------------------------------------------|
| <s<TAB>     | create a BEGIN_SRC / END_SRC block         |
| <C-c>'      | move to mode specific buffer to write code |
|-------------+--------------------------------------------|


** Export to pdf

Exporting to pdf requires that you have the necessary latex binaries
installed.

The texlive website has a [[https://www.tug.org/texlive/quickinstall.html][quick install page]] that describes how to get
setup.

** Windows texlive install

There is Tex / Latex implementation for windows called
[[http://miktex.org][MikTex]]. There is also a MikTex package on
[[https://chocolatey.org][Chocolatey]] if you want to install it that way.

The MikTex package is special in so far as there is a basic install
but it is able to detect if other packages are needed and can install
them for you on the fly (either automatically or with your permission
depending upon how you set it up). This means if you export to pdf
from org mode, instead of needing a full installation, you can have a
basic install and it will only donwload the extra required packages
needed for the export.

** OSX texlive install

The link above recommends installing [[https://www.tug.org/mactex/][MacTEX]] but I installed the
relevant packages using ~ports~

- install [[https://www.macports.org/install.php][macports]]
- sudo port install texlive
- sudo port install texlive-latex-extra

This installed all the packages I needed to export to pdf from org
mode and to export to pdf from Rmarkdown in RStudio.

* Showing line number

Line numbers can be toggled using linum-mode

To toggle line numbering in the current buffer

{'fraction_non_alphanumeric': 0.17523287153056882, 'fraction_numerical': 0.0013239396661780698, 'mean_word_length': 1.6078914919852034, 'pattern_counts': {'":': 0, '<': 45, '<?xml version=': 0, '>': 41, 'https://': 11, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 26, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1164182', 'n_tokens_mistral': 5328, 'n_tokens_neox': 5095, 'n_words': 2428}