bug#29952: 25.2; It would be nice if Emacs had a built in graphical tuto

To: bug-gnu-emacs@gnu.org

Subject: 25.2; It would be nice if Emacs had a built in graphical tutorial.

Date: Tue, 02 Jan 2018 10:53:31 -0600

Message-ID: <p7w9k1x0p5h0.fsf@WUSC006459.i-did-not-set--mail-host-address--so-tickle-me>

--text follows this line--

I apologize, this is not being a bug exactly, but a suggestion. I work in SQL,

and will be out of this position soon. I use Emacs on a day to day basis

(unfortunately in Windows) and I am writing a tutorial on how to use

Emacs specifically for this position for my successor. The built in

tutorial says that if I found the tutorial to be inadequate, to

complain.

The built in tutorial is great for showing the keybindings of

Emacs, but it doesn't do a lot to show how to use Emacs

graphically. What I mean by this is that most users (especially

in Windows) are coming to Emacs from graphical only software.

To cater to these users and get them to recognize the power of GNU, it would be nice to have a graphical only tutorial.

I am including in this bug report, the section of my tutorial that I wrote

for the graphical section of Emacs. Please only consider this to

be a starting block. This is only written specifically for one

particular person and not for everyone in general. I am only including it so that you can see what I mean. You can also tell from my "Tutorial" even I need some help in knowing what all of the menu items do.

