other:emacs_doc
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
other:emacs_doc [2023/08/09 15:13] jypeter [TODO] details about the mode line |
other:emacs_doc [2024/02/16 13:23] jypeter [Windows installation] Improved |
||
|---|---|---|---|
| Line 12: | Line 12: | ||
| * Define some concepts: | * Define some concepts: | ||
| * //frame//, //buffer//, //region// | * //frame//, //buffer//, //region// | ||
| - | * Parts of an emacs window (aka //Frame//)) | + | * Parts of an emacs //[[https://www.emacswiki.org/emacs/Frame|Frame]]// (the graphical window or terminal screen occupied by Emacs is called //[[https://www.emacswiki.org/emacs/Frame|Frame]]//)) |
| - | * [[https://www.emacswiki.org/emacs/ModeLine|Mode Line]] = information about the //Buffer// above (e.g. file name, line/column number, editing mode, ... | + | * Menu bar |
| - | * //echo area// = //Interaction field// at the bottom of the window | + | * One or more //windows// displaying a //[[https://www.emacswiki.org/emacs/Buffer|Buffer]]// |
| + | * The last line of a window is the //[[https://www.emacswiki.org/emacs/ModeLine|Mode Line]]// that displays information about the //Buffer// above (e.g. file name, line/column number, editing mode, ... | ||
| + | * //[[https://www.emacswiki.org/emacs/EchoArea|Echo Area]]// or //[[https://www.emacswiki.org/emacs/MiniBuffer/|Mini Buffer]]//, at the very bottom of the frame = //Interaction field// where informative messages are displayed (//echo area//) or where you enter information when Emacs asks for it (//mini buffer//) | ||
| + | * Useful keys: | ||
| + | * C-Z: **iconify** a Frame | ||
| + | * F11: make frame **fullscreen** (toggle) | ||
| * Automatic backup file | * Automatic backup file | ||
| * TAB key for auto-completion when opening files... | * TAB key for auto-completion when opening files... | ||
| Line 46: | Line 51: | ||
| ==== Windows installation ==== | ==== Windows installation ==== | ||
| - | === emacs for Windows === | ||
| - | This is the //light and easy// option! | + | === emacs binaries for Windows === |
| - | * Use [[other:win10apps#installing_applications_with_winget|winget]] to install ''emacs'' for Windows: | + | <note warning>When installing emacs, you will need an account that can get **//elevated// (i.e. //administrator//) permissions** |
| - | * Just type the folllowing, in a windows ''cmd'', ''PowerShell'' or ''Terminal'' **with //elevated// (i.e. //administrator//) permissions**:\\ ''%%winget install --id GNU.Emacs%%'' | + | |
| - | * Note: if the automated installation with ''winget'' does not work, download the Windows installer from the most recent ''windows/gnu-XX'' directory of a [[https://ftpmirror.gnu.org/emacs/|gnu ftp mirror]] | + | \\ On a computer configured at LSCE, use your ''[[https://wiki.lsce.ipsl.fr/pmip3/doku.php/other:win10config#the_available_accounts|.\admin]]'' account</note> |
| + | |||
| + | * Use ''winget'' to install ''emacs'' for Windows (optional [[other:win10apps#installing_applications_with_winget|winget]] details, for people who want to learn more): | ||
| + | * Just type the folllowing, in a windows ''cmd'', ''PowerShell'' or ''Terminal'' | ||
| + | * ''%%winget install --id GNU.Emacs%%'' | ||
| + | * if your Windows terminal does not have //elevated// (i.e. //administrator//) permissions, a pop-up window will open and ask for confirmation | ||
| + | * IF the automated installation with ''winget'' does not work, download the most recent Windows installer from a gnu //ftp// mirror | ||
| + | * Go to a [[https://ftpmirror.gnu.org/emacs/windows/|gnu emacs for windows ftp mirror]] | ||
| + | * Go to the most recent ''emacs-XX/'' folder (e.g. ''emacs-29/'' as of February 2024) | ||
| + | * Download the most recent ''emacs-XX.YY-installer.exe'' file (e.g. ''emacs-29.2_1-installer.exe'' as of February 2024) and execute it | ||
| + | |||
| + | * If everything went well, you should have a new ''Start''=>''Emacs-XX'' menu that you can use to start ''emacs'' | ||
| + | * If the menu shortcuts have **not** been installed: | ||
| + | * Go to the emacs binaries directory: ''C:\\Program Files\\Emacs\\emacs-XX.YY\\bin'' | ||
| + | * Click on the ''addpm.exe'' program to (re-)run the program that will create the shortcuts ([[https://www.gnu.org/software/emacs/manual/html_node/efaq-w32/Installing-binaries.html|official page]]) | ||
| * You can work with the default ''emacs'' settings, but it is highly recommended to start with a nice existing emacs configuration file (if available) | * You can work with the default ''emacs'' settings, but it is highly recommended to start with a nice existing emacs configuration file (if available) | ||
| - | * Example configuration file FIXME | + | * [[other:emacs_doc#example_configuration_file|Example configuration file]] |
| - | * **If** you need to **work with remote files**, ''emacs'' can automatically transfer files from your computer and remote servers, if configured properly\\ <wrap hi>**Extremely** useful</wrap> | + | === Recommended EXTRA binaries for Windows === |
| + | |||
| + | * **If** you need to **work with remote files**, ''emacs'' can automatically transfer files between your local computer and remote servers, if configured properly\\ <wrap hi>**Extremely** useful</wrap> | ||
| * [[https://wiki.lsce.ipsl.fr/pmip3/doku.php/other:putty_conf|Install PuTTY]], and configure a PuTTY //profile// for the desired //host **and** user// combination, so that emacs can use the [[https://the.earth.li/~sgtatham/putty/0.78/htmldoc/Chapter7.html#plink|PuTTY plink]] command to connect to remote servers (and transfer files) | * [[https://wiki.lsce.ipsl.fr/pmip3/doku.php/other:putty_conf|Install PuTTY]], and configure a PuTTY //profile// for the desired //host **and** user// combination, so that emacs can use the [[https://the.earth.li/~sgtatham/putty/0.78/htmldoc/Chapter7.html#plink|PuTTY plink]] command to connect to remote servers (and transfer files) | ||
| - | * Do not use //space// characters in the predefined PuTTY profile name! | + | * **Do not use //space// characters in the predefined PuTTY profile name**! |
| - | * ''mylogin_server'' (e.g. ''jyp_ssh1'') is OK | + | * ''mylogin_server'' (e.g. ''me_ssh1'') is OK |
| * but ''mylogin server'' will **not** work | * but ''mylogin server'' will **not** work | ||
| * Use the [[https://www.gnu.org/software/tramp/#Inline-methods|plinkx]] //method// when opening a remote file with emacs: ''/plinkx:mylogin_server:/path/to/file'' | * Use the [[https://www.gnu.org/software/tramp/#Inline-methods|plinkx]] //method// when opening a remote file with emacs: ''/plinkx:mylogin_server:/path/to/file'' | ||
| - | * Use **exactly** the same profile name as an existing PuTTY profile! | + | * Use **exactly the same profile name** as an existing PuTTY profile! |
| * More details in FIXME | * More details in FIXME | ||
| * **If** you need to use the **emacs //ediff// mode to compare text files**\\ <wrap hi>Very useful</wrap> | * **If** you need to use the **emacs //ediff// mode to compare text files**\\ <wrap hi>Very useful</wrap> | ||
| * Install the Windows version of [[https://www.gnu.org/software/diffutils/diffutils.html|Gnu diffutils]] | * Install the Windows version of [[https://www.gnu.org/software/diffutils/diffutils.html|Gnu diffutils]] | ||
| - | * Download and execute the //Complete package, except sources installer// (''diffutils-2.8.7-1.exe'' as of July 2023) from [[https://gnuwin32.sourceforge.net/packages/diffutils.htm|]] | + | * Download the //Complete package, except sources installer// (''diffutils-2.8.7-1.exe'' as of February 2024) from [[https://gnuwin32.sourceforge.net/packages/diffutils.htm|]] and execute the installer |
| - | * Be sure to uncomment the following line in your ''.emacs'' configuration file (and restart emacs). Otherwise emacs will not be able to find the ''diffutils'' binaries it needs for comparing text files | + | * This will install the required binaries and reources in ''C:\Program Files (x86)\GnuWin32\'' |
| - | * ''(setq exec-path (append exec-path '("C:\\Program Files (x86)\\GnuWin32\\bin")))'' | + | * If you use the recommended ''.emacs'' configuration file, it should already have a section telling emacs where to find the ''diffutils'' binaries it needs for comparing text files |
| - | * FIXME Find a more recent versions of ''diffutils'': dated //May 2004//, as of July 2023..., but it works fine! | + | * <code>(when (eq window-system 'w32) |
| + | (setq exec-path (append exec-path '("C:\\Program Files (x86)\\GnuWin32\\bin"))) | ||
| + | )</code> | ||
| + | * FIXME Check if there is a recent //compiled for Windows// version of ''diffutils''\\ As of February 2024... | ||
| + | * [[https://savannah.gnu.org/news/?id=10368|diffutils-3.10]] is available (released in May 2023) | ||
| + | * The ''2.8.7-1'' Win32 binaries are dated //May 2004//, but **work perfectly fine**! | ||
| - | * Extra Windows specific information (optional, read only if you need it): [[https://www.gnu.org/software/emacs/manual/html_mono/efaq-w32.html|GNU Emacs FAQ for MS Windows]] | + | === emacs for Windows technical notes === |
| - | === emacs for Linux, inside WSL === | + | <note tip>These notes are only here for finding them easily, but **you probably don't need them**.\\ Just follow exactly the windows related instructions on this page!</note> |
| - | This is the //overkill// option... Useful only if you really need WSL! But you should also install the [[#emacs_for_windows|emacs Windows version]]! | + | * [[https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Microsoft-Windows|Emacs and Microsoft Windows/MS-DOS]] (//Appendix H// of the //The Emacs Editor manual//) |
| - | * Install [[other:win10wsl|Windows Subsystem for Linux]] | + | * [[https://www.gnu.org/software/emacs/manual/html_mono/efaq-w32.html|GNU Emacs FAQ for MS Windows]] |
| - | * Install emacs for Linux (check [[#linux_installation|Linux installation]] above) | + | |
| + | * Extra Windows specific information (optional, read only if you need it): [[https://www.gnu.org/software/emacs/manual/html_mono/efaq-w32.html|GNU Emacs FAQ for MS Windows]] | ||
| ===== Launching emacs ===== | ===== Launching emacs ===== | ||
| Line 92: | Line 118: | ||
| ==== Windows launch ==== | ==== Windows launch ==== | ||
| - | * ''Start'' => ''E'' => ''Emacs'' | + | * ''Start'' => ''E'' => ''Emacs-XX.Y'' => ''Emacs'' |
| ==== Mac launch ==== | ==== Mac launch ==== | ||
| Line 172: | Line 198: | ||
| ==== Example configuration file ==== | ==== Example configuration file ==== | ||
| - | * Recommended {{:other:newppl:emacs_linux_22-11-18.tar|.emacs configuration file}} | + | * Recommended {{ :other:emacs_jyp_2023-09-12.txt |emacs configuration file}} |
| + | * Download this ''emacs_jyp_yyyy-mm-dd.txt'' file to the [[other:emacs_doc#location_of_the_configuration_file|appropriate configuration directory (for your system)]] | ||
| + | * Rename the file to ''.emacs'' | ||
| + | * Edit the file (with ''emacs'' or another editor) and search //Microsoft// to (un)comment MS Windows specific sections of the configuration file | ||
| + | * (re)start ''emacs'' to take this configuration file into account | ||
| + | * If ''emacs'' displays the following error message, just create the ''server'' directory (''c:/Users/your_login/AppData/Roaming/.emacs.d/server'') by hand and restart ''emacs''\\ <code>Warning (initialization): An error occurred while loading ‘c:/Users/your_login/AppData/Roaming/.emacs’: | ||
| - | Keyboard shortcuts defined by the example configuration file | + | File is missing: Opening output file, No such file or directory, c:/Users/your_login/AppData/Roaming/.emacs.d/server/server</code> |
| - | * ''C-x C-g'': goto line | + | * **Keyboard shortcuts** defined by the example configuration file |
| - | * ''Shift Left_Arrow'' and ''Shift Right_Arrow'': go to the beginning/end of a line\\ Same behavior as ''C-a'' and ''C-e'', and the ''Home'' and ''End'' keyboard keys | + | * ''C-x C-g'': go to a specific line |
| - | * ''Shift Up_Arrow'' and ''Shift Down_Arrow'': go to the beginning/end of the buffer | + | * ''Shift Left_Arrow'' and ''Shift Right_Arrow'': go to the beginning/end of a line\\ Same behavior as ''C-a'' and ''C-e'', and the ''Home'' and ''End'' keyboard keys |
| - | * //Function// keys | + | * ''Shift Up_Arrow'' and ''Shift Down_Arrow'': go to the beginning/end of the buffer |
| - | * ''F1'': Undo (lots of undos!!) | + | * //Function// keys |
| - | * ''F2'': Search and Replace | + | * ''F1'': Undo (lots of undos!!) |
| - | * Look for ''Query Replace'' in the [[https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf|Reference Card]] to determine what you can do when a match is found | + | * ''F2'': Search and Replace |
| - | * ...or read [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Query-Replace.html|Query Replace]] page | + | * Look for ''Query Replace'' in the [[https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf|Reference Card]] to determine what you can do when a match is found |
| - | * ''F3'': fill-paragraph (i.e. automatically re-indent text or comments) | + | * ...or read [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Query-Replace.html|Query Replace]] page |
| - | * ''F12'': Repeat complex command (e.g. restart a previous query-replace operation) | + | * ''F3'': fill-paragraph (i.e. automatically re-indent text or comments) |
| + | * ''F4'': indent the selected region (if indenting makes sense for the current buffer mode) | ||
| + | * ''F5'': comment out the selected region (comment style depends on the current buffer mode) | ||
| + | * ''M-;'' can be used for commenting **and un-commenting** | ||
| + | * ''F12'': Repeat complex command (e.g. restart a previous query-replace operation) | ||
| - | Useful shortcuts | + | |
| + | ==== Useful shortcuts ==== | ||
| * ''M-;'': comment out selected lines\\ This will automatically use the appropriate ''comment character'' for the current buffer mode, e.g. ''#'' for a Python script | * ''M-;'': comment out selected lines\\ This will automatically use the appropriate ''comment character'' for the current buffer mode, e.g. ''#'' for a Python script | ||
| Line 198: | Line 234: | ||
| * If you use the syntax below when opening a file (''C-x C-f''), emacs will automatically use the ''tramp'' mode to: | * If you use the syntax below when opening a file (''C-x C-f''), emacs will automatically use the ''tramp'' mode to: | ||
| - | * copy the remote file (with ''scp'') to your computer when you open it, so that you can edit the file locally | + | * copy the remote text file (with ''scp'') to your computer when you open it, so that you can edit the file locally |
| - | * copy the edited text (with ''scp'') file back to its original remote location when you save it (''C-x C-s'') | + | * copy the edited text file (with ''scp'') back to its original remote location when you save it (''C-x C-s'') |
| - | * Remote file on a server that you can reach directly: | + | * Opening a file on a remote server that you can reach directly: |
| - | * ''/ssh:user@server:/path/file''\\ or ''/plinkx:jdoe_server:/path/file'' on Windows with an existing ''jdoe_server'' session defined in ''PuTTY'' | + | * ''/ssh:mylogin@server:/path/file'' |
| - | * e.g. ''/ssh:your_login@ssh1.lsce.ipsl.fr:/home/users/your_login/my_script.py'' | + | * e.g. ''/ssh:mylogin@ssh1.lsce.ipsl.fr:/home/users/mylogin/my_script.py'' |
| - | * Remote file on a server than you can only access through a gateway (e.g. file in a supercomputing center): | + | * Or ''/plinkx:mylogin_server:/path/file'' on **MS Windows**, with an existing ''mylogin_server'' session defined in ''PuTTY'' |
| + | * Opening a file on a remote server than you can only access through a gateway (e.g. file in a supercomputing center): | ||
| * ''/ssh:user_A@gateway|ssh:user_B@target_server:/path/file'' | * ''/ssh:user_A@gateway|ssh:user_B@target_server:/path/file'' | ||
| - | * e.g. ''/ssh:your_login@ssh1.lsce.ipsl.fr|ssh:user_B@target_server:/path/file'' | + | * e.g. ''/ssh:mylogin@ssh1.lsce.ipsl.fr|ssh:user_B@target_server:/path/file'' |
| - | * More details: | + | * Or ''/plinkx:mylogin_server|ssh:user_B@target_server:/path/file'' on **MS Windows**, with an existing ''mylogin_server'' session defined in ''PuTTY'' |
| + | * More details: | ||
| * [[https://www.emacswiki.org/emacs/TrampMode#h5o-16|The NEW (Emacs 24.3+) ad-hoc multi-hop syntax]] | * [[https://www.emacswiki.org/emacs/TrampMode#h5o-16|The NEW (Emacs 24.3+) ad-hoc multi-hop syntax]] | ||
| Line 239: | Line 277: | ||
| * [[https://www.gnu.org/software/emacs/manual/html_node/emacs/|The Emacs Editor]] (the official manual) | * [[https://www.gnu.org/software/emacs/manual/html_node/emacs/|The Emacs Editor]] (the official manual) | ||
| * Other official related [[https://www.gnu.org/software/emacs/manual/|GNU Emacs Manuals]] | * Other official related [[https://www.gnu.org/software/emacs/manual/|GNU Emacs Manuals]] | ||
| + | |||
| + | * [[https://github.com/rougier#emacs-hacking|Emacs hacking]] by Nicolas Rougier | ||
| + | |||
| + | ===== Updating emacs ===== | ||
| + | |||
| + | ==== Linux ==== | ||
| + | |||
| + | |||
| + | ==== Mac ==== | ||
| + | |||
| + | |||
| + | ==== Windows ==== | ||
| + | |||
| + | Using ''winget upgrade'' for updating emacs on Windows unfortunately [[https://github.com/microsoft/winget-pkgs/issues/88443#issuecomment-1688257680|does not work yet (August 2023)]]. The easiest way to update Emacs is: | ||
| + | |||
| + | * Check the version of the installed Emacs | ||
| + | * In the ''Start'' menu: ''Start'' => ''E'' => ''Emacs-**version**'' (e.g. ''Emacs 28.2'') | ||
| + | * In a running Emacs: ''Help'' menu => ''About Emacs'' | ||
| + | * Use ''winget show'' in a PowerShell to determine (all) the available versions | ||
| + | * <code>PS C:> winget show --id GNU.Emacs --versions | ||
| + | Found GNU Emacs [GNU.Emacs] | ||
| + | Version | ||
| + | ------- | ||
| + | 29.1 | ||
| + | 28.2 | ||
| + | [...]</code> | ||
| + | * If you want/need to update Emacs (after making sure it is not running) | ||
| + | * Uninstall it with: ''Start'' => ''E'' => ''Emacs-**version**'' => ''Uninstall''\\ Your emacs configuration file and other files you have installed will **not** be removed! | ||
| + | * Perform a new [[other:emacs_doc#windows_installation|Emacs for Windows installation]] | ||
| /* standard page footer */ | /* standard page footer */ | ||
other/emacs_doc.txt · Last modified: 2024/05/08 10:10 by jypeter
