PMIP3 wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Using the emacs text editor ======

<note tip>{{ :other:newppl:real_programmers.png?direct&600 |}} [[https://www.explainxkcd.com/wiki/index.php/378:_Real_Programmers|xkcd & Real Programmers]]</note>

===== TODO =====

FIXME

  * Add a screenshot
  * One process, multiple windows (''File'' => ''New Frame''), multiple buffers
  * Emacs server...
  * Define some concepts:
    * //frame//, //buffer//, //region//
    * 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]]//))
      * Menu bar
      * 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
  * TAB key for auto-completion when opening files...
  * Using menus vs shortcuts
  * Key + Mouse shortcuts (e.g. CTRL+Left Mouse => //Buffer Menu//)
  * runs locally => no need for an X server
  * available on Linux/Win/Mac
  * highly customizable
  * splitting windows
  * WIN: configuring the //Cascadia Code// font
===== Installing emacs =====

==== Linux installation ====

Install the ''emacs'' package, if it is not already available

<code>$ sudo apt install emacs
[sudo] password for your_login:
Reading package lists... Done
Building dependency tree
Reading state information... Done
emacs is already the newest version (1:26.3+1-1ubuntu2).
0 upgraded, 0 newly installed, 0 to remove and 7 not upgraded.</code>


==== Mac installation ====

Install [[https://aquamacs.org/|Aquamacs]]


==== Windows installation ====


=== emacs binaries for Windows ===

<note warning>When installing emacs, you will need an account that can get **//elevated// (i.e. //administrator//) permissions**

\\ 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)
    * [[other:emacs_doc#example_configuration_file|Example configuration file]]

=== 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)
      * **Do not use //space// characters in the predefined PuTTY profile name**!
        * ''mylogin_server'' (e.g. ''me_ssh1'') is OK
        * 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 **exactly the same profile name** as an existing PuTTY profile!
      * More details in FIXME

  * **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]]
      * 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
        * This will install the required binaries and reources in ''C:\Program Files (x86)\GnuWin32\''
      * 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
        * <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**!

=== emacs for Windows technical notes ===

<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>

  * [[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//)

  * [[https://www.gnu.org/software/emacs/manual/html_mono/efaq-w32.html|GNU Emacs FAQ for MS Windows]]

  * 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 =====

==== Linux launch ====

  * ''emacs some_text_file &''
  * or just ''emacs &''
  * FIXME error type if there is no X server, and option for forcing text mode (i.e NO GUI)

==== Windows launch ====

  * ''Start'' => ''E'' => ''Emacs-XX.Y'' => ''Emacs''

==== Mac launch ====

FIXME


===== Using (and learning) emacs =====

<note tip>Use ''C-g'' (''CTRL''+''g'') to abort or interrupt something in emacs

e.g. When you are //searching forward// with ''C-s'', type ''C-g'' to exit the search</note>

All the common functions of emacs are available from the pull-down menus at the top, but the **real power** comes from knowing (a few of) the keyboard shortcuts!

  * **Understanding keyboard shortcuts**:
    * ''C-x C-c'' means ''CTRL-x'' followed by ''CTRL-c'', and will exit emacs
      * Same result as using ''File''=>''Quit'', just faster :-)
    * ''C-s'' means ''CTRL-s'', and will //Search forward//
      * Hint: look for ''Incremental Search'' in the [[https://www.gnu.org/software/emacs/refcards/pdf/refcard.pdf|Reference Card]] for more information on searching!
    * ''C-g'' means ''CTRL-G'' and will **abort** the current emacs command/action (e.g. exit a forward search started with ''C-s'')
    * ''C-z'' will iconify the emacs window!
      * Use ''C-x u'' (''CTRL-x'' followed by ''u'') or ''Edit''=>''Undo'' for **undoing** the previous action!
    * ''M-f'' means ''Alt-f'' (or ''Esc'' followed by ''f'' if the keyboard has no ''Alt'' key), and will //Move forward a word//

  * **Bonus!** Many emacs shortcuts can be used in the shell or in Python, and will also make it possible to use emacs in text mode (if you get lost on a remote server without graphics...)
    * e.g. ''C-A'' and ''C-E'' to go to the beginning and end of a line

  * **Copy-Cut-Paste**
    * With a mouse: the usual Linux copy/paste behavior works:
      * Select and Copy text (at the same time) with the left button
      * Paste text with the middle button
      * Delete/Cut text (requires some practice): left-click at the beginning of the text you want to cut, then double-right-click at the end of the text
    *  [[https://www.emacswiki.org/emacs/CopyAndPaste#h5o-1|Using keyboard shortcuts]]
    * [[https://ftp.gnu.org/old-gnu/Manuals/emacs-20.7/html_node/emacs_167.html|More stuff]]

  * **The official [[https://www.gnu.org/software/emacs/tour/|Guided Tour of Emacs]]** is a nice web page quickly detailing the major concepts (//buffer//, //region//, //mark//, ...) and shortcuts\\ You can read this page, and later find some time for following the builtin tutorial (details below)

  * **Built-in emacs tutorial, highly recommended!** Spend one hour in the tutorial, and save hundreds of hours in the rest of your life!
      * ''Help''=>''Emacs Tutorial''
      * or ''Help''=>''Emacs Tutorial (choose language)...''

  * **[[https://www.gnu.org/software/emacs/refcards/|Reference cards]]**, available in several languages
    * The //Reference Card// and the //Survival Card// mostly have the same content, just formatted a bit differently. **The Reference Card is easier to read**.
    * Emacs 21 Reference Card annotated by JYP (most useful shortcuts for beginners): {{:other:newppl:emacs_jyp.pdf}}

  * **Other reference cards**:
    * [[https://www.emacswiki.org/emacs/Reference_Sheet_by_Aaron_Hawley|EmacsWiki Reference Sheet by Aaron Hawley]] (html)
    * [[http://www.mitchr.me/SS/refc/media/refc_emacs.pdf|emacs reference card by Mitch Richling]] (2 page pdf)

  * **Misc documentation**:
    * Regular expressions: [[https://www.emacswiki.org/emacs/RegularExpression|Regular expressions]], [[https://www.emacswiki.org/emacs/RegularExpressionHelp|Reg exp help]]

===== emacs configuration file =====

  * The **configuration file** is officially known as the //[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Init-File.html|Emacs Initialization File]]//

  * The configuration file (and most of the emacs //Packages//) is written in **//Emacs Lisp//**
    * You can perfectly survive without knowing anything about lisp! Just **don't forget opening and closing parentheses** (''('' and '')'') when copy/pasting settings you find on the web, and remember that comments start with a '';'' character
    * The settings changed with the ''Options'' menu appear at the end of the configuration file

  * The easiest way to take changes into account is to restart emacs
==== Location of the configuration file ====

Configuration file name: ''.emacs''

emacs knows (of course) where its ''.emacs'' configuration file is located! You can open the configuration file just by typing ''C-x C-f ~/.emacs'' and you can then check how your //Home folder// (''~/'') has been expanded

Related emacs (configuration) files and folders (e.g. ''.emacs.d/'' folder) are located in the same place as the main configuration file

  * **Linux**:\\ ''~/.emacs'': i.e. ''.emacs'' (//dot-emacs//) file in the current user's //Home// directory

  * **Windows**:\\ If you want to access the emacs configuration files and folders, you will need to be able to [[other:win10config#displaying_hidden_folders_and_files_and_the_files_extension|see hidden folders and files]]!
    * Windows style path: ''c:\Users\your_login\AppData\Roaming\.emacs''
    * Linux style path: ''c:/Users/your_login/AppData/Roaming/.emacs'' (or just ''~/.emacs'')

  * **Mac**\\ FIXME

==== Example 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’:

File is missing: Opening output file, No such file or directory, c:/Users/your_login/AppData/Roaming/.emacs.d/server/server</code>

  * **Keyboard shortcuts** defined by the example configuration file
    * ''C-x C-g'': go to a specific line
    * ''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
    * ''Shift Up_Arrow'' and ''Shift Down_Arrow'': go to the beginning/end of the buffer
    * //Function// keys
      * ''F1'': Undo (lots of undos!!)
      * ''F2'': Search and Replace
        * 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
        * ...or read [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Query-Replace.html|Query Replace]] page
      * ''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 ====

  * ''M-;'': comment out selected lines\\ This will automatically use the appropriate ''comment character'' for the current buffer mode, e.g. ''#'' for a Python script
===== Working with remote text files =====

==== Prerequisite ====


==== Using the tramp mode ====

  * 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 text file (with ''scp'') to your computer when you open it, so that you can edit the file locally
    * copy the edited text file (with ''scp'') back to its original remote location when you save it (''C-x C-s'')
    * Opening a file on a remote server that you can reach directly:
      * ''/ssh:mylogin@server:/path/file''
        * e.g. ''/ssh:mylogin@ssh1.lsce.ipsl.fr:/home/users/mylogin/my_script.py''
      * 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''
        * e.g. ''/ssh:mylogin@ssh1.lsce.ipsl.fr|ssh:user_B@target_server:/path/file''
      * 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]]

  * Hint: if you use the {{:other:newppl:emacs_linux_22-11-18.tar|recommended configuration file}} or have activated the '' '(recentf-mode t)'' mode, you can easily access recent files in ''File''=>''Open Recent'' without having to type the full access path again!

  * More: [[https://www.emacswiki.org/emacs/TrampMode|tramp mode on EmacsWiki]] and [[https://www.gnu.org/software/tramp/|tramp user manual]]

==== Troubleshooting... ====

The ''tramp'' mode is quite complex and relies on connections to one or more remote computers using external programs and protocols. You may have to experiment a bit till you find the correct syntax and [[https://www.gnu.org/software/tramp/#Inline-methods|inline method]] to work with a particular remote server. Make sure you have read the //prerequisite// section!

''Buffer'' => ''*Messages*''

  * If you get stuck (emacs is not responding), there is pr
    * Try aborting the current emacs command by typing ''C-g''
===== Having fun with emacs =====

  * Use the built-in psychotherapist to solve your scientific problems (with ''M-x doctor''). See also [[https://www.masteringemacs.org/article/fun-games-in-emacs|Fun and Games in Emacs]]\\ <code>I am the psychotherapist.  Please, describe your problems.  Each time
you are finished talking, type RET twice.

My climate model does not work

Why do you say your climate model does not work?

I get wrong results

Is it because of your plans that you say you get wrong results?</code>

===== emacs documentation =====

  * [[https://www.emacswiki.org/emacs/SiteMap|EmacsWiki]]
  * [[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]]

  * [[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 */

\\ \\ \\ 
----
[ [[pmip3:|PMIP3 Wiki Home]] ] -
[ [[pmip3:wiki_help|Help!]] ] -
[ [[wiki:syntax|Wiki syntax]] ]
PMIP3 wiki

User Tools

Site Tools

Page Tools