/* 2. Graphical Emacs.

One of the most powerful things about Emacs is that once you get the keybindings down, you can accomplish most of your work without your hands ever leaving the keyboard. Emacs isn't the only text editor with this in mind, there are others such as JOE, VI, and NANO. Even though Emacs can be used solely from the keyboard, there are still plenty of graphical point and click style controls that you can use. You can have both keyboard based controls and point and click style controls in the same editor, this makes Emacs a little more beginner friendly than most. Assuming that you are reading this in Emacs, you can see at the top that there are normal window menu functions such as "File", "Edit", "Options", etc. I encourage you to click on all of these menu functions and browse their contents. What menus appear at the top can change based on which mode Emacs is in. Because this is a ".txt" file, you should be in text mode. I will talk more about modes in a later section.

The File Menu:

Assuming that you browsed the sections I am going to just talk about the aspects of these menu sections that you may be unfamiliar with. First of all, in the "File" menu you will notice that it refers to buffers, windows, and frames. This is the first, and it won't be the last lesson in Emacs terminology. Emacs predates windows based graphical systems. It actually predates "Windows" itself. What you would normally refer to as a "Window" , Emacs refers to as a "Frame." When Emacs says "Window" it is referring to subdivisions of a frame. When Emacs refers to a "Buffer" it is referring to the file (or the text) itself that is within a "Window."

Now you can do some experiments here. Should you make a mistake, you can always click "Edit -> Undo."

First, click "File -> New Window Below" and then "File -> New Window on Right."

Emacs should now be split into three "Windows" that each contain the same "Buffer" which is this tutorial. When you click your mouse on one of the other windows, you will activate them. In fact, you can scroll each window to a different area after you click on it. This way, you can edit three different areas of the same file if you wanted. You can also click the borders of each window to resize them. You will notice that each buffer has its own cursor, and the one that is the active buffer has a solid cursor. Now, activate one of the windows by clicking in it and click "File -> Visit New File." A graphical window will appear to allow you to select a new file. The new file just needs to be some sort of plain text file. You can open any other type of file as well, but you will most likely just be viewing the binaries of the file. If you do not have a plain text file available, you can create one here. Just type the name of the file into the file name area and press enter. For example, you can type in "text.txt" into the file name area and press enter. Emacs will create a new buffer called "test.txt." This new buffer will not be an actual new file in the system until you save it in Emacs.

Just to experiment, you can activate the window that contains the file that you just opened. You can see that typing in this window will not affect at all any of the other windows that contain this tutorial buffer.

Just like any other text editor that you are used to, you can click "File->Save" or "File-> Save As" to save your new file if you would like.

At the bottom of each window, you will notice a line that includes the name of the file in that window. For example, the line for this tutorial should read something like "-\--- emacsTutorial.txt a percentage, a line number and then "(Text)." If you hover your mouse over individual areas of this line, Emacs will pop up a dialogue to let you know what they are. The first dash is the text encoding, which you are given an option to change if you would like. The backslash is the end of line mode, which you could also change if you like. Changing either of those options shouldn't change anything that you see in Emacs, but if you were looking to encode a file for another program for specific use, you could. The next dash shows whether or not the buffer is writeable. You can toggle this by clicking on that dash. It might be a good idea, it will keep this tutorial from being changed. The next dash shows that the buffer has been unmodified. In your "test.txt" buffer this will already be an "*" or you can make it turn into "*" by typing in the "test.txt" buffer. The last dash shows if the current buffer is local. That will not matter to you until we get to the next section of the tutorial. Next, you have the name of the file that the buffer represents. The percentage indicates how far you are scrolled down the page. If you are at the top it will display "Top" or "Bot" if you are at the bottom. Next should be a line number such as "L25." Emacs will consider an entire paragraph a "Line." So "L25" in this format basically means the 25th paragraph. Finally the last portion that says "(Text)" displays information about the mode that you are in.

Now, to make things simpler, you can get rid of the three windows that you created earlier. Click in the tutorial buffer to activate that window and then click "File -> Remove Other Windows", and all windows except the one that is currently active will dissappear. These windows/buffers are not gone, they have just been removed from sight. I will show you how to get back to them later.

Now, you can experiment a little with frames. Click "File -> New Frame" and a new frame will appear with this tutorial in its buffer. Just like opening the file in a new window, you will see that you can scroll to different parts of the file independently. If you were to type in the file, you would see both frames add text at the same time (assuming that you were scrolled to that area in both frames.). Each frame can be separated into different windows with different buffers. Opening a new frame this way allows the frames to interact with each other and they are considered to be in the same session. When I get to switching buffers later, all of the buffers that you opened in the first frame will be available in the new frame that you opened. If instead of clicking "File -> New Frame", you just simply clicked "runemacs.exe" again, that would open an entirely new session of Emacs that will not interact at all with your other session. This can be a useful course of action depending on what you are trying to do. Realize that if you start a new Emacs session, they can "compete" with each other. Meaning that if you have the same file open in both sessions, the last one that is saved will be the final version of that file. For example, if I opened the same text file in two different Emacs sessions and then completely erased all contents of the file in one session, the other session would still be open with the text still in tact with it's buffer. If I then saved the file in the Emacs session where the file is blank, I would be saving a completely blank file. However, if I then saved the file in the Emacs session where the file is still unmodified, I would then restore it again. This kind of behavior might end up being useful or it might be detrimental depending on the situation. Either way, you need to be aware of it.

The new Emacs frame can now be closed with "File -> Delete Frame."

The other options in the "File" menu should be self explanatory.

The Edit Menu:

Now, in the "Edit" menu you might notice a few odd things. You have the usual "Cut", "Copy", "Paste" and "Undo" commands. I am not to the key commands section yet, but realize that the standard Windows Ctl-x,c,v,z keyboard commands do not work for these in Emacs. There is also an odd command that says "Paste From Kill Menu." Emacs keeps a running log of things that you have copied with it and saves them here for use later. In fact, cutting in Emacs is technically called "Killing" and copying in Emacs is technically called "copy region as kill." You can experiment a little by highlighting portions of the text with the click and drag method and clicking "Edit -> Copy" a few times. You can then go back to this "Paste From Kill Menu" area to see that it saved all of your copies there. When you simply click paste (which in Emacs is technically called "Yank"), it will always paste the last thing that you "killed."

Select all comes next. It is self explanatory, but Emacs may ask you if you want to enable it before you use it.

The search section is next. Searches can be done with regular expressions or by string. Regular expressions are powerful tools that do not just exist in Emacs, but unfortunately very few Windows tools use them. Searching "String Forward" and "String Backward" should be simple to understand. When you click these, you can enter your string in the minibuffer at the bottom. If need be, you can highlight and copy text and then click in the minibuffer to paste in there. Unfortunately, Emacs will only search to the next instance of your match, if you would like to search again, you need to click "Edit -> Search -> String Forward" again. You can use the up and down arrows to browse your previous searches and then press enter again. It is actually much easier to do this in with keystrokes, but I will show you how to do that in the next section. If these searches fail to find any matching string, you have the option to continue the searches from the beginning or end. By default these are case insensitive unless you include capital letters. Regular _expression_ searches have these same rules about stopping when the searches fail and then optionally starting again at the end or beginning. Regular expressions are also case insensitive unless you include capital letters.

I am going to give you some web resources for learning regular expressions, but just as a quick overview, regular expressions are used for matching patterns. Not all, but a lot of regular expressions are something like this (without the quotation marks) "[0-9].*". This regular _expression_ would match anything that starts with any number followed by zero or more characters of any kind up to and NOT including a new line character (the end of line.) You can read these resources on regular expressions, and I recommend bookmarking the entire web sites to learn more about Emacs. After learning some regular expressions, you can experiment with some regular _expression_ searches. Here are the regular _expression_ resources. The last one takes you to a page in the GNU Emacs Manual. The entire GNU Emacs manual is available under the help menu. I will get to that when I cover the help menu section. Emacs is "Self-documenting" which means that a lot of the documentation that you need is included with Emacs. Note: It is easy to highlight these lines to copy them, just triple click on the lines.

http://ergoemacs.org/emacs/emacs_regex.html

https://www.emacswiki.org/emacs/RegularExpression

https://www.gnu.org/software/emacs/manual/html_node/emacs/Regexps.html

The "repeat-forward" and "repeat-backward" commands repeat your last search without having to re-enter it.

I have never used "tags." I am sure that it is a helpful feature of Emacs, but it just is not something that I have experimented with. Basically Emacs allows you to tag files and you can edit them all at once with certain commands.

The "Incremental Search" calls the commands that we will be calling later in the keyboard commands section.

Next, in the edit menu, we are to the "Replace" section. This is similar to the "Search" section, except that Emacs will search for your match and then replace it with what you enter. When it comes to regular expressions, you can replace a regular _expression_ with some of the matching regular _expression_ itself. For example, if I had a bunch of lines that started with different numbers and I wanted to add a period and a space after a number, Emacs will allow me to match the regular _expression_ of any number at the beginning of a line and replace it with the current number, a period, and then a space. The page from the Emacs manual that explains this is here.

https://www.gnu.org/software/emacs/manual/html_node/emacs/Regexp-Replace.html#Regexp-Replace

The "Go To" section is mostly self explanatory. I have never used the definitions here, but this is the area where you set file tags. If you wish to do this, I recommend looking it up in the GNU Emacs manual.

I have not used the "Bookmarks" either, but again, I am sure that it is a powerful feature of Emacs that is worth the time to learn.

The "Text Properties Section" is interesting. The "Face" section does not affect the file, but only affects how it appears to you now. For example, if you highlight a section of this tutorial and make it "Bold." It will not change anything in the file, it will just make it appear bold to you now. The "Foreground" and "Background" colors can be experimented with. Again, these do not change the file itself, just how it appears at this time. "Justification" and "Indentation" is different compared to other programs. Emacs is a text editor, not a word processor. If you "Justify" or "Indent" text it does it with a combination of spaces and tab characters. If you are editing text that you plan on copying in to a word processor later (something that I do often), I suggest taking care of the "Justify" at least within the word processor. "Describe Properties" describes the encoding of your text. Display faces and colors allows you to view the different text faces and background colors available. to you. Again, these don't change the file, just how things look now (or optionally, how things look to you every time you load the file.)

"Regular _expression_ Highlighting" is an excellent feature of Emacs. This helped me out quite a bit when I had to search long text to categorize functional locations. You can highlight phrases, lines, buffers, and patterns. This helped me search the long text of many equipment numbers to find out how to categorize the functional locations that they were in.

The Options Menu:

The options menu contains many personal preferences and mostly writes directly to your ".emacs" file. Now is going to be a good time to copy the ".emacs" file that is included in this tutorial directory in to the proper place for Emacs to load it automatically. The place to save this in Windows is C:\Users\yourUserName\AppData\Roaming\.emacs. Copy the file and replace the existing file if there is one, which there may not be. If you copy the ".emacs" file to this location, and then close out Emacs and start a new session, the theme of Emacs should change to the one that I have selected in this ".emacs" file and the font should change as well. Also, you have just loaded my special Elisp functions into Emacs. I will discuss Elisp later.

The first section of the options menu is "Highlight Active Region" and "Highlight Matching Parentheses." If you have both of these checked, Emacs will highlight the active Window that you are using, and matching parentheses will be highlighted. For example, if it is checked (and you place the cursor right next to the end of this scentence, Emacs should highlight the matching parenthesis at the other end.) This is mainly useful when coding in languages such as "C++", but I also find it useful in regular writing.

Now, you are going to make this tutorial a little more

readable. "Line Wrapping in This Buffer" gives three

options. "Wrap at Window Edge" is the default and is perfect for

writing code. "Truncate Long Lines" cuts the lines off at the

end and you have to navigate over to the rest of the line to

view it. "Word Wrap (Visual Line Mode)" is more like what you

are used to in word processors. Unfortunately there is no way to

save this until we get to later sections of the tutorial, and you have to change it each time you load the buffer.

"Default Search Options" you will not have to change this. You normally do not want to match case, but if you did, this is where you would change it. You can also match whole words and whole symbols. For example, if you want to only match the word "thank" you might want to click on "Whole Words." That way instances of "thanks" will not appear.

Now, you might like the next option that says "Use CUA Keys." This allows you to use the standard Windows C tl-x,c,v,z keys for kill, copy region as kill, yank, and undo. When I get to the key bindings section of this tutorial, I will use the standard Emacs keybindings. You can choose to use this option just fine for now, but realize that this option needs to be disabled to accomplish some of the keybindings that are done later. When you learn the standard Emacs keybindings for these actions, you may want to keep it off.

"Use Directory Names In Buffer Names" means that if you happen to have two buffers open where their corresponding files have the same name, but they are in a different directory, the buffer name for the window will display the directory (file folder) that the file is in. This is a good option. I believe that it is enabled by default.

"Save Place in Files Between Sessions" will save the cursor position when the file is closed out and reloaded. I don't think this works well in Windows. Works perfectly on GNU/Linux.

"Blink Cursor" is enabled by default and is a good option to have enabled.

The "Enter Debugger" options have to do with compiling code. We may go back to this when I get to the Elisp section of this tutorial. The "Multi-Lingual Environment" lets you change the language and/or the encoding of the text. I do not recommend mess with this too much.

The "Show/Hide" section allows you to customize what shows up in Emacs. You can experiment with this. If you accidentally hide the menu bar, you can get it back by pressing "F10" and using the case sensitive keyboard keys "oSm" to instruct Emacs to put it back. Or, alternatively, you can just exit Emacs and re-enter it. The thing that I like to customize here is the column number, this make the column number appear next to the line number.

"Set Default Font" again only changes how the text appears to you for personal preferences. Keep in mind that there are a few different modes, such as SES mode that will not look right if you change the text to be too big.

"Save Options" obviously allows you to save the options that you have changed so far. This directly writes to the ".emacs" file that you loaded earlier.

"Manage Emacs Packages" allows you to load custom packages that have been created on-line. I honestly don't deal with this at all in Windows, but if you are interested, here is a list of packages from GNU.

https://elpa.gnu.org/packages/

The only thing that I mess with in the "Customize Emacs" section is the theming.

The Buffers Menu:

This is an easy menu item that lets you switch between buffers (open files) that are loaded into Emacs.

The Tools Menu:

Unfortunately, because you are using Emacs within Windows, some of these toolswill not work here. "Grep" is a Unix command that will not work in the Windows shell, so the first menu item here does nothing.

"Compile", will compile with native Unix commands such as Make and gcc/g++. You will not need to use this at all.

"Shell Command" allows you to run a single shell command. It will run the native Windows command line.

The "Debugger", "Project Support", and "Source Card Parsers" options have to do with using Emacs as a development environment.

Unfortunately I have not gotten "Spell Checking" to work in Windows.

The "Compare (Ediff)" option allows you to compare more than one file or buffer to see where there are differences.

"Merge" allows you to merge files, buffers, or directories.

"Apply Patch" allows you to patch source code files.

"Version Control" allows you create tags and control what version your file is.

"Read Net News", "Read Mail", "Compose Mail", and "Browse the Web" do not seem to work in Windows at all unfortunately.

"Directory Search" allows you to search for directories.

"Calendar" brings up a text based calendar.

"Programmable Calculator" and "Calculator" allows you to run a calculator within Emacs.

I doubt that "Encryption/Decryption" would work outside of Linux, but I could be wrong.

Finally, there are "Games" this includes Tetris. My favorite is the multiplication puzzle. Great to pass the time on lunch breaks.

The Text Menu:

The text menu might change depending on what major mode you are in. For example, if you are in C++ mode, there will be a "C++" menu. In "SES" mode, there will be a "SES" menu. This menu gives you a few "Text" specific options. Such as indentations. Keep in mind that indentation in Emacs is done with a combination of tabs and spaces. If you are going to copy your text to a word processor later, it is probably best to leave the indentation to the word processor and not use these options in emacs.

The "Help" menu allows you to reach various manuals. You can also access the Emacs psychotherapist.

You can see from these menu options alone, that Emacs could be

in and of itself considered to be an operating system. I have

not really touched on every thing that Emacs can do in this section.

In GNU Emacs 25.2.1 (x86_64-w64-mingw32)

of 2017-04-24 built on LAPHROAIG

Windowing system distributor 'Microsoft Corp.', version 6.1.7601

Configured using:

'configure --without-dbus --without-compress-install 'CFLAGS=-O2

-static -g3''

Configured features:

XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB

TOOLKIT_SCROLL_BARS

Important settings:

value of $LANG: ENU

locale-coding-system: cp1252

Major mode: Text

Minor modes in effect:

global-semanticdb-minor-mode: t

global-semantic-idle-scheduler-mode: t

semantic-mode: t

global-ede-mode: t

shell-dirtrack-mode: t

display-time-mode: t

show-paren-mode: t

tooltip-mode: t

global-eldoc-mode: t

electric-indent-mode: t

mouse-wheel-mode: t

tool-bar-mode: t

menu-bar-mode: t

file-name-shadow-mode: t

global-font-lock-mode: t

font-lock-mode: t

blink-cursor-mode: t

window-divider-mode: t

auto-composition-mode: t

auto-encryption-mode: t

auto-compression-mode: t

size-indication-mode: t

column-number-mode: t

line-number-mode: t

visual-line-mode: t

transient-mark-mode: t

Recent messages:

Loading c:/Users/ETFVN/AppData/Roaming/.emacs...done

Saving file c:/Users/ETFVN/AppData/Roaming/.emacs...

Wrote c:/Users/ETFVN/AppData/Roaming/.emacs

Loading c:/Users/ETFVN/AppData/Roaming/.emacs...done

Auto-saving...done

Saving file c:/Users/ETFVN/Documents/eFiles/tutorials/emacsTutorial.txt...

Wrote c:/Users/ETFVN/Documents/eFiles/tutorials/emacsTutorial.txt

Saving file c:/Users/ETFVN/Documents/eFiles/tutorials/emacsTutorial.txt...

Wrote c:/Users/ETFVN/Documents/eFiles/tutorials/emacsTutorial.txt

Load-path shadows:

None found.

Features:

(shadow sort mail-extr emacsbug sendmail apropos eieio-opt novice

tutorial tabify calc-alg calc-ext calc-misc calc-menu calc calc-loaddefs

calc-macs cal-move cal-menu calendar cal-loaddefs eudc eudc-vars

cursor-sensor nndraft nnmh network-stream nsm auth-source starttls

gnus-agent gnus-srvr gnus-score score-mode nnvirtual gnus-msg gnus-art

mm-uu mml2015 mm-view mml-smime smime dig mailcap nntp gnus-cache

gnus-sum gnus-group gnus-undo gnus-start gnus-cloud nnimap nnmail

mail-source tls gnutls utf7 netrc nnoo parse-time gnus-spec gnus-int

gnus-range message dired format-spec rfc822 mml mml-sec password-cache

epg mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045

ietf-drums mailabbrev gmm-utils mailheader gnus-win gnus gnus-ems

nnheader gnus-util mail-utils mm-util help-fns mail-prsvr

semantic/db-mode semantic/db semantic/idle semantic/format

semantic/tag-ls semantic/find semantic/ctxt semantic/util-modes

semantic/util semantic semantic/tag semantic/lex semantic/fw mode-local

find-func ede/speedbar ede/files ede ede/detect ede/base ede/auto

ede/source eieio-base eieio-speedbar eieio-custom cl-seq eieio

eieio-core cl-macs cedet shell pcomplete grep compile comint ansi-color

ring misearch multi-isearch time speedbar sb-image ezimage dframe

cus-edit wid-edit thingatpt hi-lock deeper-blue-theme paren cus-start

cus-load finder-inf package epg-config seq byte-opt gv bytecomp

byte-compile cl-extra help-mode easymenu cconv cl-loaddefs pcase cl-lib

time-date mule-util tooltip eldoc electric uniquify ediff-hook vc-hooks

lisp-float-type mwheel dos-w32 ls-lisp disp-table w32-win w32-vars

term/common-win tool-bar dnd fontset image regexp-opt fringe

tabulated-list newcomment elisp-mode lisp-mode prog-mode register page

menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock

syntax facemenu font-core frame cl-generic cham georgian utf-8-lang

misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms

cp51932 hebrew greek romanian slovak czech european ethiopic indian

cyrillic chinese charscript case-table epa-hook jka-cmpr-hook help

simple abbrev minibuffer cl-preloaded nadvice loaddefs button faces

cus-face macroexp files text-properties overlay sha1 md5 base64 format

env code-pages mule custom widget hashtable-print-readable backquote

w32notify w32 multi-tty make-network-process emacs)

Memory information:

((conses 16 256506 39924)

(symbols 56 36576 0)

(miscs 48 243 187)

(strings 32 61724 3996)

(string-bytes 1 1950418)

(vectors 16 30605)

(vector-slots 8 674350 7742)

(floats 8 699 297)

(intervals 56 593 0)

(buffers 976 36))

_{Gabriel Rider}_|Control Systems Developer I_{Matrix Technologies, Inc.
14107 W. 95}^th_{Street
Lenexa, Kansas 66215}

_{Matrix
913-687-5704 ext. 712}

_BCS

_816-242-2287

From:	G. Rider
Subject:	bug#29952: 25.2; It would be nice if Emacs had a built in graphical tutorial.
Date:	Tue, 02 Jan 2018 16:42:15 -0500