diff --git a/CMakeLists.txt b/CMakeLists.txt index 987cbd9e..b4d7ffad 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -12,5 +12,5 @@ KDE4_NO_ENABLE_FINAL(konsole) add_subdirectory( src ) add_subdirectory( data ) add_subdirectory( desktop ) - +add_subdirectory( doc/manual ) diff --git a/doc/manual/CMakeLists.txt b/doc/manual/CMakeLists.txt new file mode 100644 index 00000000..cad13c8f --- /dev/null +++ b/doc/manual/CMakeLists.txt @@ -0,0 +1,3 @@ +########### install files ############### +# +kde4_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en) diff --git a/doc/manual/index.docbook b/doc/manual/index.docbook new file mode 100644 index 00000000..04a0e0e1 --- /dev/null +++ b/doc/manual/index.docbook @@ -0,0 +1,1055 @@ + + + + + +]> + + + + +The &konsole; Handbook + +&Jonathan.Singer; &Jonathan.Singer.mail; +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; + + +&Robert.Knight; &Robert.Knight.mail; + + + +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; + + + +&Waldo.Bastian; &Waldo.Bastian.mail; + + + +&Mike.McBride; &Mike.McBride.mail; + + + + + + + +200020012002 +&Jonathan.Singer; + + +2005200820092010 +&Kurt.Hindenburg; + + +&FDLNotice; + +2010-05-25 +2.5.0 + +&konsole; is &kde;'s terminal emulator. + + +KDE +konsole +kdebase +command +line +terminal +cli + + + + + +Introduction + + +What is a terminal? + +&konsole; is an X terminal +emulator, often referred to as a terminal or a shell. It emulates a command line interface in a text only window. + + +Explaining the use of the &UNIX; CLI is beyond the scope of this document. A search of the web for these terms will produce more information. + + + + +Scrollback + +&konsole; uses the notion of scrollback +to allow user's to view previously displayed output. +By default, scrollback is on +and set to save 1000 lines of +output in addition to what is currently displayed on the screen. +As lines of text scroll off the top of the screen, they can be reviewed +by moving the scroll bar upwards, scrolling with a mouse wheel or through +the use of the +&Shift;Page Up (to move +back a page), +&Shift;Page Down (to move forward a page), +&Shift;Up Arrow (to move up a line) and +&Shift;Down Arrow (to move down a line) keys. + + +When the scrolllock is on, +ordinary input and output from the shell is suspended, and you can +scroll through the history with +Page Up, +Page Down, +Up Arrow and +Down Arrow. + + + + + + +Profiles +Profiles allow the user to quickly and easily automate the running +of common commands. Examples could include: + + +ssh into another machine +starting an irc session +use tail to watch a file + + + + + +Procedure to create a new profile: + +Click on the menu entry SettingsConfigure Profiles... + + +Click on the button New Profile.... + +Fill in the first entry with a name. This is the +name that will show in the menu, and will be the default label instead +of Shell when you start a session of this type. + + +Enter a command just as you normally would if you opened a new +shell and were going to issue that command. For our first example above, you +might type ssh administration. + +On the other tabs of the dialog, configure this session's appearance. +You can configure a different font, colour scheme, $TERM type and many +other settings for each session. + +Press the OK button. The new session +is now available in the Manage Profiles... dialog. + + + + + + +After creating profiles, they are listed by their name in the +FileNew Tab menu +underneath the default Shell item. + + + + + + +Mouse Buttons + +This section details the use of the mouse buttons for the common +right handed mouse button order. +For the left handed mouse button order, swap left and right in the text below. + + + + + +Left + + All &LMB; clicks will be sent to a mouse-aware +application running in &konsole;. +If an application will react on mouse clicks, &konsole; +indicates this by showing an arrow cursor. If not, an I-beam (bar) +cursor is shown. + +Holding the &LMB; down and +dragging the mouse over the screen with a mouse-unaware application +running will mark a region of the text. While dragging, the marked +text is displayed reversed for visual feedback. Select Copy +from the Edit menu to copy the marked text to the clipboard for further use +within &konsole; or another application. The selected text can also be +dragged and dropped into compatible applications. Click on the selected +text and drag it to the desired location. Depending on your &kde; settings, +you may need to hold the &Ctrl; key while dragging. + +Normally, new-line characters are inserted at the end of each +line selected. This is best for cut and paste of source code, or the output +of a particular command. For ordinary text, the line breaks are often +not important. One might prefer, however, for the text to be a stream +of characters that will be automatically re-formatted when pasted into +another application. To select in text-stream mode, hold down the +&Ctrl; key while selecting normally. + +Pressing the &Ctrl; and &Alt; keys along with the &LMB; +will select a column of text. + + +Double-click with the &LMB; to select a word; +triple-click to select an entire line. + +If the upper or lower edge of the text area is touched while +marking, &konsole; scrolls up or down, eventually exposing text within +the history buffer. The scrolling stops when the mouse stops +moving. + +After the mouse is released, &konsole; attempts to keep the text +in the clipboard visible by holding the marked area reversed. The +marked area reverts back to normal as soon as the contents of the +clipboard change, the text within the marked area is altered or the +&LMB; is clicked. + +To mark text on a mouse-aware application (Midnight Commander, for example) +the &Shift; key has to be pressed when clicking. + + + + + +Middle + +Pressing the &MMB; +pastes text currently in the clipboard. Holding down the &Ctrl; key as you +press the &MMB; pastes the text and sends +it to &konsole;. + +If you have a mouse with only two buttons, pressing both +the &LMB; and &RMB; together emulates the &MMB; of a three button mouse. + +If you have a wheel as the middle button, +rolling it in a mouse unaware program will move &konsole;'s scrollbar. + + + + + +Right + +These items appear in the menu when the &RMB; +is pressed: + +Copy, +Paste, +Open File Manager, +Set Encoding +Clear Scrollback, +Configure Scrollback..., +Show Menu Bar, +Change Profile, +Configure Current Profile..., +and Close Tab + + +In a mouse aware application, press the &Shift; key along with the +&RMB; to get the popup menu. + + + + + + + + + + +Command Reference + + +The Menubar + +The menubar is at the top of the &konsole; window. +If the menubar is hidden, +Show Menu Bar can be reached by +right clicking in the window +(as long as no full screen application is running in that +window such as vi, minicom, etc.). The default shortcut +is listed after each menu item. + + + +<guimenu>File</guimenu> Menu + + + + +&Ctrl;&Shift;N +FileNew Window + + +Opens a new separate &konsole; window with the default profile + + + + +&Ctrl;&Shift;T +FileNew Tab + +Opens a new tab with the default profile +&konsole; ships with the Shell profile as the default. +Any new profiles added by the user will be listed in the sub-menu. + + + + + +&Ctrl;&Shift;W +File +Close Tab + +Closes the current tab + + + + +File +Save Output As... +Saves the current scrollback as a text or html + file + + + +File +Open File Manager + +Opens &kde;'s file manager +at the current directory. By default, that is +&dolphin;. + + + + + +&Ctrl;&Shift;Q +File +Quit + +Quits &konsole; +&konsole; will display a window if there is more than one +tab open. This window can be disabled by clicking on the Do not ask again checkbox. + + + + + + + + + +<guimenu>Edit</guimenu> Menu + + + + +&Ctrl;&Shift;C +Edit +Copy +Copies the selected text to the clipboard + + + + +&Ctrl;&Shift;V +EditPaste + +Pastes text from the clipboard at the cursor +location + + + + +EditCopy Input ToAll Tabs in Current Window +Allows input from the current session to be sent simultaneously to all sessions in current window + + + + + + +&Ctrl;&Shift;. +EditCopy Input ToSelect Tabs... +Allows input from the current session to be sent simultaneously to sessions picked by user + + + + + + +&Ctrl;&Shift;/ +EditCopy Input ToNone +Stop all input to other sessions + + + + + + +&Ctrl;&Alt;S +EditRename Tab... +Opens a dialog box allowing you to change +the name of the current tab +(more info) + + + + + +&Ctrl;&Alt;U +EditZModem Upload... +Opens up a dialog to select a file to be uploaded if the required software is installed + + + + + + +&Ctrl;&Shift;F +EditFind... +Opens a search bar at the bottom of &konsole;'s window + +This allows for case sensitive, forward or backwards, and regular expressions searches. + + + + + +F3 +EditFind +Next +Moves to the next search instance + + + + + +&Shift;F3 +EditFind +Previous +Moves to the previous search instance + + + + + + + + +<guimenu>View</guimenu> Menu + + + + +&Ctrl;&Shift;( +ViewSplit ViewSplit +View Left/Right + +Splits all the tabs into left and right views + +Any output on one view is duplicated in the other view. + + + + + +&Ctrl;&Shift;) +ViewSplit ViewSplit +View Top/Bottom + +Splits all the tabs into top and bottom views + +Any output on one view is duplicated in the other view. + + + + + +&Ctrl;&Shift;S +ViewSplit View +Close Active + +Closes the current view + + + + + +&Ctrl;&Shift;O +ViewSplit View +Close Others + +Closes the non-current view + + + + + +&Ctrl;&Shift;] +ViewSplit ViewExpand View + +Makes the current view larger + + + + + +&Ctrl;&Shift;[ +ViewSplit ViewShrink View + +Makes the current view smaller + + + + + + +&Ctrl;&Shift;H +ViewDetach Current Tab + +Opens the current tab in a +separate window + +Quiting the previous &konsole; window will not +affect the newly created window. + + + + + +&Ctrl;&Shift;I +ViewMonitor for +Silence +Toggles the monitoring of the current tab for +lack of activity + +By default, after 10 seconds of inactivity, an info icon will appear on +the session's tab. +The type of alerts can be changed through +SettingsConfigure NotificationsSilence in monitored session. + + + + + +&Ctrl;&Shift;A +ViewMonitor for +Activity +Toggles the monitoring of the current tab for +activity + +Upon any activity, an info icon will appear on the session's tab. +The type of alerts can be changed through +SettingsConfigure NotificationsActivity in monitored session. + + + + + +&Ctrl;&Shift;+ +ViewEnlarge Font +Increases the text font size + + + + +&Ctrl;&Shift;- +ViewShrink Font +Decreases the text font size + + + +View +Set Encoding +Sets the character encoding + + + +ViewClear Scrollback +Clears the text in the scrollback + + + + + +&Ctrl;&Shift;X +ScrollbackClear +Scrollback and Reset +Clears the text in the current tab and scrollback +and resets the terminal + + + + + + +<guimenu>Bookmarks</guimenu> Menu + + + + + +&Ctrl;&Shift;B +BookmarksAdd Bookmark +Adds the current location + + + +BookmarksBookmark Tabs as Folder... +Adds all tabs to a bookmark folder + +A dialog will open for the bookmark folder name. + + + + +BookmarksNew Bookmark Folder... +Adds a new folder to the bookmark list + +A dialog will open for the bookmark folder name. + + + + +BookmarksEdit Bookmarks +Opens the bookmark editor + +You can use the bookmark editor to manually add URLs. +Currently, &konsole; accepts the following: + +ssh://user@host:port +telnet://user@host:port + + + + + + + + + + +<guimenu>Settings</guimenu> Menu + + + +SettingsConfigure +Profiles... +Opens a editor for managing profiles + + + + + + +&Ctrl;&Shift;M +SettingsShow +Menu Bar +Toggles the menubar being visible + + + + +SettingsFull Screen Mode +Toggles &konsole; filling the entire screen + + + +SettingsConfigure +Shortcuts... +Opens the keyboard shortcut editor + + + + +SettingsConfigure +Notifications... +Opens the notifications editor + + + + + + + +<guimenu>Help</guimenu> Menu + +&help.menu.documentation; + + + + +Rename Tab Dialog + +The name of the current tab can be changed from this dialog. +The dialog can be displayed via the menu, the shortcut &Ctrl;&Alt;S or by +double-clicking on the tab in the tab bar. +These changes can be made permanent by editing the current profile. + + + +&konsole; will subsitute these tokens: + +%n : program name +%d : current directory (short) +%D : current directory (long) +%w : window title set by shell +%# : session number +%u : user name + + + + +Examples: + + + +%d : %n + with /usr/src as current directory and running +bash will display +usr/s : bash + + + +%D : %n + with /usr/src as current directory and running +top will display +/usr/src : top + + + +%w (%#) + with ~ as current directory and running +vim in the first tab will display +[No Name] (~) - VIM(1) + + + + + + + + + +Copy Input Dialog + +The text entered in one tab can simultaneously be sent to other tabs. +This dialog allows you to select which tabs will get that input. +The current tab will be greyed out. + + + + + + + +Scrollback Options Dialog + +The +scrollback +option for the history size can be changed in this dialog. There is also +a check box to save these settings to the current profile. + + + + + + + +Command-line Options + +When &konsole; is started from the command line, various options +can be specified to modify its behavior. + + + + +List the various options. + + + + file +Start &konsole; using a saved set of sessions. + + + + +List all of the available profiles. + + + + + +Start &konsole; in the background and bring to the front when the F12 key is pressed. + + + + + +Create a new tab in an existing window rather than creating a new window. + + + + +file +Create tabs as specified in the given tabs configuration file. + +The file has one tab per line in the following format: +title: This is the title;; command: run me + + + + + + dir +Open with +dir as the working (starting) directory. + + + + +Disable transparent backgrounds, even if the system supports them. + + + + + +Try to enable transparency, even if the system does not appear to support it. + + + + + +Do not close the initial session automatically when it ends. + + + + + property=value +Change the value of a profile property. + + + + + command +Execute +command instead of the normal shell. +Any arguments after command will be passed to +command, not &konsole;. + + + + + +&konsole; also accepts generic &Qt; and &kde; options: + + + + +List &Qt;-specific options + + + +The following &Qt; options have no effect on &konsole;: + + + + +, +fontname +Defines the application font + + + +, +color +Sets the default background color + + + +, +color +Sets the default foreground color + + + +, +color +Sets the default button color + + + + + + + + + + +List &kde;-specific options + + + +List all options + + + +Show the authors' names + + + +Show the version number + + + +Show license information + + + + + + +Scripting &konsole; + +For &kde; 4, the old &DCOP; has been replaced with &DBus;. +&konsole; does support numerous methods that can be used with &DBus;. + +There are two ways to use the &DBus; interface: &Qt;'s &GUI; +qdbusviewer +and the command line +qdbus. + + + +Examples: + + + +% +qdbus +will display all services available. + + + +% +qdbus + +will display the &DBus; interface for &konsole;. + + + +% +qdbus + +will display methods for controlling the main &konsole; window. + + + +% +qdbus + +will display methods for session 1. + + + + + + +If you start &konsole; from a terminal you may need to change + to +. + + + +For more information, please visit +&DBus; tutorial. + + + + + +Credits and Copyright + +&konsole; is currently maintained by &Robert.Knight; &Robert.Knight.mail; + +Previous &konsole; maintainers include: &Kurt.Hindenburg; &Kurt.Hindenburg.mail; and &Waldo.Bastian; &Waldo.Bastian.mail; + +The application &konsole; Copyright © 1997-2008 +&Lars.Doelle; &Lars.Doelle.mail; + +This document was written by &Jonathan.Singer; +&Jonathan.Singer.mail; + +This document was updated for &kde; 3.4 by +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; + +This document was updated for &kde; 4.1 by +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; + +Originally converted to DocBook SGML by +&Mike.McBride; and &Lauri.Watts; + + + +&underFDL; +&underGPL; + + + +Links + +For more information please visit these websites: + +&konsole;'s homepage on &kde;'s UserBase  +&konsole;'s homepage +&konsole;'s mailing list +&kde; on +FreeBSD +&kde; on &Solaris; + + + + +&documentation.index; + + + + + + diff --git a/doc/manual/kde4.notes b/doc/manual/kde4.notes new file mode 100644 index 00000000..89235086 --- /dev/null +++ b/doc/manual/kde4.notes @@ -0,0 +1,141 @@ + + Konsole's interface ( particularly the menus and settings ) have + changed in KDE 4. These are notes on what needs to be covered + in the handbook and somewhere to draft a layout for the documentation. + + -- Robert Knight (robertknight@gmail.com) + +----------- +khindenburg - Aug 2008 +The handbook has been updated to trunk/ which will be 4.2. +The menus and command-line options are correct. +There is room for more information which could include some of the ideas below. +Also a FAQ section needs to be added. +Consider adding link to updated Handbook on konsole.kde.org +Consider what to do with konsole.kde.org +----------- + + Introduction + - What is Konsole? + - What is a terminal? + - How can I learn to use the terminal? + + Ideas: + + -> Information on more beginner-friendly shells such as Fish + -> Basic introduction? + -> Links to beginners tutorial for Bash shell + -> Links to information on scripting languages + -> Links to information on Vim, Emacs etc. + + - ( Konsole features )? + - A brief list of useful features in Konsole with links + to the appropriate section of the handbook. + + Basic Usage + - Creating new tabs + - Creating new windows + - Closing a tab or window + - Input + - Keyboard + - Mouse + - Opening links and email addresses + - Edit actions + - Copy and Paste + - Tab titles and renaming the tab + - Copying input to all tabs + - Scrolling + - Scrolling output + - With the mouse + - With the keyboard + - Clearing the display + - Clearing the current display only + - Clearing everything + - Changing the scroll-back size + - Searching output + - Saving output + - View actions + - Changing the text size temporarily + - Splitting the view + - Uses of split view + - What happens when the view is split? + - How to split the view: Left/Right , Top/Bottom + - Closing (unsplitting) the view: Close active view, close others + - Changing the size of the views + - Using the mouse + - Using the keyboard shortcuts + - Monitoring for silence or activity + - Hiding the menu bar + - Full screen mode + - Entering into and exiting from + + - Moving a tab between windows + - Bookmarks + - Creating a new bookmark + - Bookmarking a set of tabs as a folder + - Local vs SSH bookmarks + + Konsole Setup : Profiles + + - What is a profile + - Changing the current profile in a tab + - Editing the current profile + - General + - Name + - Command + - Working directory + - Icon + - Environment editor + - The $TERM environment variable + - Menu Bar display + - Tabs + - Tab titles + - Local vs Remote + - Inserting dynamic elementss + - Tab bar position + - Tab bar display mode + - Color Schemes and Fonts + - Choosing and previewing a color scheme + - Changing the text size + - Changing the font + + (Link -> Color Schemes) + + - Scrollback + - Scroll back types ( none , fixed line count , unlimited ) + - Scroll bar position + - Keyboard Setup + - Choosing a keyboard binding + + (Link -> Keyboard Bindings) + + - Advanced + - Managing profiles + - Creating new profiles + - Creating a new session from a profile + - Editing existing profiles + - Removing profiles + - Favorite profiles + - Profile shortcuts + + Color Schemes + - Creating new color schemes + - The color palette + - Changing a color + - Transparent color schemes + -> Transparency requirements + - Randomly varied background colors + - Editing existing color schemes + - Removing color schemes + + Keyboard Bindings + - Creating a new keyboard binding + - Editing key binding entries + - Key sequence specification + - Output specification + - Escape characters + - Adding a new key binding + - Removing a key binding + - Testing key bindings + - Editing existing bindings + - Removing bindings