From 4aed2c8219774f5d797760606b8489a92ddc5163 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/Makefile.am | 5 + doc/faq/Makefile.am | 4 + doc/faq/TODO | 35 + doc/faq/about.docbook | 72 + doc/faq/configkde.docbook | 250 ++ doc/faq/contrib.docbook | 164 ++ doc/faq/desktop.docbook | 97 + doc/faq/filemng.docbook | 207 ++ doc/faq/getkde.docbook | 79 + doc/faq/index.docbook | 136 + doc/faq/install.docbook | 726 +++++ doc/faq/intro.docbook | 93 + doc/faq/kdeapps.docbook | 158 ++ doc/faq/misc.docbook | 219 ++ doc/faq/moreinfo.docbook | 154 + doc/faq/nonkdeapps.docbook | 106 + doc/faq/notrelated.docbook | 232 ++ doc/faq/panel.docbook | 193 ++ doc/faq/qt.docbook | 76 + doc/faq/questions.docbook | 160 ++ doc/faq/sound.docbook | 55 + doc/faq/tips.docbook | 137 + doc/faq/webbrowse.docbook | 222 ++ doc/faq/winmng.docbook | 134 + doc/glossary/Makefile.am | 2 + doc/glossary/checkxrefs | 10 + doc/glossary/index.docbook | 296 ++ doc/glossary/kdeprintingglossary.docbook | 1387 +++++++++ doc/kappfinder/Makefile.am | 5 + doc/kappfinder/man-kappfinder.1.docbook | 81 + doc/kate/Makefile.am | 3 + doc/kate/TODO | 6 + doc/kate/advanced.docbook | 1242 ++++++++ doc/kate/configdialog01.png | Bin 0 -> 44641 bytes doc/kate/configdialog02.png | Bin 0 -> 25384 bytes doc/kate/configuring.docbook | 1595 +++++++++++ doc/kate/fundamentals.docbook | 621 ++++ doc/kate/highlighted.png | Bin 0 -> 4797 bytes doc/kate/highlighting.docbook | 931 ++++++ doc/kate/index.docbook | 293 ++ doc/kate/kate.png | Bin 0 -> 81016 bytes doc/kate/man-kate.1.docbook | 165 ++ doc/kate/mdi.docbook | 266 ++ doc/kate/menus.docbook | 1438 ++++++++++ doc/kate/mimetypechooser.png | Bin 0 -> 15823 bytes doc/kate/part.docbook | 671 +++++ doc/kate/plugins.docbook | 28 + doc/kate/regular-expressions.docbook | 664 +++++ doc/kate/unhighlighted.png | Bin 0 -> 3471 bytes doc/kcontrol/Makefile.am | 6 + doc/kcontrol/arts/Makefile.am | 2 + doc/kcontrol/arts/index.docbook | 201 ++ doc/kcontrol/arts/midi.docbook | 24 + doc/kcontrol/background/Makefile.am | 2 + doc/kcontrol/background/index.docbook | 383 +++ doc/kcontrol/bell/Makefile.am | 2 + doc/kcontrol/bell/index.docbook | 74 + doc/kcontrol/cache/Makefile.am | 2 + doc/kcontrol/cache/index.docbook | 69 + doc/kcontrol/clock/Makefile.am | 2 + doc/kcontrol/clock/index.docbook | 74 + doc/kcontrol/colors/Makefile.am | 2 + doc/kcontrol/colors/index.docbook | 132 + doc/kcontrol/cookies/Makefile.am | 2 + doc/kcontrol/cookies/index.docbook | 211 ++ doc/kcontrol/crypto/Makefile.am | 2 + doc/kcontrol/crypto/index.docbook | 205 ++ doc/kcontrol/desktop/Makefile.am | 2 + doc/kcontrol/desktop/index.docbook | 84 + doc/kcontrol/desktopbehavior/Makefile.am | 2 + doc/kcontrol/desktopbehavior/index.docbook | 198 ++ doc/kcontrol/ebrowsing/Makefile.am | 2 + doc/kcontrol/ebrowsing/index.docbook | 156 ++ doc/kcontrol/email/Makefile.am | 2 + doc/kcontrol/email/index.docbook | 103 + doc/kcontrol/energy/Makefile.am | 2 + doc/kcontrol/energy/index.docbook | 110 + doc/kcontrol/filemanager/Makefile.am | 2 + doc/kcontrol/filemanager/index.docbook | 297 ++ doc/kcontrol/filemanager/kfileman1.png | Bin 0 -> 7883 bytes doc/kcontrol/filemanager/kfileman2.png | Bin 0 -> 9224 bytes doc/kcontrol/filetypes/Makefile.am | 2 + doc/kcontrol/filetypes/index.docbook | 338 +++ doc/kcontrol/fonts/Makefile.am | 2 + doc/kcontrol/fonts/index.docbook | 121 + doc/kcontrol/helpindex/Makefile.am | 2 + doc/kcontrol/helpindex/index.docbook | 144 + doc/kcontrol/icons/Makefile.am | 2 + doc/kcontrol/icons/index.docbook | 233 ++ doc/kcontrol/index.docbook | 637 +++++ doc/kcontrol/kcmaccess/Makefile.am | 4 + doc/kcontrol/kcmaccess/index.docbook | 179 ++ doc/kcontrol/kcmcss/Makefile.am | 2 + doc/kcontrol/kcmcss/index.docbook | 257 ++ doc/kcontrol/kcmfontinst/Makefile.am | 2 + doc/kcontrol/kcmfontinst/index.docbook | 76 + doc/kcontrol/kcmkonsole/Makefile.am | 2 + doc/kcontrol/kcmkonsole/index.docbook | 177 ++ doc/kcontrol/kcmlaunch/Makefile.am | 2 + doc/kcontrol/kcmlaunch/index.docbook | 70 + doc/kcontrol/kcmnotify/Makefile.am | 2 + doc/kcontrol/kcmnotify/index.docbook | 151 + doc/kcontrol/kcmsmserver/Makefile.am | 2 + doc/kcontrol/kcmsmserver/index.docbook | 109 + doc/kcontrol/kcmstyle/Makefile.am | 2 + doc/kcontrol/kcmstyle/index.docbook | 189 ++ doc/kcontrol/kcmtaskbar/Makefile.am | 2 + doc/kcontrol/kcmtaskbar/index.docbook | 142 + doc/kcontrol/kdm/Makefile.am | 2 + doc/kcontrol/kdm/index.docbook | 518 ++++ doc/kcontrol/keyboard/Makefile.am | 2 + doc/kcontrol/keyboard/index.docbook | 90 + doc/kcontrol/keys/Makefile.am | 2 + doc/kcontrol/keys/index.docbook | 191 ++ doc/kcontrol/khtml/Makefile.am | 2 + doc/kcontrol/khtml/index.docbook | 352 +++ doc/kcontrol/khtml/nsplugin.docbook | 91 + doc/kcontrol/kwindecoration/Makefile.am | 2 + doc/kcontrol/kwindecoration/index.docbook | 98 + doc/kcontrol/language/Makefile.am | 2 + doc/kcontrol/language/index.docbook | 218 ++ doc/kcontrol/mouse/Makefile.am | 2 + doc/kcontrol/mouse/index.docbook | 493 ++++ doc/kcontrol/netpref/Makefile.am | 2 + doc/kcontrol/netpref/index.docbook | 109 + doc/kcontrol/panel/Makefile.am | 2 + doc/kcontrol/panel/index.docbook | 244 ++ doc/kcontrol/panelappearance/Makefile.am | 3 + doc/kcontrol/panelappearance/index.docbook | 122 + doc/kcontrol/passwords/Makefile.am | 2 + doc/kcontrol/passwords/index.docbook | 84 + doc/kcontrol/performance/Makefile.am | 2 + doc/kcontrol/performance/index.docbook | 102 + doc/kcontrol/proxy/Makefile.am | 2 + doc/kcontrol/proxy/index.docbook | 197 ++ doc/kcontrol/proxy/socks.docbook | 56 + doc/kcontrol/screensaver/Makefile.am | 2 + doc/kcontrol/screensaver/index.docbook | 203 ++ doc/kcontrol/screenshot.png | Bin 0 -> 103581 bytes doc/kcontrol/smb/Makefile.am | 2 + doc/kcontrol/smb/index.docbook | 106 + doc/kcontrol/spellchecking/Makefile.am | 2 + doc/kcontrol/spellchecking/index.docbook | 88 + doc/kcontrol/useragent/Makefile.am | 2 + doc/kcontrol/useragent/index.docbook | 117 + doc/kcontrol/windowmanagement/Makefile.am | 2 + doc/kcontrol/windowmanagement/index.docbook | 63 + doc/kdcop/Makefile.am | 4 + doc/kdcop/index.docbook | 78 + doc/kdebugdialog/Makefile.am | 3 + doc/kdebugdialog/index.docbook | 134 + doc/kdeprint/Makefile.am | 3 + doc/kdeprint/add-printer-wiz.docbook | 290 ++ doc/kdeprint/cr32-action-wizard.png | Bin 0 -> 606 bytes doc/kdeprint/cups-config.docbook | 2072 ++++++++++++++ ...s-filterarchitecture-kivio-70Percent-scaled.png | Bin 0 -> 100464 bytes doc/kdeprint/cupsaddprinterwizard1.png | Bin 0 -> 70554 bytes .../cupsaddprinterwizard2_backendselection.png | Bin 0 -> 76444 bytes doc/kdeprint/cupsaddprinterwizard3_networkscan.png | Bin 0 -> 70820 bytes .../cupsaddprinterwizard3_networkscan_results.png | Bin 0 -> 90883 bytes .../cupsaddprinterwizard4_networkscan_config.png | Bin 0 -> 10607 bytes doc/kdeprint/cupsoptions.docbook | 602 ++++ .../cupsserverconfig_browse_relay_add_button.png | Bin 0 -> 2562 bytes .../cupsserverconfig_browsingmasks_add_button.png | Bin 0 -> 2294 bytes .../cupsserverconfiguration10_browsinggeneral.png | Bin 0 -> 14678 bytes ...psserverconfiguration11_browsingconnections.png | Bin 0 -> 15433 bytes .../cupsserverconfiguration11_browsingmasks.png | Bin 0 -> 15493 bytes .../cupsserverconfiguration12_browsingtimeouts.png | Bin 0 -> 14109 bytes .../cupsserverconfiguration14_browsingrelay.png | Bin 0 -> 14903 bytes ...uration15a_resourceallprinters_defineaccess.png | Bin 0 -> 15822 bytes ...uration15b_resourceallprinters_defineaccess.png | Bin 0 -> 5870 bytes ...uration15c_resourceallprinters_defineaccess.png | Bin 0 -> 5470 bytes doc/kdeprint/cupsserverconfiguration1_welcome.png | Bin 0 -> 31316 bytes doc/kdeprint/cupsserverconfiguration2_general.png | Bin 0 -> 15870 bytes doc/kdeprint/cupsserverconfiguration3_logging.png | Bin 0 -> 16490 bytes .../cupsserverconfiguration4_directories.png | Bin 0 -> 17728 bytes doc/kdeprint/cupsserverconfiguration5_HTTP.png | Bin 0 -> 15010 bytes .../cupsserverconfiguration6_encryption.png | Bin 0 -> 15083 bytes .../cupsserverconfiguration7_miscellanious.png | Bin 0 -> 15943 bytes .../cupsserverconfiguration8_networkgeneral.png | Bin 0 -> 15538 bytes .../cupsserverconfiguration9_networkclients.png | Bin 0 -> 14998 bytes ...erverconfiguration_resourceadminaccessmasks.png | Bin 0 -> 47480 bytes ...erverconfiguration_resourceadminaddprinters.png | Bin 0 -> 30334 bytes ...ation_resourceadminaddprinters_defineaccess.png | Bin 0 -> 43890 bytes ...verconfiguration_resourceadminauthorization.png | Bin 0 -> 30503 bytes .../cupsserverconfiguration_securityoverview.png | Bin 0 -> 16804 bytes doc/kdeprint/extensions.docbook | 57 + doc/kdeprint/external-command.docbook | 25 + doc/kdeprint/final-word.docbook | 117 + doc/kdeprint/getting-started.docbook | 143 + doc/kdeprint/highlights.docbook | 518 ++++ doc/kdeprint/index.docbook | 200 ++ doc/kdeprint/kcontrol-icon.png | Bin 0 -> 1202 bytes .../kcontrolcenter-printmanager-jobcontrol-2.png | Bin 0 -> 10761 bytes doc/kdeprint/kcron_to_be_printed.png | Bin 0 -> 10637 bytes doc/kdeprint/kdeprint-jobviewer.png | Bin 0 -> 11220 bytes doc/kdeprint/kprinter-as-netscape-printcommand.png | Bin 0 -> 8210 bytes doc/kdeprint/kprinter-kivio.png | Bin 0 -> 11149 bytes doc/kdeprint/kprinter.png | Bin 0 -> 12568 bytes doc/kdeprint/kprinter_called_from_run_command.png | Bin 0 -> 6068 bytes .../kprinter_with_kcron_developer_special.png | Bin 0 -> 11245 bytes doc/kdeprint/lpd.docbook | 18 + doc/kdeprint/lpr-bsd.docbook | 25 + doc/kdeprint/lprng.docbook | 7 + doc/kdeprint/ps-boxes.png | Bin 0 -> 441 bytes doc/kdeprint/rlpr.docbook | 18 + doc/kdeprint/steinbruch_scaled.png | Bin 0 -> 116567 bytes doc/kdeprint/tech-overview.docbook | 280 ++ doc/kdeprint/theory.docbook | 690 +++++ doc/kdesu/Makefile.am | 5 + doc/kdesu/index.docbook | 320 +++ doc/kdesu/man-kdesu.1.docbook | 179 ++ doc/kdm/Makefile.am | 6 + doc/kdm/index.docbook | 1472 ++++++++++ doc/kdm/kdmrc-ref.docbook | 2316 +++++++++++++++ doc/kfind/Makefile.am | 4 + doc/kfind/index.docbook | 363 +++ doc/kfind/man-kfind.1.docbook | 79 + doc/khelpcenter/Makefile.am | 6 + doc/khelpcenter/background.png | Bin 0 -> 128431 bytes doc/khelpcenter/bgtable.png | Bin 0 -> 25929 bytes doc/khelpcenter/contact.docbook | 138 + doc/khelpcenter/help.docbook | 740 +++++ doc/khelpcenter/index.docbook | 82 + doc/khelpcenter/kdelogo2.png | Bin 0 -> 6833 bytes doc/khelpcenter/khelpcenter.png | Bin 0 -> 1687 bytes doc/khelpcenter/konq.css | 68 + doc/khelpcenter/lines.png | Bin 0 -> 259 bytes doc/khelpcenter/lines2.png | Bin 0 -> 198 bytes doc/khelpcenter/pointers.png | Bin 0 -> 268 bytes doc/khelpcenter/shadow1.png | Bin 0 -> 184 bytes doc/khelpcenter/support.docbook | 102 + doc/khelpcenter/welcome.docbook | 60 + doc/khelpcenter/whatiskde.docbook | 129 + doc/kicker/Makefile.am | 5 + doc/kicker/bookmarks_icon.png | Bin 0 -> 2272 bytes doc/kicker/desktop_icon.png | Bin 0 -> 6881 bytes doc/kicker/index.docbook | 2434 ++++++++++++++++ doc/kicker/k_menu_icon.png | Bin 0 -> 5340 bytes doc/kicker/man-appletproxy.1.docbook | 101 + doc/kicker/man-kicker.1.docbook | 88 + doc/kicker/printsys_icon.png | Bin 0 -> 2588 bytes doc/kicker/quickbrowser_icon.png | Bin 0 -> 3482 bytes doc/kicker/recent_docs_icon.png | Bin 0 -> 3271 bytes doc/kicker/screenshot_left.png | Bin 0 -> 18674 bytes doc/kicker/screenshot_right.png | Bin 0 -> 11764 bytes doc/kicker/taskbar_group.png | Bin 0 -> 4496 bytes doc/kicker/terminals_icon.png | Bin 0 -> 2009 bytes doc/kicker/windowlist_icon.png | Bin 0 -> 2801 bytes doc/kinfocenter/Makefile.am | 6 + doc/kinfocenter/cdinfo/Makefile.am | 3 + doc/kinfocenter/cdinfo/index.docbook | 51 + doc/kinfocenter/devices/Makefile.am | 3 + doc/kinfocenter/devices/index.docbook | 60 + doc/kinfocenter/dma/Makefile.am | 3 + doc/kinfocenter/dma/index.docbook | 64 + doc/kinfocenter/index.docbook | 341 +++ doc/kinfocenter/interrupts/Makefile.am | 3 + doc/kinfocenter/interrupts/index.docbook | 70 + doc/kinfocenter/ioports/Makefile.am | 3 + doc/kinfocenter/ioports/index.docbook | 64 + doc/kinfocenter/memory/Makefile.am | 3 + doc/kinfocenter/memory/index.docbook | 108 + doc/kinfocenter/nics/Makefile.am | 3 + doc/kinfocenter/nics/index.docbook | 45 + doc/kinfocenter/opengl/Makefile.am | 2 + doc/kinfocenter/opengl/index.docbook | 47 + doc/kinfocenter/partitions/Makefile.am | 3 + doc/kinfocenter/partitions/index.docbook | 56 + doc/kinfocenter/pci/Makefile.am | 3 + doc/kinfocenter/pci/index.docbook | 57 + doc/kinfocenter/pcmcia/Makefile.am | 3 + doc/kinfocenter/pcmcia/index.docbook | 38 + doc/kinfocenter/processor/Makefile.am | 3 + doc/kinfocenter/processor/index.docbook | 56 + doc/kinfocenter/protocols/Makefile.am | 3 + doc/kinfocenter/protocols/index.docbook | 39 + doc/kinfocenter/samba/Makefile.am | 4 + doc/kinfocenter/samba/index.docbook | 207 ++ doc/kinfocenter/scsi/Makefile.am | 3 + doc/kinfocenter/scsi/index.docbook | 56 + doc/kinfocenter/sound/Makefile.am | 3 + doc/kinfocenter/sound/index.docbook | 51 + doc/kinfocenter/usb/Makefile.am | 3 + doc/kinfocenter/usb/index.docbook | 43 + doc/kinfocenter/xserver/Makefile.am | 3 + doc/kinfocenter/xserver/index.docbook | 56 + doc/kioslave/Makefile.am | 4 + doc/kioslave/bzip.docbook | 29 + doc/kioslave/bzip2.docbook | 29 + doc/kioslave/cgi.docbook | 24 + doc/kioslave/data.docbook | 47 + doc/kioslave/file.docbook | 20 + doc/kioslave/finger.docbook | 33 + doc/kioslave/fish.docbook | 66 + doc/kioslave/floppy.docbook | 51 + doc/kioslave/ftp.docbook | 43 + doc/kioslave/gopher.docbook | 39 + doc/kioslave/gzip.docbook | 30 + doc/kioslave/help.docbook | 17 + doc/kioslave/http.docbook | 25 + doc/kioslave/https.docbook | 21 + doc/kioslave/imap.docbook | 31 + doc/kioslave/imaps.docbook | 17 + doc/kioslave/index.docbook | 93 + doc/kioslave/info.docbook | 36 + doc/kioslave/lan.docbook | 23 + doc/kioslave/ldap.docbook | 23 + doc/kioslave/mac.docbook | 53 + doc/kioslave/mailto.docbook | 17 + doc/kioslave/man.docbook | 86 + doc/kioslave/mrml.docbook | 26 + doc/kioslave/news.docbook | 20 + doc/kioslave/nfs.docbook | 39 + doc/kioslave/nntp.docbook | 41 + doc/kioslave/pop3.docbook | 13 + doc/kioslave/pop3s.docbook | 14 + doc/kioslave/print.docbook | 170 ++ doc/kioslave/rlan.docbook | 11 + doc/kioslave/rlogin.docbook | 31 + doc/kioslave/sftp.docbook | 19 + doc/kioslave/smb.docbook | 56 + doc/kioslave/smtp.docbook | 16 + doc/kioslave/tar.docbook | 18 + doc/kioslave/telnet.docbook | 17 + doc/kioslave/thumbnail.docbook | 28 + doc/kioslave/webdav.docbook | 65 + doc/kioslave/webdavs.docbook | 17 + doc/klipper/Makefile.am | 4 + doc/klipper/index.docbook | 511 ++++ doc/klipper/screenshot.png | Bin 0 -> 967 bytes doc/kmenuedit/Makefile.am | 3 + doc/kmenuedit/done.png | Bin 0 -> 47674 bytes doc/kmenuedit/index.docbook | 521 ++++ doc/kmenuedit/itemname.png | Bin 0 -> 7163 bytes doc/kmenuedit/kmenueditmain.png | Bin 0 -> 40179 bytes doc/kmenuedit/new.png | Bin 0 -> 9348 bytes doc/kmenuedit/selecticon.png | Bin 0 -> 45475 bytes doc/kmenuedit/selectinternet.png | Bin 0 -> 17293 bytes doc/knetattach/Makefile.am | 2 + doc/knetattach/index.docbook | 349 +++ doc/knetattach/screenshot.png | Bin 0 -> 25179 bytes doc/knetattach/screenshot1.png | Bin 0 -> 41777 bytes doc/knetattach/screenshot2.png | Bin 0 -> 30550 bytes doc/knetattach/screenshot3.png | Bin 0 -> 66693 bytes doc/knetattach/screenshot4.png | Bin 0 -> 43020 bytes doc/kompmgr/Makefile.am | 3 + doc/kompmgr/index.docbook | 433 +++ doc/konqueror/Makefile.am | 4 + doc/konqueror/basics.docbook | 386 +++ doc/konqueror/bookmarks.docbook | 129 + doc/konqueror/browser.docbook | 482 ++++ doc/konqueror/cmndline.png | Bin 0 -> 52222 bytes doc/konqueror/commands.docbook | 1210 ++++++++ doc/konqueror/config.docbook | 137 + doc/konqueror/credits.docbook | 182 ++ doc/konqueror/dirtree.png | Bin 0 -> 50215 bytes doc/konqueror/dragdrop.png | Bin 0 -> 47960 bytes doc/konqueror/faq.docbook | 169 ++ doc/konqueror/filemanager.docbook | 898 ++++++ doc/konqueror/index.docbook | 110 + doc/konqueror/introduction.docbook | 64 + doc/konqueror/konqorg.png | Bin 0 -> 86855 bytes doc/konqueror/man-kbookmarkmerger.1.docbook | 112 + doc/konqueror/parts.png | Bin 0 -> 34160 bytes doc/konqueror/path-complete.docbook | 82 + doc/konqueror/plugins.docbook | 162 ++ doc/konqueror/save-settings.docbook | 92 + doc/konqueror/shortcut1.png | Bin 0 -> 30880 bytes doc/konqueror/shortcut2.png | Bin 0 -> 14159 bytes doc/konqueror/sidebar.docbook | 201 ++ doc/konsole/Makefile.am | 3 + doc/konsole/index.docbook | 1465 ++++++++++ doc/konsole/konsole.png | Bin 0 -> 8848 bytes doc/konsole/tabbar.png | Bin 0 -> 3641 bytes doc/kpager/Makefile.am | 3 + doc/kpager/index.docbook | 381 +++ doc/kpager/screenshot.png | Bin 0 -> 7604 bytes doc/kpager/settings.png | Bin 0 -> 8917 bytes doc/ksplashml/Makefile.am | 4 + doc/ksplashml/index.docbook | 1354 +++++++++ doc/ksysguard/Makefile.am | 4 + doc/ksysguard/index.docbook | 496 ++++ doc/kwrite/Makefile.am | 4 + doc/kwrite/index.docbook | 2952 ++++++++++++++++++++ doc/kxkb/Makefile.am | 4 + doc/kxkb/index.docbook | 358 +++ doc/kxkb/layout.png | Bin 0 -> 27006 bytes doc/kxkb/switching.png | Bin 0 -> 13163 bytes doc/kxkb/xkb.png | Bin 0 -> 20695 bytes doc/quickstart/Makefile.am | 3 + doc/quickstart/index.docbook | 1340 +++++++++ doc/userguide/Makefile.am | 4 + doc/userguide/a-window.png | Bin 0 -> 86896 bytes doc/userguide/accessibility.docbook | 168 ++ doc/userguide/amarok-icon.png | Bin 0 -> 2647 bytes doc/userguide/amarok.png | Bin 0 -> 14673 bytes doc/userguide/base-kde-applications.docbook | 441 +++ doc/userguide/browser-fine-tuning.docbook | 71 + doc/userguide/burning-cds.docbook | 38 + doc/userguide/control-center.docbook | 922 ++++++ doc/userguide/creating-graphics.docbook | 48 + doc/userguide/credits-and-license.docbook | 315 +++ doc/userguide/customizing-desktop.docbook | 365 +++ doc/userguide/desktop.png | Bin 0 -> 38608 bytes doc/userguide/email.docbook | 254 ++ doc/userguide/extragear-applications.docbook | 199 ++ doc/userguide/file-sharing.docbook | 109 + doc/userguide/font-installation.docbook | 79 + doc/userguide/getting-help.docbook | 213 ++ doc/userguide/glossary.docbook | 38 + doc/userguide/groupware-kontact.docbook | 614 ++++ doc/userguide/index.docbook | 611 ++++ doc/userguide/internet-shortcuts.docbook | 80 + doc/userguide/juk-icon.png | Bin 0 -> 2599 bytes doc/userguide/juk.png | Bin 0 -> 74846 bytes doc/userguide/kaboodle-icon.png | Bin 0 -> 2070 bytes doc/userguide/kaboodle.png | Bin 0 -> 21032 bytes doc/userguide/kcalc-systray.png | Bin 0 -> 5311 bytes doc/userguide/kcontrol.png | Bin 0 -> 84846 bytes doc/userguide/kde-as-root.docbook | 52 + doc/userguide/kde-edutainment.docbook | 342 +++ doc/userguide/kde-for-admins.docbook | 2747 ++++++++++++++++++ doc/userguide/kde-office.docbook | 321 +++ doc/userguide/kmag.png | Bin 0 -> 24008 bytes doc/userguide/kmousetool.png | Bin 0 -> 30666 bytes doc/userguide/kmouth.png | Bin 0 -> 17835 bytes doc/userguide/kmouth2.png | Bin 0 -> 21497 bytes doc/userguide/kmouth3.png | Bin 0 -> 45978 bytes doc/userguide/knode-identity.png | Bin 0 -> 49777 bytes doc/userguide/knode-mail-account.png | Bin 0 -> 43215 bytes doc/userguide/knode-news-account.png | Bin 0 -> 25150 bytes doc/userguide/knode-start.png | Bin 0 -> 27701 bytes doc/userguide/konq-sidebar.png | Bin 0 -> 30404 bytes doc/userguide/konq-simple.png | Bin 0 -> 94848 bytes doc/userguide/konsole-intro.docbook | 126 + doc/userguide/kopete.png | Bin 0 -> 18060 bytes doc/userguide/kppp-dialer-tab.png | Bin 0 -> 13648 bytes doc/userguide/kppp-wizard.png | Bin 0 -> 22471 bytes doc/userguide/messaging-intro.docbook | 188 ++ doc/userguide/migrator-applications.docbook | 272 ++ doc/userguide/migrator-dictionary.docbook | 38 + doc/userguide/net-connection-setup.docbook | 238 ++ doc/userguide/networking-with-windows.docbook | 128 + doc/userguide/noatun-icon.png | Bin 0 -> 2767 bytes doc/userguide/noatun.png | Bin 0 -> 16375 bytes doc/userguide/oggfolder.png | Bin 0 -> 88475 bytes doc/userguide/open-file-dialog.png | Bin 0 -> 71366 bytes doc/userguide/panel-and-desktop.docbook | 325 +++ doc/userguide/pdf-files.docbook | 40 + doc/userguide/playing-audiocds.docbook | 142 + doc/userguide/playing-movies.docbook | 48 + doc/userguide/playing-music.docbook | 150 + doc/userguide/printer-setup.docbook | 47 + doc/userguide/printing-from-apps.docbook | 40 + doc/userguide/programs-and-documents.docbook | 565 ++++ doc/userguide/programs-controlling.docbook | 39 + doc/userguide/removable-disks.docbook | 140 + doc/userguide/rip.png | Bin 0 -> 20916 bytes doc/userguide/ripsettings.png | Bin 0 -> 52908 bytes doc/userguide/screen-captures.docbook | 38 + doc/userguide/services.png | Bin 0 -> 77067 bytes doc/userguide/shared-sessions.docbook | 46 + doc/userguide/splash-screen.png | Bin 0 -> 42044 bytes doc/userguide/standard-menu-entries.docbook | 319 +++ doc/userguide/switching-sessions.docbook | 92 + doc/userguide/the-filemanager.docbook | 291 ++ doc/userguide/titlebar-menu.png | Bin 0 -> 45043 bytes doc/userguide/troubleshooting-network-x.docbook | 41 + doc/userguide/troubleshooting-no-open.docbook | 49 + doc/userguide/under-the-hood.docbook | 521 ++++ doc/userguide/usenet.docbook | 251 ++ doc/userguide/where-next.docbook | 40 + doc/userguide/windows-how-to.docbook | 559 ++++ doc/userguide/your-kde-account.docbook | 79 + doc/visualdict/Makefile.am | 4 + doc/visualdict/index.docbook | 349 +++ doc/visualdict/pict1.png | Bin 0 -> 1170 bytes doc/visualdict/pict10.png | Bin 0 -> 2673 bytes doc/visualdict/pict11.png | Bin 0 -> 994 bytes doc/visualdict/pict12.png | Bin 0 -> 1525 bytes doc/visualdict/pict13.png | Bin 0 -> 3952 bytes doc/visualdict/pict14.png | Bin 0 -> 2950 bytes doc/visualdict/pict15.png | Bin 0 -> 523 bytes doc/visualdict/pict16.png | Bin 0 -> 9268 bytes doc/visualdict/pict17.png | Bin 0 -> 956 bytes doc/visualdict/pict18.png | Bin 0 -> 558 bytes doc/visualdict/pict19.png | Bin 0 -> 19326 bytes doc/visualdict/pict2.png | Bin 0 -> 926 bytes doc/visualdict/pict20.png | Bin 0 -> 1562 bytes doc/visualdict/pict21.png | Bin 0 -> 30371 bytes doc/visualdict/pict22.png | Bin 0 -> 1241 bytes doc/visualdict/pict23.png | Bin 0 -> 19677 bytes doc/visualdict/pict3.png | Bin 0 -> 10710 bytes doc/visualdict/pict4.png | Bin 0 -> 2493 bytes doc/visualdict/pict5.png | Bin 0 -> 4428 bytes doc/visualdict/pict6.png | Bin 0 -> 46304 bytes doc/visualdict/pict7.png | Bin 0 -> 5969 bytes doc/visualdict/pict8.png | Bin 0 -> 2178 bytes doc/visualdict/pict9.png | Bin 0 -> 5850 bytes 500 files changed, 67064 insertions(+) create mode 100644 doc/Makefile.am create mode 100644 doc/faq/Makefile.am create mode 100644 doc/faq/TODO create mode 100644 doc/faq/about.docbook create mode 100644 doc/faq/configkde.docbook create mode 100644 doc/faq/contrib.docbook create mode 100644 doc/faq/desktop.docbook create mode 100644 doc/faq/filemng.docbook create mode 100644 doc/faq/getkde.docbook create mode 100644 doc/faq/index.docbook create mode 100644 doc/faq/install.docbook create mode 100644 doc/faq/intro.docbook create mode 100644 doc/faq/kdeapps.docbook create mode 100644 doc/faq/misc.docbook create mode 100644 doc/faq/moreinfo.docbook create mode 100644 doc/faq/nonkdeapps.docbook create mode 100644 doc/faq/notrelated.docbook create mode 100644 doc/faq/panel.docbook create mode 100644 doc/faq/qt.docbook create mode 100644 doc/faq/questions.docbook create mode 100644 doc/faq/sound.docbook create mode 100644 doc/faq/tips.docbook create mode 100644 doc/faq/webbrowse.docbook create mode 100644 doc/faq/winmng.docbook create mode 100644 doc/glossary/Makefile.am create mode 100755 doc/glossary/checkxrefs create mode 100644 doc/glossary/index.docbook create mode 100644 doc/glossary/kdeprintingglossary.docbook create mode 100644 doc/kappfinder/Makefile.am create mode 100644 doc/kappfinder/man-kappfinder.1.docbook create mode 100644 doc/kate/Makefile.am create mode 100644 doc/kate/TODO create mode 100644 doc/kate/advanced.docbook create mode 100644 doc/kate/configdialog01.png create mode 100644 doc/kate/configdialog02.png create mode 100644 doc/kate/configuring.docbook create mode 100644 doc/kate/fundamentals.docbook create mode 100644 doc/kate/highlighted.png create mode 100644 doc/kate/highlighting.docbook create mode 100644 doc/kate/index.docbook create mode 100644 doc/kate/kate.png create mode 100644 doc/kate/man-kate.1.docbook create mode 100644 doc/kate/mdi.docbook create mode 100644 doc/kate/menus.docbook create mode 100644 doc/kate/mimetypechooser.png create mode 100644 doc/kate/part.docbook create mode 100644 doc/kate/plugins.docbook create mode 100644 doc/kate/regular-expressions.docbook create mode 100644 doc/kate/unhighlighted.png create mode 100644 doc/kcontrol/Makefile.am create mode 100644 doc/kcontrol/arts/Makefile.am create mode 100644 doc/kcontrol/arts/index.docbook create mode 100644 doc/kcontrol/arts/midi.docbook create mode 100644 doc/kcontrol/background/Makefile.am create mode 100644 doc/kcontrol/background/index.docbook create mode 100644 doc/kcontrol/bell/Makefile.am create mode 100644 doc/kcontrol/bell/index.docbook create mode 100644 doc/kcontrol/cache/Makefile.am create mode 100644 doc/kcontrol/cache/index.docbook create mode 100644 doc/kcontrol/clock/Makefile.am create mode 100644 doc/kcontrol/clock/index.docbook create mode 100644 doc/kcontrol/colors/Makefile.am create mode 100644 doc/kcontrol/colors/index.docbook create mode 100644 doc/kcontrol/cookies/Makefile.am create mode 100644 doc/kcontrol/cookies/index.docbook create mode 100644 doc/kcontrol/crypto/Makefile.am create mode 100644 doc/kcontrol/crypto/index.docbook create mode 100644 doc/kcontrol/desktop/Makefile.am create mode 100644 doc/kcontrol/desktop/index.docbook create mode 100644 doc/kcontrol/desktopbehavior/Makefile.am create mode 100644 doc/kcontrol/desktopbehavior/index.docbook create mode 100644 doc/kcontrol/ebrowsing/Makefile.am create mode 100644 doc/kcontrol/ebrowsing/index.docbook create mode 100644 doc/kcontrol/email/Makefile.am create mode 100644 doc/kcontrol/email/index.docbook create mode 100644 doc/kcontrol/energy/Makefile.am create mode 100644 doc/kcontrol/energy/index.docbook create mode 100644 doc/kcontrol/filemanager/Makefile.am create mode 100644 doc/kcontrol/filemanager/index.docbook create mode 100644 doc/kcontrol/filemanager/kfileman1.png create mode 100644 doc/kcontrol/filemanager/kfileman2.png create mode 100644 doc/kcontrol/filetypes/Makefile.am create mode 100644 doc/kcontrol/filetypes/index.docbook create mode 100644 doc/kcontrol/fonts/Makefile.am create mode 100644 doc/kcontrol/fonts/index.docbook create mode 100644 doc/kcontrol/helpindex/Makefile.am create mode 100644 doc/kcontrol/helpindex/index.docbook create mode 100644 doc/kcontrol/icons/Makefile.am create mode 100644 doc/kcontrol/icons/index.docbook create mode 100644 doc/kcontrol/index.docbook create mode 100644 doc/kcontrol/kcmaccess/Makefile.am create mode 100644 doc/kcontrol/kcmaccess/index.docbook create mode 100644 doc/kcontrol/kcmcss/Makefile.am create mode 100644 doc/kcontrol/kcmcss/index.docbook create mode 100644 doc/kcontrol/kcmfontinst/Makefile.am create mode 100644 doc/kcontrol/kcmfontinst/index.docbook create mode 100644 doc/kcontrol/kcmkonsole/Makefile.am create mode 100644 doc/kcontrol/kcmkonsole/index.docbook create mode 100644 doc/kcontrol/kcmlaunch/Makefile.am create mode 100644 doc/kcontrol/kcmlaunch/index.docbook create mode 100644 doc/kcontrol/kcmnotify/Makefile.am create mode 100644 doc/kcontrol/kcmnotify/index.docbook create mode 100644 doc/kcontrol/kcmsmserver/Makefile.am create mode 100644 doc/kcontrol/kcmsmserver/index.docbook create mode 100644 doc/kcontrol/kcmstyle/Makefile.am create mode 100644 doc/kcontrol/kcmstyle/index.docbook create mode 100644 doc/kcontrol/kcmtaskbar/Makefile.am create mode 100644 doc/kcontrol/kcmtaskbar/index.docbook create mode 100644 doc/kcontrol/kdm/Makefile.am create mode 100644 doc/kcontrol/kdm/index.docbook create mode 100644 doc/kcontrol/keyboard/Makefile.am create mode 100644 doc/kcontrol/keyboard/index.docbook create mode 100644 doc/kcontrol/keys/Makefile.am create mode 100644 doc/kcontrol/keys/index.docbook create mode 100644 doc/kcontrol/khtml/Makefile.am create mode 100644 doc/kcontrol/khtml/index.docbook create mode 100644 doc/kcontrol/khtml/nsplugin.docbook create mode 100644 doc/kcontrol/kwindecoration/Makefile.am create mode 100644 doc/kcontrol/kwindecoration/index.docbook create mode 100644 doc/kcontrol/language/Makefile.am create mode 100644 doc/kcontrol/language/index.docbook create mode 100644 doc/kcontrol/mouse/Makefile.am create mode 100644 doc/kcontrol/mouse/index.docbook create mode 100644 doc/kcontrol/netpref/Makefile.am create mode 100644 doc/kcontrol/netpref/index.docbook create mode 100644 doc/kcontrol/panel/Makefile.am create mode 100644 doc/kcontrol/panel/index.docbook create mode 100644 doc/kcontrol/panelappearance/Makefile.am create mode 100644 doc/kcontrol/panelappearance/index.docbook create mode 100644 doc/kcontrol/passwords/Makefile.am create mode 100644 doc/kcontrol/passwords/index.docbook create mode 100644 doc/kcontrol/performance/Makefile.am create mode 100644 doc/kcontrol/performance/index.docbook create mode 100644 doc/kcontrol/proxy/Makefile.am create mode 100644 doc/kcontrol/proxy/index.docbook create mode 100644 doc/kcontrol/proxy/socks.docbook create mode 100644 doc/kcontrol/screensaver/Makefile.am create mode 100644 doc/kcontrol/screensaver/index.docbook create mode 100644 doc/kcontrol/screenshot.png create mode 100644 doc/kcontrol/smb/Makefile.am create mode 100644 doc/kcontrol/smb/index.docbook create mode 100644 doc/kcontrol/spellchecking/Makefile.am create mode 100644 doc/kcontrol/spellchecking/index.docbook create mode 100644 doc/kcontrol/useragent/Makefile.am create mode 100644 doc/kcontrol/useragent/index.docbook create mode 100644 doc/kcontrol/windowmanagement/Makefile.am create mode 100644 doc/kcontrol/windowmanagement/index.docbook create mode 100644 doc/kdcop/Makefile.am create mode 100644 doc/kdcop/index.docbook create mode 100644 doc/kdebugdialog/Makefile.am create mode 100644 doc/kdebugdialog/index.docbook create mode 100644 doc/kdeprint/Makefile.am create mode 100644 doc/kdeprint/add-printer-wiz.docbook create mode 100644 doc/kdeprint/cr32-action-wizard.png create mode 100644 doc/kdeprint/cups-config.docbook create mode 100644 doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png create mode 100644 doc/kdeprint/cupsaddprinterwizard1.png create mode 100644 doc/kdeprint/cupsaddprinterwizard2_backendselection.png create mode 100644 doc/kdeprint/cupsaddprinterwizard3_networkscan.png create mode 100644 doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png create mode 100644 doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png create mode 100644 doc/kdeprint/cupsoptions.docbook create mode 100644 doc/kdeprint/cupsserverconfig_browse_relay_add_button.png create mode 100644 doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png create mode 100644 doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png create mode 100644 doc/kdeprint/cupsserverconfiguration11_browsingconnections.png create mode 100644 doc/kdeprint/cupsserverconfiguration11_browsingmasks.png create mode 100644 doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png create mode 100644 doc/kdeprint/cupsserverconfiguration14_browsingrelay.png create mode 100644 doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png create mode 100644 doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png create mode 100644 doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png create mode 100644 doc/kdeprint/cupsserverconfiguration1_welcome.png create mode 100644 doc/kdeprint/cupsserverconfiguration2_general.png create mode 100644 doc/kdeprint/cupsserverconfiguration3_logging.png create mode 100644 doc/kdeprint/cupsserverconfiguration4_directories.png create mode 100644 doc/kdeprint/cupsserverconfiguration5_HTTP.png create mode 100644 doc/kdeprint/cupsserverconfiguration6_encryption.png create mode 100644 doc/kdeprint/cupsserverconfiguration7_miscellanious.png create mode 100644 doc/kdeprint/cupsserverconfiguration8_networkgeneral.png create mode 100644 doc/kdeprint/cupsserverconfiguration9_networkclients.png create mode 100644 doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png create mode 100644 doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png create mode 100644 doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png create mode 100644 doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png create mode 100644 doc/kdeprint/cupsserverconfiguration_securityoverview.png create mode 100644 doc/kdeprint/extensions.docbook create mode 100644 doc/kdeprint/external-command.docbook create mode 100644 doc/kdeprint/final-word.docbook create mode 100644 doc/kdeprint/getting-started.docbook create mode 100644 doc/kdeprint/highlights.docbook create mode 100644 doc/kdeprint/index.docbook create mode 100644 doc/kdeprint/kcontrol-icon.png create mode 100644 doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png create mode 100644 doc/kdeprint/kcron_to_be_printed.png create mode 100644 doc/kdeprint/kdeprint-jobviewer.png create mode 100644 doc/kdeprint/kprinter-as-netscape-printcommand.png create mode 100644 doc/kdeprint/kprinter-kivio.png create mode 100644 doc/kdeprint/kprinter.png create mode 100644 doc/kdeprint/kprinter_called_from_run_command.png create mode 100644 doc/kdeprint/kprinter_with_kcron_developer_special.png create mode 100644 doc/kdeprint/lpd.docbook create mode 100644 doc/kdeprint/lpr-bsd.docbook create mode 100644 doc/kdeprint/lprng.docbook create mode 100644 doc/kdeprint/ps-boxes.png create mode 100644 doc/kdeprint/rlpr.docbook create mode 100644 doc/kdeprint/steinbruch_scaled.png create mode 100644 doc/kdeprint/tech-overview.docbook create mode 100644 doc/kdeprint/theory.docbook create mode 100644 doc/kdesu/Makefile.am create mode 100644 doc/kdesu/index.docbook create mode 100644 doc/kdesu/man-kdesu.1.docbook create mode 100644 doc/kdm/Makefile.am create mode 100644 doc/kdm/index.docbook create mode 100644 doc/kdm/kdmrc-ref.docbook create mode 100644 doc/kfind/Makefile.am create mode 100644 doc/kfind/index.docbook create mode 100644 doc/kfind/man-kfind.1.docbook create mode 100644 doc/khelpcenter/Makefile.am create mode 100644 doc/khelpcenter/background.png create mode 100644 doc/khelpcenter/bgtable.png create mode 100644 doc/khelpcenter/contact.docbook create mode 100644 doc/khelpcenter/help.docbook create mode 100644 doc/khelpcenter/index.docbook create mode 100644 doc/khelpcenter/kdelogo2.png create mode 100644 doc/khelpcenter/khelpcenter.png create mode 100644 doc/khelpcenter/konq.css create mode 100644 doc/khelpcenter/lines.png create mode 100644 doc/khelpcenter/lines2.png create mode 100644 doc/khelpcenter/pointers.png create mode 100644 doc/khelpcenter/shadow1.png create mode 100644 doc/khelpcenter/support.docbook create mode 100644 doc/khelpcenter/welcome.docbook create mode 100644 doc/khelpcenter/whatiskde.docbook create mode 100644 doc/kicker/Makefile.am create mode 100644 doc/kicker/bookmarks_icon.png create mode 100644 doc/kicker/desktop_icon.png create mode 100644 doc/kicker/index.docbook create mode 100644 doc/kicker/k_menu_icon.png create mode 100644 doc/kicker/man-appletproxy.1.docbook create mode 100644 doc/kicker/man-kicker.1.docbook create mode 100644 doc/kicker/printsys_icon.png create mode 100644 doc/kicker/quickbrowser_icon.png create mode 100644 doc/kicker/recent_docs_icon.png create mode 100644 doc/kicker/screenshot_left.png create mode 100644 doc/kicker/screenshot_right.png create mode 100644 doc/kicker/taskbar_group.png create mode 100644 doc/kicker/terminals_icon.png create mode 100644 doc/kicker/windowlist_icon.png create mode 100644 doc/kinfocenter/Makefile.am create mode 100644 doc/kinfocenter/cdinfo/Makefile.am create mode 100644 doc/kinfocenter/cdinfo/index.docbook create mode 100644 doc/kinfocenter/devices/Makefile.am create mode 100644 doc/kinfocenter/devices/index.docbook create mode 100644 doc/kinfocenter/dma/Makefile.am create mode 100644 doc/kinfocenter/dma/index.docbook create mode 100644 doc/kinfocenter/index.docbook create mode 100644 doc/kinfocenter/interrupts/Makefile.am create mode 100644 doc/kinfocenter/interrupts/index.docbook create mode 100644 doc/kinfocenter/ioports/Makefile.am create mode 100644 doc/kinfocenter/ioports/index.docbook create mode 100644 doc/kinfocenter/memory/Makefile.am create mode 100644 doc/kinfocenter/memory/index.docbook create mode 100644 doc/kinfocenter/nics/Makefile.am create mode 100644 doc/kinfocenter/nics/index.docbook create mode 100644 doc/kinfocenter/opengl/Makefile.am create mode 100644 doc/kinfocenter/opengl/index.docbook create mode 100644 doc/kinfocenter/partitions/Makefile.am create mode 100644 doc/kinfocenter/partitions/index.docbook create mode 100644 doc/kinfocenter/pci/Makefile.am create mode 100644 doc/kinfocenter/pci/index.docbook create mode 100644 doc/kinfocenter/pcmcia/Makefile.am create mode 100644 doc/kinfocenter/pcmcia/index.docbook create mode 100644 doc/kinfocenter/processor/Makefile.am create mode 100644 doc/kinfocenter/processor/index.docbook create mode 100644 doc/kinfocenter/protocols/Makefile.am create mode 100644 doc/kinfocenter/protocols/index.docbook create mode 100644 doc/kinfocenter/samba/Makefile.am create mode 100644 doc/kinfocenter/samba/index.docbook create mode 100644 doc/kinfocenter/scsi/Makefile.am create mode 100644 doc/kinfocenter/scsi/index.docbook create mode 100644 doc/kinfocenter/sound/Makefile.am create mode 100644 doc/kinfocenter/sound/index.docbook create mode 100644 doc/kinfocenter/usb/Makefile.am create mode 100644 doc/kinfocenter/usb/index.docbook create mode 100644 doc/kinfocenter/xserver/Makefile.am create mode 100644 doc/kinfocenter/xserver/index.docbook create mode 100644 doc/kioslave/Makefile.am create mode 100644 doc/kioslave/bzip.docbook create mode 100644 doc/kioslave/bzip2.docbook create mode 100644 doc/kioslave/cgi.docbook create mode 100644 doc/kioslave/data.docbook create mode 100644 doc/kioslave/file.docbook create mode 100644 doc/kioslave/finger.docbook create mode 100644 doc/kioslave/fish.docbook create mode 100644 doc/kioslave/floppy.docbook create mode 100644 doc/kioslave/ftp.docbook create mode 100644 doc/kioslave/gopher.docbook create mode 100644 doc/kioslave/gzip.docbook create mode 100644 doc/kioslave/help.docbook create mode 100644 doc/kioslave/http.docbook create mode 100644 doc/kioslave/https.docbook create mode 100644 doc/kioslave/imap.docbook create mode 100644 doc/kioslave/imaps.docbook create mode 100644 doc/kioslave/index.docbook create mode 100644 doc/kioslave/info.docbook create mode 100644 doc/kioslave/lan.docbook create mode 100644 doc/kioslave/ldap.docbook create mode 100644 doc/kioslave/mac.docbook create mode 100644 doc/kioslave/mailto.docbook create mode 100644 doc/kioslave/man.docbook create mode 100644 doc/kioslave/mrml.docbook create mode 100644 doc/kioslave/news.docbook create mode 100644 doc/kioslave/nfs.docbook create mode 100644 doc/kioslave/nntp.docbook create mode 100644 doc/kioslave/pop3.docbook create mode 100644 doc/kioslave/pop3s.docbook create mode 100644 doc/kioslave/print.docbook create mode 100644 doc/kioslave/rlan.docbook create mode 100644 doc/kioslave/rlogin.docbook create mode 100644 doc/kioslave/sftp.docbook create mode 100644 doc/kioslave/smb.docbook create mode 100644 doc/kioslave/smtp.docbook create mode 100644 doc/kioslave/tar.docbook create mode 100644 doc/kioslave/telnet.docbook create mode 100644 doc/kioslave/thumbnail.docbook create mode 100644 doc/kioslave/webdav.docbook create mode 100644 doc/kioslave/webdavs.docbook create mode 100644 doc/klipper/Makefile.am create mode 100644 doc/klipper/index.docbook create mode 100644 doc/klipper/screenshot.png create mode 100644 doc/kmenuedit/Makefile.am create mode 100644 doc/kmenuedit/done.png create mode 100644 doc/kmenuedit/index.docbook create mode 100644 doc/kmenuedit/itemname.png create mode 100644 doc/kmenuedit/kmenueditmain.png create mode 100644 doc/kmenuedit/new.png create mode 100644 doc/kmenuedit/selecticon.png create mode 100644 doc/kmenuedit/selectinternet.png create mode 100644 doc/knetattach/Makefile.am create mode 100644 doc/knetattach/index.docbook create mode 100644 doc/knetattach/screenshot.png create mode 100644 doc/knetattach/screenshot1.png create mode 100644 doc/knetattach/screenshot2.png create mode 100644 doc/knetattach/screenshot3.png create mode 100644 doc/knetattach/screenshot4.png create mode 100644 doc/kompmgr/Makefile.am create mode 100644 doc/kompmgr/index.docbook create mode 100644 doc/konqueror/Makefile.am create mode 100644 doc/konqueror/basics.docbook create mode 100644 doc/konqueror/bookmarks.docbook create mode 100644 doc/konqueror/browser.docbook create mode 100644 doc/konqueror/cmndline.png create mode 100644 doc/konqueror/commands.docbook create mode 100644 doc/konqueror/config.docbook create mode 100644 doc/konqueror/credits.docbook create mode 100644 doc/konqueror/dirtree.png create mode 100644 doc/konqueror/dragdrop.png create mode 100644 doc/konqueror/faq.docbook create mode 100644 doc/konqueror/filemanager.docbook create mode 100644 doc/konqueror/index.docbook create mode 100644 doc/konqueror/introduction.docbook create mode 100644 doc/konqueror/konqorg.png create mode 100644 doc/konqueror/man-kbookmarkmerger.1.docbook create mode 100644 doc/konqueror/parts.png create mode 100644 doc/konqueror/path-complete.docbook create mode 100644 doc/konqueror/plugins.docbook create mode 100644 doc/konqueror/save-settings.docbook create mode 100644 doc/konqueror/shortcut1.png create mode 100644 doc/konqueror/shortcut2.png create mode 100644 doc/konqueror/sidebar.docbook create mode 100644 doc/konsole/Makefile.am create mode 100644 doc/konsole/index.docbook create mode 100644 doc/konsole/konsole.png create mode 100644 doc/konsole/tabbar.png create mode 100644 doc/kpager/Makefile.am create mode 100644 doc/kpager/index.docbook create mode 100644 doc/kpager/screenshot.png create mode 100644 doc/kpager/settings.png create mode 100644 doc/ksplashml/Makefile.am create mode 100644 doc/ksplashml/index.docbook create mode 100644 doc/ksysguard/Makefile.am create mode 100644 doc/ksysguard/index.docbook create mode 100644 doc/kwrite/Makefile.am create mode 100644 doc/kwrite/index.docbook create mode 100644 doc/kxkb/Makefile.am create mode 100644 doc/kxkb/index.docbook create mode 100644 doc/kxkb/layout.png create mode 100644 doc/kxkb/switching.png create mode 100644 doc/kxkb/xkb.png create mode 100644 doc/quickstart/Makefile.am create mode 100644 doc/quickstart/index.docbook create mode 100644 doc/userguide/Makefile.am create mode 100644 doc/userguide/a-window.png create mode 100644 doc/userguide/accessibility.docbook create mode 100644 doc/userguide/amarok-icon.png create mode 100644 doc/userguide/amarok.png create mode 100644 doc/userguide/base-kde-applications.docbook create mode 100644 doc/userguide/browser-fine-tuning.docbook create mode 100644 doc/userguide/burning-cds.docbook create mode 100644 doc/userguide/control-center.docbook create mode 100644 doc/userguide/creating-graphics.docbook create mode 100644 doc/userguide/credits-and-license.docbook create mode 100644 doc/userguide/customizing-desktop.docbook create mode 100644 doc/userguide/desktop.png create mode 100644 doc/userguide/email.docbook create mode 100644 doc/userguide/extragear-applications.docbook create mode 100644 doc/userguide/file-sharing.docbook create mode 100644 doc/userguide/font-installation.docbook create mode 100644 doc/userguide/getting-help.docbook create mode 100644 doc/userguide/glossary.docbook create mode 100644 doc/userguide/groupware-kontact.docbook create mode 100644 doc/userguide/index.docbook create mode 100644 doc/userguide/internet-shortcuts.docbook create mode 100644 doc/userguide/juk-icon.png create mode 100644 doc/userguide/juk.png create mode 100644 doc/userguide/kaboodle-icon.png create mode 100644 doc/userguide/kaboodle.png create mode 100644 doc/userguide/kcalc-systray.png create mode 100644 doc/userguide/kcontrol.png create mode 100644 doc/userguide/kde-as-root.docbook create mode 100644 doc/userguide/kde-edutainment.docbook create mode 100644 doc/userguide/kde-for-admins.docbook create mode 100644 doc/userguide/kde-office.docbook create mode 100644 doc/userguide/kmag.png create mode 100644 doc/userguide/kmousetool.png create mode 100644 doc/userguide/kmouth.png create mode 100644 doc/userguide/kmouth2.png create mode 100644 doc/userguide/kmouth3.png create mode 100644 doc/userguide/knode-identity.png create mode 100644 doc/userguide/knode-mail-account.png create mode 100644 doc/userguide/knode-news-account.png create mode 100644 doc/userguide/knode-start.png create mode 100644 doc/userguide/konq-sidebar.png create mode 100644 doc/userguide/konq-simple.png create mode 100644 doc/userguide/konsole-intro.docbook create mode 100644 doc/userguide/kopete.png create mode 100644 doc/userguide/kppp-dialer-tab.png create mode 100644 doc/userguide/kppp-wizard.png create mode 100644 doc/userguide/messaging-intro.docbook create mode 100644 doc/userguide/migrator-applications.docbook create mode 100644 doc/userguide/migrator-dictionary.docbook create mode 100644 doc/userguide/net-connection-setup.docbook create mode 100644 doc/userguide/networking-with-windows.docbook create mode 100644 doc/userguide/noatun-icon.png create mode 100644 doc/userguide/noatun.png create mode 100644 doc/userguide/oggfolder.png create mode 100644 doc/userguide/open-file-dialog.png create mode 100644 doc/userguide/panel-and-desktop.docbook create mode 100644 doc/userguide/pdf-files.docbook create mode 100644 doc/userguide/playing-audiocds.docbook create mode 100644 doc/userguide/playing-movies.docbook create mode 100644 doc/userguide/playing-music.docbook create mode 100644 doc/userguide/printer-setup.docbook create mode 100644 doc/userguide/printing-from-apps.docbook create mode 100644 doc/userguide/programs-and-documents.docbook create mode 100644 doc/userguide/programs-controlling.docbook create mode 100644 doc/userguide/removable-disks.docbook create mode 100644 doc/userguide/rip.png create mode 100644 doc/userguide/ripsettings.png create mode 100644 doc/userguide/screen-captures.docbook create mode 100644 doc/userguide/services.png create mode 100644 doc/userguide/shared-sessions.docbook create mode 100644 doc/userguide/splash-screen.png create mode 100644 doc/userguide/standard-menu-entries.docbook create mode 100644 doc/userguide/switching-sessions.docbook create mode 100644 doc/userguide/the-filemanager.docbook create mode 100644 doc/userguide/titlebar-menu.png create mode 100644 doc/userguide/troubleshooting-network-x.docbook create mode 100644 doc/userguide/troubleshooting-no-open.docbook create mode 100644 doc/userguide/under-the-hood.docbook create mode 100644 doc/userguide/usenet.docbook create mode 100644 doc/userguide/where-next.docbook create mode 100644 doc/userguide/windows-how-to.docbook create mode 100644 doc/userguide/your-kde-account.docbook create mode 100644 doc/visualdict/Makefile.am create mode 100644 doc/visualdict/index.docbook create mode 100644 doc/visualdict/pict1.png create mode 100644 doc/visualdict/pict10.png create mode 100644 doc/visualdict/pict11.png create mode 100644 doc/visualdict/pict12.png create mode 100644 doc/visualdict/pict13.png create mode 100644 doc/visualdict/pict14.png create mode 100644 doc/visualdict/pict15.png create mode 100644 doc/visualdict/pict16.png create mode 100644 doc/visualdict/pict17.png create mode 100644 doc/visualdict/pict18.png create mode 100644 doc/visualdict/pict19.png create mode 100644 doc/visualdict/pict2.png create mode 100644 doc/visualdict/pict20.png create mode 100644 doc/visualdict/pict21.png create mode 100644 doc/visualdict/pict22.png create mode 100644 doc/visualdict/pict23.png create mode 100644 doc/visualdict/pict3.png create mode 100644 doc/visualdict/pict4.png create mode 100644 doc/visualdict/pict5.png create mode 100644 doc/visualdict/pict6.png create mode 100644 doc/visualdict/pict7.png create mode 100644 doc/visualdict/pict8.png create mode 100644 doc/visualdict/pict9.png (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000..6812bd2d1 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +SUBDIRS = $(AUTODIRS) + diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am new file mode 100644 index 000000000..9c7a6607a --- /dev/null +++ b/doc/faq/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/faq + diff --git a/doc/faq/TODO b/doc/faq/TODO new file mode 100644 index 000000000..42a37ca29 --- /dev/null +++ b/doc/faq/TODO @@ -0,0 +1,35 @@ +TODO: + +- Cull any questions that are specific to KDE =< 3.4 +- Look into reorganising sections to make finding things much easier. + + + +I'm keeping this in here for the amusement factor. Every time I look at it I rememeber that while I'm not a very good FAQ maintainer, physos wasn't much better ;) + +Last modified by physos 2002-12-27 + +Before 3.2 release +_________________________________________________ + +- Split up the monolith docbook (done) +- Get rid of 1.1.2 stuff (confusion) +- check if things are still working + * compile tutorials for the various OS's + * workarounds still needed? + * workarounds still working? + * answers are still valid? + * easier solutions? +- complete revision ? +- New structure ? +- Find maintiners for single parts +- what needs to be added ? + +[22:15:47] 1: move the faq (and other kdebase docs) up to kdebase/doc/ +so that docs.kde.org will pick them up and generate them +[22:16:05] then remove the copies on www.kde.org, put in redirects to the new +location, and have one, autogenerated and searchable copy all the time +[22:16:17] sounds nice +[22:16:24] will look into it + + diff --git a/doc/faq/about.docbook b/doc/faq/about.docbook new file mode 100644 index 000000000..89c7b6033 --- /dev/null +++ b/doc/faq/about.docbook @@ -0,0 +1,72 @@ + + + +About this <acronym>FAQ</acronym> + + + + +What can I do to help out with this FAQ? + + + + +First, send us any errors that you may find. Also, any +suggestions that you might have, are appreciated. Better yet, send us +everything that you think is unclear, and if possible, send us what +you think would be a clearer solution. The email address of the current maintainer is jhall@kde.org. + + +Second, send us your solutions of those frequently-asked +questions which are still not in this FAQ. We will +put them in as soon as possible. + +Last but not least, please make full use of this +FAQ. Read this FAQ (and other +relevant documentation) well before asking questions on the various +&kde; mailing lists or newsgroups. + + You might also want to consider becoming a +FAQ maintainer. Please refer to for more details. + + + + + + +How do I become a FAQ maintainer? + + + +Actually, it is very easy to become an FAQ +maintainer, and we are always in need of fresh blood. :-) Just send +us an email at kde-doc-english@kde.org. + + + + + + + + diff --git a/doc/faq/configkde.docbook b/doc/faq/configkde.docbook new file mode 100644 index 000000000..f0cb4d2be --- /dev/null +++ b/doc/faq/configkde.docbook @@ -0,0 +1,250 @@ + + +Configuring &kde; + + + + +How do I set the language used by &kde;? + + + +There are two ways to set the language &kde; uses in the +messages it will display: + + +Using the &kde; Control Center +Fire up the &kde; Control Center and select +Regional & Accessibility followed by +Country/Region & Language. You can select your language and location +here. If &kde; cannot find a translation in the first language +chosen, it will fall back on the default language. This is usually +(American) English by default. +Using the &kde; Control Center is the preferred way of choosing +languages in &kde;. + +Using the LANG environment variable +The second method uses the standard locale setting on +your system. To change the language, simply set the environment +variable LANG accordingly. For example, if your shell +is bash, execute +export LANG=de +to set German as the language used. + + + + + + + +Is there any keyboard switcher for international keyboards for +&kde;? + + + +Yes, you can configure it using the &kde; Control Center +Regional & Accessibility +Keyboard Layout + configuration page. + + + + + + +How do I replace the standard text login screen with the +&kde; login screen? + + +Your distribution/&UNIX; flavor may have its own setup tools to +change this (⪚ YaST on &SuSE; &Linux;). This will +be the safest way to enable the &kde; login screen. However, if for some reason +you do not wish to use these tools, the following instructions may be useful. +First, you need to change to the xdm runlevel (runlevel 5 on +&RedHat; and &SuSE; systems) by editing your +/etc/inittab file. In the file, you should have +a line saying id:3:initdefault:. Change it to +id:5:initdefault:. Now, at the end of the file, +comment out the following line: +x:5:respawn:/usr/bin/X11/xdm -nodaemon and +replace it with +x:5:respawn:/opt/kde/bin/kdm +-nodaemon. +The location of &kdm; may differ on your +system. +For changes to take effect immediately, type init +5 (for &RedHat; systems) at the shell prompt. +It is risky to initiate a graphical login without +checking beforehand whether it works. If it fails to work, you would +be in for a hard time getting back.... + + + +For FreeBSD, you should edit the file /etc/ttys +and change one of the lines that look like +ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure +to instead say ttyv8 "/usr/local/bin/kdm -nodaemon" xterm +off secure. + + + + + + +I would like to click the &LMB; anywhere on the +desktop and have the K menu displayed. + + +Open the &kde; Control Center and +choose Desktop +Behavior. You +can now choose the behavior of mouse clicks on the desktop. To have +the K menu open from a single &LMB; click, change +the entry labeled Left button to say +Application Menu. + + + + + +Where do I find information regarding &kde; themes? + + +Go to http://kde.themes.org/ or http://www.kde-look.org. + + + + + +How do I change &MIME; Types? + + +If you are using &konqueror;, do this instead: first, open a +&konqueror; window and choose +SettingsConfigure +Konqueror, then File Associations. Find the type you want to change +(⪚ text/english or +image/gif), and set the application preference order +to whatever you want. + + + + + +&kde; (&kdm;) does not read my +.bash_profile! + + +The login managersxdm and &kdm; do +not run a login shell, so .profile, +.bash_profile, &etc; are not +sourced. When the user logs in, xdm runs +Xstartup as root and then +Xsession as user. So the normal practice is to add +statements in Xsession to source the user +profile. Please edit your Xsession and +.xsession files. + + + + + +How do I use &TrueType; fonts in &kde;? + + + +You need to install &TrueType; font support into your &X-Window; configuration. +Please take a look at x.themes.org for the fonts, and +xfsft: +&TrueType; Font Support For X11 or X-&TrueType; Server Project Home +Page for the font servers. + +If you have a bunch of &TrueType; fonts from &Microsoft; +&Windows;, edit the XF86Config file to get the +fonts from the font folder. Then just tell &kde; to use these new +fonts with the font administrator utility. + + + + + + +Is it possible to enter, show and work with the Euro Symbol in +&kde;? + + +Yes and no. For details, look here: http://www.koffice.org/kword/euro.php. + + + + +How do I run a program at &kde; startup? + +There are many ways to do that. If what you want to do +is to run some scripts that would set some environment variables (for +example, to start gpg-agent, ssh-agent and others), you can put +these scripts into $KDEHOME/env/ and make sure their names end in +.sh. $KDEHOME is +usually a folder named .kde +(note the period at the beginning) in your home +folder. If you want scripts to be executed for all &kde; users, you can +put them under $KDEDIR/env/, where $KDEDIR is the prefix &kde; was +installed to (you can find this out using the command +kde-config --prefix). +If you wish to start a program after &kde; has started, you may want to use the +Autostart folder. To add +entries to the Autostart folder: + +Open &konqueror;. + +Select GoAutostart + from the menubar. + +Right-click in the window view area and select Create NewFileLink to +Application + + +Click on the Application tab in +the window that appears and enter the name of the command to run in +the Command text box. + + + + + + + + + +How can I allow more than one user to be logged in a at a time? Can &kde; do fast user switching? + + + +To enable more than one user to log in at one time on the same +computer (sometimes referred to as fast user switching) you +need to tell the program that logs you in that it can use more than one +session (or, in &X-Window; terms, display) at a time. + +In &kde;, this program is called &kdm; which stands for &kde; +Display Manager. If you are not using &kdm; as your login screen +then you will need to consult the documentation for the software you are using on how to +accomplish multiple sessions. + +By default, this will be configured at installation time automatically +if &kdm; supports virtual terminals on your system (currently Linux only). +If it was not configured automatically, consult the &kdm; manual, section +Specifying permanent &X-Server;s. +After modifying kdmrc, you will have to let &kdm; know about it; just +invoke killall -HUP kdm. + + + + diff --git a/doc/faq/contrib.docbook b/doc/faq/contrib.docbook new file mode 100644 index 000000000..807050ba7 --- /dev/null +++ b/doc/faq/contrib.docbook @@ -0,0 +1,164 @@ + + + + +Contributing + + + + +How can I contribute to &kde;? + + +&kde; is a free software project that lives from voluntary +contributions. Everybody is encouraged to contribute to &kde;. Not +only programmers are welcome. There are many ways in which you can +help to improve &kde;: + +Test the software. +Send in bug reports. For more information on this, +see How do I submit a bug +report?. +Write documentation or help files. You can get some +information by visiting the &kde; Editorial Team +Home Page. +Translate programs, documentation, and help files. +For more information on this, you should visit The &kde; Translators' and Documenters' Web +Site. +Draw nice icons or compose sound effects. You can +visit the &kde; +artists page to find out more. +Write articles and books about &kde;. If you want to +help spread the word about &kde;, simply send an email to +kde-pr@kde.org. This will get you in touch +with the &kde; public relations volunteers. +Program new &kde; applications. Please refer to for more information. + Of course, sponsors are also +welcome. :-) + +There are several places to look for more information if you +want to get involved in the development. The first step is to +subscribe to some of the mailing +lists. You will soon see something +that can be improved or added. + + + + + +How do I submit a bug report? + + +There is a bug tracking system available at http://bugs.kde.org. The +system features a wizard to submit new bug reports and a +list of all known bugs. +The easiest way to submit a bug is to select +HelpReport +Bug... from the menu bar of the application +with the bug. This will open a small dialog box with a link +to the bug tracking system. Please make sure to follow the +instructions of the bug reporting wizard. + + + + + +I want to program for &kde;. What should I do first? + + +Everybody is encouraged to develop software for &kde;. What you +should do first depends strongly on your experience, ⪚ whether you have +already learned C++ or have experience with the &Qt; toolkit and so +on. +To get into &kde; programming, you will need some basic tools: +automake, +autoconf, and +egcs. You should look to http://developer.kde.org/ +for more tips. +Another excellent resource for learning &kde; +programming is the &Qt; +online tutorials. These are installed along with &Qt;. To view them, +open $QTDIR/doc/html/index.html in +&konqueror; and bookmark it. The tutorials +can be found under "Using +Qt". The source code for each lesson can be found in the $QTDIR/tutorial +directory. +There is, however, one thing that everybody interested in +programming for &kde; should do: subscribe to the developers +mailing list. To subscribe, you have to send an email to +kde-devel-request@kde.org +with the subject subscribe +your_email_address. +Please read How to +subscribe/unsubscribe to these lists carefully. Everything +said there applies to the development list as +well. + + + + + +How do I get access to &kde; SVN? + + +The &kde; project uses SVN to develop the +core parts of the software. Usually, when you have changed one of the +parts (⪚ fixed a bug), and you want to commit this change, the best +way is to create a patch against a current snapshot and send this +patch to the developer/maintainer of the respective program. +If you are doing this more or less regularly, there are instructions here on how to get write access to the SVN repository: +http://developer.kde.org/documentation/other/developer-faq.html#q1.8. But be aware that more users will slow +down SVN access for all developers, so we want to +keep the number of people with direct SVN access +reasonably small. But feel free to ask! + + + + + +Can I have read-only access to the SVN repository? + + +Yes. Instructions on how to get anonymous, read-only SVN access are here: +http://developer.kde.org/source/anonsvn.html + + + + + + +Are there any SVN mirror sites for &kde;? + + +No, there are currently no anonymous SVN mirror sites for &kde;. If you're interested in setting one up, please contact sysadmin@kde.org + + + + + + +How do I go about translating &kde; programs into my native +language? + + +Look at the The &kde; +Translators' and Documenters' Web Site to see whether your +program is already translated (most are). Otherwise you will find +information there on how to do it yourself. + + + + + + diff --git a/doc/faq/desktop.docbook b/doc/faq/desktop.docbook new file mode 100644 index 000000000..da3de1608 --- /dev/null +++ b/doc/faq/desktop.docbook @@ -0,0 +1,97 @@ + + + +The desktop + + + + +How do I add an application to the desktop? + + + +Just choose the desired application from the K menu and drag and drop it to the Desktop. + +For applications not listed in the K menu, +use the &RMB; on the desktop and choose Create NewFile +Link to Application... and fill in the configuration for the application you want to link to. + + + + + + + +How do I mount/unmount a device from the desktop? + + + +First, make sure you are allowed to mount/umount the relevant device as a user. + +Then you can add any device via &RMB; on the desktop and then choosing Create NewLink to Device and then selecting the device of the type you wish to control from the desktop. Fill in the settings for the device in the dialog that appears and click OK. You can use the resulting desktop icon to mount/unmount the device from the desktop. + + + + + + + + +Where are the icons kept? + + +The icons can be found only in $KDEDIRS/share/icons or $HOME/.kde/share/icons or +$HOME/.kde2/share/icons. To use icons +stored in other locations, you must either copy them into one of the +above-mentioned fixed &kde; locations or make symlinks. + + + + + +How do I use the mouse scroll wheel in &kde;? + + +Mouse wheel support comes with &Qt; 2.0 and above, so &kde; based on +that will automatically support the use of the mouse scroll wheel if your system is configured correctly. Check your &X-Server; settings support the use of a scrollwheel if it is not working. + + + + + +How do I launch applications in a particular desktop? + + +&kde; comes with a program called &kstart;. +To start an xterm on the second desktop and then activate it use: + +kstart xterm. +Note that the option is important. It takes an +argument which is a regular expression matching the title of the window to +apply the settings to. +Please read kstart for more magic +available with &kstart; (and there is an abundance). + + + + + + +Where do I save my files if I want them to appear directly on +the desktop? + + +$HOME/Desktop. You might +need to refresh your desktop after you have saved your files. + + + + diff --git a/doc/faq/filemng.docbook b/doc/faq/filemng.docbook new file mode 100644 index 000000000..bfe6d1e98 --- /dev/null +++ b/doc/faq/filemng.docbook @@ -0,0 +1,207 @@ + + + +The File Manager + +&kde;'s file manager is &konqueror;. The +&konqueror; home page is located at http://www.konqueror.org where a +&konqueror; specific FAQ can be found. + + + + + + +How can I change the appearance of a folder in +&konqueror;? + + +Right-click the folder, select Properties, +click on the large icon in the dialog which appears, and choose another +icon. To change the icon displayed for entries in the +K Menu, use the Menu Editor, +located at SettingsMenu +Editor. + + + + + + +How can I do non-anonymous &FTP; transfers with &konqueror;? + + +Normally, if you enter a &URL; like +ftp://ftp.somehost.com, +&konqueror; will attempt an anonymous login to the &FTP; server. If you +want to login as a particular user, enter a &URL; like +ftp://username@ftp.somehost.com +instead. &konqueror; will ask for your password and connect to the +server. + + + + + + +How do I specify the startup folder for &konqueror;? + + + +Using the &RMB;, click on the Home icon and choose +Properties. Under the +Application tab you will probably find something like +kfmclient openProfile filemanagement; just append +file:/whereever/you/want with the +folder you would like &konqueror; to start in. + + + + + + +How do I rename files? + + +Simply right click on the file and select +Rename or press the keyboard shortcut F2 with a file selected. + + + + + +Where did the delete entry from my right-click context menu go? + + +In &kde; 3.4 the delete context menu entries that bypass the +trashcan are no longer displayed by default. To enable them, go to +SettingsConfigure +&konqueror; and select +Behaviour in the iconbar to the left. Tick the checkbox +Show 'Delete' context menu entries which bypass the +trashcan. + + + + + +How do I configure the programs that &konqueror; uses to +open different types of files? + +In order to configure file associations, you should go to the +&kcontrolcenter; and choose the item File +Associations under the category KDE +Components. + +Suppose the default PDF viewer is now &kghostview; and +you would prefer to use KPDF as a viewer. You +would simply type pdf in the search box at the top of +the dialog, choose pdf in the +application group and move +KPDF up. In the Embedding +tab you can also choose which component other applications will use to +display files (for example, when viewing files in &konqueror; or using +&ark;'s embedded viewer). + + + + + +When I try to click on a folder in &konqueror;, I get the +message: There appears to be a configuration error. You have +associated Konqueror with inode/directory, but it cannot handle this file +type. + + +You need to make sure that the embedding settings for inode/directory +are correct: + +In &konqueror;, go to +SettingsConfigure +Konqueror and then to the File +Associations page. Open +inode->directory in the tree view. Click on +the +Embedding tab. Make sure that Left Click +Action is set to Show file in embedded +viewer, and by default Icon View (konq_iconview) +is at the top +of Services Preference Order. + + + + + + What are and + in the Execute line? +They are used by all &kde; applications (since they are implemented in +KApplication and all good &kde; programs create a +KApplication object before they even look at the +command line arguments). A standard line for a &kde; +application looks like this: foo +. Pretty confusing, +-but it has been designed in that way so that it can integrate legacy, +non-&kde; applications as smoothly as possible. &konqueror;, when executing +the line above, will extend the command to +foo . Both the icon and the mini-icon as well as "The +Foo" are properties defined in the .desktop file. If +the icons are not defined, they simply default to the executable name +foo. + +This way a user can change these things in &kmenuedit; for his or her +applications. The option is important, because no +user will accept that the menu item Editor starts +something called kedit-0.9pl4-build47. Instead, he +expects a window called Editor. Furthermore these +names are localized, i.e. an American user launches +CD-Player and gets a window called +CD-Player while a German user launches +CD-Spieler and gets a window called +CD-Spieler. + + + + + +How do I make &konqueror; start up without a menu bar? +I can't save a view profile when the menu bar is invisible! + + +The easiest way to do this is to edit &konqueror;'s +configuration file manually. Add the following lines to +~/.kde/share/config/konquerorrc: + +[KonqMainWindow] +MenuBar=Disabled + + + +On restarting &konqueror;, the menubar should be hidden. + + + + + + + + diff --git a/doc/faq/getkde.docbook b/doc/faq/getkde.docbook new file mode 100644 index 000000000..ceabb2561 --- /dev/null +++ b/doc/faq/getkde.docbook @@ -0,0 +1,79 @@ + + + +Getting &kde; + + + + +Where do I get &kde;? + + + +The easiest way to get &kde; is to install a &Linux; distribution or another UNIX-like OS that ships with &kde;. +You can find an up-to-date list of distributions that ship +with &kde; here. For alternative methods of +trying &kde; that do not require you to be running &Linux;, please see +Try &kde; + +The main distribution site for &kde; is +ftp.kde.org. However, this site is +often under heavy load, so you might prefer to use +download.kde.org which automatically +redirects you to the mirror nearest to you. +You can also have a look at the list of &kde; mirror sites. + + + + + +What is the current version? + + + +Currently, the latest stable version is 3.5.5 + +The &kde; 3.5.5 Info +Page contains a lot of information specific to this +release. + + + + + +Where do I find &kde; snapshots? + + +You can get the latest snapshots from ftp://ftp.kde.org/pub/kde/unstable/snapshots. +You might also want to consider setting up your own SVN client in order to +maintain the latest snapshot at all times. Please refer to Anonymous SVN and &kde; for further +information. + + + + + + + +Where do I get &Qt;? + + +&Qt; is a product of the Norwegian company Trolltech. You can +always get the latest &Qt; version from their +&FTP; server. + +And with most up-to-date &Linux; distributions, &Qt; is already +included. Please see for the version +of &Qt; you need. + + + + + + diff --git a/doc/faq/index.docbook b/doc/faq/index.docbook new file mode 100644 index 000000000..f114e3993 --- /dev/null +++ b/doc/faq/index.docbook @@ -0,0 +1,136 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + + +&kde; Frequently Asked Questions + + + +The &kde; Team + + + + + + +1997 +1998 +1999 +2000 +2001 +2003 +2004 +2005 +The &kde; Team + + +&FDLNotice; + +2005-01-19 +3.4 + + This is a compilation of the most frequently asked +questions about the K Desktop Environment. Please report any bugs, +inconsistencies, or omissions you find in this &FAQ; to +kde-doc-english@kde.org. Please do not mail your questions +to this list. Post them to the &kde; mailing lists and newsgroups +instead. They are monitored for this &FAQ;. + + +KDE +FAQ +question +answer + + + +&faq-about; +&faq-intro; +&faq-getkde; +&faq-install; +&faq-panel; +&faq-desktop; +&faq-winmng; +&faq-filemng; +&faq-webbrowse; +&faq-configkde; +&faq-kdeapps; +&faq-sound; +&faq-nonkdeapps; +&faq-tips; +&faq-misc; +&faq-qt; +&faq-moreinfo; +&faq-questions; +&faq-contrib; + + +Credits and License + +The current &FAQ; maintainers are: + + +J Hall +jes.hall@kdemail.net + + +Many of the answers in this &FAQ; are taken +from the various &kde; mailing lists and newsgroups. Here is a +big thank you to all of you who have contributed +answers that eventually appear in this &FAQ;. + +Special thanks go to the former &FAQ; +maintainers, Rainer Endres and Mr. Lee Wee Tiong + + + + +&underFDL; + + +&documentation.index; + + + diff --git a/doc/faq/install.docbook b/doc/faq/install.docbook new file mode 100644 index 000000000..6ab33ef78 --- /dev/null +++ b/doc/faq/install.docbook @@ -0,0 +1,726 @@ + + + +Installation instructions + +These are the generic installation instructions for the K +Desktop Environment. Please complement your reading with the +READMEs and INSTALLs that +come along with the package. Please read them carefully and try to +help yourself out if anything goes wrong. If you need further +assistance, consider joining the &kde; mailing lists +(see our web site instructions for joining the &kde; +mailing +lists) or newsgroups. + + + + + + + +To the would-be converts + + + +So you have heard the rumors. Or you have seen the screenshots. +And you are dying to get hold of &kde;. But you know next to nothing +about this whole alternative OS business. Don't worry! +You only need to do some (well, maybe not some) reading, that's +all! + +&kde; does not run on any version of &Microsoft; &Windows; or OS/2 (yet). To run +&kde;, you need to have a &UNIX; system. Please refer to for more details. + +Decide on a platform and set it up for your system. This +FAQ can not help you with this, since &kde; runs on many &UNIX; platforms. + + + +Finally, you are ready to commence the &kde; installation. +Please start reading from the next section. To get &kde;, please +refer to . Last but not least, if +you encounter any problems while installing &kde;, please do not +hesitate to make use of the &kde; mailing lists and newsgroups. But do bear this in mind: no +question is too silly to ask, but some are too silly to answer, +especially when they are already answered in this FAQ. +Good luck and have fun! + + + + + + +What kind of hardware do I need to run &kde; ? + + +To run &kde; it is recommended that you have at least a pentium II processor, 64MB of memory and 500MB of free disk space for a basic installation. While &kde; may run on slower configurations than this, performance can be severely impaired. Generally, if your computer runs an &X-Server; already with other desktop environments or window managers it's probably fast enough to run &kde;. + + + + + +Available package formats + + + + +You can find several kinds of binary and source packages for +different distributions and operating systems on the &kde-ftp;. The +binary packages are not made by the &kde; Team, but by the +distributors themselves, or some dedicated individuals. Please refer to +&kde; Package Policy +Explained for information about the &kde; Package Policy. The +only official release is the source tar.bz2 +packages. Please refer to the READMEs and +INSTALLs in the several binaries folders. For +a list of the available packages for a release, refer to the relevant +info page. For the latest release this is the &kde; 3.4.1 Info +Page. + + + + + + +Prerequisites + + + + + +For &kde; 3.4.1, you need the &Qt; library version 3.3 or greater. +Please make sure you download the correct &Qt;. You will +also need the header files, if you want to compile &kde; +yourself. They are all available, at no cost, from http://www.trolltech.com/download. +In addition, there are optional libraries that might improve &kde; if +installed on your system. An example is OpenSSL which will enable +&konqueror; to browse web pages securely and is needed in a version +>=0.9.6. These should be provided by your distributor; if not, ask +for an update. + + + + + + +Description of the base packages + + +The base distribution currently consists of twenty +packages. Some are required, while others are optional. Each package +is available in each of the aforementioned package formats. + + +kdelibs + +Required +This package contains shared libraries that are needed by all +&kde; applications. + + + +kdebase + +Required +This package contains the base applications that form the core +of the K Desktop Environment like the window manager, the terminal +emulator, the control center, the file manager, and the panel. + + + +&arts; + +Required +The &arts; sound server. A powerful, network transparent sound +server. + + + +kdeaddons + +Optional +Various plugins for &kate;, &kicker;, &knewsticker;, &konqueror; and &noatun; + + + +kdeartwork + +Optional +Additional wallpapers, themes, styles, sounds ... + + + +kdebindings + +Optional +Various bindings for other languages, including &Java;, Perl, Python, ... + + + +kdegames + +Optional +Various games like &kmahjongg;, &ksnake;, &kasteroids;, and +&kpatience;. + + + +kdegraphics + +Optional +Various graphics-related programs like &PostScript; previewer, +&DVI; previewer, and a drawing program. + + + +kdeutils + +Optional +Various desktop tools like a calculator, an editor and other +nifty stuff. + + + +kdemultimedia + +Optional +Multimedia applications like a &CD; player and a mixer. + + + +kdenetwork + +Optional +Network applications. Currently contains the instant messaging client &kopete;, the +download manager &kget;, and several other network-related programs. + + + +kdepim + +Optional +Personal information management tools. Contains the email client &kmail;, the newsreader &knode; and other related programs. + + + +kdeadmin + +Optional +System administration programs. + + + +kdeedu + +Optional + +Educational and entertaining applications for &kde;'s younger users. + + + + +kdeaccessibility + +Optional + +KDE accessibility programs such as a screen magnifier and speech synthesizer front end. + + + + +kdetoys + +Optional +Toys! + + + +kdevelop + +Optional +A complete Integrated Development Environment for &kde; and Qt + + + +kdewebdev + +Optional +Web development applications. Contains such applications as &quanta;, an integrated web development environment and other applications useful in web development + + + +kdesdk + +Optional +KDE Software Development Kit. Contains a collection of applications and tools used by KDE Developers. + + + + +&arts; and then kdelibs should be installed before everything +else, and kdeaddons last. The other packages can be installed in any +arbitrary order. + +Most package management tools will let you put all these +packages in one folder and install them all at once, figuring out +the dependencies as they go. + + + + + + +Installation instructions for the different package +formats + + + +Please do not forget to read the README and INSTALL files if they are available. + + + +Installation of the Debian packages + +The Debian packages install in accordance with the upcoming FHS (File +Hierarchy Standard). + +become superuser +run dpkg for +every package you want to install. + + + + +Installation of the RPM packages + + +To install binary <acronym>RPM</acronym>s +become superuser +execute rpm + + + + +Installation of the source .tar.bz2 files + +Since there are always changes and updates to the way &kde; is compiled, please +refer to Download and Install from Source for the most up to date installation instructions for the source packages. + +The general approach should work in most cases though. + +The source .tar.bz2 package installs into /usr/local/kde by default. You can +override this setting by using the option of +the configure script. + +unpack the packages with tar +change folder to the package folder: cd +packagename +configure the package: ./configure +Some packages (notably kdebase) have special configuration +options that might be applicable to your installation. Type +./configure to see the +available options. +build the package: make +install the package: su (if you aren't already root). If you +already are, just type make +. + + + + + + + + + +Post-installation procedures + + +First of all, please make sure that you have added &kde;'s binary +installation folder (⪚ /usr/local/kde/bin) to your PATH +and &kde;'s +library installation folder to your LD_LIBRARY_PATH (only +necessary on systems that do not support rpath; on &Linux; &ELF;, it +should work without). This environment variable may be called +differently on some systems, ⪚ it is called +SHLIB_PATH on &IRIX;. Then set the environment variable +KDEDIR to the base of your &kde; tree, ⪚ /usr/local/kde. + +Please bear in mind that it is unwise to set +LD_LIBRARY_PATH blindly. In the vast majority of cases it is +unnecessary and can do more harm than good. There is a web page +written by Dave +Barr explaining the evils of LD_LIBRARY_PATH and it can be +found at http://www.cis.ohio-state.edu/~barr/ldpath.html. + + +Even though you can use most of the &kde; applications simply by +calling them, you can only benefit fully from &kde;'s advanced +features if you use the &kde; window manager and its helper +programs. +In order to make it easy for you, we have provided a simple +script called startkde which gets installed in $KDEDIR/bin and is therefore in your +path. +Edit the file .xinitrc in your home folder (make a backup +copy first!), remove everything that looks like calling a window +manager, and insert startkde instead. Restart the &X-Server;. If you use +&kdm;/xdm, you will have to edit the file .xsession instead of +.xinitrc. And if there is no .xinitrc or .xsession in your home +folder, simply create a new one with just one line containing +startkde. + +Some systems (notably &RedHat; &Linux;) use .Xclients +instead. + +This should present you with a new shining &kde; desktop. You +can now start to explore the wonderful world of &kde;. In case you +want to read some documentation first, there is a highly recommended +Quick Start +guide available. Furthermore, every application has an online +help that is available via the help menu. + + + + + + +Should I remove old version xyz before installing a new +one? + + +In principle, this is not necessary. RPM and Debian packages +should take care of all dependencies. +If you compile the source code yourself, you should take more care. +Instructions for running two different versions of &kde; on the same system are +given at http://developer.kde.org/build/kde2-and-kde3.html. +However, please note that running two different versions of &kde; from source +can lead to problems if you are not careful. + + + + + +How do I start &kde;? + + +The most comfortable method to start &kde; is to use the +startkde script. Simply put the line +startkde at the end of your .xsession +file (or your .xinitrc or .Xclients +file if you are not using &kdm; or xdm). Please +also remove the lines that start your previous window manager. If there is no +.xsession, .xinitrc, or +.Xclients in your home folder, simply create a new one +that contains just one line: startkde. + + + + + +Is it possible to install &kde; in my home directory? + + +Yes, you can install &kde; in any folder you want. What you +have to do depends on the kind of packages you want to install: +Source packages +Configure and install the package using configure +; +make; make install to install into /home/me. Replace /home/me with your home directory, generally defined in $HOME +Add the following to your init files. Please note that if +it is not necessary for you to set LD_LIBRARY_PATH, it +is better to leave it out. + +For csh or tcsh: + +setenv KDEDIR /home/me + +if ( $?LD_LIBRARY_PATH ) then + setenv LD_LIBRARY_PATH $KDEDIR/lib:$LD_LIBRARY_PATH +else + setenv LD_LIBRARY_PATH $KDEDIR/lib +endif + +if ( ! $?LIBRARY_PATH ) then + setenv LIBRARY_PATH $LD_LIBRARY_PATH +endif + +For bash: + +KDEDIR=/home/me +PATH=$KDEDIR/bin:$PATH +LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH +LIBRARY_PATH=$LD_LIBRARY_PATH +export KDEDIR PATH LD_LIBRARY_PATH LIBRARY_PATH + + +<acronym>RPM</acronym> packages +rpm allows you to use the + option to select the folder you want to +install to. For example, executing rpm will install the package +to /home/me. + + +Although &kde; will run from a user folder, there are some +problems with programs that require suid root, ⪚ the programs in +the kdeadmin package. But since they are not meant to be run by users +in the first place, this is nothing to worry about. +However, on systems using shadow passwords, the screensavers +have to be suid root to enable password access for unlocking the +screen, so this option will not work. + + + + + + +startkde fails with can not connect to X +server. What is wrong? + + +You probably tried to start the X server with startkde. The X +server is started with startx. +startkde is the +script that should be run from your .xinitrc, .xsession, or +.Xclients to activate the window manager and the necessary server +daemons for &kde;. See also . + + + + + +&kde; on &AIX;? + + + + +IBM now officially support &kde; on &AIX;. You can find +details at http://www.ibm.com/servers/aix/products/aixos/linux/index.html. +There is also some older information at http://space.twc.de/~stefan/kde/aix.html. + + + + + +&kde; on a laptop? + + +If you can get &X-Window; to run on your laptop, you should not have any problem +getting &kde; to run on it. In addition, you might find the following +links helpful: + + +http://www.linux-laptop.net/ + + +http://www.sanpei.org/Laptop-X/note-list.html + + + + + + + +I do not like the default &kde; folder after installation. How +do I move it without breaking anything? + + +Assuming the default is /opt/kde and you want to move it to +/usr/local/kde, here's what +you have to do: + +change to superuser if you aren't already +mv /opt/kde /usr/local/kde +ln -s /usr/local/kde +/opt/kde + +This will put all your &kde; files in /usr/local/kde but everything is +still accessible from /opt/kde. + + + + + +What files can I delete from my &kde; install folder? Can all the +*.h, *.c and *.o +files be safely removed? + + +There should not be any need to keep the .c and +.o files, but you might want to keep the +.h files, as they are used by includes if you ever want to +compile your own &kde; programs. But if you wish to add patches to the source +programs as they become available (rather than downloading everything again), +then they should stay. + + + + + +Will I lose my current settings when I upgrade &kde;? + + + +No. In most cases &kde; will be able to transport your settings +intact. You may need to reenter passwords in some applications (such +as &kmail; or &knode;) but most other settings will be safe. + +There were mixed reports of results between some previous +versions of &kde;. To be safe, you may like to back up your entire +&kde; configuration. + +Settings are kept in the $HOME/.kde or $HOME/.kde2 subfolder in your home +folder. Copy your +old .kde/.kde2 folder to a backup location, +install &kde; 3.2, and then copy back any necessary mail and news +settings. That said, most people can make a direct upgrade, without +removing the old .kde folder, + without a hitch. +You can override the use of $HOME/.kde by setting the +$KDEHOME variable. + + + + + +I upgraded &kde; and it seemed to go fine, but when I start it, +I get a blank gray screen, and nothing happens. There are errors in +the console about DCOPserver. What's going on? + + + + +&kde; uses several temporary files during its operation. +These are usually to be found in the following locations: + +~/.DCOPserver-* (there are usually two of these; one is a symlink to the other) +~/.kde/socket-hostname +~/.kde/tmp-hostname which is normally a symlink to the next file: +/tmp/tmp-kde-USER +~/.kde/socket-hostname which is also normally a symlink to: +/tmp/ksocket-USER + + +If the symlinks get broken, usually because a +cron or shutdown script is emptying out the +/tmp folder, then strange +things will happen. These files, and the symlinks, will all be +created automatically at the start of &kde; so you can safely remove +them while &kde; is not running. + +If you are only getting a gray screen when you start &kde;, or if you get an error message telling you to Check your installation, then shut down X and delete all the files listed above, then try to restart X. + +Normally (&ie; when not upgrading between &kde; versions) it's +quite safe to leave these files intact, and you may shave a few +seconds off your &kde; startup time by doing so. + + + + + +Compiling kdebase gives me a bin/sh: msgfmt: command +not found error! + + +You need the &GNU; msgfmt which is +part of the &GNU; i18n package gettext. +You should be able to download it from any +&GNU; mirror. + + + + + +How do I uninstall &kde; applications compiled from +source? + + +You can uninstall your programs by typing make +uninstall in the folder where you did make +install. If you have already deleted that folder, +then there is only one way, and it is not good: go to $KDEDIR/bin and start deleting files +one by one. +If you expect to find yourself in this situation, you might want to +consider a program such as &GNU; stow, found at +http://www.gnu.org/software/stow/stow.html. + + + + + +What is up with &GIF; support? + + +This has to do with issues with Unisys' &LZW; patent. &GIF; +support is turned off from &Qt; 1.44 onwards by default. When you want to use +&GIF;s and have the relevant license, recompile &Qt; with &GIF; support. +./configure . + + + + diff --git a/doc/faq/intro.docbook b/doc/faq/intro.docbook new file mode 100644 index 000000000..6f9546791 --- /dev/null +++ b/doc/faq/intro.docbook @@ -0,0 +1,93 @@ + + + +Introduction + + + + +What is &kde;? + + +&kde; is the K Desktop Environment. It is a project initiated +by Matthias Ettrich in +1996. The aim of the &kde; project is to connect the +power of the &UNIX; operating systems with the comfort of a modern user +interface. +In short, &kde; will bring &UNIX; to the desktop! +If you want further information about &kde;, have a look at +What is +&kde;? + + + + + +On which platforms can I expect &kde; to work? + + +&kde; is a Desktop Environment for all flavors of &UNIX;. While +it is true that most &kde; developers use &Linux;, &kde; runs smoothly +on a wide range of systems. You may, however, need to tweak the +source code a bit to get &kde; to compile on a not-so-popular variant +of &UNIX;, or if you are not using the &GNU; development tools, in +particular the &gcc; compiler. + + + + + +Is &kde; a window manager? + + +No, &kde; is not a window manager. While &kde; includes a very +sophisticated window manager (&kwin;), &kde; is much more than that. +It is a full-blown Integrated Desktop Environment. +&kde; provides a complete desktop environment, including a web +browser, a file manager, a window manager, a help system, a +configuration system, uncountable tools and utilities, and an ever +increasing number of applications, including but not limited to mail +and news clients, drawing programs, a &PostScript; and a &DVI; viewer +and so forth. + + + + + +Is &kde; a CDE, &Windows; or &Mac; +OS clone? + + +No, &kde; is not a clone. Specifically &kde; is not a +CDE or &Windows; clone. While the &kde; developers +have and will continue to glean the best features from all existing +desktop environments, &kde; is a truly unique environment that has and +will continue to go its own way. + + + + + +Is &kde; free software? + + +Yes, &kde; is free software according to the &GNU; General +Public License. All &kde; libraries are available under the +LGPL making commercial software development for the +&kde; desktop possible, but all &kde; applications are licensed under +the GPL. +&kde; uses the &Qt; C++ crossplatform +toolkit, which is also released (since version 2.2) under the +GPL. +It is absolutely legal to make &kde; and &Qt; available on +&CD-ROM; free of charge. No runtime fees of any kind are +incurred. + + + + + diff --git a/doc/faq/kdeapps.docbook b/doc/faq/kdeapps.docbook new file mode 100644 index 000000000..95ff1355b --- /dev/null +++ b/doc/faq/kdeapps.docbook @@ -0,0 +1,158 @@ + + + +&kde; applications + + + + +&kppp; + + + +Many &kde; users report problems using &kppp;. But before you +complain about &kppp;, make sure you have already checked the +following: + + +Can you dialup to your ISP without using &kppp;? If you cannot, then perhaps &kppp; is not the culprit after +all. +Have you gone through the &kppp; documentation at +least three times and followed its instructions and trouble-shooting +suggestions? + +The &kppp; documentation can be accessed through the +&kde; Help Center. + Last, but not least, the &kppp; homepage is at http://ktown.kde.org/~kppp/. +Now, if you still encounter problems, here's what might help you +solve them: + +How do I change the &MTU; setting in &kppp;? +Open up the &kppp; dialog box and select +Setup. Choose an existing account and click +Edit, or New to create a +new dialup account. Select the Dial tab and +click Arguments. Type what you want to change +in the Argument textbox (⪚ mtu 296) and +click Add. When you are satisfied, click +Close. +To check whether the options took, do one of the following: + + +In a terminal window, run +/sbin/ifconfig ppp0 and look +at the reported &MTU; in the output. It should match your +request. + +Add and +(each on a separate line) to your +/etc/ppp/options file and restart your +&PPP; session. You will find debugging messages in +/var/log/messages, including &MRU; and &MTU; +settings. + +If you want, the &MRU; and &MTU; settings can be added to the +options file, one complete setting per line, no +quotes or dashes. + + +&kppp; connects at a slower speed than +normal. +The following might do the trick: + +Try executing setserial +spd_hi. +The default &MTU; value is 1500, +which maybe too large +for a dialup connection. Try changing it to a smaller value like +296 +or 576. +Check in your $HOME/.kde/share/config for the +kppprc. Ensure the correct modem speed is +actually defined there. + + + + + + + + +&konsole; + + + + + +How do I page-up or page-down? +Use +ShiftPage Up +and ShiftPg +Dn. + + + + +How do I perform a simple copy from &konsole; to +anything else? +When I do a ls, first I select with +the mouse the desired text, press +&Ctrl;C, +then I make the target application active, point the mouse to the +relevant part and press &Ctrl;V. +Alternatively, highlight the text by dragging with the &LMB; down and +paste by clicking with the &MMB; (or both buttons if you are using a +2 button mouse with 3 button emulation). + + + + +Why can't &konsole; find the 9x15 and the 2 +console bitmap fonts installed with &kde;? + + +FontConfig must find the three fonts +installed in: $KDEDIR/share/fonts. + If +the &kde; install does not install these fonts in a directory that +already exists (⪚ /usr/share/fonts) then you must add this +directory to the configuration file /etc/fonts/local.conf. This should be +the first line after <fontconfig>. For example: + +<fontconfig> +<dir>/usr/kde3/share/fonts</dir> +</fontconfig> + +After adding the directory, run (as root): +fc-cache -v and check that +it found the directory. + + + + + + + + + +&kmail; + + +&kmail; has its own home page at http://kmail.kde.org where an +FAQ is available. + + + + + diff --git a/doc/faq/misc.docbook b/doc/faq/misc.docbook new file mode 100644 index 000000000..61d2950f3 --- /dev/null +++ b/doc/faq/misc.docbook @@ -0,0 +1,219 @@ + + + +Miscellaneous questions + + + + + + +Does &kde; support transparency and other visual effects provided by the new composite extension to X.org? + + + Yes! An exciting new feature for &kde; 3.4 is support for the new X composite extension. This allows for effects such as translucency and drop shadows for all windows, easily configurable through &kwin;'s configuration dialog. This requires you to be using X.org version 6.8.0 or newer and have: + + +Section "Extensions" +Option "Composite" "Enable" +EndSection + + +In your xorg.conf. If you have an nvidia graphics card and use the nvidia driver you can improve the performance of these effects by also adding the RenderAccel option to the Device section for your graphics card: + + +Section "Device" + Identifier "nvidia-fx5200" + Driver "nvidia" + Option "RenderAccel" "true" + +Once you have configured X.org correctly, transparency and other effects can be enabled through the DesktopWindow Behavior &kcontrolcenter; module, under the Translucency tab. + + + + + + +What about &kde; programs that do not have icons? How do I get +them into the menu? + + +Use &kmenuedit;. To access it use the &RMB; on the +K button and select Menu Editor. + + + + + +Does &kde; have a graphical &FTP; client? + + +Yes, and it is none other than your favorite file +manager, &konqueror;. You can drag and drop remote files into local +folders. + + + + + +How do I exit &kde;? + + +Simply click on the K button and select +Logout. In addition, if you +right click on an +empty area of the desktop, you will be presented with a menu +containing logout as one of the options. +Depending on your configuration of the &X-Window;, &Ctrl;&Alt;&Backspace; +might also do the trick by killing the X server, but its use prevents +session management and cannot be recommended. + + + + + +Is there a program that checks for new mails at my +ISP if and only if I am online? + + +&korn; will do the job. If you are not +connected, it will just sit there (idling). + + + + + +Is it really necessary to upgrade to the latest version? + + +We recommend to always use the latest stable release. If you +don't, it will probably be difficult to get answers to your +questions. If you have a problem with an old version, the answer will +probably be Please upgrade and try again. Note that +new versions also sometimes fix security problems. + + + + + +How do I copy and paste in &kde;? + + +The simplest method is to use your mouse: + +Highlight the text you want to copy by holding down the +&LMB; and dragging across the text. This adds the selected text to the clipboard. +Go to the destination area; depending on your configuration, +you might need to click it using the &LMB; to give it +focus. +Click the &MMB; to paste. If you have a two +button mouse and are emulating a three button mouse, push both buttons +simultaneously. + + +For more information about using the clipboard in &kde; please see the &klipper; hand book, accessed by typing help:/klipper +into the &konqueror; address bar. + + + + + + +How do I convert the default &RedHat; menus into a menu in the +K menu? + + +Click on the K button and select +SystemAppfinder. + + + + + +What is CVS? + + +It stands for Concurrent Versions System. It is a version +control system and is based on RCS (Revision +Control System), but +offers more functionality. It is used to maintain source code under +development. It will keep multiple versions of things (handy if you +broke something and have to back up and get a clean old version), and +allows people remote access over the Net to pick up the latest source +code and even to check in new files if they have permission. It is +also open source (you pay for support if you want it), and since it is +free it is the system of choice for people writing more free products, +such as &kde;. + + + + + +Does &kde; support dual screen (Xinerama)? + + +Yes, you need to have a multi-headed X server +(⪚ MetroX or XFree86 4.0 and above) and a &kde; >= 2.2.1 + + + + + + +Why does Drag and Drop not work with Xinerama? + + +You should upgrade to XFree86 4.2.0 for this to work properly. + + + + + + +How do I check which version of &kde; I am using? + + +Fire up your &kde; Control +Center. It comes up with an Info Screen including the version of &kde; +The &kde; version is also included in the application's +About dialog. + + + + + + + + +How do I go about creating themes and icons? + + +Go see http://artist.kde.org. +There is also a more informal community of &kde; related artists and +artwork at http://kde-look.org. + + + + + + + +How can I get to know about development updates? + + +You might want to subscribe to the various &kde; mailing lists +available, especially kde-cvs, which lists all commits done to the +&kde; CVS repository. Check http://lists.kde.org if you want to +read without subscribing. + + + + + diff --git a/doc/faq/moreinfo.docbook b/doc/faq/moreinfo.docbook new file mode 100644 index 000000000..9b28db3a2 --- /dev/null +++ b/doc/faq/moreinfo.docbook @@ -0,0 +1,154 @@ + + + +Getting more information + + + + +Where is the &kde; homepage? + + +The &kde; homepage is located at http://www.kde.org. If you prefer a +local mirror, there are several to choose from. For a current list of +web site mirrors sorted by location, please visit http://www.kde.org/mirrors/web.php. + + + + + +Is there a &kde; mailing list? + + +There are several &kde; mailing lists. Each focuses on a different +aspect of &kde;. Some are for developers, so they are not +discussed in detail. Some of the more important lists that users +might be interested in are: + +kde +This is the main &kde; mailing list for general +discussions. + +kde-announce +This list is used to announce new versions of &kde; as +well as new tools and applications. + +kde-look +This is the list that deals with questions about look and +feel, and general user interface considerations. + + +For the complete list of mailing lists available, please refer +to http://www.kde.org/mailinglists/. +Please note that it is not a good idea to ask questions which are +already answered in this &FAQ;. + + + + + +How do I subscribe/unsubscribe to these lists? + + +To subscribe, send an email to list-request, that is: + +kde-request@kde.org +kde-announce-request@kde.org +kde-look-request@kde.org + +The email must contain subscribe +your_email_address in the +subject. +To unsubscribe, send an email to list-request, that is: + +kde-request@kde.org +kde-announce-request@kde.org +kde-look-request@kde.org + +The email must contain unsubscribe +your_email_address in the +subject. +Never send subscribe/unsubscribe request to the +mailing lists directly! Use the list-request +instead. +There is also a complete list of all &kde;-related mailing +lists, and a web interface for subscribing and unsubscribing located +at http://master.kde.org/mailman/listinfo. + + + + + +Is there a mailing list archive? + + + +Yes, there is a searchable mailing list archive hosted by Progressive Computer +Concepts. The &URL; is http://lists.kde.org. There you +will see a folder listing of the mailing lists. Note that you can +only do a subject/author search at this level. You probably will not +find what you want doing this kind of search. + +To do a body search, you have to enter one of the mailing lists. +Just click on the folder you want to search (⪚ kde +or kde-devel) and then the pull-down menu by the search +box will default to Body searches. To be thorough, you +should probably search the kde, kde-linux, and kde-devel folders. + + + + + + +Is there a newsgroup about &kde;? + + +Yes, there is! It is at comp.windows.x.kde. +In addition, there is also a German newsgroup at +de.alt.comp.kde. Please note that it is not a good +idea to ask questions which are already answered in this +&FAQ;. + + + + + +Are there any other &kde;-related +&FAQ;s? + + +Yes. Here is a list of them: + +&kde; &FAQ; +&konqueror; +&FAQ; +aRts +sound server documentation + + + + + + + + + + + diff --git a/doc/faq/nonkdeapps.docbook b/doc/faq/nonkdeapps.docbook new file mode 100644 index 000000000..e0e732548 --- /dev/null +++ b/doc/faq/nonkdeapps.docbook @@ -0,0 +1,106 @@ + + + +&kde; with non-&kde; applications + + + + + + + +My non-&kde; applications like &Emacs; and +kterm are running amok with strange +colors! + + +Start the &kde; Control Center and in +Appearance & Themes +Colors uncheck the Apply colors to +non-KDE applications checkbox and click +Apply. + + + + +How can I set my default web browser to be something other +than &konqueror;? + +If you are using &kde; 3.3 or later, open up the &kcontrolcenter; and +navigate to the KDE +ComponentsComponent +Chooser panel. Select Web +Browser from the list on the left, then select Open +http and https URLs in the following browser: and type in the +name of the browser (⪚ mozilla, +firefox, opera, &etc;) +in the textbox. + + + + + +How can I configure the style and fonts of GTK +applications within &kde; ? + + + + +The simplest way to achieve this is to download and compile the +gtk-qt theme engine from +http://www.freedesktop.org/Software/gtk-qt. This theme engine makes +your GTK applications look like your &kde; widget style +by calling functions from &Qt; instead of drawing the styles itself. Once +the theme engine has been installed, there will be a &kcontrolcenter; module +under Appearance & ThemesGTK +Styles and Fonts. + + + + + + +I have been hearing about this gecko kpart or &Qt; Mozilla, how do I +get these? + + + +Good luck! The &Qt; Mozilla code is in Mozilla cvs, and not very stable as +of yet. In order to use it, you'll have to check out Mozilla from cvs +according to these instructions: + +http://www.mozilla.org/cvs.html. Then, configure either the Mozilla +suite or the Firefox browser with the option +--enable-default-toolkit=qt in addition to any other +options you would like to enable. More instructions on building Mozilla can +be found here. + + + + + + + + \ No newline at end of file diff --git a/doc/faq/notrelated.docbook b/doc/faq/notrelated.docbook new file mode 100644 index 000000000..fd66e1a6c --- /dev/null +++ b/doc/faq/notrelated.docbook @@ -0,0 +1,232 @@ + + + +Not really &kde;-related, but frequently asked nevertheless. + + + + +How do I change the screen resolution? + + +Use &Ctrl;&Alt;+ and &Ctrl;&Alt;- to cycle through +the resolutions you have defined in XF86Config (maybe under +/etc/X11; poke around first). +If you prefer to get your hands dirty, you can always edit the file +directly. By placing your favorite resolution at the beginning (or +making it the only one listed), &X-Window; will always start up with that +resolution. +Always make a backup copy of your XF86Config file +before you start editing it. Errors in this file +can render &X-Window; unusable. +These instructions are only valid if you are running +version 3.3.x of the XFree86 server. If you are running XFree86 4.x, +you must consult with the XFree86(TM): +Home Page. + + + + + +How do I change the color depth? + + +There is no way you can do this on the fly. You can either +start &X-Window; using startx where +number can be 8, 16, 24 or 32, depending on +the depth you want. Alternatively, if you are using +xdm/&kdm;, you +need to edit +/etc/X11/xdm/Xservers (may vary) and enter +:0 local /usr/X11R6/bin/X -bpp 16 for 16 bit color +depth. +You can also edit the XF86Config file and add a line +like DefaultColorDepth +number to Section "Screen". +The next time you start X, it will run with the newly-configured color +depth. + + + + + +What can I do if I am using a 2-button mouse? + + +Go buy a 3-button one, or use third button emulation. The third +button is emulated by pressing both the &LMB; and the &RMB; +together. You would need to enable +in your XF86Config file. + + + + + +What is a "sticky" window? + + +In a virtual desktop environment with multiple virtual desktops, a +"sticky" window will stay put on the screen when you switch between +desktops, as if sticking to the glass of the screen. +Xclock is a typical candidate for sticking, +as you need to run only one instance of it, and it always stays with +you. + + + + + +How do I replace the "X" mouse pointer with an arrow? + + +The various types of cursor available in X are defined in +X11/cursorfont.h. You can +change it using xsetroot -cursor_name +name_of_cursor. For example, I +have the following in my .Xclients: + +xsetroot -cursor_name left_ptr + +This will create the common left-angled pointer. To see other +alternatives, type xfd -fn cursor. And of course, +do not forget that man xsetroot is your +friend. + + + + + +How do I extract/install diff files? + + +To generate a context-diff suitable for patching, use +diff -u old-file new-file > +patchfile. To apply the diff to +a file (i.e. "patch the file"), execute +patch < patchfile. + + + + + +How do I get &Linux; to mount the floppy device for use with both +DOS and ext2 formatted floppies? + + +Just specify the filesystem type as auto in +/etc/fstab. Auto detection works fine for DOS and +ext2. + + + + + +How do I start &kde; with the Num Lock on? + + +Have you tried man setleds? In addition, you +might want to edit your +$HOME/.Xmodmap and put the +following lines in: + +! redefines numeric keypad to be used without NumLock +keycode 79 = 7 +keycode 80 = 8 +keycode 81 = 9 + +keycode 83 = 4 +keycode 84 = 5 +keycode 85 = 6 + +keycode 87 = 1 +keycode 88 = 2 +keycode 89 = 3 + +keycode 90 = 0 +keycode 91 = comma +keycode 86 = plus + +! deactivates NumLock key +keycode 77 = + +Other possible alternatives: + +xkeycaps: +right clicking should allow edits. You may +have to do this as root. +man XF86Config and look under +section Keyboard. +Install NumLockX, which is +available from http://dforce.sh.cvut.cz/~seli/en/numlockx. + + + + + + +How do I take window or desktop screenshots? + + +Use &ksnapshot;. + + + + + +Is there a tool to make webpages? + + +Yes, and there are a lot of them out there, including +StarOffice, &Netscape; Composer, and +XEmacs. +There are also many &kde; applications. To find the most current +list, go to kde-apps.org: The +Latest in &kde; Applications and search for web +development. Try as many as possible and choose the one +most suitable to your needs. + + + + + +What do all those acronyms like AFAIK mean? + + + +AAMOF: as a matter of fact +AFAIK: as far as I know +AISE: as I see it +BFN: bye for now +BION: believe it or not +BRB: be right back +BTW: by the way +CMIIW: correct me if I am wrong +FUD: fear, uncertainty, and doubt +FWIW: for what it's worth +FYI: for your information +HTH: hope this helps +IIRC: if I recall correctly +IMHO: in my humble opinion +LOL: laughing out loud +MYOB: mind your own business +PITA: pain in the ass +ROTFL: rolling on the floor laughing +RTFM: read the fine manual +SOP: standard operating procedure +TIA: thanks in advance +YMMV: your mileage may vary + + + + + diff --git a/doc/faq/panel.docbook b/doc/faq/panel.docbook new file mode 100644 index 000000000..5814dc613 --- /dev/null +++ b/doc/faq/panel.docbook @@ -0,0 +1,193 @@ + + + + +The panel + + + + + +How do I add applications to the &kde; panel (&kicker;)? + + +There are several ways to add an application to the panel, of +which the easiest is to right-click on the panel, and from the context +menu which appears, select Panel +MenuAdd to +PanelApplication +Button and then the application for which +you want to add a link. For more ways of adding buttons +to the panel, refer to the &kicker; Handbook. + + + + + + + +Is it possible to change the K button of +the panel to another picture? + + +The simplest way is to download a new icon theme with a &kmenu; icon +you prefer from +http://www.kde-look.org and +install it using the &kcontrolcenter;. +In order to change only the &kmenu; icon you can overwrite the +kmenu.png image for every size in an icon theme set. +So, for &kde; default icons this would be $KDEDIR/share/icons/default.kde/size/apps/kmenu.png, +where size is one of the sizes included in the +&kde; icon theme. + + + + + + + +After an upgrade my &kmenu; appears to be empty! How can I get my menu back? + + + + +In &kde; 3.2 and later local modifications to the &kmenu; are stored +in +$HOME/.config/menus/applications-kmenuedit.menu +. Try moving this file out of the way and then issuing the +command kbuildsycoca +. This should restore you to the +default system menus. + + + + + +My desktop panel has disappeared. How can I get it +back? + + + + +The panel disappearing is usually due to it crashing. This is +most often caused by loading an applet that has a fatal bug or due to +a bad installation of &kde; and/or the panel. + +The easiest way to get the panel back is to launch the +Run Command window by pressing &Alt;F2 and entering +kicker and then pressing the +OK button. + +If the panel continues to disappear, you may wish to either +remove or edit by hand your +$KDEHOME/share/config/kickerrc +file, where $KDEHOME is usually +~/.kde. If you choose to edit +it by hand, start by removing the applet entry groups. + + + + + +Where did the Icon Zooming option that used to be in &kicker; go? + + +Icon zooming was not actively maintained and had caused severe bugs and usability issues. It was replaced in &kde; 3.4 by the new mouse over effects, which combine esthetics with useful information. + + + + + +How can I start an application minimized to the system +tray? + + +Use ksystraycmd. For example, to start a &konsole; hidden +in the system tray, run ksystraycmd + konsole. For +more information about ksystraycmd, see the section +Advanced Window Management in the &kde; +User Guide. + + + + +How do I use the &Windows; key to open the &kmenu;? + + +Previous versions of &kde; provided a trick to allow you to +use the &Windows; key both as a modifier (so you could have shortcuts +like WinR +), and as a regular key (so that pressing +Win on its own could open the &kmenu;). This feature +was removed for reasons of usability and accessibility, as well as +keeping the code clean. For current versions of &kde;, you have two +options: either use a different shortcut to open the &kmenu; (the +default is &Alt;F1 +), or remap the Win key to be a regular +key, rather than a modifier. + +If you choose to do the second, here's one way: + + +Find the keycode for your Win key +using xev: Run the command +xev in a &konsole;, and +press the Win key. Look in the output of +xev for +keycode n, +where n is the keycode of the +Win key. + + +Use xmodmap to remap the +Win key. An appropriate command is xmodmap + 'keycode +n=Menu'. + + +In the &kcontrolcenter;, go to +Regional & +AccessibilityKeyboard Shortcuts + and set the shortcut for Popup Launch +Menu to the Win key. You should now be +able to popup the &kmenu; by pressing the Win key. + + +One more step is required to save the changes across +settings: Create a file ~/.kde/env/win-key.sh +(create the directory if it doesn't exist), and add the +xmodmap command you used previously to it. The +change should now be applied every time you start &kde;. + + + + + + + + + + diff --git a/doc/faq/qt.docbook b/doc/faq/qt.docbook new file mode 100644 index 000000000..446089edc --- /dev/null +++ b/doc/faq/qt.docbook @@ -0,0 +1,76 @@ + +&Qt; and Licensing questions + + + + + +What is &Qt;, by the way? + + +&Qt; is a C++-based class library to build user interfaces. It +also includes many utility classes like string classes and classes +to handle input and output. It +provides most of the widgets you will see in a &kde; application: +menus, buttons, sliders, &etc;. &Qt; is a cross-platform library that +allows you to write code that will compile on &UNIX; systems as well as +&Windows; and embedded devices. You can learn more about &Qt; at http://www.trolltech.com. + + + + + +Why does &kde; use &Qt;? + + +&Qt; is a very sophisticated toolkit that provides everything that +is needed to build a modern user interface. &Qt; is written in C++, thus +allowing object-oriented development which ensures efficiency and +code reuse in a project the size and scope of &kde;. In our opinion +there is no better toolkit available for &UNIX; systems and that it +would have been a grave mistake to try to build &kde; on anything but +the best. + + + + + +Why does &kde; not use gtk, xforms, xlib, whatever? + + +There are a number of toolkits available. To provide a +consistent user interface and to keep used resources such as memory to +a minimum, &kde; can use only one of them. &Qt; was selected for the +reasons mentioned above. + + + + + +But &Qt; isn't free, is it? + + +It is! As of September 4, 2000, version 2.2 of the &Qt; +libraries were licensed under the GPL, thereby +fulfiling all aspects of free software. + + + + + +Can I write commercial software for &kde;? + + +You can use the &kde; libraries to write commercial and +closed source as well as commercial and open +source software. If you write open source software you can +use the &Qt; free edition. But if you write closed source software +you may not use the &Qt; free edition; you need to obtain the &Qt; +professional edition from Troll Tech. If you want more +information, please contact Troll Tech directly. + + + + \ No newline at end of file diff --git a/doc/faq/questions.docbook b/doc/faq/questions.docbook new file mode 100644 index 000000000..1f7db6b63 --- /dev/null +++ b/doc/faq/questions.docbook @@ -0,0 +1,160 @@ + + + +Asking Questions + +Chances are, you have been linked to this document from IRC or a +mailing list. You've asked a question, and someone has told you that you +need how to ask more effectively. In order to get an appropriate, clear +answer you need to ask an appropriate, clear question in a manner that's +going to provide an incentive for people to take their time to help you. If +you appear to be rude, lazy or use bad or unclear language then chances are +your question will be ignored + + + + +What do I do before I ask? + +Read the documentation and &FAQ; for the application. There is +a wealth of &kde; documentation availible both in the help center and +online. A lot of time and effort has gone into this documentation, and +quite often the answer to your question is here. The general &kde; userguide +can be found by typing +help:/userguide into your +&konqueror; addressbar. + +Search the web: Usually googling for a specific error message or +searching mailing list archives can come up with a solution for you. + +Try it and see! Look through all the application options, read the +What's this? and tooltips for the ones you're not sure about. If you're +really unsure about an option save your data and then try it. As long as you +use some common sense, you are very unlikely to break anything by clicking +buttons. + +Above all, don't be lazy. If you show the people who you are asking +that you are able to troubleshoot and research in a logical manner, you're +showing them you're a reasonable person who is worth their time to +help. It's your problem and not theirs so the legwork is yours to do. Save +your helpers as much time as you can, they're busy people. + + + +Where do I ask? + +Usually the best place to ask a question is on the +IRC channels and mailing lists devoted to user +questions. Don't post simple questions about using &kde; to the devel +channels and mailing lists, these are for technical discussions. Some good +places are #kde on irc.freenode.net, and the &kde; mailing +lists. + + +How do I ask? + +Try to word your questions in a manner that gives the most +information possible and is polite and courteous. Don't ask to ask, just +ask! + +Q: &kde; sucks, it's being slow + +Is not a question that is likely to get you a useful answer. It does +not give any useful information about troubleshooting the problem, and it +starts out attacking the software in a way that isn't productive. + +Q: Since upgrading &kde; on Slackware &Linux; from version 3.2.3 to +3.3.2 using sources, I have noticed it's being really slow — sometimes +applications take up to 20 seconts to launch. I am using the same user +configuration as I had with the previous version, and I have tried as a new +user. I can't find anything about this on the mailing lists or by a google +search. Could anyone point me to some information that could help? + +This question is polite, contains information to help people +troubleshoot the problem and shows your helpers what avenues you have +already tried. + +Don't assume automatically that the problem is the fault of +&kde;. Proceed as though this is your error, otherwise you will quickly +annoy people if it does indeed turn out to be your problem and not +&kde;. + +Use clear language with correct spelling. Watch out for any +ambiguities and make sure you think about what you say before you write +it. If you are asked for clarification, give it as best you can. &kde; is a +project where many of the users and developers are not native english +speakers and if you don't use correct english, misunderstandings may +ensue. Use the language appropriate to the channel or mailing list you are +in — if you don't, people who might have been able to help you may +ignore your message because it is not in a language they understand. + +Include all information that could be relevant, even if you're not +sure. Have you upgraded other software or hardware on your system, +particularly system libraries or a new kernel? These things could affect how +&kde; performs. Even if you cannot see a link, someone else might. + +Don't paraphrase error messages. Paste in the exact error, and if it's +more than a line or two don't paste them directly into an +IRC channel. Use a paste service like http://www.rafb.net/paste. If you +must type them in by hand, be sure you are 100% accurate. When you provide +faulty information, your helpers cannot help you as easily. + +Follow up on your solution! Tell us if it worked, or if you have +solved it yourself in the meantime. This helps us know for sure if our +solution worked, and helps other users who may be searching mailing list +archives for a solution to the problem themselves. + + + +What do I do when told to look elsewhere? + +When you're told google knows or google +is your friend then chances are, you have not followed the above +advice. You've not done your research, and the solution is probably one the +helper knows very well to be easy to find. When you're linked to a +FAQ or a usermanual don't ever say, No, I don't +want to have to read this I want you to just tell me. This is very +bad manners. If you cannot put in the effort to read the document, what is +the incentive for your helper to put in the time and effort to help you? If +you're told to go use google, take it graciously and do so. + + +Above all, use common courtesy. &kde; users and developers are usually +volunteering their time out of an already very busy schedule, and like to +know that you are appreciating that they are helping you for free. Be +polite, say please and thank you and try to be pleasant and +friendly. + + Does this seem like a lot of trouble to ask a question? If you want +to be able to feel that people owe you an answer or support, then you're +quite welcome to pay for commercial support from companies that support +&kde; on &UNIX; platforms. If you don't want to pay money, then pay the +people who do this for free with your politeness and appreciation :) + + +If you think the answer to your question should be included in the +&kde; &FAQ; please feel free to submit any patches or suggestions to the +&kde; &FAQ; Maintainer, at faq@kde.org + + + + + + diff --git a/doc/faq/sound.docbook b/doc/faq/sound.docbook new file mode 100644 index 000000000..d7db604bc --- /dev/null +++ b/doc/faq/sound.docbook @@ -0,0 +1,55 @@ + +Troubleshooting sound problems + +&kde; uses the &arts; sound system which is complex and powerful, +making it difficult for some users to troubleshoot when things go +wrong. Here are some tips to help you diagnose what it's doing when your +sound misbehaves : + + + + +How can I troubleshoot sound related problems in &kde;? + + + To check that sound is working independently of &arts;, make +sure that artsd isn't running and then try playing sound +through XMMS or another multimedia application +that isn't a part of &kde;. If that application doesn't play sound, then +your general sound setup is probably broken and it's not a &kde; +problem. + +Try playing sound with +artsplay. Try various +formats, ogg, mp3 and wav. Any error messages there might be useful in +pointing you in the right direction. + +Try setting the &arts; output method to OSS. In the +&kcontrolcenter; go to Sound & Multimedia +Sound System. On the +Hardware tab, under Select the audio +device choose Open Sound System. If you are +running alsa this will use the OSS +emulation, which may give better or worse results. + +Running artsd from a terminal will give you a lot of debug output, +some of which might help you to diagnose the problem. Trying this in +conjunction with using artsplay in a second terminal can give a wealth of information. If an artsd instance is already running, exit it with artsshell +terminate + + + + +I've upgraded to the latest version of &kde; keeping my old configuration, and my system sounds don't work anymore! + +Assuming you've installed &arts; correctly and you still have the codecs installed your previous &kde; installation needed, chances are this is a small problem with your knotifyrc. To confirm this, try creating an entirely new user and seeing if system notifications work under the new account. If they do, try moving your $KDEHOME/share/config/knotifyrc out of the way for your original user to see if this solves the problem. + + + + + + + + diff --git a/doc/faq/tips.docbook b/doc/faq/tips.docbook new file mode 100644 index 000000000..d47709095 --- /dev/null +++ b/doc/faq/tips.docbook @@ -0,0 +1,137 @@ + + + +Useful tips + + + + +Reading documentation in &kde; + + +Pop up the Run Command window (&Alt;F2 by +default) and type: + + +man:command for man pages. It +even unpacks on the fly if the man pages are gzipped. + + + +info:command for info +pages. + + + +help:kdeappname for &kde; +application help pages. + + + + + +You can also enter any of these in the Location text +box in &konqueror;. +Or you can use the &kde; Help Center if you are using &kde; +2. Simply start the &kde; Help Center by clicking on the icon (the blue +book with the yellow key) on the toolbar. Once the &kde; Help Center has +loaded, the window on the left will contain an entry called +Unix manual pages. Click once on this entry, and +you can browse through all the installed manual pages on your +system. + + + + + +Move or resize windows quickly + + +To move a window, use &Alt;left mouse +button. &Alt;right mouse +button will resize the window. Last but not least, &Alt;middle mouse button +raises/lowers the window. The &kde; Control Center +allows you to change these mouse bindings. + + + + + +Killing windows in &kde; + + +There is a standard keybinding (&Ctrl;&Alt;&Esc;) +that gives you a skull & crossbones cursor. Click that cursor on a +window to kill it. The keybindings are viewable/changeable from the +&kde; Control Center. + +Using this option kills the program forcibly. Data may be lost, +and some processes related to the program may remain active. Use only as a +last resort. + + + + + + +What if something is so wrong that I can't even get the skull +& crossbones cursor? How do I get out of a total lockup? + + +These kind of locks tend to occur when an application locks up +while it has a so called mouse/keyboard grab. When that +happens you can try to select a virtual text console with &Ctrl;&Alt;F1 and login. With the +following command you will get a list of all running processes: + + ps | more + +By killing the process that has the mousegrab, your desktop will +come to life again. Unfortunately you can't see which process that is, +so you will have to find out through trial and error. To kill a process +use: + + kill pid + +Here pid is the process id of the +process, which is the first number on each line reported by +ps . + +You can switch back to the desktop with &Ctrl;&Alt;F7 (or +F8 through F9 depending on your +operating system) to see if things work again. When you press +&Alt;Tab you should get a +response from the window manager. If not, you need to get back to the +text console and try to kill another process. + +Good candidates to kill are: the application you were working +with, &kicker;, &klipper; and &kdesktop;. + + + + + + + diff --git a/doc/faq/webbrowse.docbook b/doc/faq/webbrowse.docbook new file mode 100644 index 000000000..b80c7ae1a --- /dev/null +++ b/doc/faq/webbrowse.docbook @@ -0,0 +1,222 @@ + + + +Webbrowsing with &konqueror; +&konqueror; is &kde;'s open source, standards compliant webbrowser. +It's home page is +http://www.konqueror.org where a +&konqueror; specific FAQ can be found. + + + + +Where does the name &konqueror; come from? +It's a word play on the other browsers' names. After the Navigator and the Explorer comes the Conqueror; it's spelled with a K to show that it's part of &kde;. The name change also moves away from kfm (the &kde; file manager, &konqueror;'s predecessor) which represented only file management. + + + +Can I run &konqueror; without running &kde;? +Yes. Just install &Qt;, kdelibs and kdebase, and from your favorite window manager just launch &konqueror;. It should work just fine, but if it doesn't (&kde; developers don't test that case often), report it to http://bugs.kde.org and try running "kdeinit" before running &konqueror;, it usually helps. +This is of course the same for any other &kde; application. + + + + +Why doesn't &konqueror; show the contents of an image's ALT attribute in a tooltip? + +There is no standard that states the ALT attribute should appear as a tooltip. The specification calls for ALT to be displayed in place of the image, as in text-mode only browsers such at lynx or w3m. Abusing the ALT attribute is bad for accessibility. Tooltips are supposed to come from the TITLE attribute and this is implemented in &konqueror; + + + + + +How do I use &konqueror; as a web browser with a proxy? + + +&konqueror; can be used with &HTTP; and &FTP; proxies. To set +up the proxy server in &konqueror;, just select +SettingsConfigure +&konqueror;... from the &konqueror; menu and +go to the Proxy tab. + + + + + +How do I import bookmarks from another browser into &konqueror; ? + + +To import bookmarks from another browser into &konqueror; select +BookmarksEdit Bookmarks +and then in the Bookmark Editor select +FileImport. Then select +the browser you would like to import bookmarks from. In the Open dialog, +navigate to the location of the folder or file your bookmarks are +contained in and click Open + + + + + +How can I make &konqueror; only show certain bookmarks in the bookmarks toolbar? +In &konqueror; go to SettingsConfigure &konqueror;.... Then select Web Behaviour from the icon list. Under the Bookmarks heading, place a check in the box next to Show only marked bookmarks in bookmark toolbar. Now in the Bookmark Editor an option to Show in Toolbar appears on clicking with the &RMB; on any bookmark entry or in the Edit menu when the entry is highlighted. Folders can also be shown in the bookmarks toolbar in much the same way. + + + + +How do I fool a site into believing &konqueror; is &Netscape; or +some other browser? + + +In &konqueror;, select +SettingsConfigure +Konqueror... and in the configuration +dialog, select Browser Identification. Default +and site-specific browser identifications can be set from here. + + + + +&konqueror; is taking a really long time to load webpages, what +could cause this? + +Quite often &konqueror; loading webpages slowly is caused by +DNS servers with broken IPV6 +support. Adding the following to /etc/profile or any +other script that is sourced on login should solve this problem: + +export KDE_NO_IPV6=true + +for bourne compatible shells, and for C-style shells: + +setenv KDE_NO_IPV6 true + + + + + + + +How do I configure &konqueror; to run &Java; applets? + + +Choose +SettingsConfigure +&konqueror;... from &konqueror;'s menubar +and then select Java & Javascript. Set the +Path to Java executable correctly. If it doesn't +work, please check the Konqueror + Java +HOWTO. + + + + + + +How do I block unrequested popup windows in &konqueror;? + + +&konqueror; has a new 'smart' policy for JavaScript popups. From the +&konqueror; main window, select Settings +Configure &konqueror;... and then +Java & JavaScript. On the +JavaScript tab, under Global JavaScript +Policies set the radio button beside Open new +windows: to Smart. + + + + + + +Why doesn't my banking site work with &konqueror;? It pops up a new +window with the login screen in other browsers, but not in +&konqueror;. + + + +Make sure you have Javascript enabled, and the default JavaScript web popups +policy set to Ask or Allow. The +Smart policy is not always sufficient for some banks. +Many banks also require &Java; support. You can find more help on enabling +this at http://www.konqueror.org/. + + + + + + +Can &konqueror; use user-specified stylesheets, like those in the +Firefox adblock extention? + + +Yes, you can set &konqueror; to use any kind of valid +css stylesheet to filter webcontent or improve accessibility. +From the &konqueror; main window simply click +Settings +Configure &konqueror;... and select +Stylesheets. Set the radio button to +Use user-defined stylesheet and browse to where the +stylesheet you want to use is located. Alternatively, you can select +Use accessibility stylesheet defined in "Customize" +tab and then set your own options. + +An example of css rules that implement ad blocking can be +found at: + +http://www.mozilla.org/support/firefox/adblock. + + + + + +Why does &konqueror; display a plain grey square when I try to view flash animations, even though the flash plugin is installed? + + +Under the latest versions of X.org, having the composite extension loaded can cause problems with the flash plugin. Try disabling the composite extension and see if normal flash operation is restored. + + + + + +Why can't &konqueror; render &GIF; images? + + +It is because you did not enable &GIF; support in &Qt;. Please see + for more details. + + + + +When I try to open a web page with &konqueror;, I get the +message: There appears to be a configuration error. You have +associated Konqueror with text/html, but it cannot handle this file +type. + + +You need to make sure that the embedding settings for the text/html +MIME type are correct: + +In &konqueror;, go to +SettingsConfigure +&konqueror;... and then to the File +Associations page. Open +text->html in the tree view. Click on the +Embedding tab. Make sure that Left Click +Action is set to Show file in embedded +viewer, and that KHTML (khtml) is at the top +of Services Preference Order. + + + + + + + + + diff --git a/doc/faq/winmng.docbook b/doc/faq/winmng.docbook new file mode 100644 index 000000000..f32384754 --- /dev/null +++ b/doc/faq/winmng.docbook @@ -0,0 +1,134 @@ + + + + + +The window manager + +The default window manager provided by &kde; is the K Window +Manager (&kwin;). Please read The +K Window Manager Handbook (which should be accessible from the +&kde; Help Center) for usage information. + + + + +Are there keyboard shortcuts for &kwin; operations? + + +Yes. Please refer to "The K Window Manager Handbook" for the +list of shortcuts available. + + + + + +Can I define my own set of keyboard shortcuts? + + +Yes. Launch the +&kde; Control Center and select +Regional & AccessibilityKeyboard Shortcuts to +configure window manager bindings like maximizing windows, &etc;. + + + + + + +When I "iconify" a window, it disappears. Where does it +go? + + +With many &X-Window; &GUI;s, the minimize button (a little dot) will +erase the window that the program is running in and create, instead, +an icon on the desktop. &kde; does not do this. Instead, when a +window is iconified it is simply hidden (but the program is still +running). +There are a few ways to access disappeared windows: + + +If you are running the taskbar part of &kicker;, +you can choose to have a list of tasks displayed on your desktop. +Iconified tasks will have their names displayed in gray. + + +If you click the &MMB; on the root window (&ie;, +the background of the desktop), &kwin; will give you a list +of all available tasks. + + + + + + + +How do I maximize windows only vertically or horizontally? + + +Provided your window is not already maximized, clicking on the +maximize button with the &LMB;/&MMB;/&RMB; will +maximize fully/vertically/horizontally respectively. + + + + + +What is shading a window? + + +By shading a window we mean rolling up the window leaving just +the title bar visible. You can do this by double clicking on the +window title bar. + + + + + + + +How can I start an application with special window options, like +maximized/minimized/to stay on top? + + +Use the kstart command. As an example, to +open &kcalc; with the Stay on Top option, use: +% kstart + +For maximized windows, use the +option, for minimized windows, use . You can +see a full list of kstart options with +kstart +. + +If you're using kstart to start +applications at &kde; startup, you should use the + option. See the &kde; User Guide, section +Advanced Window Management for more information about +this feature. + + + + + + + + + diff --git a/doc/glossary/Makefile.am b/doc/glossary/Makefile.am new file mode 100644 index 000000000..e79a46842 --- /dev/null +++ b/doc/glossary/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = khelpcenter/glossary diff --git a/doc/glossary/checkxrefs b/doc/glossary/checkxrefs new file mode 100755 index 000000000..6da64c184 --- /dev/null +++ b/doc/glossary/checkxrefs @@ -0,0 +1,10 @@ +#!/bin/sh +DEFINED_ENTRIES=`sed -ne "s^.*.*^\1^p" *.docbook` +REFERENCED_ENTRIES=`sed -ne "s^.*.*^\1^p" *.docbook | unique` + +# Check for entries which are referenced but not defined. +for ENTRY in $REFERENCED_ENTRIES; do + if ! echo $DEFINED_ENTRIES | grep $ENTRY - > /dev/null 2>&1; then + echo "'$ENTRY' referenced but not defined!" + fi +done diff --git a/doc/glossary/index.docbook b/doc/glossary/index.docbook new file mode 100644 index 000000000..4aba44c53 --- /dev/null +++ b/doc/glossary/index.docbook @@ -0,0 +1,296 @@ + + + + + + +]> + + + + +&glossary-kdeprinting; + + + Technologies + + IO Slave + IO Slaves enable &kde; applications to + access remote resources as easily as local resources (making them + network transparent). Remote resources (⪚ files) might + be stored on SMB shares or similar. + SMB + &kde; + + + + KIO + The &kde; Input/Output system which makes use of so-called + IO Slaves. + IO +Slave + &kde; + + + + KParts + KParts is an embedding technology which allows &kde; + applications to embed other &kde; applications. For example, the text + view used by &konqueror; is a KPart. + &konqueror; + + + + KSycoca + KSycoca (&kde; System + Configuration Cache) is a + configuration cache which, for example, guarantees fast access to the menu + entries. + KBuildSycoca + + + + + + XFree86 + + Antialiasing + If mentioned in context with &kde;, antialiasing often means + the smoothing of the fonts visible on the screen. &Qt; version 2.3.0 + or higher used together with XFree86 4.x makes this possible under &kde; + as well. + &kde; + &Qt; + + + + &X-Server; + The &X-Server; represents a basic layer upon which the + various &GUI;s like &kde; are built. It manages the + basic mouse and keyboard input (from the local host as well as from + remote hosts) and provides elementary graphic routines to draw + rectangles and other primitives. + &kde; + &GUI; + + + + + + Applications + + KBuildSycoca + KBuildSycoca is a command line +program and regenerates the + so-called KSycoca. This is useful, for example, if some +or all modules in + &kcontrol; are missing. + KSycoca + &kcontrol; + + + + &kcontrol; + This is the project and filename of the &kde; control + center. &kcontrol; allows you to customize virtually + every configuration option of &kde;. + &kde; + + + + &kicker; + &kicker; is the nickname as well as project name of the + &kde; panel. + &kde; + Panel + + + + &konqueror; + &konqueror; is a filemanager, web browser, picture viewer + and more, and a core part of the &kde; project. You can + find more information about &konqueror; at www.konqueror.org. + &kde; + + + + &ksirc; + &ksirc; is the default IRC client, + which is shipped with &kde;. You can use &ksirc; to chat with anyone on + an IRC network. + IRC + + + + + + Desktop Terminology + + Drag and Drop + This concept tries to replace many actions like copying + files from one place to another by a certain mouse movement, ⪚ + clicking on an icon in a &konqueror; window, moving the mouse to another + window while keeping the mouse button pressed, and releasing the mouse + button (dropping the object) copies files. + &konqueror; + + + + &GUI; + Abbreviation for Graphical + User Interface. Every desktop + environment (like &kde;) is a &GUI;. Most + &GUI;s feature mouse support and/or windows to manage + the programs. + &kde; + + + + &kde; + Abbreviation for K Desktop Environment, a + leading &GUI; for &UNIX;-based systems. You can find more + detailled information at www.kde.org. + &GUI; + + + + GNOME + + GNU Network Object + Model Environment, one of the + leading &UNIX; &GUI;s. + &GUI; + + + + Panel + Refers to the panel (also known as + &kicker;) which often resides at the bottom of the + screen. + &kde; + &kicker; + + + + ripping + The process of reading audio data from a &cdrom; and + storing it on the hard disk. + + + + + + &kde; Development + + &Qt; + The &GUI; of &kde; is built on top of + the &Qt; toolkit, which provides many graphical elements (so-called + Widgets) which are used to construct the desktop. You + can find more information about &Qt; at www.trolltech.com. + &kde; + &GUI; + Widget + + + + i18n + Abbreviation for internationalization. &kde; + supports many different languages, and several i18n techniques make it + easy to translate the &GUI; as well as the accompanying + documents of &kde; into all these languages. More information about the + i18n process is available at i18n.kde.org. + &kde; + &GUI; + + + + l10n + Abbreviation for localization, the process + of adapting a program to the local environment. This includes ⪚ the + currency used for monetary values or the time format. + i18n + + + + Widget + Graphical elements like scrollbars, buttons or input + fields which are used by &kde; to construct the &GUI;. + + &kde; + &GUI; + + + + CVS + + Concurrent Version +System. + The CVS is a very elegant way of managing file +versions that allow more than one developer + to easily work on the same project. You can find a description of how to +get the latest (developer) version of the + &kde; sources via anonymous CVS on + http://www.kde.org/anoncvs.html. + More about CVS is available at www.cvshome.org. + + + + + + + + Miscellaneous + + RFC + Request For + Comment. A common way to publish new protocol + ideas or procedures for evaluation of the Internet community. Though + RFCs are not mandatory, many applications try to + adhere to them, once they have been approved by the community. More + information about RFCs can be found at the + RFC Homepage. + + + + + + Various protocols + + SMB + Server Message + Block. A network protocol used in &Microsoft; &Windows; + networks to access the filesystems of other computers. + IO +Slave + + + + IRC + Internet Relay + Chat. A protocol defined in RFC + 1459, which handles the specification to enable real time text chat. + RFC + + + + host + This can either be a name from your + /etc/hosts file + (mycomputer), + an Internet name (www.kde.org) or an IP-Address + (192.168.0.10). + + + + + diff --git a/doc/glossary/kdeprintingglossary.docbook b/doc/glossary/kdeprintingglossary.docbook new file mode 100644 index 000000000..7a9311c73 --- /dev/null +++ b/doc/glossary/kdeprintingglossary.docbook @@ -0,0 +1,1387 @@ + + + + Printing + + + + ACLs + Abbreviation for Access + Control Lists; + ACLs are used to check for the access by a given + (authenticated) user. A first rough support for ACLs + for printing is available from &CUPS;; this will be refined + in future versions. + Authentication + + + + + AppSocket Protocol + AppSocket is a protocol for the transfer of + print data, also frequently called "Direct TCP/IP Printing". + &Hewlett-Packard; have taken AppSocket, added a few minor + extensions around it and been very successful in renaming + and marketing it under the brand "&HP; JetDirect"... + &HP; JetDirect Protocol + Direct TCP/IP Printing + + + + + APSfilter + APSfilter is used mainly in the context of "classical" + &UNIX; printing (BSD-style LPD). It is a sophisticated shell script, + disguised as an "all-in-one" filtering program. In reality, + APSfilter calls "real filters" to do the jobs needed. It sends + printjobs automatically through these other filters, based on an + initial file-type analysis of the printfile. + It is written and maintained by Andreas Klemm. + + It is + similar to Magicfilter and mostly uses Ghostscript for file conversions. + Some Linux Distributions (like &SuSE;) use APSfilter, others + Magicfilter (like &RedHat;), some have both for preference selection + (like *BSD). + + &CUPS; has no need for APSfilter, + as it runs its own file type recognition (based on &MIME; types) + and applies its own filtering logic. + Ghostscript + Magicfilter + &MIME;-Types + printcap + + + + + Authentication + Proving the identity of a certain person (maybe via username/password + or by means of a certificate) is often called authentication. Once you are + authenticated, you may or may not get access to a requested ressource, + possibly based on ACLs. + ACLs + + + + + Bi-directional communication + In the context of printing, a server or a host may receive additional + information sent back from the printer (status messages &etc;), either + upon a query or unrequested. AppSocket ( = &HP; JetDirect), &CUPS; and IPP + support bi-directional communication, LPR/LPD and BSD-style printing + do not... + AppSocket Protocol + &CUPS; + Direct TCP/IP Printing + &HP; JetDirect + IPP + LPR/LPD + + + + + BSD-style Printing + Generic term for different variants of the traditional &UNIX; + printing method. Its first version appeared in the early 70s on + BSD &UNIX; and was formally described in RFC 1179 only as late + as 1990. + + At the time when BSD "remote" printing was first designed, printers + were serially or otherwise directly connected devices to a host + (with the Internet hardly consisting of more than 100 nodes!); printers + used hole-punched, continuous paper, fed through by a tractor + mechanism, with simple rows of ASCII text mechanically hammered on to + the medium, drawn from a cardboard box beneath the table. It came out + like a zig-zag folded paper "snake". Remote printing consisted of a + neighboring host in the next room sending a file + asking for printout. + + How technology has changed! Printers generally use cut-sheet media, they have + built-in intelligence to compute the raster images of pages after pages + that are sent to them using one of the powerful page description + languages (PDL). Many are network nodes in their own right, + with CPU, RAM, a hard disk and their own Operation System, and + are hooked to a net with potentially millions of users... + + It is a vast proof of the flexible &UNIX; concept for doing things, + that it made "Line Printing" reliably work even under these modern + conditions. But time has finally come now to go for something new + -- the IPP. + + It is strong proof of the flexibility of &UNIX;; that "Line Printing" works + reliably, even under these modern conditions. But time has finally come now + to go for something new -- the IPP. + + + IPP + &CUPS; + LPR/LPD printing + + + + + &CUPS; + Abbreviation for Common + UNIX Printing + System; &CUPS; is the most modern &UNIX; and Linux + printing system, also providing cross-platform print services + to &Microsoft; &Windows; and Apple &MacOS; clients. Based on IPP, it does + away with all the pitfalls of old-style BSD printing, + providing authentication, encryption and ACLs, plus many more + features. At the same time it is backward-compatible enough + to serve all legacy clients that are not yet up to IPP, via + LPR/LPD (BSD-style). + + &CUPS; is able to control any &PostScript; printer by + utilizing the vendor-supplied PPD (PostScript Printer + Description file), targeted originally for &Microsoft; Windows NT + printing only. &kde; Printing is most powerful if based on + &CUPS;. + ACLs + Authentication + BSD-style printing + IPP + KDEPrint + LPR/LPD + PPD + + + + + + &CUPS;-FAQ + Currently only available in German (translation is on the way), + the &CUPS;-FAQ + is a valuable resource to answer many questions that anyone new to + &CUPS; printing might have at first. + + KDEPrint Handbook + + + + + + &CUPS;-O-Matic + &CUPS;-O-Matic was the first "Third Party" plugin for + the &CUPS; printing software. It is available on the Linuxprinting.org + website to provide an online PPD-generating service. + + + Together with the companion cupsomatic Perl-Script, + that needs to be installed as an additional &CUPS; backend, + it redirects output from the native pstops filter into + a chain of suitable Ghostscript filters. Upon completion, it + passes the resulting data back to a &CUPS; "backend" for sending + to the printer. + + In this way, &CUPS;-O-Matic enables support for any printer known to + have worked previously in a "classical" Ghostscript environment. + If no native &CUPS; support for that printer is in sight... &CUPS;-O-Matic + is now replaced by the more capable PPD-O-Matic. + cupsomatic + PPD-O-Matic + Foomatic + + + + + + cupsomatic + The Perl script cupsomatic (plus a working Perl installation + on your system) is needed to make any &CUPS;-O-Matic (or PPD-O-Matic) + generated PPD work with &CUPS;. It was written by Grant Taylor, author of + the Linux Printing HOWTO and Maintainer of the printer + database at the Linuxprinting.org website. + &CUPS;-O-Matic + Foomatic + cupsomatic + + + + + Daemon + Abbreviation for Disk + and execution + monitor; Daemons are present + on all &UNIX; systems to perform tasks independent of user + intervention. Readers more familiar with &Microsoft; &Windows; might + want to compare daemons and the tasks they are responsible + with "services". + + One example of a daemon present on most + legacy &UNIX; systems is the LPD (Line Printer Daemon); &CUPS; is + widely seen as the successor to LPD in the &UNIX; world and + it also operates through a daemon. + SPOOLing + + + + + Database, Linuxprinting.org + Already years ago, when Linux printing was still really difficult + (only command line printing was known to most Linux users, no device + specific print options were available for doing the jobs), Grant Taylor, + author of the "Linux Printing HOWTO", collected most of the available + information about printers, drivers and filters in his database. + + With the emerging + &CUPS; concept, extending the use of PPDs even to non-PostScript printers, + he realized the potential of this database: if one puts the different + datablobs (with content that could be described along the lines + "Which device prints with which Ghostscript or other + filter?", "How well?", and "What command line switches are available?") into + PPD-compatible files, he could have all the power of &CUPS; on top of + the traditional printer "drivers". + + This has now developed into a broader + concept, known as "Foomatic". Foomatic extends the capabilities + of spoolers other than &CUPS; (LPR/LPD, LPRng, PDQ, PPR) to a certain + degree ("stealing" some concepts from &CUPS;). The Linuxprinting + Database is not a Linux-only stop -- people running other &UNIX; + based OSes (like *BSD or &MacOS; X) will also find valuable information + and software there. + + Foomatic + Linuxprinting database + + + + + Direct TCP/IP Printing + This is a method that often uses TCP/IP port 9100 to connect + to the printer. It works with many modern network printers and has + a few advantages over LPR/LPD, as it is faster and provides some + "backchannel feedback data" from the printer to the host sending + the job. + AppSocket Protocol + &HP; JetDirect Protocol + + + + + + Drivers, Printer Drivers + The term "printer drivers", used in the same sense + as on the &Microsoft; &Windows; platform, is not entirely applicable + to a Linux or &UNIX; platform. A "driver" functionality + is supplied on &UNIX; by different modular components working + together. At the core of the printer drivers are "filters". Filters convert + print files from a given input format to another format that is acceptable + to the target printer. In many cases filters may be connected to a whole + filter "chain", where only the result of the last conversion is sent to the + printer. The actual transfer of the print data to the device is performed by + a "backend". + + Filter + PPDs + + + + + Easy Software Products + Mike Sweet's company, which has contributed a few substantial + software products towards the Free Software community; amongst + them the initial version of Gimp-Print, the EPM software packaging tool + and HTMLDOC + (used by the "Linux Documentation Project" to build the PDF versions + of the HOWTOs) -- but most importantly: &CUPS; (the 'Common &UNIX; Printing + System'). + + ESP finance themselves by selling a commercial version + of &CUPS;, called ESP PrintPro, + that includes some professional enhancements. + + &CUPS; + ESP PrintPro + ESP + Gimp-Print + + + + + Encryption + Encryption of confidential data is an all-important issue if + you transfer it over the Internet or even within intranets. + + Printing + via traditional protocols is not encrypted at all -- it is very easy + to tap and eavesdrop ⪚ into &PostScript; or PCL data transfered + over the wire. + + Therefore, in the design of IPP, provision was made for the easy + plugin of encryption mechanisms (which can be provided by the same + means as the encryption standards for HTTP traffic: SSL and TLS). + Authentication + &CUPS; + IPP + SSL + TLS + + + + + + Epson + Epson inkjets are among the best supported models by Free software + drivers, as the company was not necessarily as secretive about their + devices and handed technical specification documents to developers. + The excellent print quality achieved by Gimp-Print on the Stylus + series of printers can be attributed to this openness. + + They have also + contracted Easy Software Products to maintain an enhanced version + of Ghostscript ("ESP GhostScript") for improved support of their + printer portfolio. + + ESP Ghostscript + + + + + + Escape Sequences + The first ever printers printed ASCII data only. To + initiate a new line, or eject a page, they included special + command sequences, often carrying a leading [ESC]-character. + &HP; evolved this concept through its series of PCL language + editions until today, having now developed a full-blown + Page Description Language (PDL) from these humble beginnings. + + PCL + PDL + + + + + ESC/P + Abbreviation for Epson + Standard Codes for + Printers. Besides &PostScript; and PCL, Epson's ESC/P + printer language is one of the best known. + PCL + &PostScript; + hpgl + + + + + ESP + Abbreviation for Easy + Software Products; + the company that developed &CUPS; (the "Common &UNIX; Printing System"). + + Easy Software Products + &CUPS; + ESP PrintPro + + + + + + ESP Ghostscript + A Ghostscript version that is maintained by Easy Software + Products. It includes pre-compiled Gimp-Print drivers for + many inkjets (plus some other goodies). ESP Ghostscript + will produce photographic quality prints in many cases, especially + with the Epson Stylus model series. ESP Ghostscript is GPL-software. + + Easy Software Products + &CUPS; + ESP PrintPro + + + + + ESP PrintPro + This professional enhancement to &CUPS; (the "Common &UNIX; + Printing System") is sold by the developers + of &CUPS; complete with more than 2,300 printer drivers for several commercial + &UNIX; platforms. ESP PrintPro + is supposed to work "out of the box" with little or no configuration + for users or admins. ESP also sell support contracts for + &CUPS; and PrintPro. These sales help to feed the programmers who + develop the Free version of &CUPS;. + + &CUPS; + + + + + Filter + Filters, in general, are programs that take some input + data, work on it and pass it on as their output data. Filters + may or may not change the data. + + Filters in the context of printing, are programs that convert + a given file (destined for printing, but not suitable in the + format it is presently) into a printable format. Sometimes + whole "filter chains" have to be constructed to achieve the + goal, piping the output of one filter as the input to the next. + + Ghostscript + RIP + + + + + Foomatic + Foomatic started out as the wrapper name for a set of + different tools available from Linuxprinting.org + These tools aimed to make the usage of traditional + Ghostscript and other print filters easier for users and + extend the filters' capabilities by adding more command line + switches or explain the driver's execution data. + + Foomatic's different incarnations are &CUPS;-O-Matic, PPD-O-Matic, + PDQ-O-Matic, LPD-O-Matic, PPR-O-Matic, MF-O-Matic and + Direct-O-Matic. All of these allow the generation + of appropriate printer configuration files online, by simply + selection the suitable model and suggested (or alternate) driver + for that machine. + + More recently, Foomatic gravitated towards becoming a "meta-spooling" + system, that allows configuration of the underlying print subsystem + through a unified set of commands (however, this is much more + complicated than KDEPrint's &GUI; interface, which performs a similar + task with regards to different print subsystems). + &CUPS;-O-Matic + PPD-O-Matic + cupsomatic + + + + + Ghostscript + Ghostscript is a &PostScript; Raster Image Processor (RIP) in software, originally + developed by L. Peter Deutsch. There is always a GPL version + of Ghostscript available for free usage and distribution + (mostly 1 year old) while + the current version is commercially sold under another license. + + Ghostscript is widely used inside the Linux and &UNIX; world + for transforming &PostScript; into raster data suitable + for sending to non-&PostScript; devices. + &PostScript; + RIP + + + + + Gimp-Print + Contrary to its name, Gimp-Print is no longer + just the plugin to be used for printing from the popular + Gimp program -- its codebase can also serve to be compiled + into... + + *...a set of PPDs and associated filters that integrate seamlessly + into &CUPS;, supporting around 130 different printer models, providing + photographic output quality in many cases; + + + *...a Ghostscript filter that can be used with any other + program that needs a software-RIP; + + + *...a library that can be used by other software applications + in need of rasterization functions. + + + + + Lexmark Drivers + RIP + Ghostscript + + + + + &HP; + Abbreviation for Hewlett-Packard; + one of the first companies to distribute their own Linux printer + drivers. -- More recently, the Company has released their + "HPIJS" package of drivers, including source code and a Free license. + This is the first printer manufacturer to do so. HPIJS supports most + current models of HP Ink- and DeskJets. + + + + + + + &HP;/GL + Abbreviation for &HP; + Graphical Language; + a &HP; printer language mainly used for plotters; many CAD + (Computer Aided Design) software programs output &HP;/GL files for + printing. + ESC/P + PCL + &PostScript; + + + + + &HP; JetDirect Protocol + A term branded by &HP; to describe their implementation + of print data transfer to the printer via an otherwise "AppSocket" or + "Direct TCP/IP Printing" named protocol. + AppSocket Protocol + Direct TCP/IP Printing + + + + + IETF + Abbreviation for Internet + Engineering Task + Force; an assembly of Internet, software + and hardware experts that discuss + new networking technologies and very often arrive at + conclusions that are regarded by many as standards. "TCP/IP" + is the most famous example. + + + IETF standards, as well as + drafts, discussions, ideas and useful tutorials, are + put in writing in the famous series of "RFCs", which + are available to the public and included in most Linux and + BSD distributions. + IPP + PWG + RFC + + + + + IPP + Abbreviation for Internet + Printing Protocol; + defined in a series of RFCs accepted by the IETF with + status "proposed standard"; was designed + by the PWG. -- IPP is a completely new design for network printing, + but it utilizes a very well-known and proven method for the + actual data transfer: HTTP 1.1! By not "re-inventing the wheel", + and basing itself on an existing and robust Internet standard, + IPP is able to relatively easily bolt other HTTP-compatible standard + mechanisms into its framework: + + * Basic, Digest or Certificate authentication + mechanisms; + + * SSL or TLS for encryption of transferred + data; + + * LDAP for directory services (to publish + data on printers, device-options, drivers, costs or + also to the network; or to check for passwords while + performing authentication). + + + + + + &CUPS; + PWG + IETF + RFC + TLS + + + + + KDEPrint + The new printing functionality of &kde; since version 2.2 + consists of several modules that translate the features and settings + of different available print subsystems (&CUPS;, BSD-style LPR/LPD, RLPR...) + into nice &kde; desktop &GUI; windows and dialogs to ease their + usage. + + Most important for day-to-day usage is "kprinter", the new + &GUI; print command. -- Note: KDEPrint does not implement its own + spooling mechanism or its own &PostScript; processing; for this it + relies on the selected print subsystem + -- however it does add some functionality of its own on top of this + foundation... + + BSD-style printing + &CUPS; + kprinter + KDEPrint Handbook + + + + + + KDEPrint Handbook... + ...is the name of the reference document that describes KDEPrint + functions to users and administrators. You can load it into Konqueror by + typing "help:/kdeprint" into the address field. The KDEPrint website + is the resource for updates to this documentation, as well as PDF + versions suitable for printing it. It is authored and maintained by Kurt + Pfeifle. + + &CUPS;-FAQ + + + + + kprinter + kprinter is the new powerful + print utility that is natively used by all &kde; applications. + + Contrary to some common misconceptions, + kprinter is not a &CUPS;-only tool, + but supports different print subsystems. You can even switch + to a different print subsystem "on the fly", in between two jobs, + without re-configuration. Of course, due to the powerful + features of &CUPS;, kprinter is + best suited for use with a &CUPS; frontend. + + kprinter is the successor + to "qtcups", which is no longer being actively maintained. It has + inherited all the best features of qtcups and added several new ones. + + + MOST IMPORTANT: you can use kprinter + with all its features in all non-&kde; applications that allow + a customized print command, like gv, Acrobat Reader, Netscape, + Mozilla, Galeon, StarOffice, OpenOffice and all GNOME programs. + + kprinter can act as a "standalone" + utility, started from an X-Terminal or a "Mini-CLI" to + print many different files, from different folders, with different + formats, in one job and simultaneously, without the need to first open the + files in the applications! (File formats supported this way are &PostScript;, + PDF, International and ASCII Text, as well as many different popular graphic + formats, such as PNG, TIFF, JPEG, PNM, Sun RASTER, &etc;) + + QtCUPS + + + + + Lexmark + was one of the first companies to distribute their own Linux printer + drivers for some of their models. However, those drivers are binary only + (no source code available), and therefore cannot be used to integrate into + other Free printing software projects. + + + + + + Linuxprinting.org + Linuxprinting.org = not just for Linux; all &UNIX;-like OS-es, + like *BSD and commercial Unices may find useful printing + information on this site. This web site is the home for the interesting + Foomatic project, that strives to develop the "Meta Print Spool and Driver + Configuration Toolset" (being able to configure, through one common + interface, different print subsystems and their required drivers) with the + ability to transfer all queues, printers and configuration files seamlessly + to another spooler without new configuration effort. -- Also, they maintain + the Printing Database; a collection of driver and device information that + enables everybody to find the most current information about printer models, + and also generate online the configuration files for any + spooler/driver/device combo known to work with one of the common Linux or + &UNIX; print subsystems. + + Linuxprinting database + + + + + + Linuxprinting.org Database + ....Database containing printers and drivers that are suitable + for them... ...a lot of information and documentation to be found... ...it + is now also providing some tools and utilities for easing the integration + of those drivers into a given system... ...the "Foomatic" family + of utilities; being the toolset to make use of the database + for most of the commonly used print subsystems, for generating "on the fly" + working configurations for your printer model. + + Foomatic + + + + + LPR/LPD printing + LPR == some people translate Line + Printing Request, others: + Line Printer + Remote. + BSD-style printing + + + + + Magicfilter + Similarly to the APSfilter program, Magicfilter + provides automatic file type recognition functions and, base + on that, automatic file conversion to a printable format, + depending on the target printer. + APSfilter + + + + + &MIME;-Types + Abbreviation for Multipurpose (or + Multimedia) Internet Mail + Extensions; &MIME;-Types were first used to allow + the transport of binary data (like mail attachments containing + graphics) over mail connections that were normally only transmitting + ASCII characters: the data had to be encoded into an ASCII representation. + + Later this concept was extended to describe a data format in + a platform independent, but at the same time non-ambiguous, way. + From &Windows; everybody knows the .doc extensions for &Microsoft; Word files. + This is handled ambiguously on the &Windows; platform: .doc extensions are also + used for simple text files or for Adobe Framemaker files. And if a real + Word file is renamed with a different extension, it can no longer be + opened by the program. + + &MIME; typed files carry a recognition string with them, describing + their file format based on main_category/sub_category. + Inside IPP, print files are also described using the &MIME; type scheme. + &MIME; types are registered with the IANA (Internet Assigning Numbers + Association) to keep them unambiguous. + + &CUPS; has some &MIME; types of its own registered, like + application/vnd.cups-raster (for the &CUPS;-internal + raster image format). + + + &CUPS; + Easy Software Products + ESP PrintPro + Gimp-Print + + + + + PCL + Abbreviation for Printer + Control Language; + developed by &HP;. PCL started off in version 1 as a simple + command set for ASCII printing; now, + in its versions PCL6 and PCL-X, it is capable of printing graphics + and color -- but outside the &Microsoft; &Windows; realm and &HP-UX; + (&HP;'s own brand of &UNIX;), it is not commonly used... + ESC/P + &HP;/GL + PDL + &PostScript; + + + + + PDL + Abbreviation for Page + Description Language; + PDLs describe, in an abstract way, the graphical representation + of a page. - Before it is actually transferred into + toner or ink laid down on to paper, a PDL needs to be + "interpreted" first. In &UNIX;, the most important PDL + is &PostScript;. + + ESC/P + &HP;/GL + PCL + &PostScript; + + + + + Pixel + Abbreviation for Picture + Element; this term describes the smallest + part of a raster picture (either as printed on paper + or as displayed on a monitor by cathode rays or LCD elements). As + any graphical or image representation on those types of output + devices is composed of pixels, the values of "ppi" (pixel per inch) + and &dpi; (dots per inch) are one important parameter for the + overall quality and resolution of an image. + Filter + Ghostscript + &PostScript; + Raster + + + + + PJL + Abbreviation for Print + Job Language; + developed by &HP; to control and influence default and per-job + settings of a printer. It may not only be used + for &HP;'s own (PCL-)printers; also many &PostScript; + and other printers understand PJL commands sent to them + inside a print job, or in a separate signal. + PCL + + + + + &PostScript; + &PostScript; (often shortened to "PS") is the de-facto + standard in the &UNIX; world for printing files. It was + developed by Adobe and licensed to printer manufacturers + and software companies. + + As the &PostScript; specifications were + published by Adobe, there are also "Third Party" implementations + of &PostScript; generating and &PostScript; interpreting software + available (one of the best-known in the Free software world + being Ghostscript, a powerful PS-interpreter). + + ESC/P + &HP;/GL + PCL + PPD + + + + + PPD + Abbreviation for PostScript + Printer Description; + PPDs are ASCII files storing all information about the special + capabilities of a printer, plus definitions of the (PostScript- + or PJL-) commands to call on a certain capability (like print + duplexing). + + + As the explanation of the acronym reveals, PPDs were originally + only used for &PostScript; printers. &CUPS; has extended the + PPD concept to all types of printers. + + + PPDs for &PostScript; printers are provided by the printer + vendors. They can be used with &CUPS; and KDEPrint to have access + to the full features of any &PostScript; printer. The KDEPrint Team + recommends using a PPD originally intended for use with + &Microsoft; Windows NT. + + + PPDs for non-PostScript printers need a + companion "filter" to process the &PostScript; print files into + a format digestible for the non-PostScript target device. Those + PPD/filter combos are not (yet) available from the vendors. After + the initiative by the &CUPS; developers to utilize PPDs, the Free + Software community was creative enough to quickly come up with + support for most of the currently used printer models, through + PPDs and classical Ghostscript filters. But note: the printout + quality varies from "hi-quality photographic output" (using + Gimp-Print with most Epson inkjets) to "hardly readable" (using + Foomatic-enabled Ghostscript filters for models rated as + "paperweight" in the Linuxprinting.org database). + + &CUPS; + Linuxprinting.org + &PostScript; + + + + + PPD-O-Matic + PPD-O-Matic is a set of Perl scripts that run on the Linuxprinting.org + web server and can be used online to generate PPDs for any printer that is known + to print with Ghostscript. + + + These PPDs can be hooked up to &CUPS;/KDEPrint, as well as + used inside PPD-aware applications like StarOffice to determine all different + parameters of your printjobs. It is now recommended, in most cases, to + use "PPD-O-Matic" instead of the older &CUPS;-O-Matic. + + + To generate a PPD, go to the printer + database, select your printer model, follow + the link to show the available Ghostscript filters for that printer, select + one, click "generate" and finally save the file to your local system. + Be sure to read the instructions. Make sure that your local system + does indeed have Ghostscript and the filter, which you chose + before generating the PPD, installed. + + &PostScript; + &CUPS;-O-Matic + Linuxprinting.org + Foomatic + + + + + printcap + In BSD-style print systems, the "printcap" file holds + the configuration information; the printing daemon reads this file + to determine which printers are available, what filters are to be + user for each, where the spooling folder is located, + if there are banner pages to be used, and so on... + Some applications also depend on read access to the printcap + file, to obtain the names of available printers. + BSD-style printing + + + + + + Printer-MIB + Abbreviation for + Printer-Management + Information Base; the + Printer-MIB defines a set of parameters that are to be + stored inside the printer for access + through the network. This is useful if many (in some cases, literally + thousands) network printers are managed centrally + with the help of SNMP (Simple Network Management Protocol). + PWG + SNMP + + + + + PWG + Abbreviation for + Printer Working + Group; the PWG is a loose grouping of + representatives of the printer industry that has, in the past + years, developed different standards + in relation to network printing. These were later accepted by the + IETF as RFC standards, like the "Printer-MIB" and the IPP. + &PostScript; + IPP + Printer-MIB + SNMP + + + + + print:/ KIO Slave + You can use a syntax of "print:/..." to get quick access + to KDEPrint resources. Typing "print:/manager" as a Konqueror URL + address gives administrative access to KDEPrint. Konqueror uses &kde;'s + famous "KParts" technology to achieve that. + IO Slave + KParts + + + + + + Printer Database + . + Linuxprinting Database + + + + + Qt&CUPS; + Qt&CUPS; and KUPS were the predecessors of KDEPrint; they are now + deprecated and no longer maintained. What was good in qtcups is all inherited + by "kprinter", the new KDE print dialog (which is much improved over qtcups); + what you liked about kups is now all in the KDEPrint Manager (accessible + via the KDE Control Center or via the URL "print:/manager" from Konqueror) -- + with more functionality and less bugs... Its former developer, Michael Goffioul, is now + the developer of KDEPrint -- a very nice and productive guy and quick bug fixer... + + kprinter + + + + + Raster Image + Every picture on a physical medium + is composed of a pattern of discrete dots in different colors and (maybe) + sizes. This is called a "raster image". + + + This is as opposed to a "vector image" + where the graphic is described in terms of continuous curves, shades, + forms and filled areas, represented by mathematical formula. Vector images + normally have a smaller file size and may be scaled in size + without any loss of information and quality --- but they cannot be + output directly, but always have to be "rendered" or "rasterized" + first to the given resolution that the output device is capable of... + + + + The rasterization is done by a Raster Image Processor (RIP, + often the Ghostscript software) or some other filtering + instance. + Pixel + Ghostscript + &PostScript; + Filter + RIP + + + + + RIP + Abbreviation for + Raster Image + Process(or); if used in the context of + printing, "RIP" means a hardware or software + instance that converts &PostScript; (or other print formats + that are represented in one of the non-Raster PDLs) into a + raster image format in such a way that it is acceptable + for the "marking engine" of the printer. + + + &PostScript; printers + contain their own PostScript-RIPs. A RIP may or may not be located + inside a printer. + + + For many &UNIX; systems, Ghostscript is the package that provides + a "RIP in software", running on the host computer, and pre-digesting + the &PostScript; or other data to become ready to be sent to the + printing device (hence you may perceive a "grain of truth" in the + slogan "Ghostscript turns your printer into a &PostScript; + machine", which of course is not correct in the true sense of the + meaning). + Filter + Ghostscript + &PostScript; + PDL + Raster + + + + + + RLPR (Remote LPR) + Abbreviation for Remote + Line Printing + Request; this is a BSD-style printing system, + that needs no root privileges to be installed, and no "printcap" to + work: all parameters may be specified on the command + line. + + + RLPR comes in handy for many laptop users who are + working in frequently changing environments. This is because it + may be installed concurrently with every other printing + sub system, and allows a very flexible and quick + way to install a printer for direct access via LPR/LPD. + + + KDEPrint + has an "Add Printer Wizard" to make RLPR usage even easier. + The kprinter command allows switching to RLPR "on + the fly" at any time. + KDEPrint + kprinter + printcap + + + + + + SNMP + Abbreviation for Simple + Network Management + Protocol; SNMP is widely used to control + all types of network node (Hosts, Routers, Switches, Gateways, + Printers...) remotely. + PWG + Printer-MIB + + + + + SSL(3) encryption + Abbreviation for Secure + Socket Layer; + SSL is a proprietary encryption method for data + transfer over HTTP that was developed by Netscape. It is now being + replaced by an IETF standard named TLS. + + TLS + + + + + + SPOOLing + Abbreviation for Synchronous + Peripheral Operations + OnLine; + SPOOLing enables printing applications + (and users) to continue their work + as the job is being taken care of by a system daemon, + which stores the file at a temporary location until the printer is ready + to print. + Daemon + + + + + + TLS encryption + Abbreviation for Transport + Layer Security; + TLS is an encryption standard for + data transfered over HTTP 1.1; it is defined in RFC 2246; + although based on the former SSL development + (from Netscape) it is not fully compatible with it. + + SSL(3) + + + + + + System V-style printing + This is the second flavor of traditional &UNIX; + printing (as opposed to BSD-style printing). It uses + a different command set (lp, lpadmin,...) to BSD, + but is not fundamentally different from it. However, the + gap between the two is big enough to make the two + incompatible, so that a BSD-client cannot simply print + to a System V style print server without additional + tweaking... IPP is supposed to resolve this weakness + and more. + + BSD-style printing + IPP + + + + + TurboPrint + Shareware software providing photo quality printing for many + inkjet printers. It is useful if you are unable to find a driver for your + printer and may be hooked into either a traditional Ghostscript system + or a modern &CUPS; system. + Gimp-Print + + + + + XPP + Abbreviation for X + Printing Panel; + XPP was the first Free + graphical print command for &CUPS;, written by Till Kamppeter, + and in some ways a model for the "kprinter" utility in &kde;. + + + + + + + diff --git a/doc/kappfinder/Makefile.am b/doc/kappfinder/Makefile.am new file mode 100644 index 000000000..3f20a1e1b --- /dev/null +++ b/doc/kappfinder/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + +KDE_MANS = AUTO diff --git a/doc/kappfinder/man-kappfinder.1.docbook b/doc/kappfinder/man-kappfinder.1.docbook new file mode 100644 index 000000000..1c0fdb681 --- /dev/null +++ b/doc/kappfinder/man-kappfinder.1.docbook @@ -0,0 +1,81 @@ + + +]> + + + +JanSchaumann +jschauma@netmeister.org +April 8, 2003 + + + +kappfinder +1 + + + +kappfinder +An app to add installed applications to the &kde; menu. + + + + +kappfinder + directory + + + + + + + +Description + +The KDE application findern (&kappfinder;) looks for legacy and +third party applications that are installed on your system and adds +them to the KDE menu system. + + + + +Options + + + + directory + + +Install .desktop files into directory directory + + + + + + + + +See Also + +More detailed user documentation is available from help:/kappfinder (either enter this +URL into &konqueror;, or run +khelpcenter +help:/kappfinder). + + + + +Authors + +&kappfinder; was written by &Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail; + +This man page was prepared by Jan Schaumann +jschauma@netmeister.org for the Missing Man +Pages Project ( http://www.netmeister.org/misc/m2p2/index.html. + + + + diff --git a/doc/kate/Makefile.am b/doc/kate/Makefile.am new file mode 100644 index 000000000..17a314c39 --- /dev/null +++ b/doc/kate/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kate/TODO b/doc/kate/TODO new file mode 100644 index 000000000..d41ed4b80 --- /dev/null +++ b/doc/kate/TODO @@ -0,0 +1,6 @@ +Fill empty sections. +Rewrite intro chapter. +Write regexp appendix. +Add Misc Tools chapter, ao Find in Files. +Go over everything and make sure it reflects the practial truuth ;) +Add links to foreign documentation. diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook new file mode 100644 index 000000000..b9b0cda91 --- /dev/null +++ b/doc/kate/advanced.docbook @@ -0,0 +1,1242 @@ + + + +&Anders.Lund; &Anders.Lund.mail; +&Dominik.Haumann; &Dominik.Haumann.mail; + + + +Advanced Editing Tools + + + +Comment/Uncomment + +The Comment and Uncomment commands, available from the +Tools menu allow you to add or remove comment +markers to the selection, or the current line if no text is selected, +if comments are supported by the format of the text you are +editing. + +The rules for how commenting is done are defined in the syntax +definitions, so if syntax highlighting is not used, commenting/uncommenting +is not possible. + +Some formats define single line comment markers, some multiline +markers and some both. If multiline markers are not available, +commenting out a selection that does not fully include its last line +is not possible. + +If a single line marker is available, commenting single lines is +preferred where applicable, as this helps to avoid problems with +nested comments. + +When removing comment markers, no uncommented text should be +selected. When removing multiline comment markers from a selection, +any whitespace outside the comment markers is ignored. + +comment +To place comment markers, use the +ToolsComment +menu item or the related keyboard shortcut sequence, default is +&Ctrl;D. + +uncomment +To remove comment markers, use the +ToolsUncomment +menu item or the related keyboard shortcut, default is &Ctrl;&Shift;D. + + + + +The Editor Component Command Line + +Kate's editor component has an internal command line, allowing you to +perform various actions from a minimal GUI. The command line is a text entry +in the bottom of the editor area, to show it select +ViewSwitch to Command Line +or use the shortcut (default is +F7). The editor provides +a set of commands as documented below, and additional commands can be provided +by plugins. + +To execute a command, type the comand then press the return key. The +command line will indicate wether it succeded and possibly display a message. If +you entered the command line by pressing F7 it will +automatically hide after a few seconds. To clear the message and enter a new +command, press F7 again. + +The command line has a built-in help system, issue the command +help to get started. To see a list of all available commands +issue help list, to view help for a specific command, do +help command. + +The command line has a built in history, so you can reuse commands already +typed. To navigate the history, use the Up and +Down keys. When showing historical commands, the argument part +of the command will be selected, allowing you to easily overwrite the +arguments. + + +Standard Command Line Commands + + +Commands for Configuring the Editor + +These commands are provided by the editor component, and allows you to +configure the active document and view only. This is handy if you want to use +a setting different from the default settings, for example for indentation. + + + +Argument types + + +BOOLEAN +This is used with commands that turns things on or off. +Legal values are on, off, +true, false, +1 or 0 + + + +INTEGER +An integer number + + + +STRING +A string + + + + + + + +set-tab-widthINTEGER width +Sets the tab width to the number width + + + +set-indent-widthINTEGER width +Sets the indentation width to the number +width. Used only if you are indenting with +spaces. + + + +set-word-wrap-columnINTEGER width +Sets the line width for hard wrapping to +width. This is used if you are having your text wrapped +automatically. + + + +set-icon-borderBOOLEAN enable + +Sets the visibility of the icon border. + + + +set-folding-markersBOOLEAN enable +Sets the visibility of the folding markers pane. + + + +set-line-numbersBOOLEAN enable +Sets the visibility of the line numbers pane. + + + +set-replace-tabsBOOLEAN enable +If enabled, tabs are replaced with spaces as you type. + + + + +set-remove-trailing-spaceBOOLEAN enable +If enabled, trailing whitespace are removed whenever the cursor +leaves a line. + + + +set-show-tabsBOOLEAN enable +If enabled, TAB characters and trailing whitespace will be +visualized by a small dot. + + + +set-indent-spacesBOOLEAN enable +If enabled, the editor will indent with + spaces for each indentation level, rather than +with one TAB character. + + + +set-mixed-indentBOOLEAN enable +If enabled, kate will use a mix of TAB and spaces for +indentation. Each indentation level will be wide, +and more indentation levels will be optimized to use as many TAB characters as +possible. +When executed, this command will additionally set space indentation enabled, +and if the indent width is unspecified it will be set to half of the + for the document at the time of execution. + + + +set-word-wrapBOOLEAN +enable +Enables dynamic word wrap according to +enable + + + +set-replace-tabs-saveBOOLEAN enable + +When enabled, tabs will be replaced with whitespace whenever + the document is saved. + + + +set-remove-trailing-space-saveBOOLEAN enable +When enabled, trailing space will be removed from each line +whenever the document is saved. + + + +set-indent-modename +Sets the autoindentation mode to name. +If name is not known, the mode is set to 'none'. Valid +modes are 'cstyle', 'csands', 'xml', 'python', 'varindent' and 'none'. + + + +set-highlighthighlight +Sets the syntax highlighting system for the document. The +argument must be a valid highlight name, as seen in the +ToolsHighlighting +menu. This command provides an autocompletion list for its +argument. + + + + + + + +Commands for editing + +These commands modify the current document. + + + +indent +Indents the selected lines or the current line. + + + +unindent +Unindents the selected lines or current line. + + + +cleanindent +Cleans up the indentation of the selected lines or current line +according to the indentation settings in the document. + + + + +comment +Inserts comment markers to make the selection or selected lines +or current line a comment according to the text format as defined by the syntax +highlight definition for the document. + + + +uncomment +Removes comment markers from the selection or selected lines +or current line according to the text format as defined by the syntax highlight +definition for the document. + + + +kill-line +Deletes the current line. + + + +replacepatternreplacement +Replaces text matching pattern with +replacement. If you want to include whitespace in the +pattern, you must quote both the pattern +and replacement with single or double quotes. If the +arguments are unquoted, the first word is used as pattern +and the rest for replacement. If +replacement is empty, each occurrence of +pattern is removed. +You can set flags to configure the search by adding a colon, followed +by one or more letters each representing a configuration, giving the form +replace:options pattern replacement. Available options +are: + + + + +b +Search backwards. + + + +c +Search from cursor position. + + + +e +Search in the selection only. + + + +r +Do regular expression search. If set, you may use +\N where N is a number to represent captures in the +replacement string. + + + +s +Do case sensitive search. + + + +p +Prompt for permission to replace the next occurence. + + + +w +Match whole words only. + + + + + + + + + +dateformat +Inserts a date/time string as defined by the specified +format, or the format yyyy-MM-dd hh:mm:ss +if none is specified. The following translations are done when interpreting +format: + + + + +dThe day as number without a leading zero (1-31). +ddThe day as number with a leading zero (01-31). +dddThe abbreviated localized day name (e.g. 'Mon'..'Sun'). +ddddThe long localized day name (e.g. 'Monday'..'Sunday'). +MThe month as number without a leading zero (1-12). +MMThe month as number with a leading zero (01-12). +MMMThe abbreviated localized month name (e.g. 'Jan'..'Dec'). +yyThe year as two digit number +(00-99). +yyyyThe year as four digit number (1752-8000). +hThe hour without a leading zero (0..23 or 1..12 if AM/PM display). +hhThe hour with a leading zero (00..23 or 01..12 if AM/PM display). +mThe minute without a leading zero (0..59). +mmThe minute with a leading zero (00..59). +sThe second without a leading zero (0..59). +ssThe second with a leading zero (00..59). +zThe milliseconds without leading zeroes (0..999). +zzzThe milliseconds with leading zeroes (000..999). +APUse AM/PM display. AP will be replaced by either "AM" or "PM". +apUse am/pm display. ap will be replaced by either "am" or "pm". + + + + + + + + + +charidentifier + +This command allows you to insert literal characters by their +numerical identifier, in decimal, octal or hexadecimal form. +To use it launch the Editing Command dialog and type char: +[number] in the entry box, then hit +OK. + + +<command>char</command> examples + +Input: char:234 +Output: ê +Input: char:0x1234 +Output: ሴ + + + + + + + +replace, sed style +search, sed style +s///[ig] %s///[ig] + + +This command does a sed-like search/replace operation on the +current line, or on the whole file (%s///). + +In short, the text is searched for text matching the +search pattern, the regular expression between +the first and the second slash, and when a match is found, the +matching part of the text is replaced with the expression between the +middle and last part of the string. Parentheses in the search pattern +create back references, that is the command +remembers which part of the match matched in the parentheses; these +strings can be reused in the replace pattern, referred to as +\1 for the first set of parentheses, +\2 for the second and so on. + +To search for a literal ( or +), you need to escape it using +a backslash character: \(\) + +If you put an i at the end of the +expression, the matching will be case insensitive. If you put a +g at the end, all occurrences of the pattern will be +replaced, otherwise only the first occurrence is replaced. + + + +Replacing text in the current line + +Your friendly compiler just stopped, telling you that the class +myClass mentioned in line 3902 in your source file +is not defined. + +"Buckle!" you think, it is of course +MyClass. You go to line 3902, and instead of trying +to find the word in the text, you launch the Editing Command Dialog, +enter s/myclass/MyClass/i, hit the +OK button, save the file and compile – +successfully without the error. + + + + +Replacing text in the whole file + +Imagine that you have a file, in which you mention a Miss +Jensen several times, when someone comes in and tells you that +she just got married to Mr Jones. You want, of course, +to replace each and every occurrence of Miss Jensen +with Ms Jones. + +Enter the command line and issue the command +%s/Miss Jensen/Ms Jones/ and hit return, you +are done. + + + + +A More Advanced Example + +This example makes use of back references +as well as a character class (if you do not know what +that is, please refer to the related documentation mentioned +below). + +Suppose you have the following line: + +void MyClass::DoStringOps( String &foo, String &bar String *p, int &a, int &b ) + +Now you realize that this is not nice code, and decide that you +want to use the const keyword for all +address of arguments, those characterized by the & +operator in front of the argument name. You would also like to +simplify the white space, so that there is only 1 whitespace character +between each word. + +Launch the Editing Command Dialog, and enter: +s/\s+(\w+)\s+(&)/ const \1 \2/g and hit the +OK button. The g at the end of the expression makes +the regular expression recompile for each match to save the backreferences. + +Output: + +void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b ) + +Mission completed! Now, what happened? Well, we looked for some +white space (\s+) followed by one or more +alphabetic characters (\w+) followed by some more +whitespace (\s+) followed by an ampersand, and in +the process saved the alphabetic chunk and the ampersand for reuse in +the replace operation. Then we replaced the matching part of our line +with one whitespace followed by const followed by one +whitespace followed by our saved alphabetical chunk +(\1) followed by one whitespace followed by our +saved ampersand (\2) + +Now in some cases the alphabetical chunk was +String, in some int, so using the +character class \w and the + +quantifier proved a valuable asset. + + + + + + + + + + + + +Commands for navigation + + + + +gotoINT line +This command navigates to the specified line. + + + +findpattern +This command navigates to the first occurrence of +pattern according to the configuration. Following +occurrences can be found using +EditFind Next +(the default shortcut is F3). +The find command can be configured by appending a colon followed by one or +more options, the form is +find:options pattern. The +following options are supported: + + + + +b +Search backwards. + + + +c +Search from cursor position. + + + +e +Search in the selection only. + + + +r +Do regular expression search. If set, you may use +\N where N is a number to represent captures in the +replacement string. + + + +s +Do case sensitive search. + + + +w +Match whole words only. + + + + + + + + + + + +ifindpattern +This command provides as-you-type searching. You +can configure the behavior of the search by appending a colon +followed by one or more options, like this: +ifind:options pattern. Allowed options are + + + +b +Search backwards. + + + +r +Do regular expression search. + + + +s +Do case sensitive search. + + + +c +Search from cursor position. + + + + + + + + + + + + + + + +Using Code Folding + +Code folding allows you to hide parts of a document in the editor, making +it easier to overview large documents. In &kate; the foldable regions are +calculated using rules defined in the syntax highlight definitions, and +therefore it is only available in some formats - typically program source code, +XML markup and similar. Most highlight definitions supporting code folding +also lets you manually define foldable regions, typically using the +BEGIN and END keywords. + +To use the code folding feature, activate the folding markers using +ViewShow Folding +Markers menu item if they are not already visible. +The Folding Markers Pane in the left side of the screen displays a graphical +view of the foldable regions, with +/- signs to indicate the possible operation +on a given region: a - means that the region is expanded, clicking the - will +collapse the region and a + will be displayed instead. + +Four commands are provided to manipulate the state of folding regions, +see the menu documentation. + + +If you do not want to use the code folding feature, you can disable +the Show folding markers (if available) option in the +Appearance page of the editor +configuration + + + + + +Scripting the editor component with Javascript + + + +Introduction + +Starting with version 2.5, the &kate; editor component supports +scripting with ECMA script, also known as JavaScript. + +Scripts can be used through the built in command line +only. The requirements is that the script is placed in a folder where &kate; +can find it, along with an optional .desktop file that defines the related +properties. The valid folder are named katepart/scripts +in the &kde; data folders. You can find the data folders by running the command +kde-config data +You will usually have at least a system and a personal data folder. Of course +scripts in the system data folder are available to all users on the system, +while those in the personal folder are available for you only. + +This feature is experimental and will most likely change during +future development. +We know that many of you will be disappointed because you can't add +your scripts to the menu or assign shortcuts to them. Sorry, sometime +in the future that will likely be possible. +It is also not possible to pass any arguments to your scripts yet. Be +patient, and that may be added in the bright future ;) + + + + + + +The Kate JavaScript API + +Here is listed the complete set of functions and properties available +in the document and view objects. +In addition you can of course use all the standard objects such as +Math, String Regex and so forth. + +When a script is run, the document object is the +current document, and the view object is the current +view. + +The types of arguments are of course not used in JavaScript at +this time, they are there solely to indicate what sort of value the funcitons +expect. + + +Global Functions + +debug( string) +[function] + + +parameters +string the string to output + + +Outputs the string to STDERR using +kdDebug(). A dedicated output area is used for the output, +which will be prefixed Kate (KJS Scripts): + + + + + + +The <classname>document</classname> API + + +document.attribute( line +, column ); + [function] + + +Parameters +uint line The line of the position for which +to find the attribute. +uint column The column of the position for +which to find the attribute. + +Returns the numeric ID of the attribute for the document position +[line,column]. The attribute +represents the visual appearance or style of the text, and is also used to +calculate the syntax highlight for a specific part of the text in mixed formats +like HTML or PHP. + + + + +document.canBreakAt( Char c, +uint attribute ); [function] + + +Parameters +c The character to test +attribute The attribute at the position +of c. + +Returns whether it is allowed to break the line at a character c with +attribute attribute. The result is decided by querying the highlight owning +attribute for which characters allow breaking the line. + + + + +document.canComment( uint start_attribute, +uint end_attribute ); [function] + + +Parameters +start_attribute The attribute at the +start of the range to turn into a comment. +end_attribute The attribute at end of +the range to turn into a comment. + +Returns whether start_attribute and end_attribute belongs to the same +syntax highlight system. If they do, it is sane. + + +using canComment + +if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) { + // 1,0 and 5,0 belongs to the same syntax highlighting system +} + + + + + + +document.clear(); [function] +Clears the document. + + + +document.commentStart( uint attribute ); +[function] + + +Parameters +attribute The attribute of the text for +which to get the commentStart string. + +Returns the string required to start a multiline comment for a text with +attribute, or an empty string if multiline comments are not supported for that +text. + + + + +document.commentMarker( uint attribute ); +[function] + + +Parameters +attribute The attribute of the text for +which to get the commentMarker string + +Returns the string used to mark the rest of the line as a comment for a +text with attribute or an empty string if single line comments are not supported +for that text. + + + + +document.commentEnd( uint attribute ); +[function] + + +Parameters +attribute The attribute of the text for +which to get the commentEnd string + +Returns the string required to end a multiline comment for a text with +attribute, or an empty string if multiline comments are not supported for that +text. + + + + +document.editBegin(); [function] + +Start an editing group. All actions done until the call of editEnd() will +be grouped as one undo-action. + + + + +document.editEnd(); [function] + +Finish an editing group. + + + + +document.highlightMode; [property:read only] + +The name of the document's highlight mode, such as JavaScript or C++. +If no syntax highlight mode is set for the document, the value is None. Notice +that you need to use the English name in cases where it differs from the +translated one. + + + + +document.indentMode; [property:read only] + +The name of the document indent mode, such as +normal or cstyle. +Remember that if no indent mode is set, the value is none. + + + + + +document.indentWidth; [property:read only] + +The indentation width set for the document. This is used if space +indenting is enabled. + + + + +document.insertLine( uint line, +string text ); [function] + + +Parameters +line document line number + +text text to insert + +Inserts a new line with the text text at the +line line. + + + + +document.insertText( uint line, +uint column, string text ); +[function] + + +Parameters +line the line number +column the column +text the text which is to be +inserted + +Inserts the text text in line +line and column column. + + + + +document.length(); [function] + +Returns the document's size in bytes. + + + + +document.lines(); [function] + +Returns the number of lines in the document. + + + + +document.mixedIndent; [property:read only] + +A boolean telling whether the mixed-indent setting is enabled for the +document. If so, indentation is optimized to contain a mix of tab characters and +spaces like used by the Emacs editor. + + + + +document.removeLine( uint line ); [function] + + +Parameters +line line number + +Removes the document line line. + + + + +document.removeText( uint startLine, +uint startColumn, uint endLine, +uint endColumn ); [function] + + +Parameters +startLine specifies the beginning +line +startColumn specifies the beginning +column +endLine specifies the ending +line +endColumn specifies the ending +column + +Removes the text range from line startLine and +column startColumn up to line +endLine and column endColumn. + + + + + +document.setText( string text ); +[function] + + +Parameters +text document text + +Sets the entire document content to text. + + + + +document.spaceIndent; [property:read only] + +A boolean telling whether space-indent is enabled for the document. +If so, the document is indented with indentWidth spaces pr level, otherwise +indentation is one tab character pr. level. + + + + +document.textFull(); [function] + +Returns the full document text. If the text spans over multiple lines the +linefeed character is \n. + + + + +document.textLine( uint line ); [function] + + +Parameters +line the line + +Returns the text of line line. + + + + +document.textRange( uint startLine, +uint startColumn, uint endLine, +uint endColumn ); [function] + + +Parameters +startLine specifies the beginning +line +startColumn specifies the beginning +column +endLine specifies the ending line + +endColumn specifies the ending +column + +Returns the specified text range. If the range spans over multiple lines +the linefeed character is \n. + + + + + + +The <classname>view</classname> API + + +view.clearSelection(); [function] + +Deselects all text. + + + + +view.cursorColumn(); [function] + +Returns the current cursor column (TAB characters are expanded). + + + + +view.cursorColumnReal(); [function] + +Returns the current real cursor column (TAB characters counts one). + + + + +view.cursorLine(); [function] + +Returns the current cursor line. + + + + +view.hasSelection(); [function] + +Returns true if the view contains selected text, +otherwise false. + + + + +view.removeSelectedText(); [function] + +Removes the selected text, if the view has a selection. + + + + +view.selectAll(); [function] + +Selects all text. + + + + +view.selection(); [function] + +Returns the selected text. If the selection spans over multiple lines the +linefeed character is \n. + + + + +view.selectionEndColumn; [property:read only] + +Returns the ending column of the selection. + + + + +view.selectionEndLine; [property:read only] + +Returns the ending line of the selection. + + + + +view.selectionStartColumn; [property:read only] + +Returns the starting column of the selection. + + + + +view.selectionStartLine; [property:read only] + +Returns the starting line of the selection. + + + + +view.setCursorPosition( uint line, +uint column ); [function] + + +Parameters +line Specifies the line for the +cursor. +column Specifies the column for the +cursor. + +Sets the input cursor position in the view to [line, +col]. This sets the cursor position by visual means, +that is the a TAB character counts up to tabwidth +depending on the position inside the line. The cursor position is made visible. +Both line and column are zero-based. + + + + +view.setCursorPositionReal( uint line, +uint column ); [function] + + +Parameters +line Specifies the line for the +cursor. +column Specifies the column for the +cursor. + +Sets the input cursor position to [line, +col]. This sets the string position, that is a TAB +character counts for 1. The cursor position is made visible. Both line and +column are zero-based. + + + + +view.setSelection( uint startLine, +uint startColumn, uint endLine, +uint endColumn ); [function] + + +Parameters +startLine specifies the beginning line +startColumn specifies the beginning column +endLine specifies the ending line +endColumn specifies the ending column + +Sets a selection from line startLine and column +startColumn up to line endLine +and column endColumn. + + + + + + + +A sample script +As an example we will create a small script that uppercases the selection. +It is obvious that we first need to check whether a selection exists, if so we +get the text, change the case and then replace it with the new one. An +implementation could look like this: + + +if ( view.hasSelection() ) +{ + // uppercase selection + column = view.selectionStartColumn; + line = view.selectionStartLine; + + selection = view.selection().toUpperCase(); + + document.editBegin(); + view.removeSelectedText(); + document.insertText( line, column, selection ); + document.editEnd(); +} + + +To group this action together so that they will be reverted by a single +activation of Undo we encapsulate the lines +view.removeSelectedText() and +document.insertText() with a +document.editBegin() and +document.editEnd(). + + + + +A sample <filename>.desktop</filename> file + +Here is a sample .desktop file that accompanies the above script. + + +# Example of a .desktop file +[Desktop Entry] +Encoding=UTF-8 +Name=Kate Part JavaScript Uppercase +Comment=Script to uppercase the selection +X-Kate-Command=uppercase-selection +X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p> + + +As you can see you can define the Encoding, set a Name, a Comment, a help +text using X-Kate-Help and the command line name via X-Kate-Command. The entries +Name, Comment and X-Kate-Help are automatically translated into other languages +by the KDE translation teams, if the files are in KDE's SVN repository. + + + + +Putting it togeather + +&kate; will search the script folders (see above) for +*.js files. For every file it checks whether there is a +corresponding .desktop file, like for uppercase.js it +would look for uppercase.desktop. +If a .desktop file can not be found the script will +be registered in katepart's command line with the filename without the ending +.js, so in our example this would be uppercase. If the +command-name is fine and you don't need the extra features a +.desktop file provides you do not need a +.desktop file at all. +If a .desktop file exists katepart will read the name +under which the script will be registered from the .desktop-entry +X-Kate-Command, for example X-Kate-Command=uppercase-selection. + + + + + + + + diff --git a/doc/kate/configdialog01.png b/doc/kate/configdialog01.png new file mode 100644 index 000000000..751066792 Binary files /dev/null and b/doc/kate/configdialog01.png differ diff --git a/doc/kate/configdialog02.png b/doc/kate/configdialog02.png new file mode 100644 index 000000000..70a7ecaed Binary files /dev/null and b/doc/kate/configdialog02.png differ diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook new file mode 100644 index 000000000..14642c74c --- /dev/null +++ b/doc/kate/configuring.docbook @@ -0,0 +1,1595 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Configuring &kate; + + +Overview + + +configure +settings +preferences + + + + + + + +&kate; offers several means of tweaking the application to behave as desired. +The most important ones are: + + + + +The Configuration Dialog +The main configuration tool, allowing you to configure the &kate; application, +the editor component and the usage of plugins. + + +The Settings Menu +Allows you to change often used settings, and to +launch the configuration dialogs. + + +The View Menu +Allows you to split the current frame, as well as to +display the icons and line numbers pane for the currently edited +document. + + + +The embedded &konsole; is using the configuration defined in the +&kcontrolcenter;, and may be configured by clicking the +right mouse button and choosing from the +Settings sub menu. + + + + +The Main Configuration Dialog + + + + + + + +The &kate; configuration dialog displays a tree of topics on the +left, and a configuration page corresponding to the selected topic on +the right. + +The configuration is divided into two groups, namely + +Application configuration + +Editor component configuration + + + + + + + + +The &kate; Application Configuration +This group contains pages to configure the main &kate; application + + +The General Page +This section contains a few global options for &kate; + + + + + +Show Full Path in Title +When enabled, Kate will display the full URL of your +current document in the window title, rather than just the file name. + + + + + +Behavior + + + + + +Sync Konsole with Active Document +This will cause the built-in &konsole; to +cd into the directory of the active document when +launched and when a new document gets the focus. If not enabled, you +have to do all your navigation in the &konsole; on your own. + + + + + +Warn about files modified by foreign processes +When enabled, &kate; will notify you about files modified +from outside the application whenever the main window receives input focus. +You will be able to deal with several modified files at once, you +can reload, save or discard changed files in groups. +If not enabled, &kate; will prompt you for action when a externally +modified file receives focus within the application. + + + + + + + + + +Meta Data + + + + + +Keep meta-information past sessions +When enabled, &kate; will store meta data such as bookmarks +and session configuration even when you close your documents. The data +will be used if the document is unchanged when reopened. + + + + +Delete unused meta information after +Set the maximum number of days to keep meta information +for unopen files. This helps keeping the database of meta information +reasonably sized. + + + + + + + + + + + +The Sessions Page + +This section contains options related to using sessions. + + + + + +Elements of Sessions + + + +Include window configuration +If enabled, &kate; will save the window configuration +with each session. + + + + + + + +Behavior on Application Startup + +Select how you want &kate; to behave at startup. This setting can be +overridden by specifying what to do on the command line. + + +Start new session +With this option, &kate; will start a new, unnamed session +when you start it. + + +Load last used session +&kate; will use the most recently opened session at +startup. This is good if you want to use the same session always or switch +rarely. + + +Manually choose a session +&kate; will display a small dialog that lets you choose +your preferred session. This is the default behavior. Nice if you use a lot of +different sessions frequently. + + + + + + + +Behavior on Application Exit or Session Switch + + + +Do not save session +The changes to the session data (open files and if enabled, +window configuration) will not be saved. You will of course be prompted if you +have unsaved files. With this option, your can configure your sessions once, and +not worry about closing extra files that you opened and do not want to see +next time you use the session. + + +Save Session +&kate; will save session data, except if the session is unnamed. +With this option, your sessions are allways restored just like you left them. +This is the default behavior. + + + +Ask user +You will be asked if you want to save the session every time a +named session is closed. + + + + + + + + + + +The <guilabel>Filesystem Browser</guilabel> Page + + + +Toolbar +Configure the buttons on the file system browser toolbar +by moving the ones you want enabled to the Selected Actions +list, and order them using the arrow buttons at the side of the list. + + + + +Auto Synchronization +You can have the filesystem browser automatically navigate to +the directory containing the current document on certain events: + +When a new document becomes the active one. +When the filesystem browser becomes visible. + +Even if you select not to use this feature, you can manually synchronize the +browser with the current document by pressing the +Synchronize toolbar button. + + + + +Remember locations +Select how long a browsing history you want. The browser does +only remember individual locations, duplicates are removed. + + + +Remember filters +Select how many filters you want remembered. Only individually +distinct filters are remembered, duplicates are removed. + + + +Session + +Configure wether the file system browser should remember its location and +filter over sessions. + + + + + + + + +The <guilabel>Doucment List</guilabel> Page + + + +Backgound Shading +This section allows you to enable or disable the background +shading visualization of your recent activity, and chose which colors to use if +enabled. See the section about The Document List for more about +this feature. + + +Sort By +Set how you want the document list sorted. This can be set +from the &RMB; menu in the document list as well. + + + + + + +The <guilabel>Plugins</guilabel> Page + +This page provides a list of installed plugins for the &kate; +application. Each plug-in is represented with its name and a short description. +You can check the checkbox with an item to enable the plug-in it represents. + + +If a plug-in provides configuration options, a section to access those +will appear as a child of this page. + + + + + +External Tools + +In the Tools menu you will find a submenu labeled +External Tools. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection. This page allows you to manage the menu and edit, +remove or add new tools. + +Each external tool is a shell command which contains macros representing +the document data. When activated, the macros are substituted with data from the +active document. + + +External Tools Properties + +Label +A friendly label for the External Tools menu. + + + +Script +The script to execute when the tool is activated. Before passing +the script to the shell, the following macros are substituted: + + + +%URL +The full URL of the current document, or an empty string if the +document is unsaved. + + + +%URLS +A space seperated list of the URLs of all open documents +(except unsaved ones). + + + +%directory +The directory part of the current documents URL or an empty +string if the current document is unsaved. + + + +%filename +the filename of the current document without the path, or an +empty string if the current document is unsaved. + + + +%line +The line number of the insertion cursor is in the current +document. + + + +%column +The column number of the insertion cursor in the current +document. + + + +%selection +The selected text in the current document, or an empty string +if no text is selected + + + +%text +The full text of the current document. Beware that this will +potentially exceed the maximum command length allowed on your system. +Use with care. + + + + + + + + +Executable +The main executable is the script. This is mandatory, and is used +to test if the command can be run at all. A fully qualified path is allowed +in case the executable is not in your PATH variable. + + + +Mimetypes +A semicolon separated list of mimetypes for which this command +should be enabled. This is currently unused. + + + +Save +You can optionally select to have the current or all documents +saved prior to executing the script. This is handy if your script reads the file +from disk. + + + +Command Line Name +If you fill this, the tool will be available in the +editors command line as +exttool-Command Line Name +(the string you enter here prepended exttool-). + + + + + + + + + +The Editor Component Configuration +This group contains all pages related to the editor component of +&kate;. Most of the settings here are defaults, they can be overridden by +defining a filetype, +by Document Variables or by changing +them pr. document during an editing session. + + + +Appearance + + + +Word Wrap + + + +Dynamic word wrap +If this option is checked, the text lines +will be wrapped at the view border on the screen. + + +Dynamic word wrap indicators +Choose when the Dynamic word wrap indicators +should be displayed. + + +Vertically align dynamically wrapped lines +to indentation depth: + +Enables the start of dynamically wrapped +lines to be aligned vertically to the indentation level of the first +line. This can help to make code and markup more +readable.Additionally, this allows you to +set a maximum width of the screen, as a percentage, +after which dynamically wrapped lines will no longer be vertically aligned. +For example, at 50%, lines whose indentation levels are deeper than 50% of the +width of the screen will not have vertical alignment applied to subsequent +wrapped lines. + + + + + + +Code Folding + + + +Show folding markers (if available) + +If this option is checked, the current view will display marks +for code folding, if code folding is available. + + + + + + +Borders + + + +Show icon border + +If this is checked, you will see an icon border on the left +hand side. The icon border shows bookmark signs for instance. + + +Show line numbers + +If this is checked, you will see line numbers on the left +hand side. + + +Show scrollbar marks + +If this option is checked the current view +will show marks on the vertical scrollbar. These marks will +for instance show bookmarks. + + + + + + +Sort Bookmarks Menu + + + + +By position + +The bookmarks will be ordered by the line +numbers they are placed at. + + +By creation + +Each new bookmark will be added to the bottom, +independently from where it is placed in the document. + + + + + + +Show identation lines + +If this is checked, the editor wil display +vertical lines to help identifying indent lines. + + + + + +Fonts & Colors + +This section of the dialog lets you configure all fonts and colors in +any color scheme you have, as well creating new schemes or deleting existing +ones. Each scheme has settings for colors, fonts and normal and highlight text +styles. + + +&kate; will preselect the currently active scheme for you, if you want to +work on a different scheme start by selecting that from the +Schema combobox. + + +Colors + + + +Text Area Background + + + + + +Normal text +This is the default background for the editor area, it will be +the dominant color on the editor area. + + + +Selected Text +This is the background for selected text. The default is +the global selection color, as set in your &kde; color preferences. + + + + +Current Line +Set the color for the current line. Setting this a bit different +from the Normal text background helps to keep focus on the current line. + + + + +Bookmark +This combo lets you set overlay colors for various mark types. +The color is mixed into the background color of a marked line, so that a line +with more marks or a marked line that is current has a background that is a mix +of more colors. The mark colors are also used if you enable display of scrollbar +marks. + + + + + + + +Other Elements + + + +Left Border Background +This color is used for the marks, line numbers and folding +marker borders in the left side of the editor view when they are displayed. + + + +Line Numbers +This color is used to draw the line numbers on the left side of +the view when displayed. + + +Bracket Highlight +This color is used to draw the background of matching brackets. + + + +Word Wrap Markers +This color is used to draw a pattern to the left of dynamically +wrapped lines when those are aligned vertically, as well as for the static word +wrap marker. + + +Tab Markers +This color is used to draw white space indicators when enabled. + + + + + + + + + + +Fonts + +Here you can choose the font for the schema. You can choose from +any font available on your system, and set a default size. A sample text +displays at the bottom of the dialog, so you can see the effect of your choices. + + + + +Normal Text Styles +The normal text styles are inherited by the highlight text styles, +allowing the editor to present text in a very consistent way, for example comment +text is using the same style in allmost all of the text formats that kate can +highlight. +The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. + +Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. + + + +Highlighting Text Styles +Here you can edit the text styles used by a specific highlight definition. +The editor preselects the highlight used by your current document. To work on a +different highlight, select one in the Highlight combobox +above the style list. + +The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. + +Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. In addition you can see if a style is equal to the default style +used for the item, and set it to that if not. +You will notice that many highlights contain other highlights represented +by groups in the style list. For example most highlights import the Alert +highlight, and many source code formats imports the Doxygen highlight. Editing +colors in those groups only affects the styles when used in the edited highlight +format. + + + + + + +Cursor & Selection + + + + +Text Cursor Movement + + + +Smart home + +When selected, pressing the home key will cause the cursor to +skip white space and go to the start of a line's text. + + + +Wrap cursor + +When on, moving the insertion cursor using the Left and Right keys will +go on to previous/next line at beginning/end of the line, similar to most +editors.When off, the insertion cursor cannot be moved left of the +line start, but it can be moved off the line end, which can be very handy for +programmers. When this option is chosen, moving the cursor with the arrow keys +off the end of a line (to the right) causes it to jump down to the beginning of +the next line. Likewise when the cursor is moved past the beginning of a line +(to the left) it jumps up to the end of the preceding line. When this option is +not selected, moving the cursor right past the end of a line merely causes it to +continue horizontally in the same line and trying to move it left past the +beginning does nothing. + + + +Page Up/Page Down moves cursor + +This option changes the behavior of the cursor when the user presses +the Page Up or Page Down key. If unselected +the text cursor will maintain its relative position within the visible text in +&kate; as new text becomes visible as a result of the operation. So if the +cursor is in the middle of the visible text when the operation occurs it will +remain there (except when one reaches the beginning or end.) With this option +selected, the first key press will cause the cursor to move to either the top or +bottom of the visible text as a new page of text is displayed. + + + +Autocenter cursor (lines): + +Sets the number of lines to maintain visible above and below the cursor +when possible. + + + + + + + +Selection Mode + + + +Normal + +Selections will be overwritten by typed text and will be lost on +cursor movement. + + + +Persistent + +Selections will stay even after cursor movement and typing. + + + + + + + + + + +Editing + + + +Tabulators + + + +Insert spaces instead of tabulators + +When this is enabled the editor will insert a calculated number of spaces +according to the position in the text and the setting +when you press the TAB key. + + + +Show tabulators + +When this is enabled &kate; will display a small dot as a visual +representation of tabulator characters. +This also causes dots to be drawn to indicate trailing white space. +This will be fixed in a future version of &kate; + + + +Tab Width If the +Replace Tabs By +Spaces +option is selected this entry determines the number of +spaces with which the editor will automatically replace +tabs. + + + + + + +Static Word Wrap + +Word wrap is a feature that causes the editor to automatically start a new line +of text and move (wrap) the cursor to the beginning of that new line. &kate; +will automatically start a new line of text when the current line reaches the +length specified by the Wrap Words +At: option. + + +Enable static word wrap + +Turns static word wrap on or off. + + + +Show static word wrap markers +(if applicable) + +If this option is checked, a vertical line will be drawn at the word wrap +column as defined in the Settings +Configure Editor... in the Editing tab. +Please note that the word wrap marker is only drawn if you use a fixed pitch +font. + + + +Wrap words at: + +If the Word Wrap option is selected +this entry determines the length (in characters) at which the editor will +automatically start a new line. + + + + + + + +Remove Trailing Spaces +&kate; will automatically eliminate extra spaces +at the ends of lines of text. + + +Auto Brackets When +the user types a left bracket ([, (, or {) &kate; automatically enters the +right bracket (}, ), or ]) to the right of the cursor. + + + Maximum undo steps: +Here the user may specify the number of steps &kate; will +retain in memory for purposes of undoing entries and actions. This means that +the higher the number of steps set the more memory &kate; will use for this. +Setting this entry to 10 would mean that the user would be be able reverse the +last ten operations, i.e. click the undo +button 10 times and obtain results. + + Smart search text from: +This determines where &kate; will get the search +text from (this will be automatically entered into the Find Text +dialog): + +Nowhere: Don't guess the search +text. +Selection Only: Use + the current text selection, if available. +Selection, then Current Word: +Use the current selection if available, otherwise use the current word. + +Current Word +Only: Use the word that the cursor is currently resting on, if +available. +Current Word, then Selection: +Use the current word if available, otherwise use the current selection. + + +Note that, in all the above modes, if a +search string has not been or cannot be determined, then the Find Text Dialog +will fall back to the last search text. + + + + + + +Indentation + + +Automatic indentation + + + +Indentation mode: + +Select the automatic indentation mode you want to use as default. It is +strongly recommended to use None or +Normalhere, and use filetype configurations to set other +indentation modes for text formats like C/C++ code or &XML;. + + + +Insert leading Doxygen "*" when typing + +Automatically insert a leading "*" while typing within a doxygen +style comment. This setting is only enabled when applicable. + + + + + + + +Indentation with Spaces + + + +Use spaces instead of tabs to indent + +This replaces tabs with the number of spaces set in Number of +spaces: below. + + + +Emacs style mixed mode + +Use a mix of tabs and space characters for indentation. + + + +Number of spaces: + +Set the number of spaces you want to use for indentation when you +check Use spaces instead of tabs to indent +above. + + + + + + + +Keep Indent Profile +When this is enabled, the editor will not unindent lines in a +selection further when the line with the least indentation becomes unindented. +If you sometimes unindent blocks of indented code, this may be helpful. + + + + +Keep Extra Spaces +Indentations of more than the selected number of spaces +will not be shortened. + + + +Keys to use + + + +Tab key indents + +This allows the tab key to be used to indent. + + + +Backspace key indent + +This allows the backspace key to be used to +indent. + + + + + + + +Tab Key Mode if Nothing Selected + + + +Insert indent characters + +This allows the Tab key insert indent +characters. + + + +Insert tab character + +This allows the Tab key insert a tab. + + + +Indent current line + +This allows the Tab key indent the current +line. + + + + + + + + + + +Open & Save + + + + +File Format + + + +Encoding: + +This sets the default character encoding for your files. + + + +End of line: + +Choose your prefered end of line mode for your active +document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh. + + + +Automatic end of line detection + +Check this if you want the editor to autodetect the end of line +type. The first found end of line type will be used for the whole file. + + + + + + + +Memory Usage + + + +Maximum loaded blocks per file: + +The editor will load given number of blocks (of around 2048 lines) of +text into memory; if the filesize is bigger than this the other blocks +are swapped to disk and loaded transparently as-needed. +This can cause little delays while navigating in the document; a +larger block count increases the editing speed at the cost of memory. +For normal usage, just choose the highest possible block count: +limit it only if you have problems with the memory usage. + + + + + + + +Automatic Cleanups on Load/Save + + + +Remove trailing spaces + +The editor will automatically eliminate extra spaces at the ends of lines +of text while loading/saving the file. + + + + + + + +Folder Config File + + + +Search depth for config file: + +The editor will search the given number of folder levels upwards +for &kate; config file and load the settings line from it. + + + + + + + +Backup on Save +Backing up on save will cause &kate; to copy the disk file to +<prefix><filename><suffix>' before saving changes. +The suffix defaults to ~ and prefix is empty by +default. + + +Local files + +Check this if you want backups of local files when +saving. + + + +Remote files + +Check this if you want backups of remote files when saving. + + + +Prefix + +Enter the prefix to prepend to the backup file names. + + + +Suffix + +Enter the suffix to add to the backup file names. + + + + + + + + + + + +Highlighting +This group of options is used to customize the highlighting styles for +each programming language type. Any changes you made in other areas of this +dialog apply only to this type. + + + +Highlight: +This is used to choose the language type to +configure. + + + +Informations + + +View the properties of the chosen language highlighting rules: +author name and license. + + + + + +Properties + + + +File extensions: +This is the list of file extensions used to determine which +files to highlight using the current syntax highlight mode. + + +MIME types: +Clicking the wizard button will display a dialog with a list of +all available mime types to choose from.The File Extensions entry will automatically be edited as +well. + + +Priority: +Set the priority of the highlight rule. + + + + + + +Download... + + +Click this button to download new or updated syntax highlight descriptions +from the &kate; website. + + + + + + + + +Filetypes +This page allows you to override the default configuration for documents +of specified mimetypes. When the editor loads a document, it will try if it +matches the file masks or mimetypes for one of the defined filetypes, and if so +apply the variables defined. If more filetypes match, the one with the highest +priority will be used. + + + +Filetype: +The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are +also listed. + + +New +This is used to create a new filetype. After +you click on this button, the fields below get empty and you +can fill the properties you want for the new filetype. + + +Delete +To remove an existing filetype, select it from the drop down +box and press the Delete button. + + + + + +Properties of current filetype +The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are also +listed. + + +Name: +The name of the filetype will be the text of the corresponding +menu item. This name is displayed in the +ToolsFiletypes + + + +Section: +The section name is used to organize the file types in +menus. This is also used in the +ToolsFiletypes + menu. + + +Variables: +This string allows you to configure &kate;'s settings for the +files selected by this mimetype using &kate; variables. You can set almost any +configuration option, such as highlight, indent-mode, encoding, +etc.For a full list of known variables, see the +manual. + + +File extensions: +The wildcards mask allows you to select files by filename. A +typical mask uses an asterisk and the file extension, for example +*.txt; *.text. The string is a semicolon-separated list of +masks. + + +MIME types: +Displays a wizard that helps you easily select +mimetypes. + + +Priority: +Sets a priority for this file type. If more than one file type +selects the same file, the one with the highest priority will be +used. + + + + + + + + +Shortcuts +You can change here the shortcut keys configuration. Select an +action and click on Custom if you want a different shortcut +for this action. +The search line alllows you to look for a specific action and see +its associated shortcut. + + + +Plugins +This tab lists all available plugins and you can check those you +want to use. Once a plugin is checked, the +Configure button is enabled and you can click it +in order to configure the highlighted plugin. + + + + + + + + +Configuring With Document Variables + +Kate variables is kateparts implementation of document variables, similar +to emacs and vi modelines. In katepart, the lines have the format + +kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ] + +the lines can of course be in a comment, if the file is in a format with comments. +Variable names are single words (no whitespace), and anything up to the next +semicolon is the value. The semicolon is required. + +Here is an example variable line, forcing indentation settings for a C++, +java or javascript file: + +// kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle; + + +Only the first and last 10 lines are searched for variable lines. + +There are variables to support almost all configurations in katepart, and +aditionally plugins can use variables, in which case it should be documented in +the plugin's documentation. + + +How kate uses variables + +When reading configuration, katepart looks in the following places +(in that order): + + +The global configuration. +Optional session data. +The "Filetype" configuration. +Document variables in the document itself. +Settings made during editing from menu or command line. + + +As you can understand document variables has the next highest precedence. +Whenever a document is saved, the document variables are reread, and will +overwrite changes made using menu items or the command line. + +Any variable not listed below is stored in the document and can be queried +by other objects such as plugins, which can use them for their own purpose. +For example the variable indent mode uses document variables for its +configuration. + +The variables listed here documents &kate; version 2.4. More variables +may be added in the future. There are 3 possible types of values for variables, +with the following valid expressions: + +BOOL - on|off|true|false|1|0 +INTEGER - any integer number +STRING - anything else + + + + +Available Variables + + +auto-bracketsBOOL +Set auto insertion of brackets on or off. + + + +auto-center-linesINT +Set the number of autocenter lines. + + + +auto-insert-doxygenBOOL +Turn insertion of the leading asterisk in doxygen comments on or +off. This has no effect unless you use the cstyle auto-indenter. + + + +background-colorSTRING +Set the document background color. The value must be something +that can be evaluated to a valid color, for example "#ff0000". + + + +backspace-indentsBOOL +Turn backspace indenting on or off. + + + +block-selectionBOOL +Turn block selection on or off. + + + +bracket-highlight-colorSTRING +Set the color for the bracket highlight. The value must be +something that can be evaluated to a valid color, for example "#ff0000" + + + +current-line-colorSTRING +Set the color for the current line. The value must be +something that can be evaluated to a valid color, for example "#ff0000". + + + +dynamic-word-wrapBOOL +Turns dynamic word wrap on or off. + + + +eol | end-of-lineSTRING +Set the end of line mode. Valid settings are +unix, mac and dos + + + +encodingSTRING +Set the document encoding. The value must be a valid encoding +name, like utf-8. + + + +font-sizeINT +Set the point size of the document font. + + + +fontSTRING +Set the font of the document. The value should be a valid font +name, for example courier. + + + +icon-bar-colorSTRING +Set the icon bar color. The value must be something that can +be evaluated to a valid color, for example #ff0000. + + + +icon-borderBOOL +Set the display of the icon border on or off. + + + +folding-markersBOOL +Set the display of folding markers on or off. + + + +indent-modeSTRING +Set the auto-indentation mode. The options none, +normal, cstyle, csands, +python, xml are recognized. See the section + for details. + + + +indent-widthINT +Set the indentation width. + + + +keep-extra-spacesBOOL +Set wheather to keep extra spaces when calculating indentation width. + + + +keep-indent-profileBOOL +If enabled, prevents unindenting a block if at least one line +has no indentation. + + + +line-numbersBOOL +Set the display of line numbers on or off. + + + +mixed-indentBOOL +Set mixed indentation ala Emacs on or off. + + + +overwrite-modeBOOL +Set overwrite mode on or off. + + + +persistent-selectionBOOL +Set persistent selection on or off. + + + +remove-trailing-spaceBOOL +Set dynamic end of line cleanup on or off. + + + +replace-tabs-saveBOOL +Set tab->space conversion on save on or off. + + + +replace-tabsBOOL +Set dynamic tab->space conversion on or off. + + + +replace-trailing-space-saveBOOL +Set end of line cleanup on save on or off. + + + +schemeSTRING +Set the color scheme. The string must be the name of a color +scheme that exists in your configuration to have any effect. + + + +selection-colorSTRING +Set the selection color. The value must be something that can +be evaluated to a valid color, for example "#ff0000". + + + +show-tabsBOOL +Set the visual TAB character on or off. + + + +smart-homeBOOL +Set smart home navigation on or off. + + + +space-indentBOOL +Set indentation with spaces on or off. + + + +tab-indentsBOOL +Set the TAB key indentation on or off. + + + +tab-widthINT +Set the tab display width. + + + +undo-stepsINT +Set the number of undo steps to remember. + + + +word-wrap-columnINT +Set the hard word wrap width. + + + +word-wrap-marker-colorSTRING +Set the word wrap marker color. The value must be something +that can be evaluated to a valid color, for example "#ff0000". + + + +word-wrapBOOL +Set hard word wrapping on or off. + + + +wrap-cursorBOOL +Set cursor wrapping on or off. + + + + + + + + + diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook new file mode 100644 index 000000000..e6beaac58 --- /dev/null +++ b/doc/kate/fundamentals.docbook @@ -0,0 +1,621 @@ + + + + + + + +The Fundamentals + + +If you have ever used a text editor, you will have no problem using +&kate;. In the next two sections, Starting +&kate; and in Working with +&kate;, we'll show you everything you need to get up and running +quickly. + + + +Starting &kate; + + +You can start &kate; from the K menu or from the +command line. + + + +From the Menu + +Open the &kde; program menu by clicking on the +big K icon on the toolbar at the bottom left of your +screen. This will raise the program menu. Move your +cursor up the menu to the Utilities +Editors menu item. A list +of available editors will appear. Choose +&kate;. + + + +Unless you configure &kate; not to, it will load the last files you +edited. See Configuring &kate; to learn +how to toggle this feature on and off. + + + + + +From the Command Line + + +You can start &kate; by typing its name on the command line. If you give +it a file name, as in the example below, it will open or create that +file. + + + + +%kate + + + + +If you have an active connection, and permission, you can take advantage +of &kde;'s network transparency to open files on the internet. + + + + +%kate + + + + +Command Line Options +&kate; accepts following command line options: + + + +kate + + +This lists the most basic options available at the command line. + + + + + +kate + + + +This lists the options available for changing the way &kate; interacts +with &Qt;. + + + + + +kate + + +This lists the options available for changing the way &kate; interacts +with &kde;. + + + + + +kate + name + + +Starts kate with the session name. The session is created +if it does not exist already. If a &kate; instance running the specified session +exists, the specified files are loaded in that instance. When used with the + option, an instance running this session will be used as +well. + + + + + +kate + URL + + +Causes &kate; to use and existing instance if there is one. If you want all +documents to open in one kate instance, you can add this option to the default +command in your kde application configuration, as well as create a shell alias +in your command intepreter if it supports that. + + + + + +kate + PID + + +Only reuses an instance with the specified PID (Process ID). Used with the + option. + + + + + +kate + encoding +URL +Uses the specified encoding for the document. + + + + +kate + line +URL +Navigates to the specified line after opening the document. + + + + +kate + column +URL +Navigates to the specified column after opening the document. + + + + +kate + +Reads the document content from STDIN. This +is similar to the common option used in many command line +programs, and allows you to pipe command output into &kate;. + + + +kate + +Since &kate; 2.5.1 this standard &kde; option is supported. +When used, the specified files are treated as temporary files and +deleted (if they are local files and you have sufficient permissions) when +closed, unless they are modified since they were opened. + + + +kate + + + +This lists all of the command line options. + + + + + +kate + + + +Lists &kate;'s authors in the terminal window. + + + + + +kate + + + +Lists version information for &Qt;, &kde;, and &kate;. + + + + + +kate + + + +Shows license information. + + + + + + + + +Drag and Drop + +&kate; uses the &kde; Drag and Drop protocol. Files may be dragged and +dropped onto &kate; from the Desktop, &konqueror; or some remote ftp +site opened in one of &konqueror;'s windows. + + + + + +Working with &kate; + +Quick Start will show you how to +toggle four simple options that will let you configure some of &kate;'s +more powerful features right away. +Shortcuts lays out some of the default keystroke +shortcuts for those who can't or don't want to use a mouse. + + + +Quick Start + + +This section will describe some of the items on the +Settings menu so that you can quickly configure +&kate; to work the way you want it. + + + When you start &kate; for the first time you'll see two windows +with white backgrounds. Above the two windows is a toolbar with the +usual labeled icons. And above that, a menubar. + + + +The left-hand window is a side bar. It combines the Documents +and Filesystem Browser windows. Switch between the two by clicking on the tabs +to the left of the window. + + +If you've started &kate; with a file, the right-hand window will show +the file you are editing and the Documents on the side bar will show the +name of the file. Use the Filesystem Browser window to open files. + + + +You can toggle the Documents and Filesystem Browser window on and off in +WindowTool Views +menu. This menu offers you your first glimpse into &kate;'s power and +flexibility. In this section we'll look at three items: + + + + + + + +Show/Hide Documents + + + + +Toggles the Documents on and off. If the Documents/Filesystem Browser window is +not open, &kate; launches the side bar as a separate, undocked, +window. To dock the window grab the two thin parallel lines above the +tabs by clicking on them with your &LMB; and holding the button +down. Drag the the window into &kate;'s editing window and release the +&LMB; when you have positioned the Documents/Filesystem Browser window as you +prefer. + + + + +If you have grabbed the two parallel lines successfully your mouse +pointer will turn into two crossed arrows as you drag. + + + + + + +Show/Hide +Filesystem Browser + + +Toggles the Filesystem Browser on and off. This menu item is the same as +Show Documents with one difference. Toggling +it on launches the window with the Filesystem Browser on top. + + + + + +Show/Hide +Terminal + + +Toggles a terminal emulator on and off at the bottom of &kate;'s +window. In other words, it gives you a command line within the +application. + + + + + + + +Shortcuts + + +Many of &kate;'s keystroke commands (shortcuts) are configurable by +way of the Settings menu. By default +&kate; honors the following key bindings. + + + + + + +Insert + +Toggle between Insert and Overwrite mode. When in insert mode the editor +will add any typed characters to the text and push any previously typed +data to the right of the text cursor. Overwrite mode causes the entry of +each character to eliminate the current character. + + +Left Arrow +Move the cursor one character to the left + + +Right Arrow + Move the cursor one character to the right + + +Up Arrow + Move the cursor up one line + + +Down Arrow + Move the cursor down one line + + +Page Up + Move the cursor up one page + + +Page Down +Move the cursor down one page + + +Backspace + Delete the character to the left of the cursor + + +Home + Move the cursor to the beginning of the line + + +End + Move the cursor to the end of the line + + +Delete +Delete the character to the right of the cursor (or any selected +text) + + +&Shift;Left Arrow + Mark text one character to the left + + +&Shift;Right Arrow + Mark text one character to the right + + +F1 + Help + + +&Shift;F1 +What's this? + + +&Ctrl;F + Find + + +F3 + Find again + + +&Ctrl;B +Set a Bookmark + + +&Ctrl;C + Copy the marked text to the clipboard. + + + +&Ctrl;N + New document + + +&Ctrl;P +Print + + + +&Ctrl;Q +Quit - close active copy of editor + + +&Ctrl;R + Replace + + +&Ctrl;S +Save your file. + + +&Ctrl;V + Paste. + + + +&Ctrl;X +Delete the marked text and copy it to the clipboard. + + +&Ctrl;Z +Undo + + +&Ctrl;&Shift;Z +Redo + + + + + + + + + +Using Sessions + +Sessions is how &kate; lets you keep more than one list of files and +GUI configuration around. You can have as many named sessions as you want, +and you can use unnamed or anonymous sessions for files you want to use only +once. Currently &kate; can save the list of open files, and the general window +configuration in the session, future versions of &kate; may add more features +that can be saved in sessions. With the introduction of sessions, &kate; also +allows you to open any number of instances of the application instead of just +one as it used to do as the default behavior. + +Sessions are supported in three areas: + + +Command line +options that lets you select and start sessions when launching +kate from the command line. + +The Sessions +menu that lets you switch, save, start and manage your +sessions +Configuration +options that lets you decide how sessions generally should +behave. + + + + +When starting a new session, the GUI configuration of Default +Session is loaded. To save window configuration in the default +session, you need to enable saving window configuration in the sessions +configuration page of the configuration dialog and then load the default +session, set up the window as desired and save the session again. + +When a named session is loaded, &kate; will display the session name at +the start of the window title, which then have the form +"Session Name: Document name or +&URL; - &kate;" + +When opening files on the command line with or if a session is selected using the +session chooser, the specified session is loaded prior to the files specified +on the command line. To open files from the commandline in a new, unnamed +session, configure kate to start a new session pr default in the session page of +the configuration dialog or use with an empty string: +''. + +Since &kate; 2.5.1 the PID of the current instance is +exported to the environment variable KATE_PID. When opening files +from the built in terminal Kate will automatically select the current instance +if nothing else is indicated on the command line. + + +Restoring old style &kate; behavior + +When you get used to using sessions you will hopefully see that they +provide a very simple and efficient tool for working in different areas. +However, if you prefer the old &kate; behavior (one instance opens all files), +you can easily achieve that by following this simple strategy: + + +Make kate allways start with the +parameter by adding that to the command in the application preferences, +and additionally using a shell alias. +Configure &kate; to load the last used session at startup. + +Configure &kate; to save the file list when closing a session. + +Load the default session once + + + + + + + + + +Getting Help + + + +With &kate; + + + +This manual + + +Offers detailed documentation on all menu commands, +configuration options, tools, dialogs, plugins &etc; as well as +descriptions of of the &kate; window, the editor and various concepts +used in the application. + +Press F1 or use the +Help +Contents menu topic to view this +manual. + + + + +What's This Help + +What's This help offers immediate help with single elements of +graphical windows, such as buttons or other window areas. + +We strive to provide What's This help for any elements for which +it makes sense. It is available throughout the configuration dialog, +and in many other dialogs as well. + +To employ What's This help, press +&Shift;F1 or use the +HelpWhat's +This menu item to enable What's This +mode. The cursor will turn into an arrow with a question mark, and you +can now click any element in the window to read the What's This help +for that element, if it is available. + + + + +Help Buttons in Dialogs + +Some dialogs have a Help Button. Pressing +it will start the &khelpcenter; and open the relevant +documentation. + + + + + + + +With Your Text Files + +&kate; does not (yet!) provide any means for reading document +related documentation. Depending on the file you are editing, you may +find the Built in +&konsole; helpful for viewing related &UNIX; manual pages or +info documentation, or you can use &konqueror;. + + + + + + diff --git a/doc/kate/highlighted.png b/doc/kate/highlighted.png new file mode 100644 index 000000000..ffb95ec48 Binary files /dev/null and b/doc/kate/highlighted.png differ diff --git a/doc/kate/highlighting.docbook b/doc/kate/highlighting.docbook new file mode 100644 index 000000000..76952d26a --- /dev/null +++ b/doc/kate/highlighting.docbook @@ -0,0 +1,931 @@ + + + + + + + +Working with Syntax Highlighting + + + +Overview + +Syntax Highlighting is what makes the editor automatically +display text in different styles/colors, depending on the function of +the string in relation to the purpose of the file. In program source +code for example, control statements may be rendered bold, while data +types and comments get different colors from the rest of the +text. This greatly enhances the readability of the text, and thus +helps the author to be more efficient and productive. + + + +A Perl function, rendered with syntax +highlighting. +A Perl function, rendered with syntax highlighting. + + + + + +The same Perl function, without +highlighting. +The same Perl function, without highlighting. + + +Of the two examples, which is easiest to read? + +&kate; comes with a flexible, configurable and capable system +for doing syntax highlighting, and the standard distribution provides +definitions for a wide range of programming, scripting and markup +languages and other text file formats. In addition you can +provide your own definitions in simple &XML; files. + +&kate; will automatically detect the right syntax rules when you +open a file, based on the &MIME; Type of the file, determined by its +extension, or, if it has none, the contents. Should you experience a +bad choice, you can manually set the syntax to use from the +DocumentsHighlight +Mode menu. + +The styles and colors used by each syntax highlight definition +can be configured using the Appearance page of the +Config Dialog, while the &MIME; Types +it should be used for, are handeled by the Highlight +page. + + +Syntax highlighting is there to enhance the readability of +correct text, but you cannot trust it to validate your text. Marking +text for syntax is difficult depending on the format you are using, +and in some cases the authors of the syntax rules will be proud if 98% +of text gets correctly rendered, though most often you need a rare +style to see the incorrect 2%. + + + +You can download updated or additional syntax highlight +definitions from the &kate; website by clicking the +Download button in the Highlight Page of the Config Dialog. + + + + + + +The &kate; Syntax Highlight System + +This section will discuss the &kate; syntax highlighting +mechanism in more detail. It is for you if you want to know about +it, or if you want to change or create syntax definitions. + + + +How it Works + +Whenever you open a file, one of the first things the &kate; +editor does is detect which syntax definition to use for the +file. While reading the text of the file, and while you type away in +it, the syntax highlighting system will analyze the text using the +rules defined by the syntax definition and mark in it where different +contexts and styles begin and end. + +When you type in the document, the new text is analyzed and marked on the +fly, so that if you delete a character that is marked as the beginning or end +of a context, the style of surrounding text changes accordingly. + +The syntax definitions used by the &kate; Syntax Highlighting System are +&XML; files, containing + +Rules for detecting the role of text, organized into context blocks +Keyword lists +Style Item definitions + + + +When analyzing the text, the detection rules are evaluated in +the order in which they are defined, and if the beginning of the +current string matches a rule, the related context is used. The start +point in the text is moved to the final point at which that rule +matched and a new loop of the rules begins, starting in the context +set by the matched rule. + + + + +Rules + +The detection rules are the heart of the highlighting detection +system. A rule is a string, character or regular expression against which +to match the text being analyzed. It contains information about which +style to use for the matching part of the text. It may switch the +working context of the system either to an explicitly mentioned +context or to the previous context used by the text. + +Rules are organized in context groups. A context group is used +for main text concepts within the format, for example quoted text +strings or comment blocks in program source code. This ensures that +the highlighting system does not need to loop through all rules when +it is not necessary, and that some character sequences in the text can +be treated differently depending on the current context. + + +Contexts may be generated dynamically to allow the usage of instance +specific data in rules. + + + + +Context Styles and Keywords + +In some programming languages, integer numbers are treated +differently than floating point ones by the compiler (the program that +converts the source code to a binary executable), and there may be +characters having a special meaning within a quoted string. In such +cases, it makes sense to render them differently from the surroundings +so that they are easy to identify while reading the text. So even if +they do not represent special contexts, they may be seen as such by +the syntax highlighting system, so that they can be marked for +different rendering. + +A syntax definition may contain as many styles as required to +cover the concepts of the format it is used for. + +In many formats, there are lists of words that represent a +specific concept. For example in programming languages, the control +statements is one concept, data type names another, and built in +functions of the language a third. The &kate; Syntax Highlighting +System can use such lists to detect and mark words in the text to +emphasize concepts of the text formats. + + + + +Default Styles + +If you open a C++ source file, a &Java; source file and an +HTML document in &kate;, you will see that even +though the formats are different, and thus different words are chosen +for special treatment, the colors used are the same. This is because +&kate; has a predefined list of Default Styles which are employed by +the individual syntax definitions. + +This makes it easy to recognize similar concepts in different +text formats. For example comments are present in almost any +programming, scripting or markup language, and when they are rendered +using the same style in all languages, you do not have to stop and +think to identify them within the text. + + +All styles in a syntax definition use one of the default +styles. A few syntax definitions use more styles that there are +defaults, so if you use a format often, it may be worth launching the +configuration dialog to see if some concepts are using the same +style. For example there is only one default style for strings, but as +the Perl programming language operates with two types of strings, you +can enhance the highlighting by configuring those to be slightly +different. All available default styles +will be explained later. + + + + + + + +The Highlight Definition &XML; Format + + +Overview + +This section is an overview of the Highlight Definition &XML; +format. Based on a small example it will describe the main components +and their meaning and usage. The next section will go into detail with +the highlight detection rules. + +The formal definition, aka the DTD is stored +in the file language.dtd which should be +installed on your system in the folder +$KDEDIR/share/apps/katepart/syntax. + + + +Main sections of &kate; Highlight Definition files + + +A highlighting file contains a header that sets the XML version and the doctype: + + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd"> + + + + + +The root of the definition file is the element language. +Available attributes are: + + +Required attributes: +name sets the name of the language. It appears in the menus and dialogs afterwards. +section specifies the category. +extensions defines file extensions, like "*.cpp;*.h" + +Optional attributes: +mimetype associates files &MIME; Type based. +version specifies the current version of the definition file. +kateversion specifies the latest supported &kate; version. +casesensitive defines, whether the keywords are casesensitiv or not. +priority is necessary if another highlight definition file uses the same extensions. The higher priority will win. +author contains the name of the author and his email-address. +license contains the license, usually LGPL, Artistic, GPL and others. +hidden defines, whether the name should appear in &kate;'s menus. +So the next line may look like this: + +<language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" /> + + + + + + +Next comes the highlighting element, which +contains the optional element list and the required +elements contexts and itemDatas. + +list elements contain a list of keywords. In +this case the keywords are class and const. +You can add as many lists as you need. +The contexts element contains all contexts. +The first context is by default the start of the highlighting. There are +two rules in the context Normal Text, which match +the list of keywords with the name somename and a +rule that detects a quote and switches the context to string. +To learn more about rules read the next chapter. +The third part is the itemDatas element. It +contains all color and font styles needed by the contexts and rules. +In this example, the itemData Normal Text, +String and Keyword are used. + + + <highlighting> + <list name="somename"> + <item> class </item> + <item> const </item> + </list> + <contexts> + <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" > + <keyword attribute="Keyword" context="#stay" String="somename" /> + <DetectChar attribute="String" context="string" char="&quot;" /> + </context> + <context attribute="String" lineEndContext="#stay" name="string" > + <DetectChar attribute="String" context="#pop" char="&quot;" /> + </context> + </contexts> + <itemDatas> + <itemData name="Normal Text" defStyleNum="dsNormal" /> + <itemData name="Keyword" defStyleNum="dsKeyword" /> + <itemData name="String" defStyleNum="dsString" /> + </itemDatas> + </highlighting> + + + + + +The last part of a highlight definition is the optional +general section. It may contain information +about keywords, code folding, comments and indentation. + + +The comment section defines with what +string a single line comment is introduced. You also can define a +multiline comments using multiLine with the +additional attribute end. This is used if the +user presses the corresponding shortcut for comment/uncomment. +The keywords section defines whether +keyword lists are casesensitive or not. Other attributes will be +explained later. + + <general> + <comments> + <comment name="singleLine" start="#"/> + </comments> + <keywords casesensitive="1"/> + </general> +</language> + + + + + + + + + + +The Sections in Detail +This part will describe all available attributes for contexts, +itemDatas, keywords, comments, code folding and indentation. + + + +The element context belongs into the group +contexts. A context itself defines context specific +rules like what should happen if the highlight system reaches the end of a +line. Available attributes are: + + + +name the context name. Rules will use this name +to specify the context to switch to if the rule matches. +lineEndContext defines the context the highlight +system switches to if it reaches the end of a line. This may either be a name +of another context, #stay to not switch the context +(eg. do nothing) or #pop which will cause to leave this +context. It is possible to use for example #pop#pop#pop +to pop three times. +lineBeginContext defines the context if a begin +of a line is encountered. Default: #stay. +fallthrough defines if the highlight system switches +to the context specified in fallthroughContext if no rule matches. +Default: false. +fallthroughContext specifies the next context +if no rule matches. +dynamic if true, the context +remembers strings/placeholders saved by dynamic rules. This is needed for HERE +documents for example. Default: false. + + + + + +The element itemData is in the group +itemDatas. It defines the font style and colors. +So it is possible to define your own styles and colors, however we +recommend to stick to the default styles if possible so that the user +will always see the same colors used in different languages. Though, +sometimes there is no other way and it is necessary to change color +and font attributes. The attributes name and defStyleNum are required, +the other optional. Available attributes are: + + +name sets the name of the itemData. +Contexts and rules will use this name in their attribute +attribute to reference an itemData. +defStyleNum defines which default style to use. +Available default styles are explained in detail later. +color defines a color. Valid formats are +'#rrggbb' or '#rgb'. +selColor defines the selection color. +italic if true, the text will be italic. +bold if true, the text will be bold. +underline if true, the text will be underlined. +strikeout if true, the text will be stroked out. + + + + + +The element keywords in the group +general defines keyword properties. Available attributes are: + + +casesensitive may be true +or false. If true, all keywords +are matched casesensitive +weakDeliminator is a list of characters that +do not act as word delimiters. For example the dot '.' +is a word delimiter. Assume a keyword in a list contains +a dot, it will only match if you specify the dot as a weak delimiter. +additionalDeliminator defines additional delimiters. +wordWrapDeliminator defines characters after which a +line wrap may occur. +Default delimiters and word wrap delimiters are the characters +.():!+,-<=>%&*/;?[]^{|}~\, space (' ') +and tabulator ('\t'). + + + + + +The element comment in the group +comments defines comment properties which are used +for ToolsComment and +ToolsUncomment. +Available attributes are: + + +name is either singleLine +or multiLine. If you choose multiLine +the attributes end and region are +required. +start defines the string used to start a comment. +In C++ this would be "/*". +end defines the string used to close a comment. +In C++ this would be "*/". +region should be the name of the the foldable +multiline comment. Assume you have beginRegion="Comment" +... endRegion="Comment" in your rules, you should use +region="Comment". This way uncomment works even if you +do not select all the text of the multiline comment. The cursor only must be +in the multiline comment. + + + + + +The element folding in the group +general defines code folding properties. +Available attributes are: + + +indentationsensitive if true, the code folding markers +will be added indentation based, like in the scripting language Python. Usually you +do not need to set it, as it defaults to false. + + + + + +The element indentation in the group +general defines which indenter will be used, however we strongly +recommend to omit this element, as the indenter usually will be set by either defining +a File Type or by adding a mode line to the text file. If you specify an indenter though, +you will force a specific indentation on the user, which he might not like at all. +Available attributes are: + + +mode is the name of the indenter. Available indenters +right now are: normal, cstyle, csands, xml, python and +varindent. + + + + + + + + + + +Available Default Styles +Default Styles were already explained, +as a short summary: Default styles are predefined font and color styles. + + +So here only the list of available default styles: + +dsNormal, used for normal text. +dsKeyword, used for keywords. +dsDataType, used for data types. +dsDecVal, used for decimal values. +dsBaseN, used for values with a base other than 10. +dsFloat, used for float values. +dsChar, used for a character. +dsString, used for strings. +dsComment, used for comments. +dsOthers, used for 'other' things. +dsAlert, used for warning messages. +dsFunction, used for function calls. +dsRegionMarker, used for region markers. +dsError, used for error highlighting and wrong syntax. + + + + + + + + + +Highlight Detection Rules + +This section describes the syntax detection rules. + +Each rule can match zero or more characters at the beginning of +the string they are test against. If the rule matches, the matching +characters are assigned the style or attribute +defined by the rule, and a rule may ask that the current context is +switched. + +A rule looks like this: + +<RuleName attribute="(identifier)" context="(identifier)" [rule specific attributes] /> + +The attribute identifies the style to use +for matched characters by name, and the context +identifies the context to use from here. + +The context can be identified by: + + + +An identifier, which is the name of the other +context. + + +An order telling the engine to stay in the +current context (#stay), or to pop back to a +previous context used in the string (#pop). +To go back more steps, the #pop keyword can be repeated: +#pop#pop#pop + + + +Some rules can have child rules which are +then evaluated only if the parent rule matched. The entire matched +string will be given the attribute defined by the parent rule. A rule +with child rules looks like this: + + +<RuleName (attributes)> + <ChildRuleName (attributes) /> + ... +</RuleName> + + + +Rule specific attributes varies and are described in the +following sections. + + + +Common attributes +All rules have the following attributes in common and are +available whenever (common attributes) appears. +attribute and context +are required attributes, all others are optional. + + + +attribute: An attribute maps to a defined itemData. + + +context: Specify the context to which the highlighting system switches if the rule matches. + + +beginRegion: Start a code folding block. Default: unset. + + +endRegion: Close a code folding block. Default: unset. + + +lookAhead: If true, the +highlighting system will not process the matches length. +Default: false. + + +firstNonSpace: Match only, if the string is +the first non-whitespace in the line. Default: false. + + +column: Match only, if the column matches. Default: unset. + + + + +Dynamic rules +Some rules allow the optional attribute dynamic +of type boolean that defaults to false. If dynamic is +true, a rule can use placeholders representing the text +matched by a regular expression rule that switched to the +current context in its string or +char attributes. In a string, +the placeholder %N (where N is a number) will be +replaced with the corresponding capture N +from the calling regular expression. In a +char the placeholer must be a number +N and it will be replaced with the first character of +the corresponding capture N from the calling regular +expression. Whenever a rule allows this attribute it will contain a +(dynamic). + + +dynamic: may be (true|false). + + + + +The Rules in Detail + + + +DetectChar + +Detect a single specific character. Commonly used for example to +find the ends of quoted strings. +<DetectChar char="(character)" (common attributes) (dynamic) /> +The char attribute defines the character +to match. + + + + +Detect2Chars + +Detect two specific characters in a defined order. +<Detect2Chars char="(character)" char1="(character)" (common attributes) (dynamic) /> +The char attribute defines the first character to match, +char1 the second. + + + + +AnyChar + +Detect one character of a set of specified characters. +<AnyChar String="(string)" (common attributes) /> +The String attribute defines the set of +characters. + + + + +StringDetect + +Detect an exact string. +<StringDetect String="(string)" [insensitive="true|false"] (common attributes) (dynamic) /> +The String attribute defines the string +to match. The insensitive attribute defaults to +false and is passed to the string comparison +function. If the value is true insensitive +comparing is used. + + + + +RegExpr + +Matches against a regular expression. +<RegExpr String="(string)" [insensitive="true|false"] [minimal="true|false"] (common attributes) (dynamic) /> +The String attribute defines the regular +expression. +insensitive defaults to +false and is passed to the regular expression +engine. +minimal defaults to +false and is passed to the regular expression +engine. +Because the rules are always matched against the beginning of +the current string, a regular expression starting with a caret +(^) indicates that the rule should only be +matched against the start of a line. +See Regular Expressions +for more information on those. + + + + +keyword + +Detect a keyword from a specified list. +<keyword String="(list name)" (common attributes) /> +The String attribute identifies the +keyword list by name. A list with that name must exist. + + + + +Int + +Detect an integer number. +<Int (common attributes) (dynamic) /> +This rule has no specific attributes. Child rules are typically +used to detect combinations of L and +U after the number, indicating the integer type +in program code. Actually all rules are allowed as child rules, though, +the DTD only allowes the child rule StringDetect. +The following example matches integer numbers follows by the character 'L'. + +<Int attribute="Decimal" context="#stay" > + <StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/> +</Int> + + + + + + +Float + +Detect a floating point number. +<Float (common attributes) /> +This rule has no specific attributes. AnyChar is +allowed as a child rules and typically used to detect combinations, see rule +Int for reference. + + + + +HlCOct + +Detect an octal point number representation. +<HlCOct (common attributes) /> +This rule has no specific attributes. + + + + +HlCHex + +Detect a hexadecimal number representation. +<HlCHex (common attributes) /> +This rule has no specific attributes. + + + + +HlCStringChar + +Detect an escaped character. +<HlCStringChar (common attributes) /> +This rule has no specific attributes. + +It matches literal representations of characters commonly used in +program code, for example \n +(newline) or \t (TAB). + +The following characters will match if they follow a backslash +(\): +abefnrtv"'?\. Additionally, escaped +hexadecimal numbers like for example \xff and +escaped octal numbers, for example \033 will +match. + + + + + +HlCChar + +Detect an C character. +<HlCChar (common attributes) /> +This rule has no specific attributes. + +It matches C characters enclosed in a tick (Example: 'c'). +So in the ticks may be a simple character or an escaped character. +See HlCStringChar for matched escaped character sequences. + + + + + +RangeDetect + +Detect a string with defined start and end characters. +<RangeDetect char="(character)" char1="(character)" (common attributes) /> +char defines the character starting the range, +char1 the character ending the range. +Usefull to detect for example small quoted strings and the like, but +note that since the highlighting engine works on one line at a time, this +will not find strings spanning over a line break. + + + + +LineContinue + +Matches at end of line. +<LineContinue (common attributes) /> +This rule has no specific attributes. +This rule is useful for switching context at end of line, if the last +character is a backslash ('\'). This is needed for +example in C/C++ to continue macros or strings. + + + + +IncludeRules + +Include rules from another context or language/file. +<IncludeRules context="contextlink" [includeAttrib="true|false"] /> + +The context attribute defines which context to include. +If it a simple string it includes all defined rules into the current context, example: +<IncludeRules context="anotherContext" /> + + +If the string begins with ## the highlight system +will look for another language definition with the given name, example: +<IncludeRules context="##C++" /> +If includeAttrib attribute is +true, change the destination attribute to the one of +the source. This is required to make for example commenting work, if text +matched by the included context is a different highlight than the host +context. + + + + + + +DetectSpaces + +Detect whitespaces. +<DetectSpaces (common attributes) /> + +This rule has no specific attributes. +Use this rule if you know that there can several whitespaces ahead, +for example in the beginning of indented lines. This rule will skip all +whitespace at once, instead of testing multiple rules and skipping one at the +time due to no match. + + + + + +DetectIdentifier + +Detect identifier strings (as a regular expression: [a-zA-Z_][a-zA-Z0-9_]*). +<DetectIdentifier (common attributes) /> + +This rule has no specific attributes. +Use this rule to skip a string of word characters at once, rather than +testing with multiple rules and skipping one at the time due to no match. + + + + + + + +Tips & Tricks + + +Once you have understood how the context switching works it will be +easy to write highlight definitions. Though you should carefully check what +rule you choose in what situation. Regular expressions are very mighty, but +they are slow compared to the other rules. So you may consider the following +tips. + + + +If you only match two characters use Detect2Chars +instead of StringDetect. The same applies to +DetectChar. + + +Regular expressions are easy to use but often there is another much +faster way to achieve the same result. Consider you only want to match +the character '#' if it is the first character in the +line. A regular expression based solution would look like this: +<RegExpr attribute="Macro" context="macro" String="^\s*#" /> +You can achieve the same much faster in using: +<DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /> +If you want to match the regular expression '^#' you +can still use DetectChar with the attribute column="0". +The attribute column counts character based, so a tabulator still is only one character. + + + +You can switch contexts without processing characters. Assume that you +want to switch context when you meet the string */, but +need to process that string in the next context. The below rule will match, and +the lookAhead attribute will cause the highlighter to +keep the matched string for the next context. +<Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /> + + + +Use DetectSpaces if you know that many whitespaces occur. + + +Use DetectIdentifier instead of the regular expression '[a-zA-Z_]\w*'. + + +Use default styles whenever you can. This way the user will find a familiar environment. + + +Look into other XML-files to see how other people implement tricky rules. + + +You can validate every XML file by using the command +xmllint --dtdvalid language.dtd mySyntax.xml. + + +If you repeat complex regular expression very often you can use +ENTITIES. Example: + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd" +[ + <!ENTITY myref "[A-Za-z_:][\w.:_-]*"> +]> + +Now you can use &myref; instead of the regular +expression. + + + + + + + diff --git a/doc/kate/index.docbook b/doc/kate/index.docbook new file mode 100644 index 000000000..fe409a83d --- /dev/null +++ b/doc/kate/index.docbook @@ -0,0 +1,293 @@ + + + + + + + + + + + + + + +]> + + +The &kate; Handbook + + + +&Anders.Lund; &Anders.Lund.mail; +&Seth.Rothberg; &Seth.Rothberg.mail; +&Dominik.Haumann; &Dominik.Haumann.mail; + + + + +2000 +2001 +&Seth.Rothberg; + + +200220032005 +&Anders.Lund; + + +2005 +&Dominik.Haumann; + + +&FDLNotice; + +2005-12-29 +2.5.0 + + +&kate; is a programmer's text editor for &kde; 2.2 and above. + +This handbook documents &kate; Version 2.5.0 + + + +KDE +kdebase +Kate +text +editor +programmer +programming +projects +MDI +Multi +Document +Interface +terminal +console + + + + + +Introduction + + +Welcome to &kate;, a programmer's text editor for &kde; version 2.2 and +above. Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +HTML to bash scripts, the ability to create and +maintain projects, a multiple document interface +(MDI), and a self-contained terminal emulator. + + + +But &kate; is more than a programmer's editor. Its ability to open +several files at once makes it ideal for editing &UNIX;'s many +configuration files. This document was written in &kate;. + + + + + +Editing this manual... + + + + + +&fundamentals-chapter; + +&mdi-chapter; + +&part-chapter; + +&plugins-chapter; + +&advanced-chapter; + +&menu-chapter; + +&configuring-chapter; + + + +Credits and License + + +&kate;. Program copyright 2000, 2001, 2002 - 2005 by the &kate; developer team. + + + +The &kate; team: + +&Christoph.Cullmann; &Christoph.Cullmann.mail; +Project Manager & Core Developer + + +&Anders.Lund; &Anders.Lund.mail; +Core Developer, Perl syntax highlighting, +documentation + + +&Joseph.Wenninger; &Joseph.Wenninger.mail; +Core Developer, syntax highlighting + + +Michael Bartl michael.bartl1@chello.at +Core Developer + + +Phlip phlip_cpp@my-deja.com +The project compiler + + +&Waldo.Bastian; &Waldo.Bastian.mail; +The cool buffer system + + +Matt Newell newellm@proaxis.com +Testing... + + +Michael McCallum gholam@xtra.co.nz +Core Developer + + +Jochen Wilhemly digisnap@cs.tu-berlin.de +KWrite Author + + +&Michael.Koch; &Michael.Koch.mail; +KWrite port to KParts + + +Christian Gebauer gebauer@bigfoot.com +Unspecified + + +&Simon.Hausmann; &Simon.Hausmann.mail; +Unspecified + + +Glen Parker glenebob@nwlink.com +KWrite Undo History, KSpell integration + + +Scott Manson sdmanson@alltel.net +KWrite XML syntax highlighting support + + +&John.Firebaugh; &John.Firebaugh.mail; +Various Patches + + +&Dominik.Haumann; &Dominik.Haumann.mail; +Developer, Highlight wizard + + + + +Many other people have contributed: + +Matteo Merli merlim@libero.it +Highlighting for RPM Spec-Files, Diff and more + + +Rocky Scaletta rocky@purdue.edu +Highlighting for VHDL + + +Yury Lebedev +Highlighting for SQL + + +Chris Ross +Highlighting for Ferite + + +Nick Roux +Highlighting for ILERPG + + +John Firebaugh +Highlighting for Java, and much more + + +Carsten Niehaus +Highlighting for LaTeX + + +Per Wigren +Highlighting for Makefiles, Python + + +Jan Fritz +Highlighting for Python + + +&Daniel.Naber; +Small bugfixes, XML plugin + + + +Documentation copyright 2000,2001 &Seth.Rothberg; +&Seth.Rothberg.mail; + +Documentation copyright 2002, 2003, 2005 &Anders.Lund; +&Anders.Lund.mail; + + + +&underFDL; +&underGPL; + + + +&highlighting-appendix; + +®exp-appendix; + + +Installation + +&install.intro.documentation; + +&install.compile.documentation; + + + +&documentation.index; + + + + + + diff --git a/doc/kate/kate.png b/doc/kate/kate.png new file mode 100644 index 000000000..dc1ee4c40 Binary files /dev/null and b/doc/kate/kate.png differ diff --git a/doc/kate/man-kate.1.docbook b/doc/kate/man-kate.1.docbook new file mode 100644 index 000000000..80899a4fb --- /dev/null +++ b/doc/kate/man-kate.1.docbook @@ -0,0 +1,165 @@ + + +]> + + + +KDE User's Manual +&Lauri.Watts; &Lauri.Watts.mail; +June 07, 2005 +K Desktop Environment + + + +kate +1 + + + +kate +Advanced text editor for &kde; + + + + +kate + +name + + +pid + +name + +line + + column + +KDE Generic Options +Qt Generic Options + + + + +Description +&kate; is the &kde; Advanced Text Editor. +&kate; also provides the editor part for various applications, under +the name &kwrite;. +Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +HTML to bash scripts, the ability to create and +maintain projects, a multiple document interface +(MDI), and a self-contained terminal emulator. + + + +But &kate; is more than a programmer's editor. Its ability to open +several files at once makes it ideal for editing &UNIX;'s many +configuration files. This document was written in &kate;. + + + + + + +Options + + + +, name + +Start &kate; with a given session. + + + +Use an already running &kate; + + + +pid +Only try to reuse kate instance with this +pid + + + +name +Set encoding for the file to openYou can use +this to force a file opened in utf-8 format, for instance. (The command +iconv -l provides a list of encodings, which may be +helpful to you.) + + + line +Navigate to this line + + + +column +Navigate to this column + + + +Read the contents of +stdin + + + + + + +See Also + +kwrite(1) + +More detailed user documentation is available from help:/kate +(either enter this URL into &konqueror;, or run +khelpcenter +help:/kate). + +There is also further information available at the &kate; website. + + + +Examples + +To open a file named source.cpp at column 15, +line 25, in an existing &kate; window, you could use: +kate source.cpp + +If you have an active internet connection, you can take advantage of +&kde;'s network transparency to open a file from an ftp site. If you do not +have write permission on the remote server, the file will be opened read +only and you will be prompted for a local filename to save to if you make +changes. If you do have write permission, changes will be saved +transparently over the network. +kate + + + + + + + + +Authors +The maintainer of &kate; is &Christoph.Cullmann; +&Christoph.Cullmann.mail;. A comprehensive list of authors and contributors +is available in the complete user manual mentioned above. + + + diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook new file mode 100644 index 000000000..a6c6854db --- /dev/null +++ b/doc/kate/mdi.docbook @@ -0,0 +1,266 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Working With the &kate; <acronym>MDI</acronym> + + +Overview + +Window, View, Document, Frame, Editor... What are they all in +the terminology of &kate;, and how do you get the most out of it? This +chapter will explain all of that, and even more. + + + +The Main Window + +Main window +The &kate; Main Window is a standard &kde; application window, +with the addition of side bars containing tool views. It has a +Menubar with all the common menus, and some more, and a toolbar +providing access to commonly used commands. + +The most important part of the window is the Editing Area, by +default displaying a single text editor component, in which you can +work with your documents. + +The docking capabilities of the window is used for the tool +windows: + + +The File List +The Filesystem +Browser +The Built in Terminal Emulator + + +And possibly other tool views, for example provided by +plugins. + +Tool views can be positioned in any sidebar, to move a tool right click +its sidebar button and select from the &RMB; menu + +A tool view can be marked as persistent in the &RMB; +menu for its sidebar button. The sidebar can contain +more tools at one time so that when a tool is persistant other tools can be +shown simultaneously. + + + + + + + + +The Editor area + +Editing Area +&kate; is capable of having more than one document open at the +same time, and also of splitting the editing area into any number of +frames, similar to how for example &konqueror; or the popular +emacs text editor works. This way you can +view several documents at the same time, or more instances of the same +document, handy for example if your document contains definitions in +the top that you want to see often for reference. Or you could view a +program source header in one frame, while editing the implementation +file in another. + +When a document is available in more than one editor, changes +made in one editor will immediately be reflected in the others as +well. This includes changing the text as well as selecting +text. Search operations or cursor movement is only reflected in the +current editor. + +It is currently not possible to have more instances of the same +document open in the sense that one instance will be edited while the +other will not. + +When splitting an editor into two frames, it is divided into two +equally sized frames, both displaying the current document of that +editor. The new frame will be at the bottom (in the case of a +horizontal split) or at the right (for a vertical split). The new +frame gets the focus, which is visualized by a small green led in the +focused frame. + + + + +The Document List + +File list +The file list displays a list of all documents currently open in +&kate;. Modified files will have a small floppy +disk icon on their left to indicate that state. + +If two or more files with the same name (located in different +folders) are open, the names of the second will be prepended +<2> and so on. The tool-tip for the file will +display its full name including the path, allowing you to choose the +desired one. To display a document in the currently +active frame, click the document name in the list. + +You can sort the list in a few different ways by rightclicking the +list and selecting from the Sort By menu. + +The options are + + + +Opening Order +Lists the documents in the order of opening + + + +Document Name +Lists the documents alphabetically by their name. + + + +URL +Lists the documents alphabetically by URL. + + + + + + +The document list will pr default visualize your history by shading the +entries for the most recent documents with a background color. If the document +was edited, an extra color is blended in. The most recent document has the +strongest color, so that you can easily find the documents you are working on. +This feature can be disabled in +The Document List Page +of the configuration dialog. + +The default location in the &kate; window is to the left of the +editing area. + + + +The Filesystem Browser + +Filesystem Browser +The Filesystem Browser is a folder viewer, allowing you to open +files from a displayed folder in the current frame. + +From top down, the Filesystem Browser consist of the following +elements: + + + +A Toolbar + +This contains standard navigations tool buttons: + + +Home +Pressing it will cause the folder view to cd to your home folder. + + +Up +This will cause the folder view to cd to the immediate parent of the currently displayed +folder if possible. + + +Back +Causes the folder view to cd to the previously displayed folder in the history. +This button is disabled, if there is no previous item. + + +Forward +Causes the folder view to cd to the next folder in the history. +This button is disabled, if there is no next folder. + + +Sync +This button will cause the folder view to +cd to the folder of the currently active +document if possible. This button is disabled, if the active document +is a new, unsaved file, or the folder in which it resides can not +be decided. + + + + + + + +A &URL; entry + +Here you can type the path of a folder to browse. The &URL; +entry maintains a list of previously typed paths. To choose one use +the arrow button to the right of the entry. +The &URL; entry has folder auto-completion. The completion +method can be set using the &RMB; menu of the text +entry. + + + + +A Folder View +This is a standard &kde; folder view. + + + +A Filter Entry + +The Filter entry allows you to enter a filter for the files +displayed in the folder view. The filter uses standard globs; patterns +must be separated by white space. Example: *.cpp *.h +*.moc +To display all files, enter a single asterisk +*. +The filter entry saves the last 10 filters entered between +sessions, to use one, press the arrow button on the right of the entry +and select the desired filter string. + + + + + + + + + +The Built in Terminal Emulator + +Terminal emulator +The built in Terminal Emulator is a copy of the &kde; &konsole; +terminal application, for your convenience. It is available from the +SettingsShow Terminal +Emulator menu item or by pressing the F7 key, and will get the focus +whenever displayed. Additionally, if the Sync &konsole; with +active document option is enabled, it will +change into the directory of the current document if +possible when it is displayed, or when the current document +changes. + +The default location in the &kate; window is at the bottom, +below the editing area. + +You can configure the &konsole; using its &RMB; menu, for more +information, see the &konsole; manual. + + + + +External Tools + +In the Tools menu you will find a submenu labeled +External Tools. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection. + +External tools are user defined, you can add, edit or remove tools using +the External Tools configuration panel. + + + + + diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook new file mode 100644 index 000000000..26ae7551e --- /dev/null +++ b/doc/kate/menus.docbook @@ -0,0 +1,1438 @@ + + + + + + + +Menu Entries + + +The <guimenu>File</guimenu> Menu + + + + + + + +&Ctrl;N + +File +New + + + + +This command starts a new document in the editing +window. In the Documents list on the left the new file +is named Untitled. + + + + + + + + + +&Ctrl;O + +File +Open... + + + +Launches &kde;'s open file dialog box to let you open one or more files. + + + + + + + + + +File +Open Recent + + + + +This command allows you to open a file from a submenu +that contains a list of recently edited files. + + + + + + + + +File +Open With + + + + +This submenu presents a list of applications known to handle the mime type +of your current document. Activating an entry will open the current document +with that application. +In addition, a entry Other... command launches +the open with dialog box that allows you to select another application +to open the active file. Your file will still be open in &kate;. + + + + + + + + + +&Ctrl;S + +File +Save + + + + +This command saves your file. Use it often. If the file is +Untitled then +Save becomes +Save As. + + + + + + + + +File +Save As... + + + + +Name and rename files with this command. +It launches the save file dialog box. This dialog works just as +the open file dialog box does. You can use it to navigate through +your file system, preview existing files, or filter your file +view with file masks. + + + +Type the name you want to give the file you are saving in the +Location combo box and press the +OK button. + + + + + + + + + +&Ctrl;L + +File +Save All + + + + +This command saves all modified open files. + + + + + + + + + +F5 + +File +Reload + + + + +Reloads the active file. This command is +useful if another program or process has changed the file while you have +it open in &kate; + + + + + + + + + +&Ctrl;P + +File +Print... + + + + +Print the active file. + + + + + + + +File +Export as HTML... + + + + +Export your file in HTML format so your document can be viewed as a +web page. + + + + + + + +File +Mail... + + + + +Open your mail client and attach the file in the mail. + + + + + + + + + +&Ctrl;W + +File +Close + + + + +Close the active file with this command. If you +have made unsaved changes, you will be prompted to save +the file before &kate; closes it. + + + + + + + + +File +Close All + + + + +This command closes all the files you have open +in &kate;. + + + + + + + + + +&Ctrl;Q + +File +Quit + + + + +This command closes &kate; and any files you were +editing. If you have made unsaved changes to any of the files you were +editing, you will be prompted to save them. + + + + + + + +The <guimenu>Edit</guimenu> Menu +The Edit menu contains a host of commands, +all to work with the currently active document. + + +Menu Entries + + + + +&Ctrl;Z +Edit +Undo + + + +Undo the last editing command (typing, copying, cutting etc.) +If grouped undo is enabled, this may undo several editing commands of the same type, like typing in characters. + + + + + + + +&Ctrl;&Shift;Z +Edit +Redo + + + +Redo the last undo step. + + + + + + + +&Ctrl;X +Edit +Cut + + + +Removes selected text if any, and places a copy of the removed text in the clipboard. + + + + + + + +&Ctrl;C +Edit +Copy + + + +Copies selected text, if any, to the clipboard. + + + + + + + +Edit +Copy as HTML + + + +Copies selected text with the syntax highlight as HTML text. + + + + + + + +&Ctrl;V +Edit +Paste + + + +Copies the first item in the clipboard into the editor at cursor position. +If Overwrite Selection is enabled, the pasted text will overwrite the selection, if any. + + + + + + + +&Ctrl;A +Edit +Select All + + + +Selects all text in the editor. + + + + + + + +&Ctrl;&Shift;A +Edit +Deselect + + + +Deselects the selected text in the editor if any. + + + + + + + +&Ctrl;Shift +B +Edit +Block Selection Mode + + + +Toggles Selection Mode. When the Selection Mode is BLOCK, you can make vertical selections, +ie select column 5 to 10 in lines 9 to 15. +The status bar shows the current state of the Selection Mode, either NORM or BLK. + + + + + + + +&Ctrl;F +Edit +Find... + + + +Launch the Find Dialog to allow you to search for text in the edited document. + + + + + + + +F3 +Edit +Find Next + + + +Go to the nearest downwards match of the last text or regular expression searched for, starting from cursor position + + + + + + + +&Shift;F3 +Edit +Find Previous + + + +Go to the nearest upwards match of the last text or regular expression searched for, starting from cursor position + + + + + + + +&Ctrl;R +Edit +Replace... + + + +Launch the Replace Dialog to replace one or more instances of a defined text with something else. + + + + + + + +&Ctrl;G +Edit +Go to line... + + + +Launches the Go To Line Dialog, allowing you to enter the number of a line to find in +the document + + + + + + + + +The <guimenu>Document</guimenu> Menu +The Document menu provides a menu entry for each open document. +Clicking one of these will bring the requested document to focus. If you have +multiple frames, an editor for that document will be displayed in the currently +active frame. +In addition, commands to browse your open documents are provided: + +Menu items + + + + + +&Alt;Left +Document +Back + + + +This will bring the previous document in the stack in focus. If you have +multiple frames, an editor for the document will be displayed in the currently +active frame. The order is the order in which documents were +opened, rather than a logical history. This behavior may change in future +versions of &kate;. + + + + + + + +&Alt;Right +Document +Forward + + + +This will bring the next document in the stack in focus. If you have +multiple frames, an editor for the document will be displayed in the currently +active frame. +The order is the order in which the documents were opened, +rather than a logical history. This behavior may change in future versions of +&kate;. + + + + + + + +The <guimenu>View</guimenu> menu + +The View menu allows you to manage settings +specific to the active editor, and to manage frames. + + +Menu Items + + +F7 +ViewSwitch to Command Line + +This command will toggle the display of the +built in command line. + + + + +ViewSchema + +This menu lists the available schemas. You can change the schema +for the current view here, to change the default schema you need to +use the config dialog + + + + +F10 + +ViewDynamic Word Wrap + +Toggles dynamic word wrap in the current view. Dynamic word +wrap makes all the text in a view visible without the need for horizontal +scrolling by rendering one actual line on more visual lines as needed. + + + + +ViewShow/Hide Static Word +Wrap Marker +Toggles the display of a vertical line indicating the position +of the wrap width as configured in the config dialog. This +feature requires that you use a true fixed-width font. + + + + + + + +F6 +View +Show/Hide Icon Border + + + +This is a toggle item. Setting it on checked will make the Icon Border +visible in the left side of the active editor, and vice versa. + + + + + + + +F11 +View +Show/Hide Line Numbers + + + +This is a toggle Item. Setting it on checked will make a pane displaying +the line numbers of the document visible in the left border of the active editor, +and vice versa. + + + + +ViewShow/Hide Scrollbar +Marks +Toggles the visualization of bookmarks (and other marks) on the +vertical scrollbar. When enabled, marks are represented by a thin line in the +mark color at the scrollbar, middleclicking on the lines will scroll the view +to a position near the mark. + + + +F9 + +ViewShow/Hide Folding Markers + +Toggles the display of the folding marker pane in the left +side of the view. See Using +Code Folding. + + + + + + +Code Folding + + + + + + +&Ctrl; +Shift- +Collapse Toplevel + +Collapse all toplevel regions in the document. + + +&Ctrl; +Shift+ +Expand Toplevel + +Expand all toplevel regions in the document. + + +&Ctrl; +- +Collapse One Local Level + +Collapse the region closest to the cursor. + + +&Ctrl; ++ +Expand One Local Level + +Expand the region closest to the cursor. + + + + + + + + + + + +The <guimenu>Bookmarks</guimenu> Menu + +The Bookmarks menu allows you to work with +the bookmarks in the currently active document. + +Below the entries described here, one entry for each bookmark in +the active document will be available. The text will be the first few +words of the marked line. Choose an item to move the cursor to the +start of that line. The editor will scroll as necessary to make that +line visible. + + + +Menu Items + + + + + +&Ctrl;B +Bookmarks +Set/Clear Bookmark + + + +Sets or removes a bookmark in the current line of the active document. +(If it's there, it is removed, otherwise one is set.) + + + + + + + +Bookmarks +Clear All Bookmarks + + + +Clears (removes) all bookmarks in the active document. + + + + +&Alt; +Page Up +BookmarksPrevious + +This will move the cursor to beginning of the first above line +with a bookmark. The menuitem text will include the line number and the first +piece of text on the line. This item is only available when there is a bookmark +in a line above the cursor. + + + +&Alt; +Page Down +BookmarksNext +This will move the cursor to beginning of the next line with a +bookmark. The menuitem text will include the line number and the first piece of +text on the line. This item is only available when there is a bookmark in a line +below the cursor. + + + + + + + + +The <guimenu>Tools</guimenu> Menu + + + + +ToolsPipe to +Console +Feed the currently selected text ito the built in terminal +emulator. No newline is added after the text. + + + +ToolsExternal +Tools +This submenu contains all the external toolsyou have +configured. + + + + +Tools +Read Only Mode + +Set the current document to Read Only mode. This prevents any text +addition and any changes in the document formatting. + + + + + +Tools +Filletype + +Choose the filetype scheme you prefer for the active document. This +overwrites the global filetype +mode set in Settings Configure +Editor... in the Filetypes tab for your current +document only. + + + + + +Tools +Highlighting + +Choose the Highlighting scheme you prefer for the active document. This +overwrites the global highlighting mode set in +Settings Configure Editor... + for your current document only. + + + + + +Tools +Indentation + +Choose the style of +indentation you want for your active document. +This overwrites the global indentation mode set in +Settings Configure Editor... + for your current document only. + + + + + +Tools +Encoding + +You can overwrite the default encoding set in +Settings +Configure +Editor... in the Open/Save tab +to set a different encoding for your current document. The encoding you +set here will be only valid for your current document. + + + + + +Tools +End of Line + +Choose your prefered end of line mode for your active +document. This overwrites the global end of line mode set in +Settings Configure Editor... + for your current document only. + + + + + +ToolsSpelling... + + +This initiates the spellchecking program - a program +designed to help the user catch and correct any spelling errors. +Clicking on this entry will start the checker and bring up the speller dialog +box through which the user can control the process. There are four settings +lined up vertically in the center of the dialog with their corresponding labels +just to the left. Starting at the top they are: + + + +Unknown word: +Here, the spellchecker indicates the word currently under +consideration. This happens when the checker encounters a word not in its +dictionary - a file containing a list of correctly spelled words against which +it compares each word in the editor. + + +Replace with: + If the checker has any similar words in its dictionary the +first one will be listed here. The user can accept the suggestion, type in his +or her own correction, or choose a different suggestion from the next +box. + + +Suggested Words: + The checker may list here a number of possible replacements for +the word under consideration. Clicking on any one of the suggestions will cause +that word to be entered in the Replacement: box, +above. + + +Language: + If you have installed multiple dictionaries, here you can +select which dictionary/language should be used. + + + +On the right side of the dialog box are 5 buttons that allow the user to +control the spellcheck process. They are: + + + +Add to Dictionary +Pressing this button adds the word in the Misspelled +Word: box to the checker's dictionary. This means that in the future +the checker will always consider this word to be correctly +spelled. + + +Replace + This button has the checker replace the word under +consideration in the document with the word in the +Replacement: box. + + +Replace All + This button causes the checker to replace not only the current +Unknown word: but to automatically make the same +substitution for any other occurrences of this Misspelled +Word: in the document. + + +Ignore +Activating this button will have the checker move on without +making any changes. + + +Ignore All + This button tells the checker to do nothing with the current +Unknown word: and to pass over any other instances of +the same word. This only applies to the current spellcheck +run. If the checker is run again later it will stop on this same +word. + + + +Three more buttons are located horizontally along the bottom of the +spellcheck dialog. They are: + + + +Help + This invokes the &kde; help system starting at the &kate; help +pages (this document). + + + +Finished + This button ends the spellcheck process, and returns to the +document. + + + +Cancel + This button cancels the spellcheck process, all modifications +are reverted, and you will return to your document. + + + + + + + + + +Tools +Spelling (from cursor)... + +This initiates the spellchecking program but it starts where your cursor +is instead of at the beginning of the document. + + + + + +Tools +Spellcheck Selection... + +Spellchecks the current selection. + + + + + + +&Ctrl;I + +ToolsIndent + +This increases the paragraph's indentation by one step. The size of the +step depends on the indentation +settings. + + + + + + +&Ctrl;&Shift;I + +ToolsUnindent + + +This reduces the paragraph's indentation by one step. The size of the step + +depends on the indentation settings. + + + + + + +ToolsClean +Indentation +This cleans the indentation for the current selection or for the +line the cursor is currently in. Cleaning the indentation ensures that +all your selected text follows the indentation mode you choose. + + + + + +Tools +Align + + +Causes a realign of the current line or selected lines using the +indentation mode and indentation settings in the doucment. + + + + + + +&Ctrl;D + +Tools +Comment + +This adds one space to the beginning of the line +where the text cursor is located or to the beginning of any +selected lines. + + + + + + +&Ctrl;&Shift;D + +Tools +Uncomment + +This removes one space (if any exist) from the beginning of the +line where the text cursor is located or from the beginning of any +selected lines. + + + + + +&Ctrl;U + +Tools +Uppercase + +Put the selected text or the letter after the cursor in +uppercase. + + + + + +&Ctrl;&Shift;U + +Tools +Lowercase + +Put the selected text or the letter after the cursor in +lowercase. + + + + + +&Alt;&Ctrl;U + +Tools +Capitalize + +Capitalize the selected text or the current +word. + + + + + +&Ctrl;J + +Tools +Join Lines + +Joins the selected lines, or the current line and the line below +with one white space character as a separator. Leading/trailing white space on +joined lines is removed in the affected ends. + + + + +Tools +Word Wrap Document + +Apply static word wrapping on all the document. That means that +a new line of text will automatically start when the current +line exceeds the length specified by the Wrap words at: option +in the Editing tab in +SettingsConfigure +Editor... + + + + + + + + +The <guimenu>Sessions</guimenu> Menu + +This menu contains entries for using and managing &kate; sessions. +For more information, read Using Sessions. + + + + +Sessions +New +Creates a new empty session. All currently open files will +be closed. + + + + +SessionsOpen... + +Open an existing session. The Session Chooser dialog is +displayed to let you choose one. + + + +SessionsQuick Open + +This submenu lets you open an existing session. + + + + +SessionsSave + +Save the current session. If the session is anonymous, you will +be prompted for a session name. + + + +SessionsSave +As... +Save the current session under a new name. You are prompted for +a name to use. + + + +SessionsManage... + +Displays the Session Manager dialog which allows you to rename +and delete sessions. + + + + + + + + + +The <guimenu>Settings</guimenu> Menu + +The Settings menu allows you to change the properties +of the main window, such as showing/hiding toolbars, and provides +access to the configuration dialogs. + + + + + + + +Settings +Toolbars + + + +This submenu lists the available toolbars, each item toggles the display +of the associated toolbar. + + + + +SettingsFull Screen +Mode +Toggles full screen display. +This commmand will be moved to the Window menu in a future +version of &kate; + + + + + + + +Settings +Configure Shortcuts... + + + +Display the familiar &kde; Keyboard Shortcut Configuration +Dialog. + + + + + + + + +Settings +Configure Toolbars... + + + +Display the familiar &kde; Toolbar Configuration Dialog. + + + + + + + +Settings +Configure &kate;... + + + +Launch the Main Configuration Dialog + + + + + + + + +the <guimenu>Window</guimenu> Menu + + + + + + +Window +New Window + + + + +Opens another instance of &kate;. +The new instance will be identical to your previous instance. + + + + + + + + +&Ctrl;&Shift;L +Window +Split Vertical + + + +This will split the frame (which may be the main editing area) in two equally sized frames, +the new one to the left of the current one. The new frame gets the focus, and will display the +same document as the old one. +See also Working with the &kate; MDI + + + + + + + +&Ctrl;&Shift;T +Window +Split Horizontal + + + +Splits the current frame (which may be the main editing area) in two equally sized frames, +the new one at the bottom half. The new frame gets the focus, and displays the same document as +the old one. +See also Working with the &kate; MDI + + + + + + + +&Ctrl;&Shift;R +Window +Close Current + + + +Closes the active frame. This is disabled, if there is only one frame +(the main editing area). No documents get closed by closing a +frame – they will still be available in the Documents Menu as well as in +the File List. See also Working with the +&kate; MDI + + + + +F8 +WindowNext +View +Focus the next document view, if you have split the editor area +in more views. + + + +&Shift;F8 +WindowPrevious +View +Focus the previous document view, if you have split the editor +area in more views. + + + +WindowTool Views + + + + + +WindowTool Views +Show/Hide Sidebars +Toggles the display of the sidebar button rows. This command +does not affect the display of the sidebar content widgets, any sidebar that +is visible will stay visible, and if you assigned shortcuts to the below +commands those will of course continue to work. + + + + + + +WindowTool Views +Show Documents + + + +Toggle the display of &kate;'s Documents list + + + + + + + +WindowTool Views +Show/Hide Filesystem Browser + + + +Toggle the display of &kate;'s Filesystem Browser + + + + + + + +WindowTool Views +Show/Hide Find in Files + + + +Toggle the display of &kate;'s Find in Files tool. + + + + + + + + +WindowTool Views +Show/Hide Terminal + + + +Toggles the display of the built in terminal emulator. +When activated the first time, the terminal will be created. +When the terminal emulator is displayed, it will get the focus, so that +you can start typing in commands immediately. If the Sync Konsole with Active +Document option is enabled in the General Page of the Main configuration dialog the shell session will +change to the directory of the active document, if it is a local file. + + + + + + + + + + + + + + +The <guimenu>Help</guimenu> Menu + +Apart from standard &kde; Help menu items +described below you will have menu entries to show the +Plugins User Manuals for installed plugins. + +&help.menu.documentation; + + + + diff --git a/doc/kate/mimetypechooser.png b/doc/kate/mimetypechooser.png new file mode 100644 index 000000000..45220f8a4 Binary files /dev/null and b/doc/kate/mimetypechooser.png differ diff --git a/doc/kate/part.docbook b/doc/kate/part.docbook new file mode 100644 index 000000000..e09725b31 --- /dev/null +++ b/doc/kate/part.docbook @@ -0,0 +1,671 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Working with the &kate; editor + + + +Overview + +The &kate; editor is the editing area of the &kate; window. This +editor is also used by &kwrite;, and it can be used in &konqueror; for +displaying text files from your local computer, or from the +network. + +The editor is composed of the following components: + + + + +The editing area +This is where the text of your document is located. + + + +The Scroll bars + +The scroll bars indicate the position of the visible part of +the document text, and can be used to move around the +document. Dragging the scrollbars will not cause the insertion cursor +to be moved. +The scroll bars are displayed and hidden as required. + + + + +The Icon Border + +The icon border is a small pane on the left side of the editor, +displaying a small icon next to marked lines. +You can set or remove a bookmark in a visible line by +clicking the &LMB; in the icon border next to that line. +The display of the icon border can be toggled using the +View Show Icon +Border menu item. + + + + +The Line Numbers Pane + +The Line numbers pane shows the line numbers of all visible +lines in the document. +The display of the Line Numbers Pane can be toggled using the +View Show Line +Numbers menu item. + + + + +The Folding Pane + +The folding pane allows you to collapse or expand foldable blocks +of lines. The calculation of the foldable regions are done according to +rules in the syntax highlight definition for the document. + + + + + + +Also in this Chapter: +Navigating in the +Text +Working with the +Selection +Copying and +Pasting Text +Finding and +Replacing Text +Using +Bookmarks +Automatically +Wrapping Text +Using automatic indenting + + + + + +Navigating in the Text + +Moving around in the text in &kate; is like in most graphical text +editors. You move the cursor using the arrow keys and the +Page Up, Page Down, Home and +End keys in combination with the Ctrl and +Shift modifiers. The Shift key is always used +to generate a selection, while the Ctrl key have different +effects on different keys: + +For the Up and Down keys it +means scroll rather than move the cursor. +For the Left and Right +keys it means skip words rather than characters. +for the Page Up and Page Down +keys it means move to the visible edge of the view rather than browse. + +For the Home and End keys it +means move to the beginning or end of the document rather than the beginning or +end of the line. + + + +&kate; also provides you with a way to quickly jump to a matching brace +or paranthese: Place the cursor on the inside of a parenthese or brace +character, and press Ctrl6 +to jump to the matching parenthese or brace. + +In addition you can use +bookmarks to quickly jump to +positions that you define on your own. + + + + +Working with the Selection + +There are two basic ways of selecting text in &kate;: using the +mouse, and using the keyboard. + +To select using the mouse, hold down the &LMB; while dragging +the mouse cursor from where the selection should start, to the desired +end point. The text gets selected as you drag. + +Double-clicking a word will select that word. + +Triple-clicking in a line will select the entire line. + +If &Shift; is held down while clicking, text will be +selected: + + +If nothing is already selected, from the text cursor +position to the mouse cursor position. +If there is a selection, from and including that +selection to the mouse cursor position + + + +When selecting text by dragging the mouse, the +selected text is copied to the clipboard, and can be pasted by +clicking the middle mouse button in the editor, or in any other +application to which you want to paste the text. + + + +To select using the keyboard, hold down the &Shift; key while +using the navigation keys (The Arrow keys, Page Up, +Page Down, Home and +End, possibly in combination with &Ctrl; to extend +the move of the text cursor). + +See also the section Navigating in the Text in this +Chapter. + +To Copy the current selection, use the +Edit +Copy menu item or the keyboard +shortcut (defaults to &Ctrl;C). + +To Deselect the current selection, use the +Edit +Deselect menu item, or the +keyboard shortcut (default is &Ctrl;&Shift;A), or click +with the &LMB; in the editor. + + +Using Block Selection + +When Block Selection is enabled, you can make vertical +selections in the text, meaning selecting limited columns from +multiple lines. This is handy for working with tab separated lines for +example. + +Block Selection can be toggled using the +Edit Toggle Block +Selection menu item. The default keyboard +shortcut is F4 + + + + + +Using Overwrite Selection + +If Overwrite Selection is enabled, typing or pasting text into +the selection will cause the selected text to be replaced. If not +enabled, new text will be added at the position of the text +cursor. + +Overwrite Selection is enabled by default. + +To change the setting for this option, use the Select Page of the Configuration Dialog. + + + + + +Using Persistent Selection + +When Persistent selection is enabled, typing characters or +moving the cursor will not cause the Selection to become +deselected. This means that you can move the cursor away from the +selection and type text. + +Persistent Selection is disabled by default. + +Persistent Selection can be enabled in the Select Page of the Configuration Dialog. + + +If Persistent Selection and Overwrite Selection are both +enabled, typing or pasting text when the text cursor is inside the +selection will cause it to be replaced and deselected. + + + + + + + + +Copying and Pasting Text + +To copy text, select it and use the +Edit +Copy menu item. Additionally, +selecting text with the mouse will cause selected text to be copied to +the X selection. + +To paste the text currently in the clipboard, use the + +EditPaste +menu item. + +Additionally, text selected with the mouse may be pasted by +clicking the middle mouse button at the +desired position. + + +If you are using the &kde; desktop, you can retrieve earlier +copied text from any application using the &klipper; icon in the +&kicker; icon tray. + + + + + +Finding and Replacing Text + + +The <guilabel>Find Text</guilabel> and <guilabel>Replace +Text</guilabel> Dialogs + + +The Find and Replace Text dialogs in &kate; are very much the +same, except the Replace Text dialog offers the means of entering a +replacement string along with a few extra options. + +The dialogs offer the following common options: + + + + +Text to Find +This is where to enter the search string. The interpretation of the string +depends on some of the options described below. + + + +Regular Expression + +If checked, the search string is interpreted as a regular +expression. A button for using a graphical tool to create or edit the +expression will be enabled. +See Regular +Expressions for more on these. + + + + +Case Insensitive + +If enabled, the search will be case insensitive. + + + + +Whole Words Only + +If checked, the search will only match if there is a word +boundary at both ends of the string matching, meaning not an +alphanumeric character - either some other visible character or a line +end. + + + + +From cursor + +If checked, the search will start at cursor position, otherwise it will +start at the beginning of the first line in the document. + + + + +Find Backwards + +If checked, the search will look for the first match above the +starting point, either cursor position or the beginning of the +document, if the From Beginning option is +enabled. + + + + + +The Replace Text Dialog offers some +additional options: + + + + +Replace With +This is where to enter the replacement +string. + + + +Selected Text + +This option is disabled if no text is selected, or if the +Prompt on Replace +option is enabled. If checked, all matches of the search string within +the selected text will be replaced with the replace string. + + + + +Prompt on Replace +If checked, a small dialog will prompt you for what to +do for each time a match is found. It offers the following options: + + + +Yes +Activate this to replace the current match (which is +selected in the editor). + + + +No +Activate to skip the current match, and try to find another one. + + + +All +Activate to cancel prompting, and just replace all +matches. + + + +Close +Activate this to skip the current match and end the +searching. + + + + + + + + + + +There is currently no way to use minimal matching when searching +for a regular expression. This will be added in a future version of +&kate; + + + + + +Finding Text + +To find text, launch the Find Text Dialog +with &Ctrl;For +from the Edit +Find... menu item, enter a +search string, set the options as desired and hit +Ok. If the search was started at cursor position and no +match was found before reaching the end (or beginning if you are searching +backward) of the document, you will be asked if you want to wrap the search. + + +If a match is found it is selected and the Find +Text Dialog is hidden, but stay tuned, finding further +matches is very easy: + +To find the next match in the search direction, use the +Edit Find +Next command or press +F3. + +To find the next match in the opposite direction, use the +Edit Find +Previous command or press &Shift;F3. + +If no match is found before reaching the document end (or beginning if you +are searching backward) , you will be asked if you want to wrap the search. + + + + + +Replacing Text + +To replace text, launch the Replace text +Dialog using the Edit +Replace command, or the +&Ctrl;R shortcut, +enter a search string and optionally a replace string (if the replace +string is empty, each match will be removed), set +the options as desired and +hit the Ok button. + + +If you are using a regular expression to find the text to replace, you can +employ backreferences to reuse text captured in parenthesized subpatterns of the expression. +See for more +on those. + + +You can do find, replace and +ifind (incremental search) from the +command line. + + + + + + + +Using Bookmarks + +The bookmarks feature allows you to mark certain lines, to be +able to easily find them again. + +You can set or remove a bookmark in a line in two ways: + + + +Move the insertion cursor to the line and activate the +BookmarksToggle +Bookmark (&Ctrl;B) command. + + +Click in the Icon Border next to the line. + + + + +Bookmarks are available in the Bookmarks +menu. The individual bookmarks are available as menu items, labeled +with the line number of the line with the bookmark, and the first few +characters of the text in the line. To move the insertion cursor to +the beginning of a bookmarked line, open the menu and select the +bookmark. + +To quickly move between bookmarks or to the next/previous bookmark, +use the BookmarksNext + (Ctrl +Page Down) or +BookmarksPrevious +(CtrlPage Up +) commands. + + + + + +Automatically Wrapping text + +This feature allows you to have the text formatted in a very simple way: the text will be wrapped, +so that no lines exceed a maximum number of characters per line, unless there is a longer string of +non-whitespace characters. + +To enable/disable it, check/uncheck the Word Wrap checkbox in the +edit page of the configuration dialog. + +To set the maximum line width (maximum characters per line), use the +Wrap Words At +option in the edit page of the configuration +dialog. + +If enabled, +it has the following effects: + + +While typing, the editor will automatically insert a hard line break after +the last whitespace character at a position before the maximum line width is reached. +While loading a document, the editor will wrap the text in a similar way, so that +no lines are longer than the maximum line width, if they contain any whitespace allowing that. + + + + +There is currently no way to set word wrap for document types, or even to enable or disable +the feature on document level. This will be fixed in a future version of &kate; + + + + +Using automatic indenting + +&kate;s editor component supports a variation of autoindenting modes, +designed for different text formats. You can pick from the available modes using +the ToolsIndentation +menu. The autoindent modules also provides a function +ToolsAlign +which will recalculate the indentation of the selected or current line. Thus, +you may reindent your entire document by selecting all the text and activating +that action. + +All the indent modes use the indentation related settings in the active +document. + +You can set all sorts of configuration variables, including +those related to indentation using Document +Variables and File +types. + + + +Available Autoindent Modes + + +None +Selecting this mode turns automatic indenting off entirely. + + + + +Normal +This indenter simply keeps the indentation similar to the +previous line with any content other than whitespace. You can combine this +with using the indent and unindent actions for indenting to your own taste. + + + +C Style +An indenter for C and similar languages, such as +C++, C#, java, javascript and so on. This indenter will not work with scripting +languages such as Perl or PHP. + + + +SS C Style +An alternative indenter for C and similar languages, with the +same constraints. + + + +Python Style +An indenter specifically for the python scripting language. + + + + +XML +A very nice XML auto-indenter. However tempting, do not try to +use this with HTML other than XHTML, because it fails with the old style +HTML tags (open tags like for example <br>) + + + +Variable Indenter + + + +The variable indenter is experimental, and may change behavior or +disappear in future versions. + + + +The variable indenter is special in that it can be configured using variables in +the document (or in a filetype configuration). The followwing variables are +read: + + + +var-indent-indent-after + +A regular expression which will cause a line to +be indented by one unit, if the first non-whitespace-only line above matches. +var-indent-indent: A regular expression, which will cause a matching line +to be indented by one unit. + + + + + +var-indent-unindent + +A regular expression which will cause the line to be +unindented by one unit if matching. + + + + +var-indent-triggerchars + +A list of characters that should cause the +indention to be recalculated immediately when typed. + + + + +var-indent-handle-couples + +A list of parenthese sets to handle. Any combination +of 'parens' 'braces' and 'brackets'. Each set type is handled +the following way: If there are unmatched opening instances on the above line, +one indent unit is added, if there are unmatched closing instances on the +current line, one indent unit is removed. + + + + +var-indent-couple-attribute + +When looking for unmatched couple openings/closings, +only characters with this attribute are considered. The value must be the +attribute name from the syntax xml file, for example "Symbol". If it's not +specified, attribute 0 is used (usually 'Normal Text'). + + + + + + + + + + + + + diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook new file mode 100644 index 000000000..a097cb526 --- /dev/null +++ b/doc/kate/plugins.docbook @@ -0,0 +1,28 @@ + + + + +&Anders.Lund; &Anders.Lund.mail; + + + + +Working with Plug-ins + +Kate is using two different forms of plug-ins, namely plug-ins for the +&kate; application and plug-ins for the &kate; editor component. The latter are +available to any application using the editor component, such as KDevelop, +Quanta, Kile, Kwrite and many others, while application plug-ins are specific +to the &kate; application. + +You can enable both types of plug-ins in the configuration dialog, which also +provides access to additional configuration options for plug-ins that requires +that. + +There are many plugins for various purposes available in the kdeaddons +module, and you can search the web for more. A few plugins are shipped with the +editor component, for doing word completion, automatic bookmarks, insert files, +thesaurus and word spell checking and incremental search. + + diff --git a/doc/kate/regular-expressions.docbook b/doc/kate/regular-expressions.docbook new file mode 100644 index 000000000..c15685d75 --- /dev/null +++ b/doc/kate/regular-expressions.docbook @@ -0,0 +1,664 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + + +Regular Expressions + + This Appendix contains a brief but hopefully sufficient and +covering introduction to the world of regular +expressions. It documents regular expressions in the form +available within &kate;, which is not compatible with the regular +expressions of perl, nor with those of for example +grep. + + + +Introduction + +Regular Expressions provides us with a way +to describe some possible contents of a text string in a way +understood by a small piece of software, so that it can investigate if +a text matches, and also in the case of advanced applications with the +means of saving pieces or the matching text. + +An example: Say you want to search a text for paragraphs that +starts with either of the names Henrik or +Pernille followed by some form of the verb +say. + +With a normal search, you would start out searching for the +first name, Henrik maybe followed by sa +like this: Henrik sa, and while looking for +matches, you would have to discard those not being the beginning of a +paragraph, as well as those in which the word starting with the +letters sa was not either says, +said or so. And then of cause repeat all of that with +the next name... + +With Regular Expressions, that task could be accomplished with a +single search, and with a larger degree of preciseness. + +To achieve this, Regular Expressions defines rules for +expressing in details a generalization of a string to match. Our +example, which we might literally express like this: A line +starting with either Henrik or Pernille +(possibly following up to 4 blanks or tab characters) followed by a +whitespace followed by sa and then either +ys or id could be expressed with +the following regular expression: ^[ +\t]{0,4}(Henrik|Pernille) sa(ys|id) + +The above example demonstrates all four major concepts of modern +Regular Expressions, namely: + + +Patterns +Assertions +Quantifiers +Back references + + +The caret (^) starting the expression is an +assertion, being true only if the following matching string is at the +start of a line. + +The stings [ \t] and +(Henrik|Pernille) sa(ys|id) are patterns. The first +one is a character class that matches either a +blank or a (horizontal) tab character; the other pattern contains +first a subpattern matching either Henrik +or Pernille, then a piece +matching the exact string sa and finally a +subpattern matching either ys +or id + +The string {0,4} is a quantifier saying +anywhere from 0 up to 4 of the previous. + +Because regular expression software supporting the concept of +back references saves the entire matching part of +the string as well as sub-patterns enclosed in parentheses, given some +means of access to those references, we could get our hands on either +the whole match (when searching a text document in an editor with a +regular expression, that is often marked as selected) or either the +name found, or the last part of the verb. + +All together, the expression will match where we wanted it to, +and only there. + +The following sections will describe in details how to construct +and use patterns, character classes, assertions, quantifiers and +back references, and the final section will give a few useful +examples. + + + + + +Patterns + +Patterns consists of literal strings and character +classes. Patterns may contain sub-patterns, which are patterns enclosed +in parentheses. + + +Escaping characters + +In patterns as well as in character classes, some characters +have a special meaning. To literally match any of those characters, +they must be marked or escaped to let the regular +expression software know that it should interpret such characters in +their literal meaning. + +This is done by prepending the character with a backslash +(\). + + +The regular expression software will silently ignore escaping a +character that does not have any special meaning in the context, so +escaping for example a j (\j) is +safe. If you are in doubt whether a character could have a special +meaning, you can therefore escape it safely. + +Escaping of cause includes the backslash character it self, to +literally match a such, you would write +\\. + + + + +Character Classes and abbreviations + +A character class is an expression that +matches one of a defined set of characters. In Regular Expressions, +character classes are defined by putting the legal characters for the +class in square brackets, [], or by using one of +the abbreviated classes described below. + +Simple character classes just contains one or more literal +characters, for example [abc] (matching either +of the letters a, b or c) +or [0123456789] (matching any digit). + +Because letters and digits have a logical order, you can +abbreviate those by specifying ranges of them: +[a-c] is equal to [abc] +and [0-9] is equal to +[0123456789]. Combining these constructs, for +example [a-fynot1-38] is completely legal (the +last one would match, of cause, either of +a,b,c,d, +e,f,y,n,o,t, +1,2,3 or +8). + +As capital letters are different characters from their +non-capital equivalents, to create a caseless character class matching +a or b, in any case, you need to write it +[aAbB]. + +It is of cause possible to create a negative +class matching as anything but To do so put a caret +(^) at the beginning of the class: + +[^abc] will match any character +but a, b or +c. + +In addition to literal characters, some abbreviations are +defined, making life still a bit easier: + + + + +\a + This matches the ASCII bell character (BEL, 0x07). + + + +\f + This matches the ASCII form feed character (FF, 0x0C). + + + +\n + This matches the ASCII line feed character (LF, 0x0A, Unix newline). + + + +\r + This matches the ASCII carriage return character (CR, 0x0D). + + + +\t + This matches the ASCII horizontal tab character (HT, 0x09). + + + +\v + This matches the ASCII vertical tab character (VT, 0x0B). + + +\xhhhh + + This matches the Unicode character corresponding to +the hexadecimal number hhhh (between 0x0000 and 0xFFFF). \0ooo (&ie;, +\zero ooo) matches the ASCII/Latin-1 character +corresponding to the octal number ooo (between 0 and +0377). + + + +. (dot) + This matches any character (including newline). + + + +\d + This matches a digit. Equal to [0-9] + + + +\D + This matches a non-digit. Equal to [^0-9] or [^\d] + + + +\s + This matches a whitespace character. Practically equal to [ \t\n\r] + + + +\S + This matches a non-whitespace. Practically equal to [^ \t\r\n], and equal to [^\s] + + + +\w +Matches any word character - in this case any letter or digit. Note that +underscore (_) is not matched, as is the case with perl regular expressions. +Equal to [a-zA-Z0-9] + + + +\W +Matches any non-word character - anything but letters or numbers. +Equal to [^a-zA-Z0-9] or [^\w] + + + + + + + +The abbreviated classes can be put inside a custom class, for +example to match a word character, a blank or a dot, you could write +[\w \.] + + The POSIX notation of classes, [:<class +name>:] is currently not supported. + + +Characters with special meanings inside character classes + +The following characters has a special meaning inside the +[] character class construct, and must be escaped to be +literally included in a class: + + + +] +Ends the character class. Must be escaped unless it is the very first character in the +class (may follow an unescaped caret) + + +^ (caret) +Denotes a negative class, if it is the first character. Must be escaped to match literally if it is the first character in the class. + + +- (dash) +Denotes a logical range. Must always be escaped within a character class. + + +\ (backslash) +The escape character. Must always be escaped. + + + + + + + + + + +Alternatives: matching <quote>one of</quote> + +If you want to match one of a set of alternative patterns, you +can separate those with | (vertical bar character). + +For example to find either John or Harry you would use an expression John|Harry. + + + + + +Sub Patterns + +Sub patterns are patterns enclosed in +parentheses, and they have several uses in the world of regular +expressions. + + + +Specifying alternatives + +You may use a sub pattern to group a set of alternatives within +a larger pattern. The alternatives are separated by the character +| (vertical bar). + +For example to match either of the words int, +float or double, you could use the +pattern int|float|double. If you only want to +find one if it is followed by some whitespace and then some letters, +put the alternatives inside a subpattern: +(int|float|double)\s+\w+. + + + + + +Capturing matching text (back references) + +If you want to use a back reference, use a sub pattern to have +the desired part of the pattern remembered. + +For example, it you want to find two occurrences of the same +word separated by a comma and possibly some whitespace, you could +write (\w+),\s*\1. The sub pattern +\w+ would find a chunk of word characters, and the +entire expression would match if those were followed by a comma, 0 or +more whitespace and then an equal chunk of word characters. (The +string \1 references the first sub pattern +enclosed in parentheses) + + + + + + +Lookahead Assertions + +A lookahead assertion is a sub pattern, starting with either +?= or ?!. + +For example to match the literal string Bill but +only if not followed by Gates, you could use this +expression: Bill(?! Gates). (This would find +Bill Clinton as well as Billy the kid, +but silently ignore the other matches.) + +Sub patterns used for assertions are not captured. + +See also Assertions + + + + + + +Characters with a special meaning inside patterns + +The following characters have meaning inside a pattern, and +must be escaped if you want to literally match them: + + + + +\ (backslash) +The escape character. + + + +^ (caret) +Asserts the beginning of the string. + + + +$ +Asserts the end of string. + + + +() (left and right parentheses) +Denotes sub patterns. + + + +{} (left and right curly braces) +Denotes numeric quantifiers. + + + +[] (left and right square brackets) +Denotes character classes. + + + +| (vertical bar) +logical OR. Separates alternatives. + + + ++ (plus sign) +Quantifier, 1 or more. + + + +* (asterisk) +Quantifier, 0 or more. + + + +? (question mark) +An optional character. Can be interpreted as a quantifier, 0 or 1. + + + + + + + + + + + +Quantifiers + +Quantifiers allows a regular expression to +match a specified number or range of numbers of either a character, +character class or sub pattern. + +Quantifiers are enclosed in curly brackets ({ +and }) and have the general form +{[minimum-occurrences][,[maximum-occurrences]]} + + +The usage is best explained by example: + + + + +{1} +Exactly 1 occurrence + + + +{0,1} +Zero or 1 occurrences + + + +{,1} +The same, with less work;) + + + +{5,10} +At least 5 but maximum 10 occurrences. + + + +{5,} +At least 5 occurrences, no maximum. + + + + + + +Additionally, there are some abbreviations: + + + + +* (asterisk) +similar to {0,}, find any number of occurrences. + + + ++ (plus sign) +similar to {1,}, at least 1 occurrence. + + + +? (question mark) +similar to {0,1}, zero or 1 occurrence. + + + + + + + + +Greed + +When using quantifiers with no maximum, regular expressions +defaults to match as much of the searched string as possible, commonly +known as greedy behavior. + +Modern regular expression software provides the means of +turning off greediness, though in a graphical +environment it is up to the interface to provide you with access to +this feature. For example a search dialog providing a regular +expression search could have a check box labeled Minimal +matching as well as it ought to indicate if greediness is the +default behavior. + + + + +In context examples + +Here are a few examples of using quantifiers + + + + +^\d{4,5}\s +Matches the digits in 1234 go and 12345 now, but neither in 567 eleven +nor in 223459 somewhere + + + +\s+ +Matches one or more whitespace characters + + + +(bla){1,} +Matches all of blablabla and the bla in blackbird or tabla + + + +/?> +Matches /> in <closeditem/> as well as +> in <openitem>. + + + + + + + + + +Assertions + +Assertions allows a regular expression to +match only under certain controlled conditions. + +An assertion does not need a character to match, it rather +investigates the surroundings of a possible match before acknowledging +it. For example the word boundary assertion does +not try to find a non word character opposite a word one at its +position, instead it makes sure that there is not a word +character. This means that the assertion can match where there is no +character, &ie; at the ends of a searched string. + +Some assertions actually does have a pattern to match, but the +part of the string matching that will not be a part of the result of +the match of the full expression. + +Regular Expressions as documented here supports the following +assertions: + + + + +^ (caret: beginning of +string) +Matches the beginning of the searched +string. The expression ^Peter will +match at Peter in the string Peter, hey! +but not in Hey, Peter! + + + +$ (end of string) +Matches the end of the searched string. + +The expression you\?$ will match at the +last you in the string You didn't do that, did you? but +nowhere in You didn't do that, right? + + + + + +\b (word boundary) +Matches if there is a word character at one side and not a word character at the +other. +This is useful to find word ends, for example both ends to find +a whole word. The expression \bin\b will match +at the separate in in the string He came in +through the window, but not at the in in +window. + + + + +\B (non word boundary) +Matches wherever \b does not. +That means that it will match for example within words: The expression +\Bin\B will match at in window but not in integer or I'm in love. + + + + +(?=PATTERN) (Positive lookahead) +A lookahead assertion looks at the part of the string following a possible match. +The positive lookahead will prevent the string from matching if the text following the possible match +does not match the PATTERN of the assertion, but the text matched by that will +not be included in the result. +The expression handy(?=\w) will match at handy in +handyman but not in That came in handy! + + + + +(?!PATTERN) (Negative lookahead) + +The negative lookahead prevents a possible match to be +acknowledged if the following part of the searched string does match +its PATTERN. +The expression const \w+\b(?!\s*&) +will match at const char in the string const +char* foo while it can not match const QString +in const QString& bar because the +& matches the negative lookahead assertion +pattern. + + + + + + + + + + + + diff --git a/doc/kate/unhighlighted.png b/doc/kate/unhighlighted.png new file mode 100644 index 000000000..6361032f3 Binary files /dev/null and b/doc/kate/unhighlighted.png differ diff --git a/doc/kcontrol/Makefile.am b/doc/kcontrol/Makefile.am new file mode 100644 index 000000000..930c270cd --- /dev/null +++ b/doc/kcontrol/Makefile.am @@ -0,0 +1,6 @@ + +SUBDIRS = $(AUTODIRS) + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kcontrol/arts/Makefile.am b/doc/kcontrol/arts/Makefile.am new file mode 100644 index 000000000..093f0a698 --- /dev/null +++ b/doc/kcontrol/arts/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/arts diff --git a/doc/kcontrol/arts/index.docbook b/doc/kcontrol/arts/index.docbook new file mode 100644 index 000000000..4fbfa3bff --- /dev/null +++ b/doc/kcontrol/arts/index.docbook @@ -0,0 +1,201 @@ + + + + +]> + +
+ + + +&Mike.McBride; +&Jost.Schenck; + + + + +2005-02-20 +3.4 + + +KDE +KControl +sound server +sound +aRts + + + + +Sound System + +This control module is used to configure the settings for the +&arts; sound server (the &kde; sound server). + + +&arts; + +The top option, labeled Enable the sound system, +enables (or disables) the &arts; sound server entirely. + + +You can find out more about &arts; in general by typing +help:/artsbuilder into the &konqueror; location +bar, or by finding the &arts-builder; documentation in &khelpcenter;. + + + +The rest of the panel consists of options for the &arts; +sound server. + + + +Enable networked sound + +If this option is enabled, then sound requests from the network +will be honored by the sound server. If this option is disabled, the sound +server will only honor requests from the local computer. + + + + +Run with the highest possible priority (realtime priority) +Enabling this option will give the sound server priority over +other applications, which will help alleviate any problems delivering +uninterrupted sound. +This option may require permissions you do not have as a regular +user. +This option also relies on certain real time support from your +system which may not be available. +If you do not have the necessary permissions, or your system does +not have the real time support necessary, enabling this option will not +cause problems. + + + +Sound buffer: +This slider determines how quickly the sound server can use your +computer's resources. The faster the response time, the higher the +CPU load will be. +I would recommend that you start with the sound server set at +250 ms, and use &kde; for a while. If you notice that the sound does +not work correctly, increase the responsiveness one step at a time until +the problems disappear. + + + +Auto-suspend if idle after: + +Normally &arts; locks the sound card device, so that other +applications cannot use it. If you enable this option, then if &arts; +has been idle for the amount of time you set, it will suspend itself, +allowing any application access to the sound hardware. If &arts; +receives another request, it will unsuspend, and continue as normal. +Enabling this option may cause a small delay when you start an &arts; +application. + + + + + +At the bottom of this page are two buttons to allow you to test your +settings, labelled Test Sound and Test +MIDI respectively. + + + + +Hardware + +The first option you can configure in the +Hardware panel is Select the audio +device:. It tells &arts; which sound system to use for input and +output of sound. Current choices are ALSA (Advanced +&Linux; Sound Architecture), OSS (Open Sound System), +ESD (Enlightenment Sound Daemon), no audio at all and +autodetect. In most cases Autodetect will be perfect for +you. + +Other options are: + + + +Full duplex +This option allows the sound server to play and record sound at +the same time. This option should be enabled if you use applications (such as +Internet telephones) which require simultaneous record and +playback. + + +Use custom sampling rate: + +Normally, the sound server defaults to using a sampling rate of +44100 Hz (CD quality), which is supported on almost all +hardware. If you are using certain Yamaha soundcards, you might need to +configure this to 48000 Hz here; if you are using old SoundBlaster cards, like +SoundBlaster Pro, you might need to change this to 22050 Hz. All other values +are possible too and may make sense in certain contexts (&ie; professional +studio equipment). + + + +Quality: + +These settings allow you to configure the quality of the sounds that +will be played. + +Note that a higher sound quality causes a higher CPU +usage. +If you find sound is slow, or using too much +CPU, try reducing this setting. + + + + + +Override device location: + +Normally, the sound server defaults to using the device called +/dev/dsp for sound output. This +should work in most cases. An exception is, for instance, if you are using +devfs, then you should use /dev/sound/dsp instead. Other alternatives +are things like /dev/dsp0 or +/dev/dsp1 if you have a +soundcard that supports multiple outputs or you have multiple +soundcards. + +If you often use non-&arts; aware applications, and you have a +soundcard that supports it, try setting &arts; to use a different +device than /dev/dsp. This +way, other applications will be able to use the default device, while +&arts; is still running, without giving any error messages. + + + + + +Other custom options: +There are some options offered by +&arts; which may not be available in this control module, so you can add +command line options here which will be passed directly to +artsd. The options will be appended, so they +will override the choices made in the +GUI. To see the possible choices, open a &konsole; +window, and type artsd +. + + + + + + + + +&midi-kcontrol; + + + +
diff --git a/doc/kcontrol/arts/midi.docbook b/doc/kcontrol/arts/midi.docbook new file mode 100644 index 000000000..b92fdffb3 --- /dev/null +++ b/doc/kcontrol/arts/midi.docbook @@ -0,0 +1,24 @@ + + + +&Mike.McBride; &Mike.McBride.mail; + + + +<acronym>MIDI</acronym> Configuration + +This section is used to determine which MIDI device +&kde; should use. You can also install a MIDI wrapper around +the device if you want. + +The use of this module is simple. Click once on the +MIDI device that you would like to use from the +list. + +If you want to use a MIDI mapper, simply mark +the checkbox below the list labeled Use MIDI +Mapper. This will allow you to select the map in the text +box below. You can click on the folder icon to browse your filesystem +to find the map if you need it. + + \ No newline at end of file diff --git a/doc/kcontrol/background/Makefile.am b/doc/kcontrol/background/Makefile.am new file mode 100644 index 000000000..2a68936db --- /dev/null +++ b/doc/kcontrol/background/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/background diff --git a/doc/kcontrol/background/index.docbook b/doc/kcontrol/background/index.docbook new file mode 100644 index 000000000..5241462c0 --- /dev/null +++ b/doc/kcontrol/background/index.docbook @@ -0,0 +1,383 @@ + + + +]> + +
+ + + +&Mark.Donohoe; +&Martin.R.Jones; + +&Mike.McBride; + + + + +2005-01-18 +3.4 + + +KDE +KControl +background +wallpaper + + + + + +Background + +The Background module allows you to configure colors or wallpapers for +your desktop background. + +It is comprised of four areas: + + + +Desktop selection area + + +An area for selecting background images + + +The background Preview Monitor + + +An area for determining the background color + + + + + +Selecting the desktop + +The drop down box labeled Setting for +desktop: is used to select the desktop you want to +configure. You can select any of the desktops individually, or you +can select All Desktops and the changes you make +will be applied to all desktops. + + + + +Preview Monitor + +This is a preview window. It will give you a sense of what to +expect with each change. + + + + +Background + +This section allows you to load a wallpaper on top of the color +gradient chosen in the section below. + +There are three choices available here: + + + +No Picture + +No picture background will be shown. The color and pattern +choices below will still take effect. + + + + +Picture + +A single picture will be used as the background for the selected +desktops. +How this picture is positioned and scaled can be fine tuned +below. + + + + +Slide show + +&kde; allows you to have an automatic slide show of wallpaper +images. To enable this option, press the Setup... +button. In the resulting dialog you may choose any +image or folder of images available on your computer, using the +Add... button to navigate your file system. +Remove will remove the currently selected +entry from the list. + +You may choose the length of time any image is displayed in the +Change picture after: box, and you may choose +Show pictures in random order if you don't want +them displayed in the order they are listed. + +Displaying wallpaper requires that the image be kept in +memory. If you are low on memory, using a small, tiled image or none +at all is recommended. + +Scaling or centering a small image still requires an image the +size of your display to be maintained in memory. + + + + + + + +Options + + + +<guilabel>Position:</guilabel> + +Centered +The image will be centered on the screen without changing the +size of the image. The background colors will be present anywhere the image +does not cover. + + +Tiled +The image will be duplicated until it fills the entire +desktop. The first image will be placed in the upper left corner of the screen, +and duplicated downward and to the right. + + +Center Tiled +The image will be duplicated until it +fills the entire desktop. The first image will be placed in the center of the +screen, and duplicated upward, downward to the right, and to the left. + + +Centered Maxpect +The image will be placed in the center of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio of the +original image. This will provide you with an image that is not distorted. + + + +Tiled Maxpect + +The image will be placed in the corner of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio +of the original image. This will provide you with an image that is +not distorted. If there is any space over, the image will be +duplicated to fill it. + + + +Scaled +The image will be scaled to fit the desktop. It will be +stretched to fit to all four corners. This may distort the image. + + +Centered Auto fit + +If the picture fits the desktop size, this mode works like the +centered option. If the picture is larger than the desktop then it is +scaled down to fit while keeping the aspect ratio. + + + + +Scale and Crop + +Magnify the picture without distorting it until it fills both the +width and height of the desktop (cropping the picture if necessary), and +then center it on the desktop. + + + + + + +Colors: + +The first drop down box allows you to choose the type of color, +gradient, or pattern to display under (or in place of) wallpaper. +If you are going to be using a picture as a wallpaper, you +can skip this section of the dialog box. +However, if your chosen wallpaper does not cover the entire +desktop, the chosen colors will still show in the remaining +space. + + + +Single Color +By choosing this mode, you select one color using the +first color bar, and the entire background is covered with this one +color. + + +Horizontal Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Primary +Color on the left edge of the screen, and slowly transform into the +color selected by Blend Color by the time it gets to the +right edge of the screen. + + +Vertical Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Primary +Color on the top edge of the screen, and slowly transform into the +color selected by Blend Color as it moves to the bottom of +the screen. + + +Pyramid Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by +Primary Color in each +corner of the screen, and slowly transform into the color selected by +Blend Color as it moves to the center of the +screen. + + +Pipecross Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by +Primary Color in each corner of the screen, and slowly +transform into the color selected by Blend Color +as it moves to the center of the screen. The shape of +this gradient is different than the pyramid gradient. + + +Elliptic Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by +Blend Color in the center of the screen, and slowly +transform into the color selected by Primary Color +as it moves to the edges, in an elliptical pattern. + + + +Pattern + +The rest of the list are the names of various patterns +or textures you can choose. +Click on +OK, and &kde; will render the pattern you +selected using the two colors you selected. For more on patterns, see +the section Adding, Removing and +Modifying Patterns. + +Select the primary color with the first color bar. If you have +chosen a pattern that requires two colors to be set the secondary +color can be set by pressing the appropriate button. + + + + + + + + + + +Blending: + +The drop down box labeled Blending: contains the +options to make a smooth transition (blend) from the wallpaper as it +changes to the background. + + +A drop down box allows you to select the blending mode. +Many of the modes are similar to blending modes for background colors. Select +your mode from the list, and the preview window shows you what it will look +like. +The Balance slider adjusts the +blending. The results can be seen immediately in the preview +window. +The Reverse roles can reverse the +role of the picture and the background for some types of +blending. + + + + + + + + + + +Advanced options +Located below the preview monitor is a button labeled +Advanced Options. + +To use an external program to determine and change the +background of &kde;, simply select Use the following program +for drawing the background. Available &kde; programs are +listed, select one to enable it. To modify your choice, for example +to change the refresh times, you may press the +Modify... button. + +To add a third party application (⪚ +XEarth) you may use the +Add... button. A dialog will open allowing you +to choose your application, and fill in other data about it. You may +remove any entries from this list by selecting it and pressing the +Remove button. + +Using third party external programs to modify or change the +background is beyond the scope of this document, see their respective +documentation for the format of command-line switches and other +configuration information. + +Also in this section you may choose to set the color of text +that is used for icons on the desktop. If you find icon text +difficult to read against a wallpaper or pattern, you can choose a +solid color to show beneath text, or enable a shadow under the text to +enhance its appearance. + +It is possible to set how many lines of text will be shown beneath each icon with the Lines for icon text: If the text is longer than can be shown in the configured number of lines, it will be truncated. You can also set a value for the Width for icon text: option. The value is in pixels, and the default is Auto, which is a default calculated based on the current font. + + + +Finally you can set the Size of the background +cache:. The default (2048 KB) is usually a safe +choice. + + + + +Adding, Removing and Modifying Wallpapers and Patterns + +There is a button under the preview monitor labelled Get +New Wallpapers that helps you fetch new wallpaper images from a +selection of popular images from the KDE-Look website. You can of course +select any image you have available to use as wallpaper, and it may be +stored in any location on your hard drive. To have a wallpaper show up in +the list automatically for all users, you should save it to the $KDEDIR/share/wallpapers +folder. + +A pattern is a picture file which &kde; uses as a template to +draw your background. The picture file provides the shapes, but &kde; +provides the colors. &kde; is packaged with several patterns, and you also +can add new patterns. + +To add a new pattern that is available to every user on your +computer, simply place the file in $KDEDIR/share/apps/kdesktop/patterns/. + +Copy a .desktop file from +this folder, and name it the same as your new pattern image file. +Modify the contents to suit your new pattern. + +To add a new pattern for a single user, add the files to +$KDEHOME/share/apps/kdesktop/patterns/. + +For best results, the pattern should be a grayscale PNG file. + + + + + +
diff --git a/doc/kcontrol/bell/Makefile.am b/doc/kcontrol/bell/Makefile.am new file mode 100644 index 000000000..dbbc3935c --- /dev/null +++ b/doc/kcontrol/bell/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/bell diff --git a/doc/kcontrol/bell/index.docbook b/doc/kcontrol/bell/index.docbook new file mode 100644 index 000000000..2974c0707 --- /dev/null +++ b/doc/kcontrol/bell/index.docbook @@ -0,0 +1,74 @@ + + + +]> + +
+ + + +Pat +Dowler + + + +Matthias +Hoelzer + + + +Mike +McBride + + + + +2003-10-16 +3.2 + +KDE +KControl +Bell +Settings + + + + +System bell + +The system bell or beep is a feature of the X server, which +attempts to make good use of the available hardware. + +&kde; normally doesn't use the system bell; instead using its +own system notifications, which could include log entries, message +popups, or its own beep. You can configure these in the +System Notifications &kcontrol; module. + +It isn't always possible for the X server to actually make +a beep sound with exactly the parameters selected due to hardware +limitations. For example, on most PCs, volume control is not very good +so the X server seems to fake low volume with a reduced duration of +the sound. Thus, if the settings don't seem to do anything, this is +because the X server and/or the hardware don't support anything +better. + +Users are able to set the following parameters for the bell: + + + volume (percentage of maximum volume) + pitch (in Hz) + duration (in milliseconds) + + +You can use the test button to hear how +the current settings will sound. + +Section Authors +Pat Dowler, Matthias Hoelzer mhk@kde.org +Converted to KDE 2.0 by Mike McBride mpmcbride7@yahoo.com + + + + +
diff --git a/doc/kcontrol/cache/Makefile.am b/doc/kcontrol/cache/Makefile.am new file mode 100644 index 000000000..12a7570f3 --- /dev/null +++ b/doc/kcontrol/cache/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/cache diff --git a/doc/kcontrol/cache/index.docbook b/doc/kcontrol/cache/index.docbook new file mode 100644 index 000000000..7392d63fc --- /dev/null +++ b/doc/kcontrol/cache/index.docbook @@ -0,0 +1,69 @@ + + + +]> + +
+ + + + + + + + +2003-10-12 +3.2 + + +KDE +KControl +Konqueror +Cache + + + + +Cache + +This module allows you to control the size of the local cache +folder used by &konqueror;. Note that each user account on your +computer has a separate cache folder, and this folder is not +shared with other web browsers such as &Netscape;. + +Storing local copies of web pages that you have visited allows +&konqueror; to quickly load their contents on subsequent visits. It +will only be necessary to reload the contents from the original site +if they have changed since your last visit, or if you click the reload +button in &konqueror;. + +If you really don't want any of the web pages you visit to be +stored on your computer, you can disable &konqueror;'s disk cache by +clearing the checkbox labeled Use cache. + +You can set here how aggressively &konqueror; keeps the cache up +to date. Keep cache in sync means that &konqueror; +will hit the cache for all objects, downloading them if they are not +there, and then display the item from the cache. Use cache +whenever possible means that &konqueror; will try the cache, +and if an object is not there, it will directly download it for display. +Offline browsing mode means that &konqueror; will +try the cache, and if an object is not there, it will not attempt to +download it from the Internet. + +You can control the size of the cache by typing a number into the +text box labeled Disk cache size. This is the +average amount of space in kilobytes that the cache folder is allowed +to use. When the cache grows too large, &konqueror; will delete older +files to reduce the size of the cache folder. + +This is however, only an average, and during a browsing session +the cache could become substantially larger. + +You can use the Clear Cache button to empty +the cache at any time. + + +
diff --git a/doc/kcontrol/clock/Makefile.am b/doc/kcontrol/clock/Makefile.am new file mode 100644 index 000000000..a38969bfe --- /dev/null +++ b/doc/kcontrol/clock/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/clock diff --git a/doc/kcontrol/clock/index.docbook b/doc/kcontrol/clock/index.docbook new file mode 100644 index 000000000..88fd8c317 --- /dev/null +++ b/doc/kcontrol/clock/index.docbook @@ -0,0 +1,74 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2003-10-19 +3.2 + + +KDE +KControl +clock +date +time +set +configure + + + + + +Date & Time + +You can use this module to alter the system date and time, using a +convenient graphical interface. + +You must have system administrator (root) access to change the system date and +time. If you do not have this access level, this module will only show +you the current settings. + +When you first start, you are in display mode only. To modify +your settings, click on Administrator Mode. If +you are logged in as root, +you will go straight to the change dialog. If not, &kde; will ask for +a superuser password. + + +Modifying your settings + +You set the date using the left half of the module. Simply +choose your month (the drop down box at the top), year (the spin box +at the top), and the day of the month (simply click on the day in the +calendar). + +You set the time using the spin boxes at the bottom of the clock. +You can also directly enter your value. + +The time is represented in 24 hour format. If you want +the system time to be set to 8:00 PM, you need to set the hour spinbox +to 20 (8 + 12). If you want the system time set +to 8:00 AM, you should set the hour spinbox to +8. + +To set a new time zone, simply select one from +the drop down box at the bottom. + +When you have set the correct date and time, simply click +Apply to make the changes permanent. + + + + +
diff --git a/doc/kcontrol/colors/Makefile.am b/doc/kcontrol/colors/Makefile.am new file mode 100644 index 000000000..ec7030b15 --- /dev/null +++ b/doc/kcontrol/colors/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/colors diff --git a/doc/kcontrol/colors/index.docbook b/doc/kcontrol/colors/index.docbook new file mode 100644 index 000000000..c47912da9 --- /dev/null +++ b/doc/kcontrol/colors/index.docbook @@ -0,0 +1,132 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Mark.Donohoe; &Mark.Donohoe.mail; +&Martin.R.Jones; &Martin.R.Jones.mail; + + + +2003-09-22 +3.2 + + +KDE +KControl +color + + + + + +Colors + +Introduction + +The Color Selection module is comprised of 4 sections: + + +The color scheme +preview. +The current +Widget Color. + +The available Color +Schemes. +The contrast +slider. + + +A Widget is a commonly-used +programmer's term for referring to User Interface elements such as +buttons, menus, and scroll bars. You can think of them as the +fundamental pieces that are assembled to make your +application. + + +Preview + +This section of the dialog demonstrates how a color scheme applies +to a sample selection of widgets. It provides you with a +preview of your current color choices. + +A color scheme consists of a set of 18 colors. + +Each of the widgets is labeled to help you identify how your +changes will impact the color scheme. + + + + +<guilabel>Widget Color</guilabel> + +The currently selected member of the color scheme is shown in the +combo box. This widget color can be changed by clicking on the colored +box below the combo box. A color selection dialog will then appear, from +which you may select a new color. When you are happy with your color +selection, press OK in the color selection +dialog. The color will be updated in the Preview Area. + +You may select any member of the color scheme from the +color combination box. + + + + +<guilabel>Contrast</guilabel> Slider + +The Contrast slider allows you to change the +contrast between different shadings of the selected colors. + +The preview area instantly updates to show the effect of your +change. + + + + +<guilabel>Color Scheme</guilabel> + +Various color schemes are supplied with &kde;, and you are free to +define your own. + +The three major color components of each scheme are shown beside +the name in the list. To preview a scheme in the larger preview area, +click on its name in the list box. + +You can use the &kde;-supplied Color Schemes as a starting point +to devise your own Scheme. Click on the Save +Scheme... button to store the color scheme under a new name, +then modify it. + +When such a user-created Color Scheme is selected, changes to it +(as shown in the Preview) can be saved with the Save +Scheme... button; it can also be deleted with the +Remove Scheme button. + +The &kde;-supplied Schemes themselves cannot be changed or +deleted. + +You can use the Import Scheme... button to +add new entries to the list. This might be color schemes that you +have created on another computer and saved, or color schemes you have +downloaded from a website. + +You can choose if you want &kde; to apply the color scheme even +to non-&kde; applications by enabling the Apply colors to +non-KDE applications. Not all applications will allow +this, but most do. + + + + + + +
diff --git a/doc/kcontrol/cookies/Makefile.am b/doc/kcontrol/cookies/Makefile.am new file mode 100644 index 000000000..ed988eefc --- /dev/null +++ b/doc/kcontrol/cookies/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/cookies diff --git a/doc/kcontrol/cookies/index.docbook b/doc/kcontrol/cookies/index.docbook new file mode 100644 index 000000000..a1ea6fdd7 --- /dev/null +++ b/doc/kcontrol/cookies/index.docbook @@ -0,0 +1,211 @@ + + + +]> + +
+ + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + +2003-10-12 +3.2 + + +KDE +KControl +cookie + + + + + +Cookies + +Cookies are a mechanism used by web sites to store and retrieve +information using your browser. For example, a web site may allow you +to customize the content and layout of the pages you see, so that your +choices are persistent across different visits to that web site. + +The web site is able to remember your preferences by storing a +cookie on your computer. Then, on future visits, the web site retrieves +the information stored in the cookie to format the content of the site +according to your previously specified preferences. + +Thus, cookies play a very useful role in web browsing. +Unfortunately, web sites often store and retrieve information in cookies +without your explicit knowledge or consent. Some of this information may +be quite useful to the web site owners, for example, by allowing them to +collect summary statistics on the number of visits different areas of +the web sites get, or to customize banner advertising. + +The cookies module of the &kcontrol; allows you to set policies +for the use of cookies when you are browsing the web with the +&konqueror; web browser. + +Note that the policies that you set using this control +module will not apply to other web browsers such +as &Netscape;. + + + +Policy + +Using the Policy tab, you can configure the +&kde; applications that will handle cookies. You can do this by specifying a +general cookie policy as well as special cookie policies for certain +domains or hosts. + +The top of the policy tab has a checkbox labeled Enable +cookies. If you leave this unchecked, cookies will be +completely disabled. However, this may make browsing rather +inconvenient, especially as some web sites require the use of browsers +with cookies enabled. + +You will probably want to enable cookies and then set +specific policies on how you want them to be handled. + +The first group of options create settings that apply to all cookies. + + + +Only accept cookies from originating server + +Some pages try to set cookies from servers other than the one +you are seeing the HTML page from. For example, +they show you advertisements, and the advertisements are from another +computer, often one that belongs to a large advertising group. These +advertisements may try to set a cookie which would allow them to +track the pages you view across multiple web sites. +Enabling this option will mean only cookies that come from the +same web server as you are explicitly connecting to will be +accepted. + + + +Automatically accept session cookies + + +An increasingly common use for cookies is not to track your +movements across many visits to a web site, but to just follow what you +do during one single visit. Session cookies are saved as long as you +are looking at the site, and deleted when you leave it. + +Web sites can use this information for various things, most +commonly it is a convenience so that you do not have to keep logging in +to view pages. For example, on a webmail site, without some kind of +session ID, you would have to give your password +again for each email you want to read. There are other ways to +achieve this, but cookies are simple and very common. + +Enabling this option means that session cookies are always +accepted, even if you don't accept any other kind, and even if you +choose to reject cookies from a particular site, session cookies from +that site will be accepted. + + + + +Treat all cookies as session cookies + +If this option is enabled, all cookies are treated as session +cookies. That is, they are not kept when you leave the +web site. + +The definition of leave the web site is vague. +Some cookies may hang around for a little while after you are no +longer viewing any pages on a particular web site. This is +normal. + + + + + +The section for Default Policy sets some +further options that are mutually exclusive — you can choose only one +of these options as the default, but you are free to set a different +option for any specific web server. + + + +Ask for confirmation + +If this option is selected, you will be asked for confirmation +every time a cookie is stored or retrieved. You can selectively accept +or reject each cookie. The confirmation dialog will also allow you to +set a domain specific policy, if you do not want to confirm each +cookie for that domain. + + + +Accept all cookies + +If this option is selected, all cookies will be accepted without +asking for confirmation. + + + +Reject all cookies + +If this option is selected, all cookies will be rejected without +asking for confirmation. + + + + +In addition to the default policy for handling of cookies, which you can +set by selecting one of the three options described above, you can also set +policies for specific host domains using the controls in the Domain +Specific group. + +The Ask, Accept, or Reject policy can be applied to a specific +domain by clicking on the New... button, which +brings up a dialog. In this dialog, you can type the name of the +domain (with a leading dot), then select the policy you want to apply +to this domain. Note that entries may also get added while you are +browsing, if the default policy is to ask for confirmation, and you +choose a general policy for a specific host (for example, by selecting +Reject all cookies from this domain when asked to +confirm a cookie). + +You can also select a specific host domain from the list and click the +Change button to choose a different policy for that +domain than the one shown in the list. + +To delete a domain specific policy, choose a domain from the list, and +then click the Delete button. The default policy will +apply to domains which have been deleted from the list. + + + + +Management + +In the Management tab you can browse and selectively +delete cookies that have been set in the past. + +In the upper part of this dialog, you can see a list of domains displayed +as a tree. Click on the little + next to a domain to see all +cookies that have been set for this particular target domain. If you select one +of these cookies, you will notice that its contents will show up in the frame +Cookie Details below. + +By clicking the Delete button you can now delete the selected +cookie. Click Delete All to delete all cookies stored. + +Choose Reload List to reload the list +from your hard disk. You might want to do this if you have had the +module open and are testing web sites, or have made many changes in the +module itself. + + + + + +
diff --git a/doc/kcontrol/crypto/Makefile.am b/doc/kcontrol/crypto/Makefile.am new file mode 100644 index 000000000..3911417ea --- /dev/null +++ b/doc/kcontrol/crypto/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/crypto diff --git a/doc/kcontrol/crypto/index.docbook b/doc/kcontrol/crypto/index.docbook new file mode 100644 index 000000000..1d43131d1 --- /dev/null +++ b/doc/kcontrol/crypto/index.docbook @@ -0,0 +1,205 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2002-10-17 +3.1 + + +KDE +KControl +crypto +SSL +encryption + + + + + + +Encryption Configuration + + +Introduction +Many applications within &kde; are capable of exchanging information using +encrypted files and/or network transmissions. + + + +Use + +All encryption schemes are only as strong as their +weakest link. In general, unless you have some previous +training/knowledge, it is better to leave this module +unchanged. + +The options within this module can be divided into two +groups: + +Two options along the bottom of the module, Warn on +entering SSL Mode and Warn on leaving SSL +mode, allow you to determine if &kde; should inform you when +you enter or leave SSL encryption. + +The remainder of the options are about determining which +encryption methods to use, and which should not be used. Once you have +selected the appropriate encryption protocols, simply click +Apply to commit your changes. + +Only make changes to this module if specific information +about the strength or weakness of a particular encryption method is +given to you from a reliable source. + + + + + +The <guilabel>SSL</guilabel> Tab + +The first option is Enable TLS support if supported by +the server. TLS is Transport Layer +Security, and is the newest version of SSL. It +integrates better than SSL with other protocols, +and it has replaced SSL in protocols such as POP3 +and SMTP. + +Then next options are Enable SSL v2 and +Enable SSL v3. These are the second and third +revision of the SSL protocol, and it is normal to +enable both. + +There are several different Ciphers +available, and you can enable these separately in the lists labeled +SSL v2 Ciphers to Use and SSL v3 +Ciphers to Use. The actual protocol to use is negotiated +by the application and the server when the connection is +created. + +There are several Cipher Wizards to help +you choose a set that is suitable for your use. + + + +Most Compatible + +Select the settings found to be most compatible with the most +servers. + + + +US Ciphers Only + +Select only the US strong (128 bit or greater) +ciphers. + + + +Export Ciphers Only + +Select only the weak (56 bit or less) ciphers. + + + +Enable All + +Select all ciphers and methods. + + + + +Finally, there are some general SSL settings. + + + +Use EGD + +If selected, OpenSSL will be asked to +use the entropy gathering daemon (EGD) for +initializing the pseudo-random number generator. + + + + +Use entropy file + +If selected, OpenSSL will be asked to +use the given file as entropy for initializing the pseudo-random number +generator. + + + + +Warn on entering SSL mode + +If selected, you will be notified when entering an +SSL enabled site. + + + + +Warn on leaving SSL mode + +If selected, you will be notified when leaving an +SSL based site. + + + + +Warn on sending unencrypted data + +If selected, you will be notified before sending unencrypted +data via a web browser. + + + + + + +The <guilabel>OpenSSL</guilabel> Tab + +Here you can test if your OpenSSL +libraries have been detected correctly by &kde;, with the +Test button. + +If the test is unsuccessful, you can specify a path to the +libraries in the field labelled Path to OpenSSL Shared +Libraries. + + + + +The <guilabel>Your Certificates</guilabel> Tab + +The list shows which certificates of yours &kde; knows about. +You can easily manage them from here. + + + + +The <guilabel>Authentication</guilabel> Tab + +Not yet documented + + + +The <guilabel>Peer SSL Certificates</guilabel> Tab + +The list box shows which site and personal certificates &kde; +knows about. You can easily manage them from here. + + + + + +
diff --git a/doc/kcontrol/desktop/Makefile.am b/doc/kcontrol/desktop/Makefile.am new file mode 100644 index 000000000..545365a4a --- /dev/null +++ b/doc/kcontrol/desktop/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/desktop diff --git a/doc/kcontrol/desktop/index.docbook b/doc/kcontrol/desktop/index.docbook new file mode 100644 index 000000000..070ae0d72 --- /dev/null +++ b/doc/kcontrol/desktop/index.docbook @@ -0,0 +1,84 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + +2005-02-20 +3.4 + + +KDE +KControl +desktop + + + + + +Desktop + + +<guilabel>Appearance Tab</guilabel> + +Here you can configure how icons on your desktop appear. + + + +Standard font: +This option can be used to change the typeface used on the +desktop. Simply select your typeface from the dropdown box. + + +Font size: +You can change the relative size of the text on the Desktop. + + + +Normal text color: +This option lets you select the color of normal (or +unhighlighted) text. + +Text background color: +This option lets you select the background color of +normal text. If left unchecked, the text has a transparent +background. If selected, you can choose the color by pressing the button. + + + +Underline filenames: +Determines if file names are underlined on the +Desktop. + + + + + +<guilabel>Multiple Desktops</guilabel> + +&kde; offers you the possibility to have several virtual +desktops. In this tab you can configure the number of desktops as well +as their names. Just use the slider to adjust the number of +desktops. You can assign names to the desktops by entering text into the +text fields below. + +If you enable Mouse wheel over desktop switches +desktop then scrolling the wheel over an empty space on the +desktop will change the the next virtual desktop numerically, in the +direction you scrolled (either up or down). + + + + + +
diff --git a/doc/kcontrol/desktopbehavior/Makefile.am b/doc/kcontrol/desktopbehavior/Makefile.am new file mode 100644 index 000000000..9ff6d953a --- /dev/null +++ b/doc/kcontrol/desktopbehavior/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/desktopbehavior diff --git a/doc/kcontrol/desktopbehavior/index.docbook b/doc/kcontrol/desktopbehavior/index.docbook new file mode 100644 index 000000000..9011f265d --- /dev/null +++ b/doc/kcontrol/desktopbehavior/index.docbook @@ -0,0 +1,198 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + +2005-02-20 +3.4 + + +KDE +KControl +desktop + + + + + +Desktop Behavior + + +<guilabel>Desktop</guilabel> Tab + + + +Show icons on desktop + +Uncheck this option if you do not want to have icons on the +desktop. Without icons the desktop may be somewhat faster, but you +will no longer be able to drag files to the desktop. +This will not remove any files already stored on the desktop, +they will instead be hidden. + +If this is enabled, you may also enable the ability to Allow programs in desktop window. + +Enabling this option allows you to set a program as your desktop +background, for example xearth, or &kworldclock; + + + + + +Show tooltips + +Check this option if you would like to see tooltips for icons on +the desktop as you hover the mouse over them. These tooltips display +information about the file represented by the icon. Depending on the +type of file, the information can range from simple file size and +creation dates for unfamiliar file types, to complete meta information +such as the content of tags for music files. + + + + +Menu Bar at Top of Screen: + +This option determines whether there is a menu across +the top of the &kde; Desktop similar to the style of &MacOS;. + +The default is None. If you select +Desktop menu bar one static menu is shown at the +top of the screen, displaying the desktop menu. Finally there is +Current application's menu bar (Mac OS-style). +If this option is selected, applications won't have their menu bar +attached to their own window anymore. Instead, there is one menu bar +at the top of the screen which shows the menus of the currently active +application. You might recognize this behavior from &MacOS;. + + + + + + +Mouse button actions: + + +The mouse button section allows you to determine what happens when +you click one of the three mouse buttons on the Desktop (where there is +no window). + +Not all mice have three buttons. Two button mice can +usually activate the Middle button by +pressing both the Left and +Right mouse buttons at the same +time. + +For each of the three mouse buttons, you can select: + + + +No Action +When you use this mouse button, nothing +happens. + + + +Window list menu +This brings up a submenu with all the virtual desktops. +Under each virtual desktop, you can select any window currently located +on that desktop. Once selected, &kde; will switch to that desktop, and +place the focus on that window. + + + +Desktop Menu. +This brings up a submenu with commands specific to +&kde;. You can create icons, edit bookmarks, cut and paste, +run commands, configure &kde;, arrange icons, lock the session and log +out of &kde;. The exact content of the menu varies depending on the +current status of &kde;. + + + +Application Menu +This brings up the Application Menus +(also know as the K Menus), so you can start a new +application. + + + +Custom Menu 1 +Custom Menu 2 + +You may also configure up to two custom menus. If you choose either of these, the Edit... becomes available, allowing you to edit the contents of the custom menus. + + + + + + + + + + + + +<guilabel>File Icons</guilabel> + +First are two options regarding the placement of icons: + + + +Automatically line up icons +If this option is enabled, &kde; will align icons on a +grid on the desktop. If it is not enabled, you may drop icons +anywhere, and they will not be aligned for you. + + +Show hidden files +If this option is enabled, then all hidden files will +appear on the desktop. Generally this only clutters your desktop area, +but if you are often working with hidden files or folders, this can +be useful. +Be very careful when deleting or modifying hidden files. +Many of these files are configuration files and are essential for the +correct operation of your computer. + + + + +The &kde; desktop has a preview feature for many file types, +including HTML files, images, &PostScript; and +PDF, sound, web archives (if you have the +appropriate &konqueror; plugin installed) and text files. + +if you enable previews for one of these, files of that particular +file type will not be represented by standard icons on the desktop, but +will instead be shown as miniature previews. On slow computers, the +previews can take some time to show up, so you might not want to enable +this feature. + + + + +<guilabel>Device Icons</guilabel> + +On some operating systems (&Linux; and FreeBSD, so far) &kde; can +dynamically display icons for each mountable +device you have available. This could be &CD-ROM; drives, floppy disk +drives, or network shares. + +If you enable this, you can choose what kind, if any, of these +devices you would like quick access icons to be displayed for. + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/ebrowsing/Makefile.am b/doc/kcontrol/ebrowsing/Makefile.am new file mode 100644 index 000000000..4d7741915 --- /dev/null +++ b/doc/kcontrol/ebrowsing/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/ebrowsing diff --git a/doc/kcontrol/ebrowsing/index.docbook b/doc/kcontrol/ebrowsing/index.docbook new file mode 100644 index 000000000..da9167f6e --- /dev/null +++ b/doc/kcontrol/ebrowsing/index.docbook @@ -0,0 +1,156 @@ + + + +]> + +
+ + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; +&Yves.Arrouye; &Yves.Arrouye.mail; + + + +2002-10-16 +3.1 + + +KDE +KControl +enhanced browsing +web shortcuts +browsing + + + + + +Web Shortcuts + + + +Introduction + +&konqueror; offers some features to enhance your browsing +experience. One such feature is Web Shortcuts. + +You may already have noticed that &kde; is very Internet friendly. +For example, you can click on the Run menu +item or type the keyboard shortcut assigned to that command (AltF2, +unless you have changed it) and type in a URI. +Uniform Resource Identifier. A standardized way of +referring to a resource such as a file on your computer, a World Wide +Web address, an email address, +etc.... + +Web shortcuts, on the other hand, let you come up with new pseudo +URL schemes, or shortcuts, that basically let you +parameterize commonly used +URIs. For example, if you like the Google search +engine, you can configure KDE so that a pseudo URL +scheme like gg will trigger a search on +Google. This way, typing gg:my +query will search for my +query on Google. + +One can see why we call these pseudo URL +schemes. They are used like a URL scheme, but the +input is not properly URL encoded, so one will type +google:kde apps and not +google:kde+apps. + +You can use web +shortcuts wherever you would normally use +URIs. Shortcuts for several search engines should +already be configured on your system, but you can add new keywords, and +change or delete existing ones in the enhanced browsing control +module. + + + + + +Use + +There is a single tab in this control module. The title of the tab +is Keywords. This tab features two main boxes, one +for Internet Keywords and one for web shortcuts. + + + +Web Shortcuts + +The descriptive names of defined web shortcuts are shown in a +listbox. As with other lists in &kde;, you can click on a column +heading to toggle the sort order between ascending and +descending, and you can resize the columns. + +If you double-click on a specific entry in the list of defined +search providers, the details for that entry are shown in a popup +dialog. In addition to the descriptive name for the item, you can +also see the URI which is used, as well as the +associated shortcuts which you can type anywhere in &kde; where +URIs are expected. A given search provider can have +multiple shortcuts, each separated by a comma. + + The text boxes are used not only for displaying information +about an item in the list of web shortcuts, but also for modifying or +adding new items. + +You can change the contents of either the Search +URI or the URI Shortcuts text box. +Click OK to save your changes or +Cancel to exit the dialog with no +changes. + +If you examine the contents of the Search +URI text box, you will find that most, if not all of the +entries have a in them. This sequence of two +characters acts as a parameter, which is to say that they are replaced +by whatever you happen to type after the colon character that is +between a shortcut and its parameter. Let's consider some examples to +clarify this idea. + +Suppose that the URI is +http://www.google.com/search?q=\{@}, and +gg is a shortcut to this +URI. Then, typing +gg:alpha is +equivalent to +http://www.google.com/search?q=alpha. +You could type anything after the : character; +whatever you have typed simply replaces the +characters, after being converted to the appropriate character set for +the search provider and then properly +URL-encoded. Only the part of +the search URI is touched, the rest of it is +supposed to be properly URL-encoded already and is +left as is. + +You can also have shortcuts without parameters. Suppose the +URI was +file:/home/me/mydocs/kofficefiles/kword and the +shortcut was mykword. Then, typing +mykword: is the same as typing the complete +URI. Note that there is nothing after the colon +when typing the shortcut, but the colon is still required in order for +the shortcut to be recognized as such. + +By now, you will have understood that even though these shortcuts +are called web shortcuts, they really are shortcuts to parameterized +URIs, which can point not only to web sites like +search engines but also to anything else that can be pointed to by a +URI. Web shortcuts are a very powerful feature of +navigation in &kde;. + + + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/email/Makefile.am b/doc/kcontrol/email/Makefile.am new file mode 100644 index 000000000..137c9a103 --- /dev/null +++ b/doc/kcontrol/email/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/email diff --git a/doc/kcontrol/email/index.docbook b/doc/kcontrol/email/index.docbook new file mode 100644 index 000000000..b34e44b13 --- /dev/null +++ b/doc/kcontrol/email/index.docbook @@ -0,0 +1,103 @@ + + + +]> + +
+ + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; +&Jost.Schenck; &Jost.Schenck.mail; +&Mike.McBride; &Mike.McBride.mail; + + + +2002-09-01 +3.1.00 + + +KDE +KControl +email +e-mail + + + + +Email + + + +Introduction + +The email module of the &kcontrol; allows you to enter and save some +basic email information. This information is used when performing functions +related to email within &kde;, for example, when sending bug reports from the +&kde; crash handler application. + +Programs such as &kmail;, which are used for reading and sending +email, may offer many more options for customizing the way in which +email is handled. These options depend upon the specific program being +used. &kmail;, for instance, offers its own configuration +facilities. + +Some of the information needed for configuring email should have +been provided by your internet service provider +(ISP). If you are connected to a local network, then +the system administrator of your network should be able to help +you. + + + + +Use + +&kde; automatically establishes some of the information for this control module +using the +login information on the system. You will need to enter the remaining information. +Looking at the page from top to +bottom, the options are: + + + +Full name +Type your full name as you would like it to appear in the email +messages that you send. + + + +Organization +If you work for a company or +organization, you can enter its name in this text box. + + + +Email address +To be able to use email, you must enter your email +address here. + + + +Reply-to address +If replies to your email messages should be sent to a different +address, you can enter that address in this text box. + + + + + + +
+ + + diff --git a/doc/kcontrol/energy/Makefile.am b/doc/kcontrol/energy/Makefile.am new file mode 100644 index 000000000..b45cc2539 --- /dev/null +++ b/doc/kcontrol/energy/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/energy diff --git a/doc/kcontrol/energy/index.docbook b/doc/kcontrol/energy/index.docbook new file mode 100644 index 000000000..94d7a2745 --- /dev/null +++ b/doc/kcontrol/energy/index.docbook @@ -0,0 +1,110 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +energy + + + + +Energy + + +Introduction + +This module is useful for any computer having a monitor labeled +Energy Star Compliant. (Energy Star Compliant equipment is equipment +that can be configured to automatically enter a power saving mode when +appropriate, without human intervention.) + +Energy Star Compliance can be applied to nearly any +electrical device. This module, however, does not spin down hard +drives, does not shutdown printers, &etc; These settings only affect +the behavior of your monitor. + +For information on shutting down components on a laptop, do not +use this module. Instead, install kdeutils, and refer to the module +entitled Laptop +Power Control Center, for details. + +In the case of computer monitors, the computer can control the +monitor, switching it between four states: On, Standby, Suspend, and +Off. + +The following list of states is a generalization, and you +may find that your monitor will differ from the descriptions +below. + +ON is the normal operation of your monitor while you are using +it. + +STANDBY is usually a minor power saving level. +This setting usually involves blanking the screen, and not firing the +electron gun, but keeping the electron gun energized +and ready to go. When you need to use the monitor again, the monitor +will come back on very quickly. + +SUSPEND is a very low power mode alternative. +With most monitors the screen is blanked, the electron +gun is shut down and the magnets that control the electron gun are +powered down. While the power saving is substantial, to reactivate +the monitor may take up to 10-15 seconds. The computer should always +be able to return the monitor to On or Standby while in suspend +mode. + +OFF, usually means just that. The computer +monitor is turned off. This usually means that the computer will not +be able to turn the monitor back on by itself. Obviously, this keeps +power consumption to a bare minimum (zero). + + + +Use + +Using this module is very simple: + +If your monitor is Energy Star Compliant, then you should put a +mark in the check box labeled Enable Display Energy +Saving. This will activate the energy saving +commands. + +The next three slider bars, tell the computer how many minutes of +inactivity before automatically switching to a new state. These numbers +can be adjusted with either the sliders, or the spin boxes. + +These times are not additive, but all start counting at +zero. + +As an example: + +If you set the Standby Mode to 10 minutes, the Suspend mode to 20 +minutes, and the Power off at 30 minutes, and you stop using your +computer at 9:00, then the monitor will: Enter Standby mode +at 9:10, enter Suspend mode at 9:20, and shut the power off at +9:30. + +When you are happy with the settings, click +OK. + + + + + +
diff --git a/doc/kcontrol/filemanager/Makefile.am b/doc/kcontrol/filemanager/Makefile.am new file mode 100644 index 000000000..8e045365e --- /dev/null +++ b/doc/kcontrol/filemanager/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/filemanager diff --git a/doc/kcontrol/filemanager/index.docbook b/doc/kcontrol/filemanager/index.docbook new file mode 100644 index 000000000..be620a8cf --- /dev/null +++ b/doc/kcontrol/filemanager/index.docbook @@ -0,0 +1,297 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2002-10-16 +3.1 + + +KDE +KControl +file manager + + + +File Manager + +In this module, you can configure various aspects of +&konqueror;'s file manager functionality. + +&konqueror;'s web browser functionality has its own configuration +modules. + + +Use + + The configuration options for the file manager are +organized under tabs as follows: + + + +Appearance +This tab contains options for customizing the appearance of +&konqueror; windows, such as the default font +text color. + + + +Behavior +This tab contains a couple of &konqueror; +global options. + + + +Previews + +On this tab, you can customize when &konqueror; should show +previews. + + + + + +Appearance + +The following settings determine how text and colors are displayed in +&konqueror; File Manager mode windows. + + + +Standard font: + +This is the font used to display text such as file names in +&konqueror; windows. + + + + +Font size: + + +Lets you control the size of text, while the Standard +Font setting determines the font face used. + + + + +Normal text color: + +Determines the standard text color. + + + + +Height for icon text: + +The maximum number of lines that can be used to draw icon text. Long lines are truncated at the end of the last line. + You can still see word-wrapped filenames by pausing the mouse pointer over the icon. + + + + +Width for icon text: + +The maximum width for the icon text when &konqueror; is in multi-column view mode. + + + + +Underline filenames: + +When Underline filenames is checked, + filenames will be underlined so that they look like links on a web + page. + + + + +Display file sizes in bytes: + +The final check box on this page determines how &konqueror; +displays file sizes, when you are in one of the file manager modes +that normally shows this information. If you check the +Display file sizes in bytes box then file sizes +are always shown in bytes. If you leave it unchecked then file sizes +are shown in bytes, kilobytes or megabytes, depending on their +size. + + + + + + +Behavior + + +<guilabel>Misc Options</guilabel> + +Open folders in separate windows + If this option is checked, a new +&konqueror; window will be created when you open a +folder, rather than simply showing that folder's contents in the + current +window. + + + +Show network operations in a single window + +If unchecked, and you download a +file, a dialog box will appear that shows the status of the +download. + + + Download Dialog Box + + + Download Dialog Box + + Individual Download Dialog Box + + + + +If you start a new transfer, another dialog box will +appear. (&Netscape; users will be familiar with +this behavior) + +If checked, all transfer status windows will be grouped +together under a single dialog box. + + Download Dialog Box + + + Download Dialog Box + + Collected Download Dialog Box + + + + +If you choose to use the Collected download dialog box, you can +delete transfers by clicking once on the transfer you want to cancel, +then clicking the Delete Button on the +left. + + + + + +Show file tips + + Here you can control if, when moving the mouse over a file, you +want to see a small popup window with additional information about +that file. + + + + +Show previews in file tips + +Here you can control if the file tip should show a +thumbnail preview of the file. + + + + + +Home URL +This is the &URL; (⪚ a +folder or a web page) where &konqueror; will jump to +when the Home button is pressed.The +default is the users home folder, indicated with a +~. + + + +You can set a path that is your Home URL by +typing into the text field, or using the browse +icon. The default is ~ which is a standard +shortcut for your $HOME folder. When you choose the +home icon on your panel, in a file open or save +dialog, or from within &konqueror; in file manager mode, this is the +folder you will be shown. + +The Ask confirmation for setting tells +&konqueror; what to do when you choose to Delete, +Trash, or Shred a file in a &konqueror; +window. If any box is checked, &konqueror; asks for confirmation before +performing the corresponding action. + + + + +Previews + +&konqueror; has a +preview feature for many file types, including HTML +files, images, &PostScript; and PDF, sound, web +archives (if you have the appropriate &konqueror; plugin installed) +and text files. + +If you enable previews for one of these, files of that particular +file type will not be represented by standard icons in the filemanager, but +will instead be shown as miniature previews. On slow computers, the +previews can take some time to show up, so you might not want to enable +this feature. + +In this module you can specify which protocols +you wish the previews to be available for. Creating the previews +requires that &konqueror; download at least part of the file, in order +to create the preview. &konqueror;, like the rest of &kde; is +entirely network transparent, and will treat a remote &FTP; folder +just as if it was on your local hard drive. This can result in a +delay, especially if you are viewing, for example, a folder full of +images over a slow network connection. + +For each protocol, you can independently enable or disable +previews. For example, you might enable previews for +NFS mounted drives if you have a fast network, but +disable them for &FTP; because your Internet connection is via a +modem. + +You can further refine the maximum size file that &konqueror; +will attempt to show a preview for. The default is 1 MB. In other +words, by default, if a file is 900 kB in size, and the protocol you +are viewing the folder with is enabled, then &konqueror; will +create a preview icon for it. If the file is 1.1 MB in size, +&konqueror; will not make a preview, even if the protocol is +enabled. + +You can turn on and off previews on the fly from +within &konqueror;, using the View menu. For +example, if you normally want to see image previews on every protocol, +but find a particular server is very slow to send you the data, you +might turn it off for the present, and turn it on again later. + +You may also like to enable the checkbox Increase size +of previews relative to icons, in order to see more +information in the thumbnails. + +Many image files already contain a thumbnail. You can enable +the Use thumbnails embedded in files to make use +of these. This will save time waiting for thumbnails to be created +when viewing a folder full of images you have not previously seen in +&konqueror;. + + + + + + + +
diff --git a/doc/kcontrol/filemanager/kfileman1.png b/doc/kcontrol/filemanager/kfileman1.png new file mode 100644 index 000000000..0505d604d Binary files /dev/null and b/doc/kcontrol/filemanager/kfileman1.png differ diff --git a/doc/kcontrol/filemanager/kfileman2.png b/doc/kcontrol/filemanager/kfileman2.png new file mode 100644 index 000000000..6c8d17d75 Binary files /dev/null and b/doc/kcontrol/filemanager/kfileman2.png differ diff --git a/doc/kcontrol/filetypes/Makefile.am b/doc/kcontrol/filetypes/Makefile.am new file mode 100644 index 000000000..ae43c3018 --- /dev/null +++ b/doc/kcontrol/filetypes/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/filetypes diff --git a/doc/kcontrol/filetypes/index.docbook b/doc/kcontrol/filetypes/index.docbook new file mode 100644 index 000000000..a838156db --- /dev/null +++ b/doc/kcontrol/filetypes/index.docbook @@ -0,0 +1,338 @@ + + + +]> + +
+ + +File Associations + +&Mike.McBride; &Mike.McBride.mail; + + + +2003-10-13 +3.2 + + +KDE +KControl +files association +association + + + +File Associations + + +Introduction + +One of the most convenient aspects of &kde;, is its ability to +automatically match a data file, with its application. As an example, +when you click on your favorite &kword; document in &konqueror;, &kde; +automatically starts &kword;, and automatically loads that file into +&kword; so you can begin working on it. + +In the example above, the &kword; Data file is +associated with &kword; (the application). These +file associations are crucial to the functioning of &kde;. + +When &kde; is installed, it automatically creates hundreds of file +associations to many of the most common data types. These initial +associations are based on the most commonly included software, and the +most common user preferences. + +Unfortunately, &kde; can not: + + +predict every possible combination of software and data files +prepare for file formats not yet invented +or predict everyone's favorite application for certain file formats + + +You can change your current file associations or add new file +associations using this module. + +Each file association is recorded as a mime type. +&MIME; stands for Multipurpose Internet Mail +Extensions. It allows a computer to determine the type of file, +without opening and analyzing the format of each and every file. + + + + +How to use this module + +The file associations are organized into several categories, and +at a minimum you will have: + + +Application +Audio +Image +Inode +Message +Multipart +Print +Text +Video + + +All of the file associations are sorted into one of these +categories. + +There is also an overview category All, which +displays all the file types in one list, without categorizing +them. + +There is no functional difference between any of the +categories. These categories are designed to help organize your file +associations, but they do not alter the associations in any way. + + +The categories are listed in the box labeled Known +Types. + +You can explore each of these categories, and see the file +associations contained within each one, by simply double-clicking on the +category name. You will be presented with a list of the associated +mime-types under that category. + +You can also search for a particular &MIME; type by using the +search box. The search box is labeled Find filename +pattern and is located above the category list. + +Simply type the first letter of the &MIME; type you are interested +in. The categories are automatically expanded, and only the mime-types +that include that letter are displayed. + +You can then enter a second character and the mime-types will be +further limited to mime types containing those two +characters. + + +Adding a new mime type + +If you want to add a new &MIME; type to your file associations, +you can click on the Add... button. A small +dialog box will appear. You select the category from the drop down +box, and type the &MIME; name in the blank labeled Type +name. Click OK to add the new mime +type, or click Cancel to not add any new +mime-types. + + + + +Removing a mime type + +If you want to remove a &MIME; type, simply select the &MIME; +type you want to delete by clicking once with the mouse on the &MIME; +type name. Then click the button labeled +Remove. The &MIME; type will be deleted +immediately. + + + + +Editing a mime types properties + +Before you can edit a &MIME; types property, you must first +specify which &MIME; type. Simply browse through the categories until +you find the &MIME; type you want to edit, then click once on it with +the mouse. + +As soon as you have selected the &MIME; type, the current values of +the &MIME; type will appear in the module window. + +You will notice the current values are split into two tabs: +General and Embedding + + + +General + +There are 4 properties for each &MIME; type in this tab: + + +Mime Type Icon is the icon that +will be visible when using &konqueror; as a file +manager. +Filename Patterns is a search +pattern which &kde; will use to determine the &MIME; type. +Description is a short description +of the file type. This is for your benefit only. +Application Preference Order +determines which applications will be associated with the specified +&MIME; type. + + + + + +Embedding Tab + +The Embedding tab allows you to determine if an file will be +viewed within a &konqueror; window, or by starting the +application. + + + + + + + +Changing the Icon + +To change the icon, simply click on the Icon button. A dialog box +will appear, which will show you all available icons. Simply click once +with the mouse on the icon of your choice, and click +OK. + + + + +Editing the mime-type patterns + +The box labeled Filename Patterns, determines +what files will be included within this mime-type. + +Usually, files are selected based on their suffix. (Examples: +Files that end with .wav are sound +files, using the WAV format and files that end in .c are program files written in C). + +You should enter your filename mask in this combo box. + +The asterisk (*) is a wildcard character that +will be used with nearly every mime type mask. A complete discussion +of wildcards is beyond the scope of this manual, but it is important +to understand that the asterisk (in this context), +matches any number of characters. As an example: +*.pdf will match +Datafile.pdf, Graphics.pdf +and User.pdf, but not PDF, +Datafile.PDF, or +.pdf. + +It is very beneficial to have multiple masks. One for lower +case, one for upper case, &etc; This will help ensure that &kde; can +determine the file type more accurately. + + + + +Editing a mime types description. + +You can type a short description of the &MIME; type in the text +box labeled Description. This label is to help +you, it does not affect the function of the &MIME; type. + + + + +Editing the application associations + +There are four buttons (Move Up, +Move Down, Add and +Remove) and a combo box (which lists the +applications) which are used to configure the applications. + +The combo box lists all of the applications associated with a +specific &MIME; type. The list is in a specific order. The top +application is the first application tried. The next application down +the list is the second, etc. + +What do you mean there is more than one application per +&MIME; type? Why is this necessary? + +We started out by saying that &kde; comes preconfigured with +hundreds of file associations. The reality is, each system that &kde; +is installed on has a different selection of applications. By +allowing multiple associations per &MIME; type, &kde; can continue to +operate when a certain application is not installed on the +system. + +As an example: +For the &MIME; type pdf, there are two +applications associated with this file type. The first program is +called PS Viewer. If your system does not +have PS Viewer installed, then &kde; +automatically starts the second application Adobe Acrobat +Reader. As you can see, this will help keep &kde; running +strong as you add and subtract applications. + +We have established that the order is important. You can change +the order of the applications by clicking once with the mouse on the +application you want to move, and then clicking either Move +Up or Move Down. This will shift +the currently selected application up or down the list of +applications. + +You can add new applications to the list by clicking the button +labeled Add. A dialog box will appear. Using the +dialog box, you can select the application you want to use for this mime +type. Click OK when you are done, and the +application will be added to the current list. + +You can remove an application (thereby ensuring that the +application will never run with this &MIME; type by clicking once on the +name of the application, and clicking the Remove +button. + +It is a good idea to use the Move Up +and Move Down buttons to adjust the unwanted +application to a lower position in the list, rather than deleting the +application from the list entirely. Once you have deleted an +application, if your preferred application should become compromised, +there will not be an application to view the data document. + + + + +Embedding +By clicking on the Embedding tab, you are +presented with three radio buttons in the Left click +action group. These determine how &konqueror; views the selected +&MIME; type: + + +Show file in embedded viewer +If this is selected, the file will be shown within the &konqueror; window. +Show file in separate viewer +This will cause a separate window to be created when showing this mime-type. +Use group settings. +This will cause the mime-type to use the settings for the mime-type group. +(if you are editing an audio mime type, then the settings for the audio group are used). + + +Below this is a listbox labeled Services Preference +Order. + +When you are in &konqueror;, you can +right mouse click, and a menu will with an +entry labeled Preview with... will appear. This box +lists the applications that will appear, in the order they will +appear, under this menu. + +You can use the Move Up and +Move Down buttons to change the order. + + + + +Making changes permanent + +When you are done making any changes to mime types, you can click +Apply to make your changes permanent, but keep +you in this module. + + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/fonts/Makefile.am b/doc/kcontrol/fonts/Makefile.am new file mode 100644 index 000000000..b79d06618 --- /dev/null +++ b/doc/kcontrol/fonts/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/fonts diff --git a/doc/kcontrol/fonts/index.docbook b/doc/kcontrol/fonts/index.docbook new file mode 100644 index 000000000..cfe34bab7 --- /dev/null +++ b/doc/kcontrol/fonts/index.docbook @@ -0,0 +1,121 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2003-09-22 +3.2 + + +KDE +KControl +fonts + + + + + +Fonts + +This module is designed to allow you to easily select different +fonts for different parts of the &kde; Desktop. + +The panel consists of different font groups to give you a lot of +flexibility in configuring your fonts: + + +General: Used everywhere the other font +groups don't apply + +Fixed width: Anywhere a +non-proportional font is specified + + + +Toolbar: Font used in &kde; application +toolbars + +Menu: Font used in &kde; application +menus + +Window title: Font used in the window +title + +Taskbar: Font used in the taskbar +panel applet + +Desktop: Font used on the desktop +to label icons + + + +Each font has a corresponding Choose... +button. By clicking on this button, a dialog box appears. You can +use this dialog box to choose a new font, font style, size and +character set. Then press OK. + +An example of the font you have chosen will be displayed in the space +between the font group name and the Choose... +button. + +When you are done, simply click OK, and +all necessary components of &kde; will be restarted so your changes +can take affect immediately. + +The Adjust All Fonts... button allows you to +quickly set properties for all the fonts selected +above. A font selection dialog similar to the standard one will +appear, but you will notice checkboxes that allow you to change the +Font, Font style or +Size independently of each other. You can +choose any one, two, or three of these options, and they will be +applied to all the font groups. + +For example, if you have selected several different font faces +above, and realize they are all a size too big (this often happens +when you change screen resolution, for instance), you can apply a new +font size to all the fonts, without affecting your customized font +faces and styles. + + +Anti-alias text + +To use anti-aliasing, simply place a mark in the checkbox labeled +Use anti-aliasing for fonts. + +Placing a mark in the checkbox will allow you to specify which range of +fonts will not be anti-aliased. This range is specified +with the two combo boxes on the same line. + +You can also choose the method that &kde; uses to create an anti-alias +look to your fonts, and how strongly it should be applied. If you are not +familiar with the individual methods, you should leave this option +alone. + + + + +The ability to use anti-aliased fonts and icons requires that you have +support in both X and the &Qt; toolkit, that you have suitable fonts +installed, and that you are using the built-in font serving capabilities +of the X server. If you still are having problems, please contact the +appropriate &kde; mailing list, or check the +FAQ. + + + + + +
diff --git a/doc/kcontrol/helpindex/Makefile.am b/doc/kcontrol/helpindex/Makefile.am new file mode 100644 index 000000000..0529b36f5 --- /dev/null +++ b/doc/kcontrol/helpindex/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/helpindex.html diff --git a/doc/kcontrol/helpindex/index.docbook b/doc/kcontrol/helpindex/index.docbook new file mode 100644 index 000000000..ba7acdc80 --- /dev/null +++ b/doc/kcontrol/helpindex/index.docbook @@ -0,0 +1,144 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + + +2002-10-17 +3.1 + + +KDE +KControl +Help Index +Index + + + + + +Help Index + +At the time of writing, for most installations of &kde; the entire search engine function in &khelpcenter; is disabled, and settings made in this &kcontrol; module will have no effect. We hope to have it back in a future release. + +&kde; comes with a lot of documentation for applications and +components. While it is possible to just browse the manuals until you +find that piece of information you're looking for, this may be a very +time-consuming task. To make this easier for you, &kde; offers +fulltext search using a program called +ht://dig. It works quite similar to search +engines on the web, in fact some search engines you know might even use +it. Just click on the Search tab in the +&khelpcenter;, enter the word you are looking for, click +Search and enjoy! + +However, to make use of this feature, +ht://dig has to be installed on your system +and &kde; has to be configured to make use of it. This control module +tries to help you doing the latter. If you haven't installed +ht://dig and it wasn't shipped with your +operating system you have to get ht://dig yourself. Have a look at +the ht://dig homepage on how +to download and install it. + +When you first start, you are in display mode only. To modify +your settings, click on Administrator Mode. If +you are logged in as root, +you will go straight to the change dialog. If not, &kde; will ask for +a superuser password. + + +Use + +There are two important things to tell &kde; so it can make use of the +fulltext search engine: + + +where to find the ht://dig programs +KDE uses for fulltext search +where to search + + + + +The <application>ht://dig</application> Programs + + There are three programs &kde; needs that come with +ht://dig: htdig, +htsearch and htmerge. For each program you +have to provide the full path including the program name, for example: /usr/bin/htdig. + +Where exactly these programs are installed depends on your operating +system or your distribution. However, there are some good guesses you might want +to try: + + + +htdig and htmerge are +often found in /usr/bin/ or in something +like /usr/local/www/htdig/bin/. + +the htsearch command is often found in a sub +folder called cgi-bin, for example +/usr/local/httpd/cgi-bin/. + + + + +To find out where for example htdig is installed +you can always type whereis htdig on the +console. whereis will look for the specified command in the +standard execution path folders. However, folders like cgi-bin are often not in the standard execution +path. + + + + +Scope and Search Paths + +In this section you can choose which help resources should be indexed, +&ie; made available to the search engine. + +In the Scope frame you can select some +typical resources you want to be indexed, &ie; the &kde; help files, +and the information offered by the man and +info commands. Note that some of those may still be +disabled, which means that support for them has not been added +yet. + +Maybe you have additional files you want to access using the +&khelpcenter; fulltext search feature. For example, you might have an +HTML reference installed in +/home/jdoe/docs/selfhtml. By adding this path to +the list of additional search paths you make this documentation +available to &khelpcenter;'s fulltext search, too. Just click on the +Add button and a file dialog will ask you for +an additional search folder. Select +/home/jdoe/docs/selfhtml and click +OK. To remove an additional search path, just +select it and click Delete. + +Your changes to the scope and additional search paths +will not take effect if you don't click on the Generate +index button. + + + + + +
+ diff --git a/doc/kcontrol/icons/Makefile.am b/doc/kcontrol/icons/Makefile.am new file mode 100644 index 000000000..9de711f69 --- /dev/null +++ b/doc/kcontrol/icons/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/icons diff --git a/doc/kcontrol/icons/index.docbook b/doc/kcontrol/icons/index.docbook new file mode 100644 index 000000000..199a35275 --- /dev/null +++ b/doc/kcontrol/icons/index.docbook @@ -0,0 +1,233 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + +2003-09-22 +3.2 + + +KDE +KControl +icon + + + +Icons + + +Introduction + +&kde; comes with a full set of icons in several sizes. These icons +are being used all over &kde;: the desktop, the panel, the &konqueror; file +manager, in every toolbar of every &kde; application, etc. The icons +control module offers you very flexible ways of customizing the way &kde; +handles icons. You can: + + +install and choose icon themes +choose different icon sizes +assign effects to icons (for example make them +semi-transparent or colorize them) +configure these settings for each of the different places +icons will be used in: for example the desktop, toolbars &etc; + + + +Please note that some of these settings may depend on +your selected icon theme. &kde; comes with two icon themes by default, +&kde;-Classic (HiColor) and Crystal SVG. There is also a low color theme +in the kdeartwork package, along with others. + + + + +<guilabel>Theme</guilabel> + +Starting at the top, you can see some example icons. These change +in appearance depending on the icon theme you select. Most default +installations will have only one icon theme available, the &kde; default +Crystal SVG theme. There are others contained separately in the +kdeartwork package, and you can download more from the Internet. + +Use the Install New Theme... to browse to the +location of newly downloaded themes, and they will then become available +to select from above. + + + + +Advanced + +Looking at this second page of the icons control module, you +will see two areas: + + + +An area labelled Use of Icon. Here you can +choose which particular usage of icons you want to configure, for +example Toolbar or Panel. + + + A preview area where you can see how +icons of the selected kind will look using the current +settings. Note that the state of this preview also depends on the icon +state selected in the effects below (do not worry +about that now, we will explain that below). + + +When you want to configure icons, first select the usage of icons +you want to configure. Change the settings until you like the +preview. You can then choose a different icon usage and configure +that. At the end, if you are satisfied with your settings, click +OK or Apply to take the +changes in effect. + +There are two further options to consider, +Size and Effects. + + +Icon Size + +You have two options relating to icon sizes. First, you can choose +from a list of icon sizes. Second, you can tell &kde; to draw all icons +using double sized pixels. The largest icon sizes are especially useful +for visually impaired people. + +Which sizes will be offered by the icon size listbox depends on +the icon theme you have selected in the icon themes control module. For +example, the low color icon theme only offers the sizes 16 and 32 for +desktop icons and 16, 22 and 32 for toolbar icons. The HiColor theme +offers icon sizes 16, 32 and 48 as well as sizes from 64 to 128. +However, as &kde; can not have all these icon sizes in store, icons +using size 64 to 128 will be automatically generated which may result in +a loss of quality. + +If the icon sizes offered by your chosen icon theme are not enough +for you, there is still the option Double-sized +pixels. If this option is selected, all icons will have +double sized pixels, &ie; a 2x2 block instead of normal pixels. While +this makes it possible to achieve very large icon sizes, the quality is +poor: icons will look blocky, an effect you may remember +if you've grown up using a Sinclair ZX Spectrum or similar. If this is +an option for you, using the large sizes offered by &kde;'s HiColor +icon theme will always result in a much better quality than using the +low color icon theme with double sized pixels. + + +You can also choose animated icons. Many of the icons have +animations associated with them. Enable the checkbox labelled +Animate Icons, to enable this effect, but note +that it may appear slow or jerky if your graphics card is old or you +are low on memory. + + + + +Effects + +Finally you can configure certain filters to be +applied on icons which are in one of three states: + + + +Default +This is how the icon will look normally. + + +Active: +This is how the icon will look when the mouse cursor is over the icon. + + +Disabled: +This is how the icon will look if its corresponding action is +disabled, &ie; clicking on it will not lead to any +result. + + + +Select one of these states, and press the Set +Effect... button to configure a corresponding icon effect. +Please note that this configuration will only affect icons of the +currently selected Use of Icon category (see +above): configuring an effect for active icons, while +Toolbar icon usage is selected, will +not affect active icons used in other +places. + +Below the list of icon states there are two options: you can +configure an effect and you can select the +Semi-transparent option, which will make the +background shine through the icon. To the right of the +effects list box there is a slider button to pass additional parameters to +a filter for colours and Amount. + + +The following effects can be applied to icons: + + + +No Effect: +Icons will be used without applying any +effect. + + +To Gray: +This filter will apply a grayish look to the icon. Click +Setup... to configure the intensity of this filter. Note +that it is customary for most user interfaces to use this effect for disabled +icons only. + + +Colorize: +Icons will be colorized using a custom color. For example, you +may configure active icons (&ie; the icon the mouse cursor is over) to +shine golden. Use the color and Amount buttons to configure the used color and the intensity of the colorization. + + +Gamma: +A different gamma value will be applied to all icons. If you're +no photographer and don't know what Gamma is: it's quite similar to what people +call contrast. Just play around with the gamma settings by clicking on +Setup... to get a feeling for this +effect. + + +Desaturate: +Icons will be drawn desaturated. This is quite similar to the +Color setting on your television. Click +Setup... to configure the amount of desaturation. + + + +To Monochrome: + +Icons will be drawn using only the two colours selected. + + + + + + + + + + + +
diff --git a/doc/kcontrol/index.docbook b/doc/kcontrol/index.docbook new file mode 100644 index 000000000..cdaa3390f --- /dev/null +++ b/doc/kcontrol/index.docbook @@ -0,0 +1,637 @@ + + + +]> + + + +The &kcontrolcenter; + + +&Mike.McBride; &Mike.McBride.mail; + + + + + +&FDLNotice; + +2005-03-05 +3.4.0 + + +This documentation describes &kde;'s control center. + + + +KDE +kcontrol +configuration +settings +module + + + + + +The &kcontrolcenter; + + +The &kcontrolcenter; (from now on referred to simply as the +control center) provides you with a centralized and convenient +way to configure all of your &kde; settings. + + + +The control center is made up of multiple modules. Each module is a +separate application, but the control center organizes all of these +programs into a convenient location. + + + + +Each control center module can be executed individually + + + +See section entitled Running +individual control center modules for more information. + + + + +The control center groups the configuration modules into categories, so +they are easy to locate. Within each category, the control center shows +all the modules in a list, so it is easier to find the right +configuration module. + + + + +Using the &kcontrolcenter; + + +This next section details the use of the control center itself. For +information on individual modules, please see Control +Center Modules + + + +Starting the &kcontrol; + +The &kcontrolcenter; can be started in 3 ways: + + + + + +By selecting K ButtonControl +Center from the &kde; Panel. + + + + +By pressing &Alt;F2. + + + +This will bring up a dialog box. Type +kcontrol, and click +Run. + + + + + +You can type kcontrol & at any command prompt. + + + + + +All three of these methods are equivalent, and produce the same result. + + + + + +The &kcontrolcenter; Screen + + +When you start the control center, you are presented with a window, +which can be divided into 3 functional parts. + + + +Screenshot + + + + Screenshot + +The &kde; Control Center Screen + + + + + +Across the top is a menubar. The menubar will provide you with quick +access to most of &kcontrolcenter;'s features. The menus are detailed in +The &kde; Control Center +Menus. + + + +Along the left hand side, is a icon tree. Here you can choose which +module to configure. + + + +The main panel shows you some system information. + + + +In this example, we are running &kde; 3.4.0, we started &kcontrolcenter; +as user newkde, the computer is +named turtle, it is a +&Linux; system running the 2.6 kernel, on a i686 processor. + + + + + +The &kcontrolcenter; Menus + + +This next section gives you a brief description of what each menu item +does. + + + +<guimenu>File</guimenu> Menu + + +The File menu has a single entry. + + + + + + + +&Ctrl;Q + +File +Quit + + + +Closes the control center. + + + + + + + + +<guimenu>View</guimenu> Menu + + +These options determine how the module selection looks and behaves. + + + + +View Mode + + + + +Determines whether to use Tree view, +or Icon view for your modules. + + + +With Tree view, each submenu appears as an +indented list. + + + +With Icon view, when you click on a category, +the categories disappear and are replaced with the module list. You +then use the Back button to return to the categories. + + + + + + +ViewIcon size + + + + +Using this option, you can choose +Small, Medium, or +Large icons to select your modules. + + + +This menu item only controls the icon size if you are in +Icon View. If you choose +Tree View, the Small +icon size will be used, no matter what size was previously selected in +Icon View. + + + + + + + + + +<guimenu>Settings</guimenu> Menu + + + The Settings menu has a single entry, +SettingsConfigure Shortcuts.... From here you can map keyboard shortcuts to the +other menu options. + + + + + +<guimenu>Help</guimenu> Menu + +&help.menu.documentation; + + + + + + +Exiting The &kde; Control Center + + +You can exit the control center one of three ways: + + + + + +Select File +Quit from the menu bar. + + + + +Type &Ctrl;Q +on the keyboard. + + + + + +Click on the Close button on the frame surrounding +the control center. + + + + + + + +Running Individual Modules + + +You can run individual modules without running kcontrol using the command kcmshell from &konsole;. Type kcmshell to see a list of the available &kcontrolcenter; modules. You can also access individual &kcontrolcenter; modules through adding the Preferences button to either &kicker; or the &kmenu; through their respective configuration dialogs. + + + + + + + + + +The &kcontrolcenter; Modules + + +In order to make it as easy as possible, the &kcontrolcenter; has organized +similar options into groups. Each group is called a module. When you +click on the name of a module in the left window, you will be presented +with the options of the module on the right. + + + +Each module will have some or all of the following buttons: + + + + + +Help + + +This button will give you help specific to the current module. The +button will show you a short summary help page in the left window. At +the bottom of that window, you can click on a link to get more detailed +help. + + + + + +Defaults + + +This button will restore this module to its default values. You must +click OK to save the options. + + + + + +Apply + + +Clicking this button will save all changes to &kde;. If you have +changed anything, clicking Apply will cause the +changes to take effect. + + + + + +Reset + + +This button will Reset the module to the previous settings. + + + + + + + + +You must save the options of the current module using +Apply before you can change to a different +module. + + +If you try to change without saving your options, you will be asked if +you want to save your changes, or discard them. + + + + + + + + +Credits and License + +&kcontrol; +Program copyright 1997-2001 The &kcontrolcenter; Developers +Contributors: + + +&Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail; +&Matthias.Elter; &Matthias.Elter.mail; + + +Documentation copyright 2000 &Mike.McBride; &Mike.McBride.mail; + +Contributors: + + +&Paul.Campbell; &Paul.Campbell.mail; +&Helge.Deller; &Helge.Deller.mail; +&Mark.Donohoe; +&Patrick.Dowler; +&Duncan.Haldane; duncan@kde.org +&Steffen.Hansen; stefh@mip.ou.dk. +&Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail; +&Martin.R.Jones; &Martin.R.Jones.mail; +&Jost.Schenck; &Jost.Schenck.mail; +&Jonathan.Singer; &Jonathan.Singer.mail; +&Thomas.Tanghus; &Thomas.Tanghus.mail; +&Krishna.Tateneni; &Krishna.Tateneni.mail; +Ellis Whitehead ewhitehe@uni-freiburg.de + + + + +&underFDL; +&underGPL; + + + + + + diff --git a/doc/kcontrol/kcmaccess/Makefile.am b/doc/kcontrol/kcmaccess/Makefile.am new file mode 100644 index 000000000..c0d281754 --- /dev/null +++ b/doc/kcontrol/kcmaccess/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = kcontrol/kcmaccess + diff --git a/doc/kcontrol/kcmaccess/index.docbook b/doc/kcontrol/kcmaccess/index.docbook new file mode 100644 index 000000000..25ccf55c2 --- /dev/null +++ b/doc/kcontrol/kcmaccess/index.docbook @@ -0,0 +1,179 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2005-12-21 +3.01.00 + + +KDE +KControl +accessibility + + + + +Accessibility + + +Introduction + +This module is designed to help users who have difficulty hearing +audible cues, or who have difficulty using a keyboard. + + +The module is divided into two tabs: Bell and Keyboard. + + + +<guilabel>Bell</guilabel> + + +This panel is divided into an Audible Bell section +and a Visible Bell section. + + + +The top check box labeled Use System Bell, determines +whether the normal System bell rings. If this option is disabled, the +System bell will be silenced. + + + +The next check box down can be used to play a different sound whenever +the system bell is triggered. To activate, place a mark in the check +box labeled Use customized bell, and enter the +complete pathname to the sound file in the text box labeled +Sound to Play. If you want, you can select the +Browse button to navigate through your filesystem +to find the exact file. + + + +For those users who have difficulty hearing the System bell, or those +users who have a silent computer, &kde; offers the visible bell. This +provides a visual signal (inverting the screen or flashing a color +across it) when the system bell would normally sound. + + + +To use the visible bell, first place a mark in the check box labeled +Use visible bell. + + + +You can then select between Invert screen, or +Flash screen. If you select Invert +screen, all colors on the screen will be reversed. If you +choose Flash screen, you can choose the color by +clicking the button to the right of the Flash +screen selection. + + + +The slider bar can be used to adjust the duration of the visible +bell. The default value is 500ms, or half a second. + + + + + +<guilabel>Keyboard</guilabel> + +There are three sections to this panel. + + + +Use Sticky Keys + + +If this option is enabled, you can press and release the &Shift;, +&Alt; or &Ctrl; keys, and then press another key to get a key combo +(example: &Ctrl; &Alt; +Del could be done with &Ctrl; then &Alt; +then Del). + + + +Also in this section is a check box labeled Lock Sticky +Keys. If this check box is enabled, the &Alt;, &Ctrl; +and &Shift; keys stay selected until you +de-selected them. + + + +As an example: + + + +With Lock Sticky Keys disabled: + +If you press the &Shift; key then press the +F key, the computer interprets this as &Shift;F. Now if you +type a P, the computer interprets this as the letter p +(no shift). + + + + + +With Lock Sticky Keys enabled: + + +If you press the &Shift; key twice then press the F key, +the computer interprets this as &Shift;F. Now if you +type a p, the computer interprets this as the letter P +(&Shift;P). To +de-select the &Shift; key, press it again. + + + + + + + + +Slow keys + + +If this option is enabled, you must hold the key down for a +specified length of time (adjustable with the slider) before the +keystroke will be accepted. This helps prevent accidental key strokes. + + + + + +Bounce keys + + +If this option is enabled, you must wait for a specified length of time +(configurable with the slider) before the next key press can be +accepted. This prevents accidental multiple key strokes. + + + + + + + + + + + +
diff --git a/doc/kcontrol/kcmcss/Makefile.am b/doc/kcontrol/kcmcss/Makefile.am new file mode 100644 index 000000000..fc406ca64 --- /dev/null +++ b/doc/kcontrol/kcmcss/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG= en +KDE_DOCS = kcontrol/kcmcss diff --git a/doc/kcontrol/kcmcss/index.docbook b/doc/kcontrol/kcmcss/index.docbook new file mode 100644 index 000000000..106cc38d8 --- /dev/null +++ b/doc/kcontrol/kcmcss/index.docbook @@ -0,0 +1,257 @@ + + + +]> + +
+ + + +&Lauri.Watts; &Lauri.Watts.mail; + + + +2003-10-12 +3.2 + + +KDE +CSS +Stylesheets +Accessibility + + + + + + +Stylesheets + + +Introduction + +CSS style sheets affect the way web pages +appear. CSS stands for +Cascading Style +Sheets. + +&kde; can use its own stylesheet, based on simple defaults and +the color scheme you are using for your desktop. &kde; can also use a +stylesheet that you have written yourself. Finally, you can specify a +stylesheet in this module. The options presented in this module are +tuned for accessibility purposes, especially for people with reduced +vision. + +Your choices here affect every &kde; application that renders HTML +with &kde;'s own renderer, which is called khtml. These include +&kmail;, &khelpcenter; and of course &konqueror;. Choices here do not +affect other browsers such as &Netscape;. + +The module has two pages, General, where you +can choose which stylesheet to use, and Customize +where you can design an accessibility stylesheet. + + + + +General + +This page contains the following options: + + + +Use default stylesheet + +&kde; will use the default stylesheet. Some of the colors will +default to those defined in your chosen color scheme. Most settings are +easily overridden by the page you are viewing. + + + + +Use user-defined stylesheet + +&kde; will use a stylesheet that you have written yourself. You +can use the browse button to locate the stylesheet on your system. +CSS files traditionally have a .css extension, but this is not +required. + + + + +Use accessibility stylesheet defined in +"Customize"-tab + +Use the settings defined in the Customize +tab. Enabling this option will enable the options on the +Customize page. + + + + + + + +Customize + +Here you can set up a user stylesheet. The options available are +only a subset of the instructions you can add in a stylesheet, and they +are geared towards people with reduced vision, to allow users to create +a stylesheet that makes web pages and the &kde; help files more +readable. + +The options on this page are disabled unless you chose +Use accessibility stylesheet defined in +"Customize"-tab on the previous page. + + +<guilabel>Font Family</guilabel> + + + +Base family + +Choose a font family to use for body text. + + + + +Use same family for all text + +If you enable this, then the same font family will be used for all +text, regardless of the settings on the page you are viewing. This is +useful for pages which have used a decorative or hard to read font for +headlines. + + + + + + +Font Size + + + +Base Font Size + +This is the default size for text on the page. Many web sites set +their font sizes relative to this default, using larger +or +1 to make the text bigger, and smaller +or -1 to make the text smaller. +Many people design their web pages on platforms where the ordinary +default text size is too large for the average user to read, so it is +very common to come across web pages that have forced the font smaller +in this way. +This setting will allow you to set the default font to a +comfortable size, so that the relative sizes are also enlarged enough to +be comfortable. +Do not forget you can also have &konqueror; enforce a minimum size, +so that text is never too small to read. Set that +under Behavior, in the Web Browser section in &kcontrol;. + + + + +Use same size for all elements + +If you enable this option, then all text will be rendered at your +specified font size, regardless of the instructions the page contains. +Relative font sizes as discussed earlier, and even specific instructions +that text should be rendered at a certain size will be overridden +here. + + + + + + +Colors + + + +Black on White + +Many people with reduced vision find black text on a white screen +gives the most contrast, and is easiest to read. If this applies to +you, you can set this here. + + + + +White on Black + +Many other people with reduced vision find the opposite to be +true, that white text on a black screen is easier to read. + + + + +Custom + +Still other people find that pure black and white, in either +order, is difficult to read. You can set custom colors here for both +the Background and the +Foreground. + + + + +Use same color for all text + +Many web sites use a different, often contrasting color for +headings or other flourishes. If this interferes with your ability to +read the content, you can enable this checkbox to have &kde; use the +colors you have set above for all text. + + + + + + + +Images + + + +Suppress images + +If you do not want to view images, you can turn this off +here. + + + +Suppress background images + +One major problem for reduced vision users is that background +images do not give sufficient contrast to allow them to read the text. +You can disable background images here, independently of your choice +above to view all images. + + + + + + + +Preview + +The Preview allows you to see the effect of +your changes. A window will pop up, showing how several types of +headings will appear with your stylesheet, and a sentence in the default +body text. + +This should allow you to fine tune your stylesheet until you have +something that you can comfortably read. + +Happy surfing! + + + + + + + +
diff --git a/doc/kcontrol/kcmfontinst/Makefile.am b/doc/kcontrol/kcmfontinst/Makefile.am new file mode 100644 index 000000000..16be3161e --- /dev/null +++ b/doc/kcontrol/kcmfontinst/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmfontinst diff --git a/doc/kcontrol/kcmfontinst/index.docbook b/doc/kcontrol/kcmfontinst/index.docbook new file mode 100644 index 000000000..a46a8ee0f --- /dev/null +++ b/doc/kcontrol/kcmfontinst/index.docbook @@ -0,0 +1,76 @@ + + + +]> + +
+ + +&Craig.Drummond; &Craig.Drummond.Mail; + + + + +2003-10-22 +3.2 + + +KDE +KControl +fonts + + + +Font Installer + +This module is responsible for installing (and uninstalling) +fonts. The installer will configure X (X.org, XFree86), XRender, +(anti-aliasing), fontconfig, and Ghostscript (printing), +for any TrueType +(.ttf) and Type1 (.pfa, .pfb) fonts that you care to install - +bitmap (.bdf, .pcf) fonts will also be installed, but +these can only used by X. + +When the module is started by a normal (non-root) user, then the +settings will refer to their personal configuration, and installed +fonts will be available to them only. For root, the settings will usually refer to +the system-wide configuration, and as such any installed fonts should +be available to all users. +If you install fonts as a normal user and notice the fonts used for +display (and for print preview) do not match those of the printed output +- then you should re-install the fonts system-wide (i.e. as root). This can occur because when printing +the output is sent to a printer queue - and when the system comes to actually +send the information to the printer, it is running as a different user (usually +lp), and cannot find the font files. +To install fonts, simply select the "Add Fonts" button - this will +produce a file dialog, then just locate the fonts to install. Likewise, to +remove a font, simply highlight a font and press the "Delete" button. + +Using Konqueror +You can also use Konqueror to install fonts via drag-and-drop. +To do this just type fonts:/ into Konqueror's Location bar. +As a normal (non-root) user, this will produce 2 top-level folders: + + +Personal - this will display your personal fonts. + + +System - this will display the system wide fonts. If you drag-n-drop a font +on to the folders here, you will be asked for the root password in order +to install the font. + + +If you drop a font over fonts:/, then you will be asked whether this +should go into "Personal", or "System". +As root, just the contents of the system font folder will be displayed +- as root does not have any "personal" fonts. + + +
diff --git a/doc/kcontrol/kcmkonsole/Makefile.am b/doc/kcontrol/kcmkonsole/Makefile.am new file mode 100644 index 000000000..6b3d56240 --- /dev/null +++ b/doc/kcontrol/kcmkonsole/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmkonsole diff --git a/doc/kcontrol/kcmkonsole/index.docbook b/doc/kcontrol/kcmkonsole/index.docbook new file mode 100644 index 000000000..0a4367115 --- /dev/null +++ b/doc/kcontrol/kcmkonsole/index.docbook @@ -0,0 +1,177 @@ + + + +]> + +
+ + + + +&Jonathan.Singer; &Jonathan.Singer.mail; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +konsole +terminal + + + + +&konsole; + +In this module, you can configure basic settings for &konsole;, +the &kde; terminal. You can also easily create new schemata (appearance +files) for &konsole;. + +This module contains several tab pages: +General, Schema, +Session and Write +Daemon. + + +<guilabel>General</guilabel> + +This tab page allows you to configure aspects of &konsole;'s +functions. It contains the following options: + + + +Use Konsole as default terminal +application + +If you wish to have &kde; use another terminal application by +default, uncheck this box and enter the preferred application +(wterm, rxvt, +&etc;) in the text field below. + + + + +Show Terminal Size when Resizing + +By default, &konsole; will show the size (in characters) of the +window when you are resizing, allowing you to make the window a +specific size. Uncheck this box to turn off this +behavior. + + + +Show Frame + +Draw an inner frame around the inside of the &konsole; window. + + + + +Confirm quit with open sessions + +When set, a warning appears when you try to close a &konsole; +window with multiple sessions. + + + + +Blinking Cursor +If you have trouble spotting the cursor in the +&konsole; window, you can have it blink to draw your +attention. + + + +Line Spacing +Change the space between lines of text. + + + + +Consider the following characters part of a word when +double clicking +It is a common &UNIX; behavior to select a whole word +when you double click on it, however, the computer's idea of a word may +differ from yours. Add characters here that you would like to be +considered always to be part of a word. For example, +adding the @ character will allow you to double +click to select an entire email address. + + + + + +Schema + +The Schema page will allow you to easily +create, edit and save schemata, with text and background coloring, +transparency and background images. + + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/kcmlaunch/Makefile.am b/doc/kcontrol/kcmlaunch/Makefile.am new file mode 100644 index 000000000..f6c3bce75 --- /dev/null +++ b/doc/kcontrol/kcmlaunch/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmlaunch diff --git a/doc/kcontrol/kcmlaunch/index.docbook b/doc/kcontrol/kcmlaunch/index.docbook new file mode 100644 index 000000000..78bf7008f --- /dev/null +++ b/doc/kcontrol/kcmlaunch/index.docbook @@ -0,0 +1,70 @@ + + + +]> + +
+ + + +&Lauri.Watts; &Lauri.Watts.mail; + + + +2006-06-24 +3.5.2 + + +KDE +KControl +launch feedback +cursor +busy + + + + + +<guilabel>Launch Feedback</guilabel> + +Sometimes it is reassuring to know that your computer didn't just +ignore your command, and something is happening behind the scenes. In +this module you can configure visible feedback to help you know if you +really hit that icon or not. + +The traditional way to indicate that your computer is busy is to +modify the cursor, and you can turn this on by choosing a +Busy Cursor. + +With this option enabled, your cursor will have an icon attached +to it for a short time, when a new application is being launched. You +can configure how long this icon is displayed beside your cursor with the +Startup indication timeout: spinbox. The +default is 30 seconds. + +There are several variations of busy cursor available, including +a Blinking Cursor, a Bouncing Cursor +or a Passive Busy Cursor icon with no animation. + +Traditional &kde; launch notification has taken another form, +which you can also enable and disable here. Normally when you start an +application, it gets an immediate entry in the taskbar, with the icon +replaced by a spinning hourglass to let you know something is +happening. You can toggle this behavior on and off with the +Enable taskbar notification checkbox, and when it's +enabled, you can set a time in the Startup indication timeout +: spinbox. + +Not all applications that you start will eventually show a +window, or an entry in the taskbar. Some of them, for example, are +docked into the &kde; system tray. Alternatively, it might be that you +sent it off to a different virtual desktop, and Show windows +from all desktops is unchecked in the &kcontrolcenter; module +Taskbar. Setting a timeout ensures that, +even in these cases, you can still get launch feedback, but also that +it will go away when the job is done. + + +
\ No newline at end of file diff --git a/doc/kcontrol/kcmnotify/Makefile.am b/doc/kcontrol/kcmnotify/Makefile.am new file mode 100644 index 000000000..40efdecdc --- /dev/null +++ b/doc/kcontrol/kcmnotify/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmnotify diff --git a/doc/kcontrol/kcmnotify/index.docbook b/doc/kcontrol/kcmnotify/index.docbook new file mode 100644 index 000000000..cf77945f7 --- /dev/null +++ b/doc/kcontrol/kcmnotify/index.docbook @@ -0,0 +1,151 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2005-03-04 +3.4.0 + + +KDE +KControl +system notification +notification + + + + +System Notification Settings + +&kde;, like all applications, needs to inform the user when a +problem occurs, a task is completed, or something has happened. &kde; +uses a set of System Notifications to keep the user +informed on what is happening. + +Using this module, you can determine what &kde; does to communicate +each event. + +The panel consists of a large list of specific events which need +to be communicated to the user. This list is organized into groups by applications. + +To configure a notification, simply select the application from the drop down box at the top +of the dialog labeled Event source:. This will lead to a list of +all configurable notifications for the application. The list of notifications includes 6 columns to +the left of the notification name. These columns (from left to right) are: + + + +Execute a program +If an icon is present in this column, a seperate program will be executed when this notification is performed. This can be used to execute a program to help restore data, shutdown a potentially compromised system or email another user to alert them to a problem. + + + +Print to standard error output +If an icon is present in this column, &kde; will send a message to the computers standard output. + + + +Display a message box +If an icon is present in this column, &kde; will open a message box and inform the user of the notification. This is probably the most commonly selected option for alerting users to an error. + + + +Log to a file +If an icon is present in this column, &kde; will write certain information to a file on disk for later retrieval. This is useful for tracking problems or important system changes. + + + +Play a sound +This does exactly what you think it does. If an icon is present in this column, &kde; will play a specific sound over the speakers. This is commonly used by games in &kde; for starting a new game, or other action within the game. + + + +Flash the taskbar entry +If an icon is present in this column, &kde; will cause the taskbar to flash until the user has clicked the taskbar entry. This is most useful when you want the user to look at the program (such as a new email message was received, or the users name was said on an IRC channel). + + + +Change a single notification +To make a change to a notification, click on the name of the notification once with the &LMB;. The notification will be highlighted. +Now click on the button labeled +More options so you can see all the checkboxes. + +You can have more than one event triggered by a single notification. As an example, it is easy to have a sound played and +a message box appear in response to a system notification. One notification does not prevent other notifications from operating. +The following list details each of the notification types and how to use them. + + + +Play a sound +If a mark is in this checkbox, &kde; will play a sound everytime this notification is initiated. To specify the sound, use the text box to the right of the checkbox to enter the folder location of the sound file you want &kde; to play. You can use the folder button (located to the far right of the dialog box) to browse your directory tree. To hear a test of your sound, simply click on the play button (small button directly to the right of Play a sound.) + + + +Log to a file +If a mark is in this checkbox, &kde; will write certain information to a file on disk for later retrieval. To specify the log file to use, enter the pathname in the text box to the right of the checkbox. You can use the folder button (located to the far right of the dialog box) to browse your directory tree. + + + +Execute a program +If a mark is in this checkbox, a separate program will be executed when this notification is performed. To specify the program to execute, enter the pathname in the text box to the right of the checkbox. You can use the folder button (located to the far right of the dialog box) to browse your directory tree. + + + +Show a message in a pop up window +If a mark is in this checkbox, &kde; will open a message box and inform the user of the notification. The text of the box can not be changed from this dialog. If you place a mark in the checkbox labeled Use a passive window that does not interrupt other work, &kde; will open the message box, but it will not change desktops and the message box will not appear until the user returns to the program sending the notification. If that box is left empty, the user must respond to the message box even if it means they have to stop working on another program. + + + +Print a message to standard error output +If a mark is in this checkbox, &kde; will send a message to the computer's standard output. + + + +Mark taskbar entry +If a mark is in this checkbox, &kde; will cause the taskbar of the program sending the notification to flash until the user has clicked the taskbar entry. + + + +You can use the icon columns (located to the left of the notifications) to quickly select or deselect the options. Clicking in the column with the &LMB; will toggle the notification on and off. + + +Change all notifications in all &kde; applications +You can alter more than one notification at a time by using the section of the dialog labeled Quick Controls. +The first item in this section is a checkbox labeled Apply to all applications. If there is a mark in this checkbox, any changes made in the Quick Controls area are applied to all applications (not just the selected application). If there is no mark in this checkbox, any changes are limited to the application selected at the top of the dialog. +The next line consists of a button and a drop down box. This is used to enable every notification of a single type. Simply select the notification type from the drop down box (on the right) and click the button labeled Turn On All. This will enable all notifications of that type. +The bottom line operates the same, but when you select the button labeled Turn Off All, all the notifications of the selected type will be disabled. + +Change sound player options +If you click the button labeled Player settings, a small dialog box will appear with three radio buttons: + + +Use the &kde; sound system +If a mark is in this radio button, &kde; will play all sound notifications through the &kde; sound system (&arts;). You can adjust the volume of system notifications using the slider. +The slider only affects &kde; system notifications. Changes to this slider will not affect other sounds on your computer. + + +Use external player +If a mark is in this radio button, &kde; will not use the &kde; sound system to play the sound. This is a good choice if the sound format you want to use is not supported by the &kde; notification system or if you don't use the &arts; sound daemon. After checking the radio box, enter the full path and name of the program you want to use into the text field. You can use the folder button (located along the right side) to browse the directory tree. + + +No audio output +Disables all sound notifications. + + +When you have made your selection, click Apply to save changes but keep the dialog box open. Click +OK to save changes and close dialog box. Click Cancel to close the dialog box without +making any changes. + + + +
\ No newline at end of file diff --git a/doc/kcontrol/kcmsmserver/Makefile.am b/doc/kcontrol/kcmsmserver/Makefile.am new file mode 100644 index 000000000..cf4388a52 --- /dev/null +++ b/doc/kcontrol/kcmsmserver/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmsmserver diff --git a/doc/kcontrol/kcmsmserver/index.docbook b/doc/kcontrol/kcmsmserver/index.docbook new file mode 100644 index 000000000..65cb9423f --- /dev/null +++ b/doc/kcontrol/kcmsmserver/index.docbook @@ -0,0 +1,109 @@ + + + +]> + +
+ + + +&Jost.Schenck; &Jost.Schenck.mail; + + + +2003-10-13 +3.2 + + +KDE +KControl +session + + + + +Session Manager + + +Use + +In this control module you can configure &kde;'s session +manager. + +Session management refers to &kde;'s ability to save the state +of applications and windows when you log out of &kde; and restore them +when you log back in. + + + +Confirm logout + +If this option is checked, when logging out, &kde; will display a +dialog asking for confirmation. In this dialog you can also choose +whether you want to restore your current session when you login the next +time. + + + +Offer shutdown options + +If this option is checked, &kde; will offer a choice of actions during +logout. These include simply ending the current session (the +action performed if shutdown options are not enabled) turning off the +computer, or restarting the computer. + + + + +You may choose one of three options on what should happen when +you log into &kde;: + + + +Restore previous session +If this option is checked, &kde; will save your current +session's state when you logout. &kde; will restore your session on the +next login, so you can continue to work with a desktop just like you +left it. + + + +Restore manually saved session +Instead of restoring &kde; to the state it was when +you logged out last, it will be restored to a specific state that you +have saved manually. + + +Start with an empty session + +If you choose this option, &kde; will never restore sessions that it has saved. + + + + +You can configure what should happen by default when you log out of +&kde;. These options are not possible on all operating systems, and some of +them may not appear unless you are using &kdm; as your login manager. + +The options available are self explanatory, if you are in doubt, +leave the default settings. They are: + + +End current session (this is the default) +Turn off computer +Restart computer + + +Finally, you can enter a colon (:) +separated list of applications that should not be saved in sessions, +and therefore won't be started when restoring a session. For example +xterm:konsole. + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/kcmstyle/Makefile.am b/doc/kcontrol/kcmstyle/Makefile.am new file mode 100644 index 000000000..067f33e6c --- /dev/null +++ b/doc/kcontrol/kcmstyle/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmstyle diff --git a/doc/kcontrol/kcmstyle/index.docbook b/doc/kcontrol/kcmstyle/index.docbook new file mode 100644 index 000000000..4d38cf2fc --- /dev/null +++ b/doc/kcontrol/kcmstyle/index.docbook @@ -0,0 +1,189 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2005-02-20 +3.4 + + +KDE +KControl +style + + + +Style + + +Introduction + +This module is used to configure how the individual widgets are +drawn by &kde;. + +A Widget is a commonly-used +programmer's term for referring to User Interface elements such as +buttons, menus, and scroll bars. You can think of them as the +fundamental pieces that are assembled to make your +application. + +You can configure how the widgets are drawn with this module, +but to change the color of the widgets, you should refer to the +section entitled Colors. + +This panel is divided into three tabs: Style, +Effects, Toolbar. + + +<guilabel>Style</guilabel> tab + +The top list box, labeled Widget Style +contains a list of the pre-defined styles. +Each style has a name, and a brief description. + +To change styles, simply click on the style name, and a preview +of the style will be displayed in the preview box below the style list. + +The other options available here are: + + + +Show icons on buttons + +If this option is selected, action buttons (like OK and +Apply) will have a small icon located within them to act +as a visual reference. If this option is not selected, then only text +will appear on the button. + + + + +Enable tooltips + +This will toggle tooltips off and on. + + + + + + + +<guilabel>Effects</guilabel> tab + +If you click on the Effects tab, you will see the panel is divided +into two sections. +At the top of the first section, is a checkbox labeled Enable +GUI effects. If there is no mark in front of this checkbox, then all +visual effects of this panel are disabled. To edit any of these effects, simply +place a mark in this checkbox. + +Below that checkbox, are the following choices: + + +Combobox effect: +This combobox has two options. If this option is set to Animate +then when a combo box is selected, it will appear to scroll down. If Disable +is selected, then the combobox list appears instantly. + + + +Tool tip effect: +This combobox has three options. If this option is set to Animate +then when a tool tip appears, it will have a short animation. If Fade is +selected, the tool tip appears to fade from the background. If Disable +is selected, then the tool tip appears instantly. + + + +Menu effect: +This combobox has four options. If this option is set to Animate +then when a menu list appears, it will appear to scroll downward. If Fade is +selected, the menu list appears to fade from the background. If Make Transparent +is selected, the menu list will have a transparent look to it. The details of that transparency is +configured in the next part of the dialog. If Disable +is selected, then the menu list appears instantly. + + + +Menu tear-off handles: +If this option is set to Disable, then no menus can be separated +from the application. If Application Level is selected, then it is left up +to each individual application to determine which menus can be torn separated from the application. +Many applications do not have tear off menus. You cannot tell &kde; to force an +application to allow tear off menus. This is determined by the authors of the application. + + + +The next checkbox, labeled Menu drop shadow is used to toggle the drop shadow behind all +&kde; menus. A drop shadow is a dark, soft line on the bottom and right sides of the menu, which give the menus the +appearance that the menu is lifted off the application, and the menu is creating a shadow on the application. + +The next section only applies if the combobox labeled Menu Effect is set to +Make Transparent. You can use the combo box labeled Menu transparency type: +to select the method &kde; uses to generate the transparency. You can use the slider to determine the level of +transparency in menus. A preview is visible on the right side of this section. + + + + +<guilabel>Toolbar</guilabel> tab + + + + +Highlight buttons under mouse. + +If there is a mark in this checkbox, when the mouse pointer is above a toolbar +button, that button will be highlighted with a square around the button. This is a good visual +indicator of which button will be selected with a mouse click. + + + + +Transparent toolbars when moving + +As the title suggests, if this option is selected, the toolbars will be transparent when +you are moving them around on the screen. + + + + +Text position + +This combo box lets you determine where on the button the text name of the button will appear as the default. +If Icon Only is selected, then there is no text on the toolbar buttons. If Text Only is selected, then the button's icon is replaced with a text name of the button. If Text Alongside Icons is selected, then the name of the button will be placed to the right of the icon. If Text Under Icons is selected, the default will be to have the text of the button below the icon. +This option only specifies the default location. Each application can override the setting used in this panel. + + + + + + + + + + + +
diff --git a/doc/kcontrol/kcmtaskbar/Makefile.am b/doc/kcontrol/kcmtaskbar/Makefile.am new file mode 100644 index 000000000..756585015 --- /dev/null +++ b/doc/kcontrol/kcmtaskbar/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmtaskbar diff --git a/doc/kcontrol/kcmtaskbar/index.docbook b/doc/kcontrol/kcmtaskbar/index.docbook new file mode 100644 index 000000000..3f73691a3 --- /dev/null +++ b/doc/kcontrol/kcmtaskbar/index.docbook @@ -0,0 +1,142 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2006-06-24 +3.5.2 + + +KDE +KControl +taskbar +configure + + + + +Taskbar + + +<guilabel>Taskbar</guilabel> + +The taskbar is a quick way to switch between applications. The taskbar +can be located in the panel (default), or outside the panel on the +desktop. + +This module has options to control how the taskbar operates: + +Show windows from all desktops, determines +if all open windows are included in the taskbar or not. By default, +the taskbar only shows the open windows on the current +desktop. If this option is enabled, the taskbar will show +all open windows on all desktops. +Sort windows by desktop changes the +sort order of the icons on the taskbar, so that windows on virtual +desktop 1 are shown first (to the left, or at the top of the taskbar), +followed by windows on virtual desktop 2, and so on. + +Sort alphabetically by application name shows +the icons in an alphabetical sort order on the taskbar. + +You can have the taskbar Show only minimized +windows. In this case, when you minimize a window, it will +show up on the taskbar, and when you open it again, its taskbar entry +will disappear. + +You can disable Show application icons, and show just the +text. You might want to do this to save space on your taskbar, for +example. + +Using the Show window list button option, +you can enable a little button to be shown in the taskbar: this button +will open a popup menu offering access to applications on other desktops +as well as some useful actions, like Unclutter +Windows or Cascade Windows. + +Group similar tasks allows +you to save some space on your taskbar, by only showing one icon for +each running application, no matter how many windows are shown. You can +click on the icon to display a menu of all the windows that are +available. This is most useful when you have enabled Show windows +from all desktops. + +The next option allows you to set the Appearance to Elegant, Classic or For Transparency. + + + + +<guilabel>Actions</guilabel> + +The next set of options allow you to customize the actions +performed with different mouse clicks on taskbar icons. + +You can select any action from the list for the Left button, +the Middle button and the Right button. + +The options available are: + + + +Show Task List + +Show the list of tasks grouped under the icon you have clicked +on. If there is only one task or window for that icon, it will become +the active window. +This is the default action for the &LMB;. + + + + +Cycle Through Windows + +If there is more than one task grouped under the icon, switch +from one to the next, until you release the button (&ie; when you have +reached the window you are looking for). If there is only one task or +window for that icon, it will become the active window. + +This is the default action for the &MMB; if window grouping is +enabled. + + + + + +Show Operations Menu + +Show the operations menu for the application. This allows you +to minimize, maximize, &etc;, move windows between desktops, and close +windows. You can perform these actions on all windows grouped under +that icon, or on any single window, by choosing it from the +submenu. +This is the default action for the &RMB;. + + + + +Raise Task, Lower +Task, Minimize Task + +These three options make sense only if window grouping is +disabled. They are fairly self-explanatory. Raise means to make +active, bring to the front, and give focus. Lower means, send to the +back, and give focus to whichever window is now on top. + + + + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/kdm/Makefile.am b/doc/kcontrol/kdm/Makefile.am new file mode 100644 index 000000000..511936b0f --- /dev/null +++ b/doc/kcontrol/kdm/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kdm diff --git a/doc/kcontrol/kdm/index.docbook b/doc/kcontrol/kdm/index.docbook new file mode 100644 index 000000000..8f00db2f3 --- /dev/null +++ b/doc/kcontrol/kdm/index.docbook @@ -0,0 +1,518 @@ + + + +]> + +
+ + + +&Thomas.Tanghus; &Thomas.Tanghus.mail; +&Steffen.Hansen; &Steffen.Hansen.mail; +&Mike.McBride; &Mike.McBride.mail; + + + +2002-02-13 +3.00.00 + + +KDE +KControl +KDM configuration +login manager +login + + + + +Login Manager + +Using this module, you can configure the &kde; graphical login +manager, &kdm;. You can change how the login screen looks, who has +access using the login manager and who can shutdown the +computer. + +In order to organize all of these options, this module is +divided into six sections: Appearance, +Font, Background, +Sessions, +Users and +Convenience. + +You can switch between the sections using the tabs at the top of +the window. + +If you are not currently logged in as a superuser, you +will need to click the Administrator Mode +Button. You will then be asked for a superuser password. Entering a +correct password will allow you to modify the settings of this +module. + + +Appearance + +From this page you can change the visual appearance of &kdm;, +&kde;'s graphical login manager. + +The greeting string is the title of the login screen. If the +string contains the word HOSTNAME it +will be translated to the domainless name of the machine &kdm; is +installed on. + +You can then choose to show either the current system time, a logo +or nothing special in the login box. Make your choice in the radio +buttons labeled Logo area. Using the +Positions setting, you can choose to either center +the content of the logo area or to position it using fixed +coordinates. + +If you chose Show logo you can now choose a +logo: + + + +Drop an image file on the image button. + + +Click on the image button and select a new image from the image chooser +dialog. + + + +If you do not specify a logo the default +$KDEDIR/share/apps/kdm/pics/kdelogo.png +will be displayed. + +While &kde;'s style depends on the settings of the user logged in, +the style used by &kdm; can be configured using the GUI +Style option. + +Below that, you have two dropdown boxes to choose the language and the +country for your login box. + + + + +Font + +From this section of the module you can change the fonts used in +the login window. + +You can select three different font styles from the drop down box +(Greeting, Fail, +Standard). When you click on the Change +font button a dialog appears from which you can select the +new characteristics for the font style. + + + +The Greeting font is the font used for the title +(Greeting String). + + +The Fail font is used when a login fails. + + +The Standard font is used in all other places in the +login window. + + + +An example of each font can be seen in the +Example Box. + + + + +Background + +Here you can change the desktop background which will be displayed +when a user logs in. You can have a single color or an image as a +background. If you have an image as the background and select center, the +selected background color will be used around the image if it isn't +large enough to cover the entire desktop. + +The background colors and effects are controlled by the options on +the tab labeled Background and you select a +background image and its placement from the options on the tab labeled +Wallpaper. + +To change the default background color(s) simply click either of +the color buttons and select a new color. + +The dropdown box above the color buttons provides you with several +different blend effects. Choose one from the list, and it will be +previewed on the small monitor at the top of the window. Your choices +are: + + + +Flat +By choosing this mode, you select one color (using the color +button labeled Color 1), and the entire background is +covered with this one color. + + +Pattern +By choosing this mode, you select two colors (using both color +buttons). You then select a pattern by clicking +Setup. This opens a new dialog window, which gives you +the opportunity to select a pattern. Simply click once on the pattern of your +choice, then click on OK, and &kde; will render the pattern +you selected using the two colors you selected. For more on patterns, see the +section Background: Adding, Removing and Modifying +Patterns. + + +Background Program +By selecting this option, you can have &kde; use an external +program to determine the background. This can be any program of your choosing. +For more information on this option, see the section entitled Background: Using an external program. + + +Horizontal Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 on the left edge of the screen, and slowly transform into the +color selected by Color 2 by the time it gets to the +right edge of the screen. + + +Vertical Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 on the top edge of the screen, and slowly transform into the color +selected by Color 2 as it moves to the bottom of the +screen. + + +Pyramid Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 in each corner of the screen, and slowly transform into the color +selected by Color 2 as it moves to the center of the +screen. + + +Pipecross Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 in each corner of the screen, and slowly transform into the color +selected by Color 2 as it moves to the center of the +screen. The shape of this gradient is different then the pyramid +gradient. + + +Elliptic Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +2 in the center of the screen, and slowly transform into the color +selected by Color 1 as it moves to the edges, in an +elliptical pattern. + + + +The setup button is only needed for if you select Background +program or Patterns. In these instances, +another window will appear to configure the specifics. +Wallpaper +To select a new background image first, click on the +Wallpapers tab, then you can either select an image from the +drop-down list labeled Wallpaper or select +Browse... and select an image file from a file +selector. + +The image can be displayed in six different ways: + + +No wallpaper +No image is displayed. Just the background colors. + + +Centered +The image will be centered on the screen. The background colors +will be present anywhere the image does not cover. + + +Tiled +The image will be duplicated until it fills the entire +desktop. The first image will be placed in the upper left corner of the screen, +and duplicated downward and to the right. + + +Center Tiled +The image will be duplicated until it fills the entire +desktop. The first image will be placed in the center of the screen, and +duplicated upward, downward to the right, and to the left. + + +Centered Maxpect +The image will be placed in the center of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio of the +original image. This will provide you with an image that is not distorted. + + + +Scaled +The image will be scaled to fit the desktop. It will be +stretched to fit all four corners. + + + + + + +Sessions + +Allow to shutdown +Use this dropdown box to choose who is allowed to shut down: + + +None: No one can shutdown the computer using &kdm;. +You must be logged in, and execute a command. + + +All: Everyone can shutdown the computer using +&kdm;. + +Root only: &kdm; requires that the +root password be entered before shutting down the +computer. +Console only: The user must be at this +console, to shut down the computer. + + +Commands +Use these 3 blanks to define the exact shutdown command. +The shutdown command defaults to: + +/sbin/shutdown + +The restart command defaults to: + +/sbin/reboot + +The Console mode (which restarts the computer as a console only terminal) +defaults to: + +/sbin/init + +When Show boot options is enabled, &kdm; will on reboot +offer you options for the lilo boot manager. For this feature to work, you will +need to supply the correct paths to your lilo command and to +lilo's map file. + + + +Session types + +Define which session types should be accessible from the login +window. + + For more information on this subject, look at /etc/X11/xdm/Xsession to find your +xdm setup files. Also review the xdm man pages, especially under the SESSION +PROGRAM section. + +To add a session, type its name in the +blank entitled New types, and click +Add new. + +To remove a session, select the session from the list and click +Remove. + + + + + + + +Users + +From here you can change the way users are represented in the +login window. + +As you look on this window, you will see three lists (All users, +selected users, and no-show users). You also see an image box, and a +set of options along the right side of the window. + +The first thing you must decide, is if you are going to show users +or not. + + +If you choose to show users, then the login window will show +images (which you select), of a list of users. When someone is ready to +login, they select their user name/image, enter their password, and they +are granted access. + +If you choose not to show users, then the login window will be +more traditional. Users will need to type their username, and password +to gain entrance. This is the preferred way if you have many users on +this terminal. + + +To show (and sort) or not to show users + +Along the right edge of the window are two check boxes: + +If Show users is selected, you have chosen to +show images of users, instead of making them type their login +name. + +If Sort users is selected, then the list of +users will be sorted alphabetically in the login window. If unchecked, +users will be listed in the same order as they are on this page. If +Show users is not checked, this has no +effect. + + + + +How to determine which users to show and which users to hide + +Below the user image box, and above the Show +users check box, is a set of two radio buttions: + + +Show only selected users: If this option is selected, only the +users contained in the list labelled Selected Users, will +be displayed in the login window. If Show users is not +checked, this has no effect. +Show all users but no-show users: If this option is selected, +all users will be listed, except those users contained in +the list entitled No show users. If Show +users is not checked, this has no effect. + + + + + +Select users + +This page contains three listboxes. The large listbox on the left +shows all the users on the system which might be a genuine user. + +The top rightmost listbox shows the selected users and the bottom +rightmost listbox shows the users we don't want displayed in the login +window. + +To move a user from one listbox to another you click on the +username in the listbox and click >> to +move the user from the leftmost box the the rightmost box or +<< to move the user from the rightmost box +to the leftmost box. + + + + +Images + +This section of the manual only applies if Show +users is selected. If it is not, this image box has no +effect. + +Every user on the system can be represented by a image. The image +for the user is kept in a file called +$KDEDIR/share/apps/kdm/pics/users/$USER.xpm. +If the user doesn't have such a file the file +$KDEDIR/share/apps/kdm/pics/users/default.xpm +will be used instead. + +To assign a new image to a user just select the user in one of the +listboxes and either drop an imagefile on the image button to the right +or click on the image button and select a new image from the image +selector. + +If no user is currently selected you will be asked if you want to change +the default image. + +The replacement is performed by a &konqueror; process so if the +image file already exists you will be prompted by &konqueror; if you +want to replace it. If you confirm the image will be replaced - you will +not have to press the Apply +button. + + + + + + +Convenience + +In the convenience tab you can configure some +options that make life easier for lazy people, like auto login or +disabling passwords. + +Please think more than twice before using these +options. Every option in the convenience tab is +well-suited to seriously compromise your system security. Practically, +these options are only to be used in a completely non-critical +environment, ⪚ a private computer at home. + + +Automatic Login + +Automatic login will give anyone access to a certain account on +your system without doing any authentication. You can enable it using +the option Enable auto-login. + +Automatic login comes in two flavors: truly automatic +login acts like you would expect automatic login to, &ie; +&kdm; will automatically login without expecting any input from the +user. Enable this using the Truly automatic login +option. If this option is not enabled, &kdm; will start normally, +enabling you to login as any user, and will only perform automatic login +if you kill the X server, ⪚ by pressing &Ctrl;&Alt;Backspace. + +You can choose the account to be used for automatic login in the +list below. + + + + +Password-less Login + +Using this feature, you can allow certain users to login without +having to provide their password. Enable this feature using the +Enable password-less logins option. + +Below this option you will see a list of users for which a password +is required, as well as a (by default, empty) list of users that do not +need to provide a password. When Enable password-less +logins is enabled, you can move users from one list into the +other, by selecting them and then clicking the +>> and << +buttons. + +Again, this option should only be used in a safe +environment. If you enable it on a rather public system you should take +care that only users with heavy access restrictions are granted +password-less login, ⪚ +guest. + +The Automatically login after X server crash +option allows you to skip the authentication procedure when your X +server accidentally crashed. Show previous user +will show the name of the last login already entered into the login +field in &kdm;. Some site administrators would consider even this a +possible security weakness, because potential attackers then know at +least one valid login. + + + + + + + + +
diff --git a/doc/kcontrol/keyboard/Makefile.am b/doc/kcontrol/keyboard/Makefile.am new file mode 100644 index 000000000..16b3221e1 --- /dev/null +++ b/doc/kcontrol/keyboard/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/keyboard diff --git a/doc/kcontrol/keyboard/index.docbook b/doc/kcontrol/keyboard/index.docbook new file mode 100644 index 000000000..489443264 --- /dev/null +++ b/doc/kcontrol/keyboard/index.docbook @@ -0,0 +1,90 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +keyboard + + + +Keyboard + +This module allows you to choose how your keyboard works. + +The actual effect of setting these options depends upon the +features provided by your keyboard hardware and the X server on which +&kde; is running. As an example, you may find that changing the key +click volume has no effect because that feature is not available on your +system. + + +Advanced + + + +Enable keyboard repeat + +When this option is selected, pressing and holding down a key +emits the same character repeatedly until the key is released. Pressing +and holding the key will have the same effect as pressing it multiple +times in succession. + Almost all users will want to have this option enabled, because it +makes navigating through documents with the arrow keys significantly +easier. + + + + +NumLock on KDE Startup + +You can choose to either always Turn on or +Turn off the NumLock when &kde; starts, or you can +choose to have &kde; leave NumLock at whatever it was set to before KDE +started up. + + + + + +Key click volume: + +If supported, this option allows you to hear audible clicks from +your computer's speakers when you press the keys on your keyboard. In +essence, this simulates the click of a mechanical +type-writer. You can change the loudness of the key click feedback by +dragging the slider button or by clicking the up/down arrows on the +spin-button. Setting the volume to 0% turns off the key +click. +Many computers won't support this function. +Very few people would choose to enable this option, since it +generally annoys everyone else in the room. However, if your heart +yearns for the pre-soft-key era, this may help you to re-experience the +warm sentimentality of days-gone-by. + + + + + + + + + + + +
diff --git a/doc/kcontrol/keys/Makefile.am b/doc/kcontrol/keys/Makefile.am new file mode 100644 index 000000000..5b4b56825 --- /dev/null +++ b/doc/kcontrol/keys/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/keys diff --git a/doc/kcontrol/keys/index.docbook b/doc/kcontrol/keys/index.docbook new file mode 100644 index 000000000..6b7d04a6e --- /dev/null +++ b/doc/kcontrol/keys/index.docbook @@ -0,0 +1,191 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + +2002-02-13 +3.00.00 + + +KDE +KControl +key bindings +bindings +shortcuts + + + + +Shortcuts + + +Introduction + +While most of the functionality offered by &kde; can be accessed +using a simple point and click interface, many people +prefer using the keyboard for some tasks. Pressing something like + &Ctrl;F is often +just faster than moving your hands off the keyboard to the mouse, +opening the Edit menu and selecting +Find. + + As different people have different preferences about keyboard +shortcuts, &kde; offers full customization of key +bindings. A key binding or shortcut is a combination of an +action with a key or a combination of keys. + + + + +Use + +In the Shortcuts control module you'll see a list of key +schemes, a list of key bindings in the currently selected +scheme and a frame where you can customize the currently selected key +binding. Also, you'll see a tab for Global +shortcuts and one for Application +shortcuts. + + +Global Shortcuts and Application Shortcuts + +Global shortcuts and application +shortcuts work just the same. Actually, in a certain way +application shortcuts are global as well. The only +difference is: + + +Global shortcuts are shortcuts for +actions that make sense even when no application is opened. These +shortcuts usually refer to actions like switching desktops, manipulating +windows etc. +Application shortcuts refer to actions +that are often available in applications, such as Save, Print, Copy +etc. + + +Please note, that the application shortcuts configured here are +only the standard actions often found in +applications. Most applications will define their own actions as well, +for which you have to customize key bindings using the application's +key bindings dialog. + + + + +Configuring Key Bindings + +Configuring key bindings is pretty easy. In the middle of the +key bindings control module you'll find a list of available +actions. If there's a key binding configured for that action you'll +find it right next to it. Just select the action you want to +configure. + +After you've selected an action you'll notice that most of the +controls below the action list are enabled. There you can configure a +combination of keys or maybe no key binding at all for the selected +action. + + +No key: the selected action will not +be associated with any key. + +Default key: the selected action +will be associated with &kde;'s default value. This is a good choice +for most actions, as &kde; comes with reasonable key bindings we have +thought about. + +Custom key: if this option is +enabled, you can create a key combination for the selected +action. Just select any modifiers (&ie; &Shift;, &Ctrl;, or &Alt;) and +then select a key: just click on the key symbol and after that press +the key you want to assign to this key combination. + + + +As with all control modules, your changes won't take in effect +until you click OK or +Apply. Click Cancel to +discard all changes. + + + + +Configuring Schemes + +A key binding scheme is a set of key bindings that you can +select by name. &kde; comes with several pre-defined key binding +schemes. In addition to these bundled schemes, you will always see a scheme named +Current scheme that represents the set of key +bindings you are using right now (&ie; not the current settings you +are playing with, but what you've been using up to now). + +When you are playing with the key bindings for the first time +you don't have to be afraid of changing the default bindings: &kde; +won't let you overwrite the defaults, so you can always switch back to +the factory presets. By choosing Current scheme +you can return to the set of key bindings you've been using up to +now. However, be careful not to select a scheme when you've made +changes to the key bindings you don't want to lose. + +When you are satisfied with a set of key bindings you've +created, you may want to save them to a scheme of your own, so that +you can still experiment with the bindings and always return to a +certain scheme. You can always do this by clicking on the +Add button. You will be prompted for a name +and then the new scheme will appear in the key schemes listbox. You +can remove your own schemes again by selecting a scheme and clicking +the Remove button. Click the Save +changes button to save any changes you have made to the +currently selected scheme. Note that you can not remove or save +changes to KDE default or to Current +scheme. + +If you want to save your changes while a read-only +scheme is selected, you always have to add a new scheme first! If you +select one of your own schemes because you want to save the changes to +that one, the control module will switch to the key bindings of that +scheme, discarding your changes. + + + + +Modifier Keys + +Different keyboards offer different sets of modifier keys. A +&Mac; keyboard, for example, does not have a &Ctrl; key, and instead +has an Option key. Here you can see what the +available modifier keys for the current keyboard are. + +If you enable Macintosh keyboard the list +of modifiers will change. + +If you have enabled the &Mac; keyboard, you can further enable +MacOS-style modifier usage, to make &kde; behave +more like &MacOS;. + +Finally, you can change what a keypress sends to the &X-Server; +in the X Modifier Mapping section. A common +example is to reconfigure the Caps Lock key, which is +rarely used, to be another &Ctrl; key. This is especially nice if you +are a touch typist, as Caps Lock is much easier to +reach than either of the &Ctrl; keys on a standard keyboard. + + + + + + + +
diff --git a/doc/kcontrol/khtml/Makefile.am b/doc/kcontrol/khtml/Makefile.am new file mode 100644 index 000000000..c54c99e96 --- /dev/null +++ b/doc/kcontrol/khtml/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/khtml diff --git a/doc/kcontrol/khtml/index.docbook b/doc/kcontrol/khtml/index.docbook new file mode 100644 index 000000000..9f204f075 --- /dev/null +++ b/doc/kcontrol/khtml/index.docbook @@ -0,0 +1,352 @@ + + + + +]> + +
+ + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; + + + +2003-10-12 +3.2 + + +KDE +KControl +konqueror +browsing + + + + +Browsing With &konqueror; + +The &konqueror; Browser module of &kcontrol; allows you to select +various options for the appearance and behavior of &konqueror;, the +integrated web browser of &kde;. + + + +Behavior + +The first option you can enable on this page is Enable +completion of forms. If you check this box, &konqueror; will +try to remember what you answer to form questions, and will try to fill +in forms for you with the answers you previously used. + +You can configure the number of form items &konqueror; remembers +with the slider below labelled Maximum +completions + +Of course, anything &konqueror; fills in a form with, you +can still edit before submitting the form! + +The next option is Change cursor over +links. If this option is selected, the shape of the cursor +will change (usually to a hand) whenever it moves over a +hyperlink. This makes it easy to identify links, especially when they +are in the form of images. + +&konqueror; defaults to a single window per page, but has the +capability to open multiple tabs inside a +single window. &konqueror; also, by default, has a &MMB; shortcut to +open any link in a new window. If you enable Open links in +new tab instead of in new window you can &MMB; click on a +link to have it open in a new tab. + +If you are using tabbed browsing, you can choose if a newly +opened tab becomes the active (front) tab, or goes to +the back. On a slow internet connection, or while browsing a page +that has a list of headlines or other links in a list, you may like to +have the new tabs load in the background while you continue reading. +In this case, leave this setting disabled. If you prefer to go +straight to the new page, leaving the old one in the background to +return to later, enable it. + +If you close a window in &konqueror; that has multiple tabs +open, &konqueror; will ask you if you're sure that you meant to close +it. You can toggle on and off this behavior with the +Confirm when closing windows with multiple tabs +checkbox. + +As a convenience feature, if you enable Right click +goes back in history, then clicking an empty area (&ie; not +a link) in the &konqueror; window will act as if you pressed the +Back button on the toolbar. + +The checkbox labeled Automatically load +images, allows you to control whether images on web pages are +loaded by default. Unless you have a very slow connection, you will +probably want to leave this option selected, as there are many web pages +that are difficult to use without images. If you don't select the option +to automatically load images, you can still view the text on the page, +and then load the images if you need them. + +Enabling Allow automatic delayed +reloading/redirecting allows websites to send you to +another page without your interaction. In many cases, this is a +convenience. For example, the website has moved to a new +URL. Many webmasters in this situation will put up +a page on the old site, telling you that it has moved and you may like +to change your bookmark, and then automatically move you along to the +new website. However, such features can be confusing, or annoying, +when misused, and so you may wish to disable it. + +The next setting is Underline links:. You can +choose to underline links Always. If this option +is selected, any text on web pages that acts as a link will be shown in +an underlined font. While many web pages do use color to distinguish +text that acts as a link, underlining makes it very easy to spot +links. + +If you don't like underlined links, you can choose +Never, so that no links are underlined. Or you +can choose a middle ground, Hover, so that links +are underlined when the mouse cursor is resting over them, and not +underlined the rest of the time. + +Many web pages use animated gif images, and these can be very +annoying, and in some cases, quite a drain on your system resources. +The Animations option lets you choose when +animations are enabled. The default is enabled, but you can set this +to disabled, or to run the animation only once, even if the file +itself contains instructions that the animation should run more times, +or continuously. + + + + + +Fonts + +Under this tab, you can select various options related to the use +of fonts. Although the shapes and sizes of fonts are often part of the +design of a web page, you can select some default settings for +&konqueror; to use. + +The first thing you can set here is the font size. There are two +settings which work together to allow you a comfortable browsing +experience. + +Firstly, you can set a Minimum Font Size. +This means, even if the font size is set specifically in the page you +are viewing, &konqueror; will ignore that instruction and never show +smaller fonts than you set here. + +Next you can set a Medium Font Size. This is +not only the default size of text, used when the page doesn't specify +sizes, but it is also used as the base size that relative font sizes are +calculated against. That is, the HTML instruction +smaller, it means smaller than the size you set for this +option. + +For either option, you can select the exact font size in points by +using the up/down spin control (or just typing) next to the option +label. + +These options are independent of each other. Pages that do not +set a font size, or ask for the default, will display with the size +you set from Medium Font Size, while any pages +that ask for a size smaller than your Minimum Font +Size setting will instead show that size. The one does not +affect the other. + +The remaining options are for the fonts to be associated with +different types of markup used in HTML pages. Note +that many web pages may override these settings. If you click anywhere +on a control which shows a font name, a list of font names appears, and +you can select a different font if you like. (If there are a lot of +fonts, a vertical scrollbar appears in the list to allow you to scroll +through all of the fonts.) + +Below this, you can set a Font size adjustment for this +encoding. Sometimes the fonts you want to use for a +particular encoding or language are much larger or smaller than average, +so you can use this setting to bring them into line. + +You can set a default encoding that &konqueror; should assume +pages are when rendering them. The default setting is Use +language encoding, but you can change it to any encoding +available in the list. + + + + +&Java; and JavaScript + +&Java; allows applications to be downloaded and run by a web +browser, provided you have the necessary software installed on your +machine. Many web sites make use of &Java; (for example, online +banking services or interactive gaming sites). You should be aware +that running programs from unknown sources could pose a threat to the +security of your computer, even if the potential extent of the damage +is not great. + +The checkboxes under Global Settings allows +you to turn &Java; support on for all web sites by default. You can +also select to turn &Java; on or off for specific hosts. To add a +policy for a specific host, click the Add... +button to bring up a dialog in which you can type the host name and +then choose to accept or reject &Java; code from that particular host, +which will add the domain to the list on the left of the page. + +You can select a host in the list, and click the +Change... button to choose a different policy for +that host. Clicking the Delete button removes the +policy for the selected host; after deletion, the global settings will +then apply to that host. You can import policies from a file by clicking +the Import... button. To save the current list to a +compressed archive file, click the Export... +button. + +Finally, the group of controls labeled Java Runtime +Settings allows you to set some options for the way in +which &Java; should run. These options are useful for diagnosing +problems, or if you are a &Java; developer, and should not normally +need adjusting. + +If you select the Show Java +Console option, &konqueror; will open a console window from +which &Java; applications can read and write text. While most &Java; +applications will not require such a console, it could be helpful in +diagnosing problems with &Java; applications. + +Use KIO will cause the +JVMto use &kde;'s own KIO +transports for network connections. + +Use security +manager is normally enabled by default. This setting will +cause the JVM to run with a Security Manager in place. This will keep +applets from being able to read and write to your file system, creating +arbitrary sockets, and other actions which could be used to compromise +your system. Disable this option at your own risk. You can modify your $HOME/.java.policy file with the +&Java; policytool utility to give code downloaded from certain sites +more permissions. + +The Shutdown Applet Server when inactive +checkbox allows you to save resources by closing the &Java; Applet +Server when it is not in use, rather than leaving it running in the +background. Leaving this disabled may make &Java; applets start up +faster, but it will use system resources when you are not using a +&Java; applet. If you enable this, you can set a timeout. + +You can either opt to have &konqueror; automatically detect the +&Java; installation on your system, or specify the path to the +installation yourself by selecting Use user-specified +Java. You may want to choose the latter method, for +instance, if you have multiple &Java; installations on your system, +and want to specify which one to use. If the &Java; Virtual Machine +you are using requires any special startup options, you can type them +in the text box labeled Additional Java +Arguments. + + + + +JavaScript + +Despite the name, JavaScript is not related at all to +&Java;. + +The first part of this page works the same as the &Java; page +settings. + +The checkboxes under Global Settings allow +you to turn JavaScript support on for all web sites by default. You +can also select to turn JavaScript on or off for specific hosts. To +add a policy for a specific host, click the +Add... button to bring up a dialog in which you +can type the host name and then choose to accept or reject JavaScript +code from that particular host, which will add the domain to the list +on the left of the page. + +You can select a host in the list, and click the +Change... button to choose a different policy for +that host. Clicking the Delete button removes the +policy for the selected host; after deletion, the global settings will +then apply to that host. You can import policies from a file by +clicking the Import... button. To save the +current list to a compressed archive file, click the +Export... button. + +The final set of options on this page determine what happens +when a page uses JavaScript for specific actions. + +You can individually enable or disable the ability of JavaScript +to manipulate your windows by moving, resizing or changing focus. You +can also disable JavaScript from changing the status bar text, so that +for instance, you can always see where links will take you when +clicked.The choices for these options are Allow and +Ignore. + +For opening a new window, there is even more control. You can +set &konqueror; to Allow all such requests, +Ask each time a request is made, or +Deny all popup requests. + +The Smart setting will only allow +JavaScript popup windows when you have explicitly chosen a link that +creates one. + + + + +AdBlocK + +&konqueror; AdBlocK can be configured to replace or remove +images or frames from web pages that match a series of filters. + +The setting Enable filters enables or +disables the use of list of URL filters. +If Hide filtered images is enabled then +blocked images are completely removed from the page and the space they +occupied is reclaimed. If the option is disabled then a placeholder +image is used in place of filtered images. + +URL expressions to filter is a list of +URLs that will be compared against image and frame names to decide +on fitlering actions. The wildcards can be given as filename style +regular expressions. + +Each filter can either be expressed as a file style wildcard +string (e.g. http://www.site.com/ads/*) or as a full regular expression +by enclosing the filter with forward slashes (e.g. //(ads|dclk)\./). + +Import and export will save or read the current filter list to a +plain text file. Lines prefixed with an exclamation mark (!) are treated +as comments and can be used to clarify or label a set of filters. + + + +Plugins + +The first setting here is Enable Plugins +globally. If you disable this checkbox, then &konqueror; +will not use any plugins. If you enable it, then any installed and +configured plugins that it can find will be used by &konqueror; + +You can also restrict &konqueror; to Only allow HTTP +and HTTPS URLs for plugins by checking the box. + + + +&nsplugins-kcontrol; + + + +
diff --git a/doc/kcontrol/khtml/nsplugin.docbook b/doc/kcontrol/khtml/nsplugin.docbook new file mode 100644 index 000000000..1f8547461 --- /dev/null +++ b/doc/kcontrol/khtml/nsplugin.docbook @@ -0,0 +1,91 @@ + +&Netscape; Plugins + + +Introduction + +As &Netscape;'s Navigator has been a +web browsing standard for many years, so-called &Netscape; plugins have +appeared that allow rich web content. Using those plugins, web sites +can contain PDF files, flash animations, video, &etc; +With &konqueror;, you can still use these plugins to take advantage of +rich web content. + +&Netscape; plugins should not be confused with &konqueror; +plugins. The latter ones specifically extend &konqueror;'s +functionality; they are normally not used to display rich web +content. + + + + +Scan + +&konqueror; has to know where your &Netscape; plugins are +installed. This can be in several places, &ie; you might have +system-wide plugins in /opt/netscape/plugins and your personal +plugins in $HOME/.netscape/plugins. +However, &konqueror; will not automatically use the installed plugins: +it first has to scan a list of folders. You can initiate the scan +by clicking Scan for new plugins. Alternatively, +you can enable Scan for new plugins at &kde; startup +so &konqueror; will scan the appropriate folders every time &kde; +starts up, to see whether new plugins have been installed. + +Enabling Scan for new plugins at &kde; +startup can considerably slow down the startup procedure, +and is known to give difficulty on certain installations. Turn this +option off if you experience problems. + +To find plugins, &konqueror; will look in the folders +specified in the Scan Folders frame. When you +use this control module for the first time, this list will already be +filled with reasonable paths that should work on most operating systems. +If you need to provide a new path, click the New +button; then you can either enter the new path in the text edit box to +the left, or choose a folder using the file dialog by clicking the +New... button. As scanning the folders can take +a little time, you might want to remove folders from the list where +you know that no plugins are installed: do this by selecting a folder +and clicking Remove. Using the +Up and Down buttons you +can change the order in which folders will be scanned by moving the +selected folder up or down. + +As usual, click Apply to save your changes +permanently. + + + + +Plugins + +In this tab, you can see a list of the &Netscape; plugins found by +&konqueror;, displayed as a tree. Double click on a plugin to fold it +out and you'll see that the different mime types this plugin can handle +will be displayed as branches. Fold out a mime type to see its +info. + +This tab is mostly for informational purposes. The only +configurable option is Use artsdsp to pipe plugin sound +through aRts, which is enabled by default. Disable this if +you wish plugins to use their own method for sounds, and you have +configured &arts; in such a way that third-party applications can do +so (for example, by having it exit when idle, or by having it use a +custom sound device on modern soundcards which allow this.) + + + + +Section Author + +This section written by: Jost Schenck +jost@schenck.de + + + + + + diff --git a/doc/kcontrol/kwindecoration/Makefile.am b/doc/kcontrol/kwindecoration/Makefile.am new file mode 100644 index 000000000..ad89ecd92 --- /dev/null +++ b/doc/kcontrol/kwindecoration/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kwindecoration diff --git a/doc/kcontrol/kwindecoration/index.docbook b/doc/kcontrol/kwindecoration/index.docbook new file mode 100644 index 000000000..c6bfd5276 --- /dev/null +++ b/doc/kcontrol/kwindecoration/index.docbook @@ -0,0 +1,98 @@ + + + +]> + +
+ + + +&Rik.Hemsley; &Rik.Hemsley.mail; + + + +2003-09-28 +3.2 + + +KDE +KControl +kwin +window +border +theme +style + + + +Window Decoration + + +General + +This module allows you to select a style for the borders around +windows. + +Each style has a different look, but also a different +feel. Some have (sometimes invisible) +resize borders all around the edge, which make resizing +easier but moving more difficult. Some have no borders on certain +edges. One (BII) even has a dynamically sized and +positioned title element. + +You are encouraged to experiment with the different styles until +you find one which best suits your pattern of work. + +Choose a window decoration style from the drop down box at the +top of the screen to see a preview of it in the lower pane. + +If there are any configurable options for the theme you chose on +the first page, they will become available below the preview... + + + + + + +Buttons + +This page has instructions directly on it - just drag around the +buttons until you have the order that makes you comfortable. + + +Not all the window decorations are able to comply with your custom +set button order. The ones that cannot are being converted, but at the +time of this release they have not been all been changed. + + +Apart from choosing the window decoration itself, you can choose +here two further options: If there should be a tooltip while you hover +your mouse over a window decoration button, and if the window +decoration should attempt to use a custom set button order. + + +The tooltips can be quite useful if you have set a custom button +order, and then changed to an unfamiliar window decoration. + + + +For accessibility purposes, some window decorations support +extra wide borders. If this is available, you can also choose a +border size here. These large borders are easier to see for low +vision users, and easier to grab for people with limited mobility or +difficulty using a mouse. + + + + + + +
diff --git a/doc/kcontrol/language/Makefile.am b/doc/kcontrol/language/Makefile.am new file mode 100644 index 000000000..ab4abf365 --- /dev/null +++ b/doc/kcontrol/language/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/language diff --git a/doc/kcontrol/language/index.docbook b/doc/kcontrol/language/index.docbook new file mode 100644 index 000000000..c93c16190 --- /dev/null +++ b/doc/kcontrol/language/index.docbook @@ -0,0 +1,218 @@ + + + +]> + +
+ + + + +&Mike.McBride; &Mike.McBride.mail; +&Krishna.Tateneni; &Krishna.Tateneni.mail; + + + + 2003-10-14 + 3.2 + + + KDE + KControl + locale + country + language + + + + + +Country and Language + +This module of the &kde; control center allows you select +customization options that depend on the region of the world that you +happen to live in. There are five different pages in this module, each +of which is described in detail in the following sections. + +In most cases, you can simply select the country you live in, and +the other options will be set in an appropriate manner. + +Below the pages of this module, you can see a preview of what the +settings look like. In addition to positive and negative numbers, you +can see how positive and negative currency values, long and short dates, +and times are displayed. When you change any of the settings, the +preview shows the effects of the changes before you apply them. + + +Locale + +On this page, there are two lists, from which you can +select the country and languages that you want +to use. + +When you click on the Country list, +a menu pops up showing major groups of countries. You can select +one of these regions and see a list of the countries that are +available for that region. + +If the language for the country you have selected is available on your +system, it will be selected automatically. For instance, choosing +Germany as the country will select +German as the language, if it is available. + + + + +Numbers + +On this page, you can select options for how numbers are +displayed. The defaults are selected automatically based on the country +which is currently selected. + +In the text box labeled Decimal symbol, you +can type the character that you want to use to separate the decimal +portion of numbers. You could put anything here you wanted to, but +really, . and , are the +two characters that make the most sense. + +Similarly, you can choose the character which is used to group +units of thousands in numbers. If no character, not even a space, is +present, then there will be no separator for thousands. + +Finally, you can choose what character should be prefixed to +positive and negative numbers respectively. For example, the default +for English is not to have any prefix for positive numbers, and a +- for negative numbers. + + + + + +Money + +Unlike the display of ordinary numbers, conventions for +currency values do vary from region to region. However, you will +find that the defaults are probably fine. + +The character or characters representing the currency symbol +are based on the country that is currently selected. The decimal +symbol and thousands separator work as they do for numbers. The +text box labeled Fract digits allows you +to specify the number of fractional digits used in displaying +currency values. + +For both positive and negative currency values, you can +control whether the currency symbol appears before or after the +numeric value, and how the sign of the value is distinguished +in the display. Note that the symbols used for the sign of +currency values are the same as those used for other numeric +values. + +If the checkbox labeled Prefix currency +symbol is selected, the currency symbol appears +before the numeric value. If this checkbox is cleared, then the +currency symbol appears after the numeric value. + +There are five choices for the way in which the sign of the +currency value is handled: + +The Parens around +option displays the numeric value within a pair of +parentheses. +The Before quantity money +option displays the sign before the numeric value, but after any +currency symbol that may be present. +The After quantity money +option displays the sign after the numeric value, but before any +currency symbol that may be present. +The Before money option +displays the sign before the numeric value as well as any +currency symbol that may be present. +The After money option +displays the sign after the numeric value as well as any +currency symbol that may be present. + + + + + +Time and Dates + +If you use a different calendar system than Gregorian, you can +choose this from the first dropdown box. + +On the rest of this page, there are text boxes for the time, long +date, and short date, in which you can type format strings to control +the way in which times and dates are displayed. + +Except for the special codes described below, any other characters in the +format strings are displayed literally. The special codes consist of a +% sign followed by a character, as shown in the list of +codes below: + + +Time format codes: + + + HH - The hour according to a 24-hour + clock, using two digits (00 to 23). + hH - The hour according to a 24-hour + clock, using one or two digits (0 to 23). + PH (uppercase p) - The hour according + to a 12-hour clock, using two digits (01 to 12). + pH (lowercase p) - The hour according + to a 12-hour clock, using one or two digits (1 to 12). + MM - The current minute using two digits + (00 to 59). + SS - The current second using two digits + (00 to 59). + AMPM - Either am or pm depending on the hour. + Useful with PH or + pH. + + + +Date format codes: + + YYYY - The year, using 4 + digits. + YY - The year, using 2 + digits. + MM - The month, using 2 digits (01 to + 12). + mM - The month, using 1 or 2 digits (1 + to 12). + MONTH - The name of the + month. + SHORTMONTH - The abbreviated name of the + month. + DD - The day, using 2 digits (01 to + 31). + dD - The day, using 1 or 2 digits (1 to + 31). + WEEKDAY - The name of the + weekday. + SHORTWEEKDAY - The abbreviated name of the + weekday. + + + + +Finally, there's a combobox labeled First day +of the week which lets you select which day is the first +one of the week in your country. + + + +Other +You can select the default paper format with the combo box labeled Paper Format. + +Use the drop down box labeled Measure system to select Imperial or +Metric systems of measurement. + + + + +
diff --git a/doc/kcontrol/mouse/Makefile.am b/doc/kcontrol/mouse/Makefile.am new file mode 100644 index 000000000..b0a8d6b17 --- /dev/null +++ b/doc/kcontrol/mouse/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/mouse diff --git a/doc/kcontrol/mouse/index.docbook b/doc/kcontrol/mouse/index.docbook new file mode 100644 index 000000000..62d223de1 --- /dev/null +++ b/doc/kcontrol/mouse/index.docbook @@ -0,0 +1,493 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Brad.Hards; &Brad.Hards.mail; + + + +2004-10-09 +3.03.00 + + +This is the documentation for the &kde; &kcontrol; module that configures mice and other pointing devices. + + + + +KDE +KControl +mouse + + + + +Mouse + +This module allows you to configure your pointing device. Your +pointing device may be a mouse, a track ball, a touch-pad, or another piece +of hardware that performs a similar function. + +This module is divided into several tabs: +General, +Cursor Theme, +Advanced and +Mouse Navigation. +There may also be one or more additional tabs if you have a Logitech mouse +or trackball, providing access to special features. + + + +<guilabel>General</guilabel> + + + +Button Order + +If you are left-handed, you may +prefer to swap the functions of the left and +right buttons on your pointing device by choosing the +Left handed option. If your pointing device has more than two +buttons, only those that function as the left and +right buttons are affected. For example, if you have +a three-button mouse, the middle button is +unaffected. + + + + +Reverse scroll direction + +With this checkbox selected, the scroll wheel (if any) will work in the opposite direction (so that if rolling the top of the scroll wheel towards you previously causes a scroll down, then it will now cause a scroll up). This may be useful to handle a unusual setup of the X server. + + + + + +Double-click to open files and folders (select icons on first click) + + If this option is not checked, icons/files will be opened with a +single click of the left mouse-button. This +default behavior is consistent with what you would expect when you click +links in most web browsers. If checked however, icons/files will be +opened with a double click, while a single click will only select the +icon or file. This is the behavior you may know from other desktops or +operating systems. + + + + +Single-click to open files and folders + +This is the default setting for &kde;. Clicking once on an icon +will open it. To select you can drag around the icon(s) or &Ctrl;Right click, +or simply click and hold to drag it. You can also enable automatic selection of icons using the Automatically select icons checkbox, discussed below. + + + + +Change pointer shape over icons + +When this option is checked, the shape of the mouse pointer +changes whenever it is over an icon. + +This option should be checked in most situations. It gives +more visual feedback and says, in essence, if you click here, something +will happen. + + + + + +Automatically select icons + + +As noted above, if you have Single-click to open files and folders selected, you can select icons by dragging around them, or by using &Ctrl;Right click. If you routinely need to select icons, you may want to enable this checkbox, which will allow icons to be selected automatically by pausing over the icon. The Delay: slider determines how long is required before the automatic selection takes effect. + + + + + +Visual feedback on activation + +When this option is +checked, &kde; gives you visual feedback whenever you click on something and activate it. + + + + + + +<guilabel>Cursor Theme</guilabel> + + +This tab allows you to select from a number of cursor themes. A preview of the cursor display is shown above the listbox. + + +The features provided by this tab may not be available on some systems. Your system may need to be updated to support cursor themes. + + + +If you have additional cursor themes available to you, you can install and remove them using the buttons below the listbox. Note that you cannot remove the default themes. + + + + + +Advanced + + + + +Pointer acceleration + +This option allows you to change the relationship +between the distance that the mouse pointer moves on the +screen and the relative movement of the physical device +itself (which may be a mouse, track-ball, or some other +pointing device.) + +A high value for the acceleration multiplier will lead to large +movements of the mouse pointer on the screen, even when +you only make a small movement with the physical device. + +A multiplier between 1x and +3x will works well for many systems. With a multiplier +over 3x the mouse pointer may become difficult to +control. + + + + +Pointer threshold + +The threshold is the smallest distance that the mouse pointer must +move on the screen before acceleration has any effect. If the movement +is within the threshold, the mouse pointer moves as if the acceleration +were set to 1x. + +Thus, when you make small movements with the physical device (⪚ +mouse), you still have fine control of the mouse pointer on the screen, +whereas larger movements of the physical device will move the mouse +pointer rapidly to different areas on the screen. + +You can set the threshold value by dragging the slider button or +by clicking the up/down arrows on the spin-button to the left of the +slider. + +In general, the higher you set the Pointer +acceleration value, the higher you will want to set the +Pointer threshold value. For example, A +Pointer threshold of 4 pixels may +be appropriate for a Pointer Acceleration of +2x, but 10 pixels might be +better for 3x. + + + + +Double click interval + +This is the maximum amount of time between clicks for &kde; to +register a double click. If you click twice, and the time between those +two clicks is less than this number, &kde; recognizes that as a double +click. If the time between these two clicks is greater than this +number, &kde; recognizes those as two separate +single clicks. + + + + +Drag start time and Drag start +distance + + +If you + +click with the mouse +drag within the time specified in Drag start +time, and +move a distance equal to or greater than the number (of +pixels) specified in Drag start distance + + + +&kde; will drag the selected item. + + + + +Mouse wheel scrolls by + +If you have a wheel mouse, use the slider to determine how many +lines of text one step of the mouse wheel will +scroll. + + + + + + + + +<guilabel>Mouse Navigation</guilabel> + + +This tab allows you to configure the keyboard number pad keys as a mouse-type device. This may be useful when you are working on a device without another pointing device, or where you have no other use for the number pad. + + + + + +Move pointer with keyboard (using the num pad) + + +To enable keyboard mouse mode, you need to select the checkbox labelled Move pointer with keyboard (using the num pad). When you do this, the other settings will become enabled, and you can customize the keyboard pointer behavior further, if required. + + +The various keys on the number pad move in the direction you would expect. Note that you can move diagonally as well as up, down, left and right. The 5 key emulates a click to a pointer button, typically &LMB;. You change which button is emulated by using the / key (which makes it &LMB;), * key (which makes it &MMB;) and - (which makes it &RMB;). Using the + emulates a doubleclick to the selected pointer button. You can use the 0 key to emulate holding down the selected pointer button (for easy dragging), and then use the . to emulate releasing the selected pointer button. + + + + + +Acceleration delay + + +This is the time (in milliseconds) between the initial key press and the first repeated motion event for mouse key acceleration. + + + + + +Repeat interval + + +This is the time in milliseconds between repeated motion events for mouse key acceleration. + + + + + +Acceleration time + + +This is the number of key events before the pointer reaches a maximum speed for mouse key acceleration. + + + + + +Maximum speed + + +This is the maximum speed in pixels per key event the pointer can reach for mouse key acceleration. + + + + + +Acceleration profile + + +This is the slope of the acceleration curve for mouse key acceleration. + + + + + + + + + +<guilabel>Logitech Support</guilabel> + + +Some Logitech USB mice support special features, such as switching to a higher resolution, or +providing cordless status. If KDE was built with libusb support, then you will get an additional +tab for each supported mouse that is plugged in. + + + +The supported devices are: + + +Wheel Mouse Optical +MouseMan Traveler +MouseMan Dual Optical +MX310 Optical Mouse +MX510 Optical Mouse +MX300 Optical Mouse +MX500 Optical Mouse +iFeel Mouse +Mouse Receiver +Dual Receiver +Cordless Freedom Optical +Cordless Elite Duo +MX700 Optical Mouse +Cordless Optical Trackman +Cordless MX Duo Receiver +MX100 Laser Mouse +Receiver for Cordless Presenter + + + +Not all devices support all capabilities (typically cordless devices do not +provide resolution switching, and of course only cordless devices support +cordless status reporting), so some parts of the tab will not be enabled for +some mouse types. + + + +If the mouse supports resolution switching, the Sensor Resolution +radio button group will be enabled, and you can switch from 400 counts per +inch to 800 counts per inch and back. If you use +800 counts per inch, the same physical movement of the mouse +will cause a greater (roughly double) amount of motion of the cursor. This tends +to be popular amongst gamers. + + + +If the mouse supports cordless reporting, the Battery Level +and RF Channel widgets will be enabled. You can only change +the RF Channel if your mouse has two channel support. + + + +Fixing permission problems on Logitech mice + + +Because of the way USB devices work, the code that accesses the current +status on Logitech mice needs to be able to write to the mouse. This +should be handled by your distribution, but if not, you may need to do some +configuration yourself. + + + +On a Linux system, you should use the hotplug system to change the ownership +and permissions on the mouse entry in /proc/bus/usb. One +way to do this is to create a short script +(/etc/hotplug/usb/consoleUserPerms) that changes the ownership +and permissions, as shown below: + + + + + + if [ -f /var/run/console.lock ] + then + CONSOLEOWNER=`cat /var/run/console.lock` + elif [ -f /var/lock/console.lock ] + then + CONSOLEOWNER=`cat /var/lock/console.lock` + else + CONSOLEOWNER= + fi + if [ -n "$CONSOLEOWNER" ] + then + chmod 0000 "${DEVICE}" + chown "$CONSOLEOWNER" "${DEVICE}" + chmod 0600 "${DEVICE}" + fi +fi +]]> + + + + +The usermap file that goes with this is +/etc/hotplug/usb/logitechmouse.usermap, as +shown below: + + + + + + + + + +That should be all that is needed on Linux - just copy the files into +/etc/hotplug/usb/, and when the mouse is +plugged in, the ownership and permissions should be changed +so that the user at the console can access the mouse. + + + + + + + +
diff --git a/doc/kcontrol/netpref/Makefile.am b/doc/kcontrol/netpref/Makefile.am new file mode 100644 index 000000000..8dacf4438 --- /dev/null +++ b/doc/kcontrol/netpref/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/netpref diff --git a/doc/kcontrol/netpref/index.docbook b/doc/kcontrol/netpref/index.docbook new file mode 100644 index 000000000..f97b30b36 --- /dev/null +++ b/doc/kcontrol/netpref/index.docbook @@ -0,0 +1,109 @@ + + + +]> + +
+ + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +2002-10-16 +3.1 + + +KDE +kdebase +kcontrol +network +timeouts + + + + + + +Preferences + +Here you can set timeout values. You might want to tweak them +if your connection is very slow, but the default settings are +appropriate for most users. + +Here Timeout Values are the length of time +an application should wait for an answer from a network operation. + +You can configure the following timeouts: + + + +Socket read: + + Some applications use sockets to +communicate. You can think of a socket as a water tap; while it is +open, water (or in our case, data) comes out, without any interaction. +If something stops this flow of data, the application will wait for +more to come. This could be a very long time, but you can configure a +maximum time for an application to wait with this option. +This setting will only apply to &kde; applications, of course. + + + + +Proxy connect: + + +Sets how long to wait for a connection to a proxy server, if one is configured. + + + + + +Server connect: + + +Sets how long to wait for a connection to a remote server. + + + + + +Server response: + + +Sets how long to wait for a reply from a remote server. + + + + + + +You can configure FTP Options here. At +present there is just two options: + + +Enable passive mode (PASV) +Passive &FTP; is often required when you are behind a firewall. +Many firewalls only permit connections that were initiated from +the inside. Passive &FTP; is controlled by the client, +which makes it usable through firewalls. + + + +Mark partially uploaded files +When a mark is placed in this box, partially uploaded files will +have a .part extension added to the end +of the file. This extension is removed once the file download is complete. + + + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/panel/Makefile.am b/doc/kcontrol/panel/Makefile.am new file mode 100644 index 000000000..06524aebe --- /dev/null +++ b/doc/kcontrol/panel/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/panel diff --git a/doc/kcontrol/panel/index.docbook b/doc/kcontrol/panel/index.docbook new file mode 100644 index 000000000..722c6ed9d --- /dev/null +++ b/doc/kcontrol/panel/index.docbook @@ -0,0 +1,244 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Lauri.Watts; &Lauri.Watts.mail; + + + +2005-02-20 +3.4 + + +KDE +KControl +panel + + + + +Panel + + The &kde; panel (often referred to as &kicker;) is the bar that +you'll usually find at the bottom of the screen when you start up &kde; +for the first time. For detailed help on &kicker;'s usage you can type + help:/kicker in &konqueror; to read +the user manual. + +The panel gives you quick access to applications and makes it +easier for you to organize your desktop. Using the &kde; panel you +can: + + +launch applications using the K menu or +the application buttons +switch desktops using the panel's pager applet + +switch active windows, and minimize or maximize them + +browse folder using the browser menu functionality + +access panel applets that extend the panel's functionality, +offering for example mixers, clocks or a system monitor + + + +<guilabel>Arrangement</guilabel> + +In the Arrangement tab you can configure the size and +position of the panel. + +If you have more than one panel on screen, you can select at the +top of the window which panel you wish to configure. + +In the section labeled Position is a set of +12 small buttons arranged in a square. Each button corresponds to a +location for the panel. Click on a button and notice where the panel +is located on the preview monitor to the right. + +Generally, the available space in kicker is used more +efficiently if the panel is aligned horizontally, &ie; attached to the +top or bottom screen border. + +In the section labeled Length, you can use +the combo box and slider to adjust the minimum +length of the panel. If you place a mark in the checkbox labeled +Expand as required to fit contents, the panel +will become longer if more space is needed. When less space is +required on the panel, the panel will shrink down to the minimum size. +If there is no mark in the checkbox, then the panel is fixed to the +length specified in this section. + +The final section of this table is labeled +Size, and refers to the +height of the panel. The panel's size can be +Tiny, Small, +Medium, Large or +Custom. If you choose +Custom mode, you can resize &kicker; by +specifying a height in the combobox. + +If you have multiple monitors, you can configure the panel for +each screen entirely independently. If you are not sure which screen +is which, Press the Identify and a number will +appear centred on each screen. + + +Then simply choose the screen you wish to configure from the +drop down box labelled Xinerama screen, or choose +All Screens to have identical configurations on +each. + + + + +Hiding + +Depending on your screen resolution you may find that the panel +takes away too much of your precious screen real estate. To save +screen space, the panel offers manual hiding of the panel, an auto +hide feature, and the ability to allow other windows to lay on top of +the panel. These features are selected in the section entitled +Hide Mode. + +The Hide Mode section has three options: + + +Only hide when panel-hiding button is clicked +When this option is selected, the panel will remain visible at +the location you defined unless you click on the button at the far right (for horizontally +oriented) or bottom (for vertically oriented) button. This button has an arrow on it pointed +to the edge of the screen. + +Once clicked, the panel will disappear. If the button is clicked again, the panel will re-appear +at the same location. + + + + +Hide automatically +If this option is selected, then the panel will automatically disappear after +the number of seconds specified in the combo box below the option. To make the panel reappear, +simply move the mouse pointer to the edge of the screen where the panel is located, and the +panel will reappear immediately. + +If you place a mark in the checkbox labeled Show panel when switching +desktops, the panel will automatically reappear when you switch desktops. (The panel +will disappear again after the specified number of seconds.) + + + + +Allow other windows to cover the panel +As this option's label implies, the panel is always on the desktop when +this option is selected. It is now possible, however, for application windows to lay +on top of the panel. + +To restore the panel, simply move the mouse cursor to the screen +location specified in the drop box labeled Raise when the pointer touches +the screen's:. You can change this value by selecting one of the choices +provided in the drop down box. + +Once the panel has moved back on top of the application window, it will stay there +until an application window becomes active again. + + + + +The next section down is labeled Panel-Hiding Buttons. It +consists of two check boxes: Show left panel-hiding button and +Show left panel-hiding button. Use these checkboxes to show and +hide the left and right manual panel hiding buttons. + +If there is no mark in the checkbox labeled Animate +panel hiding, then whenever the toolbar is hidden, is simply disappears. If there +is a mark in the check box, then the panel appears to slide off the edge of the screen. + +You can determine how quickly the panel appears to move by adjusting the slider from +Fast to Slow. + + + +Menus + +In the Menus tab you can configure the panel +menu's behavior. This affects the K menu you will often use to launch +applications, the browser menus you can use to access folders and other +menus like the recent documents menu. + +The K Menu frame offers you some options to +configure the K menu's functionality. This frame consists +of 4 items: + + +The Menu item format: radio +buttons have three options. This determines how the application name +(&ie; &konqueror;, &kword;, &etc;) and the description (&ie; Web +Browser, Word Processor, &etc;) are displayed on the &kmenu;. + + +The Optional Menus checkboxes allow +you to +determine which special menu items appear in the &kmenu;. +The Bookmarks +menu allows you to quickly select from the same bookmarks that are available in &konqueror;. +The Find menu offers access to the &kfind; application to search for local files, and a quick link to a search engine to search for things on the Internet. +The Konqueror Profiles menu allows you to +launch &konqueror; with any of your configured profiles. +The Network Folders menu can launch a +&konqueror; file manager window displaying any of your configured +network folders. +The Preferences menu allows you to launch each &kcontrol; module +directly from the K menu. +The Print System menu provides several menu entries to help manage +the printer(s) attached to your system. +The Quick Browser menu gives you quick links to locations on your hard drive. +The Recent Documents menu lists the most recently edited documents and will automatically +launch the application to edit or view this document. +The System menu allows you quick access to +some commonly visited places, including your Home folder, and the +Trash. You may find this useful instead of having a separate entry for +each of these in the &kmenu; +The Terminal Sessions menu provides menu items to launch several different types of +terminal programs (command line interfaces). + + +Show side image will add a small +image to the side of the menu. This is purely decorative. + +The Edit K Menu button launches the &kde; +menu editor. + + + In the QuickBrowser Menus area you can configure +whether the panel's browser menus will show hidden files or not (hidden +files on &UNIX; systems are those whose filenames begin with a dot) as +well as how many files at most will be shown in a browser menu. The +latter option may be especially useful if you have a rather small screen +resolution, as then the browser menus will quickly fill up your screen +when you browse folders containing many files. + +The quick start section in the K menu offers quick access to +programs you have used often or recently. In the Quick Start Menu Items +frame you can choose whether +this section will show the most recently or the most frequently used +programs. Using the option Maximum number of entries +combo box, you can configure how many programs the quick start +section will remember. + + + + + + + +
diff --git a/doc/kcontrol/panelappearance/Makefile.am b/doc/kcontrol/panelappearance/Makefile.am new file mode 100644 index 000000000..1a92a45e8 --- /dev/null +++ b/doc/kcontrol/panelappearance/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/panelappearance + diff --git a/doc/kcontrol/panelappearance/index.docbook b/doc/kcontrol/panelappearance/index.docbook new file mode 100644 index 000000000..1619c3f12 --- /dev/null +++ b/doc/kcontrol/panelappearance/index.docbook @@ -0,0 +1,122 @@ + + + +]> + +
+ + + + +Mike +McBride + + +Jost +Schenck + + + + +2003-10-06 +3.2 + + +KDE +KControl +panel + + + + +Panel + +Here you can configure the panel's overall appearance. + +You can also have the icons themselves zoom out when the +mouse is over them, with the Enable icon zooming +option. You can choose to have tooltips appear when your mouse button is +over an icon, by enabling the Show tooltips +option. + + +Button Backgrounds + +The &kde; panel supports so-called Button +Backgrounds. This means that the buttons shown on the panel +will be drawn using configurable images. To enable button backgrounds, +simply choose the button type from the list, and change the drop down +box to the color image you would like to use. Choose +Default to return to an unstyled button. If you +choose Custom color, the color button next to the +drop down list will be enabled. Click on it to select a custom color +to use. + + + + +<guilabel>Panel Background</guilabel> + +Enable transparency to turn the entire +panel transparent. The desktop background will show through instead +of a background image or color. + +There will still be small handles beside each applet, to allow +you to locate, move, and configure them. These can be turned off in +the Advanced Options + +If you check Enable background image a +picture will be used to draw the panel's background, just as you +can use a picture for the desktop background. You can specify an image +file in the line edit box below or choose one by clicking on the +Browse button. You'll see a preview of the +selected picture on the right. + +The image can be tinted on-the-fly by enabling the option +Colorize to match the desktop color scheme. You +might use a grayscale texture that is tinted in this manner, to create +a particular effect. + + + +<guilabel>Advanced Options</guilabel> + +The Hide button size: option allows you to +choose a width in pixels for the hide buttons, if they are +visible. + +The panel itself has several default sizes set, which you can +switch between by simply dragging the edge of it, or by &RMB; clicking +on an empty space in the panel, choosing Size +and selecting the desired size from the submenu. If you enable +Allow Drag and Drop resizing of panels then by +choosing Custom in the panel menu, you can +drag the panel edge to any size you like. + +Applet handles are normally visible beside each applet on the panel, so that it is clear where to click to configure them, or to get to the panel menu. You can instead have them Fade out, or hide unless you hover the mouse over them, or you can choose to Hide them completely. + +Finally, if the panel is transparent, you can tint it with a +color of your choice. The slider allows you to choose how opaque the +tint is. At the lowest end, there is no tint visible, while at the +highest, the panel is not transparent at all. + + + + +Section Author +This section written by: Jost Schenck jost@schenck.de +Minor update by Mike McBride +mpmcbride7@yahoo.com + +Some new options added by Lauri Watts +lauri@kde.org + + + + + + + +
diff --git a/doc/kcontrol/passwords/Makefile.am b/doc/kcontrol/passwords/Makefile.am new file mode 100644 index 000000000..6c8d0b013 --- /dev/null +++ b/doc/kcontrol/passwords/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/passwords diff --git a/doc/kcontrol/passwords/index.docbook b/doc/kcontrol/passwords/index.docbook new file mode 100644 index 000000000..3aa2ed0bc --- /dev/null +++ b/doc/kcontrol/passwords/index.docbook @@ -0,0 +1,84 @@ + + + +]> + +
+ + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; + + + +2003-10-16 +3.2 + + +KDE +KControl +password + + + + + +Passwords + + +Introduction + +This module of the &kcontrol; gives you options for configuring the way in +which the &kdesu; program treats passwords. &kdesu; will ask you for a password +when you try to carry out some privileged actions, such as changing the +date/time stored in your system clock, or adding new users on your +computer. + +Privileged actions such as those described above can only be +carried out by root or a +user with administrator permissions on your system. You will need to +enter the password for the root account when you want to carry out +such actions. + +The options in this module do not affect the behavior of +passwords in other programs such as &kmail;. + + + + + +Use + +There are two configuration options for passwords. The first is +to control the visual feedback that you receive when you type a +password. The actual characters in the password are never shown on the +screen. You can choose to have each character represented by a +* character. If you want to make it harder for someone +who might be watching your screen to figure out how many characters +there are in the password, you can choose to have each character in +the password be represented by three asterisks rather than just +one. Still another option is not to have any visual feedback at all, +so nothing appears on the screen when you type a password. + +If you work in a reasonably secure environment, you can check +the option labeled Remember Passwords, and then +choose a time period in minutes using the spinner labeled +Timeout. (You can either type a number between 5 +and 1200 minutes, or use the arrows on the spinner.) + +If the Remember passwords option has been selected, +kdesu will not ask you for a password for the length +of time specified, after you have given the password once. Keep in mind, +however, that this makes your workstation less secure. + +You should avoid selecting the Remember +passwords option if you are working in an insecure area, such as a +publicly accessible workstation. Also, note that choosing a shorter timeout may +be better if you are in a less secure environment. + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/performance/Makefile.am b/doc/kcontrol/performance/Makefile.am new file mode 100644 index 000000000..194fae838 --- /dev/null +++ b/doc/kcontrol/performance/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/performance diff --git a/doc/kcontrol/performance/index.docbook b/doc/kcontrol/performance/index.docbook new file mode 100644 index 000000000..b0acf0685 --- /dev/null +++ b/doc/kcontrol/performance/index.docbook @@ -0,0 +1,102 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2005-03-04 +3.4.0 + + +KDE +KControl +system performance +performance +preload + + + + +Performance Settings + +&kde;, is used on a wide variety of computers by a wide variety of users. Under the category of +performance, this dialog box allows each user to adjust options which may make the computer that &kde; is +installed on feel more responsive. + +This module is divided into two tabs. + + +&konqueror; performance options +&konqueror; instances +The first section of this dialog is labeled Minimize Memory Usage and has three options which determine maximum number of instances of &konqueror; that can be open on one machine at any one time. + +Do not confuse &konqueror; instances, with &konqueror; windows or tabs. The number of konqueror instances is determined by &kde; not by the user. You can think of instances as the hidden data of your &konqueror; windows and tabs. One &konqueror; instance can contain the data for multiple windows or tabs. Your choice on the following radio buttons does not limit the number of windows you can open at one time, but rather, how many instances of &konqueror; you can have open. +The reason the choices you make in this dialog box are important is evident when something goes wrong and &konqueror; is forced to close an instance. All &konqueror; windows associated with a &konqueror; instance must be closed immediatly (without time to save data or bookmark locations). Therefore, the more instances you can have open at one time, the less likely a problem in one instance will affect all of your work. Each instance requires more memory which can be a problem on systems with less system memory. + +Your options are: + + + +Never +There are no restraints. Any number of &konqueror; instances can be open at any one time. The advantage of this option is if any &konqueror; instance crashes the remaining will be unaffected. The disadvantage is that each &konqueror; instance uses more memory. + + + +For file browsing only (recommended) +If this option is selected, you can have as many as you want &konqueror; instances open that are browsing the web, but only one instance of &konqueror; for file management. + + + +Always (use with care) +If this option is selected, you can only have one instance of &konqueror; running at any one time. This saves system memory, but if your &konqueror; window crashes, all your browsing windows close immediatly without warning. This should only be used for seriously memory limited systems. + + + +Preloading +The subsection labeled Preloading also makes a tradeoff between memory and performance. + +Preloading refers to loading an instance of &konqueror; into memory before a user asks to start &konqueror;. The positive effect of this is that when a user asks &kde; to load &konqueror; the window appears instantly + because most of the application has been preloaded. The negative effect is that this instance of &konqueror; uses memory that +could be used by other programs. By default, when a user closes &konqueror;, &kde; does not close the instance. +This means that the next time a user wants &konqueror; loaded, it is nearly instantanous again. +The spinbox labeled Maximum number of instances kept preloaded: can be used to adjust the maximum number of preloaded instances. This option does not affect instances when they are loaded. It also does not limit the number of instances that can be used by active windows. It only affects the number of preloaded instances. +The checkbox labeled Preload an instance after &kde; startup does just what it says. It tells +&kde; to preload one instance of &konqueror; at the startup of &kde;. +This does extend the startup time for &kde;. +The final checkbox labeled Always try to have at least one preloaded instance signals to &kde; that you always want &kde; to have one preloaded, but not used, instance of &konqueror; available. This option will actually decrease performance on some machines (especially those with limited physical memory). + + +&kde; system performance options +Click on the tab labeled System. +Currently there is only one option labeled Disable system configuration startup check. + +When &kde; starts, it checks several directories for changes to configuration. Most of these changes relate to installation and uninstalling applications to the computer. This scan extends the startup time for &kde; and many times this scan is not needed as the configuration is current from the last time &kde; was started. When the configuration has changed &kde; uses this scan to update various datafiles to ensure a smooth user experience. +You are given the option to skip this initial scan during startup. &kde; developers strongly suggest you do not disable this scan because of the potential to introduce instability into your system. +If you do select this option: + +&kde; will wait to perform the scan until after &kde; has started. This scan will be performed after the desktop is loaded. +In the event of a crash, &kde; will not perform a backtrace because your problem may be related to the delayed scan. +Switch this option off if any application is crashing as a delayed scan may be responsible for the crash. + + + + + + + + + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/proxy/Makefile.am b/doc/kcontrol/proxy/Makefile.am new file mode 100644 index 000000000..ce9c3748a --- /dev/null +++ b/doc/kcontrol/proxy/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/proxy diff --git a/doc/kcontrol/proxy/index.docbook b/doc/kcontrol/proxy/index.docbook new file mode 100644 index 000000000..0a47cec36 --- /dev/null +++ b/doc/kcontrol/proxy/index.docbook @@ -0,0 +1,197 @@ + + + + +]> + +
+ + + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; + + + +2002-02-11 +3.00.00 + + +KDE +KControl +proxy +proxies + + + + +Proxies + + + +Introduction + +Proxies are programs running on a computer that acts a server on +the network you are connected to (whether by modem or other +means). These programs receive &HTTP; and &FTP; requests, retrieve the +relevant files from the internet, and pass them on to the client +computer that made the requests. + +When you have configured a proxy, &HTTP; and/or &FTP; requests +are re-routed through the computer that is acting as a proxy server. +However, you can also select specific hosts which should be contacted +directly, rather than through the proxy server. If you are on a local +network, for example, access to local hosts probably doesn't need to +go through a proxy server. + +You should only need to configure a proxy server if your network +administrator requires it (if you are a dial-up user, that would be +your internet service provider or ISP). Otherwise, +especially if you are feeling a bit confused about this proxy +business, but everything seems to be fine with your internet +connection, you don't need to change anything. + +Please note that using proxy servers is optional, but has the +benefit or advantage of giving you faster access to data on the +internet. + +If you are uncertain whether or not you need to use a proxy +server to connect to the internet, please consult with your internet +service provider's setup guide or your system administrator. + + + + + +Use + + + +Connect to the Internet directly + + +Select this option if you do not want to use a proxy server. + + + + +If you have decided to use a proxy, you have several methods to +configure the settings for it. + + + +Automatically detected script file + + +Select this option if you want the proxy setup configuration +script file to be automatically detected and downloaded. +This option only differs from the next choice in that it +does not require you to supply the location of +the configuration script file. Instead, it will be automatically +downloaded using Web Access Protocol Discovery +(WAPD). + +If you have a problem using this setup, please consult the +FAQ section at http://www.konqueror.org for +more information. + + + + +Specified script file + +Select this option if your proxy support is provided through a +script file located at a specific address. You can then enter the +address in the location text box, or use the folder +icon to browse to it. + + + + +Preset environment variables + +Some systems are setup with $HTTP_PROXY to allow +graphical as well as non-graphical applications to share the same +proxy configuration information. +If you know this applies to you, select this option and click on +the Setup... button to provide the environment +variable names used to set the address of the proxy server(s). + + + + +Manually specified settings + +Select this option, and click on the +Setup... to manually setup the location of the +proxy servers to be used. + +If you choose this option, another dialog will pop up. + +The complete addressing information for the proxy includes both +the internet address and a port number. You should enter these into +the relevant text boxes. The arrow button copies +the information from the HTTP line to the +FTP line, in order to help save some +typing. + +If there are hosts which you can connect to without going +through the proxy server, you can press Add to +add the names of these hosts, separated by in the text box labeled +No Proxy For:. For example, hosts that are on +your local network can probably be contacted directly. + +You can also choose Only use proxy for entries in this +list. + +Check this box to reverse the use of the exception list, &ie; +the proxy servers will only be used when the requested &URL; matches +one of the addresses listed here. + +This features is useful if all you need is a proxy to access a +few specific sites, for example, an internal intranet. If you have +more complex requirements you might want to use a configuration +script. + + + + + + + +<guilabel>Authorization</guilabel> + +Here you can choose between two types of authentication, if your +proxy requires it. You can have Prompt as +needed, the default, in which case &konqueror; will only +ask for a username or password if it needs to. + +The other option is Use automatic login. +Select this option if you have already set up a login entry for your +proxy server in the +$KDEDIR/share/config/kionetrc +file. + + + + +<guilabel>Options</guilabel> + + +Use persistent connections to proxy + +Use persistent connection to your proxy server. Keeps connection to proxy open, helps lower bandwidth/speed up connection. Enabling this option will require the proxy server's cooperation, if the proxy server does not support this, it will bring your internet to a stop. + + + + + + +&socks-kcontrol; + + + +
diff --git a/doc/kcontrol/proxy/socks.docbook b/doc/kcontrol/proxy/socks.docbook new file mode 100644 index 000000000..73c5e2ec6 --- /dev/null +++ b/doc/kcontrol/proxy/socks.docbook @@ -0,0 +1,56 @@ + + + +&Lauri.Watts; + + + + +SOCKS + +SOCKS is a protocol to execute proxy requests for a client. SOCKS +is capable of authentication and encryption of traffic, and is often +found in corporate settings, as opposed to home users. For more +information about SOCKS, see the NEC website + +With this module you can enable most of the network aware &kde; +applications to transparently use SOCKS. + +Setting up of a SOCKS client is outside the scope of this +document, and the differences between the commonly used ones are very +large. If you already have a working SOCKS implementation, allowing you +to use commandline clients (for example, if lynx or +ftp are already working) then you can simply check +the Enable SOCKS support checkbox. + +When this box is checked, several further options become available +to you. + +First, you should select which of the various SOCKS clients you +have installed on your computer. &kde; will attempt to find this out by +itself, if you choose Auto detect. If you know the +client you have, you could choose either NEC +Socks or Dante. If you have a +custom built SOCKS library to use, you can select Use custom +library and then enter the path to it in the +Path field. + +If you want &kde; to auto detect the SOCKS library in use, but you +suspect it isn't looking in the right places or you have installed it in +a non-standard location, then you can add further paths to be searched in +the bottom of this panel. Use the Add and +Remove to add or remove paths. + +At any time while filling in this module, you can press the +Test button, and &kde; will report immediately +with a message box to tell you if it could find and initialize SOCKS or +not. + +Changes made here will not affect any applications that are +already open. You will need to close and restart them before they are +able to connect via SOCKS. + + + + diff --git a/doc/kcontrol/screensaver/Makefile.am b/doc/kcontrol/screensaver/Makefile.am new file mode 100644 index 000000000..d9412ca98 --- /dev/null +++ b/doc/kcontrol/screensaver/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/screensaver diff --git a/doc/kcontrol/screensaver/index.docbook b/doc/kcontrol/screensaver/index.docbook new file mode 100644 index 000000000..67cb99411 --- /dev/null +++ b/doc/kcontrol/screensaver/index.docbook @@ -0,0 +1,203 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; + + + +2005-02-20 +3.4 + + +KDE +KControl +screensaver +screen saver + + + + + +Screen Saver + +Using this module, you can choose your screen saver, determine +how much time must pass before the screen saver is activated, and add +or remove password protection to your screen saver. + + +Choosing the screen saver, and configuring its options + +In the Settings box is a check box +labeled Start screen saver automatically. This +box must have a mark in it, or &kde; will not launch any screen saver +and it will not allow you to adjust the settings of your screen +saver. + +Along the left side is a list of all available screen savers. You can +select a screen saver by simply clicking on its name. Once +you have selected a screen saver, you will see a small preview on the +monitor on the right. + +The preview monitor will often show the screen saver +larger than it is when the screen saver is activated. This is done on +purpose, since many of the details of the screen savers would be +unintelligible if actually scaled down to such a small +size. + +Each screen saver has a different set of setup options. By +clicking on Setup..., a dialog box will appear with +all available options. As you adjust the options, the preview box in +the dialog box will show you what effect you will achieve with the +current settings. + +When you are done setting up your screen saver, click +OK. Clicking Cancel +will erase any changes you made in this dialog box, and return you to the +screen saver module. + +Clicking the About button will give you +the Copyright and Author information if you are interested. + +When you think you have all the options set the way you want, +simply click on Test to immediately start the +screen saver exactly as it will appear. + + + + +Setting the time, priority and passwords for screen +savers. + +Below the screensaver list is a check box to have the screen saver Start automatically check box, and a spin box which determines the period of inactivity before the screen saver should be started. You can enter any postive number of minutes in this box. + +Below that is a check box labeled Require password to +stop screen saver. If it is checked, when you click a key +or click a mouse button to end the screen saver and return to your +work, you must enter a password. The password used is the same +password you used to login to your machine. If there is no mark in +the check box, no password is required to return to your +desktop. + +Enable the check box Make aware of +power management if you don't want the screensaver to start +while you watch TV or movies on your monitor. + + + +Using a non-&kde; screen saver + +&kde; does not prevent another screen saver from working. To use a +different screen saver, such as xscreensaver, simply +disable the &kde; Screen Saver, and set up your other screen saver program +normally. + + + + +Removing and restoring a screen saver from your system + +If you want to remove a screen saver from the list in this +Control Center Module, you will need to rename a file on your +system. + +Working as a root user is a potentially dangerous +situation. While unlikely, it is entirely possible to do permanent +damage to your system while working as +root. + +Be very careful following the next set of +directions + +To delete a screen saver, type the following commands: + + +bash$ cd +$KDEDIR/share/applnk/System/ScreenSavers +bash$ ls + + +This will give you a list of files. You will notice +similarities between some of the file names and that of the screen saver you +want to remove. Simply rename the file of similarly named desktop +file to a name which does not end in +desktop. + +Example: + +bash$ cd +$KDEDIR/share/applnk/System/ScreenSavers +bash$ mv KSpace.desktop KSpace.backup + + +Will remove Space (GL) from the list + +You must close the &kcontrolcenter; entirely and restart it before +the changes will be seen. + +To restore the disabled screen saver, simply rename the file back to its +original name: + + +bash$ cd +$KDEDIR/share/applnk/System/ScreenSavers +bash$ mv KSpace.backup KSpace.desktop + + +Restart the &kcontrolcenter;, and the screen saver is back in the +list. + + + + +Advanced Settings: Grace period + +There is a five second grace period after the screen saver +begins before a password is required even if Require +password is checked. +Locking the desktop manually, by clicking the lock icon +in the &kde; panel, causes the password protection to engage immediately with +no grace period. +To alter the grace period setting, you need to manually edit the +configuration file. To do so: + +$ cd ~/.kde/share/config + + +Now, using a text editor (the example uses &kate;, the &kde; text editor), +load the kdesktoprc. + +$ kate kdesktoprc + + +Search through the file for the section labeled +[Screensaver]. +Look through all lines in the section for an entry entitled +LockGrace. +If the entry exists, you can edit the value of the entry. +[Screensaver] +LockGrace=3000 +The value of the entity represents the duration of the grace period +in milliseconds. An entry of 3000, would change the grace period to 3 seconds. +You can set the value of the entry to any number between zero (no grace period) +and 300000 (5 minutes). + +If the entry does not exist, simply add the entry to the end of the +section. + +Any changes to the configuration entry take effect +immediately. + + + + + +
diff --git a/doc/kcontrol/screenshot.png b/doc/kcontrol/screenshot.png new file mode 100644 index 000000000..f73f380cf Binary files /dev/null and b/doc/kcontrol/screenshot.png differ diff --git a/doc/kcontrol/smb/Makefile.am b/doc/kcontrol/smb/Makefile.am new file mode 100644 index 000000000..9f75f1d22 --- /dev/null +++ b/doc/kcontrol/smb/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/smb diff --git a/doc/kcontrol/smb/index.docbook b/doc/kcontrol/smb/index.docbook new file mode 100644 index 000000000..3d3a0ea6a --- /dev/null +++ b/doc/kcontrol/smb/index.docbook @@ -0,0 +1,106 @@ + + + +]> + +
+ + + +&Mike.McBride; &Mike.McBride.mail; +&Jost.Schenck; &Jost.Schenck.mail; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +Windows shares + + + +Windows Shares + + +Introduction + +In many small local area networks, the SMB +protocol is used to offer network services. Names like +&Windows; Network or &Windows; for Workgroups +Network or LanManager are often used as +well. Using SMB you can access so-called +shares (&ie; folders made available by the server) +as well as printers. + +&kde; comes with built-in support for the SMB +protocol. As &kde; is network-transparent that means you can access +SMB shares from everywhere you can access your +local files, for example in the &konqueror; file manager and in the +file dialog. To make use of this you should provide &kde; with some +information on your SMB network. But don't worry, +this is normally pretty simple as, for example, all the Windows +clients in your network need and have the same information. + + + + + +For the SMB protocol to work, it is +required to have Samba correctly +installed. If you have an NT domain controller, you will need at least +Samba version 2.0 or higher. If you want to +access &Windows; 2000 shares, you will need +Samba version 2.0.7 or higher. Older +versions may work too, but have not been tested. + + + + + + +Use + +Although there are a lot of insecure SMB +networks out there which allow access to anyone, in principle you have +to authenticate yourself to access the services of an +SMB server. By default, &kde; will use the data +entered in the Default user name and +Default password fields to authenticate itself on +SMB hosts. If you leave the field Default +user name empty, &kde; will try to access +SMB hosts without a username. If you leave the +default password empty, it will try without a password. If &kde; is +unsuccessful accessing the host using these settings, you will be +asked for a username and a password. + +While it makes things more comfortable if &kde; +stores your SMB password, this may be a security +problem. If you are using SMB in a security +conscious environment, you should not store your password here but +rather enter it anew every time you need to access an +SMB host. + +In the Workgroup field, you can enter your +workgroup name. If you don't know it, ask your system administrator +or have a look at other already configured machines in your network. +However, in most cases providing the workgroup name is not required, +so you probably can also leave this empty. + +If the option Show hidden shares is +checked, shares ending with a $ will be shown. + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/spellchecking/Makefile.am b/doc/kcontrol/spellchecking/Makefile.am new file mode 100644 index 000000000..7eb60d12b --- /dev/null +++ b/doc/kcontrol/spellchecking/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/spellchecking diff --git a/doc/kcontrol/spellchecking/index.docbook b/doc/kcontrol/spellchecking/index.docbook new file mode 100644 index 000000000..87279d41b --- /dev/null +++ b/doc/kcontrol/spellchecking/index.docbook @@ -0,0 +1,88 @@ + + + +]> + +
+ + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +2003-10-13 +3.2 + + +KDE +Spelling +dictionary + + + + + + +Spell Checker + +The configuration options available here are used by all &kde; +applications that use &kspell;, which is a front end to +ispell or aspell. + + + +Create root/affix combinations not in +dictionary + +Selecting this option allows the spell checker to register as correct combinations of root words with suffixes or prefixes even if the particular combination is not listed in its dictionary database of words. + + + + +Consider run-together words as spelling +errors +If this is selected, then words that appear in the +dictionary separately, but have been run together, are considered to be +spelling errors. For example, even though alarm and +clock might be in your dictionary, if +alarmclock is not, it will be flagged as a spelling +error. + + + +Dictionary: + +Choose from the available dictionaries, which one to use for +&kspell;. + + + + +Encoding: + +You should select the one that matches the character set you are +using. In some cases, dictionaries will support more than one encoding. +A dictionary might, for example, accept accented characters when +Latin1 is selected, but accept email-style +character combinations (like 'a for an accented +a) when 7-Bit-ASCII is +selected. Please see your dictionary's distribution for more +information. + + + + +Client: + +You can choose which of the installed client applications on your +system to use. For example, you can choose ispell. + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/useragent/Makefile.am b/doc/kcontrol/useragent/Makefile.am new file mode 100644 index 000000000..c7efa77d7 --- /dev/null +++ b/doc/kcontrol/useragent/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/useragent diff --git a/doc/kcontrol/useragent/index.docbook b/doc/kcontrol/useragent/index.docbook new file mode 100644 index 000000000..14be0fcf2 --- /dev/null +++ b/doc/kcontrol/useragent/index.docbook @@ -0,0 +1,117 @@ + + + +]> + +
+Browser Identification + + +&Krishna.Tateneni; &Krishna.Tateneni.mail; + + + +2003-10-12 +3.2 + + +KDE +KControl +user agent +browser +identification + + + + + +Browser Identification + + + +Introduction + +When &konqueror; connects to a web site to retrieve information, +some basic identifying information is sent to the web site in the form +of a User Agent header. + +Because of minor differences in the way that different web +browsers function, web sites that rely too much on a single browser may +sometimes not display as intended when viewed using another +browser. Some web sites are smart enough to examine the contents of the +user agent header and incorporate this information in the +HTML code so that the content is displayed correctly +regardless of the browser used. + +However, you may find that some web sites refuse to function +correctly unless you are using a browser recognized as +proper by that site. In these cases, you may find it +necessary to fool the web site by having &konqueror; report itself to be +another browser by means of the user agent header. + + + + +Use + +In this module you can configure the +type of browser that &konqueror; will report itself to be. You can +control this information by web site. Usually, the list box that is +labeled Site/Domain Specific Identification will be +empty, so that &konqueror; will always use its default useragent +string. + +You can disable the sending of a user agent entirely, by +unchecking the Send identification +checkbox. This may cause strange behavior on some sites, and may even +deny you access to some websites, so disable this with caution. + +To configure a new agent binding, press the +New... button. Type the name of the server or +a domain in the text box at the top of the dialog that pops up, which +is labeled When browsing the following +site. + +Note that you can not use the wildcard +character * in this text box. However, the string +kde.org will match all hosts in the domain +kde.org + +After typing the name of the server, type in the identifying +string in the next combo box, which is labeled Use the +following identity:, or choose a string from the list. If +you don't choose a string from the list, you will need to know what a +valid string from the browser looks like. For example, you could type +Mozilla/4.0 (compatible; MSIE 4.0). + +In the field labeled Alias (description) +you can enter a descriptive name for the configured binding, ⪚ +Netscape Navigator 4.75 on Linux for the +useragent string Mozilla/4.75 (X11; U; Linux 2.2.14 +i686). + +You can click on an existing entry in the Configured +agent bindings list, and then modify the contents of the +text boxes, followed by clicking Change.... + +The Delete button can be used to delete +the selected entry in the list of configured agent bindings. The +Delete All will remove all the configured user +agent strings. Click the Apply to take your +changes in effect. + +You can use the checkboxes at the top of the screen to build a +user agent that is uniquely yours, by choosing your own combination of +operating system name and version, platform, processor type, and +language. + +In all cases, the user agent that is being sent by default is +displayed in bold text at the top of the page. + + + + + +
\ No newline at end of file diff --git a/doc/kcontrol/windowmanagement/Makefile.am b/doc/kcontrol/windowmanagement/Makefile.am new file mode 100644 index 000000000..3e5215103 --- /dev/null +++ b/doc/kcontrol/windowmanagement/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/windowmanagement diff --git a/doc/kcontrol/windowmanagement/index.docbook b/doc/kcontrol/windowmanagement/index.docbook new file mode 100644 index 000000000..650b8d2aa --- /dev/null +++ b/doc/kcontrol/windowmanagement/index.docbook @@ -0,0 +1,63 @@ + + + +]> + +
+ + + +&Lauri.Watts; &Lauri.Watts.mail; + + + +2005-02-21 +3.4 + + +KDE +KControl +window settings +window placement +window size + + + +Window Specific Settings + +Here you can constomize window settings specifically only for +some windows. + + +Please note that this configuration will not take effect if you +do not use &kwin; as your window manager. If you do use a different +window manager, please refer to its documentation for how to customize +window behavior. + + +Many of the settings you can configure here are those you can +configure on a global basis in the Window Behavior +&kcontrol; module, however some of them are even more detailed. + +They encompass geometry, placement, whether a window should be +kept above or below others, focus stealing prevention, and translucency +settings. + +You can access this module in two ways: from the titlebar of the +application you wish to configure, or from &kcontrol;. If you +start it from within &kcontrol; you can use the +New... to create a window profile, and the +Detect button on the resulting dialog to +partially fill in the required information for the application +you wish to configure. + +You can also at any time Modify... or +Delete any stored settings profile, and +reorder the list. Reordering the list is a convenience to help you sort +the profiles, and has no effect on how they are applied. + + + +
\ No newline at end of file diff --git a/doc/kdcop/Makefile.am b/doc/kdcop/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kdcop/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kdcop/index.docbook b/doc/kdcop/index.docbook new file mode 100644 index 000000000..f92de1232 --- /dev/null +++ b/doc/kdcop/index.docbook @@ -0,0 +1,78 @@ + + + + + +]> + + + + +The &kdcop; Handbook + + + + + + + +
+ + + + + +&FDLNotice; + + + +2002-12-16 +0.00.00 + + + + + +&kdcop; is a program to help you browse available dcop functions. + + + + + +KDE +Kompare + + + + + Introduction +The documentation for &kappname; was not finished when &kde; was installed on +this computer. If you need help, please check The &kde; Website for updates, or by +submitting your question to The +&kde; User Mailing list. The &kde; +Team + +&underFDL; + + + +&documentation.index; + + + diff --git a/doc/kdebugdialog/Makefile.am b/doc/kdebugdialog/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kdebugdialog/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kdebugdialog/index.docbook b/doc/kdebugdialog/index.docbook new file mode 100644 index 000000000..72634224d --- /dev/null +++ b/doc/kdebugdialog/index.docbook @@ -0,0 +1,134 @@ + +KDebugDialog"> + + + + + +]> + + + +The &kdebugdialog; Handbook + + +&David.Faure; &David.Faure.mail; + + + +2001-02-13 +0.03.00 + + +This document describes &kdebugdialog;. + + + +KDE +KDebugdialog + + + + +What is KDebugDialog? + +It is a dialog box for managing diagnostic messages at runtime. + + +If you simply start kdebugdialog, you will +see a list of areas, that can be disabled or enabled. A +kdDebug(area) call in the code will show +something in the debug output only if the area is enabled. + +Note that kdWarning, kdError and kdFatal always appear, +they are NOT controlled by this setting. + + + +Area + +The areas which should only be output. Every message +that is not mentioned here will simply not be output (unless +this field remains empty, which is the default, and means that all +messages should be output). You can enter several areas +separated by commas here, and you can also use area ranges with +the syntax start-end. Thus a valid entry could be: +117,214-289,356-359,221. Do not use whitespaces. + + + + +If you start kdebugdialog +, then for every severity level you can +define separately what should be done with the diagnostic messages of +that level, and the same for each debug area. + +In full mode, first you should select the debug area you are +interested in from the drop down list at the top. + +You may independently set the output for various types of +messages: + + +Information +Warning +Error +Fatal Error + + +For each of these types, you can set the following: + + + +Output to: + +In this Combobox, you can choose where the messages +should be output. The choices are: File, Message +Box, Shell (meaning stderr) and +Syslog. Please do not direct fatal messages to syslog +unless you are the system administrator yourself. The default is +Message Box. + + + + +Filename: +This is only enabled when you have chosen +File as the output and provides the name of that file +(which is interpreted as relative to the current folder). The +default is kdebug.dbg. + + + + +Apart from this, you can also tick the checkbox Abort +on fatal errors. In this case, if a diagnostic message with +the severity level KDEBUG_FATAL is +output, the application aborts with a SIGABRT after outputting the +message. + +When you close the dialog by pressing OK, +your entries apply immediately and are saved in +kdebugrc. When you press +Cancel, your entries are discarded and the old +ones are restored. + +Credits to Kalle Dalheimer for the original version of +&kdebugdialog; + + + +&documentation.index; + + + + diff --git a/doc/kdeprint/Makefile.am b/doc/kdeprint/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kdeprint/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kdeprint/add-printer-wiz.docbook b/doc/kdeprint/add-printer-wiz.docbook new file mode 100644 index 000000000..6b6ada4ea --- /dev/null +++ b/doc/kdeprint/add-printer-wiz.docbook @@ -0,0 +1,290 @@ + +The <quote>Add Printer Wizard</quote> for &CUPS; + +Clicking on the leftmost icon on the toolbar + + in the upper part of the window starts the +Add Printer Wizard. + +This wizard steps you through various screens to install a new +printer. At present this Wizard works for &CUPS; and the +RLPR environment module. The number of steps depend +on the actual print-subsystem which is active and available to you on +your box. + + +Starting + +The welcome screen informs you that you can go back any time to +change a setting. + + +The &kdeprint; wizard introduction screen + + + + +The introduction screen of the printer wizard + + + + + +Backend Selection + +Choose the backend protocol that &CUPS; is supposed to +use with your new printer. There are: + + + +local printer (serial, parallel, USB) + + +remote LPD queue + + +SMB shared printer (&Windows;) + + +Network Printer (TCP, &HP; JetDirect, +AppSocket) + + +Network printer with &IPP; (&IPP;/HTTP) + + +File printer + + +serial fax /modem printer + + +Class of Printers + + + +If some choices are grayed out, they are not available. For +example, you may have no FAX backend software or no modem installed to +use it. + + +Choosing your Printer system + + + + +Choosing your Printer System + + + + + + +Direct Network Setting + +The contents of your next screen is dependent on your choice in +the previous screen. If you know the details, just type them in to +configure your network settings directly. + +In other cases the wizard can scan the network for you, to help you +decide which setting could be useful. + + +&kdeprint; wizard network scan + + + + +In the &kdeprint; wizard, you can enter network details +directly, or you can scan the network +automatically. + + + + + +Information Retrieval by Scanning the Network + +If you use one of the network connections (remote +LPD, SMB, remote &CUPS;, network +printer with &IPP;), you have an option for scanning the network. Be careful +when applying this; in some environments network scanning is considered +to be hostile and harmful! + +In the case of SMB, &kdeprint; will use the +Samba utilities nmblookup and +smbclient (which need to be installed for this to +work) to retrieve the information it presents in a tree +structure. + +In the case of &IPP; (Port 631) and TCP +Network/AppSocket (Port 9100) &kdeprint; will try to open the port and, +if successful, send an ipp-get-printer-attribute +request to the printer. For newer &HP; printers the latter usually +works, because they support both AppSocket and &IPP;. + +Some printers or manufacturers use other port numbers for direct +TCP/IP printing. You may need to look up which one to use. The +Settings button in the dialog lets you configure +your scan, including IP addresses, ports and +timeout to use. + +Once again: be careful not to be mistaken for an intruder on +your network, if you use the scanning technique. + + +&kdeprint; wizard network configuration dialog + + + + +In the &kdeprint; wizard, you can enter parameters to have the +wizard scan parts of your network. + + + + + +Printer Model Selection + +The hardest part is probably the Printer Model +Selection. In former years the situation was difficult, because +there were hardly any drivers to find. The difficulty now is there are too +many; though some of them are very good, many are quite broken. + +If you have a current database of available drivers +on your system, select the manufacturer in the left part of the window +first, then the device model in the right part. This split window shows +all &PPD;s found by &CUPS; in its standard repository of installable +&PPD;s. This repository normally is /usr/share/cups/model/. If you want your +driver to be found automatically by &CUPS; and &kdeprint;, place it in +there. + + + + + + +Driver Selection + +On the next screen you will see a description of the driver +selected previously. This description is extracted from the actual &PPD; +used. + + +For a real &PostScript; printer never try to +install a Foomatic or Gimp-Print &PPD;, +even if it is offered. You won't be happy with it. Instead find the +original &PPD; from the manufacturer, preferably the one written for +&Windows; NT and use it. + + +Some &Linux; distributions have supplied for &CUPS; every +possible combination of Ghostscript filters +and foomatic &PPD; files they could find on the net. +Many of these are quite useless; they were generated a year ago, when +the people at www.linuxprinting.org began +their first experiments with supplying third party &PPD;s for +&CUPS;. Although dubbed Alpha at the time, these +started to take on a life of their own and can now be found at various +places on the net, doing &CUPS; no favors. + +If you are not sure which ones to use go to: + + + +http://www.linuxprinting.org + + + + + +http://www.cups.org + + + + +And ask for help. At a later stage, a document detailing the +differences between the different driver and &PPD; models will appear at +http://kdeprint.sourceforge.net/ +Watch out for this! + +Via the Other... button you are able to +retrieve any &PPD; located somewhere on your available file +system. + + + + + +Printer Test and Finding the Right Settings + +Specify your first driver settings now. The most important one is the +default paper size. In many cases this is set to +Letter. If you live in an A4 +country and don't want your first test page to jam: now is the time to +prevent this. + +You are ready to start a test print. Hit the +Test button. + + + + + + + + +Finally: Baptizing Your New Printer + +The last screen lets you insert a name for your new +printer. + +The name must start with a letter and may contain numbers and +underscores with a maximum size of 128 characters. Conform to this if you +want to avoid erratic behavior of your &CUPS; daemon. The printer +names in &CUPS; are not case sensitive! This is a +requirement of &IPP;. So the names DANKA_infotec, Danka_Infotec and danka_infotec all represent the same +printer. + + + + + + +The Final Confirmation Screen + + + + + + + + diff --git a/doc/kdeprint/cr32-action-wizard.png b/doc/kdeprint/cr32-action-wizard.png new file mode 100644 index 000000000..b00db2499 Binary files /dev/null and b/doc/kdeprint/cr32-action-wizard.png differ diff --git a/doc/kdeprint/cups-config.docbook b/doc/kdeprint/cups-config.docbook new file mode 100644 index 000000000..ff286e632 --- /dev/null +++ b/doc/kdeprint/cups-config.docbook @@ -0,0 +1,2072 @@ + +Print Server Configuration: CUPS + +Start the print server configuration (now that you have chosen +&CUPS;, this is equivalent to the configuration of the &CUPS; daemon) by +clicking on the appropriate button. You can find it by moving the mouse +slowly over the buttons and reading the tooltips. It should be the 11th +from the left , or third from the right; its icon is a +wrench. + +The &CUPS; Server Configuration window pops up. It gives you a +structured view of all the settings that apply to the &CUPS; daemon. The +configuration file for that daemon is normally located in +/etc/cups/cupsd.conf. This is a plain +ASCII file with a syntax similar to the configuration +file of the Apache web server. It is a good +idea to create a backup copy, just in case something goes wrong with the +configuration through &kdeprint;/&CUPS; Server Configuration +dialogs: + +cp /etc/cups/cupsd.conf /etc/cups/cupsd.conf.bak + +As this graphical user interface to edit the configuration file is +such a new feature, you should have the second chance of resorting to +the original file. So back it up, please. + + +Quick Help + +One very nice feature is the Quick Help +available. If you click on the little question mark (What's +this?) on your window title bar, you'll see the cursor +changing its form. Now click on a cupsd +configuration setting field to find out what it means and what your +options are. In most cases you should understand the meaning +immediately, otherwise turn to the excellent &CUPS; documentation. (If +your &CUPS; Daemon is running, you have it online on your own host at +http://localhost:631/documentation.html. +If &CUPS; is not running, but installed on your system you could +find it in your own host's file system. The exact location depends on +your &OS;, but on &Linux; the default is /usr/share/doc/cups/ or + +/usr/share/doc/cups/documentation.html. + + + +Longer Help + +For the best, most detailed and most recent information you should +always refer to the original &CUPS; documentation. &CUPS; is, much like +&kde; in a rapid development process. There are constantly new features +being added. New features might for times be only configurable by +directly editing the configuration files. The &kdeprint; &GUI; might not +have caught up with &CUPS; development. + +Just in case you want to look at the original configuration files +of your &CUPS; system -- they are here: + + +These paths are based on the default installation. Your &OS; +may have installed them to a different prefix, for example, /usr/local/, but the hierarchy should +still match that shown below. + + + + +/etc/cups/ + +The folder with the configuration files + + + + +/etc/cups/cupsd.conf + +The configuration file for the &CUPS; daemon + + + + +/etc/cups/printers.conf + +The configuration file that contains the information about your +locally installed printers. + + + + +/etc/cups/ppd/ + +The folder with &PPD; files of your installed +printers. + + + + +The following links only work if your &CUPS; daemon is up and +running. To access all the original &CUPS; documentation, go +to: + + + + +http://localhost:631/documentation.html + +A page with all the links to the other documents. + + + + + +http://localhost:631/sam.html + +Direct access to the &CUPS; Software Administrator Manual +in HTML format. + + + + + +http://localhost:631/sam.pdf + +Direct access to the &CUPS; Software Administrator Manual in +PDF format. + + + + + +http://www.cups.org/documentation.html + +The latest on line documentation from the &CUPS; web +site. + + + +The following links give you access to the same files (probably +icons and graphics will be missing) even if your CUPS daemon is not up +and running. You need, however, CUPS installed on your system. (Some +distributions might place the files somewhere else -- you're on your +own then to find out where...) To access all the original CUPS +documentation, go to: + +This documentation is available even when the &CUPS; daemon is +not installed, although you may find images and icons are missing when +you view the HTML files. + +As noted above, the hierarchy below should be intact, but your +&OS; may have installed &CUPS; to a different location. + + + +/usr/share/doc/cups/documentation.html + +A page with all the links to the other documents. + + + + +/usr/share/doc/cups/sam.html + +Direct access to the &CUPS; Software Administrator Manual in +HTML format. + + + + +/usr/share/doc/cups/sam.pdf + +Direct access to the &CUPS; Software Administrator Manual in +PDF format. + + + + +There are a few WebSites and Newsgroups discussing &CUPS; (and +&Linux; Printing in General) and giving help to newbies at: + + + + +http://www.cups.org/newsgroups.php + +The &CUPS; website. + + + + + +http://www.linuxprinting.org/newsportal/ + +LinuxPrinting.org, the home of the Linuxprinting HOWTO and the +&Linux; Printer Database + + + + +And finally, there will be a WebSite for &kdeprint; and related +documentation, at +http://kdeprint.sourceforge.net/ + +In the next section I will step you through most of the +configuration options of &kdeprint; with &CUPS;. + + + +Explaining different elements of the &GUI; + + +Upper Window: View on Printers, both Real and Virtual + +This section is not yet complete + + + +Tree view, icon view and list view + + +The icons of the task bar + + +Different fonts for different printers + + +Different printer icons mean different things + + + + + + +Lower Window: Tabbed View of Details + +This section is not yet complete. + + + +The icons of the task bar + + +The Tabs + + +Changing printer settings + + + + + + + + + +Welcome to the &CUPS; Server Configuration + +This is the Welcome Screen for your server configuration +dialogs. Clicking onto one of the items of the tree view on left +side of the screen opens the appropriate part of the configuration +settings. + +Every setting has a default value. The defaults let &CUPS; +normally work as a fully functional client. The clients listen on +TCP/IP Port 631 for infos broadcast by &CUPS; servers on the +LAN. This information let the clients print +immediately after receiving them, without installing any driver or +configuring any printer on the clients. + +To configure a &CUPS; server (which is broadcasting its service +to the LAN) you need to change settings from the +defaults. + +The dialog to configure the &CUPS; server: welcome screen. + +CUPS server configuration dialog: welcome screen + + + + +The dialog to configure the &CUPS; server: welcome +screen +The dialog to configure the &CUPS; server: welcome +screen + + + +To select the default setting of any item just enable the +checkbox on the right side of the screen. To set an item to a +different value, disable the checkbox and then go on to do the setting +you want on the left side of the screen. + +The complete server configuration includes: + + + +Server +General Configuration + + +Server +Logging Configuration + + +Server +Folders and Path Definitions + + +Server +HTTP Configuration + + +Server +Encryption and Certificate Support +Configuration + + +Server +Miscellaneous Configuration + + +Network General Configuration + + +Network +Clients Configuration + + +Browsing +General Configuration + + +Browsing +Connection Configuration + + +Browsing +Masks Configuration + + +Browsing +Timeouts Configuration + + +Browsing +Relay Configuration + + +Security +Configuration + + + +Each of these configuration items will be described in the +following sections of the manual. + + + + +Server General Configuration + +The server general configuration is done on this screen. It +includes: + + +Server name +Administrators email +Server user +Server group +Remote user name + + +The tab window to configure the &CUPS; server general settings +lets you the change the default values. Click on the little question +mark and then on one of the fields to get a Quick Help +about the meaning of the setting. + +If you are unsure, leave alone and turn to the original &CUPS; +documentation first. If your &CUPS; daemon is already running, it is +readable from the &konqueror; by pointing it to &URL; +http://localhost:631/documentation.html. + +There, first make friends with the Software +Administrator Manual. Otherwise, for example, if the &CUPS; daemon is +not running, try looking in your local file system, by default at +/usr/share/doc/cups/ or +/usr/share/doc/cups/documentation.html. + + +&CUPS; server general configuration dialog: ServerName, AdminMail, +ServerUser, ServerGroup, RemoteUserName + + + + +The dialog to configure the &CUPS; server general settings: +ServerName, AdminMail, ServerUser, ServerGroup, RemoteUserName + + + + + + +Server Name + +The hostname of your server, as advertised to the world. By +default, &CUPS; will use the hostname of the system. To set the +default server usd by clients, see the +client.conf file. + + +For example, enter myhost.domain.com + + +This is the hostname that is reported to clients. Should you +ever encounter strange problems in accessing the server, put here its +IP address for troubleshooting. This way you +eliminate any potential name resolution problems; and you can more +easily nail the real problem down. + + + + +Administrators email + +This is the email address to send all complaints or problems +to. By default &CUPS; will use root@hostname. + + +For example, enter +root@myhost.com. + + + +Contrary to what the quickhelp suggests, it is also legal to +send an email full of praise and enthusiasm about &CUPS; and +&kdeprint; to the server administrator. + + + + + +Server User + +The user the server runs under. Normally this must be +lp, however you can +configure things for another user if needed. + + +The server must be initially run as root to support the default +IPP port of 631. It changes users whenever an +external program is run. + + + +Enter for example lp. + + +This is the &UNIX; user account for filters and +CGI programs to run under. CGI +programs are responsible for showing you the nice web administration +interface accessible via http://localhost:631/). + + +There is no need to set the User directive +to root, so never do this, +as it only involves dangers. Should anyone discover security +vulnerabilities in one of the used file filters, printer drivers or +CGI programs, he could remotely execute arbitrary +commands on your system with root user privileges. Always use an +unprivileged account for the server directive +User. + + + + + +Server group + +The group the server runs under. Normally this must be +sys, however you can +configure things for another group as needed. + + +Enter for example sys. + + + + + +Remote user name + +The name of the user assigned to unauthenticated accesses from +remote systems. By default remroot. + +This name will appear in log files and in queries about the job +owner &etc;, for all resources and locations of the &CUPS; server that +are configured to allow access without +authentication. Authenticated entries will carry the authenticated +names. + + + + + + +Server Logging Configuration + +The server logging configuration is done on this screen. It +includes: + + +Access log file setting +Error log file setting +Page log file setting +Log level setting +Max log file size +setting + + +This is an important screen for you. Should you ever encounter +problems: here is the place to set the Log level to +debug, restart the &CUPS; daemon and then look at the +Error log file defined here for entries that might give you an insight +to the trouble. + + +&CUPS; server configuration dialog: Server +logging + + + + +The dialog to configure the &CUPS; server: Server +logging + + + + + +Access log file + +This is where accesses to the server are logged. If this does +not start with a leading /, then it is assumed to +be relative to the server root. + +You can also use the special name syslog +to send the output to the syslog file or daemon. + + +Enter a path, for example +/var/log/cups/acces_log. + + +The format of this file is stored in the so-called Common +Log Format. This way you can use programs such as +Webalyzer or any other Web access reporting +tool to generate reports on the &CUPS; server activities. + +To include the server name in the file name use a +%s in the name. Example: +/var/log/cups/access_log-%s. + +kurt@transmeta:~ >tail /var/log/cups/access_log + +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST /printers/ HTTP/1.1" 200 109 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST /admin/ HTTP/1.1" 401 0 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST / HTTP/1.1" 200 210 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "GET /ppd/DANKA_P450.ppd HTTP/1.1" 200 51021 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST /jobs/ HTTP/1.1" 200 246 +10.160.16.45 - - [04/Aug/2001:20:11:39 +0100] "GET /printers/DANKA_P450 HTTP/1.0" 200 0 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST / HTTP/1.1" 200 80 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST / HTTP/1.1" 200 139 +10.160.16.45 - - [04/Aug/2001:20:11:40 +0100] "GET /cups.css HTTP/1.0" 200 198 +127.0.0.1 - - [04/Aug/2001:20:11:40 +0100] "POST / HTTP/1.1" 200 139 +10.160.16.45 - - [04/Aug/2001:20:11:39 +0100] "GET /printers/DANKA_P450 HTTP/1.0" 200 7319 +10.160.16.45 - - [04/Aug/2001:20:11:40 +0100] "GET /images/title-logo.gif HTTP/1.0" 200 5729 + + +You see a separate line for each single access, showing the +IP address of the accessing client, date and time +of access, method of access (POST or +GET), the requested ressource, the &HTTP; version +used by the client, status code and the number of transferred +bytes. Status code 200 means +successful-OK the 401 in +the above example was an unauthorized access +which was denied. For a detailed explanation of the log format go to +the &CUPS; Software +Administrator Manual. + + + + +Error log file + +If this does not start with a leading /, then +it is assumed to be relative to the server root. The default setting +is /var/log/cups/error_log. + +You can also use the special name syslog +to send the output to the syslog file or daemon. + + +Enter the path, for example +/var/log/cups/error_log. + + +The error log excerpt below shows you the part logged for printing the test page +with the default setting of Log level to +info. For an explanation of the Log +Level setting see further below. + +kurt@transmeta:~ > tail /var/log/cups/error_log + +I [04/Aug/2001:23:15:10 +0100] Job 213 queued on 'DANKA_P450' by 'root' +I [04/Aug/2001:23:15:10 +0100] Started filter /usr/lib/cups/filter/pstops (PID 18891) for job 213. +I [04/Aug/2001:23:15:10 +0100] Started backend /usr/lib/cups/backend/lpd (PID 18892) for job 213. + + + + + +Page log file + +If this does not start with a leading / then +it is assumed to be relative to the server root. The default is +/var/log/cups/page_log + +You can also use the special name syslog +to send the output to the syslog file or daemon. + + +Enter the path, for example +/var/log/cups/page_log. + +The page log file has a line for every single page of every job +printed. + + Here is what some entries look like: + +kurt@transmeta:~ > tail /var/log/cups/page_log + +GIMP_print_stp_HP kdetest 201 [03/Aug/2001:03:18:03 +0100] 4 1 +GIMP_print_stp_HP kdetest 201 [03/Aug/2001:03:18:03 +0100] 5 1 +GIMP_print_stp_HP kdetest 202 [03/Aug/2001:11:46:49 +0100] 1 1 +GIMP_print_stp_HP kdetest 203 [03/Aug/2001:11:46:54 +0100] 1 1 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 1 33 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 2 33 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 3 33 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 4 33 +DANKA_infotec_P450 root 205 [04/Aug/2001:19:12:34 +0100] 1 14 +DANKA_infotec_P450 root 206 [04/Aug/2001:19:15:20 +0100] 1 1 + + +In this excerpt of the file you find information on the name of +the printers (GIMP_print_stp_HP and DANKA_infotec_P450) used through this +server, the user names (kdetest, kurt and root), the job-IDs (201 +to 205), time of printing, page number inside the job +and the number of copies for the pages. For example, job-ID 204 had 4 +pages and 33 copies printed, job-ID 205 had 14 copies of just 1 page) +. + + +&CUPS; is dependent (for its calculation of the number of pages +in a job) on passing the &PostScript; through the +pstops filter. See the &kivio; Flowchart on the &CUPS; +filter architecture for an idea about were this filter fits into the +whole printing process). More, pstops depends for +the counting on a DSC conforming +(DSC is Document Structuring Conventions, a +standard defined by Adobe) to be sent by the client. In most cases +this is working. + +However, this page accounting does not work for any +raw printer queues (as those, by definition, don't use +any filtering on the &CUPS; host and are by-passing +pstops.) Every job going through a +raw queue is counted as a 1-page-job (with possibly +multiple copies). This is especially true for all Jobs send from +&Microsoft; &Windows; clients via Samba to +the &CUPS; server, as those jobs are already arriving in the correct +format for the printer, because the clients use the original printer +driver. + + + +I am still looking for someone who will write a nice &CUPS; page +log analysing tool. It should generate a report with a graphical +output similar to the Webalizer's access +log reports. This way you could have nice statistics to be used for +accounting about usage of printers, load dependent on daytime or +weekday, users &etc; Anyone? + + + + + +Log level + +This setting controls the number of messages logged to the error +log file. It can be one of the following: + + + +debug2 + +Log everything. + + + + +debug + +Log almost everything. + + + + +info + +Log all requests and state changes. + + + + +warn + +Log errors and warnings. + + + + +error + +Log only errors. + + + + +none + +Log nothing. + + + + + +If you need to troubleshoot (or if you want to study the inner +workings of &CUPS;), set the log level to debug or debug2. Then the +error_log will have a lot more entries (not just errors, but also +informational entries). + +You can use this to watch live what &CUPS; is +doing when you send a print job. In a &konsole; type: + +kurt@transmeta:~ >tail 100 /var/log/cups/error_log + +This will give you the last 100 lines ( +100) of the file onto the screen and a +realtime update ()of what is +happening. The following listing shows the printing of a test page +(some pieces have been cut off for space reasons... Try it yourself if +you need more info): + + +I [04/Aug/2001:23:15:12 +0100] Job 214 queued on 'DANKA_P450' by 'root' +D [04/Aug/2001:23:15:12 +0100] StartJob(214, 08426fe0) +D [04/Aug/2001:23:15:12 +0100] StartJob() id = 214, file = 0/1 +D [04/Aug/2001:23:15:12 +0100] job-sheets=none,none +D [04/Aug/2001:23:15:12 +0100] banner_page = 0 +D [04/Aug/2001:23:15:12 +0100] StartJob: argv = "DANKA_P450","214","root","KDE Print Test", +[....] +D [04/Aug/2001:23:15:12 +0100] StartJob: envp = "PATH=/usr/lib/cups/filter:/bin:/usr/bin", [....] +D [04/Aug/2001:23:15:12 +0100] StartJob: statusfds = 5, 6 +D [04/Aug/2001:23:15:12 +0100] StartJob: filterfds[1] = 7, -1 +D [04/Aug/2001:23:15:12 +0100] StartJob: filter = "/usr/lib/cups/filter/pstops" +D [04/Aug/2001:23:15:12 +0100] StartJob: filterfds[0] = 8, 9 +D [04/Aug/2001:23:15:12 +0100] start_process("/usr/lib/cups/filter/pstops", [....] +I [04/Aug/2001:23:15:12 +0100] Started filter /usr/lib/cups/filter/pstops (PID 18991) for job 214. +D [04/Aug/2001:23:15:12 +0100] StartJob: backend = "/usr/lib/cups/backend/lpd" +D [04/Aug/2001:23:15:12 +0100] StartJob: filterfds[1] = -1, 7 +D [04/Aug/2001:23:15:12 +0100] start_process("/usr/lib/cups/backend/lpd", [....] +I [04/Aug/2001:23:15:12 +0100] Started backend /usr/lib/cups/backend/lpd (PID 18992) for job 214. +D [04/Aug/2001:23:15:12 +0100] Page = 595x842; 15,16 to 580,833 [....] + +The lines tagged D at the beginning are debug +level entries, the ones tagged I are there in +info level. + + + + +Max log file size + + +Controls the maximum size of each log file before they are +rotated. Defaults to 1048576 (1 Mb). Set this to 0 to disable log +rotation. + + +Enter an size in bytes, for example 1048576 + + + + + + + + +Server Folders Configuration + +The dialog to configure the &CUPS; server. Different +folders are to be set here. Normally you don't need to change +anything in this section. In case you play around with fancy +(TrueType, &PostScript; or other) fonts on your system, this qis the +place to do the settings for using those fonts when printing. Server +folder settings include: + + + +Executables: where to find the server +executables + + +Configuration: where to find the server +configuration files + + +Data: where to find the server data +files + + +Temporary files: where to put the server +temporary print files + + +Temporary Requests: where to find the +server + + +Font Path: where to find the +server fonts + + + +&CUPS; server configuration dialog: &HTTP; configuration + + + + +The dialog to configure the &CUPS; server: &HTTP; configuration + + + + + +Executables + +The root folder for the scheduler executables. By default +this is /usr/lib/cups (or +/usr/lib32/cups on IRIX +6.5) + + + + +Configuration + +The root folder for the scheduler. By default, /etc/cups. +On the authors SuSE system, this is /usr/share/doc/cups. It contains all the +HTML or PDF documentation for +&CUPS; which is available through the Web interface at +http://localhost:631/documentation.html + + + + +Data + +The root folder for the &CUPS; data files. By default this +is /usr/share/cups +It contains such things as banners, charsets, data, drivers, +fonts, and pstoraster templates. + + + + +Temporary files + +The folder to put temporary files in. This folder must be +writable by the user defined on the previous screen. This defaults to +either /var/spool/cups/tmp or +the value of the TMPDIR environment variable. + + + + +Temporary Requests + +The folder where request files are stored. By default this +is /var/spool/cups + + + + +Font path + +The place to configure the &CUPS; server for handling your fancy +fonts (TrueType or &PostScript;). &CUPS; will look here for fonts to +embed in printfiles. This currently only affects the +pstoraster filter, and the default is /usr/share/cups/fonts. + +To specify more than one folder, list them with double colons as +separator. Do it like this: + + +/path/to/first/fontdir/:/path/to/second/fontdir/:/path/to/last/fontdir/ + + +For the Font path directive to work as intended, the application +that wants to print needs to: + + + +Either correctly reference its desired fonts in the header of the +generated &PostScript; + + +Or embed the font into the &PostScript; file. + + + +Referencing the font by name leaves it up +to the RIP and print device to respect and actually +use it. RIP or printer can +only use the desired font, if it is available on the system. + + In the case of a &PostScript; printer, this needs to be a +printer-resident font. If the printers doesn't have this font, it will +try and replace it by an adequately similar font. + +In the case of a non &PostScript; printer, this is done by +&CUPS; and its RIP-ing filtering system. &CUPS; +will use the font path directive to grab the correct font when +RIP-ing the &PostScript; in the +pstoraster filter. + +In the case of a &PostScript; output device, &CUPS; is just +spooling the file (actually, it is passing it through the +pstops filter for accounting or n-up purposes), not +working on it. Therefore, if you print to a +&PostScript; printer it is solely the printer's responsibility to use +the font asked for. It can't, if the font is neither loaded into the +printer nor embedded in the &PostScript;. + + + + + + + +Server <acronym>HTTP</acronym> +Configuration + +The dialog to configure the &CUPS; server &HTTP; settings +is shown here. +&CUPS; server &HTTP; settings are the following ones: + +the Document folder +the Default Language +the Default Charset + + + +Dialog to configure the &CUPS; server &HTTP; settings + + + + + +Dialog to configure the &CUPS; server &HTTP; settings + + + + + + +Document folder + +The root folder for &HTTP; documents that are served. By +default the compiled in folder, /usr/share/cups/doc + + + + +Default Language + +The default language, if not specified by the browser. If not +specified, the current locale is used. + +Use the two letter locale codes, for example +en or de. + + + + + + +Default charset + +The default character set to use. If not specified, this +defaults to UTF-8. This can also be overridden directly in the +HTML documents. + + + + + + +<guilabel>Server encryption support configuration</guilabel> + +This is the dialog to configure the &CUPS; server security +settings. The server encryption support settings are these: + + +Server certificate: the file to +read containing the server's certificate +Server key: the file to read containing the server's +key + + +&CUPS; server configuration dialog: security overview + + + + +The dialog to configure the &CUPS; server: security settings + + + + + +Server certificate + +The file to read containing the server's certificate. Defaults +to /etc/cups/ssl/server.crt. + + + + +Server key + +The file to read containing the server's key. Defaults to +/etc/cups/ssl/server.key + + + + + + + +Server Miscellaneous Configuration + +The dialog to configure the &CUPS; server miscellaneous settings +is shown here. The following server settings are done through this +screen: + + +Preserve job history: whether to +preserve a job history for later re-view +Preserve job files: whether to +preserve fully RIP-ed job files for later +re-print +Printcap file: setting the name +of and the path to a printcap file +RIP Cache: setting the size of +the RIP cache in memory +Filter Limit: defining a filter +limit + + + +Dialog to configure the &CUPS; server miscellaneous settings + + + + +Dialog to configure the &CUPS; server miscellaneous +settings + + + + + +Preserve job history (after completion) + +Whether or not to preserve the job history after a job is +completed, canceled, or stopped. The default is yes + + + + +Preserve job file (after completion) + +Whether or not to preserve the job files after a job is +completed, canceled, or stopped. The default is no. + + + + +Printcap file + +The name of the printcap file. The default is no filename. +Leave this blank, to disable printcap file generation. +The printcap setting is only needed to satisfy older +applications in need of such a file. + + + + +RIP cache + +The amount of memory that each RIP should use +to cache bitmaps. The value can be any real number, followed by +k for kilobytes, m for megabytes, +gfor gigabytes, or t for tiles, where +one tile is 256 x 256 pixels. The default value is 8m. + + + + +Filter limit + +Sets the maximum cost of all job filters that can be run at the +same time. A limit of 0 means no limit. A typical job may need a +filter limit of at least 200. Limits less than the minimum required +by a job force a single job to be printed at any time. The default +limit is 0 (unlimited). + + + + + + +Network General Configuration + +The dialog to configure the &CUPS; server network settings is +shown here. It includes: + + +Look for hostname on IP +addresses +Port +Max request size +Timeout + + + +Dialog to configure the &CUPS; server network settings + + + + +Dialog to configure the &CUPS; server network +settings + + + + +Look for hostname on IP addresses + +Whether or not to do lookups on IP addresses +to get a fully-qualified hostname. This defaults to off, for +performance reasons. + + + + +Port + +Enter here Ports and addresses that the server will listen to. +The default port 631 is reserved for the Internet Printing Protocol, +and is what we use here. +You can have multiple entries, to listen to more than one port +or address, or to restrict access. + +Unfortunately, most web browsers don't support +TLS or &HTTP; upgrades for encryption. If you want +to support web-based encryption, you'll probably need to listen on +port 443, the HTTPS port. + +Use the Add and +Remove buttons to add and remove entries from +the list. + +You can enter ports on their own, ⪚ +631, or hostnames with ports, ⪚ +myhost:80 or 1.2.3.4:631. + + + + + +Max request size + +Controls the maximum size of &HTTP; requests and print files. +The default setting is 0, which disables this feature. + + + + +Timeout + +The timeout (in seconds) before requests time out. The default +is 300 seconds. + + + + + + + +Network Clients Configuration + +The dialog to configure the &CUPS; network client settings is +shown here. It includes: + + +Accept "Keep Alive" +requests +KeepAliveTimeout: +MaxClients: + + +dialog to configure the &CUPS; network client settings + + + + +Dialog to configure the &CUPS; network client settings + + + + + +Accept "Keep Alive" requests + +Whether or not to support the Keep-Alive connection option. The +default is on. + + + + +Keep alive timeout + +The timeout (in seconds) before Keep-Alive connections are +automatically closed. The default is 60 seconds. + + + + +Max number of clients + +Controls the maximum number of simultaneous clients that will be +handled. Defaults to 100. + + + + + + + +Browsing General Configuration + +The dialog to configure the &CUPS; browsing general settings +is shown here. It includes: + + +Enable browsing +Use short names when +possible +Use implicit +classes + + + + +Dialog to configure the &CUPS; browsing general +settings + + + + +Dialog to configure the &CUPS; browsing general +settings + + + + + +Enable browsing + +Whether or not to broadcast printer information to other &CUPS; +servers. Enabled by default. + + + + +Use short names when possible + +Whether or not to use short names for remote +printers when possible (⪚ printer instead of printer@host). Enabled by +default. + + + + +Use implicit classes + +Whether or not to use implicit classes. +Printer classes can be specified explicitly, in the +classes.conf file, implicitly based upon the +printers available on the LAN, or both. +When Implicit classes are enabled, printers on the +LAN with the same name (⪚ Acme-LaserPrint-1000) will be put into +a class with the same name. This allows you to setup multiple +redundant queues on a LAN without a lot of +administrative difficulties. If a user sends a job to Acme-LaserPrint-1000, the job will go to +the first available queue. +This option is enabled by default. + + + + + + +Browsing Connection Configuration + +The dialog to configure the &CUPS; server browsing connection is +shown here. Browsing connection settings include: + + +Broadcast addresses: The +(UDP) broadcast address to transmit printer +information to +Broadcast Port: The port number +to use for broadcasting +Poll addresses: The address(es) +to poll for information about printers on servers that might not +broadcast (or whose broadcasts might not reach your +LAN due to routers in between). + + + +Dialog to configure the &CUPS; server browsing +connection + + + + +Dialog to configure the &CUPS; server browsing +connection + + + + + +Broadcast addresses + +After pressing the Add button, you will +see the following dialog to enter a new value for outgoing +broadcasting browse packets. It is the same kind of dialog as for +adding other &CUPS; server addresses to be polled for printer +information. + + +Dialog to enter a new value for broadcasting browse +packets to + + + + +Dialog to enter a new value for broadcasting browse packets +to + + + +This option specifies a broadcast address to be used. By +default, browsing information is broadcast to all active +interfaces. + + +&HP-UX; 10.20 and earlier do not properly handle broadcast +unless you have a Class A, B, C or D netmask (&ie;, there is no +CIDR support). + + + + + +Broadcast port + +The port used for UDP broadcasts. By default +this is the IPP port; if you change this, you need +to do it on all servers. Only one BrowsePort is recognized. + + + + +Poll addresses + +Poll the named server(s) for printers. + + + + + + +Browsing Masks Configuration + +The dialog to configure the &CUPS; server allowed and/or denied browse +packets from other servers is shown here. + + +Browse allow: +Browse deny: +Browse order: + + + +Dialog to configure the &CUPS; server allowed and/or +denied browse packets from other servers + + + + +Dialog to configure the &CUPS; server allowed and/or denied +browse packets from other servers + + + + + +Add Browse Address dialog + +The dialog to enter a new value for the address of another +&CUPS; server to accept browse packets from is shown here. It is opened +by clicking on the Add... button beside the +field named Browse Allow:. It is the same dialog +as for adding denied broadcast sending +addresses. + +The dialog to enter a new value for the address of another +&CUPS; server to accept browse packets from is shown here. + + +Dialog to enter a new value for the address of another +&CUPS; server to accept browse packets from + + + + +Dialog to enter a new value for the address of another &CUPS; +server to accept browse packets from + + + + + + +Browse allow and Browse +deny + +Browse allow specifies an address mask to +allow for incoming browser packets. The default is to allow packets +from all addresses. +Browse deny specifies an address mask to +deny for incoming browser packets. The default is to deny packets +from no addresses. +Both Browse allow and Browse +deny accept the following notations for addresses: + + + + +All + + +None + + +*.domain.com + + +.domain.com + + +host.domain.com + + +nnn.* + + +nnn.nnn.* + + +nnn.nnn.nnn.* + + +nnn.nnn.nnn.nnn + + +nnn.nnn.nnn.nnn/mmm + + +nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm + + + + +The hostname/domain name restrictions will only work if you have +turned hostname lookups on! + + + + +Browse order + +Specifies the order of the allow/deny comparisons. + + + + + + + +Browsing Timeouts Configuration + +The dialog to configure the &CUPS; server browse timeout settings +is shown here. Browse timeout settings include: + +Browse Interval +Browse Timeout + + +Dialog to configure the &CUPS; server browse timeout +settings + + + + +dialog to configure the &CUPS; server browse timeout +settings + + + + + +Browse interval + +The time between browsing updates in seconds. The default is 30 +seconds. +Note that browsing information is sent whenever a printer's +state changes as well, so this represents the maximum time between +updates. +Set this to 0 to disable outgoing broadcasts so your local +printers are not advertised, but you can still see printers on other +hosts. + + + + +Browse timeouts + +The timeout (in seconds) for network printers - if we don't get +an update within this time, the printer will be removed from the +printer list. +This number definitely should not be less than the browse +interval period, for obvious reasons. Defaults to 300 seconds. + + + + + + +Browsing Relay Configuration + +The dialog to configure the &CUPS; server as a browsing relay is +shown here. Browsing relay settings include: + + +Browser packets relay + + + +Dialog to configure the &CUPS; server as a browsing +relay + + + + +Dialog to configure the &CUPS; server as a browsing +relay + + + + + +Add Browse Relay dialog + +The dialog to enter a new value for an address pair to define +browsing relaying between a &CUPS; server and a network is shown +here. + + +The dialog to enter a new value for an address pair to +define browsing relaying between a &CUPS; server and a +network + + + + +The dialog to enter a new value for an address pair to define +browsing relaying between a &CUPS; server and a +network + + + + + + +Browser packets relay + +Relay browser packets from one address or network to +another. + + + + + + + +Security Configuration + +The dialog to configure the &CUPS; server security settings for +any of the defined server locations is shown here. It contains the +following settings, which may be defined separately for any valid +resource (or location) of the &CUPS; server: + + +System Group: +Access Permissions: +Auth Type: +Auth Class: +Auth Group Name: +Encryption: +Allow: +Deny: +Order: + + +Valid resources (or locations) of the &CUPS; server are: + + +Server Root Location: / +Server Administration Location: /admin +All printers on the server: /printers +Any individual printer on the server: +⪚ /printers/infotec_P320 +All printer classes on the server: /classes: +Any individual printer class on the server: +⪚ /classes/all_infotecs_P320_or_P450 + + + +Dialog to configure the &CUPS; server security settings +for any of the defined server locations + + + + +dialog to configure the &CUPS; server security settings for +any of the defined server locations + + + + + +For all locations that are not defined separately the setting of +the location above it is valid. + +For example, you have a printer named infotec_P450 with no set security +options. Then the security of the location /printers will take the responsibility +for this printer as it is a sub-location of/printers. If, in turn there is no +security set for /printers, +then the security for / (the +general security) of the server takes responsibility. Either you have +set this for your purpose or the compiled-in default value takes +over. + + + + +SystemGroup + +The group name for System or printer administration +access. The default varies depending on the operating system, but +will be sys, system or root (checked for in that order). + + + + +Access Permissions + +Access permissions for each folder served by the scheduler. +Locations are relative to the document root. + + + + +Authorization Type + +The authorization to use: + + + +None + +Perform no authentication. + + + +Basic + +Perform authentication using the &HTTP; Basic method. + + + +Digest + +Perform authentication using the &HTTP; Digest method. + + + + + +Local certificate authentication can be substituted by the +client for Basic or Digest, when connecting to the localhost +interface. + + + + + +Authorization Class + +The authorization class. Currently only +Anonymous, User, System +(valid user belonging to the group set as system group), and +group (valid user belonging to the specified group) are +supported. + + + + +Authorization Group Name + +The group name for Group authorization + + + + +Encryption + +Whether or not to use encryption. This depends on having the +OpenSSL linked into the &CUPS; library and +scheduler. +Possible values are: + + +Always + +Always use encryption (SSL) + + + +Never + +Never use encryption. + + + +Required + +Use TLS encryption upgrade. + + + +IfRequested + +Use encryption if the server requests it. + + + + + + + +Allow + +Allows access from the specified hostname, domain, +IP address or network. Possible values are: + + + + +All + + +None + + +*.domain.com + + +.domain.com + + +host.domain.com + + +nnn.* + + +nnn.nnn.* + + +nnn.nnn.nnn.* + + +nnn.nnn.nnn.nnn + + +nnn.nnn.nnn.nnn/mmm + + +nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm + + + + +The host and domain address require that you enable hostname +lookups, as described earlier. + + + + +Deny + +Denies access from the specified hostname, domain, +IP address or network. Possible values are: + + + +All + + +None + + +*.domain.com + + +.domain.com + + +host.domain.com + + +nnn.* + + +nnn.nnn.* + + +nnn.nnn.nnn.* + + +nnn.nnn.nnn.nnn + + +nnn.nnn.nnn.nnn/mmm + + +nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm + + + +The host and domain address require that you enable hostname +lookups, as described earlier. + + + + +Order + +The order of the allow and deny processing. + + + + + + +Example: How To Define The Security For All Printers + +The dialog to configure the &CUPS; server security settings is +discussed here. We use the example to add security definitions other +than the default ones for the resource named all printers. For the &CUPS; web server, +this is the location you access through +http://localhost:631/printers/ or (remotely) through +http://cups.server.name:631/printers/ + +The first screenshot shows the general location for this +setting. Select Add or +Modify a resource for which you want to decide +about its security settings. + + +Dialog to configure the &CUPS; server security +settings + + + +Dialog to configure the &CUPS; server security +settings + + + +This dialog is to add a new resource. It looks similar if you +want to modify an already existing resource. Here are the general +options: + + +Dialog to add a new resource. + + + + +Dialog to add a new resource. + + + +.This is the second part or the dialog is to add a new +ressource. It looks similar if you want to modify an already existing +resource. Here you define the actual access masks for the resource in +question. + + +Dialog to add a new resource. + + + + +Dialog to add a new resource. + + + +Resource dialog + + + + +Resource dialog + + + + +Resource dialog + + + + +Resource dialog + + + + +Resource dialog + + + + +Resource dialog + + + + +Resource dialog + + + + +Resource dialog + + + + + + diff --git a/doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png b/doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png new file mode 100644 index 000000000..9f5a73d39 Binary files /dev/null and b/doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png differ diff --git a/doc/kdeprint/cupsaddprinterwizard1.png b/doc/kdeprint/cupsaddprinterwizard1.png new file mode 100644 index 000000000..cf20e087c Binary files /dev/null and b/doc/kdeprint/cupsaddprinterwizard1.png differ diff --git a/doc/kdeprint/cupsaddprinterwizard2_backendselection.png b/doc/kdeprint/cupsaddprinterwizard2_backendselection.png new file mode 100644 index 000000000..3e4b2f126 Binary files /dev/null and b/doc/kdeprint/cupsaddprinterwizard2_backendselection.png differ diff --git a/doc/kdeprint/cupsaddprinterwizard3_networkscan.png b/doc/kdeprint/cupsaddprinterwizard3_networkscan.png new file mode 100644 index 000000000..160834ee9 Binary files /dev/null and b/doc/kdeprint/cupsaddprinterwizard3_networkscan.png differ diff --git a/doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png b/doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png new file mode 100644 index 000000000..aa6cd87f1 Binary files /dev/null and b/doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png differ diff --git a/doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png b/doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png new file mode 100644 index 000000000..7fff7de52 Binary files /dev/null and b/doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png differ diff --git a/doc/kdeprint/cupsoptions.docbook b/doc/kdeprint/cupsoptions.docbook new file mode 100644 index 000000000..dc886d21c --- /dev/null +++ b/doc/kdeprint/cupsoptions.docbook @@ -0,0 +1,602 @@ + +&CUPS; options presently not available through &kcontrol; + +This chapter gives you some hints about further configuration +possibilities which may not be available through the &kdeprint; &GUI; +interface to &CUPS;. + + +Overview of provided features + +All of the most often used features and functions &CUPS; provides +are supported in &kdeprint;. + + + +Printer management is supported: add, remove, modify, configure, +test, disable, enable ... + + +Job management is supported: cancel, hold, release, move to +different printer + + +Print options: for full control as provided by &CUPS;. + + + + + + +Where to find help when using &CUPS; + +A lot of information about the inner workings of &CUPS; is +available through the web interface, which &CUPS; will always +support. It works with any browser (yes, even text-based ones). Just go +to http://localhost:631/ for +a start. There you find a link to locally available &CUPS; documentation +in HTML and PDF if you are new to +&CUPS;. + +&CUPS; is accessible through other means than &kdeprint;: +commandline and browser are two native &CUPS; interfaces. The many +commandline utilities add up to the most complete control you have on +&CUPS;. The web interface is only a subset of all available +configuration or control options. + +This is also true for &kdeprint;. Generally, as &CUPS; develops, +most new features will first be implemented through the commandline. Be +sure to check the latest versions of the man pages for &CUPS; to stay +up-to-date with new features after you install a new version. + + +Depending on your update method for &CUPS;, your active +configuration file might not have been re-placed by a new one; thus your +new, more capable &CUPS;-daemon might not have been told by the old +configuration file about the new features to use. + + +A complete list of available files and man pages should always be +in the &CUPS; Software Administrator Manual (http://localhost:631/sam.html#FILES. +In the &konqueror; &URL;/location field, type +man:/lpadmin and +man:/cupsd.conf to find out about the most +important command and configuration file. You knew already about +&konqueror;'s nice abilities to show you the traditional &UNIX; man +pages, didn't you? Read this. From there you find more interesting +hints and links to other man pages and documentation. + + +How to find &CUPS; related man pages + +Here is a way to find out which &CUPS; related man pages there +are on your system: + +kurt@transmeta:~ > apropos cups + +cups-calibrate (8)- ESP Printer Calibration Tool +lpstat (1) - print cups status information +cups-lpd (8) - receive print jobs + report printer status to lpd clients +classes.conf (5) - class configuration file for cups +backend (1) - cups backend transmission interfaces +filter (1) - cups file conversion filter interfaces +cups-polld (8) - cups printer polling daemon +mime.types (5) - mime type description file for cups +cupsd (8) - common unix printing system daemon +lpadmin (8) - configure cups printers and classes +cupsd.conf (5) - server configuration file for cups +mime.convs (5) - mime type conversion file for cups +printers.conf (5) - printer configuration file for cups +mime.convs (5) - mime type conversion file for cups +cups-polld (8) - cups printer polling daemon +lpstat (1) - print cups status information +backend (1) - cups backend transmission interfaces +mime.types (5) - mime type description file for cups +cupsd (8) - common unix printing system daemon +lpadmin (8) - configure cups printers and classes +printers.conf (5) - printer configuration file for cups +cupsd.conf (5) - server configuration file for cups +filter (1) - cups file conversion filter interfaces + + + + + +Outside &kdeprint;: Hints & Tips Tricks with &CUPS; on the +Commandline + +Here are a few examples of options that are presently only +available if you use the commandline. + + +Allowing or denying printer access for certain users + +When installing (or modifying) a printer through the command line, +you can either deny or allow the usage of that printer to certain +users: + +lpadmin HeidelbergDigimaster9110 lpd:/10.160.16.99/mqueue allow:kurt,sylvi,hansjoerg /home/kurt/PPDs/DVHV.ppd + +will allow the usage of this (believe me: very nice and also very +professional) printer to only the three mentioned users and at the same +time deny it to all others. If another user wants to print on the +DigiMaster via this &CUPS; server, he will receive an error message +along the lines client-error-not-possible. + +lpadmin HeidelbergDigimaster9110 lpd:/10.160.16.99/mqueue deny:tackat,boss,waba /home/kurt/PPDs/DVHV.ppd + +will deny the usage of this same printer to the three mentioned +users and at the same time allow it to all others. If +denied user wants to print on the DigiMaster via this +&CUPS; server, he will receive an error message along the lines +client-error-not-possible. + + +Only one of the two options may be used at one time; at present +there is no support to have a similar option in a per-group based +way. This will be implemented in the future. + + + + +Imposing Quotas for certain printers + +Sometimes you want to impose quotas for certain printers. With +quotas you can set upper limits for the number of pages or the amount of +data to be printed over a certain period to a certain printer. + +Quotas can be set with the option when +installing a printer with the lpadmin command, or +afterwards for an already existing printer. Following are some +guidelines (which are missing at the time of writing in the, official +&CUPS; documentation): + + + +With &CUPS; you may have pagecount- and filesize-based quotas for +individual printers. + + + +Quotas are calculated for each user individually (so a single set +of limits applies to all users for the printer concerned). + + + +Quotas include banner pages (if those are used). + + + +This means: you can limit every user to 20 pages per day on an +expensive printer, but you cannot limit every user except Kurt or root. + + + +There are , +, and +options to give when setting up a printer. + + + + sets a time interval for quota +computing (intervals are determined in seconds; so a day is +60x60x24=86.400, a week is 60x60x24x7=604,800, and a month is +60x60x24x30=2.592.000 seconds.) + + + +For quotas to be enforced, the time-period +plus at least one job-limit must be set to +non-zero. + + + +The default value of 0 for specifies +that there is no limit. + + + +The default value of 0 for +specifies that there is no limit. + + + +The default value of 0 for +specifies that the limits apply to all jobs that have been printed by a +user that are still known to the system. + + + + +Working Examples: + +Working, as both, time-period plus one or +both job-limits are defined + +lpadmin danka_infotec_4850 job-quota-period=604800 job-k-limit=1024 + +This sets a limit of a file size of 1 MB (in total) for each user +of existing printer danka_infotec_4850 during one week. + +lpadmin danka_infotec_4105 job-quota-period=604800 job-page-limit=100 + +This sets a limit of 100 pages (in total) for each user of +existing printer danka_infotec_4105 during one week. + +lpadmin danka_infotec_P450 job-quota-period=604800 job-k-limit=1024 job-page-limit=100 + +This sets a combined limit of 1 MB (in total) and 100 pages (in +total) for each user of existing printer danka_infotec_P450 during one +week. Whichever limit is reached first will take effect. + + + + +Not working examples + +NOT working, as only +one, time-period or job-limit +is defined) + +lpadmin danka_infotec_P320 job-quota-period=604800 + +lpadmin danka_infotec_FullColor job-page-limit=100 + +lpadmin danka_infotec_HiSpeed job-k-limit=1024 + + + + +Related Error Messages + +Once a user reaches his quota limit, he'll get a +client-error-not-possible message, if he wants to +print. + + + + + + +Installing a <quote>raw</quote> printer + +There are different ways to define a raw +printer. One comfortable one is to use the lpadmin +command. Just don't define a &PPD; file to be used for that printer and +it will be a raw one: + +lpadmin Raw_Danka_infotec lpd://10.160.16.137/PORT1 + +Raw printer queues are those which don't touch the print file to +transform it to a different file format. You need this for example when +printing from &Windows; clients via Samba through a &CUPS; server to a +PCL printer: in this case the &Windows; side printer +driver would generate the finished print file format for the target +printer and filtering it through &CUPS; filters would only harm the +purpose. Under certain circumstances (if you want to make sure that the +file goes to the printer unfiltered by &CUPS;) the +lpadmin without a &PPD; comes in +handy. + + + + + +Troubleshooting &CUPS; in &kdeprint; + +This section of the &kdeprint; Handbook will live from the +readers' feedback. Here is just a small beginning. + + +Error Messages + + + + +What does the error +client-error-bad-request mean? + + +The user sent a file to the &CUPS; which the server could not +process. You get this also upon sending an empty +file. + + + + + +And client-error-not-possible? + + +User is either not allowed to print to a certain printer or has +achieved his quota (based on file size and/or page number) + + + + + +How about client-error-not-found? + + +The user tried to access a nonexistent resource on the &CUPS; +server, such as trying to print a nonexistent file, or one that you are +denied permission to read. + + + + + + + + +Questions and Answers + + + + +Why can't I re-start my jobs? + + +To be able to re-start your completed jobs from the +web interface, you need a setting in the +/etc/cups/cupsd.conf file: set +PreserveJobFiles True. + + + + + +How do I get rid of the long list of completed jobs in the web +interface? + + +TODO + + + + + +How does page accounting work? + + +&CUPS; does the print accounting by passing nearly +every job through the pstops filter. This one does, +amongst other things, the page counting. Output of this filter there may +be piped into other filters (like pstoraster --> rastertopcl) or sent to +the printer directly (if it is a &PostScript; printer). + +In any case, this works for network, parallel, serial or +USB printers the same. For pstops to work, it needs +DSC, Document Structuring Convention compliant +&PostScript; (or near-equivalent) as input. So it calculates the pages +during filtering on the print server and writes info about every single +page (what time, which user, which job-ID and -name, which printer, how +many copies of which pages of the document, how many kilo-bytes?) into +/var/log/cups/page_log. + +By the way: on my personal wishlist is a hack of +webalizer to read and analyze the page_log and give a +similar output. Anyone? + +However, it is not giving correct results in +the following cases: + + + +The printer jams and maybe therefor throw away the job (real live +experience; or maybe throwing away the job because of problems with the +data format) + + +Jobs printed as raw are always counted as size of 1 +page (and maybe multiple copies). + + + +Therefore the page accounting of &CUPS; is only +an approximation (in many cases an excellent or at least good one, in +others a quite poor one). The only reliable print count is the one +done by the internal printer counter. (Because this is the one you pay +for, if you are on a click price or similar.) Some, by +far not most, printers can be queried remotely for that information +via SNMP (Simple Network Management Protocol). That +means, in a bigger network with many different printers there +is just no completely reliable and accurate page +accounting tool! + + + + + +Why doesn't page-accounting work with &Windows; clients? + + +From &Windows; clients jobs nearly always need to be sent as +raw. Why? If &CUPS; works as a print server for &Windows; +clients using the original native &Windows; driver for the target print +device, this guarantees the correct formatting of the job on the clients +already; therefor the server should not touch it and print +raw; therefor no filtering is started (and this is not +even possible as the input from the clients is not &PostScript; as +pstops expects; hence no page-count other than the default +1. + + + + + +How do I get a list of available options for a given printer or a +&PPD; file? + + +See the man page for the lpoptions command. You +may investigate a &CUPS;-enabled box about any option of its available +printers. There is no need to have the printer installed locally. As +long as the printer is available locally (through the &CUPS; +printer browsing feature), it will also work +remote. + +To query for a printers' option typing +lpoptions +HitachiDDP70MicroPress + will give a long listing of all +available options as read from the &PPD; file for the given +Hitachi-Printer (in my case installed on remote server +transmeta). Remote server Transmeta and its &CUPS; daemon as well +as the localhost's &CUPS; daemon need to be up and running for this to +succeed. + + + + + +How do I read the listing retrieved by the +lpoptions command? + + + +You know that for &PostScript; printer manufacturers it is +legal to define their own internal names and procedures +even for standard &PostScript; options. As long as the driver is able to +retrieve the option from the &PPD; and show it to the user in a way that +he understands it everything is OK. But what do you +do, if you want to use some obscure printer options on the command line? +How do you find out its exact syntax? + +Let's take an example. Looking at Hitachi's DDP70 printer and how +it implements duplex printing is revealing somehow. How do you tell how +to print double sided? duplex or Duplex? Or another name altogether?. + +lpoptions transmeta Hitachi_DDP70_ClusterPrintingSystem | grep uplex + +This leads to the output + +TR-Duplex/Duplex: False *True + +This is to be interpreted like follows: + + + +The name of the investigated option is +; + + +Behind the slash you see the translation of the option, as it +should be shown in a &GUI; or Web interface +(Duplex); + + +The option may take one of the two values +False or True; + + +The present setting is True to be +recognized by the marking with a star *. + + + +To override the present default setting (duplex) and print a job +in simplex, you need to use the following command: + +lpr Hitachi_DDP70_ClusterPrintingSystem TR-Duplex=False /path/to/your/printjob + + + + + +How do I get a nicely formatted listing of available options for a +given printer or &PPD;? + + +Use the lphelp command which may be installed +on your system locally. There is not yet a man page for +lphelp. + +lphelp infotecP450 + +This lists the available options for the named printer. It is +nicely formatted and does explain every available option and how to use +it. You can query different printers' options at once: + +lphelp infotec7410color DANKA_fullcolor_D2000 HP_ColorLaserJet8550 + +It also works for &PPD; files. Just specify the path to the +&PPD;: + +lphelp /home/kurt/PPDs/HP-ColorLaserJet8550.ppd + + + + + + +Solving Problems + +No system is perfect. Here are some commonly seen traps people +have fallen into. + + + + +My printer named 3-lp-duplex shows erratic +behavior. What's wrong? + + +The printer names used in &CUPS; shall start with a letter and may +contain up to 128 letters, numbers or underscores. Using dashes may lead +to problems. Speaking about naming: printer names in &CUPS; are not case +sensitive. So a printer named Best_of_Danka will be the same as +best_of_danka or BEST_OF_DANKA. (This is a requirement of +&IPP;, which &CUPS; is fully compliant with). + + + + + +Why do I get Unable to connect to SAMBA host: +Success with my printer shares from &Windows; accessed via +Samba? + + +Are the rights on the remote &Windows; box set correctly for you? +Are you actually allowed to print on the &Windows; shared +printer? + + + + + +My files for printer lp +sometimes mysteriously disappear and two days later I am told they got +printed on a printer three floors below my office. What is going on? + + +Believe me, it is very unlikely that your printer is the only one +with the name lp. Maybe +&CUPS; is playing a trick on you. As you might have the setting +ImplicitClasses On activated, &CUPS; tries to stuff all +printers it sees on the network into a Class name lp. All +jobs destined to lp are sent to this class and the first available +member prints it. So if you had this nice fellow (who listened closely +when you raved about &CUPS; and &kdeprint;) install &CUPS; and poke +around the system...get the idea? + +Take my advice: choose a unique name for any network printer! +(Mind you, the one on your parallel port also turns out to be a network +printer for the rest of the world if you don't take care of your +settings). + + + + + + diff --git a/doc/kdeprint/cupsserverconfig_browse_relay_add_button.png b/doc/kdeprint/cupsserverconfig_browse_relay_add_button.png new file mode 100644 index 000000000..391cf06ee Binary files /dev/null and b/doc/kdeprint/cupsserverconfig_browse_relay_add_button.png differ diff --git a/doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png b/doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png new file mode 100644 index 000000000..f5767faad Binary files /dev/null and b/doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png differ diff --git a/doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png b/doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png new file mode 100644 index 000000000..3775f4d2a Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png differ diff --git a/doc/kdeprint/cupsserverconfiguration11_browsingconnections.png b/doc/kdeprint/cupsserverconfiguration11_browsingconnections.png new file mode 100644 index 000000000..d3ca6971f Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration11_browsingconnections.png differ diff --git a/doc/kdeprint/cupsserverconfiguration11_browsingmasks.png b/doc/kdeprint/cupsserverconfiguration11_browsingmasks.png new file mode 100644 index 000000000..a662dd117 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration11_browsingmasks.png differ diff --git a/doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png b/doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png new file mode 100644 index 000000000..d9e9528d6 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png differ diff --git a/doc/kdeprint/cupsserverconfiguration14_browsingrelay.png b/doc/kdeprint/cupsserverconfiguration14_browsingrelay.png new file mode 100644 index 000000000..0030b4d7c Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration14_browsingrelay.png differ diff --git a/doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png new file mode 100644 index 000000000..fab7bc65b Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png differ diff --git a/doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png new file mode 100644 index 000000000..2cc4bf8ae Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png differ diff --git a/doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png new file mode 100644 index 000000000..cfd09e543 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png differ diff --git a/doc/kdeprint/cupsserverconfiguration1_welcome.png b/doc/kdeprint/cupsserverconfiguration1_welcome.png new file mode 100644 index 000000000..50bd9ba3a Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration1_welcome.png differ diff --git a/doc/kdeprint/cupsserverconfiguration2_general.png b/doc/kdeprint/cupsserverconfiguration2_general.png new file mode 100644 index 000000000..c8e8b01c0 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration2_general.png differ diff --git a/doc/kdeprint/cupsserverconfiguration3_logging.png b/doc/kdeprint/cupsserverconfiguration3_logging.png new file mode 100644 index 000000000..300c31943 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration3_logging.png differ diff --git a/doc/kdeprint/cupsserverconfiguration4_directories.png b/doc/kdeprint/cupsserverconfiguration4_directories.png new file mode 100644 index 000000000..e55ab35fc Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration4_directories.png differ diff --git a/doc/kdeprint/cupsserverconfiguration5_HTTP.png b/doc/kdeprint/cupsserverconfiguration5_HTTP.png new file mode 100644 index 000000000..3e46eb17b Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration5_HTTP.png differ diff --git a/doc/kdeprint/cupsserverconfiguration6_encryption.png b/doc/kdeprint/cupsserverconfiguration6_encryption.png new file mode 100644 index 000000000..aca75adf0 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration6_encryption.png differ diff --git a/doc/kdeprint/cupsserverconfiguration7_miscellanious.png b/doc/kdeprint/cupsserverconfiguration7_miscellanious.png new file mode 100644 index 000000000..6a30d103e Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration7_miscellanious.png differ diff --git a/doc/kdeprint/cupsserverconfiguration8_networkgeneral.png b/doc/kdeprint/cupsserverconfiguration8_networkgeneral.png new file mode 100644 index 000000000..a0a40da20 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration8_networkgeneral.png differ diff --git a/doc/kdeprint/cupsserverconfiguration9_networkclients.png b/doc/kdeprint/cupsserverconfiguration9_networkclients.png new file mode 100644 index 000000000..89b30dfe9 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration9_networkclients.png differ diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png b/doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png new file mode 100644 index 000000000..147830184 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png differ diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png new file mode 100644 index 000000000..295a0970a Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png differ diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png new file mode 100644 index 000000000..3b3b4eb04 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png differ diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png b/doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png new file mode 100644 index 000000000..1b388a6cb Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png differ diff --git a/doc/kdeprint/cupsserverconfiguration_securityoverview.png b/doc/kdeprint/cupsserverconfiguration_securityoverview.png new file mode 100644 index 000000000..bed1d3df6 Binary files /dev/null and b/doc/kdeprint/cupsserverconfiguration_securityoverview.png differ diff --git a/doc/kdeprint/extensions.docbook b/doc/kdeprint/extensions.docbook new file mode 100644 index 000000000..3995272c2 --- /dev/null +++ b/doc/kdeprint/extensions.docbook @@ -0,0 +1,57 @@ + +&kdeprint; Extensions To All Print Subsystems + + +<quote>Virtual</quote> Printers + + +The <quote>Fax</quote> Printer + +To be written + + + + +The <quote>File</quote> Printer + +To be written + + + + +The <quote><acronym>PDF</acronym></quote> Printer + +To be written + + + + + + +<quote>External</quote> Filters + + +The <command>enscript</command> Filter for Text Files + +To be written + + + + +The <quote>n-up</quote> Filter for Any File + +To be written + + + + +Three different <quote>Make Pamphlet</quote> Filters for +&PostScript; Files + +To be written + + + + + + diff --git a/doc/kdeprint/external-command.docbook b/doc/kdeprint/external-command.docbook new file mode 100644 index 000000000..1a1135d7c --- /dev/null +++ b/doc/kdeprint/external-command.docbook @@ -0,0 +1,25 @@ + +Module For External Print Command (&Netscape;-like) + +This module allows the print command to be specified completely +(&Netscape;-like). An edit line is added in the print dialog for that +purpose. Can be used in many cases, for example with a self-made print +program. + + +Overview of provided features + + + +Printer management: not supported + + +Job management: not supported. + + +Print options: basic control, depending on your knowledge of the +print command + + + + diff --git a/doc/kdeprint/final-word.docbook b/doc/kdeprint/final-word.docbook new file mode 100644 index 000000000..ed2ae029a --- /dev/null +++ b/doc/kdeprint/final-word.docbook @@ -0,0 +1,117 @@ + +Final word from the Author + + +Who am I, what is my business? + + +My employer is Danka Deutschland GmbH, a leading and +manufacturer-independent provider of professional and hi-speed digital +printing systems, black-and-white as well as color. Danka provides +hardware, software, service, maintenance, consumables and customized +solutions for the products in its portfolio. I work there as a +System Engineer. Amongst the brands Danka offers are Heidelberg +(formerly Kodak), Canon, &Hewlett-Packard;, Hitachi, Infotec and +EfI. + + +My acquaintance with &Linux; and the Free Software community is not +too old. When I started to play around with &Linux; at the beginning +of 1999, my deepest disappointment was the poor support for +printing. True, I made all our machines spit out simplex prints -- but +what about duplex? What about punching the output? How to make sorting +work? Or stapling, cover sheets and all the other beautiful finishing +options our engines offer to customers? No way -- at least for me as a +non-geek! + + +I began a search on the Internet for a solution. Fortunately not +much later, in May 1999, Mike Sweet, principal developer of &CUPS;, +announced the first Beta release of this superb piece of printing +software. After trying it briefly, I knew this was it! + + +Next thing I attempted: to make &Linux; distributions interested in +this new stuff. Believe me -- it was more than tenacious! They seemed +to think they already had the best thing they could get in +printing. One reason probably was that they (and many &Linux; +developers) never had to think about how to best support a printer +duplexer -- because one had never come near their own +desks... + + +Finally, my attempts to make some &Linux; print publications +interested in &CUPS; backfired on me - one editor +squeezed me into writing a series on the subject myself. And this is +how some people started to give me the nickname CUPS +Evangelist. I will not get rid of this nick anytime soon, now +that even the &kde; people wedged me into their timeframe of +releases. Oh, boy... + +Anyway, &CUPS; is now making its way around the world and it +might well become a triumphal one: I am a little bit proud to have +supported and contributed to this from near the beginning. + +It should encourage you: even if some more experienced &Linux; +users than you are skeptical about it, and even if your programming +skills are next to zero (like mine) - there are a lot of tasks and +jobs and ideas, and talent that you can contribute to the Free Software +community. Not least within the &kde; project... ;-) + + + + + +Credits + +I'd like to thank... + + +Mike Sweet for developing &CUPS; in the first place + + +Jean-Eric Cuendet for starting kups +and qtcups, the predecessors of +&kdeprint; + + +Michael Goffioul for doing all the hard work recently + + +Martin Konold for thinking twice + + +Sven Guckes for teaching me a few things about the art of survival +on the terminal (just in case &kde; is not there ;-) ) + + +...too numerous others to mention who also let me snatch bits +and bytes of knowledge +off them + + + and last, but not least: Tom Schwaller for encouraging me +to get into documentation +writing + + + + + + +Caveats + +&kdeprint; has been developed on a system using &CUPS; 1.1.6. +&kdeprint; has been tested on other versions of &CUPS; and so +far no incompatibilities are known. By the time of writing +this Handbook, &CUPS; 1.1.9 is out with a few new features +not yet supported by &kdeprint;. Of course you are able to +access these features, but you will need to bypass &kdeprint; +and use the &CUPS; command-line tools or edit configuration +files manually. &kdeprint;'s development will go on and this +Handbook strives to always be the best available user documentation +resource for it. + + + + diff --git a/doc/kdeprint/getting-started.docbook b/doc/kdeprint/getting-started.docbook new file mode 100644 index 000000000..cb360379f --- /dev/null +++ b/doc/kdeprint/getting-started.docbook @@ -0,0 +1,143 @@ + +Getting Started + +This chapter of the &kdeprint; Handbook will walk you through most +of the configuration or selection options of &kdeprint;. It will mainly +deal with &CUPS; in this version, as the author is most familiar with +it, and also because &kdeprint; started off with supporting &CUPS; +best. Later versions of the &kdeprint; software and editions of this +handbook will support and explore other printing +systems more closely. + + +Selecting Your Print Subsystem + +You need to define your print subsystem, before you are able to +install any printer with the &kdeprint; framework. There are two areas +where you can define this: either in &kcontrol; (The Printing +Manager section), or directly and on the fly +from the print dialog. + +Navigate to K Menu +Preferences System +Printing Manager. At the bottom +you can see a button that lets you select which printing subsystem you +want to use. In &kde; 2.2 you can choose from the following +alternatives: + + + +&CUPS; (Common &UNIX; Printing System) + + +Print through an external program (generic) + + +LPR (Standard BSD Print +System) + + +Generic &UNIX; LPD print system (the +default) + + +RLPR environment (print to remote +LPD servers from the command line) + + + +Of course, the chosen system must be installed, and up and running on +your box prior to your selection, or before it takes effect. + + + +On it's first startup, &kdeprint; will try an autodetection. This +only works for: + + + +&CUPS;, as it is checking first for a running &CUPS; daemon + + +LPD, as it is checking for a running +LPD daemon, plus a printcap +file. + + + + + +The system you choose must be installed on your system prior to +your selection. The author's personal recommendation is +&CUPS;. + +Once autodetected, chosen, or changed, the active print +subsystem will take effect for all &kde; applications. Different +users may have different print subsystems in use, if those do exist on +the computer and are compliant with each other. Their settings are +stored in the kdeprintrc. This file is unique to +every user, and is normally installed in +$HOME/.kde/share/config/kdeprintrc. + + +This file is not intended to be directly editable, and all +available options can be set from the &kdeprint; &GUI;. + + +You may even select a different printer subsystem, on the fly, from +the &kprinter; dialog box. + + + + +Working with the Printing Manager + +Once you have chosen your preferred and installed print subsystem, +you are ready to investigate, configure administer and work with this +system through the &kdeprint; framework. + +Navigate to K Menu +Preferences System +Printing Manager. In the right +part of the window you will see at least 4 printers predefined. These +are the virtual or special purpose printers, explained in section . You will probably see a toolbar with 13 icons at the +top of the window, and at least 4 tabs in the lower half of the window, +labeled Information, Jobs, +Properties and +Instances. + + + + + + + + + + + + + + + + + + diff --git a/doc/kdeprint/highlights.docbook b/doc/kdeprint/highlights.docbook new file mode 100644 index 000000000..85e0e348f --- /dev/null +++ b/doc/kdeprint/highlights.docbook @@ -0,0 +1,518 @@ + +&kdeprint;'s Highlights + +The new &kdeprint; system includes more than one highlight. +Having worked in an environment in the past that is not exactly +sophisticated, as far as printing is concerned, take a look at some of +the benefits that come with &kdeprint; + + +The <quote>Add Printer</quote> Wizard + +&kdeprint; has an Add Printer Wizard. The Add +Printer Wizard helps you with adding and configuring a new printer. Of +course, you may do this manually as well. + +&kdeprint; helps you discover printers. It is able +to scan the environment for available devices and queues. This works for +network connections using TCP (AppSocket, +aka &HP; JetDirect, or IPP) or +SMB/Samba (shared &Windows;) printers +and partially for directly attached printers over parallel, serial, or +USB connections. + + +A screenshot of the new Add Printer +Wizard + + + + + +Here's a screenshot of the Add Printer Wizard +(this one is not very exciting yet; but...) + + + + +The wizard makes the installation and handling of the drivers +a snap. Selecting, configuring and testing should be easy +as never before on any &Linux;-like system. + + + + + + + +Full Print Job Control + +The Print Job Viewer is automatically started by &kprinter;. It +may be docked into the &kde; panel (in the system tray). The Print Job +Viewer allows full job management, if supported by the print +subsystem. + +You can: + + + +Hold and release jobs, + + +Move pending jobs to another printer, + + +Cancel pending or processing jobs. + + + +A screenshot of the &kdeprint; PrintJob Viewer shows the information +you get: Job-ID, target printer, job name, job owner, job status and job +size. In the next &kdeprint; release you will also see information about the +number of pages (as &CUPS; calculates it; see chapter on page accounting +for more information about its merits and limitations). + + +A screenshot of the &kdeprint; PrintJob Viewer + + + + + +Here's a screenshot of the &kdeprint; PrintJob Viewer. + +A screenshot of the &kdeprint; PrintJob +Viewer. + + + +An alternative way to looking at the same information (and having the +same amount of control is through the + + &kcontrolcenter; selecting +SystemPrinting +Manager. If you don't see the +Printer Information, +right click on the window +background and select View Printer +Information. Then go to the Jobs tab +to see this: + + + + + + + + +Here's a screenshot of the &kdeprint; PrintJob Viewer. + + + + + + + +Modules for different print subsystems + +&kdeprint; uses different modules to realize the interface to the +possible print subsystems. Not all the modules are yet developed fully, +but you will have basic printing functionality with: + + + +LPD (BSD style) + + +LPRng (&RedHat;, if you just use it's +BSD style subset), + + +RLPR (a command-line LPR +utility, which doesn't need a printcap file. + + +external print commands (&Netscape; like). + + + +Most importantly, full support for &CUPS; is already there. +Modules for other print subsystems, such as PLP, +PPR and PDQ may be available +later. + +&kdeprint; makes &kde; much more flexible. It gives freedom of +choice to &kde; 2.2 users. To use different available print subsystems, +these must, of course, be installed independently from &kde;. In +former versions, users were stuck with the old LPD +style print subsystems. Now they can even use &CUPS;. In the future, +there will be easy integration of new subsystems, as they +appear on the scene. + + + + +More &kdeprint; <quote>Goodies</quote> +Benefitting all Print SubSystems. + +Some specific features of &kdeprint; depend on the chosen print +subsystem. This dependency might exist because those features are only +implemented there; remember, &kdeprint; is an intermediate layer between +&kde; applications, and the print subsystem, but it's no replacement for +any print subsystem by itself. Such dependency may exist for another +reason: that &kdeprint; has not yet implemented an interface to all the +features of all the subsystems. + +Other features include benefits from &kdeprint; that are +independent of the chosen print subsystem, and are available with all of +them. At present there are special or +virtual printers, and some generic +pre-filters. + + + +Print Preview + +From the Print Dialog, you can select to look at a preview. For +this, the print file is passed through filters which make it suitable for +displaying on screen using &kghostview;. + + + + +Special Printers + +Amongst these additional &kdeprint; features are a few +special or virtual printers: + +These special printers may: + + + +Print to PDF + +Convert your document into a PDF file with the +help of an external program. + + + + +Print to email + +Send your document as an email attached PDF +file. + + + + +Print to PS file + +Save your document as a &PostScript; file. + + + + +Print to Fax + +Send it through an available backend, such as +Hylafax as a fax. + + + + + +These special printers appear in the user print +dialog just like normal printers. They are entirely +configurable on a per-user basis. + + + + + +Generic Pre-Filtering + +&kdeprint; provides you with a framework to define and configure +your own pre-filters. These pre-filters may take effect +before they are passed to your print subsystem for +further processing, but after the (&PostScript;, +plain text or other) print files have been generated by your +application. + +There are a few useful filters already predefined. These +are: + + + +The multiple pages per sheet filter, + + + +the enscript text filter, + + + +and three filters to help print pamphlets. + + + +You may create your own filters based on any third party program +that is able to process &PostScript;, plain text or image files, and output +any one of those formats. + +These filters are configured through XML files. +This makes an extension of the concept very easy for experienced developers, +but end-user configuration is also done through an intuitive graphical +user interface. So, fear not, you don't need to learn +XML because of &kdeprint;! + + + +Multiple Pages Per Sheet Filter + +This is a predefined filter that installs with &kdeprint;. It +allows you to create a modified &PostScript; output, from &PostScript; +input, that prints 1, 2, or 4 logical pages on a single sheet of +paper. + + + + +Enscript Text Filter + +This is a predefined filter that installs with &kdeprint;. It +allows you to create &PostScript; output from any text file input, that +includes syntax highlighting for program listings, pretty-printing, and +nice configurable page frames and headers. + + + + +Pamphlet Printing Filters + +If your printer is able to produce duplex output, using either +one-pass or two-pass technology, you may be able to use one, or a +combination, of the pamphlet filters. + +For duplexing printers, make sure you use the duplex option that +turns the output along the short paper edge. Folding the +printed paper along the middle turns your document into a nice pamphlet. + +If you are stuck with using a simplex-only device, you can do the +same, using two different filters and a few additional steps. + +Depending on your model, first use the filter for printing the +odd pages, then insert the paper in the correct order +back into the paper tray to get the even pages printed on the reverse +side. These can then be folded to make a pamphlet. + + + + + + + + + + +&CUPS; Support: the Most Important Module in &kdeprint; + +&kdeprint; contains a module for &CUPS;. &CUPS;, the +Common &UNIX; Printing System (http://www.cups.org/), is the most +advanced, powerful and flexible of all print subsystems on &UNIX; and +other &UNIX;-like operating systems. It is still quite new on the +horizon, but is based on IPP, the Internet Printing +Protocol, the newly emerging standard for the future of network +printing. &CUPS; is clearly the print system of choice for Michael +Goffioul, the principal &kdeprint; developer. + +Experienced &kde; users may already be familiar with Michael's +utilities qtcups and +kups (co-developed with Jean-Eric Cuendet). +These were, up until now, the graphical +&GUI; front ends for &CUPS; with a strong relation to &kde;. + + +<application>qtcups</application> and +<application>kups</application> — The Predecessors + +Both utilities are probably still widely used. For those +not familiar with them, +here are brief explanations. + +qtcups was a graphical front end for +the lp or lpr print commands as +installed by &CUPS;. Using qtcups opened a +dialog. This dialog let you comfortably select your printer and the +print job options. qtcups +worked from the command line, or from +within applications, when the application in question had a configurable +print command. + +kups was a graphical wrapper to do the +administration tasks for your &CUPS; server, and the &CUPS; daemon at +the heart of it. You could add, delete, modify, configure, start, and +stop printers. You could cancel, delete, move, stop and restart print +jobs, and you could change the settings of the daemon, start, stop, and +restart it. + + + + +&kdeprint; — The Heir + +The &CUPS; Module in &kdeprint; now contains all (and more) +functions that were provided by qtcups and +kups in former &kde; versions. + +Instead of qtcups you can now use the +kprinter command. And in place of +kups you will probably use +kcmshell printers from now on. + + +The &kdeprint; module for &CUPS; also lets you fully administer +the print subsystem, just like kups did +before. It can start, stop and configure your &CUPS; daemon. It can also +start, stop, add and delete printers (&ie; printer +queues) and printer instances. Printer instances are +printer queues that point to the same physical output device but with a +different default setting of print options. + + + + +&kprinter; — Graphical Print Command + +&kdeprint;'s &CUPS; module gives you access to a graphical +print command, like qtcups did +before. + +Use &kprinter; in any application, even a non-&kde; +application, that lets you configure your print command. Examples of +these are &Netscape; and StarOffice, but +not most pre-&kde; 2.2 programs. + +A screenshot how to use the new kprinter +print command instead of the old-fashioned lpr... +Of course you need to have kprinter in your +$PATH, or give the full path in the dialog; ⪚ +/opt/kde/bin/kprinter. +&Netscape; will remember this and with further print jobs you will get +the kprinter dialog to configure your printouts. + + +A screenshot of the kprinter print +command in action. + + + + + +Here's a screenshot showing how to use the new +kprinter print command +instead of the old-fashioned lp or +lpr in &Netscape;. + + + + +You can also use &kprinter; from the +command line and see the resulting dialog box pop up: + + +Screenshot of the kprinter command + + + + +Screenshot showing use of the kprinter command +from the command line. + + + +Just make sure you give at least the file to be printed +from the command line as well: kprinter +. +This will hand over the &CUPS; Software Administrator Manual to the +kprinter dialog, which will then pop up with the +default printer pre-selected. + +To pre-select a specific printer from the command line, use the + option, ⪚: +kprinter +. You +can still de-select the printer and +choose a different one. + + You cannot however call +kprinter +without a print file and hope to open a file selection +dialog box from the &kprinter; window. This is a feature that will be +implemented only in the next version. + + +Using kprinter you are able to ring +all the bells and blow all the whistles of your printer. You +will need a device-specific so-called &PPD; (&PostScript; Printer +Description) to enable &CUPS; to make this nice tandem team do this +for you. Read more about this in . + + + + + + +Plans for Future Development + +What you have now is the first, already very feature-rich +version of &kdeprint;. This version is, of course, fully usable for +printing. You might even think that it was never so +easy (not even back in the days when you had to use +&Microsoft; &Windows;). + + In the future, &kdeprint; will become even better. It will do a +better job of detecting your installed print subsystem +itself. Already &kdeprint; is doing quite well in automatically +sensing if you have &CUPS; on your system. But in many cases you will +have to tell &kdeprint; what you are using, if you want to keep a +legacy print system. + +The most important improvement in the near future will be a +completion of the LPRng plugin. This at +present is still very basic. It is restricted to the pure classical +LPD part of +LPRng. + +Also, you may be able to add printers directly from the print +dialog to your system just in time, without going to +&kcontrol; first. + +Some smaller improvements already planned are: + + +add a file selection dialog from the &kprinter; window +to allow combining of additional files to the present +printjob add a +history button to the +KJobViewer window and also a column to show +the number of pages &CUPS; calculates for the job. + + +Finally, there will be an IO slave that will give +you access to your print subsystem, via &konqueror; for example. With +this you will soon be able to browse your print subsystem from +&konqueror; through a &URL; like shortcut such as +print://printers/printername. A KPart will add +a virtual folder to the services section of the &konqueror; navigation +panel, giving a nice integrated way to browse and manage your print +system via the &URL; print:/manager. + +Please contact Michael Goffioul at kdeprint@swing.be +with any further user or developer suggestions. + + + diff --git a/doc/kdeprint/index.docbook b/doc/kdeprint/index.docbook new file mode 100644 index 000000000..79ef27770 --- /dev/null +++ b/doc/kdeprint/index.docbook @@ -0,0 +1,200 @@ + +CUPS"> + PPD"> + IPP"> + ghostscript"> + + + + + + + + + + + + + + + + + +]> + + + + +The &kdeprint; Handbook + + + +Kurt +Pfeifle + +
kpfeifle@danka.de
+ + + + +Michael +Goffioul + +
kdeprint@swing.be
+ +Developer + + + +Lauri +Watts + +
lauri@kde.org
+ +Reviewer + + + + + + + +2001 +Kurt Pfeifle + + +&FDLNotice; + +2001-08-09 +1.00.04 + + +This handbook describes &kdeprint;. &kdeprint; is not a standalone +program. It is the new printing framework for &kde; 2.2. &kdeprint; +is an intermediate layer between &kde; (or other) applications and the selected +(and installed) print subsystem of your OS (&OS;). + + + +KDE +kdebase +kdeprint +print +printing +CUPS +LPR + + + + + +Introduction + +This handbook describes &kdeprint;. &kdeprint; is not a standalone +program. It is the new printing framework for &kde; 2.2. &kdeprint; +is an intermediate layer between &kde; (or other) applications and the selected +(and installed) print subsystem of your OS (&OS;). + +It should be noted that both the developer of this application, +and the author of this document are most familiar with &CUPS; as a +printing system. At the time of writing, &CUPS; is the best supported +printing subsystem, and it is the best documented. + +This handbook is a work in progress, and later versions of the +&kdeprint; software and editions of this handbook will support and +explore more closely other printing systems. + +In the meantime, even if your printing subsystem is not yet well +covered, you are encouraged to explore the Printing +Manager module in &kcontrol;, and you will find its +operation to hopefully be fairly self evident, no matter what printing +subsystem you use. + +Lauri Watts, &kde; documentation team + + + + +To configure your printing subsystem from &kcontrol; + +To configure your printing subsystem from &kcontrol;, go to +SystemPrinting +Manager and select your subsystem. Or you can +let &kdeprint; try to determine it... + + +&CUPS; Printing Manager dialog: overview via &kcontrol; + + + + +The dialog to configure the &CUPS; server: security +settings +Configuration of printing subsystem from +&kcontrol; + + + + + + +&tech-overview-doc; + +&highlights-doc; + +&theory-doc; + +&getting-started-doc; + +&cups-configuration-doc; + +&add-printer-wizard-2-doc; + +&cupsoptions-presently-outside-kcontrol-doc; + +&rlpr-doc; + +&lpd-doc; + +&lpr-bsd-doc; + +&lprng-doc; + +&external-command-doc; + +&extensions-doc; + +&final-word-doc; + + +Credits And Licenses + +&kdeprint; copyright 2001, Michael Goffioul +kdeprint@swing.be +&underGPL; + +Documentation copyright 2001, Kurt Pfeifle, +kpfeifle@danka.de +&underFDL; + + + + + + + + diff --git a/doc/kdeprint/kcontrol-icon.png b/doc/kdeprint/kcontrol-icon.png new file mode 100644 index 000000000..8fbaacd79 Binary files /dev/null and b/doc/kdeprint/kcontrol-icon.png differ diff --git a/doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png b/doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png new file mode 100644 index 000000000..d7132b1cd Binary files /dev/null and b/doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png differ diff --git a/doc/kdeprint/kcron_to_be_printed.png b/doc/kdeprint/kcron_to_be_printed.png new file mode 100644 index 000000000..114b26b3c Binary files /dev/null and b/doc/kdeprint/kcron_to_be_printed.png differ diff --git a/doc/kdeprint/kdeprint-jobviewer.png b/doc/kdeprint/kdeprint-jobviewer.png new file mode 100644 index 000000000..8182e4317 Binary files /dev/null and b/doc/kdeprint/kdeprint-jobviewer.png differ diff --git a/doc/kdeprint/kprinter-as-netscape-printcommand.png b/doc/kdeprint/kprinter-as-netscape-printcommand.png new file mode 100644 index 000000000..0780e2a80 Binary files /dev/null and b/doc/kdeprint/kprinter-as-netscape-printcommand.png differ diff --git a/doc/kdeprint/kprinter-kivio.png b/doc/kdeprint/kprinter-kivio.png new file mode 100644 index 000000000..b36b49b89 Binary files /dev/null and b/doc/kdeprint/kprinter-kivio.png differ diff --git a/doc/kdeprint/kprinter.png b/doc/kdeprint/kprinter.png new file mode 100644 index 000000000..f83cfcd4b Binary files /dev/null and b/doc/kdeprint/kprinter.png differ diff --git a/doc/kdeprint/kprinter_called_from_run_command.png b/doc/kdeprint/kprinter_called_from_run_command.png new file mode 100644 index 000000000..b02070c1d Binary files /dev/null and b/doc/kdeprint/kprinter_called_from_run_command.png differ diff --git a/doc/kdeprint/kprinter_with_kcron_developer_special.png b/doc/kdeprint/kprinter_with_kcron_developer_special.png new file mode 100644 index 000000000..dc9b785cf Binary files /dev/null and b/doc/kdeprint/kprinter_with_kcron_developer_special.png differ diff --git a/doc/kdeprint/lpd.docbook b/doc/kdeprint/lpd.docbook new file mode 100644 index 000000000..cc555e399 --- /dev/null +++ b/doc/kdeprint/lpd.docbook @@ -0,0 +1,18 @@ + +Generic <acronym>LPD</acronym> Module (&UNIX;) + + + +Overview of Provided Features + +Module used by default (on first start for example). + +Generic module that only allows sending of print jobs. No printer or +job management supported. It is made to work on a wide variety of &UNIX; +flavors: &Linux;/LPR, &HP-UX;, Solaris, &IRIX;. +It also supports some LPRng extensions (like +the absence of continuation character \ in +printcap files). + + + diff --git a/doc/kdeprint/lpr-bsd.docbook b/doc/kdeprint/lpr-bsd.docbook new file mode 100644 index 000000000..007fbc6e5 --- /dev/null +++ b/doc/kdeprint/lpr-bsd.docbook @@ -0,0 +1,25 @@ + +<acronym>LPR</acronym> (<acronym>BSD</acronym>) + +Plain (old?) LPR support. An +LPRng module is in development, and hopefully +available for 2.3 release. + + +Overview of Provided Features + + + +Printer management: basic support to add/remove/configure a +printer, compatible with &RedHat;-6.x systems +(printtool + rhs-printfilers packages). + + +Job management: not supported + + +Print options: basic control + + + + diff --git a/doc/kdeprint/lprng.docbook b/doc/kdeprint/lprng.docbook new file mode 100644 index 000000000..5117664e0 --- /dev/null +++ b/doc/kdeprint/lprng.docbook @@ -0,0 +1,7 @@ + +<application>LPRng</application> + +An LPRng module for &kdeprint; is in +development, and hopefully available for the &kde; 2.3 release. + + diff --git a/doc/kdeprint/ps-boxes.png b/doc/kdeprint/ps-boxes.png new file mode 100644 index 000000000..a24f845a7 Binary files /dev/null and b/doc/kdeprint/ps-boxes.png differ diff --git a/doc/kdeprint/rlpr.docbook b/doc/kdeprint/rlpr.docbook new file mode 100644 index 000000000..fab48d7bb --- /dev/null +++ b/doc/kdeprint/rlpr.docbook @@ -0,0 +1,18 @@ + +Module Built Around <application>rlpr</application> +Utility + + +Overview of provided features + +Printer management: basic operations are supported +(add/remove/modify). + +Each user can predefine the printers he wants to use by specifying +the host and related printer queues. Printers are stored on a per +user basis. This module is built around the +rlpr utility rlpr + + + diff --git a/doc/kdeprint/steinbruch_scaled.png b/doc/kdeprint/steinbruch_scaled.png new file mode 100644 index 000000000..57e6fde76 Binary files /dev/null and b/doc/kdeprint/steinbruch_scaled.png differ diff --git a/doc/kdeprint/tech-overview.docbook b/doc/kdeprint/tech-overview.docbook new file mode 100644 index 000000000..96b3888e9 --- /dev/null +++ b/doc/kdeprint/tech-overview.docbook @@ -0,0 +1,280 @@ + +Technical Overview + +This chapter aims to give a technical overview of &kdeprint; which +non-programmers can comprehend. + +&kdeprint; is a new and revolutionary tool to give easy access to +printing services for both &kde; users and &kde; developers. + + +A Brief Description of &kdeprint; + +You can access the functions of &kdeprint; in different ways: +through the Printing Manger in the &kcontrol;, through the +kprinter command or through the dialog that pops up +if you want to print. + + +What it is <emphasis>not</emphasis> + +&kdeprint; is not a replacement for the +printing subsystem itself. &kdeprint; does not +therefore give provision for spooling, and it does +not do the basic processing of &PostScript; or +other print data. + + + + +What it <emphasis>is</emphasis> +&kdeprint; is an intermediate layer between the spooling and the +data processing print subsystem (as installed), and the application that +seeks to print. &kdeprint; provides a common interface for &kde; +developers and &kde; users, to various supported print subsystems. At +the same time, it is customizable, and highly configurable. + +&kdeprint; is easy to use for both &kde; developers and end-users. +Developers can port their applications, with minimal changes, to use +&kdeprint; instead of the old &Qt; print system. Users +can easily choose and configure their print subsystem. + +For a reference to new &kde; users: &Qt; is the basic library and +graphical toolkit, which is used by all &kde; applications; &Qt; is +developed by TrollTech, a Norwegian software company. + + + + + + +&kdeprint; -- Different Usage for Different People + +&kdeprint; has different faces for different people. + + +What users and administrators can do with &kdeprint; + +&kdeprint; allows users and/or administrators, depending on their +rights, access to printing subsystems (&CUPS;, LPD, +RLPR, LPRng, +PDQ &etc;) through a &kde; graphical user +interface (&GUI;). Using &kdeprint;, they can print, administer jobs, +printers and the printing daemon, all in a comfortable manner. + +Experienced users will like the capability to plug any working +filter for the print data between the output of their application and +the input, into the chosen print subsystem. Some examples for this +already ship with plain vanilla &kdeprint;. Read +on. + + + + + +What &kde; developers can do with it... + +If a &kde; developer needs printing access for his application, he +does not code the printing functions from scratch. Before &kde; 2.2 this +service was provided by the QPrinter class, a +library function of the &Qt; Toolkit. The +QPrinter class relied on the out-moded +Line Printer Daemon (LPD). The +&kdeprint; library bases itself firmly on the more modern Common &UNIX; +Printing System (&CUPS;), while at the same time keeping backward +compatibility with LPD and other legacy, or less +elaborate, print systems. It also leaves the door open +for any new development that might occur. + +For &kde; developers to use the new &kdeprint; class in their +applications, they require only minimal changes to their code: for every +call of QPrinter, they just need to change this to +KPrinter. Replacing one (!) letter in a few +spots, and automatically they are done; their application can then use +all of the features of the new &kdeprint; library. + +More ambitious developers, or ones with special requirements, can +do more: despite &kdeprint;'s feature-rich framework, they are still able +to customize the print dialog of their application +by creating an additional Tab, where their +extensions to the standard &kdeprint; will feel right at home. + + +This last mentioned feature has not been used widely inside +&kde; so far, as developers are not yet fully aware of &kdeprint;'s +power. Expect more of this in the near future. One example I +discovered is the &kcron; application. It lets you edit the crontab +through a &GUI;. The developers have implemented a printing feature +that lets you (or root) +choose if you want to print the whole of crontab (for all users) or +just the part that is marked. You can see the effects on &kdeprint; +in the following screenshots. + +This shot shows a sample from the &kcron; utility. + +&kcron; utility: a small sample of a system's cronjobs as +shown through the &kde; GUI&GUI;. + + + + +The &kcron; developers let you choose to print the whole of the +cron table or just the marked part of it. + + + + +The dialog to configure &kcron;'s printing options: the +additional tab titled Cron Options is from inside +&kcron;, not &kdeprint;; it is a special extension added by the +&kcron; developers for printing purposes, not originating from, but +executed by &kdeprint;. Developers of other applications are free +to implement their own goodies, if they feel need for it. + + + +&kcron;'s addition to the &kdeprint; dialog. + + + + +&kcron;'s addition to the &kdeprint; dialog. + +&kcron;'s addition to the &kdeprint; dialog. + + + + + + + +What &kdeprint; offers to everybody... + +&kdeprint;'s easy-to-use interface for all supported print subsystems +of course does not eliminate basic traditional weaknesses of some of +those systems. But it smooths some rough edges. Different users may use +different printing systems on the same box. A user is free to even +switch on the fly, from the print dialog, the print +subsystem to be used for the next job. (This is possible if different +systems are installed in a way that they don't get in each +other's way.) + +Most &UNIX; users are used to +LPD printing. LPD provides only +basic printing functions, is very inflexible and does not utilize the +many options of more modern print systems like &CUPS;. While also +working remotely over any distance (like every TCP/IP based protocol), +LPD lacks bi-directional communication, +authentication, access control and encryption support. + +&kdeprint; can use &CUPS; to support: + + + +Querying the LAN for available printers, + + +Basic, Digest, and Certificate Authentication, + + +Access Control based on IP addresses, net +addresses, netmasks, host- and domain names, + + +and 128-Bit TLS or SSL3 encryption of print data, to prevent +eavesdropping, or at least make it much more difficult. + + + +This makes &kdeprint; a much more robust and reliable solution +than using the venerable LPD. + + + +How to access &kdeprint; + +You get access to &kdeprint;, or parts of it, in four different +ways: + + +through your applications: if you call the printing +dialog (either File +Print...) or the button with the +little printer icon on it; this opens the printing +dialog. + +through the typed command kprinter +in a terminal or a &konsole; window or from +the Run Command... mini-CLI +window: this also opens the printing dialog. + +from the + button, starting &kcontrol;, and then go to +SystemPrinting +Manager. This opens the &kdeprint; +administration which is part of the &kcontrolcenter; and also lets +you switch to other parts of the &kcontrol; + +from a command line (&konsole; or +mini-CLI) type +kcmshell . +This opens just the &kdeprint; part of &kcontrol; to change your settings + + + +&kprinter; dialog to be started from Run Command... window + + + + +Starting the &kprinter; dialog from +a Run Command... window. +Starting the &kprinter; dialog from a Run +Command... window. + + + + Here is a +&kivio; drawing of the &kprinter; dialog as it pops up after being +started... You can always add a new printer by clicking on the small +Wizard button (marked red/yellow in this +drawing). + + +&kprinter; dialog started (&kivio; draft drawing) + + + + + +&kprinter; dialog started (&kivio; draft drawing) +&kprinter; dialog started (&kivio; draft +drawing) + + + + + + + + + + diff --git a/doc/kdeprint/theory.docbook b/doc/kdeprint/theory.docbook new file mode 100644 index 000000000..a90aa2755 --- /dev/null +++ b/doc/kdeprint/theory.docbook @@ -0,0 +1,690 @@ + +Some Theoretical Background: &CUPS;, <acronym>IPP</acronym>, +&PostScript; and <application>Ghostscript</application> + +This chapter aims to give a bit of theoretical background to +printing in general, and to &CUPS; especially. If you are not in need +of this, you might like to skip ahead to the next chapter. Chances are you will +come back to this chapter at some point anyway, because sometimes one +needs extra theory to solve a practical problem. + + +Basics About Printing + +Printing is one of the more complicated chapters in +IT technology. + + +Earlier on in history, every developer of a program that was +capable of producing printable output had to write his own printer +drivers too. That was quite complicated, because different programs +have different file formats. Even programs with the same purpose, for +example: word processors, often do not understand each other's formats. +There was therefore no common interface to all printers, hence the +programmers often supported only a few selected models. + +A new device appearing on the market required the program authors +to write a new driver if they wanted their program to support it. Also +for manufacturers, it was impossible to make sure their device was +supported by any program known to the world (although there were far +fewer than today). + +Having to support ten application programs and a dozen printers, +meant a system administrator had to deal with 120 drivers. So the +development of unified interfaces between programs and printers became +an urgent need. + +The appearance of Page Description Languages, +describing the graphical representation of ink and toner on sheets of +paper (or other output devices, like monitors, photo typesetters, &etc;) +in a common way, was a move that filled a big gap. + +One such development was &PostScript; by Adobe. It meant that an +application programmer could concentrate on making his program generate +a &PostScript; language description of his printable page, while +printing device developers could focus on making their devices +&PostScript; literate. + +Of course, over time, there came the development of other description +methods. The most important competitors to &PostScript; were +PCL (Print Control Language, from +&Hewlett-Packard;), ESC/P (from Epson) and +GDI (Graphical Device Interface from +&Microsoft;). + +The appearance of these page description languages made life easier, +and facilitated further development for everybody. Yet the fact that there +still remained different, incompatible, and competing page description +languages keeps life for users, administrators, developers and +manufacturers difficult enough. + + +&PostScript; in memory - Bitmaps on Paper + +&PostScript; is most heavily used in professional printing +environments such as PrePress and printing service industries. In the +&UNIX; and &Linux; domains, &PostScript; is the predominant standard +as a PDL. Here, nearly every program generates a +&PostScript; representation of its pages once you push the +Print button. Let us look at a simple example of +(hand-made) &PostScript; code. The following listing describes two +simple drawings: + + +&PostScript; Code +%!PS +100 100 moveto +0 50 rlineto +50 0 rlineto +0 -50 rlineto +closepath +.7 setgray fill +% first box over; next +160 100 moveto +0 60 rlineto +45 10 rlineto +0 -40 rlineto +closepath +.2 setgray fill + + +This tells the imaginary &PostScript; pen to draw +a path of a certain shape, and then fill it with different shades of +gray. The first part translates into more comprehensive English as +Go to coordinate (100,100), draw a line with length 50 upward; +then one from there to the right, then down again, and finally close +this part. Now fill the drawn shape with 70% darkness gray. + + +Rendered &PostScript; + + + + + + example rendered as an +image. + + + + +Of course, &PostScript; can be much more complicated than this +simplistic example. It is a fully fledged programming language with +many different operators and functions. You may even write +&PostScript; programs to compute the value of Pi, format a hard disk or +write to a file. The main value and strength of &PostScript; however +lies in the field to describe the layout of graphical objects on a +page: it also can scale, mirror, translate, transform, rotate and +distort everything you can imagine on a piece of paper -- such as +letters in different font representations, figures, shapes, shades, +colors, lines, dots, raster... + +A &PostScript; file is a representation of one or more pages +to be printed, in a relatively abstract way. Ideally, it is meant +to describe the pages in a device-independent way. &PostScript; is +not directly visible; it only lives on hard disks +and in RAM as a coded representation of +future printouts. + + + + +Raster Images on Paper Sheets + +What you see on a piece of paper is nearly always a +raster image. Even if your brain suggests to you that +your eyes see a line: take a good magnifying glass and you will +discover lots of small dots... (One example to the contrary are +lines that have been drawn by pen plotters). And that +is the only thing that the marking engines of today's +printers can put on paper: simple dots of different colors, size and +resolution, to make up a complete page image composed of +different bitmap patterns. + +Different printers need the raster image prepared in different +ways. Thinking about an inkjet device: depending on its resolution, +the number of inks used (the very good ones need 7 different inks, while +cheaper ones might only use 3), the number of available jets (some print +heads have more than 100!) dispensing ink simultaneously, the +dithering algorithm used, and many other things, the +final raster format and transfer order to the marking engine is heavily +dependent on the exact model used. + +Back in the early life of the Line Printer Daemon, +printers were machines that hammered rows of ASCII +text mechanically on to long media, folded as a zig-zag paper +snake, drawn from a cardboard box beneath the +table... What a difference from today! + + + + + +<acronym>RIP</acronym>: From &PostScript; to Raster + +Before the final raster images are put on paper cut-sheets, they +have to be calculated somehow out of their abstract &PostScript; +representation. This is a very computing-intensive process. It is called +the Raster Imaging Process, more commonly +RIP). + +With &PostScript; printers the RIP-ping is +taken care of by the device itself. You just send the &PostScript; +file to it. The Raster Imaging Processor (also called the +RIP) inside the printer is responsible (and +specialized) to fulfill quite well this task of interpreting the +&PostScript;-page descriptions and put the raster image on paper. + +Smaller &PostScript; devices have a +hardware-RIP built in; it is etched in silicon, on a +special chip. Big professional printers often have their +RIP implemented as a software-RIP +inside a dedicated fast &UNIX; run computer, often a Sun SPARC Solaris +or a &SGI; &IRIX; machine. + + + + +<application>Ghostscript</application> as a Software +<acronym>RIP</acronym> + +But what happens, if you are not lucky enough to have a +&PostScript; printer available? + +You need to do the RIP-ing before you send +the print data to the marking engine. You need to digest the &PostScript; +generated by your application on the host machine (the print client) +itself. You need to know how the exact raster format of the target +printer's marking engine must be composed. + +In other words, as you can't rely on the printer to understand +and interpret the &PostScript; itself, the issue becomes quite a bit +more complicated. You need software that tries to solve for you the +issues involved. + +This is exactly what the omnipresent &ghostscript; package is +doing for many &Linux;, *BSD and other &UNIX; boxes that need to print +to non-&PostScript; printers: &ghostscript; is a &PostScript; +interpreter, a software RIP capable of running many +different devices. + + + + +<quote>Drivers</quote> and <quote>Filters</quote> in General + +To produce rasterized bitmaps from &PostScript; input, the +concept of filters is used by &ghostscript;. There are +many different filters in &ghostscript;, some of them specialized for +a certain model of printer. &ghostscript; filterspecializedin devices +have often been developed without the consent or support of the +manufacturer concerned. Without access to the specifications and +documentation, it was a very painstaking process to reverse engineer +protocols and data formats. + +Not all &ghostscript; filters work equally well for their +printers. Yet, some of the newer ones, like the +stp Filter of the +Gimp Print project, produce excellent +results leading to photographic quality on a par or even superior to +their &Microsoft; &Windows; driver counterparts. + +&PostScript; is what most application programs produce for +printing in &UNIX; and &Linux;. Filters are the true workhorses of +any printing system there. Essentially they produce the right bitmaps +from any &PostScript; input for non-&PostScript; target +engines. + + + + +Drivers and Filters and Backends in CUPS + +&CUPS; uses its own filters, though the filtering system is +based on Ghostscript. Namely the pstoraster and the imagetoraster +filters are directly derived from Ghostscript code. &CUPS; has +reorganized and streamlined the whole mechanics of this legacy code +and organized it into a few clear and distinct modules. + +This next drawing (done with the help of &kivio;) gives an +overview of the filters and backends inside &CUPS; and how they fit +together. The flow is from top to bottom. Backends +are special filters: they don't convert date to a different format, +but they send the ready files to the printer. There are different +backends for different transfer protocols. + + +&kprinter; dialog started (&kivio; draft drawing) + + + + + +&kprinter; dialog started (&kivio; draft +drawing) + + + + + +Spoolers and Printing Daemons + +Besides the heavy part of the filtering task to generate a +print-ready bitmap, any printing software needs to use a SPOOLing +mechanism: this is to line up different jobs from different users for +different printers and different filters and send them accordingly to +the destinations. The printing daemon takes care of all this. + +This daemon is keeping the house in order: it is also +responsible for the job control: users should be allowed to cancel, +stop, restart, &etc; their jobs (but not other peoples's jobs) and so +on. + + + + + + + + +Excursion: How <quote>CUPS</quote> uses the power of +&PPD;s + +Now that you know how a &PostScript; language file (which +describes the page layout in a largely device independent way) is +transformed into a Raster Image, you might ask: +Well, there are different kinds of raster output devices: first +they differ in their resolution; then there are the different paper +sizes; it goes on with many finishing options (duplex prints, +pamphlets, punched and stapled output with different sheets of colored +paper being drawn from different trays, &etc;). How does this fit into +our model of device-independent &PostScript;? + +The answer comes with so called &PostScript; Printer Description +(&PPD; files. A &PPD; describes all the device dependent features +which can be utilized by a certain printer model. It also contains +the coded commands that must be used to call certain features of the +device. But &PPD;s are not a closed book, they are simple +ASCII text files. + +&PPD;s were invented by Adobe to make it easy for +manufacturers to implement their own features into &PostScript; +printers, and at the same time retain a standard way of doing so. +&PPD;s are well documented and described by Adobe. Their +specification is a de-facto open standard. + + +Device Dependent Print Options + +Remember, advanced &PostScript; printing was originally only +developed for use on &Microsoft; &Windows; and Apple &Mac; systems. +For a long time, all of the feature rich printing on modern devices +was simply unavailable for &Linux; and &UNIX;. &CUPS; changes this +decisively. &CUPS; is closely tied with &PPD;s, and therefore existing +&PPD;s can be utilized to the full by all systems powered by +&CUPS;. + +Using &PPD;s, printer manufacturers were able to insert +device-specific hardware features into their products, for features such +as duplexing, stapling, punching, finishing, &etc;. The printer drivers +load this &PPD; just like an additional configuration file. Thus the +printer driver learns about the available device options and how to +call them; the driver also presents them in a &GUI; to the user. Through +this mechanism you are still able to print +device-independent &PostScript; page description +language files and specify device-dependent finishing options on top, +which are added to the application-generated &PostScript;. + + + + +Where to get the &PPD;s for &PostScript; Printers + +&PPD;s originally were not used routinely in &UNIX; and &Linux; +systems. The vendors providing those &PPD;s never intended them for +anything other than the originally supported &OS;s: &Microsoft; &Windows; and +&MacOS;. Through its brilliant move to fully support and utilize +the existing &PPD; specification, &CUPS; now gives the power to use +all features of modern printers to users of &Linux; and &Linux;-like +systems. &kdeprint; makes its usage even more comfortable than the +&CUPS; developers ever dreamed of. + +&CUPS; can use original &Windows; &PPD;s, distributed by the +vendors in the case of &PostScript; printers. Those normally don't +cost any money, and they can be grabbed from any &Windows; computer +with an installed &PostScript; driver for the model concerned, or from +the disks provided with the printer. There are also several places on +the web to download them. + + + + +How Special &PPD;s are Now Useful Even For Non-&PostScript; +Printers. + +Now you know how &PostScript;-Printers can use &PPD;s. But what +about non-&PostScript; printers? &CUPS; has done a very good trick: by +using the same format and data structure as the &PostScript; Printer +Descriptions (&PPD;s) in the &PostScript; world, it can describe the +available print job options for non-&PostScript; printers just the +same. For its own special purposes &CUPS; just added a few special +options (namely the line which defines the filter to be used for +further processing of the &PostScript; file). + +So, the developers could use the same software engine to parse +the Printer Description Files for available options for all sorts of +printers. Of course the &CUPS; developers could not rely on the +non-&PostScript; hardware manufacturers to suddenly develop &PPD;s. +They had to do the difficult start themselves and write them from +scratch. More than 1000 of these are available through the commercial +version of &CUPS;, called ESP +PrintPro. + +Meanwhile there are a lot of &CUPS;-specific &PPD;s available. +Even now those are in most cases not originating from the printer +manufacturers, but from Free software developers. The &CUPS; folks +proofed it, and others followed suit: where &Linux; and &UNIX; +printing one or two years ago still was a kludge, it is now able to +support a big range of printers, including 7-color inkjets capable of +pushing them to Photo Quality output. + + + + +Different Ways to get &PPD;s for non-&PostScript; +Printers + +You can get &PPD;s to be used with &CUPS; and non-&PostScript; +printers from different areas in the Web: + + + + first, there is the repository at www.linuxprinting.org, +which lets you generate a CUPS-O-Matic-&PPD; online for +any printer that had been supported by traditional &ghostscript; +printing already. This helps you to switch over to &CUPS; with little +effort, if you wish so. If your printer was doing well with the +traditional way of &ghostscript; printing, take CUPS-O-Matic to plug +your driver into th e &CUPS; system and you'll have the best of both +worlds. + + + +second, there are &CUPS;-&PPD;s for the more than 120 printer +models, which are driven by the new universal +stp driver. stp +(stood originally for Stylus Photo) is now developed by the gimp-print +project; it was started by Mike Sweet, the leading &CUPS; developer +and is now available through gimp-print.sourceforge.net. +This driver prints real Photo quality on many modern inkjets and can +be configured to make 120 &CUPS;-&PPD;s along its own +compilation. &HP; Laser- and DeskJet, Epson Stylus and Photo Color models as +well as some Canon and +Lexmark are covered. + + + +third, there is the commercial extension to &CUPS; from the +&CUPS; developers themselves: it is called ESP +PrintPro and comes with more than 2.300 printer +drivers. There are even improved imagetoraster and pstoraster filters +included. + + + +&CUPS; makes it really easy for manufacturers to start +supporting &Linux; and &UNIX; printing for their models at reasonably +low cost. The modular framework of &CUPS; facilitates to plug in any +filter (=driver) with minimal effort and to access and utilize the +whole printing framework that &CUPS; is creating. + +Read more about the exciting &CUPS; features in the available +&CUPS; documentation at http://www.cups.org/documentation.html +and http://www.danka.de/printpro/faq.html. +Also at http://www.linuxprinting.org/ +is a universal repository for all issues related to &Linux; and &UNIX; +printing. + + + + + + +How &IPP; Support Makes &CUPS; the Best Choice Around + + +<quote><acronym>LPD</acronym> Must Die!</quote> + +For a long time many developers were deeply dissatisfied with good +old LPD. Quite a few new projects were started to +improve printing: LPRng is the best known +example. Others are PDQ, PPR, +PLP, GNUlpr and +RLPR. But none of the new programs were seen as a +big shot; most of them are just implementing the same old +LPD specification with a few (or many) new +extensions, which again make them incompatible with each other. + +Having seen the development of not just one, but different +viable alternatives to venerable BSD-style +LPD, Grant Taylor, author of the Linux +Printing HOWTO, finally rallied the call LPD +Must Die! in his Campaign To Abolish The Line +Printer Daemon. + + + + + + +How the &IPP; Came to Be + +Along with the above, on the industry side of things, there were +efforts to overcome the well-known weaknesses of +LPD. It started with proprietary extensions to +plain old LPD, and stretched as far as +&Hewlett-Packard;'s attempt to establish &HP; JetDirect as a new +standard for a network printing protocol. The result were even more +incompatibilities. + +In the end, an initiative to define a new common industry and +IETF standard took shape. The Printer +Working Group or PWG, a loose aggregation +of vendors in hardware, software, and operating systems, drafted the +new Internet Printing Protocol, &IPP;. &IPP; v1.1 has +now been approved by the IETF (Internet Engineering +Task Force) as a proposed standard, and now enjoys the unanimous +support throughout the industry in Europe, USA and Japan. Most +current network printer models have now built in &IPP; support on top +of traditional LPR/LPD or +JetDirect Printing. + + + + +Why &IPP; is Solving Many Problems + +&IPP; promises to solve a lot of problems network administrators +face. This trade normally deals with heterogeneous network +environments and spends more than half of its working hours dealing +with printing problems. + +By creating a unified set of query functions for &IPP; enabled +printers and servers, for transferring files and setting job-control +attributes &etc;, &IPP; is destined to work across all &OS; platforms. +It's rollout however, will not happen overnight, as many legacy print +devices will still be in use for many years to come. Therefore, in +&IPP; there is a provision made for backwards compatibility of all +&IPP; implementations. &CUPS; is proving the viability of &IPP; +printing in all environments. + +The most striking advantage will be it's integration into the +existing set of other robust IP protocols. Being +an extension of the proven and robust HTTP 1.1 +protocol, for the special task of handling print file and related +data, it is also very easy to plug in other standards as they are +being developed and deployed: + + + +Basic, Digest, and Certificate Authentication for users seeking +access to print services. + + +SSL3 and TLS encryption for transferring +data. + + +Bi directional communication of clients with print devices, using +the HTTP/&IPP; GET and +POST mechanism. + + +LDAP directory service integration to keep a consistent database +of available printers, their capabilities and page-costs, &etc;, as well +as user passwords, ACLs &etc;. + + +Pull (as opposed to the usual Push +model) printing, where a server or printer just needs to be told the +&URL; of a document, whereupon it is retrieved from the resource on the +internet and printed. + + + + + + + + +Printer <quote>Plug'n'Play</quote> for Clients + +Have you ever seen a demonstration about &CUPS; capabilities in +the network? You must have been quite impressed if you didn't know in +advance what to expect. + +Imagine you as the administrator of a LAN. For +testing purposes you fully installed one &kde;/&CUPS; box on your net, +complete with a dozen printers configured and functional: +&PostScript;, LaserJets, InkJets and BubbleJets, and so on. Your +&kde; users on that box are very happy, they can print like never +before, ringing all the bells and whistles of every +printer. It took you 2 hours to make everything run perfectly... and +now all the other 100 users on the network want the same. Two hours +again for every box? No way you could do that before next year, you +think? + +Wrong. Just change one setting in the original &CUPS; box to +make it a server. Install &CUPS; on five other boxes, +as clients. By the time you turn back to your first +client, you find the users happily playing with the settings for the +dozen printers you had defined earlier on the server. +Somehow magically the printers had appeared on all the +Print dialogs of the five new &CUPS; client +boxes. + +Your users print, but not a single driver had been installed on +the clients, nor a printer queue defined. + +So, how does this magic work? + + + + +<quote>Seeing</quote> Printers Not Installed Locally? + +The answer is not complicated at all. + +If a &CUPS; server is on the LAN, it +broadcasts the names of all available printers to the +LAN, using the UDP protocol and +port 631. Port 631 is reserved as a well-known port by +IANA (the Internet Assigning Numbers +Authority) for &IPP; purposes. All &CUPS; clients listen to +&CUPS; server info sent to their port 631. That's how they know about +available printers, and that's how they learn about the +path to the printers as well. + +Using &IPP;, which is really a clever extension to +HTTP v1.1, &CUPS; is able to address all objects +related to the printing system via Universal Resource +Locators or URLs. Print jobs to be deleted +or restarted, printers to be queried or modified, admin tasks to be +performed on the server, with &IPP; and &CUPS;, everything is +addressable by a certain URL. Many important +things can be done through the web interface to &CUPS;, accessible for +example with &konqueror;. + + + + +Printing Without Installing a Driver + +And more, the clients basically can administer +and use any printer they see, just as if it was a +locally installed one. Of course, you can set restrictions on it with +access control lists &etc;, so that not any +clients may use any printer as it likes. + +The clients even are able to print without the appropriate filter +(or driver) installed locally. + +So how does this work? If a client wants to know about and +select printer-specific options, it sends a request (called +CUPS-get-ppd) to the server. The server tells the +client all about all printer-specific options, as read from the server +side &PPD;. The user on the client side can see the options and +select the required ones. He then sends the print file, usually +unfiltered raw &PostScript;, spiced up with the +printer-options to the printer server, using &IPP; as the transport +protocol. All further processing, especially the filtering to +generate the final format for the target printer, is then done by the +server. The server has the necessary programs (drivers +or filters) to do this. + +This way a client prints without needing to install a driver +locally. + +Any change on the server, such as adding or modifying a printer, +is instantly known to the clients with no further +configuration. + + + + +<quote>Zero Administration</quote>, Load Balancing, and +<quote>Failover Switching</quote> + +Some other advanced features built into &CUPS; are the capacity to +do load balancing. + +If you define the same printer queues on two or more different +servers, the clients will send their jobs to the first responding or +available server. This implies an automatic load balancing amongst +servers. If you have to take one server off the network for +maintenance, the others will just take over its tasks without the users +even noticing the difference. + + + + + + diff --git a/doc/kdesu/Makefile.am b/doc/kdesu/Makefile.am new file mode 100644 index 000000000..bafa3f6c3 --- /dev/null +++ b/doc/kdesu/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO + diff --git a/doc/kdesu/index.docbook b/doc/kdesu/index.docbook new file mode 100644 index 000000000..800d20b10 --- /dev/null +++ b/doc/kdesu/index.docbook @@ -0,0 +1,320 @@ + + + + + +]> + + + + +The &kdesu; handbook + + +&Geert.Jansen; &Geert.Jansen.mail; + + + + +2000 +&Geert.Jansen; + + +&FDLNotice; + +2005-06-07 +1.00.00 + + +&kdesu; is a graphical front end for the &UNIX; +su command. + + +KDE +su +password +root + + + + + +Introduction + +Welcome to &kdesu;! &kdesu; is a graphical front end for the +&UNIX; su command for the K Desktop Environment. +It allows you to run a program as different user by supplying the +password for that user. &kdesu; is an unprivileged program; it uses +the system's su. + +&kdesu; has one additional feature: it can remember passwords +for you. If you are using this feature, you only need to enter the +password once for each command. See for more information on this and a +security analysis. + +This program is meant to be started from the command line or +from .desktop files. Although it asks for the +root password using a &GUI; +dialog, I consider it to be more of a command line <-> &GUI; +glue instead of a pure &GUI; program. + + + + +Using &kdesu; + +Usage of &kdesu; is easy. The syntax is like this: + + +kdesu + + + + file + icon name + + priority + + + + +user + + +command arg1 + arg2 + + + +kdesu +&kde; Generic Options +Qt Generic Options + + +The command line options are explained below. + + + + +This specifies the program to run as root. It has to be passed +in one argument. So if, for example, you want to start a new file manager, you +would enter at the prompt: kdesu + + + +Show debug information. + + + +This option allow efficient use of &kdesu; in +.desktop files. It tells &kdesu; to examine the +file specified by file. If this file is +writable by the current user, &kdesu; will execute the command as the +current user. If it is not writable, the command is executed as user +user (defaults to root). +file is evaluated like this: if +FILE starts with a /, it is +taken as an absolute filename. Otherwise, it is taken as the name of a +global &kde; configuration file. For example: to configure the K display +manager, kdm, you could issue +kdesu + + + icon name +Specify icon to use in the password dialog. You may specify +just the name, without any extension. +For instance to run kfmclient and show the +&konqueror; icon in the password dialog: +kdesu kfmclient + + + + + +Do not keep the password. This disables the keep +password checkbox in the password dialog. + + + priority + +Set priority value. The priority is an arbitrary number between 0 and +100, where 100 means highest priority, and 0 means lowest. The default is +50. + + + + +Use realtime scheduling. + + + + + +Stop the kdesu daemon. See . + + + +Enable terminal output. This disables password keeping. This is +largely for debugging purposes; if you want to run a console mode app, use the +standard su instead. + + + user +While the most common use for &kdesu; is to run a command as +the superuser, you can supply any user name and the appropriate +password. + + + + + + + + +Internals + + +X authentication + +The program you execute will run under the root user id and will +generally have no authority to access your X display. &kdesu; gets +around this by adding an authentication cookie for your display to a +temporary .Xauthority file. After the command +exits, this file is removed. + +If you don't use X cookies, you are on your own. &kdesu; will +detect this and will not add a cookie but you will have to make sure +that root is allowed to access to your display. + + + + +Interface to <command>su</command> + +&kdesu; uses the sytem's su for acquiring +priviliges. In this section, I explain the details of how &kdesu; does +this. + +Because some su implementations (&ie; the one +from &RedHat;) don't want to read the password from +stdin, &kdesu; creates a pty/tty pair and executes +su with it's standard filedescriptors connected to +the tty. + +To execute the command the user selected, rather than an +interactive shell, &kdesu; uses the argument with +su. This argument is understood by every shell that +I know of so it should work portably. su passes +this argument to the target user's shell, and the +shell executes the program. Example command: su . + +Instead of executing the user command directly with +su, &kdesu; executes a little stub program called +kdesu_stub. This stub (running as the +target user), requests some information from &kdesu; over the pty/tty +channel (the stub's stdin and stdout) and then executes the user's +program. The information passed over is: the X display, an X +authentication cookie (if available), the PATH and the +command to run. The reason why a stub program is used is that the X +cookie is private information and therefore cannot be passed on the +command line. + + + + +Password Checking + +&kdesu; will check the password you entered and gives an error +message if it is not correct. The checking is done by executing a test +program: /bin/true. If this succeeds, the +password is assumed to be correct. + + + + +Password Keeping + +For your comfort, &kdesu; implements a keep +password feature. If you are interested in security, you +should read this paragraph. + +Allowing &kdesu; to remember passwords opens up a (small) +security hole in your system. Obviously, &kdesu; does not allow +anybody but your user id to use the passwords, but, if done without +caution, this would lowers root's security level to that of a +normal user (you). A hacker who breaks into your account, would get +root access. &kdesu; tries +to prevent this. The security scheme it uses is, in my opinion at +least, reasonably safe and is explained here. + +&kdesu; uses a daemon, called +kdesud. The daemon listens to a &UNIX; +socket in /tmp for commands. The mode of the +socket is 0600 so that only your user id can connect to it. If +password keeping is enabled, &kdesu; executes commands through this +daemon. It writes the command and root's password to the socket and the +daemon executes the command using su, as describe +before. After this, the command and the password are not thrown +away. Instead, they are kept for a specified amount of time. This is +the timeout value from in the control module. If another request for +the same command is coming within this time period, the client does +not have to supply the password. To keep hackers who broke into your +account from stealing passwords from the daemon (for example, by +attaching a debugger), the daemon is installed set-group-id +nogroup. This should prevent all normal users (including you) from +getting passwords from the kdesud +process. Also, the daemon sets the DISPLAY environment +variable to the value it had when it was started. The only thing a +hacker can do is execute an application on your display. + +One weak spot in this scheme is that the programs you execute +are probably not written with security in mind (like setuid +root programs). This means +that they might have buffer overruns or other problems and a hacker +could exploit those. + +The use of the password keeping feature is a tradeoff between +security and comfort. I encourage you to think it over and decide for +yourself if you want to use it or not. + + + + + +Author + +&kdesu; + +Copyright 2000 &Geert.Jansen; + +&kdesu; is written by &Geert.Jansen;. It is somewhat based on +Pietro Iglio's &kdesu;, version 0.3. Pietro and I agreed that I will +maintain this program in the future. + +The author can be reached through email at &Geert.Jansen.mail;. +Please report any bugs you find to me so that I can fix them. If you +have a suggestion, feel free to contact me. + +&underFDL; +&underArtisticLicense; + + + + + + diff --git a/doc/kdesu/man-kdesu.1.docbook b/doc/kdesu/man-kdesu.1.docbook new file mode 100644 index 000000000..b9c5ac4ca --- /dev/null +++ b/doc/kdesu/man-kdesu.1.docbook @@ -0,0 +1,179 @@ + + +]> + + + +KDE User's Manual +&Lauri.Watts; &Lauri.Watts.mail; +Jun 7, 2005 +K Desktop Environment + + + +kdesu +1 + + + +kdesu +Runs a program with elevated privileges + + + + +kdesu + + + + file + icon name + + priority + + + + +user + + +command arg1 + arg2 + + + +kdesu +KDE Generic Options +Qt Generic Options + + + + +Description +&kdesu; is a graphical front end for the +&UNIX; su command for the K Desktop Environment. +It allows you to run a program as different user by supplying the +password for that user. &kdesu; is an unprivileged program; it uses +the system's su. + +&kdesu; has one additional feature: it can optionally remember passwords +for you. If you are using this feature, you only need to enter the +password once for each command. + +This program is meant to be started from the command line or +from .desktop files. + + + +Options + + + + +This specifies the program to run as root. It has to be passed +in one argument. So if, for example, you want to start a new file manager, you +would enter at the prompt: kdesu + + + +Show debug information. + + + +This option allow efficient use of &kdesu; in +.desktop files. It tells &kdesu; to examine the +file specified by file. If this file is +writable by the current user, &kdesu; will execute the command as the +current user. If it is not writable, the command is executed as user +user (defaults to root). +file is evaluated like this: if +file starts with a /, it is +taken as an absolute filename. Otherwise, it is taken as the name of a +global &kde; configuration file. For example: to configure the K display +manager, kdm, you could issue +kdesu + + + icon name +Specify icon to use in the password dialog. You may specify +just the name, without any extension. + + + + + +Do not keep the password. This disables the keep +password checkbox in the password dialog. + + + priority + +Set priority value. The priority is an arbitrary number between 0 and +100, where 100 means highest priority, and 0 means lowest. The default is +50. + + + + +Use realtime scheduling. + + + + + +Stop the kdesu daemon. This is the daemon that caches +successful passwords in the background. This feature may also be disabled with + when &kdesu; is initially run. + + + +Enable terminal output. This disables password keeping. This is +largely for debugging purposes; if you want to run a console mode app, use the +standard su instead. + + + user +While the most common use for &kdesu; is to run a command as +the superuser, you can supply any user name and the appropriate +password. + + + + + + + + +See Also +su(1) + +More detailed user documentation is available from help:/kdesu +(either enter this URL into &konqueror;, or run +khelpcenter +help:/kdesu). + + + + +Examples +Run kfmclient as user jim, and show the &konqueror; icon in the +password dialog: +kdesu kfmclient + + + + +Authors +&kdesu; was written by +GeertJansen jansen@kde.org +and PietroIglio +iglio@fub.it. + + + + diff --git a/doc/kdm/Makefile.am b/doc/kdm/Makefile.am new file mode 100644 index 000000000..c04fe0908 --- /dev/null +++ b/doc/kdm/Makefile.am @@ -0,0 +1,6 @@ +conf_def = $(top_srcdir)/kdm/config.def +ref: $(conf_def) $(top_srcdir)/kdm/confproc.pl + $(PERL) -w $(top_srcdir)/kdm/confproc.pl --doc $(conf_def) kdmrc-ref.docbook + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kdm/index.docbook b/doc/kdm/index.docbook new file mode 100644 index 000000000..1a127a506 --- /dev/null +++ b/doc/kdm/index.docbook @@ -0,0 +1,1472 @@ + + + + kdmrc"> + ksmserver"> + kdesktop"> + XDMCP"> + xdm"> + + + +]> + + + +The &kdm; Handbook + + + +&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail; + + + + + + + +2000 +&Neal.Crook; + + + +2002 +&Oswald.Buddenhagen; + + + +2003 +&Lauri.Watts; + + +2003-03-01 +0.05.02 + + +This document describes &kdm; the &kde; Display Manager. &kdm; +is also known as the Login Manager. + + + +KDE +kdm +xdm +display manager +login manager + + + + + +Introduction + +&kdm; provides a graphical interface that allows you to log in to a +system. It prompts for login (username) and password, authenticates the user +and starts a session. &kdm; is superior to &xdm;, the X +Display Manager, in a number of ways. + + + + + + + +Quick Start Guide + +This is a quick start guide for users who fit the following +pattern: + + + +X is configured and works with the command +startx from the commandline. + + +Each user will generally only use a single window manager or +desktop environment, and does not change this choice very +often, or is comfortable editing a single text file in order to change +their choice. + + + +This scenario will be sufficient for many environments where a single +user or several users normally boot the computer and log into their +preferred environment. + + +Setting up a Default Session + +Create or open the file ~/.xinitrc +If you already have a working ~/.xinitrc, go to +the next step + + +If one does not already exist, add a line to the +~/.xinitrc to start your preferred window manager +or desktop environment. +For &kde; you should enter: +startkde +For other window managers or desktop environments, you should +look in their documentation for the correct command. + +Make a link as follows: +ln ~/.xinitrc ~/.xsession + + + +At this point, typing startx +on the commandline should start X, with a &kde; session. The next task is +to try &kdm;. + +As root, type +kdm at the prompt. + +You should see a login window, which is described more fully in . + +Typing your normal username and password in the fields provided, and +leaving selected as the session type should now +open a &kde; session for your user. + +If you have other users to configure, you should repeat the procedure +above for each of them. + + +This is a quick guide to getting up and running only. You probably +will want to customize &kdm; further, for example, to hide the names of the +system accounts, to allow further sessions, and much more. Please read +through the rest of this manual to find out how to do these things. + + + + + +The Login Window + + The user interface to &kdm; consists of two dialog boxes. The main +dialog box has these controls: + + + +A Username: field for you to enter your +username. + + + +A Password: field for you to enter your +password. + + + +(Optionally) a graphical image of each user (for example, a digitized +photograph). Clicking on an image is equivalent to typing the associated +username into the Username: field. (This feature is an +imitation of the login box on &IRIX;). + + + +A Menu drop down box that allows &kdm; to be used +to start sessions with various different window managers or desktop +environments installed on the system. + + + +(Optionally) a region to the right of the +Username:, Password: and +Session Type: fields which can be used to display +either a static image or an analog clock. + + + +A Login button that validates the +username/password combination and attempts to start a session of the +selected type. + + + +A Clear button that clears the text from +the Login and Pass +fields. + + + +A Menu button that opens an action menu +with the following items: + + + +(On local displays) A Restart X Server item +that terminates the currently running &X-Server;, starts a new one and +displays the login dialog again. You can use this if the display content +seems to be broken somehow. + + + +(On remote displays) A Close Connection +item that closes the connection to the &XDMCP; server you are currently +connected to. If you got to this server through a host chooser, this will +bring you back to the chooser, otherwise it will only reset the &X-Server; +and bring up the login dialog again. + + + +(Optionally on local displays) A Console +Mode item that terminates the currently running &X-Server; and +leaves you alone with a console login. &kdm; will resume the graphical login +if nobody is logged in at the console for some time. + + + + + +(Optionally) A Shutdown button that displays +the Shutdown dialog box. + + + +The Shutdown dialog box presents a set of +radio buttons that allow one of these options to be selected: + + + +Shutdown + +Shut the system down in a controlled manner, ready for +power-down. + + + +Restart + +Shut the system down and reboot. For systems that use +Lilo, an optional drop down box allows you to +select a particular operating-system kernel to be used for the +reboot. + + + +Restart X Server + +Stop and then restart the X-server. Typically, you might need to use +this option if you have changed your X11 configuration in some way. + + + +Console Mode + +Stop the &X-Server; and return the system to console mode. This is +achieved by bringing the system down to runlevel 3. Typically, the system +manager might need to use this option before upgrading or re-configuring X11 +software. + + + + +Pressing the OK button initiates the selected +action; pressing the Cancel button returns to the +main &kdm; dialog box. + + + + + +Configuring &kdm; + +This chapter assumes that &kdm; is already up and running on your +system, and that you simply want to change its behavior in some way. + +When &kdm; starts up, it reads its configuration from the folder +$KDEDIR/share/config/kdm/ (this may +be /etc/kde3/kdm/ or something else +on your system). + +The main configuration file is &kdmrc;; all other files are +referenced from there and could be stored under any name anywhere on +the system - but usually that would not make much sense for obvious +reasons (one particular exception is referencing configuration files +of an already installed &xdm; - however when a new &kdm; is installed, +it will import settings from those files if it finds an already installed +&xdm;). + +Since &kdm; must run before any user is logged in, it is not +associated with any particular user. Therefore, it is not possible to have +user-specific configuration files; all users share the common &kdmrc;. It +follows from this that the configuration of &kdm; can only be altered by +those users that have write access to +$KDEDIR/share/config/kdm/kdmrc (normally +restricted to system administrators logged in as root). + +You can view the &kdmrc; file currently in use on your system, and you +can configure &kdm; by editing this file. Alternatively, you can use the +graphical configuration tool provided by the &kcontrolcenter; (under +System AdministrationLogin +Manager), which is described in the &kcontrolcenter; help files. + + +The remainder of this chapter describes configuration of &kdm; +via the &kcontrolcenter; module, and the next +chapter describes the options available in &kdmrc; itself. If +you only need to configure for local users, the &kcontrolcenter; module +should be sufficient for your needs. If you need to configure remote +logins, or have multiple &kdm; sessions running, you will need to read +on. + + + + +&Thomas.Tanghus; &Thomas.Tanghus.mail; +&Steffen.Hansen; &Steffen.Hansen.mail; +&Mike.McBride; &Mike.McBride.mail; + + + +The Login Manager &kcontrolcenter; Module + +Using this module, you can configure the &kde; graphical login +manager, &kdm;. You can change how the login screen looks, who has +access using the login manager and who can shutdown the +computer. + +All settings will be written to the configuration file +&kdmrc;, which in its original state has many comments to help you +configure &kdm;. Using this &kcontrolcenter; module will strip these +comments from the file. All available options in &kdmrc; are covered +in . + +The options listed in this chapter are cross referenced with +their equivalents in &kdmrc;. All options available in the &kcontrol; +module are also available directly in &kdmrc; but the reverse is not +true. + +In order to organize all of these options, this module is +divided into several sections: Appearance, +Font, Background, +Shutdown, +Users and +Convenience. + +You can switch between the sections using the tabs at the top of +the window. + +If you are not currently logged in as a superuser, you +will need to click the Administrator Mode... +Button. You will then be asked for a superuser password. Entering a +correct password will allow you to modify the settings of this +module. + + +Appearance + +From this page you can change the visual appearance of &kdm;, +&kde;'s graphical login manager. + +The Greeting: is the title of the login + screen. Setting this is especially useful if you have many servers users + may log in to. You may use various placeholders, which are described + along with the corresponding key + + in &kdmrc;. + + +You can then choose to show either the current system time, a logo or +nothing special in the login box. Make your choice in the radio buttons +labeled Logo area:. This corresponds to in &kdmrc; + +If you chose Show logo you can now choose a +logo: + + + +Drop an image file on the image button. + + +Click on the image button and select a new image from the image chooser +dialog. + + + +If you do not specify a logo the default +$KDEDIR/share/apps/kdm/pics/kdelogo.xpm +will be displayed. + +Normally the login box is centered on the screen. Use the +Position: options if you want it to appear +elsewhere on the screen. You can specify the relative position +(percentage of the screen size) for the center of the login window, +relative to the top left of the display, in the fields labeled +X: and Y: respectively. +These correspond to the key + +in &kdmrc;. + +While &kde;'s style depends on the settings of the user logged +in, the style used by &kdm; can be configured using the GUI +Style: and Color Scheme: options. +These correspond to the keys and in +&kdmrc; respectively. + +Below that, you have a drop down box to choose the language for +your login box, corresponding to setting in +&kdmrc;. + + + + +Font + +From this section of the module you can change the fonts used in the +login window. Only fonts available to all users are available here, not +fonts you have installed on a per user basis. + +You can select three different font styles from the drop down box +(General:, Failures:, +Greeting:). When you click on the +Choose... button a dialog appears from which you can +select the new characteristics for the font style. + + + +The General: font is used in all other places in the +login window. + + +The Failures: font is used when a login +fails. + + +The Greeting: font is the font used for the title +(Greeting String). + + + +You can also check the box labeled Use anti-aliasing for +fonts if you want smoothed fonts in the login dialog. + + + + +Background + +Here you can change the desktop background which will be displayed +before a user logs in. You can have a single color or an image as a +background. If you have an image as the background and select center, the +selected background color will be used around the image if it is not +large enough to cover the entire desktop. + +The background colors and effects are controlled by the options on +the tab labeled Background and you select a +background image and its placement from the options on the tab labeled +Wallpaper. + +To change the default background color(s) simply click either of +the color buttons and select a new color. + +The drop down box above the color buttons provides you with several +different blend effects. Choose one from the list, and it will be +previewed on the small monitor at the top of the window. Your choices +are: + + + +Flat +By choosing this mode, you select one color (using the color +button labeled Color 1), and the entire background is +covered with this one color. + + +Pattern +By choosing this mode, you select two colors (using both color +buttons). You then select a pattern by clicking +Setup. This opens a new dialog window, which gives you +the opportunity to select a pattern. Simply click once on the pattern of your +choice, then click on OK, and &kde; will render the pattern +you selected using the two colors you selected. For more on patterns, see the +section Background: Adding, Removing and Modifying +Patterns. + + +Background Program +By selecting this option, you can have &kde; use an external +program to determine the background. This can be any program of your choosing. +For more information on this option, see the section entitled Background: Using an external program. + + +Horizontal Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 on the left edge of the screen, and slowly transform into the +color selected by Color 2 by the time it gets to the +right edge of the screen. + + +Vertical Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 on the top edge of the screen, and slowly transform into the color +selected by Color 2 as it moves to the bottom of the +screen. + + +Pyramid Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 in each corner of the screen, and slowly transform into the color +selected by Color 2 as it moves to the center of the +screen. + + +Pipecross Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +1 in each corner of the screen, and slowly transform into the color +selected by Color 2 as it moves to the center of the +screen. The shape of this gradient is different then the pyramid +gradient. + + +Elliptic Gradient +By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by Color +2 in the center of the screen, and slowly transform into the color +selected by Color 1 as it moves to the edges, in an +elliptical pattern. + + + +The setup button is only needed for if you select Background +program or Patterns. In these instances, +another window will appear to configure the specifics. +Wallpaper +To select a new background image first, click on the +Wallpapers tab, then you can either select an image from the drop down list labeled Wallpaper or select +Browse... and select an image file from a file +selector. + +The image can be displayed in six different ways: + + +No wallpaper +No image is displayed. Just the background colors. + + +Centered +The image will be centered on the screen. The background colors +will be present anywhere the image does not cover. + + +Tiled +The image will be duplicated until it fills the entire +desktop. The first image will be placed in the upper left corner of the screen, +and duplicated downward and to the right. + + +Center Tiled +The image will be duplicated until it fills the entire +desktop. The first image will be placed in the center of the screen, and +duplicated upward, downward to the right, and to the left. + + +Centered Maxpect +The image will be placed in the center of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio of the +original image. This will provide you with an image that is not distorted. + + + +Scaled +The image will be scaled to fit the desktop. It will be +stretched to fit all four corners. + + + + + + +<guilabel>Shutdown</guilabel> + +Allow Shutdown +Use this drop down box to choose who is allowed to shut down: + + +Nobody: No one can shutdown the computer using +&kdm;. You must be logged in, and execute a command. + + +Everybody: Everyone can shutdown the computer using +&kdm;. + +Only Root: &kdm; requires that the +root password be entered before shutting down the +computer. + + +You can independently configure who is allowed to issue a +shutdown command for the Local: and +Remote: users. + +Commands Use these text fields to +define the exact shutdown command. The +Halt: command defaults to +/sbin/halt. The Restart: command +defaults to +/sbin/reboot. + +When Show boot options is enabled, &kdm; +will on reboot offer you options for the lilo boot manager. For this +feature to work, you will need to supply the correct paths to your +lilo command and to lilo's map file. Note that this +option is not available on all operating systems. + + + + +Users + +From here you can change the way users are represented in the +login window. + +You may disable the user list in &kdm; entirely in the +Show Users section. You can choose from: + + + +Show List + +Only show users you have specifically enabled in the list +alongside +If you do not check this box, no list will be shown. This is the most secure setting, since an +attacker would then have to guess a valid login name as well as a +password. It's also the preferred option if you have more than a +handful of users to list, or the list itself would become +unwieldy. + + + +Inverse selection + +Allows you to intead select a list of users that should +not be shown, and all other users will be +listed. + + + + +Independently of the users you specify by name, you can use the +System UIDs to specify a range of valid +UIDs that are shown in the list. By default user +id's under 1000, which are often system or daemon users, and user id's +over 65000, are not shown. + +You can also enable the Sort users +checkbox, to have the user list sorted alphabetically. If this is +disabled, users will appear in the order they are listed in the +password file. &kdm; will also autocomplete user names if you enable the +Autocompletion option. + +If you choose to show users, then the login window will show +images (which you select), of a list of users. When someone is ready +to login, they may select their user name/image, enter their password, +and they are granted access. + +If you permit a user image, then you can configure the source +for those images. + +You can configure the admin picture here, for each user on the +system. Depending on the order selected above, users may be able to +override your selection. + +If you choose not to show users, then the login window will be +more traditional. Users will need to type their username and password +to gain entrance. This is the preferred way if you have many users on +this terminal. + + + + +Convenience + +In the convenience tab you can configure +some options that make life easier for lazy people, like automatic +login or disabling passwords. + +Please think more than twice before using these +options. Every option in the Convenience tab is +well-suited to seriously compromise your system security. Practically, +these options are only to be used in a completely non-critical +environment, ⪚ a private computer at home. + + +Automatic Login + +Automatic login will give anyone access to a certain account on +your system without doing any authentication. You can enable it using +the option Enable Auto-login. + +You can choose the account to be used for automatic login from +the list labeled User:. + + + + +<guilabel>Password-Less Login</guilabel> + +Using this feature, you can allow certain users to login without +having to provide their password. Enable this feature using the +Enable Password-less logins option. + +Below this option you'll see a list of users on the system. +Enable password-less login for specific users by checking the checkbox +next to the login names. By default, this feature is disabled for +all users. + +Again, this option should only be used in a safe +environment. If you enable it on a rather public system you should +take care that only users with heavy access restrictions are granted +password-less login, ⪚ +guest. + +You can also choose which user is preselected +when &kdm; starts. The default is None, but you +can choose Previous to have &kdm; default to the +last successfully logged in user, or you can +Specify a particular user to always be selected +from the list. You can also have &kdm; set the focus to the password +field, so that when you reach the &kdm; login screen, you can type the +password immediately. + +The Automatically login after X server crash +option allows you to skip the authentication procedure when your X +server accidentally crashed. + + + + + + + + + +&kdmrc-ref; + + + +Configuring your system to use &kdm; + +This chapter assumes that your system is already configured to +run the &X-Window;, and that you only need to reconfigure it to +allow graphical login. + + +Setting up &kdm; + +The fundamental thing that controls whether your computer boots to a +terminal prompt (console mode) or a graphical login prompt is the default +runlevel. The runlevel is set by the program /sbin/init under the control of the +configuration file /etc/inittab. The default runlevels +used by different &UNIX; systems (and different &Linux; distributions) vary, +but if you look at /etc/inittab the start of it should +be something like this: + +# Default runlevel. The runlevels used by RHS are: +# 0 - halt (Do NOT set initdefault to this) +# 1 - Single user mode +# 2 - Multiuser, without NFS +# 3 - Full multiuser mode +# 4 - unused +# 5 - X11 +# 6 - reboot (Do NOT set initdefault to this) + +id:3:initdefault: + + +All but the last line of this extract are comments. The comments +show that runlevel 5 is used for X11 and that runlevel 3 is used for +multi-user mode without X11 (console mode). The final line specifies +that the default runlevel of the system is 3 (console mode). If your +system currently uses graphical login (for example, using &xdm;) its +default runlevel will match the runlevel specified for X11. + +The runlevel with graphical login (&xdm;) for some common &Linux; +distributions is: + + +5 for &RedHat; 3.x and later, and for &Mandrake; +4 for Slackware +3 for &SuSE;. 4.x and 5.x + + +The first step in configuring your system is to ensure that you +can start &kdm; from the command line. Once this is working, you can +change your system configuration so that &kdm; starts automatically +each time you reboot your system. + +To test &kdm;, you must first bring your system to a runlevel +that does not run &xdm;. To do so, issue a command like this: + +/sbin/init + +Instead of the number you should specify the +appropriate runlevel for console mode on your system. + +If your system uses Pluggable Authentication Modules +(PAM), which is normal with recent &Linux; and &Solaris; +systems, you should check that your PAM configuration permits +login through the service named kde. If you previously used +&xdm; successfully, you should not need to make any +changes to your PAM configuration in order to use +&kdm;. /etc/pam.conf or +/etc/pam.d/kde. Information on configuring +PAM is beyond the scope of this handbook, but +PAM comes with comprehensive documentation (try looking in +/usr/share/doc/*pam*/html/). + +Now it's time for you to test &kdm; by issuing the following +command: + +kdm + + +If you get a &kdm; login dialog and you are able to log in, +things are going well. The main thing that can go wrong here is that +the run-time linker might not find the shared &Qt; or &kde; libraries. +If you have a binary distribution of the &kde; libraries, make sure +&kdm; is installed where the libraries believe &kde; is installed and +try setting some environment variables to point to your &kde; and &Qt; +libraries. + +For example: + +export + +export + +export + +export + + + +If you are still unsuccessful, try starting &xdm; instead, to +make sure that you are not suffering from a more serious X +configuration problem. + +When you are able to start &kdm; successfully, you can start to +replace &xdm; by &kdm;. Again, this is distribution-dependent. + + + +For &RedHat;, edit /etc/inittab, look for this + line: +x:5:respawn:/usr/X11/bin/xdm -nodaemon +and replace with: +x:5:respawn:/opt/kde/bin/kdm +This tells init(8) to respawn &kdm; when the +system is in run level 5. Note that &kdm; does not need the + option. + + +For &Mandrake;, the X11 runlevel in +/etc/inittab invokes the shell script +/etc/X11/prefdm, which is set up to select from +amongst several display managers, including &kdm;. Make sure that all +the paths are correct for your installation. + + +For &SuSE;, edit /sbin/init.d/xdm to add a +first line: + +. /etc/rc.config +DISPLAYMANAGER=kdm +export DISPLAYMANAGER + +For FreeBSD, edit /etc/ttys and find +the line like this: +ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure +and edit it to this: +ttyv8 "/usr/local/bin/kdm" xterm on secure + + +Most other distributions are a variation of one of +these. + + +At this stage, you can test &kdm; again by bringing your system +to the runlevel that should now run &kdm;. To do so, issue a command +like this: + +/sbin/init + + +Instead of the number you should specify the +appropriate runlevel for running X11 on your system. + +The final step is to edit the initdefault +entry in /etc/inittab to specify the appropriate +runlevel for X11. + +Before you make this change, ensure that you have a way +to reboot your system if a problem occurs. This might be a +rescue floppy-disk provided by your operating system +distribution or a specially-designed rescue +floppy-disk, such as tomsrtbt. Ignore this advice +at your peril. + +This usually involves changing the line: +id:3:initdefault: +to +id:5:initdefault: + +When you reboot your system, you should end up with the +graphical &kdm; login dialog. + +If this step is unsuccessful the most likely problem is that the +environment used at boot time differs from the environment that you used for +testing at the command line. If you are trying to get two versions of &kde; +to co-exist, be particularly careful that the settings you use for your +PATH and LD_LIBRARY_PATH environment variables +are consistent, and that the startup scripts are not over-riding them in +some way. + + + + + + +Supporting multiple window managers + +&kdm; detects most available window manager and desktop environments when +it is run. Installing a new one should make it automatically available in +the &kdm; main dialog Session Type:. + +If you have a very new window manager, or something that &kdm; does +not support, the first thing you should check is that the application to be +run is in the PATH and has not been renamed during the +install into something unexpected. + +If the case is that the application is too new and not yet supported +by &kdm;, you can quite simply add a new session. + +The sessions are defined in .desktop files in +$KDEDIR/share/apps/kdm/sessions. +You can simply add an appropriately named .desktop file in this directory. The fields +are: + +[Desktop Entry] +Encoding=UTF-8 This is fixed to and +may be omitted +Type=XSession This is fixed to and +may be omitted +Exec=executable name Passed to +eval exec in a Bourne shell +TryExec=executable name Supported +but not required +Name=name to show in the &kdm; session list + +There are also three magic: + + + +default + + +The default session for &kdm; is normally &kde; but can be configured by the +system administrator. + + + + +custom + + +The Custom session will run the users ~/.xsession if it exists. + + + + +failsafe + + +Failsafe will run a very plain session, and is useful only for debugging +purposes. + + + + + +To override a session type, copy the .desktop file from the data dir +to the config dir and edit it at will. Removing the shipped session types +can be accomplished by shadowing them with .desktop files +containing Hidden=true. For the magic session types no .desktop files exist +by default, but &kdm; pretends they would, so you can override them like any +other type. I guess you already know how to add a new session type by +now. ;-) + + + + +Using &kdm; for Remote Logins (&XDMCP;) + +&XDMCP; is the Open Group standard, the X Display Manager +Control Protocol. This is used to set up connections between +remote systems over the network. + +&XDMCP; is useful in multiuser situations where there are users +with workstations and a more powerful server that can provide the +resources to run multiple X sessions. For example, &XDMCP; is a good +way to reuse old computers - a Pentium or even 486 computer with 16 Mb +RAM is sufficient to run X itself, and using &XDMCP; such a computer can +run a full modern &kde; session from a server. For the server part, +once a single &kde; (or other environment) session is running, running +another one requires very few extra resources. + +However, allowing another method of login to your machine +obviously has security implications. You should run this service only +if you need to allow remote X Servers to start login sessions on your +system. Users with a single &UNIX; computer should not need to run +this. + + + + +Advanced Topics + + +Command Sockets + +This is a feature you can use to remote-control &kdm;. It's mostly +intended for use by &ksmserver; and &kdesktop; from a running session, but +other applications are possible as well. + +The sockets are &UNIX; domain sockets which live in subdirectories of the +directory specified by =. The subdir is the key to +addressing and security; the sockets all have the file name +socket and file permissions +rw-rw-rw- (0666). This is because some systems don't care +for the file permission of the socket files. + +There are two types of sockets: the global one (dmctl) and the +per-display ones (dmctl-<display>). + +The global one's subdir is owned by root, the subdirs of the per-display +ones' are owned by the user currently owning the session (root or the +logged in user). Group ownership of the subdirs can be set via FifoGroup=, +otherwise it is root. The file permissions of the subdirs are rwxr-x--- +(0750). + +The fields of a command are separated by tabs (\t), the +fields of a list are separated by spaces, literal spaces in list fields are +denoted by \s. + +The command is terminated by a newline (\n). + +The same applies to replies. The reply on success is +ok, possibly followed by the requested +information. The reply on error is an errno-style word (⪚ +perm, noent, &etc;) +followed by a longer explanation. + + +Global commands: + +login +(now | schedule) user password +[session_arguments] + +login user at specified display. if now is +specified, a possibly running session is killed, otherwise the login is done +after the session exits. session_arguments are printf-like escaped contents +for .dmrc. Unlisted keys will default to previously saved values. + + + + + +Per-display commands: + +lock + +The display is marked as locked. If the &X-Server; crashes in this +state, no auto-relogin will be performed even if the option is on. + + + +unlock + +Reverse the effect of lock, and re-enable +auto-relogin. + + + +suicide + +The currently running session is forcibly terminated. No auto-relogin +is attempted, but a scheduled "login" command will be executed. + + + + + +Commands for all sockets + +caps + +Returns a list of this socket's capabilities: + + + +&kdm; + +identifies &kdm;, in case some other DM implements this protocol, +too + + + +list, lock, +suicide, login + +The respective command is supported + + + +bootoptions + +The listbootoptions command and the + to shutdown are supported + + + +shutdown <list> + +shutdown is supported and allowed for the listed +users (a comma separated list.) * means all +authenticated users. + + + +nuke <list> + +Forced shutdown may be performed by the listed users. + + + +nuke + +Forced shutdown may be performed by everybody + + + +reserve <number> + +Reserve displays are configured, and number +are available at this time + + + + +list [all | +alllocal] + +Return a list of running sessions. By default all active sessions are +listed. if all is specified, passive sessions are +listed as well. If alllocal is specified, passive +sessions are listed as well, but all incoming remote sessions are +skipped. +Each session entry is a comma separated tuple of: + +Display or TTY name +VT name for local sessions +Logged in user's name, empty for passive sessions and +outgoing remote sessions (local chooser mode) +Session type or <remote> for outgoing +remote sessions, empty for passive sessions. +A Flag field: +* for the display belonging +to the requesting socket. +! for sessions that cannot be killed by the +reqeusting socket. + + + +New fields may be added in the future. + + + + +reserve [timeout in +seconds] + +Start a reserve login screen. If nobody logs in within the specified +amount of time (one minute by default), the display is removed again. When +the session on the display exits, the display is removed, too. +Permitted only on sockets of local displays and the global +socket. + + + + +activate +(vt|display) + +Switch to a particular VT (virtual terminal). The VT may be specified +either directly (⪚ vt3) or by a display using it +(eg; :2). +Permitted only on sockets of local displays and the global +socket. + + + + +listbootoptions + +List available boot options. + + + + + +shutdown (reboot | +halt) +[=bootchoice] +(ask|trynow|forcenow|schedule|start +(-1|end +(force|forcemy|cancel)))) + +Request a system shutdown, either a reboot or a halt/poweroff. +An OS choice for the next boot may be specified from the list returned +by listbootoptions +Shutdowns requested from per-display sockets are executed when the +current sessino on that display exits. Such a request may pop up a dialog +asking for confirmation and/or authentication +start is the time for which the shutdown is +scheduled. If it starts with a plus-sign, the current time is added. Zero +means immediately. +end is the latest time at which the shutdown +should be performed if active sessions are still running. If it starts with +a plus-sign, the start time is added. -1 means wait infinitely. If end is +through and active sessions are still running, &kdm; can do one of the +following: + +cancel - give up the +shutdown +force - shut down +nonetheless +forcemy - shut down nonetheless if +all active sessions belong to the requesting user. Only for per-display sockets. + +start and end are +specified in seconds since the &UNIX; epoch. +trynow is a synonym for 0 0 +cancel, forcenow for 0 0 +force and schedule for 0 +-1. +ask attempts an immediate shutdown and +interacts with the user if active sessions are still running. Only for +per-display sockets. + + + + +shutdown cancel +[local|global} + +Cancel a scheduled shutdown. The global socket always cancels the +currently pending shutdown, while per-display sockets default to cancelling +their queued request. + + + + +shutdown status + +Return a list with information about shutdowns. +The entries are a comma-separated tuples of: + + +(global|local) - +pending vs. queued shutdown. A local entry can be returned only by a +per-display socket. + +(halt|reboot) +start +end +("ask"|"force"|"forcemy"|"cancel") +Numeric user ID of the requesting user, -1 for the global +socket. +The next boot OS choice or "-" for none. + +New fields might be added later + + + + + + +There are two ways of using the sockets: + + +Connecting them directly. FifoDir is exported as +$DM_CONTROL; the name of per-display sockets can be derived +from $DISPLAY. + + +By using the kdmctl command (⪚ from within a +shell script). Try kdmctl to find out +more. + + + +Here is an example bash script reboot into FreeBSD: + +if kdmctl | grep -q shutdown; then + IFS=$'\t' + set -- `kdmctl listbootoptions` + if [ "$1" = ok ]; then + fbsd=$(echo "$2" | tr ' ' '\n' | sed -ne 's,\\s, ,g;/freebsd/I{p;q}') + if [ -n "$fbsd" ]; then + kdmctl shutdown reboot "=$fbsd" ask > /dev/null + else + echo "FreeBSD boot unavailable." + fi + else + echo "Boot options unavailable." + fi +else + echo "Cannot reboot system." +fi + + + + + + +Other sources of information + +Since &kdm; is descended from &xdm;, the &xdm; man page may provide useful background +information. For X-related problems try the man pages X and startx. If you have +questions about &kdm; that are not answered by this handbook, take advantage of +the fact the &kdm; is provided under the terms of the &GNU; +General Public License: look at the source code. + + + + + +Credits and License + +&kdm; is derived from, and includes code from, +&xdm; (C) Keith Packard, MIT X Consortium. + +&kdm; 0.1 was written by &Matthias.Ettrich;. Later versions till &kde; +2.0.x were written by &Steffen.Hansen;. Some new features for &kde; 2.1.x and +a major rewrite for &kde; 2.2.x made by &Oswald.Buddenhagen;. + +Other parts of the &kdm; code are copyright by the authors, and +licensed under the terms of the &GNU; +GPL. Anyone is allowed to change &kdm; and redistribute the result +as long as the names of the authors are mentioned. + +&kdm; requires the &Qt; library, which is copyright Troll Tech AS. + +Documentation contributors: + + +Documentation written by &Steffen.Hansen; +stefh@dit.ou.dk + +Documentation extended by Gregor +Zumsteinzumstein@ssd.ethz.ch. Last update August 9, +1998 + +Documentation revised for &kde; 2 by &Neal.Crook; &Neal.Crook.mail;. Last update August 6, 2000 + +Documentation extended and revised for &kde; 2.2 by &Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;. Last update August, +2001 + + + +Documentation copyright &Steffen.Hansen;, Gregor Zumstein, &Neal.Crook; +and &Oswald.Buddenhagen;. This document also includes large parts of the &xdm; +man page, which is © Keith Packard. + + + +&underFDL; +&underGPL; + + + + +Glossary + + +greeter +The greeter is the login dialog, &ie; the part of &kdm; +which the user sees. + + + + +entropy +The entropy of a system is the measure of its +unpredictability. This is used during the generation of random numbers. + + + + + + diff --git a/doc/kdm/kdmrc-ref.docbook b/doc/kdm/kdmrc-ref.docbook new file mode 100644 index 000000000..9ebcfbdd3 --- /dev/null +++ b/doc/kdm/kdmrc-ref.docbook @@ -0,0 +1,2316 @@ + + + +The Files &kdm; Uses for Configuration + +This chapter documents the files that control &kdm;'s behavior. +Some of this can be also controlled from the &kcontrol; module, but +not all. + + +&kdmrc; - The &kdm; master configuration file + +The basic format of the file is INI-like. +Options are key/value pairs, placed in sections. +Everything in the file is case sensitive. +Syntactic errors and unrecognized key/section identifiers cause &kdm; to +issue non-fatal error messages. + +Lines beginning with # are comments; empty lines +are ignored as well. + +Sections are denoted by +[Name of Section]. + + +You can configure every X-display individually. +Every display has a display name, which consists of a host name +(which is empty for local displays specified in +or ), a colon, and a display number. +Additionally, a display belongs to a +display class (which can be ignored in most cases). + +Sections with display-specific settings have the formal syntax +[X- host [ : number [ _ class ] ] - sub-section ] + +All sections with the same sub-section +make up a section class. + +You can use the wildcard * (match any) for +host, number, +and class. You may omit trailing components; +they are assumed to be * then. The host part may be a +domain specification like .inf.tu-dresden.de +or the wildcard + (match non-empty). + +From which section a setting is actually taken is determined by +these rules: + + + +An exact match takes precedence over a partial match (for the +host part), which in turn takes precedence over a wildcard +(+ taking precendence over *). + + + +Precedence decreases from left to right for equally exact matches. + + + + + +Example: display name myhost.foo:0, class dpy + + + +[X-myhost.foo:0_dpy] precedes + + +[X-myhost.foo:0_*] (same as [X-myhost.foo:0]) precedes + + +[X-myhost.foo:*_dpy] precedes + + +[X-myhost.foo:*_*] (same as [X-myhost.foo]) precedes + + +[X-.foo:*_*] (same as [X-.foo]) precedes + + +[X-+:0_dpy] precedes + + +[X-*:0_dpy] precedes + + +[X-*:0_*] (same as [X-*:0]) precedes + + +[X-*:*_*] (same as [X-*]). + + +These sections do not match this display: +[X-hishost], [X-myhost.foo:0_dec], [X-*:1], [X-:*] + + + + + + + +Common sections are [X-*] (all displays), [X-:*] (all local displays) +and [X-:0] (the first local display). + +The format for all keys is + = value. +Keys are only valid in the section class they are defined for. +Some keys do not apply to particular displays, in which case they are ignored. + + +If a setting is not found in any matching section, the default +is used. + +Special characters need to be backslash-escaped (leading and trailing +spaces (\s), tab (\t), linefeed +(\n), carriage return (\r) and the +backslash itself (\\)). +In lists, fields are separated with commas without whitespace in between. + +Some command strings are subject to simplified sh-style word splitting: +single quotes (') and double quotes (") +have the usual meaning; the backslash quotes everything (not only special +characters). Note that the backslashes need to be doubled because of the +two levels of quoting. + +A pristine &kdmrc; is very thoroughly commented. +All comments will be lost if you change this file with the +kcontrol frontend. + + + +The [General] section of &kdmrc; + + +This section contains global options that do not fit into any specific section. + + + + + + + + +This option exists solely for the purpose of clean automatic upgrades. +Do not change it, you may interfere with future +upgrades and this could result in &kdm; failing to run. + + + + + + + + +List of displays (&X-Server;s) permanently managed by &kdm;. Displays with a +hostname are foreign displays which are expected to be already running, +the others are local displays for which &kdm; starts an own &X-Server;; +see . Each display may belong to a display class; +append it to the display name separated by an underscore. +See for the details. + +The default is :0. + + + + + + + +List of on-demand displays. See for syntax. + +Empty by default. + + + + + + + +List of Virtual Terminals to allocate to &X-Server;s. For negative numbers the +absolute value is used, and the VT will be allocated only +if the kernel says it is free. If &kdm; exhausts this list, it will allocate +free VTs greater than the absolute value of the last entry +in this list. +Currently Linux only. + +Empty by default. + + + + + + + +This option is for operating systems (OSs) with support +for virtual terminals (VTs), by both &kdm; and the +OSs itself. +Currently this applies only to Linux. + +When &kdm; switches to console mode, it starts monitoring all +TTY lines listed here (without the leading +/dev/). +If none of them is active for some time, &kdm; switches back to the X login. + +Empty by default. + + + + + + + +The filename specified will be created to contain an ASCII representation +of the process ID of the main &kdm; process; the PID will not be stored +if the filename is empty. + +Empty by default. + + + + + + + +This option controls whether &kdm; uses file locking to keep multiple +display managers from running onto each other. + +The default is true. + + + + + + + +This names a directory under which &kdm; stores &X-Server; authorization +files while initializing the session. &kdm; expects the system to clean up +this directory from stale files on reboot. + +The authorization file to be used for a particular display can be +specified with the option in [X-*-Core]. + +The default is /var/run/xauth. + + + + + + + +This boolean controls whether &kdm; automatically re-reads its +configuration files if it finds them to have changed. + +The default is true. + + + + + + + +Additional environment variables &kdm; should pass on to all programs it runs. +LD_LIBRARY_PATH and XCURSOR_THEME are good candidates; +otherwise, it should not be necessary very often. + +Empty by default. + + + + + + + +If the system has no native entropy source like /dev/urandom (see +) and no entropy daemon like EGD (see + and ) is running, +&kdm; will fall back to its own pseudo-random number generator +that will, among other things, successively checksum parts of this file +(which, obviously, should change frequently). + +This option does not exist on Linux and various BSDs. + +The default is /dev/mem. + + + + + + + +If the system has no native entropy source like /dev/urandom (see +), read random data from a Pseudo-Random +Number Generator Daemon, +like EGD (http://egd.sourceforge.net) via this UNIX domain socket. + +This option does not exist on Linux and various BSDs. + +Empty by default. + + + + + + + +Same as , only use a TCP socket on localhost. + + + + + + + + +The path to a character device which &kdm; should read random data from. +Empty means to use the system's preferred entropy device if there is one. + +This option does not exist on OpenBSD, as it uses the arc4_random +function instead. + +Empty by default. + + + + + + + +The directory in which the command FiFos should +be created; make it empty to disable them. + +The default is /var/run/xdmctl. + + + + + + + +The group to which the global command FiFo should belong; +can be either a name or a numerical ID. + + + + + + + + +The directory in which &kdm; should store persistent working data; such data +is, for example, the previous user that logged in on a particular display. + +The default is /var/lib/kdm. + + + + + + + +The directory in which &kdm; should store users' .dmrc files. This is only +needed if the home directories are not readable before actually logging in +(like with AFS). + +Empty by default. + + + + + + + + +The [Xdmcp] section of &kdmrc; + + +This section contains options that control &kdm;'s handling of +&XDMCP; requests. + + + + + + + + +Whether &kdm; should listen to incoming &XDMCP; requests. + +The default is true. + + + + + + + +This indicates the UDP port number which &kdm; uses to listen for incoming +&XDMCP; requests. Unless you need to debug the system, leave this with its +default value. + +The default is 177. + + + + + + + +XDM-AUTHENTICATION-1 style &XDMCP; authentication requires a private +key to be shared between &kdm; and the terminal. This option specifies +the file containing those values. Each entry in the file consists of a +display name and the shared key. + +Empty by default. + + + + + + + +To prevent unauthorized &XDMCP; service and to allow forwarding of &XDMCP; +IndirectQuery requests, this file contains a database of hostnames which +are either allowed direct access to this machine, or have a list of hosts +to which queries should be forwarded to. The format of this file is +described in . + +The default is ${kde_confdir}/kdm/Xaccess. + + + + + + + +Number of seconds to wait for the display to respond after the user has +selected a host from the chooser. If the display sends an &XDMCP; +IndirectQuery within this time, the request is forwarded to the chosen +host; otherwise, it is assumed to be from a new session and the chooser +is offered again. + +The default is 15. + + + + + + + +When computing the display name for &XDMCP; clients, the name resolver will +typically create a fully qualified host name for the terminal. As this is +sometimes confusing, &kdm; will remove the domain name portion of the host +name if it is the same as the domain name of the local host when this option +is enabled. + +The default is true. + + + + + + + +Use the numeric IP address of the incoming connection on multihomed hosts +instead of the host name. This is to avoid trying to connect on the wrong +interface which might be down at this time. + +The default is false. + + + + + + + +This specifies a program which is run (as +root) when an &XDMCP; +DirectQuery or BroadcastQuery is received and this host is configured +to offer &XDMCP; display management. The output of this program may be +displayed in a chooser window. If no program is specified, the string +Willing to manage is sent. + +Empty by default. + + + + + + + + +The [Shutdown] section of &kdmrc; + + +This section contains global options concerning system shutdown. + + + + + + + + +The command (subject to word splitting) to run to halt/poweroff the system. + +The default is something reasonable for the system on which &kdm; was built, like +/sbin/shutdown  now. + + + + + + + + +The command (subject to word splitting) to run to reboot the system. + +The default is something reasonable for the system &kdm; on which was built, like +/sbin/shutdown  now. + + + + + + + + +Whether it is allowed to shut down the system via the global command FiFo. + +The default is false. + + + + + + + +Whether it is allowed to abort active sessions when shutting down the +system via the global command FiFo. + +This will have no effect unless is enabled. + +The default is true. + + + + + + + +The boot manager &kdm; should use for offering boot options in the +shutdown dialog. + + + +None +no boot manager + + +Grub +Grub boot manager + + +Lilo +Lilo boot manager (Linux on i386 & x86-64 only) + + +The default is None. + + + + + + + + +The [X-*-Core] section class of &kdmrc; + + +This section class contains options concerning the configuration +of the &kdm; backend (core). + + + + + + + + +See . + +The default is 15. + + + + + + + +See . + +The default is 120. + + + + + + + +These options control the behavior of &kdm; when attempting to open a +connection to an &X-Server;. is the length +of the pause (in seconds) between successive attempts, + is the number of attempts to make and + is the amount of time to spend on a +connection attempt. After attempts have been +made, or if seconds elapse in any particular +connection attempt, the start attempt is considered failed. + +The default is 5. + + + + + + + +How many times &kdm; should attempt to start a foreign +display listed in before giving up +and disabling it. +Local displays are attempted only once, and &XDMCP; displays are retried +indefinitely by the client (unless the option +was given to the &X-Server;). + +The default is 4. + + + + + + + +How many times &kdm; should attempt to start up a local &X-Server;. +Starting up includes executing it and waiting for it to come up. + +The default is 1. + + + + + + + +How many seconds &kdm; should wait for a local &X-Server; to come up. + +The default is 15. + + + + + + + +The command line to start the &X-Server;, without display number and VT spec. +This string is subject to word splitting. + +The default is something reasonable for the system on which &kdm; was built, +like /usr/X11R6/bin/X. + + + + + + + + +Additional arguments for the &X-Server;s for local sessions. +This string is subject to word splitting. + +Empty by default. + + + + + + + +Additional arguments for the &X-Server;s for remote sessions. +This string is subject to word splitting. + +Empty by default. + + + + + + + +The VT the &X-Server; should run on. + should be used instead of this option. +Leave it zero to let &kdm; assign a VT automatically. +Set it to -1 to avoid assigning a VT +alltogether - this is required for setups with multiple physical consoles. +Currently Linux only. + + + + + + + + +This option is for OSs without support for +VTs, either by &kdm; or the OS itself. +Currently this applies to all OSs but Linux. + +When &kdm; switches to console mode, it starts monitoring this +TTY line (specified without the leading +/dev/) for activity. If the line is not used for some time, +&kdm; switches back to the X login. + +Empty by default. + + + + + + + +See . + +The default is 5. + + + + + + + +To discover when remote displays disappear, &kdm; +regularly pings them. + specifies the time (in minutes) between the +pings and specifies the maximum amount of +time (in minutes) to wait for the terminal to respond to the request. If +the terminal does not respond, the session is declared dead and terminated. + +If you frequently use X terminals which can become isolated from +the managing host, you may wish to increase the timeout. The only worry +is that sessions will continue to exist after the terminal has been +accidentally disabled. + +The default is 5. + + + + + + + +Whether &kdm; should restart the local &X-Server; after session exit instead +of resetting it. Use this if the &X-Server; leaks memory or crashes the system +on reset attempts. + +The default is false. + + + + + + + +The signal number to use to reset the local &X-Server;. + +The default is 1 (SIGHUP). + + + + + + + +The signal number to use to terminate the local &X-Server;. + +The default is 15 (SIGTERM). + + + + + + + +Controls whether &kdm; generates and uses authorization for +local &X-Server; connections. +For &XDMCP; displays the authorization requested by the display is used; +foreign non-&XDMCP; displays do not support authorization at all. + +The default is true. + + + + + + + +If is true, use the authorization mechanisms +listed herein. The MIT-MAGIC-COOKIE-1 authorization is always available; +XDM-AUTHORIZATION-1, SUN-DES-1 and MIT-KERBEROS-5 might be available as well, +depending on the build configuration. + +The default is DEF_AUTH_NAME. + + + + + + + +Some old &X-Server;s re-read the authorization file +at &X-Server; reset time, instead of when checking the initial connection. +As &kdm; generates the authorization information just before connecting to +the display, an old &X-Server; would not get up-to-date authorization +information. This option causes &kdm; to send SIGHUP to the &X-Server; +after setting up the file, causing an additional &X-Server; reset to occur, +during which time the new authorization information will be read. + +The default is false. + + + + + + + +This file is used to communicate the authorization data from &kdm; to +the &X-Server;, using the &X-Server; command line +option. It should be kept in a directory which is not world-writable +as it could easily be removed, disabling the authorization mechanism in +the &X-Server;. If not specified, a random name is generated from + and the name of the display. + +Empty by default. + + + + + + + +This option specifies the name of the file to be loaded by +xrdb as the resource database onto the root window +of screen 0 of the display. KDE programs generally do not use +X-resources, so this option is only needed if the +program needs some X-resources. + +Empty by default. + + + + + + + +The xrdb program to use to read the X-resources file +specified in . +The command is subject to word splitting. + +The default is ${x_bindir}/xrdb. + + + + + + + +This string is subject to word splitting. +It specifies a program which is run (as +root) before offering the +greeter window. This may be used to change the appearance of the screen +around the greeter window or to put up other windows (e.g., you may want +to run xconsole here). +The conventional name for a program used here is Xsetup. +See . + +Empty by default. + + + + + + + +This string is subject to word splitting. +It specifies a program which is run (as +root) after the user +authentication process succeeds. +The conventional name for a program used here is Xstartup. +See . + +Empty by default. + + + + + + + +This string is subject to word splitting. +It specifies a program which is run (as +root) after the session +terminates. +The conventional name for a program used here is Xreset. +See . + +Empty by default. + + + + + + + +This string is subject to word splitting. +It specifies the session program to be executed (as the user owning +the session). +The conventional name for a program used here is Xsession. +See . + +The default is ${x_bindir}/xterm -ls -T. + + + + + + + +If the program fails to execute, &kdm; will +fall back to this program. This program is executed with no arguments, +but executes using the same environment variables as the session would +have had (see ). + +The default is ${x_bindir}/xterm. + + + + + + + +The PATH environment variable for +non-root s. + +The default depends on the system &kdm; was built on. + + + + + + + + +The PATH environment variable for all programs but +non-root +s. Note that it is good practice not to include +. (the current directory) into this entry. + +The default depends on the system &kdm; was built on. + + + + + + + + +The SHELL environment variable for all programs but the +. + +The default is /bin/sh. + + + + + + + +When &kdm; is unable to write to the usual user authorization file +($HOME/.Xauthority), it creates a unique file name in this +directory and points the environment variable XAUTHORITY +at the created file. + +The default is /tmp. + + + + + + + +If enabled, &kdm; will automatically restart a session after an &X-Server; +crash (or if it is killed by Alt-Ctrl-BackSpace). Note that enabling this +feature opens a security hole: a secured display lock can be circumvented +(unless &kde;'s built-in screen locker is used). + +The default is false. + + + + + + + +If disabled, do not allow root +(and any other user with UID = 0) to log in directly. + +The default is true. + + + + + + + +If disabled, only users that have passwords assigned can log in. + +The default is true. + + + + + + + +Who is allowed to shut down the system. This applies both to the +greeter and to the command FiFo. + + + +None +no Shutdown... menu entry is shown at all + + +Root +the root password must be entered to shut down + + +All +everybody can shut down the machine + + +The default is All. + + + + + + + +Who is allowed to abort active sessions when shutting down. + + + +None +no forced shutdown is allowed at all + + +Root +the root password must be entered to shut down forcibly + + +All +everybody can shut down the machine forcibly + + +The default is All. + + + + + + + +The default choice for the shutdown condition/timing. + + + +Schedule +shut down after all active sessions exit (possibly at once) + + +TryNow +shut down, if no active sessions are open; otherwise, do nothing + + +ForceNow +shut down unconditionally + + +The default is Schedule. + + + + + + + +How to offer shutdown scheduling options: + + + +Never +not at all + + +Optional +as a button in the simple shutdown dialogs + + +Always +instead of the simple shutdown dialogs + + +The default is Never. + + + + + + + +Enable password-less logins on this display. Use with extreme care! + +The default is false. + + + + + + + +The users that do not need to provide a password to log in. +Items which are prefixed with @ represent all users in the +user group named by that item. +* means all users but +root +(and any other user with UID = 0). +Never list root. + +Empty by default. + + + + + + + +Enable automatic login. Use with extreme care! + +The default is false. + + + + + + + +If true, auto-login after logout. If false, auto-login is performed only +when a display session starts up. + +The default is false. + + + + + + + +The delay in seconds before automatic login kicks in. This is also known as +Timed Login. + + + + + + + + +The user to log in automatically. Never specify root! + +Empty by default. + + + + + + + +The password for the user to log in automatically. This is not required +unless the user is logged into a NIS or Kerberos domain. If you use this +option, you should chmod  kdmrc for obvious reasons. + +Empty by default. + + + + + + + +Immediately lock the automatically started session. This works only with +KDE sessions. + +The default is false. + + + + + + + +A list of directories containing session type definitions. + +The default is ${kde_datadir}/kdm/sessions. + + + + + + + +The file (relative to the user's home directory) to redirect the session +output to. One occurrence of %s in this string will be +substituted with the display name. Use %% to obtain a +literal %. + +The default is .xsession-errors. + + + + + + + +Specify whether &kdm;'s built-in utmp/wtmp/lastlog registration should +be used. If it is not, the tool sessreg should be used +in the and scripts, or, +alternatively, the pam_lastlog module should be used on +PAM-enabled systems. + +The default is true. + + + + + + + + +The [X-*-Greeter] section class of &kdmrc; + + +This section class contains options concerning the configuration +of the &kdm; frontend (greeter). + + + + + + + + +Specify the widget style for the greeter. Empty means to use the +built-in default which currently is Plastik. + +Empty by default. + + + + + + + +Specify the widget color scheme for the greeter. Empty means to use +the built-in default which currently is yellowish grey with some light +blue and yellow elements. + +Empty by default. + + + + + + + +What should be shown in the greeter righthand of the input lines (if + is disabled) or above them (if + is enabled): + + + +None +nothing + + +Logo +the image specified by + + +Clock +a neat analog clock + + +The default is Clock. + + + + + + + +The image to show in the greeter if is +Logo. + +Empty by default. + + + + + + + +The relative coordinates (percentages of the screen size; X,Y) at which +the center of the greeter is put. &kdm; aligns the greeter to the edges +of the screen it would cross otherwise. + +The default is 50,50. + + + + + + + +The screen the greeter should be displayed on in multi-headed and Xinerama +setups. The numbering starts with 0. For Xinerama, it corresponds to the +listing order in the active ServerLayout section of XF86Config; -1 means +to use the upper-left screen, -2 means to use the upper-right screen. + + + + + + + + +The headline in the greeter. An empty greeting means none at all. + +The following character pairs are replaced by their value: + + +%d +name of the current display + + +%h +local host name, possibly with the + domain name + + +%n +local node name, most probably the host name without the + domain name + + +%s +operating system + + +%r +operating system version + + +%m +machine (hardware) type + + +%% +a single % + + + +The default is Welcome to %s at %n. + + + + + + + +Whether the fonts used in the greeter should be antialiased. + +The default is false. + + + + + + + +The font for the greeter headline. + +The default is Serif,20,bold. + + + + + + + +The normal font used in the greeter. + +The default is Sans Serif,10. + + + + + + + +The font used for the Login Failed message. + +The default is Sans Serif,10,bold. + + + + + + + +What to do with the Num Lock modifier for the time the greeter is running: + + + +Off +turn off + + +On +turn on + + +Keep +do not change the state + + +The default is Keep. + + + + + + + +Language and locale to use in the greeter, encoded like $LC_LANG. + +The default is en_US. + + + + + + + +Enable autocompletion in the username line edit. + +The default is false. + + + + + + + +Show a user list with unix login names, real names, and images in the greeter. + +The default is true. + + + + + + + +This option controls which users will be shown in the user view +() and/or offered for autocompletion +(). +If it is Selected, contains +the final list of users. +If it is NotHidden, the initial user list contains all users +found on the system. Users contained in are +removed from the list, just like all users with a UID greater than specified +in and users with a non-zero UID less than +specified in . +Items in and +which are prefixed with @ represent all users in the +user group named by that item. +Finally, the user list will be sorted alphabetically, if + is enabled. + +The default is NotHidden. + + + + + + + +See . + +Empty by default. + + + + + + + +See . + +Empty by default. + + + + + + + +See . + + + + + + + + +See . + +The default is 65535. + + + + + + + +See . + +The default is true. + + + + + + + +If is enabled, this specifies where &kdm; gets the +images from: + + + +AdminOnly +from <>/$USER.face[.icon] + + +PreferAdmin +prefer <>, fallback on $HOME + + +PreferUser +... and the other way round + + +UserOnly +from the user's $HOME/.face[.icon] + + + + +The images can be in any format Qt recognizes, but the filename +must match &kdm;'s expectations: .face.icon should be a +48x48 icon, while .face should be a 300x300 image. +Currently the big image is used only as a fallback and is scaled down, +but in the future it might be displayed full-size in the logo area or a +tooltip. + +The default is AdminOnly. + + + + + + + +See . + +The default is ${kde_datadir}/kdm/faces. + + + + + + + +Specify, if/which user should be preselected for log in: + + + +None +do not preselect any user + + +Previous +the user which successfully logged in last time + + +Default +the user specified in the option + + + + +If is enabled and a user was preselected, +the cursor is placed in the password input field automatically. + +Enabling user preselection can be considered a security hole, +as it presents a valid login name to a potential attacker, so he +only needs to guess the password. On the other hand, +one could set to a fake login name. + + +The default is None. + + + + + + + +See . + +Empty by default. + + + + + + + +See . + +The default is false. + + + + + + + +The password input fields cloak the typed in text. Specify, how to do it: + + + +OneStar +* is shown for every typed +character + + +ThreeStars +*** is shown for every typed +character + + +NoEcho +nothing is shown at all, the cursor does not move + + +The default is OneStar. + + + + + + + +If enabled, &kdm; will automatically start the krootimage +program to set up the background; otherwise, the +program is responsible for the background. + +The default is true. + + + + + + + +The configuration file to be used by krootimage. +It contains a section named [Desktop0] like +kdesktoprc does. Its options are not described +herein; guess their meanings or use the control center. + +The default is ${kde_confdir}/kdm/backgroundrc. + + + + + + + +To improve security, the greeter grabs the &X-Server; and then the keyboard +when it starts up. This option specifies if the &X-Server; grab should be held +for the duration of the name/password reading. When disabled, the &X-Server; +is ungrabbed after the keyboard grab succeeds; otherwise, the &X-Server; is +grabbed until just before the session begins. + +Enabling this option disables and +. + + +The default is false. + + + + + + + +This option specifies the maximum time &kdm; will wait for the grabs to +succeed. A grab may fail if some other X-client has the &X-Server; or the +keyboard grabbed, or possibly if the network latencies are very high. You +should be cautious when raising the timeout, as a user can be spoofed by +a look-alike window on the display. If a grab fails, &kdm; kills and +restarts the &X-Server; (if possible) and the session. + +The default is 3. + + + + + + + +Warn, if a display has no X-authorization. This will be the case if + + + the authorization file for a local &X-Server; could not be created, + + + a remote display from &XDMCP; did not request any authorization or + + + the display is a foreign display specified in + . + + + +The default is true. + + + + + + + +Specify whether the greeter of local displays should start up in host chooser +(remote) or login (local) mode and whether it is allowed to switch to the +other mode. + + + +LocalOnly +only local login possible + + +DefaultLocal +start up in local mode, but allow switching to remote mode + + +DefaultRemote +... and the other way round + + +RemoteOnly +only choice of remote host possible + + +The default is LocalOnly. + + + + + + + +A list of hosts to be automatically added to the remote login menu. +The special name * means broadcast. +Has no effect if is LocalOnly. + +The default is *. + + + + + + + +Use this number as a random seed when forging saved session types, etc. of +unknown users. This is used to avoid telling an attacker about existing users +by reverse conclusion. This value should be random but constant across the +login domain. + + + + + + + + +Enable &kdm;'s built-in xconsole. +Note that this can be enabled for only one display at a time. +This option is available only if &kdm; was configured +with . + +The default is false. + + + + + + + +The data source for &kdm;'s built-in xconsole. +If empty, a console log redirection is requested from +/dev/console. +Has no effect if is disabled. + +Empty by default. + + + + + + + +Specify conversation plugins for the login dialog; the first in the list +is selected initially. +Each plugin can be specified as a base name (which expands to +$kde_modulesdir/kgreet_base) +or as a full pathname. + +Conversation plugins are modules for the greeter which obtain authentication +data from the user. Currently only the classic plugin is +shipped with &kde;; it presents the well-known username and password form. + +The default is classic. + + + + + + + +Same as , but for the shutdown dialog. + +The default is classic. + + + + + + + +A list of options of the form +Key=Value. +The conversation plugins can query these settings; it is up to them what +possible keys are. + +Empty by default. + + + + + + + +Show the Console Login action in the greeter (if / +is configured). + +The default is true. + + + + + + + +Show the Restart X Server/Close Connection action in the greeter. + +The default is true. + + + + + + + +A program to run while the greeter is visible. It is supposed to preload +as much as possible of the session that is going to be started (most +probably). + +Empty by default. + + + + + + + +Whether the greeter should be themed. + +The default is false. + + + + + + + +The theme to use for the greeter. Can point to either a directory or an XML +file. + +Empty by default. + + + + + + + + + + + +Specifying permanent &X-Server;s + +Each entry in the list indicates a +display which should constantly be +managed and which is not using &XDMCP;. This method is typically used only for +local &X-Server;s that are started by &kdm;, but &kdm; can manage externally +started (foreign) &X-Server;s as well, may they run on the +local machine or rather remotely. + +The formal syntax of a specification is + +display name [_display class] + +for all &X-Server;s. Foreign displays differ in having +a host name in the display name, may it be localhost. + +The display name must be something that can +be passed in the option to an X program. This string +is used to generate the display-specific section names, so be careful to match +the names. +The display name of &XDMCP; displays is derived from the display's address by +reverse host name resolution. For configuration purposes, the +localhost prefix from locally running &XDMCP; displays is +not stripped to make them distinguishable from local +&X-Server;s started by &kdm;. + +The display class portion is also used in the +display-specific sections. This is useful if you have a large collection of +similar displays (such as a corral of X terminals) and would like to set +options for groups of them. +When using &XDMCP;, the display is required to specify the display class, +so the manual for your particular X terminal should document the display +class string for your device. If it does not, you can run &kdm; in debug +mode and grep the log for class. + +The displays specified in will not be +started when &kdm; starts up, but when it is explicitly requested via +the command socket (or FiFo). +If reserve displays are specified, the &kde; menu will have a +Start New Session item near the bottom; use that to +activate a reserve display with a new login session. The monitor will switch +to the new display, and you will have a minute to login. If there are no more +reserve displays available, the menu item will be disabled. + +When &kdm; starts a session, it sets up authorization data for the +&X-Server;. For local servers, &kdm; passes + filename +on the &X-Server;'s command line to point it at its authorization data. +For &XDMCP; displays, &kdm; passes the authorization data to the &X-Server; +via the Accept &XDMCP; message. + + + + +&XDMCP; access control + +The file specified by the option provides +information which &kdm; uses to control access from displays requesting service +via &XDMCP;. +The file contains four types of entries: entries which control the response +to Direct and Broadcast queries, entries which +control the response to Indirect queries, macro definitions for +Indirect entries, and entries which control on which network +interfaces &kdm; listens for &XDMCP; queries. +Blank lines are ignored, # is treated as a comment +delimiter causing the rest of that line to be ignored, and \ +causes an immediately following newline to be ignored, allowing indirect host +lists to span multiple lines. + + +The format of the Direct entries is simple, either a +host name or a pattern, which is compared against the host name of the display +device. +Patterns are distinguished from host names by the inclusion of one or more +meta characters; * matches any sequence of 0 or more +characters, and ? matches any single character. +If the entry is a host name, all comparisons are done using network addresses, +so any name which converts to the correct network address may be used. Note +that only the first network address returned for a host name is used. +For patterns, only canonical host names are used in the comparison, so ensure +that you do not attempt to match aliases. +Host names from &XDMCP; queries always contain the local domain name +even if the reverse lookup returns a short name, so you can use +patterns for the local domain. +Preceding the entry with a ! character causes hosts which +match that entry to be excluded. +To only respond to Direct queries for a host or pattern, +it can be followed by the optional NOBROADCAST keyword. +This can be used to prevent a &kdm; server from appearing on menus based on +Broadcast queries. + +An Indirect entry also contains a host name or pattern, +but follows it with a list of host names or macros to which the queries +should be forwarded. Indirect entries can be excluding as well, +in which case a (valid) dummy host name must be supplied to make the entry +distinguishable from a Direct entry. +If compiled with IPv6 support, multicast address groups may also be included +in the list of addresses the queries are forwarded to. + +If the indirect host list contains the keyword CHOOSER, +Indirect queries are not forwarded, but instead a host chooser +dialog is displayed by &kdm;. The chooser will send a Direct +query to each of the remaining host names in the list and offer a menu of +all the hosts that respond. The host list may contain the keyword +BROADCAST, to make the chooser send a +Broadcast query as well; note that on some operating systems, +UDP packets cannot be broadcast, so this feature will not work. + + +When checking access for a particular display host, each entry is scanned +in turn and the first matching entry determines the response. +Direct and Broadcast entries are ignored when +scanning for an Indirect entry and vice-versa. + +A macro definition contains a macro name and a list of host names and +other macros that the macro expands to. To distinguish macros from hostnames, +macro names start with a % character. + +The last entry type is the LISTEN directive. +The formal syntax is + + LISTEN [interface [multicast list]] + +If one or more LISTEN lines are specified, &kdm; listens +for &XDMCP; requests only on the specified interfaces. +interface may be a hostname or IP address +representing a network interface on this machine, or the wildcard +* to represent all available network interfaces. +If multicast group addresses are listed on a LISTEN line, +&kdm; joins the multicast groups on the given interface. For IPv6 multicasts, +the IANA has assigned ff0X:0:0:0:0:0:0:12b as the +permanently assigned range of multicast addresses for &XDMCP;. The +X in the prefix may be replaced by any valid scope +identifier, such as 1 for Node-Local, 2 for Link-Local, 5 for Site-Local, and +so on (see IETF RFC 2373 or its replacement for further details and scope +definitions). &kdm; defaults to listening on the Link-Local scope address +ff02:0:0:0:0:0:0:12b to most closely match the IPv4 subnet broadcast behavior. +If no LISTEN lines are given, &kdm; listens on all +interfaces and joins the default &XDMCP; IPv6 multicast group (when +compiled with IPv6 support). +To disable listening for &XDMCP; requests altogether, a +LISTEN line with no addresses may be specified, but using +the [Xdmcp] option is preferred. + + + + + +Supplementary programs + + +The following programs are run by &kdm; at various stages of a session. +They typically are shell scripts. + + + +The Setup, Startup and Reset programs are run as +root, so they should be careful +about security. +Their first argument is auto if the session results +from an automatic login; otherwise, no arguments are passed to them. + + + +Setup program + + +The Xsetup program is run after the &X-Server; is +started or reset, but before the greeter is offered. +This is the place to change the root background (if + is disabled) or bring up other windows that +should appear on the screen along with the greeter. + + + +In addition to any specified by , +the following environment variables are passed: + + + DISPLAY + the associated display name + + + PATH + the value of + + + SHELL + the value of + + + XAUTHORITY + may be set to an authority file + + + DM_CONTROL + the value of + + + + Note that since &kdm; grabs the keyboard, any other windows will not be +able to receive keyboard input. They will be able to interact with the mouse, +however; beware of potential security holes here. If +is set, Xsetup will not be able to connect to the display +at all. Resources for this program can be put into the file named by +. + + + + + +Startup program + +The Xstartup program is run as +root when the user logs in. +This is the place to put commands which add entries to +utmp (the sessreg program +may be useful here), mount users' home directories from file servers, +or abort the session if some requirements are not met (but note that on +modern systems, many of these tasks are already taken care of by +PAM modules). + +In addition to any specified by , +the following environment variables are passed: + + + DISPLAY + the associated display name + + + HOME + the initial working directory of the user + + + LOGNAME + the username + + + USER + the username + + + PATH + the value of + + + SHELL + the value of + + + XAUTHORITY + may be set to an authority file + + + DM_CONTROL + the value of + + + +&kdm; waits until this program exits before starting the user session. +If the exit value of this program is non-zero, &kdm; discontinues the session +and starts another authentication cycle. + + + + +Session program + +The Xsession program is the command which is run +as the user's session. It is run with the permissions of the authorized user. +One of the keywords failsafe, default +or custom, or a string to eval by a +Bourne-compatible shell is passed as the first argument. + +In addition to any specified by , +the following environment variables are passed: + + + DISPLAY + the associated display name + + + HOME + the initial working directory of the user + + + LOGNAME + the username + + + USER + the username + + + PATH + the value of + (or for + root user sessions) + + + + SHELL + the user's default shell + + + XAUTHORITY + may be set to a non-standard authority file + + + KRBTKFILE + may be set to a Kerberos4 credentials cache name + + + + KRB5CCNAME + may be set to a Kerberos5 credentials cache name + + + + DM_CONTROL + the value of + + + XDM_MANAGED + will contain a comma-separated list of parameters the + session might find interesting, like the location of the command + FiFo and its capabilities, and which conversation + plugin was used for the login + + + + DESKTOP_SESSION + the name of the session the user has chosen to run + + + + + + + +Reset program + +Symmetrical with Xstartup, the +Xreset program is run after the user session has +terminated. Run as root, it should +contain commands that undo the effects of commands in +Xstartup, removing entries from utmp +or unmounting directories from file servers. + +The environment variables that were passed to +Xstartup are also passed to Xreset. + + + + + + + diff --git a/doc/kfind/Makefile.am b/doc/kfind/Makefile.am new file mode 100644 index 000000000..da8216ae4 --- /dev/null +++ b/doc/kfind/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kfind/index.docbook b/doc/kfind/index.docbook new file mode 100644 index 000000000..ecfa5921d --- /dev/null +++ b/doc/kfind/index.docbook @@ -0,0 +1,363 @@ + + + + + +]> + + + + +The &kfind; Handbook + + +&Dirk.Doerflinger; &Dirk.Doerflinger.mail; + + + + + + +2001 +&Dirk.Doerflinger; + + +&FDLNotice; + +2004-04-11 +1.20.01 + + + +&kfind; is &kde;'s file find utility. + + + + +KDE +kdeutils +kfind +find +search + + + + +Introduction + + +&kfind; is the &kde; file find utility. + + + +Launching &kfind; + + +The Find Files tool is a useful method of searching for specific files on your +computer, or for searching for files that match a pattern. An example of +this could include searching for files of a particular type or with certain +letters in the filename. + +You can load this utility by clicking on Find Files. This will +launch &kfind;. + + + + + + +Finding Files + + +The Name/Location Tab + + +When starting &kfind;, you will see a quite simple window. Type in the +name of the file you are searching in the textbox labeled +Named:. Choose a folder where you want to search +by typing it in the field Look in: +or by clicking Browse... and press +Enter or click Find. If +Include subfolders is checked all +subfolders starting from your chosen folder will be searched +too. The results will be displayed in the box below. + + + +You can use the following wildcards: + + + + +The Asterisk * + + +The asterisk stands for any number of missing characters (even zero), +that means ⪚ searching for marc* may find the +files marc, marc.png and + marc_must_not_read_this.kwd. +mar*.kwd may find +marketplace.kwd and +marc_must_not_read_this.kwd. + + + + + +The Question Mark ? + + +In contrast to the asterisk, the question mark stands for exactly one +character, so mar? will find +marc, but marc? will not find +anything, as our files are called marc and +marc.png. You can put as many question marks in the +term as you want, it will find exactly that number of characters. + + + + + + + +Of course you can combine those two wildcard symbols in a search term. + + + + + +The Contents Tab + + + +File type + + +Here you can specify the type of file you are searching for. + + + + + +Containing text + + +Type in the word or phrase the files you are searching for must +contain. Note: If you do this in a large folder or checked +Include subfolders in the +Name/Location tab, this may take a long time. + + + +This option will not work for all files listed +under File type. Only the following file types +are supported: + + +Text files, ⪚ source code and README files +KWord >= 1.2 +KPresenter >= 1.2 +KSpread >= 1.2 +OpenOffice.org Writer +OpenOffice.org Impress +OpenOffice.org Calc + + + + + + + + + +Case sensitive + + +If you enable this option, &kfind; will +only find files with the exact case matching, ⪚ +MARC will only match +MARC, not Marc. + + + + + +Regular expression +If you have installed the &kregexpeditor; tool from +the kdeutils package, you will have this additional option. Enabling +it will allow you to search for a regexp or +regular expression. A regexp is a way to specify conditions for your +search, and they can be very complex, and equally they can be very +powerful. If you are unfamiliar with regular expressions, you can +choose Edit Regular Expression to open +&kregexpeditor;. This tool allows you to construct your set of +conditions graphically, and then generates the expression for +you. + +&kregexpeditor; is a very useful tool, and can be used from within +many &kde; applications other than &kfind;. You can find more +information from within its own help file. + + + + + + + + + + +The Properties Tab + + +Here you can refine your search. These are the special refinements +you can choose: + + + + + +Find all files created or modified + + +Here you can either enter two dates, between which the +files were created or modified, or specify a time period. + + + + + +File size is + +Here you can specify if the file has to be at least or as most as +big as the size you entered in the following box. + + + + + +Files owned by user, Files owned by group + +Here you can specify user and group names. + + + + + + + + + + + + +Credits and License + + +&kfind; + + + +Program copyright: + + + +Developers + +Martin Hartig + + + +Stephan Kulow coolo@kde.org + + + +Mario Weilguni mweilguni@sime.com + + + +Alex Zepeda jazepeda@pacbell.net + + + +Miroslav Flídr flidr@kky.zcu.cz + + + +Harri Porten porten@kde.org + + + +Dima Rogozin dima@mercury.co.il + + + +Carsten Pfeiffer pfeiffer@kde.org + + + +Hans Petter Bieker bieker@kde.org + + + +Waldo Bastian bastian@kde.org + + + + + +Documentation copyright 2001 &Dirk.Doerflinger; +&Dirk.Doerflinger.mail; + + + +&underFDL; +&underBSDLicense; + + + + +Installation + + +How to obtain &kfind; + +&install.intro.documentation; + + + + +Requirements + + +In order to successfully use &kfind;, you need &kde; 3.x. + + + + + +Compilation and Installation + +&install.compile.documentation; + + + + + +&documentation.index; + + + + diff --git a/doc/kfind/man-kfind.1.docbook b/doc/kfind/man-kfind.1.docbook new file mode 100644 index 000000000..bab220749 --- /dev/null +++ b/doc/kfind/man-kfind.1.docbook @@ -0,0 +1,79 @@ + + +]> + + + +KDE User's Manual +&Lauri.Watts; &Lauri.Watts.mail; +June 07, 2005 +K Desktop Environment + + + +kfind +1 + + + +kfind +file find utility for &kde; + + + + +kfind + +KDE Generic Options +Qt Generic Options + + + + +Description +The Find Files tool is a useful method of searching for specific files +on your computer, or for searching for files that match a pattern. An +example of this could include searching for files of a particular type or +with certain letters in the filename, or that contain a certain piece of +text in their contents. +&kfind; is a graphical tool, and not normally run from the command +line. + + + + +Options + + + +You may optionally supply a colon separated path to prefill +the dialog. You might use this ability to set up different icons on your +panel or desktop to quickly run searches in different locations. + + + + +App options, in a variablelist + + + + +See Also +More detailed user documentation is available from help:/kfind +(either enter this URL into &konqueror;, or run +khelpcenter +help:/kfind). + + + +Authors +The current maintainer of &kfind; is . A list of +previous contributors is available in the complete user manual available in +khelpcenter. +This documentation was prepared by &Lauri.Watts; +&Lauri.Watts.mail; + + + diff --git a/doc/khelpcenter/Makefile.am b/doc/khelpcenter/Makefile.am new file mode 100644 index 000000000..251280f85 --- /dev/null +++ b/doc/khelpcenter/Makefile.am @@ -0,0 +1,6 @@ + +SUBDIRS = $(AUTODIRS) + +KDE_LANG= en +KDE_DOCS = AUTO + diff --git a/doc/khelpcenter/background.png b/doc/khelpcenter/background.png new file mode 100644 index 000000000..2dda48e23 Binary files /dev/null and b/doc/khelpcenter/background.png differ diff --git a/doc/khelpcenter/bgtable.png b/doc/khelpcenter/bgtable.png new file mode 100644 index 000000000..b52f2e6f2 Binary files /dev/null and b/doc/khelpcenter/bgtable.png differ diff --git a/doc/khelpcenter/contact.docbook b/doc/khelpcenter/contact.docbook new file mode 100644 index 000000000..0c6609186 --- /dev/null +++ b/doc/khelpcenter/contact.docbook @@ -0,0 +1,138 @@ + + +2002-10-29 +3.5.5 + +Contact the &kde; team + + + +Mailing lists + + &kde; has several mailing lists up. See below for some of the +most useful. Older articles can be found in the mailing list archive. + + + + +kde +For general discussion, users helping each other. + + + +kde-announce +Announcements of new &kde; applications + + + +kde-devel +For developers. + + + +kde-artists +Creating icons and other artwork + + + +kde-doc-english +For people interested in writing documentation for &kde;. + + + +kde-i18n-doc +Internationalization and documentation issues + + + +http://l10n.kde.org/teams/ +For localized information, which may include user +email lists and websites, check the translation teams page at the +above &URL;. + + + + + + + +Contacting the &kde; developers + +On this page, you can find links to &kde; related web sites. + +The K Desktop Environment is developed by a large group of people +around the world. Our main communication channel is the Internet. For +general questions, you will be best served by asking on the mailing +lists mentioned in the previous +section, and contact addresses for individual developers can be +found in the documentation of their individual application. + +Please visit our Official +Representatives page for official enquiries regarding &kde; +(⪚ interviews). + +More information about &kde; is available at &kde-http;. + +Other &kde; websites include: + + + +www.kde.org +&kde;'s official website + + + +developer.kde.org +The &kde; developers center + + + +websvn.kde.org +A web interface to the &kde; Subversion repository + + + +l10n.kde.org +&kde;'s internationalization and documentation server + + + +ftp.kde.org +The main &kde; &FTP; server. Please have a look at the link +below to find a mirror site in your geographic region. + + + +www.kde.org/mirrors +&kde; web and &FTP; mirror sites + + + +www.kde-apps.org +A directory of &kde; applications. + + + +www.kde-look.org +&kde; themes, icons, and other items to change the +look of your desktop. + + + + + + + diff --git a/doc/khelpcenter/help.docbook b/doc/khelpcenter/help.docbook new file mode 100644 index 000000000..98536e1f5 --- /dev/null +++ b/doc/khelpcenter/help.docbook @@ -0,0 +1,740 @@ + + +2002-02-03 +0.08.00 + +&kde; Help System User Manual + + + +&kde; Help System + +The &kde; help system is designed to make accessing the common +&UNIX; help systems (man and +info) simple, as well as the native &kde; +documentation (&XML;). + + + All base &kde; applications come fully documented, thanks to +the efforts of the Documentation team. If you would like to help, +please write to the Documentation coordinator, Lauri Watts, at +lauri@kde.org for information. No experience is +required, just enthusiasm and patience. + + + +If you would like to help translating &kde; documentation to your native +language, the Translation coordinator is Thomas Diehl, +thd@kde.org, and he would also welcome the help. More +information, including the coordinators for each language team, can be +found on the Internationalization web +site, and in the Contact section +of this document. + + + +Installation + + +&khelpcenter; is an integral part of the &kde; Base installation, and +is installed with every copy of &kde;. It can be found in the kdebase +package, and is available from the &kde-ftp;, or will be found in your +operating system kdebase package. + + + + + + +Invoking Help + + +&khelpcenter; can be called in several ways: + + + + +From the Help menu + + +The most common will probably be from within an application. Choose +Help +Contents to open that +application's help file, at the contents page. + + + + + +From the K menu + + +Choose the big K in your panel, and select +Help to open &khelpcenter;, starting at the +default welcome page. + + + + + +From the panel + + +By default, the &kicker; panel contains an icon to call &khelpcenter;. +Again, the default welcome page is displayed. + + + + + +From the command line + + +&khelpcenter; may be started using a &URL; to display a +file. &URL;s have been added for +info and man pages +also. You can use them as follows: + + + + +An application help file + + +khelpcenter + + + +Opens the &kedit; help file, at the contents page. + + + + + +A local &URL; + +khelpcenter + + + + + + +A Man page + + +khelpcenter + + + + + + +An Info page + + +khelpcenter + + + + + + + +Invoking khelpcenter with no parameters opens the +default welcome page. + + + + + + + + +The &khelpcenter; interface + + +The &khelpcenter; interface consists of two panes of information. + + + +The toolbar and menus are explained further in . + + + +Documents contain their own navigation tools, enabling you to move +either sequentially through a document, using +Next, Previous, and +Home links, or to move around in a less +structured manner, using hyperlinks. + + + +Links can take you to other parts of the same document, or to a +different document, and you can use the Back (Left +pointing arrow) or Forward (Right pointing arrow) +icons on the toolbar to move through the documents you have viewed in +this session. + + + +The two panes display the contents of the help system, and the help +files themselves, on the left and right respectively. + + + +The <guilabel>Contents</guilabel> pane + + +The Contents pane in &khelpcenter; is +displayed on the left hand side of the window. As you might expect, you +can move the splitter bar, to make sure you can comfortably read the +contents of either pane. + + + +The Contents pane is further divided into two +tabs, one containing a menu +showing all the help information &khelpcenter; is aware of, and the +other contains the &kde; glossary +of terms. + + + +The <guilabel>Contents</guilabel> Menu + + +The Contents contains the following default +entries: + + + + +Introduction +Welcome to &kde; - an introduction to the K Desktop +Environment. + + + +Introduction to &kde; + + +The &kde; Quickstart guide. Contains a tour of the &kde; +Interface and specific help and tips on how to work smarter with &kde;. + + + + + +&kde; User's manual + + +The &kde; User's manual is an in-depth exploration of &kde;, including +installation, configuration and customization, and use. + + + + + +Application manuals + + +Native &kde; application documentation. All &kde; applications have +documentation in &XML; format, which are converted to +HTML when you view them. This section lists all the +&kde; applications with a brief description and a link to the full +application documentation. + + +The applications are displayed in a tree structure that echoes the default +structure of the K menu, making it easy to find the +application you are looking for. + + + + + +&UNIX; manual pages + + +&UNIX; man pages are the traditional on-line documentation format for +&UNIX; systems. Most programs on your system will have a man page. In +addition, man pages exist for programming functions and file +formats. + + + + + +Browse info pages + + +TeXinfo documentation is used by many &GNU; applications, +including gcc (the C/C++ compiler), +emacs, and many others. + + + + + +Tutorials + + +Short, task based or informational tutorials. + + + + + +The &kde; FAQ + + +Frequently asked questions about &kde;, and their answers. + + + + + +&kde; on the web + + +Links to &kde; on the web, both the official &kde; website, and other +useful sites. + + + + + +Contact Information + + +Information on how to contact &kde; developers, and how to join the +&kde; mailing lists. + + + + + +Supporting &kde; + + +How to help, and how to get involved. + + + + + + + + + + + +The <application>Man</application> and <application>Info</application> +sections + +Man pages are the standard &UNIX; manual pages, and have been in +use for many years on many operating systems. They are extremely +thorough, and are the very best place to get information about most +&UNIX; commands and applications. When people say +RTFM, the Manual they are referring to is very often the +man page. + +The man pages are not perfect. They tend to be in depth, but +also extremely technical, often written by developers, and for +developers. In some cases this makes them somewhat unfriendly, if not +downright impossible for many users to understand. They are, however, +the best source of solid information on most command line +applications, and very often the only source. + +If you've ever wondered what the number is when people write +things like man(1) it means which section of the manual the item is +in. You will see &khelpcenter; uses the numbers to divide the very many +man pages into their own sections, making it easier for you to find +the information you're looking for, if you're just browsing. + +Also available are the Info pages, intended to be a replacement +for the man pages. The maintainer of some applications no longer +update the man pages, so if there is both a man page and an info page +available, the info page is probably the most recent. Most +applications have one or the other though. If the application you are +looking for help on is a &GNU; utility, you will most likely find it +has an info page, not a man page. + + +Navigating inside the <application>Info</application> pages + +Info documents are arranged hierarchically with each page called +a node. All info documents have a Top node, +&ie; the opening page. You can return to the +Top of an info document by pressing +Top. + +Prev & Next +are used to move to the previous/next page at the current level of the +hierarchy. + +Clicking on a menu item within a document moves you to a lower +level in the hierarchy. You may move up the hierarchy by pressing +Up. + +Man is treated similarly to info, with the section index being +the Top node and each man page on the level below. Man entries are +one page long. + + + + + +The &kde; glossary + + +The glossary provides a quick reference point, where you can look up +the definitions of words that may be unfamiliar to you. These range +from &kde; specific applications and technologies, through to general +&UNIX; computing terms. + + + +In the left hand pane you will see a tree view, with two choices: +Alphabetically or By topic. +Both contain the same entries, sorted differently, to allow you to +quickly find the item of interest. + + + +Navigate down the tree views to the left, and items you select will be +displayed on the right. + + + + + +The menus and toolbar + + +&khelpcenter; has a very minimal interface, allowing you to concentrate +on getting help rather than learning how to use the help browser. + + + +The icons available to you in the toolbar are as follows: + + + +Toolbar Icons + + + +Back + +Go to the previous page you viewed. + + + + +Forward + +Go forward one page. This icon is only active if you have +already used the Back icon. + + + +Print + + +Print the contents of the currently visible page. + + + + + +Find + + +Find a word or words within the currently visible page. + + + + + +Increase Font + + +Increase the size of the text in the viewer pane. + + + + + +Decrease Font + + +Decrease the size of the text in the viewer pane. This icon is only +enabled if you have previously enlarged the text. + + + + + + + +The menus contain the following entries: + + + + +File + + + + + + +File +Print... + + + + +Print the contents of the currently visible page. + + + + + + + + +&Ctrl;Q + +File +Quit + + + + +Close and exit &khelpcenter; + + + + + + + + +Edit + + + + + +&Ctrl;A +Edit +Select All + + + + +Select all the text in the current page. + + + + + + +&Ctrl;F +Edit +Find... + + + + +Find a word or words in the currently visible page. + + + + + + + + +View + + + + +View +View Document Source + + + + +View the HTML source of the page you are currently + viewing. + + + + + +View +Set Encoding + + + + +Change the encoding of the current page. Normally, the default setting +of Auto should be sufficient, but if you are +having problems viewing pages written in languages other than English, +you may need to choose a specific encoding in this menu. + + + + + + + + +Go +Back + +Go back to the previous page you were viewing. + + + + +Go +Forward + + +If you have previously moved back with the back icon or menu +entry, you can work your way forward again with this menu +entry. + + + + +Go +... + + +At the bottom of the Go menu, you will find a +history list, of the last few pages you have looked at. Selecting one +will take you directly back to that page. + + + + + + + +Credits and Licenses + +&khelpcenter; + +Originally developed by &Matthias.Elter; &Matthias.Elter.mail; +The current maintainer is &Cornelius.Schumacher; &Cornelius.Schumacher.mail; + +&underFDL; +&underGPL; + + + + diff --git a/doc/khelpcenter/index.docbook b/doc/khelpcenter/index.docbook new file mode 100644 index 000000000..b6997f7f3 --- /dev/null +++ b/doc/khelpcenter/index.docbook @@ -0,0 +1,82 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + +The &khelpcenter; + +The &kde; Team + + +2002-01-18 +3.00.00 + + +&kde; is a powerful graphical desktop environment for &UNIX; +workstations. A &kde; desktop combines ease of use, contemporary +functionality and outstanding graphical design with the technological +superiority of the &UNIX; operating system. + + + +KDE +kdebase +khelpcenter +kdehelp +help +help center +KDE help center + + + +&welcome; +&help; +&whatiskde; +&contact; +&support; + + + + + diff --git a/doc/khelpcenter/kdelogo2.png b/doc/khelpcenter/kdelogo2.png new file mode 100644 index 000000000..aa0ff56e8 Binary files /dev/null and b/doc/khelpcenter/kdelogo2.png differ diff --git a/doc/khelpcenter/khelpcenter.png b/doc/khelpcenter/khelpcenter.png new file mode 100644 index 000000000..e30c35825 Binary files /dev/null and b/doc/khelpcenter/khelpcenter.png differ diff --git a/doc/khelpcenter/konq.css b/doc/khelpcenter/konq.css new file mode 100644 index 000000000..ee75f658f --- /dev/null +++ b/doc/khelpcenter/konq.css @@ -0,0 +1,68 @@ +body {background-color: #3679AD; + color: #000000; + margin-left: 0; + margin-right: 0; + margin-top: 5; + padding: 0; + background-image: url(background.png); + background-repeat: no-repeat; + background-position: top-center;} + +.caption { + color: black; + font-family: sans-serif; + font-size: 23pt; + font-style: italic; + font-weight: bolder; + margin-left: 3pt; +} + +td.trans {background-image: url(bgtable.png); + background-repeat: no-repeat;} +td.end {background-image: url(lines2.png); + background-repeat: x-repeat;} +td.shadow1 {background-image: url(shadow1.png); + background-repeat: x-repeat;} + +table.vnice { font-family: sans-serif; + font-size: x-small;} + +a:link {background-color: transparent; + color: #191970; + text-decoration:none;} +a:visited {background-color: transparent; + color: #551a8a; + text-decoration:none;} +a:active {background-color: transparent; + color: #fe0000; + text-decoration:none;} +a:hover {background-color: transparent; + color: #1919aa; + text-decoration:underline;} + +tr.menurow {background-color: #505050; + color: #000000; + vertical-align: middle;} + +td.deco {color: #ffffff; + background-color: #505050; + font-family: sans-serif; + font-size: small;} + +td.menuactive {color: #ffcc00; + background-color: #777777; + font-family: sans-serif; + font-size: small;} + +td.menu {color: #ffffff; + background-color: #505050; + font-family: sans-serif; + font-size: small;} + +a.menu {color: #eeeeee; + font-family: sans-serif; + font-size: small;} + +a.menu:hover {color: #ffffff; + text-decoration:none;} + diff --git a/doc/khelpcenter/lines.png b/doc/khelpcenter/lines.png new file mode 100644 index 000000000..498330c38 Binary files /dev/null and b/doc/khelpcenter/lines.png differ diff --git a/doc/khelpcenter/lines2.png b/doc/khelpcenter/lines2.png new file mode 100644 index 000000000..02a8c05b5 Binary files /dev/null and b/doc/khelpcenter/lines2.png differ diff --git a/doc/khelpcenter/pointers.png b/doc/khelpcenter/pointers.png new file mode 100644 index 000000000..17bfb2eb8 Binary files /dev/null and b/doc/khelpcenter/pointers.png differ diff --git a/doc/khelpcenter/shadow1.png b/doc/khelpcenter/shadow1.png new file mode 100644 index 000000000..b57787697 Binary files /dev/null and b/doc/khelpcenter/shadow1.png differ diff --git a/doc/khelpcenter/support.docbook b/doc/khelpcenter/support.docbook new file mode 100644 index 000000000..9099aa392 --- /dev/null +++ b/doc/khelpcenter/support.docbook @@ -0,0 +1,102 @@ + + +2002-03-04 +2.02.00 + +Supporting &kde; + + + +Supporting &kde; + + If you are new to &kde;, the &kde; project might look like big +machinery to you. Undoubtedly, &kde; is no longer a small project, +nevertheless it is very important to realize that it is easy to +make a difference in the &kde; world. + + There is always a need for dedicated developers, graphic +artists, sound engineers, translators and documentation +writers. Consider jumping aboard this exciting international project +and make yourself a name in the software world. + + Along the way you will make countless friends and acquaintances +all over the world. Also, the satisfaction that stems from doing +actual hands-on work, that will benefit an uncountable number of users +world-wide, and from seeing an unparalleled project grow, is hard to +beat. Please consider joining and supporting &kde; and hop aboard this +exciting journey towards a free and open alternative computing +platform. + + + + +How to get started + + + + +Subscribe to the &kde; mailing lists +that interest you. + + + +Read the mailing list archives in +order to get a feel for &kde; development. + + + +Learn how to program using the &kde; application framework and join the +friendly &kde; developers' community. + + + + + + + +Supporting financially + + The &kde; team is working very hard on providing you with the +best desktop available for the &UNIX; operating system. &kde; is +available for free and will always be available for free, including +each and every line of its source code, for everyone to modify and +distribute. If you enjoy and use &kde; please consider supporting the +&kde; Project financially. &kde; is in constant need of funds in +order to finance its operations. + + If your busy schedule or skills do not permit you to be +actively involved in &kde; development, please consider supporting +&kde; financially by sending a donation to: + + You can send regular US checks to the following address: + + +K Desktop Environment e.V. +Mirko Boehm +2029 Chadds Ford Drive +Reston, VA 20191 +USA + + + Use "KDE e.V. - Mirko Boehm" in the "Pay to the order of..." line. + + + +From Europe, you may remit your donation to (be aware of a fee if wiring from outside of Germany): + + + +K Desktop Environment e.V. +Account-Nr. 0 66 64 46 +BLZ 200 700 24 +Deutsche Bank 24 + + + Please contact Mirko Boehm +kde-ev-treasurer@kde.org if you have any questions. + + Your contribution is very much appreciated. Thank you! + + + + diff --git a/doc/khelpcenter/welcome.docbook b/doc/khelpcenter/welcome.docbook new file mode 100644 index 000000000..6f1859311 --- /dev/null +++ b/doc/khelpcenter/welcome.docbook @@ -0,0 +1,60 @@ + + +2002-01-18 +3.00.00 + +Welcome to &kde; + + + The &kde; team welcomes you to user-friendly &UNIX; +computing. + + +Welcome to the K Desktop Environment + + +Information about &kde; + +&kde; is a powerful graphical desktop environment for &UNIX; +workstations. A &kde; desktop combines ease of use, contemporary +functionality and outstanding graphical design with the technological +superiority of the &UNIX; operating system. + +What is the K Desktop Environment? + +Contacting the &kde; Project + +Supporting the &kde; Project + +Useful links + + + + +Getting the most out of &kde; + + +General documentation + +A Quick Start Guide to the Desktop + +&kde; User's guide + +Frequently asked questions + + + + +Basic applications + +Desktop Panel + +Control Center + +File Manager + + + + + + diff --git a/doc/khelpcenter/whatiskde.docbook b/doc/khelpcenter/whatiskde.docbook new file mode 100644 index 000000000..d63213eee --- /dev/null +++ b/doc/khelpcenter/whatiskde.docbook @@ -0,0 +1,129 @@ + + +2002-01-18 +3.00.00 + +What is &kde;? + + + +What is &kde;? + +&kde; is a desktop environment. In other words, &kde; is a +collection of programs, technologies and documentation that attempt to +make life easier for computer users. &kde; is targeted at &UNIX; +workstations. It features network transparency and a contemporary work +philosophy. + +The creators of the K Desktop Environment are a world-wide group of +software engineers. This group's major goal in free software development is to +provide high quality software that empowers the user with easy control of his +computer's resources. + +&kde; seeks to fill the need for an easy to use desktop for +&UNIX; workstations, similar to the desktop environments found under +&MacOS; or &Windows; 95/NT. &kde; meets the requirement +of users for an easy to use work environment. Tools used to reach +this end are: enhanced inter-application communication, component +reuse, generalized drag and drop, uniform look and feel and many +more. Thus, &kde; offers much more than the traditional &UNIX; window +managers. + +Stability, scaleability and openness are qualities which have +made &UNIX; the undisputed choice for the information technology +professional for many years. &kde; builds on top of this excellent +base framework and brings new, much needed qualities: usability, user +friendliness and beauty! &kde; was the first, and stays the forefront +player in bringing these qualities to &UNIX;, which constituted for +years, the premier platform for server computers and scientific +institutions, but wasn't very attractive for desktop users. + +Without &UNIX; the Internet would not exist, or at least would +have a vastly different form. &UNIX; has not, until now, addressed the +needs of the average computer user. This fact is particularly +unfortunate, since a number of implementations of &UNIX; (&Linux;, FreeBSD, NetBSD, &etc;) are freely +available on the Internet, all of which are of exceptional quality and +stability. + + + + +&kde; The Desktop Environment + +In combination with a free implementation of &UNIX;, &kde; +provides to the world an open and completely free desktop computing +platform either at home or at work. + + This platform is available to anyone free of charge including +its source code for anyone to modify. + +While there will always be room for improvement we believe we +have now delivered a viable alternative to some of the more commonly +found and commercial operating systems/desktops combinations available +today. It is our hope that the combination of &UNIX; and &kde; will +finally bring the same open, reliable, stable, and monopoly free +computing to the average computer user that scientists and computing +professionals world-wide have enjoyed for years. + + + + +&kde; The Application Development Framework + +&kde; focuses on the user's needs, but it's obvious that this +focus is more easily achieved by also giving developers the best +tools. &kde; code contains, and comes with, some of the best +development technologies of the modern computing age. + +Authoring applications under &UNIX;/X11 used to be an extremely +tedious and labor intensive process. &kde; recognizes the fact that a +computing platform is only as good as the number of first class +applications available to the users of that particular +platform. + +&kde; defines new technologies in &DCOP; and KParts, created to +offer a component document model and technology. Together with the +complete &kde; libraries programming interface, &DCOP;/KParts are set +in direct competition with other similar technologies like &Microsoft; +MFC/COM/ActiveX technologies. The +excellent quality and the high level of refinement of &kde;'s +application programming interface (API) enables +developers to focus on original and interesting issues and avoid +reinventing the wheel. + + + + +&kde; The Office Application Suite + +In its current form, &kde; provides, apart from the essential desktop +component applications, a suite of powerful office programs known to the +world by the name &koffice;. + +&koffice; is based on the &kde; &DCOP;/KParts +technologies. It currently contains: a word processor with desktop +publishing capabilities (&kword;), a spreadsheet application (&kspread;) +and accompanying charting program (&kchart;), a presentation program +(&kpresenter;) and a vector drawing program (&kontour;). Tying things +together is the KOffice Workspace, an +integrated shell to ease the use of the &koffice; components in +conjunction with each other. Additional components include an email +client, a news reader, and a powerful PIM (Personal +Information Manager - an organizer). + +While some of those components are still in alpha development, +others are already extremely powerful. For example, &kpresenter;, +&kde;'s presentation application, was successfully used at the 5th +International &Linux; Congress in Cologne, Germany to deliver a &kde; +presentation. + +We would like to invite you to learn more about &kde; and &koffice;. + + + + diff --git a/doc/kicker/Makefile.am b/doc/kicker/Makefile.am new file mode 100644 index 000000000..3f20a1e1b --- /dev/null +++ b/doc/kicker/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + +KDE_MANS = AUTO diff --git a/doc/kicker/bookmarks_icon.png b/doc/kicker/bookmarks_icon.png new file mode 100644 index 000000000..aa335b286 Binary files /dev/null and b/doc/kicker/bookmarks_icon.png differ diff --git a/doc/kicker/desktop_icon.png b/doc/kicker/desktop_icon.png new file mode 100644 index 000000000..5055c7df8 Binary files /dev/null and b/doc/kicker/desktop_icon.png differ diff --git a/doc/kicker/index.docbook b/doc/kicker/index.docbook new file mode 100644 index 000000000..bc7333c72 --- /dev/null +++ b/doc/kicker/index.docbook @@ -0,0 +1,2434 @@ + + + + + +]> + + + + + + +The &kicker; Handbook + + +&Orville.Bennett; &Orville.Bennett.mail; +&Dirk.Doerflinger; &Dirk.Doerflinger.mail; + + + + +20012002 +&Dirk.Doerflinger; + + +2004 +&Orville.Bennett; + + +2005 +Titus Laska + + +&FDLNotice; + +2006-06-15 +3.5.2 + + + +&kicker; is the &kde; application starter panel and is also capable of +some useful applets and extensions. It usually resides on the bottom of +the desktop. + + + + +KDE +Kicker +kdebase +panel +application +starter + + + + + +Introduction + + + +&kicker; is the application launcher panel of the K Desktop Environment. +Besides the K Menu, where you can start applications, +&kicker; is also capable of running docked applets like the pager, the +taskbar or the clock, and extensions, such as child panels. + + + +&kicker; usually resides on the bottom of the desktop, but it can also +be moved to any other border. Please report any problems or feature +requests to the &kde; mailing lists. + + + + + +Using &kicker; + + +This is what you see on a freshly installed &kde;, assuming that you +skipped KPersonalizer. If you are using +lower resolution, some of the icons may not appear immediately. To +cater for those smaller resolutions, the screenshot below is divided +in two parts. + + + +Here is a screenshot of the left side of &kicker; + + + + +Screenshot Left + + + +This is a screenshot of the left side of &kicker; + + + + + + +And here is the right side + + + + +Screenshot Right + + + +This is the right side of &kicker; + + + + + + +Of course, this is only one way &kicker; might appear on the +screen. There are many more configurations available. + + + +A quick tour for new &kde; users + + +If you are experienced with this kind of application launcher, you can +ignore this chapter and move on to &kicker; +basics. + + + +The main use of &kicker; is starting applications. This is +done by clicking icons, either from the panel or from the +K Menu. &kicker; shows some more things too, so let's +see. + + + +Having a look at the screenshots above, there are from left to right: + + + + + +The K Menu + + +It is used for launching applications and some other useful +things. Refer to The K Menu +for more information. + + + + + +Application start icons + + +Here are some icons of commonly used applications. They can be moved and +removed and others can be added. Some of them have a special meaning, +which you can read more about in &kicker; +basics. Resting the mouse over an icon without clicking shows the +name and a short description of that application, if you have set that in +the Settings Dialog. + + + + + +The Pager applet + + +This displays a small view of the virtual desktops. Clicking one section +of it will activate that desktop. Please refer to Applets. + + + + + +The Taskbar + + +All running applications are displayed as buttons in the +taskbar. Clicking an application's button will bring this application on +top. If it was on top before, it will be iconified. More +information is available in the Applets +section. + + + + + +System Tray + + +The system tray is able to swallow some kind of applications like - in +this case - &klipper; and the &korganizer; Reminder Daemon. There are +many other applications that dock in the system tray, for example &juk; +and &kopete;. Clicking the icons with the +left or the right +mousebutton performs specific actions defined for each +application. + + + + + +Clock + + +The Clock applet is - of course - a small, useful clock. It can have +various styles, have a look at the applets section for more information. + + + + + +The Hide panel button + + +This button lets you fade out &kicker; for having more space on the +screen. When &kicker; is faded out, only the Hide panel button +will remain in order to fade in &kicker; again. + + + + + + +This was only the description of &kicker; on its initial launch. It can +be configured in many ways and styles and more applets can be +added. There are even some extensions like the external taskbar you can +add. See &kicker; basics, Applets and Extensions for more information. + + + + + + + + +&kicker; basics + + +General usage + + +As mentioned before, there are a lot of things that can be added to +&kicker;. This section will tell you everything about application +starting, folder browsing and adding some kinds of applets and +extensions. Lots of things can be done from the context +menu with Configure Panel... or via the &kcontrolcenter;'s section Desktop Panels. + + + +Adding applications + + +There are three different ways to add an application to &kicker;: + + + + +Drag and Drop + + +Simply drag any file from &konqueror; into &kicker; and it's there. Dragging +also works from the K Menu with any entry. You can +change the attributes like optional command line parameters or the icon +by clicking it with the &RMB; and choosing Configure +applicationname Button... from the +context menu. + + + + + +Using the context menu to add a &kde; application + + +Click the &RMB; on any free space +in &kicker; and choose Add Application to Panel. +There you can choose an application +which will then be added to &kicker;. + + + + + +Using the context menu to add a +non-&kde;-application + + +Non-&kde;-applications ⪚ +xosview or xemacs. + + + +Click the &RMB; on any free space +in &kicker; and choose Add Application to +Panel and then Add Non-KDE +Application. In the newly appearing window, enter Button title +and a Description of the application in the first two text boxes. Then fill +in the command of the application you +wish to add in the Executable: text box. You can +also append command line arguments, have +the application start from a terminal, and choose the icon which will +appear in &kicker; by clicking the gear. If you don't +choose an icon, the application will use the gear as a default. + + + + + + +Applications can be moved or removed by &RMB; click and choosing +Move application name Button or +Remove application name Button. +You can also move icons using the &MMB; if you have one. To do this click on an icon using the &MMB;, hold for a second and then drag the icon to its new position. +Another way to remove an application is by clicking the &RMB; on any free space +and then choosing Remove from Panel +Application and then the application you want to be +removed. + + + + + + + + +Adding Folders + + +Folders can be added by simply dragging a folder to any free space of +&kicker;. Quick Browsers can also be added from the context +menu or the K Menu. + + + +There are two different ways to have a folder in &kicker;, you can +choose between them in the menu appearing after dropping. + + + + +Add as File Manager &URL; + +Choosing this will add a link to the selected folder. Clicking +this folder icon will open &konqueror; displaying the +contents of this folder. + + + + +Add as Quick Browser + +If you add a folder this way, it will be displayed as a submenu of +&kicker;. This submenu contains Open in File +Manager, which does the same as a file manager &URL;, and +Open in Terminal, which opens a terminal with +this folder as the working path. Also, this submenu contains the contents of +that folder. Sub-folders are displayed as new submenus like the Quick +Browser itself. The maximum number of displayed elements can be set in +the Settings Dialog. +Quick Browsers can also be added from the context menu of +&kicker; and then choosing Add Applet to Panel... and +then Special Buttons on the right top of the +Add Applet dialog. + + + + + + + +Both kinds of folders can be moved or removed by &RMB; click and +choosing Move application name Button or +Remove application name Button. +You can also move icons using the &MMB; if you have one. To do this click on an icon using the &MMB;, hold for a second and then drag the icon to its new position. +Another way to remove a folder is by clicking the &RMB; on any free space +and then choosing Remove from Panel +Applet and then the applet you want to be +removed. + + + +File manager &URL;s can also be configured from the +context menu, just like any other folder anywhere in +&kde;. + + + + + +Special Icons + + +Some icons in &kicker; have a special meaning. They are added by +choosing Add Applet to Panel... and +then Special Buttons on the right top of the +Add Applet dialog. + + + + +The K Menu Icon + + + The +K Menu icon is one of the most necessary icons in +&kicker;. As you might guess, it opens the K Menu, +which you can learn more about in The K +Menu. + + + + + + +The Window List Menu + + + Clicking this +icon will show the Window +list. Its first entry, Unclutter +Windows, tries to move the windows on your active desktop +in a way to see as many as possible. + + + +Cascade Windows puts all windows on the +active desktop over each others, the most recently on top and the others +sorted by the time they where last used. Below those +entries is a list of all currently running applications, grouped by the +desktops on which they are running. Clicking on an application will activate it. + + + + + + +The Bookmarks Menu + + + The +Bookmarks icon provides fast access to your +bookmarks. They appear in the same way as if you click the +Bookmarks menu in &konqueror;. Clicking a bookmark in +the menu will launch &konqueror; with the &URL; which +is behind that bookmark. + + + + + +The Recent Documents Icon + + + +This menu shows the most recently used documents. Clicking the element +Clear History will remove those entries, +which may be useful for privacy reasons. + + + + + +The Show Access Icon + + + The +Show desktop icon lets you have quick access to all +the things you have on your desktop by minimizing all currently open +applications. Clicking it once will toggle it to show the desktop. The +icon will remain pressed until you either click it +again, which will restore your minimized apps, or reactivate an +application from the taskbar. + + + + + +The Quick File Browser Item + + +Adding a +Browse icon will open a dialog which will +let you choose a path and an icon, which will appear as a +Quick File Browser menu. Refer to the Adding Folders section for more information +about quick browsers. + + + + + +The Non-&kde; Application Launcher + + + + + +The Non-&kde; Application Launcher lets you add an +application which doesn't appear in the K menu to &kicker;. +Refer to Adding Applications for more +information about Non-&kde; Applications. + + + + + + +The Terminal Sessions Icon + + + This icon +provides a menu of the available Terminal sessions, just as &konsole; does +when you click and hold its New Session button. + + + + + +The Print System Icon + + +This icon gives +direct access to &kde;'s printing system. &kde; is able to utilize various printing +systems according to users' wishes. The options shown below will vary depending +on the printing system in use. Clicking the &LMB; on the icon opens +a menu which gives the following options: + + + +Add Printer... This will start &kde;'s Add Printer +Wizard which allows you to simply add a new printer to your system. + + +&kde; Print Settings This item will open the &kde; Print +Configuration dialog. + + + +Configure Server This item allows configuration +of a &CUPS; Server. An authorization dialog, requiring validation, will be presented +to you before allowing any changes. + + + + +Print Manager This item starts the Printing Manager, +&kde;'s main printing control center. + + + +Print Browser (&konqueror;) This item will +start &konqueror; with the print:/ io-slave to +browse all kinds of printers. + + + +Print File... This item opens a dialog which lets +you easily print one or more files. + + + +The next items with the names of all your printers open the KJobviewer window for each printer. + + + + + + + + + + + + + +Removing all kinds of icons + + +Clicking the &RMB; on any icon, whether it's an application, +folder or special icon and then choosing +Remove name from the appearing context +menu will remove the icon from &kicker;. + + +Another way of removing icons is clicking the &RMB; on any free space in +&kicker; and choosing Remove From Panel and then +Applet, Application or All. You can then choose the button you want to remove in +the submenu. + + + +Please note that removing an icon from &kicker; won't remove the +application on the disk! + + + + + + +Adding Applets + + +&kicker; comes with a set of applets like the taskbar or the +mini-pager. They can be added by choosing Add +Applet to Panel... from the context menu, +which can be opened by +clicking the &RMB; on any free space in &kicker;. In the upcoming +dialog, choose an applet to add and click the Add to +Panel button. + + + +Applets can be moved by dragging them on their handle with holding the +&LMB;, or the &MMB;, or by choosing +Move from the context menu. + + + +You can learn more about the applets in the section Applets. + + + + +Removing Applets + +Applets can be removed by choosing the Remove applet name option from the context menu, which appears when the +&RMB; is clicked on the applet's handle (left or top side of the applet) or on the icon itself. + + + + + + +Adding Extensions + + +There is also the possibility to add external extensions to &kicker;, +like the External Taskbar, the Dock +Application Bar for WindowMaker +dock-applications, Kasbar, an iconic kind of +taskbar, an Universal Sidebar and even child Panels which behave like new instances of +&kicker;. + + + +Extensions can be added by selecting them from the +submenu Add New Panel in the context +menu of &kicker;. +Most of the extensions can be moved to any border of the screen by +dragging them with the &LMB; on a free space. If that does not work, +open the context menu on any free space in &kicker;, +choose Configure Panel... and set up the panel +positions in the appearing dialog. + + + +More about extensions can be read in the extensions section. + + + + + +Removing Extensions + + +You can remove extensions by clicking Remove +in their context menu, usually located in the +fade-out handles or by selecting them from the Remove +Panel submenu of the &kicker; context +menu. + + + + + + +Configuring Application Buttons + + +Every application starter has some preferences you +can set from their context menu with Configure application nameButton.... Usually applications +and folders have the same preferences as in &konqueror;. Only the +applications which are located in the K Menu (for +experienced users: those which have a .desktop extension in the applnk folder) have a special kind of config +dialog. + + + +The <guilabel>General</guilabel> Tab + + +Here you can see some information about the application link. You can also +choose an icon by clicking on the icon button +. +This may be useful if you want the icon on the panel behave different +to the analog one in the K Menu. + + + + + + +The <guilabel>Permissions</guilabel> Tab + + +Here you can see the permissions of the link file. Please refer to the +manuals or handbooks of your operating system for more about +permissions. + + + + + +The <guilabel>Application</guilabel> Tab + + +You can set the behavior of the application when it's executed on this page. + + + + +Name + + +Here you can set the name of the application which will be shown in the tooltip. + + + + + +Description + + +Here you can set an informative title which will be shown in the tooltip. + + + + +Once the Description is set however, it alone will be +shown in the tooltip. + + + + + + +Comment + + +See Description. + + + + +If you set a Name and a Comment, they will +be shown as tooltips of the start icons in the style Name - Comment. + + + + + + +Command + + +Usually, there is only the name of the binary that has to be started +when clicking on the icon. You can search for another application to be +started by clicking the Browse... button and/or add +special command line parameters to the application. + + + + + +Work path + + +Not yet written + + + + + + + +Supported file types: + + +In this section you can choose what kinds of filetypes are handled by +this application. Please refer to &konqueror; handbook for more about this. + + + + + +Advanced Options + + +This button allows for further configuration of the application to be run. + + + + +Run in terminal + + +If this box is checked, the application will be executed in a terminal +window. You can also add special Terminal options. + + + + + +Run as different user + + +Checking this option will let the application start with the permission +of the user you typed in the field Username. You +will be prompted for the user's password on application start. This +option may be very useful if you want to start some applications as +superuser. + + + + + +Enable launch feedback + + +If this box is checked, this will display feedback when an application icon is clicked +with the &LMB;. + + + + + +Place in system tray + + +When checked, the application's icon will show up in the panel system tray. +You will then be able to hide or show the application by clicking on the system +tray icon. Clicking on it using the &RMB; will allow also you to undock, or quit the +application. + + + + + +DCOP registration + + +Not yet written + + + + + + + + + + + + + + + + +Configuring &kicker; + + +This section describes the ways &kicker; can be configured. It's only +about the basic &kicker; settings, configuration of the applets are +described in their sections + + + +You can change the settings by either clicking +Configure Panel... in the context +menu of &kicker;, or in &kcontrolcenter; by +going to Desktop and then selecting the +Panels or the Taskbar module. + + + + +The Panel Section + + +Extensions + +Panels and panel extensions are configured +on the same page. Simply choose one of your extensions (⪚ +Child Panel) from the Settings for: listbox. You will then +be adjust its settings rather than that of the Main Panel. + + + + + +<guilabel>Arrangement</guilabel> + + +In the Arrangement tab you can configure some basic +functionality of the &kde; panel (&ie; functionality you'd find in other +panel applications as well; later we'll come to the more interesting +features). + + + +In the Position frame you can choose which +screen border the panel should be attached to. Please note that usually +the available space is used more efficiently if the panel is aligned +horizontally, &ie; attached to the top or bottom screen border. If you +want to play around with different settings you can change the panel's +position even easier by dragging the panel from one border to the other. + + + +The Length frame lets you define how much space a panel +will occupy on the side of the screen which it resides. By default this is on the +bottom so changing this value will affect a panel's width. The value can be anywhere +from 1% to 100%. +Checking the check box Expand as required to fit contents +makes sure that a panel is at least as big as needed to show every icon and +applet. + + + +The Size frame lets you define how large a panel will be. +The panel's size can be tiny, small, medium, large or custom. Depending on +which applets you use you may find that some applets work better at +different panel sizes. + + + + + +<guilabel>Hiding</guilabel> + + +Depending on your screen resolution you may find that the panel takes +away too much of your precious screen real estate. To save screen space, +the panel offers an auto hide feature. When this feature is enabled, the +panel will hide when the mouse cursor has not been moved over it for a +configurable amount of time. If you move the mouse to the panel's screen +border it will show up again. Select the Hide automatically +option in the Hide Mode frame to enable this feature. +You can also configure the amount of time the panel will wait before +it hides here. The check box Show panel when switching +desktops makes sure that the panel will be shown on the new +chosen desktop. Otherwise, if there are too many applets and icons on +&kicker;, two small scroll buttons will be displayed to scroll the whole +panel. + + + +When the panel's hide buttons are enabled you'll see buttons on both +sides of the panel, with arrows showing to the screen border. If you +click on one of these buttons, the panel will slide away in that +direction. After that, you'll see a remaining show button in that +corner, which will make the panel show again. Check the appropriate +checkbox if you want the hide buttons to show up on any side of +&kicker;. Using the slider you can change the width of the buttons. + + + +You can toggle which hide buttons the chosen panel should have with +the check boxes in the group Panel-Hiding Buttons. + + + +The Panel Animation frame allows you to choose +whether the panel will softly slide away or just disappear. +Checking the Animate panel hiding will allow you +to configure the speed of the animation using the sliders. Unchecking, +naturally, disables the panel animations. + + + + + +Menus + + +In the Menus tab you can configure the panel menu's +behavior. This affects the K menu you will often use +to launch applications, the browser menus you can use to access +folders and other menus like the recent documents menu. + + + +The K Menu frame offers you some options to +configure the K menu's functionality. The +Bookmarks and Recent Documents options +will enable submenus showing your konqueror +bookmarks and the last documents you've opened using &kde; applications +respectively. The Quick Browser option will enable a browser menu. +Enabling the Show side image check box will display a neat +image on the left side of the K menu. +The Menu item format entry allows you to set how +detailed the K menu entries will be. +The Name only option simply shows the application's name in the menu. +The Name (Description) option will show a small description +besides the name of the application. +The Description (Name) and Name +(Description) options will show both name and description in +the KMenu. + + + +In the QuickBrowser Menus frame you can configure +whether the panel's browser menus will show hidden files or not (hidden +files on &UNIX; systems are those whose filenames begin with a dot) as +well as how many files at most will be shown in a browser menu; the +latter option may be especially useful if you have a rather small screen +resolution, as the browser menus would otherwise quickly fill up your screen +when you browse folders containing many files. + + + +The quick start section in the K menu offers quick +access to programs you have used often or recently. In the +QuickStart Menu Items frame you +can choose whether this section will show the most recently or the most +frequently used programs. Using the option Maximum number of +entries you can configure how many +programs the quick start section will remember. + + + + + +<guilabel>Appearance</guilabel> + + +Using the Appearance tab you can configure the +panel's overall appearance. + + + +The check box Enable icon mouseover effects +toggles the large animated tooltips of &kicker;. They show name and +description of the icons and applets the mousepointer is positioned on. + + + +If Show tooltips is checked, the classical small +tooltips with descriptions of the icons and applets will be shown if the +mousepointer rests over an icon for some seconds. Note that this +has no effect as long as the option to Enable icon mouseover +effects is enabled. + + + +The &kde; panel supports so-called tiled buttons. This +means that the buttons shown on the panel will be drawn using +configurable images/colors. + + + +For every kind of panel button there is a combo box offering a custom +color option and tiled images. When the value is changed from "Default", +tiles are enabled for this kind of button. You can also see a preview of a tile +before use via the combo box. + + + +The different kinds of buttons are: + + + + +K Menu tiles + + +The icon for the K Menu will be displayed as a tile + + + + + +Applications tiles + + +The icons which start applications will be displayed as tiles + + + + + +Desktop access tiles + + +The Desktop Access icon will be displayed as a tile + + + + + +QuickBrowser menus Tiles + + +The icons for Quickbrowsers will be displayed as +tiles + + + + + +Window list Tiles + + +The Window List icon will be displayed as a tile + + + + + + +The Enable transparency option, when checked, allows the +panel to appear transparent. + + + +The background image is a picture that will be used +to draw the panel's background, just like you can use a picture for the +desktop background. Check the Enable background +image option to enable this feature. You can specify an image +file in the edit box below or choose one by clicking on the +Open file dialog button. You may also check the +Colorize to match the desktop color scheme box to +modify the background image's colors. You'll see a preview of the selected +picture on the right. + + + + + + + + + + + +The <guilabel>Taskbar</guilabel> Section + + +This section changes the settings of the taskbar. Changes affect the +external taskbar and also taskbar applets on &kicker; or child-panels. + + + + +Show windows from all desktops + + +If this box is checked, the taskbar will show all running apps of every +desktop. Otherwise, only the applications of the current desktop are +shown. + + + + + +Sort windows by desktop + + +Checking this box will sort all taskbar buttons +in a group for each desktop, otherwise they are sorted by the order they +are started. This will not affect grouped tasks if they are spread over +more than one desktop. + + + + + +Sort alphabetically by window name + + +To be written + + + + +Show only minimized windows + + +If this box is checked, only windows which have been minimized will be +shown in the taskbar. If Show windows from all desktops +has been checked then all minimized windows will be shown. Otherwise, only the +minimized windows of the current virtual desktop will be shown. + + + + + +Show application icons + + +If this box is checked, every taskbar button will +have the icon of the running application beside its title. + + + + + +Show window list button + +Checking this box will show the small window list +button. + + + + + +Group similar tasks + + + + + + +This is an option which helps you if you often lack space in your +taskbar. If it is set to Always, several +instances of the same application are grouped together in one taskbar +button. Select When Taskbar Full to make &kicker; +only group similar tasks if there is not much space left in the taskbar. + + + + + + + + +You can define the mouse actions of the taskbar buttons with the settings in +the Actions frame. Each action can be one of the +following: + + + + +Show Task List + +Clicking with the +mouse button will open a menu displaying all +tasks in that group. If you click an entry of that menu with any mouse +button, the corresponding application will become active. + + + + +Show Operations Menu + + +Clicking with the mousebutton will open a menu with all +applications of that group, where every application has its window +menu as a submenu and there are some group specific entries like +Close All which closes all applications of +that group, All to Desktop which lets you +define on which desktop the whole group appears and +Maximize All, Minimize +All and Restore All which +appends those actions to all applications of that group. + + + + +Cycle Through Windows +If this action is chosen, each +click with the mousebutton on the taskbar button will +activate one of that group's applications, one after each others. + + + +Activate Task + + +Activate Task: Clicking with the mousebutton will activate +the first application in that group without opening the group menu. + + + + +Raise Task + +The first application of that group will be +put in the foreground without giving focus to it. + + + +Lower Task + + +The first application of that group will be +put in the background. It won't lose the focus. + + + +Minimize Task + +The first application of that group will be +minimized. If it is already minimized, it will be restored again. + + + + +Please note that some of these settings only have effect if a +taskbar button contains more than one application. + + + + + + + +The <guimenu>K</guimenu> Menu + + +The K Menu is one of the central elements of +&kicker;. + + + +There are five main groups in the K Menu which will +be described now from bottom to top. + + + +The &kde; Group + + +This group is for the common &kde; things in the K +Menu. + + + + +Log Out... + + +This entry is used to finish the &kde; session. It also shuts down the +&X-Window; session. + + + + + +Lock Session + + +With this entry you can lock your session if you don't want anybody else +to access your desktop. If you have set a screensaver, it will appear when +locked, otherwise the screen will turn black. If you hit any key, you +will be prompted for your user password. This is independent from the +screensaver's password settings. + + + + + +Special Configuration + + +Clicking with the &RMB; on the K Menu, will produce a +special submenu. In this submenu is the Panel Menu. +Here you can change the settings of &kicker;, described in the +Configuring &kicker; section, add +things to &kicker; (see in &kicker; Basics +for more), or reach the Help Menu, but as you are +reading this, you probably found it yourself. +You can also start the Menu Editor via this submenu. + + + + + + + + +<guilabel>Run Command...</guilabel> + + +This will bring up a small but powerful application start dialog. + + + +In the standard case, you just type in a command and press +Enter or click Run. But there +is also an Options >> button which will bring up +some starting options to the command window. + + + + +Run in terminal window + + +Checking this box will let the application start in a terminal which means that +you will be able to see any command-line messages the application may give. + + + + + +Run as a different user + + +If this box is checked, you can specify a user with whose permission the +application should run in the Username textfield. +If you specify another user, you will have to give a password at the box +below. + + + + + +Run with different priority + + +Check this option to run with a different priority. A higher priority +will tell the operating system to give more processing time to the +applications. You can use the slider to change the priority. If you +want to give your app a higher priority than the default one (middle +position), you will need to enter the root password below. + + + + + +Run with realtime scheduling + + +The Scheduler is the part of the operating system which processes will +run and which have to wait. Usually, an application will run with normal +schedule, which means it can use the processing time it gets from the +operating system, but you can also set it to +realtime. This means that the application has all +the process time until it gives it away. You will need to enter the root +password to use Run with realtime scheduling. + + + + +This can be dangerous. If the application hangs and cannot give up the +processor, the complete system might hang. + + + + + + + + + + + + +The Actions Group + + +This group contains some very useful dynamic menus as described in the +Menus section of &kicker;'s settings. + + + + +Quick Browser + + +This submenu contains quick browsers for three very useful folders: +home, root, and system configuration. + + + + + +Recent Documents + + +This menu shows the most recently used documents (works only with &kde; +applications for the moment). Clicking the element Clear +History will remove those entries, what may be useful for +privacy reasons. + + + + + +Bookmarks + + +This submenu shows your personal bookmarks just like &konqueror; +does. Refer to the &konqueror; Handbook for more help on this. + + + + + + + + + +The All Applications Group + + +The submenus for application starting are located in this group. You can +use &kmenuedit; to add, remove or move the entries. Applications will have a +short description if either the Name (Description) or +Description (Name) option is enabled in the settings. + + + + +The Most Used Applications Group + + +This group holds either the most recently or the most frequently used +applications. See the Menus +Configuration section for more about that. + + + + + + +Applets + + +Applets are small applications running inside of &kicker;. Almost +everything besides the application starter buttons +are applets. They can be added from the context menu +by choosingAdd Applet to Panel. Every +applet contains a small arrow in its handle. Clicking it will bring up a menu +which lets you move or remove it, set the Preferences, if there are any and set +the preferences of &kicker;. + + + +The Taskbar Applet + + +The taskbar applet shows buttons for the running applications. The +application, which has the focus, is shown as a pressed button. If an +application is minimized, the title displayed in the taskbar will fade +to gray. + + + + +If you click on the button of the active application, it will be +minimized. This means also that if you click twice on an inactive +application, it will also be minimized. + + + + +A click with the &RMB; on a button will show the standard application +menu. Only the entry To Current Desktop +differs: if you have set the taskbar to show the applications of all +desktops, you can move this app to the current desktop. + + + +There is also a small icon on the left or top side of the taskbar, which +opens a menu. This is called the windows list +icon. The menu's first entry, Unclutter +Windows, tries to move the windows on your active desktop +in a way to see as many as possible. Cascade +Windows puts all windows on the active desktop over each +others, the most recently on top and the others sorted by the time they +where last used. + + + +Below those entries is a list of all currently running applications, +grouped by the desktops on which they are running. Clicking on the name +of a desktop will switch to that one, clicking an application will also +activate it. You can specify the mouse behavior. Please refer to Taskbar settings for more about that. + + + + +Configuring the Taskbar Applet + + +You can configure the taskbar by clicking the &RMB; on the small move +handle. + + +Please refer to for details about the +preferences of the taskbar. + + + + + + + +The Mini-Pager Applet + + +This little applet shows a preview of the virtual desktops, lets you +switch between virtual desktops and gives you the ability to move windows +from one desktop to another by dragging them. + + + +There is also a very useful context menu used to +configure this applet: + + + + +Configure Desktops... + + +This opens the configuration dialog for virtual desktops. There you can +specify how many desktops you want to have and give them names. + + + + + +Pager Options + + +In this submenu you can configure the appearance of the Mini-Pager. It +provides the following functionality: + + + + + +Pager Layout + + +In this section you can choose in how many Rows +or Columns the desktop previews are arranged, +if you want to see which windows are currently visible on the desktops +and if icons should indicate the applications running on the different +vitual desktops. + + + + + +Text Label + + +Here you can choose if the desktop previews should be labeled by their +numbers, their names or if you you don't want them to be labeled at all. + + + + + +Background + + +You can set the background of the pager to +Elegant, Transparent +or equivalent to the Desktop Wallpaper. + + + + + + + + + + +Launch Pager + + +This launches the application &kpager;, which provides functions similar +to those offered by the Mini-Pager applet. + + + + + + + + + +The Clock Applet + + +As you might already guess, the clock applet is a small clock which +resides in &kicker;. + + + +A click with the &LMB; on the clock will show a small calendar. You can +use the single arrows to switch the months or the +double arrows for switching years. This won't +have any effect of your date settings, it's just for your information. + + + +There are some things you can do with the clock applet. This can be done +from the context menu. + + + +<guisubmenu>Type</guisubmenu> + + +There are four ways the clock can appear: + + + + +Plain + + +This lets the clock appear as a simple text that shows the time in plain text. + + + + + +Digital + + +This lets the clock appear as a digital clock showing the time in the +well known seven segment style. + + + + + +Analog + + +If this is set, the clock will be displayed as an old styled analog +clock. + + +This may only be useful if you set &kicker; to normal or large +size. + + + + + + +Fuzzy + + +This is a very unorthodox style of time display. Try it out, it is +really funny! + + + + + + + + +<guimenuitem>Show Timezone</guimenuitem> + + +Select available timezones or open the Timezones +tab of Configure dialog of the clock applet with +Configure Timezones.... + + + + +<guimenuitem>Adjust Date & Time</guimenuitem> + + +This option starts the Date & Time +configuration module in the section System Administration of the &kcontrolcenter;. + + + +You will need the super user password for adjusting date and time. + + + + + + +<guimenuitem>Date & Time Format</guimenuitem> + + +This will open the Country/Region & Language module in the section Regional & Accessibility of the &kcontrolcenter; +where you can set your formats on the page Times & Dates. There aren't any special permissions needed for that. + + + + + +<guisubmenu>Copy to Clipboard</guisubmenu> + + +If you need to paste the actual date and/or time in another application +(⪚ in a text editor), you can copy it to the clipboard with this +function. After selecting one of the available formats, the actual date +and/or time is placed in the clipboard using the appropriate format. + + + + + +<guimenuitem>Configure Clock...</guimenuitem> + + +Here you can set some general preferences of the clock applet. + + + + +Appearence + + +In the Clock Type settings you can choose between +the clock styles like in the context menu. + + + + + + + +The Plain Clock options + +In the Display section you can check if you +want to have the date and/or the seconds shown. In +Time you can choose if you want the common &kde; +look or your own custom colors and font. + + + + + +The Digital Clock options + +In the Display section you can check if you +want to have the date, the seconds and/or blinking dots shown. In +Time you can choose if you want the common +LCD-Look or your own custom colors. + + + + + +The Analog Clock options + + +In the Display section you can check if you want to +have the date and/or seconds shown. In Time you +can choose if you want the common LCD-Look or your +own custom colors. +You can also set the level of antialiasing, which means that lines will get +blurred a little bit to prevent steps in the drawing. High quality antialiasing +may catch some system load on low-end systems. + + + + + +The Fuzzy Clock options + + +In the Display section you can check if you want to +have the date shown. In Time +you can choose the colors and the font of the fuzzy clock. There is also a slider to set the +Fuzziness. This cannot be described in the +documents, just do your own experiments. + + + + + + + + + + + +The Quick Launcher Applet + + +This is a compressed application launcher. It is very useful especially +if the panel is set to normal or large size. You can add applications by +drag and drop or from the context menu. The +context menu is also used to remove an application. + + + + +The System Tray Applet + + +The System Tray is used to dock some special applications ⪚ +&klipper; or &juk;. The applications shown in the system tray all +provide individual funtionality. If you need help concerning these +options, please refer to the application handbooks. + + + +The System Tray's context menu provides the option +Configure System Tray... . If you click on it, +a dialog pops up which lets you choose applications that should not be +permanently visible in the System Tray. Hidden icons can be made visible +by clicking on the small arrow appearing on the left or top side of the +applet. + + + + +Lock/Logout Applet + +This little applet contains two buttons. +The Lock the session is used to lock the session if you +ever want to leave your &kde; unattended and don't want anybody to access it. +The Log out is used to close your &kde; session. + + + + +The Application Launcher Applet + + +This applet provides a simple command line embedded in &kicker;. Nothing +more, nothing less. + + + + + +The Runaway Process Catcher Applet + + +This applet shows a smiley which will get angry when any process catches +up too much system resources. If an application uses too much, a +messagebox will appear and ask you how to handle that application. + + + +Clicking it with the &LMB; will show a configuration dialog. Here you +can set the Update interval, which is set in +seconds, and the CPU load threshold. At the +moment, there is no real advice for setting this up, you will have to do +some experimenting. These settings will probably change in a future +release. There is also a section Programs to ignore +where you can add applications that use many resources naturally, +⪚ compilers or 3D renderers. + + + + + +&klipper; Applet + + +This applet does exactly the same like the &klipper; residing in the system +tray. It has the advantage, that it consumes a little bit less system +resources, which only matters on really slow systems, but has the +disadvantage, that it uses more space than &klipper; in the system +tray. You can read more about that in the manual for +&klipper;. + + + + + + +Panel Extensions + + +There are also some features that run outside of &kicker;, the +extensions. They are added from the +context menu by choosing Add New Panel. You can move them to any +screenborder by dragging them at the small applet +handle on their side and remove it by right clicking on an empty space and choose Remove Panel. + + + +The style of the extensions can be configured in the section of &kicker;'s preferences. + + + + +The External Taskbar Panel Extension + + +The external taskbar is just the same as the taskbar applet with the +only difference that it provides its own panel. Refer to the taskbar applet section for help about +it. + + + + + +The Child Panel Extension + + +This is just a panel like &kicker; itself, where you can add all the +stuff &kicker; is also capable. So you can have as many &kicker;s as you +want. Just add a child panel and add applications and applets to it. + + + + + +The <application>KasBar</application> Extension + + +The KasBar is an iconic replacement of the +taskbar. It always shows the icons of all currently running applications +on any desktop, they can be chosen by clicking with the &LMB;. The +active window is highlighted, minimized windows will show a little +triangle pointing downwards instead of the square in the lower right of +the icons. A triangle pointing to the right indicates that the +application is shaded. + + + + +The Dock Application Bar Extension + + +The Dock Application Bar is an external bar which lets WindowMaker +applications be docked. Just run your dockable WindowMaker programs, if +the Dock Application Bar is running, they will be automatically docked. + + + + + + +Command Reference + + +The Panel + + +There is only one standard shortcut available in &kicker;: + + + + +&Alt;F1 + + +Opens the K Menu + + + + + + + + + + +Questions and Answers + + + + + +How can I add applications, applets or anything else to the panel? + + + + +Click the &RMB; on any free space in &kicker; and choose +what you want to add. See in &kicker; Basics +for more about that. + + + + + + + +Can I have an external Taskbar just like in &kde; 1? + + + + +Yes, you can just click the &RMB; on any empty space in &kicker; and +then choose Add, +Panel and the External +Taskbar. + + + + + + + +How can I move &kicker; to another screen border? + + + + + +Simply drag it by holding the &LMB; on any empty space in &kicker; to +any screen border. + + + + + + + +How can I move extensions to another screen border? + + + + + +Just drag them by holding the &LMB; on the small +handles on the left or the top of the extension. + + + + + + + +I want the taskbar to show all applications I am running, independent on +which desktop they are. Is that possible? + + + + +It is. Click the &RMB; on the small handle of the +taskbar, then choose Configure Taskbar... and check +Show windows from all desktops in the appearing dialog. + + + + + + + +How can I access the K Menu without using the mouse? + + + + +Simply press &Alt;F1 and it will appear. + + + + + + + +Is there a way to add a menu containing all desktop icons to &kicker;? + + + + +Just start &konqueror;, go to your home folder and drag the +Desktop icon to any free space of &kicker;, then +choose Add as Quick Browser from the +appearing menu. + + + + + + + +How can I change the color and style of &kicker;? + + + + +You can change the colors of the panel with the global color module of +the Control Center or you can style the panel +itself, see in for more about that. + + + + + + + +Why is the clock showing the wrong time? + + + + +On some &RedHat;systems, the clock always shows the time in +&GMT;. This is a bug in the system setup, and not +directly related to &kicker;. However, to solve it, just create this +symbolic link: ln +/usr/share/zoneinfo +/usr/lib/zoneinfo. + + + + + + + +Is it possible to change the K button of the panel to +another picture? + + + + +Look for $HOME/.kde/share/apps/kicker/pics/go.png +and $HOME/.kde/share/apps/kicker/pics/mini/go.png +and replace them. Do not forget to flatten the replacements to one +layer, or else you will not see anything. Create the folders if +they do not already exist. Then restart &kicker;. + + + + + + + +Why is my Settings menu not working? + + + + +Your menu entries may be mixed up for some reason. Simply run +kbuildsycoca on a commandline. + + + + + +&reporting.bugs; + + + + + + +Credits and License + + +&kicker; + + + +Program copyright 1999-2000 The &kde; Team (www.kde.org). + + + + +&Matthias.Elter; &Matthias.Elter.mail; + + + + +&Matthias.Ettrich; &Matthias.Ettrich.mail; + + + + +&Wilco.Greven; &Wilco.Greven.mail; + + + + +&Rik.Hemsley; &Rik.Hemsley.mail; + + + + +&Daniel.M.Duley; &Daniel.M.Duley.mail; + + + + +&Preston.Brown; &Preston.Brown.mail; + + + + + +Original documentation copyright 2001, 2002 &Dirk.Doerflinger; +&Dirk.Doerflinger.mail; +Portions copyright 2004 &Orville.Bennett; +&Orville.Bennett.mail; +Portions copyright 2005 Titus Laska +titus.laska@gmx.de + + + +&underFDL; +&underBSDLicense; + + + +&documentation.index; + + + + + + diff --git a/doc/kicker/k_menu_icon.png b/doc/kicker/k_menu_icon.png new file mode 100644 index 000000000..b3ca6b647 Binary files /dev/null and b/doc/kicker/k_menu_icon.png differ diff --git a/doc/kicker/man-appletproxy.1.docbook b/doc/kicker/man-appletproxy.1.docbook new file mode 100644 index 000000000..4081f6c19 --- /dev/null +++ b/doc/kicker/man-appletproxy.1.docbook @@ -0,0 +1,101 @@ + + +]> + + + +KDE User's Manual + +Lauri +Watts + +&Lauri.Watts.mail; +Feb 25, 2005 +K Desktop Environment + + + +appletproxy +1 + + + +appletproxy +&kde; panel applet proxy + + + + +appletproxy +desktopfile +--configfile file +--callbackid id +KDE Generic Options +Qt Generic Options + + + + +Description +appletproxy is a small application that +allows you to run a &kicker; (&kde; panel) applet outside of &kicker; +itself. The applet will appear in it's own window, making this a convenient +way to debug panel applets. + + + +Options + + + + +The applet's desktop file + + + +The config file to be used + + + + +&DCOP; callback id of the applet container. + + + + + + + + +See Also + +kicker(1) + + + + +Examples + + + +appletproxy knewsticker + +Run &knewsticker; in a standalone window. + + + + + + + +Authors +&kappname; was written by &Matthias.Elter; and &Matthias.Ettrich; and +is maintained by &Aaron.J.Seigo; &Aaron.J.Seigo.mail; + +This man page was written for &kde; 3.4 by &Lauri.Watts; +&Lauri.Watts.mail; + + + diff --git a/doc/kicker/man-kicker.1.docbook b/doc/kicker/man-kicker.1.docbook new file mode 100644 index 000000000..99f984670 --- /dev/null +++ b/doc/kicker/man-kicker.1.docbook @@ -0,0 +1,88 @@ + + + +]> + + + +KDE User's Manual +&Lauri.Watts;&Lauri.Watts.mail; +February 27, 2005 +K Desktop Environment + + + +kicker +1 + + + +kicker +&kicker; is the &kde; panel + + + + +kicker +KDE Generic Options +Qt Generic Options + + + + +Description +&kicker; is the &kde; panel. It normally contains application +starters, applets, and a clock. + + + + +Files + + + +$KDEHOME/share/apps/kickerrc + +User specific configuration file. This file is not normally intended +to be edited directly; Most configuration items can be controlled from +&kcontrol;. + + + + +$PREFIX/share/apps/kickerrc + +Global configuration file. This file is not normally intended to be +edited directly; Most configuration items can be controlled from &kcontrol;. +Global settings may be configured by the system administrator to either set +defaults, or lock down options that may not be altered by the users of the +system. + + + + + + + +See Also + +More detailed user documentation is available from help:/kicker +(either enter this URL into &konqueror;, or run +khelpcenter +help:/kicker). + + + + +Authors +&kappname; was written by &Matthias.Elter; and &Matthias.Ettrich; and +is maintained by &Aaron.J.Seigo; &Aaron.J.Seigo.mail; + +This man page was written for &kde; 3.4 by &Lauri.Watts; +&Lauri.Watts.mail; + + + + diff --git a/doc/kicker/printsys_icon.png b/doc/kicker/printsys_icon.png new file mode 100644 index 000000000..13adbd006 Binary files /dev/null and b/doc/kicker/printsys_icon.png differ diff --git a/doc/kicker/quickbrowser_icon.png b/doc/kicker/quickbrowser_icon.png new file mode 100644 index 000000000..fbc259e95 Binary files /dev/null and b/doc/kicker/quickbrowser_icon.png differ diff --git a/doc/kicker/recent_docs_icon.png b/doc/kicker/recent_docs_icon.png new file mode 100644 index 000000000..21f079bf4 Binary files /dev/null and b/doc/kicker/recent_docs_icon.png differ diff --git a/doc/kicker/screenshot_left.png b/doc/kicker/screenshot_left.png new file mode 100644 index 000000000..8b29998ca Binary files /dev/null and b/doc/kicker/screenshot_left.png differ diff --git a/doc/kicker/screenshot_right.png b/doc/kicker/screenshot_right.png new file mode 100644 index 000000000..b5bcee61c Binary files /dev/null and b/doc/kicker/screenshot_right.png differ diff --git a/doc/kicker/taskbar_group.png b/doc/kicker/taskbar_group.png new file mode 100644 index 000000000..e5484fe96 Binary files /dev/null and b/doc/kicker/taskbar_group.png differ diff --git a/doc/kicker/terminals_icon.png b/doc/kicker/terminals_icon.png new file mode 100644 index 000000000..de458c184 Binary files /dev/null and b/doc/kicker/terminals_icon.png differ diff --git a/doc/kicker/windowlist_icon.png b/doc/kicker/windowlist_icon.png new file mode 100644 index 000000000..ca164a12a Binary files /dev/null and b/doc/kicker/windowlist_icon.png differ diff --git a/doc/kinfocenter/Makefile.am b/doc/kinfocenter/Makefile.am new file mode 100644 index 000000000..251280f85 --- /dev/null +++ b/doc/kinfocenter/Makefile.am @@ -0,0 +1,6 @@ + +SUBDIRS = $(AUTODIRS) + +KDE_LANG= en +KDE_DOCS = AUTO + diff --git a/doc/kinfocenter/cdinfo/Makefile.am b/doc/kinfocenter/cdinfo/Makefile.am new file mode 100644 index 000000000..e4070c171 --- /dev/null +++ b/doc/kinfocenter/cdinfo/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/cdinfo diff --git a/doc/kinfocenter/cdinfo/index.docbook b/doc/kinfocenter/cdinfo/index.docbook new file mode 100644 index 000000000..6048e5873 --- /dev/null +++ b/doc/kinfocenter/cdinfo/index.docbook @@ -0,0 +1,51 @@ + + + +]> + +
+CD-ROM Information/Capabilities + + + + +Jahshan +Bhatti +
jabhatti91@gmail.com
 + + + + +2006-06-13 +3.00.00 + + +KDE +KControl +cd-rom +capabilities information + + + + +CD-ROM Information/Capabilities + + +This page displays information about the attached CD-ROM drives and their capabilites, + + + +On &Linux;, this information is read from /proc/sys/dev/cdrom/info, which are only available if +the /proc pseudo-filesystem is +compiled into the kernel. + + + +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/devices/Makefile.am b/doc/kinfocenter/devices/Makefile.am new file mode 100644 index 000000000..dc255fa48 --- /dev/null +++ b/doc/kinfocenter/devices/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/devices diff --git a/doc/kinfocenter/devices/index.docbook b/doc/kinfocenter/devices/index.docbook new file mode 100644 index 000000000..43eac4de9 --- /dev/null +++ b/doc/kinfocenter/devices/index.docbook @@ -0,0 +1,60 @@ + + + +]> + +
+Device Information + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +device +system information + + + + +Device Information + + +This page displays information about the available devices, + + + + +The exact information displayed is system-dependent. On some systems, +device information cannot be displayed yet. + + + + +On &Linux;, this information is read from /proc/devices and /proc/misc, which are only available if +the /proc pseudo-filesystem is +compiled into the kernel. Devices are listed by group (Character, Block, +or Miscellaneous). The device major number is listed, followed by an +identifying label. + + + +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/dma/Makefile.am b/doc/kinfocenter/dma/Makefile.am new file mode 100644 index 000000000..0e2aa88e7 --- /dev/null +++ b/doc/kinfocenter/dma/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/dma diff --git a/doc/kinfocenter/dma/index.docbook b/doc/kinfocenter/dma/index.docbook new file mode 100644 index 000000000..75fb55c75 --- /dev/null +++ b/doc/kinfocenter/dma/index.docbook @@ -0,0 +1,64 @@ + + + +]> + +
+<acronym>DMA</acronym> Channel Information + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +DMA +system information + + + + +<acronym>DMA</acronym> Channel Information + + This page displays information about the DMA +(Direct Memory Access) Channels. A DMA channel is a +direct connection that allows devices to transfer data to and from +memory without going through the processor. Typically, i386-architecture +systems (PC's) have eight DMA +channels (0-7). + + The exact information displayed is system-dependent. On +some systems, DMA Channel information cannot be +displayed yet. + + On &Linux;, this information is read from /proc/dma, which is only available if the +/proc pseudo-filesystem is +compiled into the kernel. + + A list of all currently-registered (ISA bus) +DMA channels that are in use is shown. The first +column shows the DMA channel, and the second column +shows the device which uses that channel. + + +Unused DMA channels are not listed. + + + +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/index.docbook b/doc/kinfocenter/index.docbook new file mode 100644 index 000000000..a62ca655d --- /dev/null +++ b/doc/kinfocenter/index.docbook @@ -0,0 +1,341 @@ + + + + +]> + + + +The &infocenter; + + + +Michael +McBride +
mpmcbride7@yahoo.com
 + + + +2002-07-03 +3.10.00 + + +This documentation describes &kde;'s information center. + + + +KDE +kinfocenter +system +information +module + + + + + +The &infocenter; + + +The &infocenter; (from now on referred to simply as the +information center) provides you with a centralized and convenient +overview of your &kde; and system settings. + + + +The information center is made up of multiple modules. Each module is a +separate application, but the information center organizes all of these +programs into a convenient location. + + + + + +Using The &infocenter; + + +This next section details the use of the information center itself. For +information on individual modules, please see Info +Center Modules + + + +Starting the &infocenter; + + +The &infocenter; can be started 3 ways: + + + + + +By selecting K +ButtonSystemInfo +Center from the &kde; Panel. + + + + + +By pressing &Alt;F2. + + + +This will bring up a dialog box. Type +kinfocenter, and click +Run or press Enter. + + + + + +You can type kinfocenter & at any command prompt. + + + + + +All three of these methods are equivalent, and produce the same result. + + + + + +The &infocenter; Screen + + +When you start the information center, you are presented with a window, +which can be divided into 3 functional parts. + + + +Across the top is a menubar. The menubar will provide you with quick +access to most of &infocenter;'s features. The menus are detailed in +The &kde; Info Center +Menus. + + + +Along the left hand side, is a column. This is a where you choose which +module to investigate. You can learn how to navigate through the modules +in the section called Navigating +Modules. + + + +The main panel shows you some system information. + + + + + + + +The &infocenter; Menus + + +This next section gives you a brief description of what each menu item +does. + + + +<guimenu>File</guimenu> Menu + + +The File menu has a single entry. + + + + + + + +&Ctrl;Q + +File +Quit + + + +Closes the info center. + + + + + + + + +<guimenu>Help</guimenu> Menu + +&help.menu.documentation; + + + + + + +Exiting The &kde; Information Center + + +You can exit the info center one of three ways: + + + + + +Select File +Quit from the menu bar. + + + + +Type &Ctrl;Q +on the keyboard. + + + + + +Click on the Close button on the frame surrounding +the info center. + + + + + + + + + + + +The &infocenter; Modules + + +Navigating Modules + + +This is a list of the standard configuration +modules (sorted by category) provided by the &kde; base package. Please note that there +may be many more modules on your system if you have installed additional +software. + + + + +Devices + + +DMA-Channels + + +Interrupts + + +IO-Ports + + +Memory + + +Network Interfaces + + +OpenGL + + +Partitions + + +PCI + + +PCMCIA + + +Processor + + +Protocols + + +Samba Status Information + + +SCSI + + +Sound + + +USB Devices + + +X-Server + + + + + + + + + + +Credits and License + +&infocenter; +Program copyright 1997-2001 The &infocenter; Developers +Contributors: + + +Matthias Hoelzer-Kluepfel +hoelzer@kde.org +Matthias Elter elter@kde.org + + +Documentation copyright 2000 Michael +McBride mpmcbride7@yahoo.com + +Contributors: + + +Paul Campbell paul@taniwha.com +Helge Deller deller@kde.org +Mark Donohoe +Pat Dowler +Duncan Haldane duncan@kde.org +Steffen Hansen stefh@mip.ou.dk. +Matthias Hoelzer-Kluepfel hoelzer@kde.org +Martin Jones mjones@kde.org +Jost Schenck jost@schenck.de +Jonathan Singer jsinger@leeta.net +Thomas Tanghus tanghus@earthling.net +Krishna Tateneni tateneni@pluto.njcc.com> +Ellis Whitehead ewhitehe@uni-freiburg.de + + + + + +&underFDL; +&underGPL; + + + + diff --git a/doc/kinfocenter/interrupts/Makefile.am b/doc/kinfocenter/interrupts/Makefile.am new file mode 100644 index 000000000..46be8b9ce --- /dev/null +++ b/doc/kinfocenter/interrupts/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/interrupts diff --git a/doc/kinfocenter/interrupts/index.docbook b/doc/kinfocenter/interrupts/index.docbook new file mode 100644 index 000000000..b29611202 --- /dev/null +++ b/doc/kinfocenter/interrupts/index.docbook @@ -0,0 +1,70 @@ + + + +]> + +
+Interrupt Request (<abbrev>IRQ</abbrev>) Lines + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +IRQ +interrupts +system information + + + + +Interrupt Request (<abbrev>IRQ</abbrev>) Lines in Use + +This page displays information about the Interrupt Request +Lines in use, and the devices that use them. + +An IRQ is a hardware line used in a +PC by (ISA bus) devices like +keyboards, modems, sound cards, &etc;, to send interrupt signals to the +processor to tell it that the device is ready to send or accept data. +Unfortunately, there are only sixteen IRQ's (0-15) +available in the i386 (PC) architecture for sharing among +the various ISA devices. + +Many hardware problems are the result of IRQ +conflicts, when two devices try to use the same IRQ, or +software is misconfigured to use a different IRQ from the +one a device is actually configured for. + +The exact information displayed is system-dependent. On some +systems, IRQ information cannot be displayed + yet. + +On &Linux;, this information is read from +/proc/interrupts, which is only +available if the /proc +pseudo-filesystem is compiled into the kernel. + +The first column, is the IRQ number. The second +column, is the number of interrupts that have been received since the last +reboot. The third column shows the type of interrupt. The fourth, +identifies the device assigned to that interrupt. + +The user cannot modify any settings on this page. + + + +
+ diff --git a/doc/kinfocenter/ioports/Makefile.am b/doc/kinfocenter/ioports/Makefile.am new file mode 100644 index 000000000..56e830b08 --- /dev/null +++ b/doc/kinfocenter/ioports/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/ioports diff --git a/doc/kinfocenter/ioports/index.docbook b/doc/kinfocenter/ioports/index.docbook new file mode 100644 index 000000000..fa662feba --- /dev/null +++ b/doc/kinfocenter/ioports/index.docbook @@ -0,0 +1,64 @@ + + + +]> + +
+I/O Port + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + + +2002-02-12 +3.00.00 + + +KDE +KControl +ioports +system information + + + + +Input/Output Port Information + +This page displays information about the I/O ports. + +I/O Ports are memory addresses used by the processor for direct +communication with a device that has sent an +interrupt signal to the processor. + +The exchange of commands or data between the processor and the device +takes place through the I/O port address of the device, which is a + hexadecimal +number. No two devices can share the same I/O port. Many devices use + multiple +I/O port addresses, which are expressed as a range of hexadecimal +numbers. + +The exact information displayed is system-dependent. On some +systems, I/O port information can not yet be displayed. + +On &Linux;, this information is read from /proc/ioports which is only available if +the /proc pseudo-filesystem is +compiled into the kernel. A list of all currently-registered I/O port +regions that are in use is shown. + +The first column is the I/O port (or the range of I/O ports), the +second column identifies the device that uses these I/O ports. + +The user cannot modify any settings on this page. + + +
diff --git a/doc/kinfocenter/memory/Makefile.am b/doc/kinfocenter/memory/Makefile.am new file mode 100644 index 000000000..e9a9e23ef --- /dev/null +++ b/doc/kinfocenter/memory/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/memory diff --git a/doc/kinfocenter/memory/index.docbook b/doc/kinfocenter/memory/index.docbook new file mode 100644 index 000000000..19d10fc57 --- /dev/null +++ b/doc/kinfocenter/memory/index.docbook @@ -0,0 +1,108 @@ + + + +]> + +
+Memory Information + + + +&Mike.McBride; + + + + + +2002-02-13 +3.00.00 + + +KDE +KControl +memory +system information + + + + +Memory Information + +This module displays the current memory usage. It is updated +constantly, and can be very useful for pinpointing bottlenecks when certain +applications are executed. + + +Memory Types + +The first thing you must understand, is there are two types of +memory, available to the operating system and the programs +that run within it. + +The first type, is called physical memory. This is the memory located +within the memory chips, within your computer. This is the +RAM (for Random Access Memory) you bought when you +purchased your computer. + +The second type of memory, is called virtual or swap memory. This +block of memory, is actually space on the hard drive. The operating +system reserves a space on the hard drive for swap space. +The operating system can use this virtual memory (or swap space), if it +runs out of physical memory. The reason this is called +swap memory, is the operating system takes some data that +it doesn't think you will want for a while, and saves that to disk in +this reserved space. The operating system then loads the new data you +need right now. It has swapped the not needed data, for +the data you need right now. Virtual or swap memory is not as fast as +physical memory, so operating systems try to keep data (especially often +used data), in the physical memory. + +The total memory, is the combined total of physical memory and +virtual memory. + + + + +Memory Information Module + +This window is divided into a top and bottom section + +The top section shows you the total physical memory, total free + physical memory, shared memory, and buffered memory. + +All four values are represented as the total number of bytes, and + as the number of megabytes (1 megabyte = slightly more than 1,000,000 + bytes) + +The bottom section shows you three graphs: + + +Total Memory (this is the combination of physical and virtual memory). +Physical Memory +Virtual memory, or Swap Space. + + +The green areas are free, and the red areas are used. + +The exact values of each type of memory are not critical, and + they change regularly. When you evaluate this page, look at + trends. + +Does your computer have plenty of free space (green areas)? If + not, you can increase the swap size or increase the physical + memory. + +Also, if your computer seems sluggish: is your physical memory + full, and does the hard drive always seem to be running? This suggests + that you do not have enough physical memory, and your computer is + relying on the slower virtual memory for commonly used data. Increasing + your physical memory will improve the responsiveness of your + computer. + + + + + +
diff --git a/doc/kinfocenter/nics/Makefile.am b/doc/kinfocenter/nics/Makefile.am new file mode 100644 index 000000000..73ab1b332 --- /dev/null +++ b/doc/kinfocenter/nics/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/nics diff --git a/doc/kinfocenter/nics/index.docbook b/doc/kinfocenter/nics/index.docbook new file mode 100644 index 000000000..f82552c28 --- /dev/null +++ b/doc/kinfocenter/nics/index.docbook @@ -0,0 +1,45 @@ + + + +]> + +
+Network Interfaces + + + +&Lauri.Watts; + + + +2002-02-11 +3.00.00 + + +KDE +KControl +Network +Interfaces + + + + + +Network Interfaces + + +This page displays information about the network interfaces +installed in your computer. + + +The exact information displayed is system-dependent. On +some systems, this information can not yet be displayed. + +The user cannot modify any settings on this page. + + + + +
diff --git a/doc/kinfocenter/opengl/Makefile.am b/doc/kinfocenter/opengl/Makefile.am new file mode 100644 index 000000000..cc8923bc3 --- /dev/null +++ b/doc/kinfocenter/opengl/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG= en +KDE_DOCS = kinfocenter/opengl diff --git a/doc/kinfocenter/opengl/index.docbook b/doc/kinfocenter/opengl/index.docbook new file mode 100644 index 000000000..62af34008 --- /dev/null +++ b/doc/kinfocenter/opengl/index.docbook @@ -0,0 +1,47 @@ + + + +]> + +
+<acronym>OpenGL</acronym> + + + +IlyaKorniykok_ilya@ukr.net + + + + + + + + +KDE +KControl +OpenGL +system information + + + + + +OpenGL + +This page displays information about installed OpenGL implementation. +OpenGL (for "Open Graphics Library") is a cross-platform, +hardware independent interface for 3D graphics. + +GLX is the binding for OpenGL to X Window system. + + DRI (Direct Rendering Infrastucture) provides hardware acceleration for OpenGL. +You must have a videocard with 3D accelerator and properly installed driver for this. + + +Read more at the official OpenGL site http://www.opengl.org + + + +
diff --git a/doc/kinfocenter/partitions/Makefile.am b/doc/kinfocenter/partitions/Makefile.am new file mode 100644 index 000000000..7eab338b4 --- /dev/null +++ b/doc/kinfocenter/partitions/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/partitions diff --git a/doc/kinfocenter/partitions/index.docbook b/doc/kinfocenter/partitions/index.docbook new file mode 100644 index 000000000..f3655a8cf --- /dev/null +++ b/doc/kinfocenter/partitions/index.docbook @@ -0,0 +1,56 @@ + + + +]> + +
+Partition Information + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +drive partition +system information + + + + +Partition Information + +This page displays information about partitions on your hard +drives. + +The exact information displayed is system-dependent. On +some systems, partition information cannot be displayed +yet. + +On &Linux;, this information is read from /proc/partitions, which is only available +if the /proc pseudo-filesystem is +compiled into the (2.1.x or later) kernel. + +The first two columns are the major and minor numbers +respectively. The third column is the number of blocks (usually 1 +block = 1024 bytes). The fourth column is a label for the +device. + +The user cannot modify any settings on this page. + + + +
+ diff --git a/doc/kinfocenter/pci/Makefile.am b/doc/kinfocenter/pci/Makefile.am new file mode 100644 index 000000000..b6702265a --- /dev/null +++ b/doc/kinfocenter/pci/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/pci diff --git a/doc/kinfocenter/pci/index.docbook b/doc/kinfocenter/pci/index.docbook new file mode 100644 index 000000000..1d4d8b3f9 --- /dev/null +++ b/doc/kinfocenter/pci/index.docbook @@ -0,0 +1,57 @@ + + + +]> + +
+<acronym>PCI</acronym>-bus and Installed <acronym>PCI</acronym> Cards + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +PCI +system information + + + + + +<acronym>PCI</acronym>-bus and Installed <acronym>PCI</acronym> +Cards + +This page displays information about the +PCI-bus and installed PCI cards, +and other devices that use the Peripheral Component Interconnect +(PCI) bus. + +The exact information displayed is system-dependent. On some +systems, PCI-information can not yet be +displayed. + +On &Linux;, this information is read from /proc/pci which is only available if the +/proc pseudo-filesystem is +compiled into the kernel. A listing of all PCI +devices found during kernel initialization, and their configuration, is +shown. + +Each entry begins with a bus, device and function number. +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/pcmcia/Makefile.am b/doc/kinfocenter/pcmcia/Makefile.am new file mode 100644 index 000000000..23040b3c9 --- /dev/null +++ b/doc/kinfocenter/pcmcia/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/pcmcia diff --git a/doc/kinfocenter/pcmcia/index.docbook b/doc/kinfocenter/pcmcia/index.docbook new file mode 100644 index 000000000..901fdf2e5 --- /dev/null +++ b/doc/kinfocenter/pcmcia/index.docbook @@ -0,0 +1,38 @@ + + + +]> + +
+<acronym>PCMCIA</acronym> + + + +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +Laptop +PCMCIA + + + + +<acronym>PCMCIA</acronym> + +This module displays information about PCMCIA +Cards + +The exact information is system dependent. On most systems no +information is displayed at all. + + +
diff --git a/doc/kinfocenter/processor/Makefile.am b/doc/kinfocenter/processor/Makefile.am new file mode 100644 index 000000000..7cdf67a93 --- /dev/null +++ b/doc/kinfocenter/processor/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/processor diff --git a/doc/kinfocenter/processor/index.docbook b/doc/kinfocenter/processor/index.docbook new file mode 100644 index 000000000..3794aca67 --- /dev/null +++ b/doc/kinfocenter/processor/index.docbook @@ -0,0 +1,56 @@ + + + +]> + +
+Processor Information + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +CPU +processor +system information + + + + +Processor Information + +This page displays information about the system +Central Processing Unit (CPU). + +The exact information displayed is system-dependent. On +some systems, processor information cannot be displayed +yet. + +On &Linux;, this information is read from /proc/cpuinfo, which is only available if +the /proc pseudo-filesystem is +compiled into the kernel. + +The exact contents of the window will depend on the +CPU(s) in your machine, but the window is organized +into two columns. The first column is the parameter, and the second +column is the value of that parameter. + +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/protocols/Makefile.am b/doc/kinfocenter/protocols/Makefile.am new file mode 100644 index 000000000..afc73fa8a --- /dev/null +++ b/doc/kinfocenter/protocols/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/protocols diff --git a/doc/kinfocenter/protocols/index.docbook b/doc/kinfocenter/protocols/index.docbook new file mode 100644 index 000000000..a5a37658b --- /dev/null +++ b/doc/kinfocenter/protocols/index.docbook @@ -0,0 +1,39 @@ + + + +]> + +
+Protocols + + + +&Lauri.Watts; + + + + +KDE +Protocols +IOSlaves + + + + +Protocols + +On the left of the panel you will see a list of the IOSlaves that +are installed on your system. IOSlaves are how &kde; applications +talk to other computers, other applications, or act on +files. + +Clicking on an IOSlave name will display some help information +about that IOSlave, such as how to use it, and what it does. + +The protocols module is purely informational, you cannot change +any settings here. + + +
\ No newline at end of file diff --git a/doc/kinfocenter/samba/Makefile.am b/doc/kinfocenter/samba/Makefile.am new file mode 100644 index 000000000..91de8fa54 --- /dev/null +++ b/doc/kinfocenter/samba/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/samba + diff --git a/doc/kinfocenter/samba/index.docbook b/doc/kinfocenter/samba/index.docbook new file mode 100644 index 000000000..37b14c48c --- /dev/null +++ b/doc/kinfocenter/samba/index.docbook @@ -0,0 +1,207 @@ + + + +]> + +
+Samba Status Information + + +&Alexander.Neundorf; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +Samba +system information + + + + + + +Samba Status Information + +The Samba and NFS Status Monitor is a front end +to the programs smbstatus and +showmount. Smbstatus reports on current Samba +connections, and is part of the suite of Samba tools, which implements +the SMB (Session Message Block) protocol, also called +the NetBIOS or LanManager protocol. + +This protocol can be used to provide printer sharing or drive +sharing services on a network including machines running the various +flavors of &Microsoft; &Windows;. + +showmount is part of the NFS +software package. NFS stands for Network File System +and is the traditional &UNIX; way to share folders over the +network. In this case the output of showmount + is parsed. On some systems showmount is in +/usr/sbin, check if you have +showmount in your PATH. + + +Exports + +On this page you can see a big list which shows the currently +active connections to Samba shares and NFS exports of +your machine. The first column shows you whether the resource is a Samba +(SMB) share or a NFS export. The +second column contains the name of the share, the third the name of the +remote host, which accesses this share. The remaining columns have only +a meaning for Samba-shares. + +The fourth column contains the User ID of the +user, who accesses this share. Note that this does not have to be equal +to the &UNIX; user ID of this user. The same applies +for the next column, which displays the group ID of the +user. + +Each connection to one of your shares is handled by a single +process (smbd), the next column shows the process +ID (pid) of this +smbd. If you kill this process the connected user +will be disconnected. If the remote user works from &Windows;, as soon +as this process is killed a new one will be created, so he will almost +not notice it. + +The last column shows how many files this user has currently open. +Here you see only, how many files he has open just +now, you don't see how many he copied or formerly opened &etc; + + + + +Imports + + Here you see which Samba- and NFS-shares from +other hosts are mounted on your local system. The first column shows +wether it is a Samba- or NFS-share, the second column +displays the name of the share, and the third shows where it is +mounted. + +The mounted NFS-shares you should see on +&Linux; (this has been tested), and it should also work on &Solaris; +(this has not been tested). + + + + +Log + +This page presents the contents of your local samba log file in a +nice way. If you open this page, the list will be empty. You have to +press the Update button, then the samba log file +will be read and the results displayed. Check whether the samba log file +on your system is really at the location as specified in the input +line. If it is somewhere else or if it has another name, correct +it. After changing the file name you have to press +Update again. + +Samba logs its actions according to the log level (see +smb.conf). If loglevel = 1, samba logs only when +somebody connects to your machine and when this connection is closed +again. If log level = 2, it logs also if somebody opens a file and if he +closes the file again. If the log level is higher than 2, yet more +stuff is logged. + +If you are interested in who accesses your machine, and which +files are accessed, you should set the log level to 2 and regularly +create a new samba log file (⪚ set up a cron task +which once a week moves your current samba log file into another +folder or something like that). Otherwise your samba log file may +become very big. + +With the four checkboxes below the big list you can decide, which +events are displayed in the list. You have to press +Update to see the results. If the log level of +your samba is too low, you won't see everything. + +By clicking on the header of one column you can sort the list by +this column. + + + + + +Statistics + +On this page you can filter the contents of the third page for +certain contents. + +Let's say the Event field (not the one in the +list) is set to Connection, +Service/File is set to *, +Host/User is set to *, +Show expanded service info is disabled and +Show expanded host info is disabled. + +If you press Update now, you will see how +often a connection was opened to share * (&ie; to any +share) from host * (&ie; from any host). Now enable +Show expanded host info and press +Update again. Now you will see for every host +which matches the wildcard *, how many connections +were opened by him. + +Now press clear. + +Now set the Event field to File Access and +enable Show expanded service info and press +Update again. + +Now you will see how often every single file was accessed. If you +enable Show expanded host info too, you will see +how often every single user opened each file. + +In the input lines Service/File and +Host/User you can use the wildcards +* and ? in the same way you use +them at the command line. Regular expressions are not +recognized. + +By clicking on the header of a column you can sort the list by +this column. This way you can check out which file was opened most +often, or which user opened the most files or whatever. + + + + + +Section Author + +Module copyright 2000: Michael Glauche and &Alexander.Neundorf; &Alexander.Neundorf.mail; + +Originally written by: Michael Glauche + +Currently maintained by: &Alexander.Neundorf; &Alexander.Neundorf.mail; + + +Contributors +Conversion to kcontrol applet: +&Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail; +Use of KProcess instead of popen, and more error checking: +&David.Faure; &David.Faure.mail; +Conversion to kcmodule, added tab pages 2,3,4, bug +fixed: +&Alexander.Neundorf; &Alexander.Neundorf.mail; + + +Documentation copyright 2000 &Alexander.Neundorf; &Alexander.Neundorf.mail; + +Documentation translated to docbook by &Mike.McBride; &Mike.McBride.mail; + + + + + + +
\ No newline at end of file diff --git a/doc/kinfocenter/scsi/Makefile.am b/doc/kinfocenter/scsi/Makefile.am new file mode 100644 index 000000000..09cdb4e25 --- /dev/null +++ b/doc/kinfocenter/scsi/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = kinfocenter/scsi diff --git a/doc/kinfocenter/scsi/index.docbook b/doc/kinfocenter/scsi/index.docbook new file mode 100644 index 000000000..87ec0934f --- /dev/null +++ b/doc/kinfocenter/scsi/index.docbook @@ -0,0 +1,56 @@ + + + +]> + +
+<acronym>SCSI</acronym> Interface Information + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +SCSI +system information + + + + + +<acronym>SCSI</acronym> Interface Information + +This page displays information about Small Computer Systems +Interface (SCSI) Interfaces and the attached +SCSI devices. + +The exact information displayed is system-dependent. On +some systems SCSI information cannot be displayed +yet. + +On &Linux;, this information is read from /proc/scsi/scsi, which is only available +if the /proc pseudo-filesystem is +compiled into the kernel. A listing of all SCSI +devices known to the kernel is shown. + +The devices are sorted numerically by their host, channel, and +ID numbers. + +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/sound/Makefile.am b/doc/kinfocenter/sound/Makefile.am new file mode 100644 index 000000000..611f571ca --- /dev/null +++ b/doc/kinfocenter/sound/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/sound diff --git a/doc/kinfocenter/sound/index.docbook b/doc/kinfocenter/sound/index.docbook new file mode 100644 index 000000000..de1fd601d --- /dev/null +++ b/doc/kinfocenter/sound/index.docbook @@ -0,0 +1,51 @@ + + + +]> + +
+Soundcard Information + + + +&Matthias.Hoelzer-Kluepfel; +&Helge.Deller; +&Duncan.Haldane; +&Mike.McBride; + + + +2002-02-12 +3.00.00 + + +KDE +KControl +soundcard +system information + + + + + +Soundcard Information + +This page displays information about any soundcards installed in the +system. + +The exact information displayed is system-dependent. On some +systems, soundcard information cannot be displayed yet. + +On &Linux;, this information is read either from /dev/sndstat, if present, or from +/proc/sound, which is only +available if the /proc +pseudo-filesystem is compiled into the (2.1.x or later) kernel. + +The user cannot modify any settings on this page. + + + +
diff --git a/doc/kinfocenter/usb/Makefile.am b/doc/kinfocenter/usb/Makefile.am new file mode 100644 index 000000000..80cc84914 --- /dev/null +++ b/doc/kinfocenter/usb/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/usb diff --git a/doc/kinfocenter/usb/index.docbook b/doc/kinfocenter/usb/index.docbook new file mode 100644 index 000000000..8936fa796 --- /dev/null +++ b/doc/kinfocenter/usb/index.docbook @@ -0,0 +1,43 @@ + + + +]> + +
+<acronym>USB</acronym> + + + + + + + + + + + + +2002-02-12 +3.00.00 + + +KControl +USB +System Information + + + + + +<acronym>USB</acronym> + +This module allows you to see the devices attached to your +USB bus(es). + +This module is for information only, you cannot edit any +information you see here. + + +
\ No newline at end of file diff --git a/doc/kinfocenter/xserver/Makefile.am b/doc/kinfocenter/xserver/Makefile.am new file mode 100644 index 000000000..f72dcdbbf --- /dev/null +++ b/doc/kinfocenter/xserver/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/xserver diff --git a/doc/kinfocenter/xserver/index.docbook b/doc/kinfocenter/xserver/index.docbook new file mode 100644 index 000000000..a56e47fb3 --- /dev/null +++ b/doc/kinfocenter/xserver/index.docbook @@ -0,0 +1,56 @@ + + + +]> + +
+X Server Information + + + +&Mike.McBride; + + + + + +2002-02-12 +3.00.00 + + +KDE +KControl +X server +system information + + + + +X Server Information + +This screen is useful for getting specific information about your +X server and the current session of X. + +When you open this module, you are presented with some +information. The left hand side of the window is organized into a +tree. Some of the elements have a plus sign in front of the label. +Clicking this sign opens a submenu related to the +label. Clicking on a minus sign in front of a label hides the +submenu. + +The right hand side of the window contains the individual +values for each of the parameters on the left. + +The information presented will vary depending on your +setup. + +Some setups may not be able to determine some or all of the +parameters. + +You can not change any values from this menu. It is for +information only. + + +
diff --git a/doc/kioslave/Makefile.am b/doc/kioslave/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kioslave/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kioslave/bzip.docbook b/doc/kioslave/bzip.docbook new file mode 100644 index 000000000..9a3dc90cb --- /dev/null +++ b/doc/kioslave/bzip.docbook @@ -0,0 +1,29 @@ +
+bzip + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +bzip is a compression program. It is rarely +used today, having been replaced with bzip2, which offers much better +compression. + +The bzip kioslave is not directly usable, and is intended for use +as a filter. For example, the tar kioslave can filter a file through +the bzip kioslave, in order to display the contents of a tar.bz file directly in a &konqueror; +window. + +If you click on a file compressed with a bz extension in &konqueror;, this kioslave is +used to uncompress it and display it as a normal (uncompressed) +file. + +If you are a developer, and would like to use the bzip filter, +you can find documentation on using kioslaves at http://developer.kde.org + +
diff --git a/doc/kioslave/bzip2.docbook b/doc/kioslave/bzip2.docbook new file mode 100644 index 000000000..9551632a5 --- /dev/null +++ b/doc/kioslave/bzip2.docbook @@ -0,0 +1,29 @@ +
+bzip2 + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +Bzip2 is a compression program + +The bzip2 kioslave is not directly usable, and is intended for use +as a filter. For example, the tar kioslave can filter a file through +the bzip2 kioslave, in order to display the contents of a tar.bz2 file directly in a &konqueror; +window. + +If you click on a file compressed with a .bz2 in &konqueror;, this kioslave is used to +uncompress it and display it as a normal (uncompressed) file. + +If you are a developer, and would like to use the bzip2 filter, +you can find documentation on using kioslaves at http://developer.kde.org + + See the manual: bzip2. + + +
diff --git a/doc/kioslave/cgi.docbook b/doc/kioslave/cgi.docbook new file mode 100644 index 000000000..5df94da13 --- /dev/null +++ b/doc/kioslave/cgi.docbook @@ -0,0 +1,24 @@ +
+cgi + + +&Lauri.Watts;&Lauri.Watts.mail; + + + + +The CGI slave provides a way to execute +CGI programs without the need to have a running web +server. This can for example be used for local testing of +CGI programs or for using search engines that only +provide a CGI frontend like the one from +Doxygen. + +The slave implements the cgi: protocol. It +uses the filename from the given &URL; and searches a configurable +list of folders. If it finds an executable with the given name it +executes it, passes the arguments of the &URL; and sets the +environment variables needed by CGI +programs. + +
diff --git a/doc/kioslave/data.docbook b/doc/kioslave/data.docbook new file mode 100644 index 000000000..ca0e4e9a5 --- /dev/null +++ b/doc/kioslave/data.docbook @@ -0,0 +1,47 @@ +
+Data URLs + + + +LeoSavernik +
l.savernik@aon.at
+ + + + +2003-02-06 + + + + +Data URLs allow small document data to be included in the URL itself. +This is useful for very small HTML testcases or other occasions that do not +justify a document of their own. + +data:,foobar +(note the comma after the colon) will deliver a text document that contains +nothing but foobar + + +The last example delivered a text document. For HTML documents one +has to specify the MIME type text/html: +data:text/html,<title>Testcase</title><p>This +is a testcase</p>. This will produce exactly the same +output as if the content had been loaded from a document of its own. + + +Specifying alternate character sets is also possible. Note that 8-Bit +characters have to be escaped by a percentage sign and their two-digit +hexadecimal codes: +data:;charset=iso-8859-1,Gr%FC%DFe aus Schl%E4gl +results in +Grüße aus Schlägl +whereas omitting the charset attribute might lead to something like +Gr??e aus Schl?gl + + +IETF +RFC2397 provides more information. + +
+ diff --git a/doc/kioslave/file.docbook b/doc/kioslave/file.docbook new file mode 100644 index 000000000..a9031a259 --- /dev/null +++ b/doc/kioslave/file.docbook @@ -0,0 +1,20 @@ +
+file + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + + +The file protocol is used by all &kde; applications to +display locally available files. + + +Entering +file:/directoryname in &konqueror; + lists the files of this folder. + + +
diff --git a/doc/kioslave/finger.docbook b/doc/kioslave/finger.docbook new file mode 100644 index 000000000..27b278c48 --- /dev/null +++ b/doc/kioslave/finger.docbook @@ -0,0 +1,33 @@ +
+finger + + +&Lauri.Watts;&Lauri.Watts.mail; + + + + +Finger is a program to display information about users. + +If finger is enabled on the remote machine, you may be given +information on the user's real name, if they are currently logged in, if +they have mail and the text of their .plan file in +their home folder. + +Finger is normally associated with a user@hostname address, which +may or may not be the same as a users email address. + +Most Internet Service Providers no longer allow finger access, so, +you may find that you get no useful answer for most people. + +Other people use their local .plan file to +hold such information as PGP keys, the fact they are +on vacation, and all sorts of information. + +Use the finger kioslave like this: +finger://username@hostname + + See the manual: finger. + + +
diff --git a/doc/kioslave/fish.docbook b/doc/kioslave/fish.docbook new file mode 100644 index 000000000..5063abd04 --- /dev/null +++ b/doc/kioslave/fish.docbook @@ -0,0 +1,66 @@ +
+fish + + +&Joerg.Walter; &Joerg.Walter.mail; +&Brad.Hards; &Brad.Hards.mail; + + + +2005-02-29 +1.1.2 + + + +Allows you to access another computer's files using the SEcure Shell (SSH) protocol. The remote computer needs to be running the SSH daemon, but the remainder of the protocol uses standard commandline tools as discussed below. + +You can use the fish kioslave like this: +fish://hostname or fish://username@hostname. + +You need to use double forward slashes. + +You can omit the username (and the trailing +@ symbol) if you have the same username on both computers. + +You can add a password in the format: +fish://username:password@hostname +but it is not necessary as you will be prompted for one if it is not +supplied. + +If you are running the SSH daemon on a non-standard +port, you can specify that port using the normal &URL; syntax as shown +below: +fish://hostname:portnumber. + +Fish should work with any roughly POSIX compatible +&UNIX; based remote computer. It uses the shell commands +cat, chgrp, +chmod, chown, +cp, dd, +env, expr, +grep, ls, +mkdir, mv, +rm, rmdir, +sed, +and wc. Fish starts +/bin/sh as its shell and expects it to be a +Bourne shell (or compatible, like bash). +If the sed and +file commands are available, as well as a +/etc/apache/magic file with &MIME; type +signatures, these will be used to guess &MIME; types. + + +If Perl is available on the remote +machine, it will be used instead. Then only env and +/bin/sh are needed. Using +Perl has the additional benefit of being +faster. + +Fish may even work on &Windows; machines, if tools like +Cygwin are installed. All the above +utilities must be in the system PATH, and the initial +shell must be able to process the command echo +FISH:;/bin/sh correctly. + +
diff --git a/doc/kioslave/floppy.docbook b/doc/kioslave/floppy.docbook new file mode 100644 index 000000000..ff32c217c --- /dev/null +++ b/doc/kioslave/floppy.docbook @@ -0,0 +1,51 @@ +
+Floppy + + +&Alexander.Neundorf; &Alexander.Neundorf.mail; + + + + + +The floppy ioslave gives you easy access to the floppy disk drives +installed on your system. + + + +The drive letter becomes the first subdirectory +in the floppy &URL;. Let's say there is a file logo.png on your floppy +disk in drive A, then the &URL; will be floppy:/a/logo.png + + + +If you want to access drive B, floppy:/b will do it. +floppy:/ is a shortcut for floppy:/a. + + +Note that floppy:/logo.png means you have a disk drive +named logo.png. + + +To use it you need to have the mtools package +installed, and the floppy ioslave supports everything the various mtools +command line utilities support. You don't have to mount your floppy disks, +simply enter floppy:/ in any &kde; 3.x app and you will be able to +read from and write to your floppy drive. + + +It also works with USB sticks, ZIP and JAZ drives. +You can use floppy:/u for the USB stick and floppy:/z for the zip drive, for example. +To make this work, you might need to adjust your /etc/mtools file. See the manpage +for documentation. + + +The ioslave gives read and write access to the floppy drive, but not +simultaneously. While you can read and write to the floppy during the same +session, reading and writing have to happen one after the other, not at the same +time. + +Author: Alexander Neundorf neundorf@kde.org + +
+ diff --git a/doc/kioslave/ftp.docbook b/doc/kioslave/ftp.docbook new file mode 100644 index 000000000..3d4114850 --- /dev/null +++ b/doc/kioslave/ftp.docbook @@ -0,0 +1,43 @@ +
+&FTP; + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + + +&FTP; is the Internet service used to transfer a data file from the disk of +one computer to the disk of another, regardless of the operating system type. + + + Similar to other Internet applications, &FTP; uses the +client-server approach — a user invokes an &FTP; program on the +computer, instructs it to contact a remote computer, and then requests +the transfer of one or more files. The local &FTP; program becomes a +client that uses TCP to contact an &FTP; server +program on the remote computer. Each time the user requests a file +transfer, the client and the server programs cooperate to send a copy +of the data across the Internet. + + &FTP; servers which allow anonymous &FTP; permit +any user, not only users with accounts on the host, to browse the +ftp archives and download files. Some &FTP; servers are +configured to allow users to upload files. + + +&FTP; is commonly used to retrieve information and obtain software stored in +files at &FTP; archive sites throughout the world. + + + + +Source: Paraphrased from +http://tlc.nlm.nih.gov/resources/tutorials/internetdistlrn/ftpdef.htm + + + See the manual: ftp. + +
diff --git a/doc/kioslave/gopher.docbook b/doc/kioslave/gopher.docbook new file mode 100644 index 000000000..29e418faf --- /dev/null +++ b/doc/kioslave/gopher.docbook @@ -0,0 +1,39 @@ +
+gopher + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + + +gopher began as a distributed campus information service +at the University of Minnesota. Gopher allows the user to access information +on Gopher servers running on Internet hosts. + + +Gopher is an Internet information browsing service that uses a menu-driven +interface. Users select information from menus, which may return another +menu or display a text file. An item may reside on a Gopher server you +originally queried, or it may be on another Gopher server (or another host). +Gopher can tunnel from one Gopher to another without the +user knowing that the server and/or host machine have changed. Gopher keeps +the exact location of computers hidden from the user, providing the +illusion of a single, large set of interconnected menus. + + + +Gopher permits the user to record an item's location in a +bookmark thereby allowing users to follow a +bookmark directly to a particular item without +searching the menu system. Gopher menus are not standardized, inasmuch as +each Gopher server is individually determined. + + + +Source: + http://tlc.nlm.nih.gov/resources/tutorials/internetdistlrn/gophrdef.htm + +
diff --git a/doc/kioslave/gzip.docbook b/doc/kioslave/gzip.docbook new file mode 100644 index 000000000..906f0d654 --- /dev/null +++ b/doc/kioslave/gzip.docbook @@ -0,0 +1,30 @@ +
+gzip + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +gzip is a compression program + +The gzip kioslave is not directly usable, and is intended for use +as a filter. For example, the tar kioslave can filter a file through +the gzip kioslave, in order to display the contents of a tar.gz file directly in a &konqueror; +window. + +If you click on a file compressed with a gz extension in &konqueror;, this kioslave is +used to uncompress it and display it as a normal (uncompressed) +file. + +If you are a developer, and would like to use the gzip filter, you +can find documentation on using kioslaves at http://developer.kde.org + + See the manual: gzip. + + +
diff --git a/doc/kioslave/help.docbook b/doc/kioslave/help.docbook new file mode 100644 index 000000000..0b38cb93f --- /dev/null +++ b/doc/kioslave/help.docbook @@ -0,0 +1,17 @@ +
+help + + +&Ferdinand.Gassauer;&Ferdinand.Gassauer.mail; + + + + + +The help system of &kde; + + + See The &khelpcenter;. + + +
diff --git a/doc/kioslave/http.docbook b/doc/kioslave/http.docbook new file mode 100644 index 000000000..0d6a8cef6 --- /dev/null +++ b/doc/kioslave/http.docbook @@ -0,0 +1,25 @@ +
+http + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +http is the +HyperText +Transfer Protocol. + +The http kioslave is used by all &kde; applications to handle +connections to http servers, that is, web servers. The most common +usage is to view web pages in the &konqueror; web browser. + +You can use the http kioslave in &konqueror; by giving it a +URL. +http://www.kde.org. + + See the manual: http. + + +
diff --git a/doc/kioslave/https.docbook b/doc/kioslave/https.docbook new file mode 100644 index 000000000..38772f5dc --- /dev/null +++ b/doc/kioslave/https.docbook @@ -0,0 +1,21 @@ +
+https + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + +HTTPS is +HTTP + encapsulated in an SSL/TLS stream. + + +SSL is the Secure Sockets Layer protocol, a security protocol that provides communications privacy over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. + + +TLS stands for Transport Layer Security + + +
diff --git a/doc/kioslave/imap.docbook b/doc/kioslave/imap.docbook new file mode 100644 index 000000000..e34c1e4e9 --- /dev/null +++ b/doc/kioslave/imap.docbook @@ -0,0 +1,31 @@ +
+imap + + +&Michael.Haeckel; &Michael.Haeckel.mail; + + + +2001-08-07 + + + + +The IMAP4rev1 protocol (Internet Message Access Protocol) allows +access to messages in mail folders on a server. Unlike POP3, which is designed +to download the mails and delete them from the server, the purpose of IMAP is +to store all mails on the server to be able to access these mails from +everywhere. Messages can be stored on the server, retrieved from there or +moved between folders. + +This plugin is currently mainly used by KMail, but you can also use it +in any other KDE application that uses kioslave plugins. + +For example in &konqueror;, simply type +imap://username@your.mail.server/ to get your IMAP +folders listed. You can then deal with the folders and mails like with folders +and files on a local file system. +IMAP URLs are defined in RFC 2192. + + +
diff --git a/doc/kioslave/imaps.docbook b/doc/kioslave/imaps.docbook new file mode 100644 index 000000000..d5f8e7b6f --- /dev/null +++ b/doc/kioslave/imaps.docbook @@ -0,0 +1,17 @@ +
+imaps + + +&Michael.Haeckel; &Michael.Haeckel.mail; + + + +2001-08-07 + + + + +IMAPS is the IMAP protocol +encrypted via SSL. + +
diff --git a/doc/kioslave/index.docbook b/doc/kioslave/index.docbook new file mode 100644 index 000000000..6f70d6e23 --- /dev/null +++ b/doc/kioslave/index.docbook @@ -0,0 +1,93 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +KDEPrint"> +FerdinandGassauer'> +f.gassauer@aon.at'> + + +]> + + +IO-Slaves +&kio-bzip; +&kio-bzip2; +&kio-cgi; +&kio-data; +&kio-file; +&kio-finger; +&kio-fish; +&kio-floppy; +&kio-ftp; +&kio-gopher; +&kio-gzip; +&kio-help; +&kio-http; +&kio-https; +&kio-imap; +&kio-imaps; +&kio-info; +&kio-lan; +&kio-ldap; +&kio-mailto; +&kio-mac; +&kio-man; +&kio-mrml; +&kio-news; +&kio-nfs; +&kio-nntp; +&kio-pop3; +&kio-pop3s; +&kio-print; +&kio-rlan; +&kio-rlogin; +&kio-sftp; +&kio-smb; +&kio-smtp; +&kio-tar; +&kio-telnet; +&kio-thumbnail; +&kio-webdav; +&kio-webdavs; + + + diff --git a/doc/kioslave/info.docbook b/doc/kioslave/info.docbook new file mode 100644 index 000000000..1ea645c33 --- /dev/null +++ b/doc/kioslave/info.docbook @@ -0,0 +1,36 @@ +
+Info + + +&Lauri.Watts; &Lauri.Watts.mail; + + Nicolas + Goutte + goutte@kde.org + + + + + +Info is a type of documentation. The documents are in a file +format called texinfo, and can be read on the command line with the +info program. + +The Info ioslave allows you to read the info pages installed on +your system, from within &konqueror;. You can use it very easily: + +info:gcc + +This would show you the top level node of the Info documentation +for the &gcc; compiler. + +Info is a &GNU; replacement for +man, but is not widely used outside of +&GNU; software. + +You can quite easily browse the info documentation you have +installed from within the &khelpcenter; application, or you can use the +info ioslave directly from within both &konqueror; and the +mini-cli. + +
diff --git a/doc/kioslave/lan.docbook b/doc/kioslave/lan.docbook new file mode 100644 index 000000000..c494b5767 --- /dev/null +++ b/doc/kioslave/lan.docbook @@ -0,0 +1,23 @@ +
+lan + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + + +This protocol is intended to provide a kind of network +neighborhood but only relying on the TCP/IP protocol stack and with +the ability to use other protocols than just SMB. + +The lan kioslave can use &FTP;, &HTTP;, SMB, +NFS, and FISH + +It must first be configured in &kcontrol;, +NetworkLAN-Browsing + and for more information see the +Lan Browsing manual. + +
diff --git a/doc/kioslave/ldap.docbook b/doc/kioslave/ldap.docbook new file mode 100644 index 000000000..ff23339c3 --- /dev/null +++ b/doc/kioslave/ldap.docbook @@ -0,0 +1,23 @@ +
+ldap + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +ldap is the lightweight directory access +protocol. It provides access to an X.500 directory, or to a stand-alone +LDAP server. + +You can use the ldap kioslave as follows: + +ldap://host:port/ou=People,o=where,c=de??sub +for a subtree-query + +or +ldap://host:port/cn=MM,ou=People,o=where,c=de??base +for a complete branch. + +
diff --git a/doc/kioslave/mac.docbook b/doc/kioslave/mac.docbook new file mode 100644 index 000000000..a1398c39a --- /dev/null +++ b/doc/kioslave/mac.docbook @@ -0,0 +1,53 @@ +
+mac + + +JohnathanRiddelljr@jriddell.org + + + + + +The mac ioslave lets you read an HFS+ partition from &konqueror; +or any other &kde; file dialog. It uses hfsplus +tools, so you will need these installed for it to work. + +Enter mac:/ into &konqueror; and you +should see the contents of your &MacOS; partition. If you have not +used kio-mac before, you will probably get an error message saying you +have not specified the right partition. Enter something like +mac:/ to specify +the partition (if you don't know which partition &MacOS; is on, you +can probably guess by changing hda2 to hda3 and so on or use the print +command from mac-fdisk). This partition will be +used the next time, so you do not have to specify it each time. + +Hfsplus tools let you see the file and copy +data from the HFS+ partition, but not to copy data to it or change the +filenames. + +HFS+ actually keeps two files for every one you see (called +forks), a resource fork and a data fork. The default copy mode when +you are copying files across to your native drive is raw data, which +means it only copies the data fork. Text files are copied in text mode +(same as raw format but changes the line endings to be &UNIX; friendly +and gets rid of some extra characters - strongly advised for text +files), unless you specify otherwise. You can also copy the files +across in Mac Binary II format or specify text or raw format with +another query: +mac:/ or +mac:/. See the +hpcopy man page for more. + +Note that you need permissions to read your HFS+ partition. How +you get this depends on your distribution. + +For some reason some folders in &MacOS; end in a funny tall +f character. This seems to confuse hfstools. + +
+ diff --git a/doc/kioslave/mailto.docbook b/doc/kioslave/mailto.docbook new file mode 100644 index 000000000..3603aea8d --- /dev/null +++ b/doc/kioslave/mailto.docbook @@ -0,0 +1,17 @@ +
+mailto + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + +The mailto kioslave is used when you click on a mailto link in an +HTML page. &konqueror; will open the preferred mail +client you have configured, with a composer window. Any information +supplied in the URL will be filled in for you. + + +See the manual: mailto. + +
diff --git a/doc/kioslave/man.docbook b/doc/kioslave/man.docbook new file mode 100644 index 000000000..6d2d00c15 --- /dev/null +++ b/doc/kioslave/man.docbook @@ -0,0 +1,86 @@ +
+Man + + +&Lauri.Watts; &Lauri.Watts.mail; + + Nicolas + Goutte + goutte@kde.org + + + + + + +Using the man ioslave you are able to read the man pages installed +on your system. It is easy to use: + + + + +man: + +See the sections of the manual, click to find the rest. + + + + +man:fopen + +See the man page of fopen. + + + + +man:fopen(3) + +See the man page of fopen in section 3. + + + + +man:(3) + +See the index of section 3. + + + + +man:intro(3) + +See the introduction of section 3. + + + + + +If there are more than one man page of the name that you +have entered, you will get a list where you can choose the man page +that you want to see. + + +There is also a shortcut: #fopen, +which has the same effect as above. + + + +If you do not find all your man pages, adjust the configuration file +/etc/manpath.config +(or a file of a similar name depending on your distribution) +or adjust the environment variables +MANPATH and MANSECT. + + + +As with any other &kde; ioslave, it is possible to enter a &URL;, like +man:socket in any +&kde; application. Try it in &kwrite; and you will see the man page in +&HTML; format. + + + +Contact mailing list: kde-devel@kde.org + + +
diff --git a/doc/kioslave/mrml.docbook b/doc/kioslave/mrml.docbook new file mode 100644 index 000000000..32af0922c --- /dev/null +++ b/doc/kioslave/mrml.docbook @@ -0,0 +1,26 @@ +
+mrml + + +&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; + + + + +2003-01-08 + + + + +MRML stands for Multimedia Retrieval Markup Language. MRML is an XML-based +protocol to provide standardized access to Multimedia retrieval software. +See http://www.mrml.net for more information. + + +kio_mrml is used for the Image Finding feature in &kde; + +⪚ type mrml:/ or mrml:/some.other.server in &konqueror; to start searching for +images. + + +
diff --git a/doc/kioslave/news.docbook b/doc/kioslave/news.docbook new file mode 100644 index 000000000..c56e3a8e0 --- /dev/null +++ b/doc/kioslave/news.docbook @@ -0,0 +1,20 @@ +
+news + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + + +The news kioslave is used when you click on a news link on a web +page. It will open &knode;, and if the group referred to in the news +link is available from your server, it will subscribe you to the group, in +the first available account you have configured in &knode; + +You can unsubscribe from within &knode; if you decide you don't +want to read the group, by right clicking and +selecting Unsubscribe from Group. + +
diff --git a/doc/kioslave/nfs.docbook b/doc/kioslave/nfs.docbook new file mode 100644 index 000000000..bbe9bb625 --- /dev/null +++ b/doc/kioslave/nfs.docbook @@ -0,0 +1,39 @@ +
+nfs + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + +Sun's NFS protocol provides transparent remote access to +shared file systems across networks. The NFS protocol is +designed to be machine, operating system, network architecture, and +transport protocol independent. This independence is achieved through the +use of Remote Procedure Call (RPC) primitives built on +top of an eXternal Data Representation (XDR). + + + +The supporting MOUNT protocol performs the operating system-specific +functions that allow clients to attach remote folder trees to a point +within the local file system. The mount process also allows the server to +grant remote access privileges to a restricted set of clients via export +control. + + +The Lock Manager provides support for file locking when used in the +NFS environment. The Network Lock Manager +(NLM) protocol isolates the inherently stateful aspects +of file locking into a separate protocol. + + +Source: + +http://www.networksorcery.com/enp/protocol/nfs.htm + + + See the manual: nfs. + +
diff --git a/doc/kioslave/nntp.docbook b/doc/kioslave/nntp.docbook new file mode 100644 index 000000000..8020b8903 --- /dev/null +++ b/doc/kioslave/nntp.docbook @@ -0,0 +1,41 @@ +
+nntp + + +&Lauri.Watts; &Lauri.Watts.mail; + + + +The nntp kioslave accesses NNTP servers +directly. + +This kioslave can not be used with servers that do not implement +the GROUP command, including some versions of the +popular INN news server which is often used +by ISPs. It does work with +leafnode, which many people use to keep an +offline cache of news articles on their own hard drive or within their +LAN. + +You can use the nntp kioslave by typing +nntp://yourserver/groupname into the &konqueror; +URL bar. + +If you enter a group name, as above, and the group is available, +you will see the messages stored for that group as icons in +&konqueror;. + +Clicking on a message will display it as plain text, including all +headers. This could be useful for debugging a news client to news +server connection, for example, to ensure that your new +leafnode server is working correctly. + +If you don't enter a group name, and only the server name, you +will see a list of available groups. + +Please be aware that this could take an enormous amount of time, and +will cause a lot of network traffic. Some commercial usenet servers +have 60,000 or more groups available, and doing such a thing may +cause your desktop to freeze. + +
diff --git a/doc/kioslave/pop3.docbook b/doc/kioslave/pop3.docbook new file mode 100644 index 000000000..1c956a1cd --- /dev/null +++ b/doc/kioslave/pop3.docbook @@ -0,0 +1,13 @@ +
+pop3 + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + +The Post Office Protocol (POP3) allows a user's workstation to access mail from a mailbox server. + + +
diff --git a/doc/kioslave/pop3s.docbook b/doc/kioslave/pop3s.docbook new file mode 100644 index 000000000..856709e80 --- /dev/null +++ b/doc/kioslave/pop3s.docbook @@ -0,0 +1,14 @@ +
+pop3s + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + +POP3S is the POP3 protocol encrypted via SSL. + + + +
diff --git a/doc/kioslave/print.docbook b/doc/kioslave/print.docbook new file mode 100644 index 000000000..034eddab1 --- /dev/null +++ b/doc/kioslave/print.docbook @@ -0,0 +1,170 @@ +
+print + + +&Kurt.Pfeifle; &Kurt.Pfeifle.mail; + + + + +2002-06-23 +1.00.00 + + + +The print KIOSlave gives quick access to browse +different &kdeprint; sections via virtual folders. +These folders provide some information about and quick access to your print +subsystem. + +print:/ represents one more of those useful +KIOSlaves implemented by &kde;. To access it, just type print:/ + into the address field of &konqueror;. print:/ + doesn't purely provide read-only access to + your print subsystem, but it also allows you to change settings + of your printers, of your print system and lets you create new printers + and classes. + +You are asked for the Administrator or root password, if you are +not allowed a view or an operation as a normal user. + +You can bookmark frequently used shortcuts like + print:/manager + +Valid syntax is either +print:/[path-to-virtual-folder] or +print:[path-to-virtual-folder] + +Note, that some of the views and actions offered do heavily + depend on the print subsystem that is installed on your box and presently +activated for &kde;. Pages showing printer information display only +those parts that are valid for the &kde; selected print subsystem. +(So if you normally run CUPS, but switched temporarily to + + + Generic UNIX LPD Printing, which is possible, you will see +less printer info, because LPD is not capable of using the same amount of +print settings as are possible in CUPS). + +Valid syntax to access different virtual folders +and a short explanation of what they represent: + + +Some examples + + +print:/ (&ie; the root of +print-kioslave) + + virtual root for browsing your print subsystem. + It displays subfolders Classes, + Jobs, + Manager, Printers, + and Specials + + + + +print:/classes or +print:classes + + view your printer classes + (supported by and useful for CUPS only) + + + + + + +print:/classes/class_name or + print:classes/class_name +view all members of the named + printer class (supported by and useful only + for CUPS) + + + + + +print:/jobs +or print:jobs + + lists the current and pending jobs. + + + + +print:/printers +or print:printers + + lists all your printers. Clicking + on a printer name shows more info about that printer. + + + + + +print:/printers/printer_name +or print:printers/printer_name + +displays useful info about the named + printer + + + + +print:/manager or +print:manager + +opens a page very similar to the &kdeprint; + Manager module inside the &kde; Control Center. + Switch to a different printing system here or do every + other administrative task. +This is the most important of access points to your printing + system. + + + + +print:/specials or +print:specials + +lists all presently available special printers: + Likely you'll see: + + + The two that let you save a printfile to disk, in + &PostScript; or PDF format. + + + One that sends it as a PDF attachment via +&kmail;. + + + And last, send it via fax, if you have one of the + supported fax backends active, +Hylafax or +efax. + + + + + + + +You can also put print:/manager + or similar as the command in + the Quick Command utility (started via +&Alt;F2) + +You can learn more about printing and &kdeprint;'s powerful abilities +by reading the &kdeprint; Handbook +locally or at the &kdeprint; +Website where there are documents online (HTML and +PDF),containing +Tutorials, + as well as FAQs and + Tips and Tricks related to printing in general. + +
diff --git a/doc/kioslave/rlan.docbook b/doc/kioslave/rlan.docbook new file mode 100644 index 000000000..98c962444 --- /dev/null +++ b/doc/kioslave/rlan.docbook @@ -0,0 +1,11 @@ +
+rlan + + +The &kde; team + + + +Not yet documented + +
diff --git a/doc/kioslave/rlogin.docbook b/doc/kioslave/rlogin.docbook new file mode 100644 index 000000000..a24b20f85 --- /dev/null +++ b/doc/kioslave/rlogin.docbook @@ -0,0 +1,31 @@ +
+rlogin + + +ChristianBunting + + + +Using &konqueror; you can start up an rlogin +session with a server hosting the rlogin service. + +To use this kioslave feature, in the &konqueror; +URL bar, type +rlogin:/host_to_connect_to + +This will initialize &konsole; with an rlogin +session, prompting you for your password. + +The rlogin kioslave uses the username of the +account you are currently using in &kde;. + +After you have successfully entered your password, you can begin +your remote session. + + See the manual: rlogin. + + + + + +
diff --git a/doc/kioslave/sftp.docbook b/doc/kioslave/sftp.docbook new file mode 100644 index 000000000..ff2770a47 --- /dev/null +++ b/doc/kioslave/sftp.docbook @@ -0,0 +1,19 @@ +
+sftp + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + +SFTP is a Secure file transfer protocol. +sftp is an interactive file transfer program, +similar to ftp, but it performs all operations over an encrypted +ssh transport. It may use many of the features of +ssh, including public key authentication and +compression. + + See the manual: sftp. + + +
diff --git a/doc/kioslave/smb.docbook b/doc/kioslave/smb.docbook new file mode 100644 index 000000000..716db415f --- /dev/null +++ b/doc/kioslave/smb.docbook @@ -0,0 +1,56 @@ +
+SMB + + +&Alexander.Neundorf; &Alexander.Neundorf.mail; + + + + +The smb ioslave enables you to browse the shares of a &Windows; (or Samba) +network. + + + +To see the workgroups, enter +smb:/. + + +smb://a_workgroup +will list the hosts in this workgroup. + + +To see the shares of a host, enter +smb://the_host +or +smb:/a_workgroup/the_host. + + +To access a share directly enter +smb://the_host/the_share +or +smb:/a_workgroup/the_host/the_share + + + +The smb ioslave requires that you have libsmbclient to use this ioslave. + + + +You can set your default user name and password in the &kcontrol; in +NetworkWindows +Shares. This is especially useful if you are a +member of a &Windows; NT domain. There you can also set your +workgroup name, but in most cases this is not required. The kioslave will ask for your username and password if a default is not set. + + + +This ioslave is tested and developed using mainly Samba 2.0.7, but other +versions of Samba should work too. + + + +Author: Alexander Neundorf neundorf@kde.org + +
+ diff --git a/doc/kioslave/smtp.docbook b/doc/kioslave/smtp.docbook new file mode 100644 index 000000000..2aa2c7dbf --- /dev/null +++ b/doc/kioslave/smtp.docbook @@ -0,0 +1,16 @@ +
+smtp + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + +A protocol to send mail from the client workstation to the mail server. + + + See : Simple Mail Transfer Protocol . + + +
diff --git a/doc/kioslave/tar.docbook b/doc/kioslave/tar.docbook new file mode 100644 index 000000000..8a5405198 --- /dev/null +++ b/doc/kioslave/tar.docbook @@ -0,0 +1,18 @@ +
+tar + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + +An archiving program designed to store and extract files from an archive +file known as a tarfile. A tarfile may be made on a tape drive, however, it +is also common to write a tarfile to a normal file. + + + See the manual: tar. + + +
diff --git a/doc/kioslave/telnet.docbook b/doc/kioslave/telnet.docbook new file mode 100644 index 000000000..9d2131e84 --- /dev/null +++ b/doc/kioslave/telnet.docbook @@ -0,0 +1,17 @@ +
+telnet + + +&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail; + + + + +The network terminal protocol (TELNET) allows a user to log in on any other computer on the network supporting TELNET. + + + + See the manual: telnet. + + +
diff --git a/doc/kioslave/thumbnail.docbook b/doc/kioslave/thumbnail.docbook new file mode 100644 index 000000000..7b2e0752f --- /dev/null +++ b/doc/kioslave/thumbnail.docbook @@ -0,0 +1,28 @@ +
+thumbnail + + +&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; + + + +The thumbnail kioslave is used by &kde; for network transparent +and persistent generation of thumbnails. + +The thumbnail kioslave uses plugins to generate the actual +thumbnails. You can enable viewing of these thumbnails from the +View +Preview submenu, available in +&konqueror; in file manager mode. + +The thumbnail kioslave is not directly useful to a user, but if +you are a developer, you can use it within your own applications to +create file previews. + +See the documentation in the sources for more information. You +will find these at +$KDEDIR/include/kio/thumbcreator.h or +in the source folder kdebase/kioslave/thumbnail + +
diff --git a/doc/kioslave/webdav.docbook b/doc/kioslave/webdav.docbook new file mode 100644 index 000000000..d549384f2 --- /dev/null +++ b/doc/kioslave/webdav.docbook @@ -0,0 +1,65 @@ +
+webdav + + +&Hamish.Rodda; &Hamish.Rodda.mail; + + + +2002-01-21 + + +WebDAV is a Distributed +Authoring and Versioning +protocol for the World Wide Web. It allows for easy management of +documents and scripts on a http server, and has +additional features designed to simplify version management amongst +multiple authors. + +Usage of this protocol is simple. Type the location you want to +view, similar to a http URL except for the +webdav:// protocol name at the start. An example is +webdav://www.hostname.com/path/. +If you specify a folder name, a list of files and folders will be +displayed, and you can manipulate these folders and files just as you +would with any other filesystem. + + +WebDAV Features + +Locking + +File locking allows users to lock a file, informing others that they +are +currently working on this file. This way, editing can be done without fear +that +the changes may be overwritten by another person who is also editing the +same +document. + + + +Source file access + +WebDAV allows access to the script which is called +to +produce a specific page, so changes can be made to the script itself. + + + +Per-document property support + +Arbitrary properties may be set to assist identification of a +document, +such as the author. + + + + +To take advantage of these additional capabilities, you will need an +application which supports them. No application currently supports them +through +this kioslave. + +
diff --git a/doc/kioslave/webdavs.docbook b/doc/kioslave/webdavs.docbook new file mode 100644 index 000000000..edbd635e6 --- /dev/null +++ b/doc/kioslave/webdavs.docbook @@ -0,0 +1,17 @@ +
+webdavs + + +&Hamish.Rodda; &Hamish.Rodda.mail; + + + +2002-01-21 + + + + +WebDAVS is the WebDAV protocol +encrypted via SSL. + +
diff --git a/doc/klipper/Makefile.am b/doc/klipper/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/klipper/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/klipper/index.docbook b/doc/klipper/index.docbook new file mode 100644 index 000000000..71327f14c --- /dev/null +++ b/doc/klipper/index.docbook @@ -0,0 +1,511 @@ + + + + + +]> + + + +The &klipper; Handbook + + +&Philip.Rodrigues; &Philip.Rodrigues.mail; + + +&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; + + + + + + + + +2000-2003 +&Philip.Rodrigues; + + +&FDLNotice; + +2005-01-31 +2.92.00 + + +&klipper; is the &kde; clipboard cut & paste utility. + + + +KDE +Klipper +kdebase +clipboard + + + + +Introduction +&klipper; is the &kde; clipboard utility. It stores clipboard +history, and allows you to link clipboard contents to application +actions. Please report any problems or feature requests to Esben Mose +Hansen (see http://mosehansen.dk/about +for contact details). + + + + +Using &klipper; + + +Basic Usage + +The &klipper; icon. + + + + + +The &klipper; icon + + + + +To display the clipboard history, click on the &klipper; icon in + the &kde; panel, or press &Ctrl;&Alt;V . Previous + clipboard entries are shown at the top of the pop-up menu which + appears. Selecting one of these copies it to the clipboard, from + where it can be pasted into any &kde; or X application as + usual. + +You can search through the clipboard history by opening it +(click on &klipper;) and typing your query. The results are updated as +you type. In case you're wondering how to use the accelerator keys in +the &klipper; menu, just press &Alt; and the accelerator you want. For +example, to clear the clipboard history when the &klipper; menu is +open, press &Alt;L +. + +To remove &klipper;, click on its icon in the System Tray, and from the +menu that appears, select Quit. + + + + +Actions + +&klipper; can perform actions on the contents of the clipboard, +based on whether they match a particular regular expression. For +example, any clipboard contents starting with http:// can +be passed to &Netscape; or &konqueror; as &URL;s to open. + +To use this feature, just copy a &URL; or filename to the +clipboard. If there is a matching regular expression in &klipper;'s +list, a menu will appear showing you the options you have (⪚ Open +&URL; in &konqueror;, open &URL; in &Netscape;). Use the mouse or +keyboard to select the option you want, and &klipper; will run the +program you have selected, opening the address pointed to by the +clipboard contents. + +If you do not want to perform any actions on the clipboard +contents, select Do Nothing on the pop-up menu +to return to what you were doing before. If you leave the menu, it will +disappear, leaving you to continue your work. You can change the time +that the menu remains for in the Configure Klipper... +dialog, with the option Timeout for action pop-ups +under the General tab. + +Actions can be disabled completely by clicking on &klipper; and +selecting Actions Enabled, or by pressing +&Ctrl;&Alt;X. + +Clipboard contents which match a regular expression can also be +edited before performing an action on them. Select Edit contents... on the &klipper; pop-up menu, and you can +change the clipboard contents in the dialog which appears, before +clicking the OK button to run the appropriate +action. + +Pressing &Ctrl;&Alt;R shows the pop-up +menu to repeat the last action which &klipper; performed. + + + + +Clipboard/Selection Behavior + + +General + +&klipper; can be used to set the behavior of the clipboard and selection in +&kde;. + + +The &X-Window; uses two separate clipboard buffers: the +selection and the clipboard. Text is +placed in the selection buffer by simply selecting it, and can be +pasted with the middle mouse button. To place text in +the clipboard buffer, select it and press +&Ctrl;X or +&Ctrl;C . Text from the +clipboard buffer is pasted using &Ctrl;V + or by selecting +EditPaste +. + + + + + + +Changing Clipboard/Selection Behavior + +In order to change clipboard/selection behavior, select +Configure Klipper... from the &klipper; pop-up menu, +and in the dialog box that appears, select the +General tab. Selecting Separate clipboard and +selection makes the clipboard and selection function as completely +separate buffers as described above. With this option set, the option +Ignore selection will prevent &klipper; from +including the contents of the selection in its clipboard history and from +performing actions on the contents of the selection. Selecting +Synchronize contents of the clipboard and the selection +causes the clipboard and selection buffers to always be the same, meaning that +text in the selection can be pasted with either the +middle mouse button or the key combination &Ctrl;V +, and similarly for text in the clipboard buffer. + + + + + + + + + + + + +Configuring Klipper + + + +Viewing the Configuration Dialog + +To view or change &klipper;'s settings, open the &klipper; +pop-up menu, and select Configure Klipper.... The &klipper; +configuration dialog will appear. Its contents are described +below. + + + + +General Options + + + + +Popup menu at mouse-cursor position +Make the &klipper; pop-up menus appear at the position of +the mouse cursor, instead of their default position (in the &kde; Panel). +Useful if you use the mouse more than the keyboard. + + + + +Save clipboard contents on +exit If this option is on, the clipboard +history will be saved when &klipper; exits, allowing you to use it next time +&klipper; starts. + + + + +Remove whitespace when executing actions +If selected, any whitespace (spaces, tabs, &etc;) at the +beginning and end of the clipboard contents will be removed before passing the +clipboard contents to an application. This is useful, for example, if the +clipboard contains a &URL; with spaces which, if opened by a web browser, would +cause an error. + + + + +Replay actions on an item selected from +history +If this is switched on, selecting an item from the history +causes &klipper; to display the actions pop-up on that item, if +appropriate. + + + + +Prevent empty clipboard +If selected, the clipboard will never be empty: &klipper; will +insert the most recent item from the clipboard history into the clipboard +instead of allowing it to be empty. + + + +Ignore selection +Sets the clipboard mode. See . + + + + + + +Synchronize contents of the clipboard and the +selection +Sets the clipboard mode. See . + + + + + +Separate clipboard and selection +Sets the clipboard mode. See . + + + + + + +Timeout for Action pop-ups +Set the time that a pop-up menu will remain for if you do +nothing with it. + + +Clipboard history +size +Sets the number of items that are stored +in the clipboard history. + + + + + + + +Actions Options + + + +Editing Expressions/Actions +On the Actions tab, double-click +the regular expression or action that you want to edit. An in-place text editing +box will appear in which the text can be edited as you wish. Make sure you +press Enter when you are done. + + + +Adding Expressions/Actions +Click the Add Action button +to add a regular expression for &klipper; to match. &klipper; uses +&Qt;'s QRegExp, which understands most regular +expressions as you would use in grep or +egrep for instance. +You can add a description of the regular expression type (⪚ +HTTP URL) by left clicking in the +Description column. + +You can find detailed information about the use of +QRegExp regular expressions at http://doc.trolltech.com/qregexp.html#details. +Note that &klipper; does not support the wildcard mode mentioned on this +page. + +Edit the regular expression as described above. To add a command +to execute, right click, select +Add Command and edit the command which +appears in the tree under the regular expression. + +Note that %s in the command line is replaced with +the clipboard contents, ⪚ if your command definition is +kedit %s and +your clipboard contents are /home/phil/textfile, +the command kedit +/home/phil/textfile will be run. To +include %s in the command line, escape it with a +backslash, as so: \%s. + + +Advanced... +Brings up the Disable Actions for windows of type +WM_CLASS dialog. +Some programs, such as &konqueror;, +use the clipboard internally. If you get unwanted &klipper; pop-ups all the time +when using a certain application, do the following: + + +Open the application. +From a terminal, run xprop +| grep WM_CLASS +and then click on the window of the application you are +running. +The first string after the equals sign is the one to +enter. + + +Once the WM_CLASS is added, no more actions will be generated for +windows of that application. + + + + + + + +Shortcuts Options + +The shortcuts tab allows you to change the keyboard shortcuts +which are used to access &klipper; functions. You can change the +shortcut to one of three things: + + + +None +The selected action cannot be accessed directly from the +keyboard + + +Default +The selected action uses &klipper;'s default key. These are the +shortcuts referred to in this manual. + + +Custom +The selected action is assigned to the keys you choose. +To choose a custom key for the action you have selected, click on the +representation of a key in the lower right of the screen to activate it, and +type the desired key combination on your keyboard, as in any &kde; application. + + + + + + + + +Credits and License + + +&klipper; + + +Program copyright 1998 Andrew Stanley-Jones asj@cban.com + + +Program copyright 1998-2000 &Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; + +Currently maintained by Esben Mose Hansen. See http://mosehansen.dk/about +for contact details. + + + +Documentation copyright 2000-2003, 2005 &Philip.Rodrigues; +&Philip.Rodrigues.mail; + +&underFDL; +&underGPL; + + + + +Installation + + +How to obtain &klipper; + +&install.intro.documentation; + + + + +Compilation and Installation +&klipper; should compile and install along with the kdebase +package, and appear on your &kde; panel (&kicker;) when you run &kde; +3. If it does not appear, you can start it by selecting +Panel +MenuAddAppletKlipper + +in any context menu in &kicker;, the &kde; Panel. + + +&klipper; icon + + + + + + Screenshot + + + + + + + + + +&documentation.index; + + + + + + + + + + + + + diff --git a/doc/klipper/screenshot.png b/doc/klipper/screenshot.png new file mode 100644 index 000000000..2b1fbbafe Binary files /dev/null and b/doc/klipper/screenshot.png differ diff --git a/doc/kmenuedit/Makefile.am b/doc/kmenuedit/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kmenuedit/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kmenuedit/done.png b/doc/kmenuedit/done.png new file mode 100644 index 000000000..c614475a7 Binary files /dev/null and b/doc/kmenuedit/done.png differ diff --git a/doc/kmenuedit/index.docbook b/doc/kmenuedit/index.docbook new file mode 100644 index 000000000..73cb76ced --- /dev/null +++ b/doc/kmenuedit/index.docbook @@ -0,0 +1,521 @@ + + + Firefox"> + + +]> + + + + + +The &kmenuedit; Handbook + + +&Milos.Prudek; &Milos.Prudek.mail; + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + + + +2000 +&Milos.Prudek; + + +&FDLNotice; + +2006-11-23 +0.7 (&kde; 3.5.5) + +&kmenuedit; allows editing of the &kde; &kmenu;. + + + +KDE +KDE Menu Editor +kmenuedit +application +program +menu +kicker + + + + + + +Introduction + +&kmenuedit; allows editing of &kde; &kmenu;. + +&kmenuedit; can be started either by &RMB; clicking the +&kmenu; button on the panel and choosing +Menu Editor, or by choosing +Menu Editor from the +Settings submenu of the &kmenu;. + +&kmenuedit; allows you to: + + +View and edit the current &kmenu; +Cut, Copy +and Paste menu items +Create and delete submenus + + + + + + + +&Virgil.J.Nisly; &Virgil.J.Nisly.mail; + + +A Quick Start Guide to Adding an Entry to the &kmenu; + + In this example, we will add &firefox; to the Internet submenu. Most applications can be added with &kappfinder;, &firefox; can usually be added that way, but was used for lack of a better example. + To start off, we need to open &kmenuedit;, so &RMB; on the &kmenu;, click Menu Editor to start &kmenuedit;. After &kmenuedit; has started, select Internet as shown in picture below. + +Select Internet + + + + + +Select Internet + + + + + Once you have selected Internet, click on FileNew Item..., opening the New Item dialog, as shown below. Type the name of the program you want to add, in this case, type firefox. + +New Item dialog + + + + + +The New Item dialog. + + + + + +Press return, and you should see something like the picture below in the main window. + +New Item + + + + + +The new item created. + + + + + + Now lets fill in the Description:, in this case type Web Browser. The description and name will be displayed on the &kmenu; as Web Browser (Firefox). We will need to fill in the executable name in the Command: field, in this instance we will type firefox. +Following the command, you can have several place holders which will be replaced with actual values when the program is run: + +%f - a single file name +%F - a list of files; use for applications that can open several local files at once +%u - a single &URL; +%U - a list of &URL;s +%d - the folder of a file to open +%D - a list of folders +%i - the icon +%m - the mini icon +%c - the caption + +For example: if you want to firefox to start your web browsing at www.kde.org - instead of firefox you would type firefox %u www.kde.org. +We would like to have a more creative icon, so we will click the generic icon sitting beside Name:. It will bring the Select Icon dialog which will let us choose the new icon, as shown below. + +Select Icon dialog + + + + + +The Select Icon dialog. + + + + + We choose the firefox icon from the list, and press return. Your finished screen should probably look something like the screenshot below. + +Done screenshot + + + + + +This is what the completed menu item should looks like. + + + + +Click FileSave, wait for the Updating System Configuration dialog to get finished, you should find &firefox; in the &kmenu; Internet submenu! + + + + + + +Using &kmenuedit; + +The left application panel shows the &kmenu; structure. When +you browse items in the left panel, the right panel shows detailed +information for the highlighted menu item. + + +General program information + + + +Name: +This is the name of your program as it appears in the +&kmenu; menu. It can be different from the real executable +name. For instance the name of mc executable is +"Midnight Commander". + + +Description: +The description will be displayed together with the name in the &kmenu;. This is +entirely optional. + + +Comment: +Describe the program in greater detail in this field. This is +entirely optional. + + +Command: +This is the name of the executable program. Make sure that you +have permission to run the program. + + +Enable launch feedback +If this box is checked, this will display feedback when an application is started + + + +Place in system tray +When checked, the application's icon will show up in the panel system tray. +You will then be able to hide or show the application by clicking on the system +tray icon. Clicking on it using the &RMB; will allow also you to undock, or quit the +application. + + + +Icon List +Click +this icon to display a choice of icons. Choose an icon for your +program. + + +Work path: +Specify the work path of the program. This will be the current +path when the program launches. It does not need to be the same as the +executable location. + + +Run in terminal +You must check this if your program requires terminal emulator +in order to run. This mainly applies to console +applications. + + +Terminal options: +Put all terminal options in this field. + + +Run as a different user +If you want to run this program as a different user (not you), +check this checkbox, and provide the username in the +Username: field. + + + +You can assign a special keyboard shortcut to launch your program. + +Click the None button to the right of the Current +shortcut key: checkbox. + +A dialog box will pop up, allowing you to assign a Primary shortcut: +by pressing the key combination on your keyboard that you want to be assigned to your program. +It might be useful to assign a second +keybinding to the same item by checking the +Alternate shortcut: button, for +example, if you often switch keyboard maps, and some shortcuts are not +as convenient to type at all times. + +Click the x to clear the shortcut, if you +made a mistake. Check the Multi-key mode box if you +want to assign a shortcut that uses more than one key. + +The dialog will close when you have selected a keybinding. + + + + + + + +Menu Reference + + + + +&Ctrl;N +File New Item... + Adds new menu +item. + + + + +File +New Submenu... + +Adds new submenu. + + + +FileNew +Separator + +Adds a new separator to the menu. + + + + + +&Ctrl;S +FileSave + + +Saves the menu + + + + + + +&Ctrl;Q + +File +Quit + +Quits &kmenuedit;. + + + + + +&Ctrl;X + + +Edit Cut + +Cuts the current menu item to the clipboard. If +you want to move menu item, you should first cut it to the clipboard, move to +the destination place using the left panel, and use the +Paste function to paste the menu item from the +clipboard. + + + + + +&Ctrl;C + + +Edit Copy + +Copies the current menu item to the +clipboard. You can later use the Paste +function to paste the copied menu itemfrom the clipboard to its destination. You +can paste the same item many times. + + + + + +&Ctrl;V + +Edit +Paste +Paste menu item from the clipboard to currently +selected place in the Main menu. You must first use +Cut or Copy before you can +Paste. + + + + +Delete +Edit Delete + +Deletes currently selected menu +item. + + + + +Settings +Show/Hide Toolbar + +Show or hide the toolbar + + + + +SettingsConfigure +Shortcuts... + +Customize the keyboard shortcuts + + + + + +SettingsConfigure +Toolbars... + +Customize the toolbar icons. + + + + + +&help.menu.documentation; + + + + + +Credits and License + + +&kmenuedit; + +Program copyright © 2002, &Raffaele.Sandrini; + +Contributors: + +&Matthias.Elter; &Matthias.Elter.mail; - Original +Author + +&Matthias.Ettrich; &Matthias.Ettrich.mail; + +&Daniel.M.Duley; &Daniel.M.Duley.mail; + +&Preston.Brown; &Preston.Brown.mail; + + + +Documentation copyright © 2000 &Milos.Prudek; + +Updated for &kde; 3.0 by &Lauri.Watts; &Lauri.Watts.mail; +2002 + + + +&underFDL; +&underGPL; + + + + +Glossary + + +Terminal emulator + +Terminal emulator is simply a windowed shell; this is known as +command line window in some other environments. If you +want to use the shell, you should know at least a few of the +system-level commands for your operating system. + + + + +Applet +A small application that occupies very little memory +and screen space, and at the same time gives you some useful +information or provides a control shortcut. For instance the +Clock applet shows current time and date +(and even a month diary if you click it), and System +Monitor applet shows how busy your machine currently is +in real-time. + + + +Legacy Application + + +An X-window application which was not written with &kde; in +mind. Such applications run fine in &kde;. However, they are not +warned automatically when you shut down your &kde; session. You +therefore must not forget to save documents open in these applications +before you log out from &kde;. Additionally, many of +these applications do not support copying and pasting from +&kde; compliant applications. &Netscape; 4.x browser is a prominent +example of such application Some GNOME applications may provide +limited interoperability with the &kde;.. + + + + +Console Application + + +Application originally written for non-graphic, text oriented +environment. Such applications run fine in &kde;. They must run within +console emulator, like &konsole;. They are not warned automatically +when you shut down your &kde; session. You therefore must not forget +to save documents open in these applications before you log out from +the &kde;. + +Console applications support copying and pasting from +&kde;-compliant applications.Simply mark the text in the console +application with your mouse, switch to the &kde;-compliant application +and press &Ctrl; +V to paste the text. If you want to copy +from &kde; application to a console application, first mark the text +with your mouse, press &Ctrl; +C, switch to the console application and +press the middle button on your mouseIf your mouse +does not have a middle button, you must press +left and right +button at the same time. This is called middle button +emulation and it must be supported by your operating system to +work.. + + + + + + +&documentation.index; + + + + diff --git a/doc/kmenuedit/itemname.png b/doc/kmenuedit/itemname.png new file mode 100644 index 000000000..fb3d8a286 Binary files /dev/null and b/doc/kmenuedit/itemname.png differ diff --git a/doc/kmenuedit/kmenueditmain.png b/doc/kmenuedit/kmenueditmain.png new file mode 100644 index 000000000..46509372f Binary files /dev/null and b/doc/kmenuedit/kmenueditmain.png differ diff --git a/doc/kmenuedit/new.png b/doc/kmenuedit/new.png new file mode 100644 index 000000000..a26a1dd41 Binary files /dev/null and b/doc/kmenuedit/new.png differ diff --git a/doc/kmenuedit/selecticon.png b/doc/kmenuedit/selecticon.png new file mode 100644 index 000000000..c60363f37 Binary files /dev/null and b/doc/kmenuedit/selecticon.png differ diff --git a/doc/kmenuedit/selectinternet.png b/doc/kmenuedit/selectinternet.png new file mode 100644 index 000000000..92d63b092 Binary files /dev/null and b/doc/kmenuedit/selectinternet.png differ diff --git a/doc/knetattach/Makefile.am b/doc/knetattach/Makefile.am new file mode 100644 index 000000000..171f575ce --- /dev/null +++ b/doc/knetattach/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/knetattach/index.docbook b/doc/knetattach/index.docbook new file mode 100644 index 000000000..c5e7a4db0 --- /dev/null +++ b/doc/knetattach/index.docbook @@ -0,0 +1,349 @@ + + + + + + + + +]> + + + + + + +The &knetattach; Handbook + + + +&Orville.Bennett; &Orville.Bennett.mail; + + + + + + +2005 +&Orville.Bennett; + +&FDLNotice; + +2005-02-09 +1.01.00 + + + +&knetattach; is an application which makes it easier to integrate your +network resources with your &kde; Desktop. + + + + + + +KDE +kdebase +knetattach +Network Folders +Network Folder Wizard +KDE Network Folder Wizard + + + + + +Introduction + + +The &knetattach; program, affectionately and hereafter known as the +Network Folder Wizard, allows easy addition and integration of various +network folders with your &kde; desktop. Please report any problems or +feature requests for it to the &kde; bugs website. + + + + +Using &knetattach; + + +As you will see in the screenshot below, the Network Folder Wizard currently allows +you to add four types of network folders: WebDav, FTP, +Microsoft +Windows (Samba) network drives and SSH. + + +Here's a screenshot of &knetattach; + + + + + +Screenshot + + +Network Folder Wizard main window + + + + + + + +Adding network folders + + +Network folders show up in a special location of &konqueror; called a +virtual folder. +This virtual folder is accessed by typing remote:/ in +&konqueror; Location bar. You will then be able to see +any folders which have been previously added and you also will be able to use +the wizard to add new ones. + +Here's a screenshot of &knetattach; + + + + + +Screenshot + + +The virtual folder with the Network Folder wizard + + + + + + +Speaking of wizards, the Network Folder Wizard aims at being very easy to use. +After opening the wizard you must choose the type of network folder you would +like to access. When you move on to the next screen you will just need to +fill in the requested information. The final step is entering your username and +login password for the network share you've chosen to access. + + +Below is a list of the information needed by the wizard to create the network folders. If an option is not +available for a particular folder it does not have to be entered. e.g. The Samba +folders do not require a Port entry. + + + + + +Name: + + +This is where you give a name to the network connection. It is limited only by +your imagination (or alphabet). + + + + +Server: + + +This is the address of the server you are attempting to add. It can be an +IP address or domain name. + + + + +Port: + + +Here you enter the port number you wish to connect to. The defaults are usually +sufficient. + + +Not available for Microsoft +Windows (Samba) folders. + + + + + + +Folder: + + +The path to the folder you wish to connect to should go here. + + + + +Create an icon for this remote folder + + +If this box is checked an icon will be created allowing access through the +remote:/ virtual folder. If it is not checked, a connection will be possible +but it will not be accessible from remote:/. + + +The Recent connection: option allows you to re-connect to the +last network mount point you connected to using the wizard whether an icon is created or not. + + + + + + +Use encryption + + +If checked the ability to make a secure connection will be enabled. + +Available only for WebDav folders. + + + + + + + + + + + +&knetattach; Walkthrough + + + +This will be a quick walkthrough of the Network Folder Wizard. Don't +blink or you might miss it. + + + +Below you see the main window of the Network Folder Wizard. It is here +that we choose what type of folder we want to add or connect to. For +the purposes of this walkthrough we will be using FTP. It contains most +of the options you will encounter while using the wizard. + + + + +Here's a screenshot of the &knetattach; main window + + + + + +Screenshot + + + + + + +OK, so we (as in me) have chosen to add an FTP folder. Below you see +an example of the type of information you will need to add for your particular +FTP server. After filling it in we press Save & +Connect +and wait for the magic. Oh yes, if your server requires validation of some kind +you will be prompted at this point before being allowed to connect. + + + + +Screenshot showing addition of FTP Folder +using &knetattach; + + + + + +Screenshot + + + + + + +So now we are all connected now and able to navigate our newly added share. Joy! + + + + +Screenshot of the connected FTP folder + + + + + +Screenshot + + + + + + +To get back to our network folders all that is necessary is typing remote:/ +in the Location: bar of &konqueror;. + + + + +Screenshot of the remote:/ virtual folder with the +added connection + + + + + +Screenshot + + + + + + +You can even add new folders from the same location by using the +Add a Network Folder link. Well that brings us to +the end of our walkthrough (told you it would be quick). I wish you the +best of luck in your own network folder adventures ;-) + + + + + +Credits and License + + +&knetattach; + + +Program copyright 2004 &George.Staikos; &George.Staikos.mail; + + + +Documentation Copyright © 2005 &Orville.Bennett; &Orville.Bennett.mail; + + + + +&underFDL; +&underGPL; + + + +&documentation.index; + + + diff --git a/doc/knetattach/screenshot.png b/doc/knetattach/screenshot.png new file mode 100644 index 000000000..a22996512 Binary files /dev/null and b/doc/knetattach/screenshot.png differ diff --git a/doc/knetattach/screenshot1.png b/doc/knetattach/screenshot1.png new file mode 100644 index 000000000..1a9ef1001 Binary files /dev/null and b/doc/knetattach/screenshot1.png differ diff --git a/doc/knetattach/screenshot2.png b/doc/knetattach/screenshot2.png new file mode 100644 index 000000000..581fa167c Binary files /dev/null and b/doc/knetattach/screenshot2.png differ diff --git a/doc/knetattach/screenshot3.png b/doc/knetattach/screenshot3.png new file mode 100644 index 000000000..668d093e0 Binary files /dev/null and b/doc/knetattach/screenshot3.png differ diff --git a/doc/knetattach/screenshot4.png b/doc/knetattach/screenshot4.png new file mode 100644 index 000000000..13e375a05 Binary files /dev/null and b/doc/knetattach/screenshot4.png differ diff --git a/doc/kompmgr/Makefile.am b/doc/kompmgr/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kompmgr/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kompmgr/index.docbook b/doc/kompmgr/index.docbook new file mode 100644 index 000000000..2d70bc9d6 --- /dev/null +++ b/doc/kompmgr/index.docbook @@ -0,0 +1,433 @@ + + + + + +]> + + + +&kappname; Information + + + +ThomasLuebking +thomas.luebking@web.de + + + + + + +2005 +Thomas Luebking + + +&FDLNotice; + +2005-01-15 +2.0.1 + + +&kappname; is a composite rendering engine to be used by &kwin;. +This document is rather a general explanation of what it does, +how it works and what the restrictions are than a documentation how to use +it (as it works in the background automatically). + + + +KDE +kwin +render engine + + + + +Introduction + +&kappname; is based upon xcompmgr, Keith +Packards reference composing implementation for the use of the new X +features. + +A composite manager catches the output of the X windows and renders +them into a single picture that will be displayed on the screen. The advantage +of doing so is that you can do basically anything with the windows contents, +including blending them together (translucency) or attaching shadows. You +could also tint them, add a nasty advertise on any window, squeeze them, +fract them, add scanlines, or anything else you can imagine, limited by +your hardware. + + + + +Xorg + +You necessarily need X.org 6.8 or later to have +&kappname; work. X.org 6.7 or older or XFree86 won't work. + + +Setup +You need to explicitly enable the Composite extension. Add a +new Section to your X.org configuration file: + + +Section "Extensions" + Option "Composite" "Enable" +EndSection + + +If supported by your GPU (the complex chip that +powers a modern graphics card), activate the Render acceleration. This is +best supported by NVIDIA, and less completely by ATI +cards. + + +Section "Device" +.... +.... + Option "RenderAccel" "true" +.... +.... +EndSection + +&kappname; should be available now. For more information, please see +the FAQ. + + + + + + +Settings + +This chapter describes which parameters you can tweak, how they will +result visually and their performance impact. + + +Translucency + +A translucent object is one that allows light to pass through it. In +terms of windows on your desktop, that means that the contents of windows +can be seen through the one on the top. + +Translucency allows you to emphasize special windows, have a 3 +dimensional view on your desktop, keep track of covered windows, and just +looks cute. The price is, that blending things together costs some system +capacity. + +You can independently configure translucency for the following +items: + + + +Active windows +It is suggested you deactivate translucency for the active +window. The main reason is for perfomance, and secondly because to scan the +content of a translucent window means your brain has to strip the irritating +throughshining information, which is tiring. + + + +Inactive windows +If you set inactive windows translucent, active windows will +appear emphasized and are easier to focus. However, if you choose a lower +value, you may have trouble to find an inactive window. If you choose very +low values (< 20%) you may not be able to distinguish +windows in their stack order - so you may accidently click the +OK button of a dialog when you just wanted to +activate a window. Optimal values are between 60% and +80%. + + + +Moving windows +Though it's a nice effect to have heavily translucent +(opacity < 20%) moving windows, there is a heavy price to pay in +performance, especially if you do not deactivate shadows (see below). Just +try out and if you feel your system is too slow, keep moving windows +opaque. This value also applies to windows in resize state. + + + +Dock windows +As docks like kicker are seldom if ever moved and usually of +limited size, this is purely visual and won't detrimentally affect your +system's performance. + + + +Treat "keep above" windows as active ones +If you set a window to keep above others, you usually want +to keep focus on it, so it can make sense to give it the same +emphasis. + + + +Disable ARGB windows +XRender supports windows with an alpha mask, &ie; +translucent sections. Currently there are no or only very few applications +that would make use of this feature, as it doesn't make any sense without +using a composite manager. This may change in the future. +On the other side, most gtk 1.x applications (⪚ +xmms) set such an alpha mask, resulting in +almost unusable windows (as long as the sublying windows are not black), so +you can disable the support for ARGB windows here to make use of gtk +applications. There will hopefully be a patch for gtk in the near future to +fix this. + + + + + + +Shadows +Why should anyone want his windows to throw shadows? Well, maybe just +because it looks cute, or because it allows a better window separation, +or... because it looks cute! + + +Use shadows +As shadows cost some additional cpu/gpu power, they can be +deactivated, while keeping a general alpha channel capability. + + + +Active window size +Inactive window size +Dock window size +You may select different shadow sizes for different window +states/types. The values are not absolute, but will apply to your screen +resolution. +In principle, you can set every value you want (if you edit the config +file with a text editor, far beyond the offered 32), but +bigger shadows cost more cpu/gpu power. + + + +Vertical offset +Horizontal offset +By default, the window would throw a all around +equal shadow, implying a frontal light source. Users familiar with +&MacOS; may like a vertical offset, &Windows; users may prefer a +slighter offset to the southeast. Experiment with the values until you are +happy. + + + +Shadow color +Usually shadows as the absence of light appear in shades of +grey (so the maximum shadow color is black, or no light at all). But hey, +this is a virtual world, and if you'd like to have even pink shadows, why +not? + + + +Remove shadows on move +Check this if you need more performance (especially when +using translucent moving windows). + + + +Remove shadows on resize +It's a good idea to check this item whether using +translucent resizing (moving) windows, or not. The windows shadow pixmap has +to be permanently recreated on resizes what has a deep impact on the system +performance. + + + + + + +Effects + + +Fade-in windows +Fade between opacity changes +Instead of just popping up a new window, you might want to +slowly fade it in. While this looks impressive, there is an equally +impressive price to pay in performance speed, and it is difficult to interact +meaningfully with windows that are in the process of fading. + + + + + +Fade-in speed +Fade-out speed +For the usability reasons mentioned under Fade-in +windows, it is most practical to use a fast fade in speed and +(for more eye candy) a slow fade out speed. This will provide you nice +effects and a smooth feeling system as well as low latency before +information appears. + + + + + + + + +Problems + +The whole Composite extension is quite new. It may cause several +problems and even crash X, so it is strongly suggested to not even +enable the Composite extension in Xorg.conf on mission critical production +systems. If you however can risk a slightly more unstable system, +it's certainly nice to have some eye candy around. + + +In this case you may notice some glitches. +Here are some common problems - and workarounds: + + + + + +I have X.org 6.8.x, but &kappname; fails to start + + +You need to explicitly enable the Composite extension, add a new Section to /etc/X11/XorgConfig: +Section "Extensions" + Option "Composite" "Enable" +EndSection + + + + + +Ok, &kappname; works, but it's horribly slow + + +If supported by your GPU (mainly +NVIDIA, and somewhat by ATI cards), first make sure +you activated the Render acceleration + +Section "Device" +.... +.... +Option "RenderAccel" "true" +.... +.... +EndSection + + +If it's still slow, you can try to adjust your memory usage. Either +decrease you screen depth (⪚ from 24 to 16) or lower your resolution +(⪚ from 1280x1024 to 1024x768). + +Please notice that the currently limiting factor for the Composite +extension seems to be the CPU cache size. + + + + + + +After enabling the Composite extension, I cannot run any +GLX applications anymore. I've got an +NVIDIA card. + + +To prevent some problems, NVIDIA deactivated the +GLX support when Coposite is active. Reactivating is possible, but may cause +problems on some kernel/driver/GPU combinations. + +Section "Device" +.... +.... +Option "AllowGLXWithComposite" "true" +.... +.... +EndSection + + + + + + +I wanted to play a game using SDL (but not +GL), say scummvm, but when the +compmgr is active, all I can see is a shadow! + + +This is a problem with the PictType reported by SDL. + +Workaround: + +Instead of calling scummvm directly, call +SDL_VIDEO_X11_VISUALID=0x24 scummvm This will tell SDL to +use a supported format and you can play as ever. + + + + + + Application XXX refuses to start after enabling the Composite +extension. +Application YYY breaks X after enabling the Composite +extension. +Application ZZZ looks weird after activating the composite +manager. + + +The Composite extension is still experimental. +Workaround: +Instead of calling appName directly, call XLIB_SKIP_ARGB_VISUALS=1 appName +Applications that are known to cause problems: + +All gtk1 applications (⪚ gmplayer, +xmms, gaim) - failing +startup or look unusable weird or crash X +&kuickshow; - displays only a black frame +&Qt; Designer - crashes +X +&kopete; - crashes X +&kolf; - crashes X + + + + + + +I try to watch a video, but only see artefacts in the Video +Window. + + +You're using xv as video backend. This is the overlay +mode, where the video content is written directly into the video card +memory, bypassing X. Therefore the window seems to be static (colored +background) and is not updated by the damage extension. + There will hopefully be a fix for this in the future. Currently I had +the best results using Xine but displaying +translucent videos isn't fast anyway. + + + + + + + +Credits and Licenses + + +Authors +Thomas Luebking baghira-style@gmx.net - Editor + +&underFDL; +&underGPL; + + + + + + + + diff --git a/doc/konqueror/Makefile.am b/doc/konqueror/Makefile.am new file mode 100644 index 000000000..da8216ae4 --- /dev/null +++ b/doc/konqueror/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/konqueror/basics.docbook b/doc/konqueror/basics.docbook new file mode 100644 index 000000000..8940df621 --- /dev/null +++ b/doc/konqueror/basics.docbook @@ -0,0 +1,386 @@ + + + + +&Pamela.Roberts; + + + +2003-10-20 +3.2 + + +&konqueror; Basics + +Like all &kde; applications, &konqueror; is highly + configurable. This document describes how &konqueror; behaves with the normal, + default settings. + A three button mouse can be useful when you are running +&konqueror; or any other &kde; application. If your mouse only has two buttons +then you should be able to set your system up so that you can simulate a &MMB; +by pressing both buttons at the same time. +You can read more about mouse usage in +If you are used to having to double-click to perform an action, +then take care, because in common with the rest of &kde;, &konqueror; defaults +to single-clicking. + + +Starting &konqueror; + +Being a combined File Manager and Browser, +&konqueror; will automatically +switch between the two modes as needed when it is running, but it is convenient +to be able to choose which mode is to be used when you start it up. + + +If you have a house shaped icon on the panel +or desktop, then left click on it to open +&konqueror; as a file manager. + +Or left click on world + shaped icon on the panel or desktop to open &konqueror; in browser +mode. + +From the K menu, select +InternetKonqueror Web +Browser to start it as a browser, or +Home to launch &konqueror; in file manager mode. + + +&Alt;F2 +will open a Run Command dialog box, type +konqueror (lower case) and press +Enter or the Run button to start in +file +manager mode, or just enter a &URL; such as + http://www.konqueror.org to start &konqueror; as a +browser. + + + +&konqueror; is also started automatically when you +left click on a desktop icon that represents a +folder, such as a hard disk drive or the Trash icon. + + + + + + +The Parts of &konqueror; + +A brief look at the main parts of &konqueror;'s window: + + + + +Here's a screenshot of &konqueror; + + + +The Titlebar is the strip across the top of +&konqueror;'s window, and operates in the same way as for other &kde; +applications. Right click on the central portion to +bring up the neat Titlebar menu. + +The Menubar is the strip containing the names of +the drop-down menus. Left click on a name to +alternately show and hide that menu, or use &Alt;the underlined +letter in the name as a hot key, for example &Alt;E to show the +Edit menu. The various menus are described in the Menubar section of this document. + +The Toolbar contains icons for commonly used +operations. Left clicking on an icon will activate +it. If you have enabled tooltips in the Control Center +Appearance & +ThemesStyle +dialog a brief description of what that icon does will appear when you hover +the pointer over it. + +Some icons, for example the Up and Back icons in the previous screenshot, +have a small black triangle at their bottom right corner. If you hold the &LMB; +pressed while the cursor is over this type of icon a small dropdown menu will +appear. Right clicking on the +Toolbar will bring up the Toolbar Menu which you can use +to change the Toolbar's appearance and position. + +The Location Toolbar shows the path to the +directory, &URL; or file being viewed. You can type a path or &URL; here and +press &Enter; or left click on the +Go icon at the right hand end of the Location +Toolbar to go to it. The black icon at the left hand end of the +Location Toolbar clears the text entry box. + +The Bookmark Toolbar is the area under the +Location Toolbar in the previous screenshot. You can add +frequently used bookmarks here; see the Organizing +Your +Bookmarks section of this document. + +The Window is the main area of &konqueror; and +can show you the contents of a directory, web page, document or image. Using +the Window menu you can +split &konqueror;'s main window into one or more separate views, useful for +drag and drop operations, or set it to contain two or more tabbed views. + + +The Status Bar runs across the bottom of the +&konqueror;'s window +and often shows general information about whatever the mouse pointer is +hovering +over. If you have split the main window into a number of views you will get an +Status Bar for each view, and it will include a small green light at the left +hand end to show which is the active +view. Right clicking on the Status Bar brings up the +Status Bar Right Mouse +Button Menu. + +Don't worry if your &konqueror; doesn't look exactly like this +screenshot; it is highly configurable. In particular: + + +You can use the Settings menu to choose +whether to show or hide the Menubar, Main Toolbar, Location Toolbar and +Bookmark Toolbar, or even to add an Extra Toolbar. +You can also flatten the toolbars by +left clicking on the vertical lines at the left hand end +of the bars, or move them around by holding the &LMB; down while you +drag these bars around. +This screenshot does not show the optional +Navigation Panel. + + +For more details of how to change &konqueror;'s appearance, see the Configuring &konqueror; section + + + + +Tooltips and What's This? + +You can find out a lot about how &konqueror; works without needing to +read +this entire document if you take advantage of Tooltips and + the +What's This? feature. + +If Tooltips have been enabled in &kde; (K menu + Control CenterAppearance & + ThemesStyle, + Style dialog) then when you hover the mouse pointer + over a Toolbar or Navigation Panel +button it should bring up a terse description of what that button does. + +What's This? is invoked by the Menubar +HelpWhat's This? item, by +&Shift;F1, or by +just &LMB; clicking on the question mark near the top right hand corner of +&konqueror;'s window. It changes the cursor to show a question mark alongside +the arrow. + +When this question mark is visible, a &LMB; click won't actually do +anything until you have clicked on a control (or the text alongside it) that +supports What's This?, in which case it will +display +a reasonably comprehensive description of what the control is supposed to do. +Most of the dialog boxes that &konqueror; brings up support the +What's This? feature. + + + + +<mousebutton>Left</mousebutton> and <mousebutton>Middle</mousebutton> +Mouse Button Actions + +If you click the &LMB; on an item in &konqueror;'s window, it will + be +activated. Thus + + + +Left click on an icon in the Toolbar +to do whatever that icon is supposed to do. +Left click on an item in the Menubar +to make that menu drop down. +Left click on a menu item to do that +thing. +Left click on an icon in the +Bookmark + Toolbar +to open that &URL;. +Left click on a link in a web page +to make &konqueror; follow that link. +Left click on a folder icon or +name and &konqueror; will descend into (show the contents of) that folder. + +Left click on a file name or icon +and &konqueror; will do whatever it thinks appropriate, based on the file type. +In general this means opening HTML pages, or previewing +text, image or +KOffice files, showing them within &konqueror;'s +window (Preview means that you can see the file but not change +it). + +&konqueror; decides what the file type is by matching the filename +extension against a list of known types. If that fails it tries to guess +the type from the file contents. You can change the list of known file types +and associated actions with the File Associations page of +the SettingsConfigure Konqueror... + dialog. + + + +Clicking the &MMB; on a file or folder name or icon does essentially the +same as left clicking except that it usually does it +in a new &konqueror; window, unless the Open links in new tab instead +of in new window box has been checked in the +Behavior page of the +SettingsConfigure + +Konqueror... dialog. &konqueror; can open +links on pages and Bookmarks, +as well as the +Home, Up, +Back and Forward +entries in a new tab or window. + +Holding the &Shift; key down while pressing the &MMB; will open the link +in the background. +If you click the &MMB; when the mouse cursor is over a blank +part of the main view (not over a link or file name or icon) &konqueror; will +copy the contents of the clipboard into the Location Toolbar and try to use +that as a &URL;. + + + +<mousebutton>Right</mousebutton> Mouse Button Menus + +Clicking the &RMB; on almost any part of &konqueror;'s window +will bring up an appropriate context menu. + +If you have enabled the Right click goes back in +history option in &konqueror;'s +configuration settings a +simple right click is equivalent to clicking on the +Back button. In this case you can access the context +menu by moving the mouse with the right button held +down. + + + + +On the Titlebar +Right clicking on any free area of +the Titlebar brings up the Titlebar Menu, allowing you to control the position +of &konqueror;'s window as well as the decoration applied to all &kde; program +windows. + + + +On the Main Toolbar +Right click on any free area of the +Toolbar to bring up the Toolbar Menu. You can use it to control whether the +Toolbar is at the top, bottom, left or right of &konqueror;'s window. +You can also use the Toolbar Menu to set the size of the buttons on the +Toolbar, +and whether they are shown as icons, text or both. + + + +On the Location Toolbar +Right click in the + &URL; +entry box area to perform Cut, Copy, Paste or Clear operations in this area, or +to change the automatic Text Completion +features. + + + +On the Bookmark Toolbar + If you have the Bookmark Toolbar showing, then +right click on any free part of it to bring up the +Bookmark Toolbar Menu which lets you change its position and whether items are +shown as text, icons, or both. + + + +Within a View +If you right click on any free area +of a view then you will get a menu that contains, among other options, the + Up, +Back, Forward and +Reload navigation commands. + + + + +On a File or Folder +This is a most useful feature. Right +clicking on the name or icon of any file or folder not only +selects that item but also brings up a menu allowing you to +Cut, Move, Copy or Remove the item in +various +ways, add it to your Bookmarks, open it with the program of +your choice or preview it, rename it, or edit the file type or +properties. + + +On the Status Bar +Right click on the Status Bar at the +bottom of a window or view to add or remove a view within &konqueror;'s +window. + + + + + + +Viewing Help, Man and Info Pages + +You can view &kde; Help and &UNIX; Man and Info pages directly in +&konqueror;, without having to start up KHelpCenter. + + +To view a &kde; Help page, enter +help:/application name (for +example help:/kmail to view the &kmail; documentation.) +into &konqueror;'s Location Toolbar window. + + + +If you want to read &UNIX; Man pages &konqueror; makes it easy. For +example type man:/touch or +#touch into the Location Toolbar to see the page for +the touch command. + +To browse through &UNIX; Info pages, entering +info:/dir takes you to Info's top level directory, then +it's just a matter of clicking on the right links to find the page you +want. Alternatively, use info:/command +name to go straight to the Info page you want. + +Unfortunately, &kde; Help pages are stored in such a way that they +cannot be viewed in other browsers. If you really need to do this your only +recourse is to go online and visit +http://docs.kde.org. + + + + + diff --git a/doc/konqueror/bookmarks.docbook b/doc/konqueror/bookmarks.docbook new file mode 100644 index 000000000..99eac7ab7 --- /dev/null +++ b/doc/konqueror/bookmarks.docbook @@ -0,0 +1,129 @@ + + + +&Pamela.Roberts; + + + +2003-11-05 +3.2 + + +Using Bookmarks + +Although you can use &konqueror;'s bookmarks to record the locations of +your own files and folders, they are most useful when you are surfing the +Web, letting you build up a list of useful sites. + +To open the Bookmarks menu you may either +left click on the +Bookmarks menu or use the &Alt;B shortcut. Once +the list is visible, you can navigate through it with the arrow keys or with +your mouse, then press &Enter; or +left click to visit the selected location. + +To add a new item to the list use Bookmarks +Add Bookmark or +&Ctrl;B or +right click on a clear space in the web page or +folder view and select Bookmark this Location from +the pop up menu. + +The Bookmarks list can contain subfolders containing +other bookmarks, you can create these with Bookmarks +New Bookmark Folder... . +To add a bookmark into a subfolder rather than into the main Bookmark list, +select the folder from within the Bookmarks list and use +the Add Bookmark item in that folder. + +You can also access your bookmarks from the +Navigation Panel. + + +The Bookmark Editor + +The BookmarksEdit +Bookmarks option opens the Bookmark +Editor. +This shows a tree view of your bookmarks and bookmark subfolders. +As is usual for tree views in &kde;, subfolders are shown with a small square +at the left of the folder name; if the square contains a + +sign left clicking on it will expand the view to +show the contents of that subfolder and the + sign will +change to -, left clicking on the +- sign will collapse the subfolder view. + +To select an item in the list you can left +click on it, or you can navigate through the list by using the +Up arrow and Down arrow keys to move around, +Right arrow to expand a subfolder and +Left arrow to collapse it. + +You can move an item to a different place in the list by using the +normal Drag and Drop or Cut and +Paste methods. The order in which the items appear in +the Bookmark Editor is the order they will appear in the +Bookmarks drop down list. The Insert +Insert Separator option can +be used to insert separating lines into the list wherever you wish. + +A new subfolder can be created at the selected point in the list by +using the Create New Folder... option in the +Insert menu or from the drop down menu you get when you +right click on an item in the main part of the +window, or with &Ctrl;N + + +To change the name of a bookmark or folder select it then press +F2 or choose the Rename item from +the Edit menu or the pop up menu that appears when you +right click on the item. Similarly, you can edit +the &URL; by pressing F3 or choosing the +Change URL menu item. + +The Bookmark Editor lets you import bookmarks from +a range of other browsers into &konqueror;'s bookmark list, putting them into + a new folder or replacing all current bookmarks. To do this select +Import from the File menu. The +FileExport + option can be used to export &konqueror;'s bookmarks to a +&Netscape; or Mozilla browser. + +If you often use the &Netscape; browser as well as &konqueror;, then +rather than importing your &Netscape; bookmarks into &konqueror; it is +better to select the Show Netscape Bookmarks in Konqueror +Windows item in the Settings menu. If you +do this any updates to &Netscape;'s bookmarks are automatically seen by +&konqueror;. + +To select which bookmark subfolder is used to hold the Bookmark +Toolbar items select the subfolder then choose Set as Toolbar +Folder from the Edit menu. + +If you are tidying up your bookmarks and have forgotten what a +particular web page is, you can easily open it from within the +Bookmark Editor by right clicking +on the item and selecting Open in Konqueror from +the pop up menu. If you just want to check that the &URL; is still valid +select Check Status instead. + +Don't forget to save your changes with +FileSave or +&Ctrl;S before you leave +the Bookmark Editor. + + + + + + diff --git a/doc/konqueror/browser.docbook b/doc/konqueror/browser.docbook new file mode 100644 index 000000000..9707e29ad --- /dev/null +++ b/doc/konqueror/browser.docbook @@ -0,0 +1,482 @@ + + + + +&Pamela.Roberts; + + + +2003-11-05 +3.2 + + + +&konqueror; the Web Browser + + + + +Browsing www.konqueror.org + + + + +Connecting to the Internet + +Once you are connected to the Internet you can use &konqueror; to browse +the Web just as easily as you can use it to handle your local files. Just type +a &URL; into the Location Toolbar window, press +&Enter;, and you are away! + + +If you use a dial-up modem connection, then you will be using +&kppp; or a similar dialer program to make the connection. + +If your machine is connected to a local area network +(LAN) that gives you a proxy connection to the Internet +then you will have to set &konqueror; up for the proxy connection. This can be +done with the Proxy page of the +SettingsConfigure Konqueror... + dialog. + +If you are lucky enough to have a high speed cable connection, +then the service provider will probably give you an external cable modem which +needs an ethernet connection to your machine. Unfortunately the details of how +to establish the connection depend on the service provider and to some extent +on which Linux/&UNIX; distribution you are using. Some ISPs +connect their customers to the Internet through a proxy server, in which case +you will have to set up &konqueror; to use it. You may find it useful to +search the archives of your distribution's user group mailing list for +help. + + + +An error message such as Unknown Host +usually means that &konqueror; cannot find a connection to the Internet or that +you have entered an incorrect &URL;. + + + + +Surfing and Searching + +Once you have a connection to the Internet, you can surf with +&konqueror; just as you can with any other browser. + +Type a &URL; into the Location Toolbar window, press +&Enter; or left click on the +Go button at the right hand end of the Location +Toolbar, and &konqueror; will download and display that page. +If you have visited the page before, &konqueror;'s +Automatic Text Completion feature can help +you type the &URL; a second time, or you could look through the +History page in the +Navigation Panel. If you want to use one of +the web's search engines, &konqueror;'s +Web Shortcuts feature can make this easier. + +Left click on a link in the page to + go there. + +To open a link in a new instance of &konqueror;, leaving the +old page still visible, &MMB; click on the link or right + click on it and select the +Open in New Window option. Alternatively, you might want to Open in New Tab. Tabbed Browsing will let +you hold a number of pages in one &konqueror; window and quickly switch +between them with a single mouse click. + +You could also select the multiple view mode with &Ctrl;&Shift;L + +or the Menubar Window Split View +Left/Right option which will let you see different +pages at the same time. This can be useful if you are looking through a +complicated set of HTML pages, but make sure the little link +box at the bottom right hand corner is empty when you are doing +this. +To go back to the previous page use the &Alt;Left Arrow +shortcut, the Back button on the Toolbar, or the Menubar +Go Back +option. +Similarly, once you have gone back you can go forward by using +&Alt;Right +Arrow, the Forward button, or the +Menubar +Go +Forward option. + +If you want to stop the download for any reason then use the +Esc key, the Toolbar Stop button or the +Menubar View +Stop item. + +When you are viewing a web page you should see two new icons in the +Toolbar, looking like magnifying glasses with small + and +- symbols. Use these to adjust the size of the text in the +page if you find it difficult to read. How well this works will +depend on how the web page has been constructed. + + + +Tabbed Browsing +By using this feature you can make &konqueror; load multiple web pages in +the same window, and switch between them using tabbed pages. This way, you can +preload a page in the background while you carry on reading another. + +To use tabbed browsing, right click on a +link and choose Open in New Tab from the drop down +menu. The page will be downloaded and displayed as normal, but with tabs +across the top of the view, one tab for each page. Left + click on a tab to view that page, or you can use the shortcuts +&Ctrl;[ and +&Ctrl;] to cycle through +the tab pages. Alternatively, you can scroll through the tabs using +the mouse wheel while the mouse pointer is +over the tab bar (presuming that your mouse has one). Also, +double-clicking over the empty tab bar space will open a new +tab. + +The Open in Background Tab option in the +&RMB; menu also downloads the page and shows a new tab for it, but the new +page will not be displayed until you left click +on the tab. + +If you check the Open links in new tab instead of in new window + box in the Web Behavior page of the +SettingsConfigure Konqueror... + dialog, &MMB; clicking on a link will open it +in a new tab page and if you hold the &Shift; key down while clicking the +&MMB; the link will be opened in a background tab page. + +Right clicking on a tab will bring up a +menu with the following options: + + + +New Tab +This opens a new, blank, tabbed page view. +You can then download a web page into it by typing the &URL; into the +Location Bar or by making a selection from the Bookmark Toolbar or the +Navigation Panel history page. + + + +Duplicate Tab +To create a duplicate tabbed page. + + + +Detach Tab +This option removes the selected tabbed +page from the current &konqueror; window and opens it in a new instance of +&konqueror;. + + + +Close Tab +To close the selected tab page. + + + +Reload +Reloads the content of the current tab. + + + +Reload all Tabs +Reloads the content of every tab. + + + +Switch to Tab +Displays a submenu showing all other tabs. Choosing a tab from +this list makes it the active tab. + + + +Close Other Tabs +To close all but the selected tab page. + + + + + + +Web Shortcuts + +If enabled, &konqueror;'s Web Shortcuts +feature lets you submit a query directly to a search engine or similar web site +without having to visit the site first. For example, entering +gg:konqueror into the Location Bar and pressing &Enter; +will ask Google to search for items related to +&konqueror;. To see what Web Shortcuts are available, and perhaps +add your own, use SettingsConfigure +Konqueror... to open the Settings + dialog box and click on the Web Shortcuts +icon. + +Once there, to make a new Web Shortcut select +New... and you will now have a new dialog +requesting the options and specifications of your new Web +Shortcut. The first field is for the human readable name of the search +provider; that is, simply the name of the Search provider. For +example, Google. + +In the next field you should enter the &URI; that is used to do a +search on the search engine. The whole text to be searched for can be +specified as \{@} or +\{0}. The recommended version is +\{@} since it removes all query variables +(name=value) +from the resulting string whereas \{0} will be +substituted with the unmodified query string. + +You can use \{1} +... \{n} to specify certain words from the +query and +\{name} +to specify a value given by +name=value +in the user query. In addition it is possible to specify multiple +references (names, numbers and strings) at once, like +(\{name1,name2,...,"string"}). The first +matching value (from the left) will be used as substitution value for +the resulting &URI;. A quoted string can be used as the default value if +nothing matches from the left of the reference list. + +To make a basic Web Shortcut here however, all that is required +is the &URI; that is used to do a search on the search +engine. Following our previous example with +Google, we would enter +http://www.google.com/search?q=\{@}&ie=UTF-8&oe=UTF-8. You +can often easily find where to place the \{@} +by doing a search on the search engine in question, and then analysing +the &URL; address. For example, doing a Google +search for &konqueror; produces the &URL;: http://www.google.com/search?q=konqueror&ie=UTF-8&oe=UTF-8. Now +you need to merely replace &konqueror; with +\{@} in this example to find the appropriate +&URI; to be entered. + +In the third field you need to enter the &URI; shortcut. For +example, the gg in +gg:konqueror. In the next option — the +drop-down menu — you have the option to select the character set that +will be used to encode the search query. Once you have entered all the +options correctly to your satisfaction, press &Enter; and your new Web +Shortcut should now be available in &konqueror;. + + + + + +Access Keys + +&konqueror; has full support for the +accesskey &HTML; attribute in +forms and links. Access keys allow you to use +the keyboard keys for functions which would perhaps normally be done +with the mouse, such as following links. The benefit of this is, quite +simply, that users can interact with a page with devices other than a +pointing device. + +To activate the access keys in &konqueror;, press and release +&Ctrl;. Once this is pressed, if a particular link on the website has +the accesskey attribute in the given link, then the +character(s) should appear over the link, identifying what needs to be +pressed. Then, you can enter the character(s) associated with the link +as an alternative to following the link with the mouse. To disable the +access keys once activated you can press &Ctrl; again. + +The proper use of this feature requires that the web +designer of the page has specifically assigned, using the +accesskey attribute, an access key for the +link. Many web designers might not include the +accesskey in their links and forms, and +consequently this feature will be unusable on the given +webpage. + + + + +Browser Identification +When &konqueror; connects to a web site it sends some brief browser +identification information, known as the User Agent string. +Many web sites use this information to customize the pages that they send +back, based on the strengths and weaknesses of different browsers. +Unfortunately, some badly designed sites refuse to work properly +unless you are using a browser that the site recognizes as a +valid one, even though if given a chance, &konqueror; will +work satisfactorily with the vast majority of web pages. +To overcome this problem you can change the browser identification +information that &konqueror; sends for specific sites or domains by +selecting Settings +Configure Konqueror... to bring up the +Settings dialog box and clicking the Browser Identification +icon. +Problems with getting a web page to work properly may also be due +to its use of &Java; or JavaScript. If you suspect that this may be the case +check that they have been enabled in the Java & JavaScript + section of the Settings dialog box. + + + + +Saving and Printing Web Items + +When you are viewing a web page you can save it (or at least the basic +&HTML; or similar source text) to your local disk with +LocationSave +As.... If the page +you are viewing uses frames, then you will also be given the +LocationSave Frame +As... option. Left click + in the frame you want to save first. + +If the page uses a background image, you can get and save that with the +LocationSave Background +Image As... option. + +But if what you really want is that glorious picture of the latest +Ferrari, then right clicking on the image will +give you a drop-down menu with a +Save Image As... option. Be sure to respect the +owner's copyright, and ask for permission before using any pictures saved this +way for anything other than your own viewing pleasure. + +If you right click on a link (which may be a +picture) and select Save Link As... from the pop +up menu the basic &HTML; or similar source text will be +downloaded and saved on your local disk. + +Right clicking on a link (which may be a +picture) and choosing Copy Link Location will copy +the &URL; of the link to the clipboard so you can then paste it into, say, an +e-mail to a friend telling her about this wonderful new site. + +Right clicking on a picture and choosing +Copy Image Location copies the &URL; of the picture +to the clipboard. + +To save a complete web page, including images, select +Archive Web Page... from the Tools menu. +Note that this feature is provided by a plugin + and may not have been installed on your system. The web page will be +saved as a single file with a .war +extension and can be opened by left clicking +on the filename in &konqueror; running in File Manager mode. + +Printing a copy of the page you are viewing is easily done with the +Menubar Location +Print... or Print +Frame option or with the Toolbar Print +button. + + + + +&FTP; + +&FTP;, or File Transfer Protocol, is one of the the earliest, and still +perhaps the best, way of transferring files between computers over the +Internet. + +With &FTP; you can see files and folders on the distant computer just +as if they were on your own system, download them onto your computer using +&konqueror;'s normal Copy and +Paste or Drag n' Drop methods and, if allowed, +upload files from your machine to the other computer's filesystem. To try it, +type the &URL; + + +ftp://ftp.kde.org/pub/kde + + +into the Location Toolbar and press &Enter;. As long as +you are connected to the Internet, and as long as the &kde;'s &FTP; site is +not too busy, you should end up seeing the /pub/kde folder at &kde-ftp; + +Although, strictly speaking, &FTP; &URL;s should +be entered starting with ftp:// and WWW + &URL;s starting with http:// +&konqueror; is usually smart enough to figure out what is meant, and insert +these characters for you if you leave them out. + +When you access an &FTP; site it will usually need some form of username +and password from you. To simplify things, most &FTP; sites that offer files +for free downloading will accept the word +anonymous as a username and your email +address as a password, and to make your life even easier &konqueror; will +automatically supply these without troubling you. + +If you try to access an &FTP; site that does not need a proper +username or password but which is too busy to accept any more connections, +&konqueror; often interprets the busy message as a request for +a name and password and will therefore pop up a dialog box asking you to +supply them. + +Sites that are more concerned with security will need a proper username +and password, in which case &konqueror; will ask you for them or you can +include the username in the &URL; you type into the Location Toolbar, as +for example + + +ftp://username@ftp.cia.org + + +&konqueror; will then prompt you for the password. + +&konqueror; can also support automatic logins as specified in a +.netrc file. Details of how to enable this feature are +given at +http://www.konqueror.org/faq.html#netrc + + + + + +&URL;s with Port Numbers +If you specify a port number in your &URL;, as in for example +http://intranet.corp.com:1080, you might get the error +message Access to restricted port in POST denied. This is done +for security reasons. If you nevertheless need to access a server on this port, +just add a key line + +OverridenPorts=CommaSeparatedListOfAllowedPorts + +to $KDEDIR/share/config/kio_httprc + or +~/.kde/share/config/kio_httprc. +For example +OverridenPorts=23,15 + +(it should not include any embedded spaces). +&konqueror; will reject the following ports (the list is hardcoded in +kdelibs/kio/kio/job.cpp): + + 1, 7, 9, 11, 13, 15, 17, 19, + 20, 21, 22, 23, 25, 37, 42, 43, + 53, 77, 79, 87, 95, 101, 102, 103, 104, + 109, 110, 111, 113, 115, 117, 119, 123, + 135, 139, 143, 179, 389, 512, 513, 514, + 515, 526, 530, 531, 532, 540, 556, 587, + 601, 989, 990, 992, 993, 995, 1080, + 2049, 4045, 6000, 6667 + + + + + + + diff --git a/doc/konqueror/cmndline.png b/doc/konqueror/cmndline.png new file mode 100644 index 000000000..380fead0f Binary files /dev/null and b/doc/konqueror/cmndline.png differ diff --git a/doc/konqueror/commands.docbook b/doc/konqueror/commands.docbook new file mode 100644 index 000000000..2b3142ecc --- /dev/null +++ b/doc/konqueror/commands.docbook @@ -0,0 +1,1210 @@ + + + + +&Pamela.Roberts; + + + +2003-11-06 +3.2 + + +Command Reference + +The shortcut key combinations shown in this chapter are the +default ones. They can of course be changed. + + + +Special Shortcuts +There are some useful shortcuts that are not shown in any of the menus: + + + +F6 + +Sets the focus to the text entry box in the Location Toolbar. + + + + +&Ctrl;] + +Activate the next tab page. + + + + +&Ctrl;[ + +Activate the previous tab page. + + + + + + + + + +The Menubar Note that some menu entries only appear when +they are applicable to the file you currently have open in &konqueror;. For +example, the +EditFind... + +item will not appear when you are viewing the contents of a directory. + +The <guimenu>Location</guimenu> Menu + + + + + +&Ctrl;N + +Location +New Window + +Open another &konqueror; +window. + + + + + +&Ctrl;&Shift;N + +Location New Tab + +Open another &konqueror; tab, containing a +blank page. + + + + + +&Ctrl;D + +Location +Duplicate Window + +Open another &konqueror; window, duplicating the +current +one. + + + + + +&Ctrl;O + +Location +Open Location... + +Open a folder or file by entering its path + (for example /home/pam or +/home/pam/fred.txt) in a simple dialog +box. + + + + +Location +Send Link + +Send an email containing a link to the current +location. + + + + +Location +Send File + +Send an email containing the selected file as an +attachment. + + + + + +Location +Save Background Image As... + + +Only applies if you are viewing a web page with a background image. Opens +the Save As dialog box to let you save the background +image file to your own computer. + + + + + + +&Ctrl;S + +Location +Save As... + +Only applies if you are viewing a document or web page, uses +the +Save As... dialog box to let you save a copy to your own +computer. + + + + +Location +Save Frame As... + +Similar to Save As... but for +use with a web site that uses frames. + + + + + +&Ctrl;P + +Location +Print... + +Print. + + + + +Location +Print Frame + +Print selected frame of a Web +page. + + + + +Location +Open With Netscape/Mozilla + +Open the web page you are +viewing in &konqueror; with &Netscape;/Mozilla as well. + + + + + +&Ctrl;Q + +Location +Quit + +Close down this instance of +&konqueror;. + + + + + + + +The <guimenu>Edit</guimenu> Menu + +Most items in the Menubar Edit menu can also be +found by &RMB; clicking on a free area of a view. + + + + + + +&Ctrl;Z + +Edit +Undo + +Sometimes lets you reverse a mistaken +action. + + + + + +&Ctrl;X + +Edit +Cut + +Puts selected item(s) into the clipboard. If +you then do a a Paste the item(s) will be moved +from the original location to the new one. + + + + + +&Ctrl;C + +Edit +Copy + +Copy selected item(s) to the +clipboard. + + + + + +&Ctrl;V + +Edit +Paste + +Paste item(s) from clipboard to the currently viewed +folder. + + + + +F2 +Edit +Rename + +Lets you rename a file or folder without + having to +open the Properties... dialog box. + + + + + + +Delete +Edit +Move to Trash + +Move selected item(s) to the Trash +folder. + + + + + +&Shift;Delete + +Edit +Delete + +Delete the selected item(s). + + + + +F7 +Edit +Copy Files + +Copy the selected item(s) to another +folder. + + + + +Edit +Move Files + +Move the selected item(s) to another +folder. + + + + +Edit +Create New + +Create a link to an application, +URL, Floppy or &CD-ROM; device, or create a new Folder or +text or &HTML; file. See the Create +New...section for more details. + + + + +Edit +Edit File Type... + +Open the Edit File Type +dialog box + + + + +Edit +Properties.. + +Open the Edit Properties +dialog box + + + +EditSelection + +Contains a number of options for changing the items selected in +the &konqueror; window: + + + + + +&Ctrl;+ + +Edit +Selection +Select... + +Together with the Unselect..., +Unselect All and Invert +Selection commands, this provides an easy and powerful way of selecting +multiple +files. +It brings up a simple dialog box where you can enter a file +name using the wild card characters * and ?, for example entering +*.html will select all files ending with +.html while ?a* will +select all files which have the letter a as the second character in their +filename. + + + + + +&Ctrl;- + +Edit +Selection +Unselect... + +Unselect files or folders via a dialog similar to the one used +by Select.... + + + + + +&Ctrl;U + +Edit +Selection +Unselect All + +Unselect all selected files or +folders. + + + + + +&Ctrl;* +Edit +Selection +Invert Selection + +Invert current selection. + + + + + +&Ctrl;A +Edit +Selection +Select All + +Selects all text in an &HTML; +page or in a text page being previewed, you can then +Copy it and Paste it into +a text editor. + + + + + + + + +&Ctrl;F +Edit +Find... + +Find a text string in a text +page you are previewing or in an &HTML; +page. + + + + +F3 +Edit +Find Next + +Find the next occurrence of the text string +in the text or &HTML; page. + + + + +Edit +Go to Line... + +Go to a particular line number in a text +page you are previewing. + + + + + + + + +The <guimenu>View</guimenu> Menu + + + + +View +View Mode... + +Selects Icon, +MultiColumn, Tree, +Detailed List +or Text view mode. + + + + +View +Use index.html + +If a selected folder contains a file +index.html, it will be opened as a web +page rather than showing the folder as a list of +files. + + + + +View +Lock to current location + +Lock to current location. + + + + + +View +Unlock all views + +Unlock all views. + + + + + +View +Link View + +Link current view to others in a multiple view +window. + + + + +F5 +View +Reload + +Reload. + + + + +Esc +View +Stop + +Stop load (particularly useful when web +browsing). + + + + +View +Icon Size + +Select size of icons used when +viewing a folder in Icon Mode. + + + + +View +Sort + +Choose order in which items are presented in the +window when in Icon or MultiColumn View mode. + + + + +View +Case Insensitive Sort + +Choose whether the sort order in Tree, Detailed List +or Text View modes is case sensitive. + + + + +&Ctrl;U + + +View +View Document Source + +View document source text. +Only available if you are viewing a document or &HTML; +page. + + + + + +View +View Frame Source + +View frame source text +Only applies if you are viewing a web site that uses frames. Similar to +View Document Source. + + + + + +&Ctrl;I + + +View +View Document Information + +View document information, such as title, &URL;, and &HTTP; +headers used in retrieving the document. +Only available if you are viewing an &HTML; +page. + + + + + +View +Security... + +Tells you whether the current browser connection is +secured with SSL and lets you bring up the +Cryptography Configuration... dialog +box. Left clicking on the Menubar padlock icon does +the same thing. + + + +View +Set Encoding + +Set encoding +Allows you to choose the character encoding used to display +&HTML; pages. Auto is usually the + best +choice. + + + + +View +Preview + +Lets you choose to show thumbnails of images, text +files +or &HTML; pages instead of the normal icons in Icon or +MultiColumn View modes. + + + + +View +Show Hidden Files + +Show hidden (dot) files. + + + + +View +Show details... + +Lets you choose which file and folder details are +shown in Tree, Detailed List and Text views. + + + + + +View +Background Color... + +Select background color for the File Manager mode. + + + + + +View +Background Image... + +Select background image for the File Manager mode. + + + + + + + + +The <guimenu>Go</guimenu> Menu + + + + + + +&Alt;Up Arrow +Go +Up + +Go up a level in the folder +hierarchy. + + + + + +&Alt;Left Arrow +Go +Back + +Go back to the previous +view. + + + + + +&Alt;Right Arrow +Go +Forward + +You can only go forward if you've just gone +back. + + + + + +&Ctrl;Home +Go +Home URL + +Go to your home folder. + + + + +Go +Applications + +Open the folder holding your +applications. + + + + +Go +Trash + +Open your Trash +folder in a separate window. + + + + +Go +Templates + +Open the Templates folder in a separate +window. + + + + +Go +Autostart + +Open your Autostart folder in a separate +window. + + + + +Go +Most Often Visited + + +Displays a submenu showing the &URL;s you visit most often. Selecting one +of these will make &konqueror; open that &URL;. + + + + + + + + +The <guimenu>Bookmarks</guimenu> Menu + +See the section Using Bookmarks +in this manual for a fuller description of these menu items. + + + + + + +&Ctrl;B + +Bookmarks +Add Bookmark + +Add current selection to your +bookmarks. + + + + +Bookmarks +Bookmark Tabs as Folder... + + +Create a bookmark folder containing links to all of the &URL;s currently +open in &konqueror; tabs. + + + + + +Bookmarks +Edit Bookmarks... + +Open the Bookmark Editor. + + + + + +Bookmarks +New Bookmark Folder... + +Create a new folder in your Bookmarks +folder. + + + + + + +The <guimenu>Tools</guimenu> Menu + + + + + + +&Alt;F2 +Tools +Run Command... + +Run a program by entering its name in a +simple dialog box. + + + + + +&Ctrl;T +Tools +Open Terminal + +Open a &konsole; terminal + window. + + + + +Tools +Find File... + +Open the &kfind; application. + + + +If you have &konqueror; plugins installed there will be additional +entries in the Tools menu. See the &konqueror; Plugins chapter for further +details. + + + +The <guimenu>Settings</guimenu> Menu + +See also the section Saving Settings +and Profiles. + + + + + + +&Ctrl;M +Settings +Show Menubar + +Show/Hide the menubar. + + + + +Settings +Toolbars + +Opens a sub menu where you can choose to show or hide +the various Toolbars. + + + + + +&Ctrl;&Shift; +F + +Settings +Full Screen Mode + + +Changes &konqueror; to full screen mode, in which the &konqueror; window +takes up the whole screen, and does not have the usual window decorations. To +exit full screen mode, click on the Exit Full Screen Mode +icon on the toolbar, or press &Ctrl;&Shift; +F. + + + + + + +Settings +View Properties Saved in Folder + +Save View properties to current + folder. If this is selected, a .directory file will be +written in the current directory storing the settings you last used to view the +directory. These settings are then loaded when you open the directory in &konqueror;. + + + + +Settings +Remove Folder Properties + +Remove settings stored in folder by View +Properties Saved in Folder. + + + + +Settings +Load View Profile + +Load the settings associated with a particular view profile. + + + + +Settings +Save View Profile "ProfileName"... + +Save the current settings to the current view profile. + + + + +Settings +Configure View Profiles... + +Lets you change an existing view profile or create a +new one. + + + + Settings +Configure Shortcuts... + Lets you +see and change &konqueror;'s shortcut key bindings, i.e. the +associations between actions such as Copy and keys +or combinations of keys such a &Ctrl;V. If you do +this take care not to duplicate an existing shortcut. + + + + Settings +Configure Toolbars... + +Lets you configure the Main, Extra and Location Toolbars. See the +section Changing Bars. + + + + Settings +Configure &konqueror;... +Lets you configure the File manager, File Associations, +Browser, Internet Keywords, Cookies, Proxies, Cryptography, User Agent, or +Toolbars by bringing up the appropriate dialog box. + + + + Settings +Configure Spell Checking... + +Displays the spell checking configuration dialog box, in which you can +change settings associated with spell checking in &konqueror;. + + + + + + + + + +The <guimenu>Window</guimenu> Menu + + + + + + +&Ctrl;&Shift;L +Window +Split View Left/Right + +Split View Left/Right. + + + + + +&Ctrl;&Shift;T +Window +Split View Top/Bottom + +Split View Top/Bottom. + + + + + +&Ctrl;&Shift;R +Window +Remove Active View + +Remove Active View. + + + + + +&Ctrl;&Shift;N +Window +New Tab + +Open a new, empty, tab page. + + + + + +&Ctrl;&Shift;D +Window +Duplicate Current Tab + +Open a duplicate tab page. + + + + + +&Ctrl;&Shift;B +Window +Detach Current Tab + +Show the current tab page in a new instance of +&konqueror;. + + + + + +&Ctrl;W +Window +Close Current Tab + +Close the current tab page. + + + + + +&Ctrl;&Shift;Left +Window +Move Tab Left + +Move the current tab one place left in the list of tabs. + + + + + +&Ctrl;&Shift;Left +Window +Move Tab Right + +Move the current tab one place right in the list of tabs. + + + + +Window +Show Terminal Emulator + +Open a small text terminal view at the bottom of the + main +window. + + + + + +F9 +Window +Show Navigation Panel + +Toggles the display of the &konqueror; navigation panel. See +. + + + + + + + +The <guimenu>Help</guimenu> Menu + + + + + +Help +&konqueror; Handbook + +View this document. + + + + + +&Shift;F1 +Help +What's This? + +Draws a question mark (?) beside the mouse +pointer, clicking on a window item such as the +Stop button will then display a brief explanation. See +Tooltips and What's This? . + + + + +Help +&konqueror; Introduction + +Revisit the introductory pages that you got when +&konqueror; was first started. + + + + +Help +Report Bug... + +Report bug. + + + + +Help +About &konqueror;... + +Display some brief information about +&konqueror;'s version number, authors and license agreement. + + + + +Help +About KDE... + +Show some information about the version of &kde; that +you are running. + + + + + + + + + + diff --git a/doc/konqueror/config.docbook b/doc/konqueror/config.docbook new file mode 100644 index 000000000..18ebfaa4f --- /dev/null +++ b/doc/konqueror/config.docbook @@ -0,0 +1,137 @@ + + + + +&Pamela.Roberts; + + + +2003-11-06 +3.2 + + + +Configuring &konqueror; + +In common with the rest of &kde;, &konqueror; is highly configurable, so +you can really get the look and feel that best fits your needs and +wishes. + + +Toolbars + +When &kde; is newly installed, &konqueror;'s window contains a Menubar, +Main and Location Toolbars and possibly a Bookmark Toolbar. + +Maybe you don't need all these toolbars. To hide one of them, go into +the SettingsToolbars + menu and uncheck its box. To show a hidden toolbar, just check +the box. + +The Menubar itself can be toggled on and off with the shortcut key +combination &Ctrl;M. + + + +On the left hand end of each bar you can see some vertical +lines. By &LMB; clicking on them, you flatten the bar, meaning +that it is hidden but can be quickly restored by clicking on the now +horizontal lines. You can also drag a bar into a new position with these +lines. + +If you right click on a Toolbar, you +will get a menu to configure this bar. You can choose the orientation, text +position and icon size + +The icons shown in the various bars can be changed by using the +Settings Configure +Toolbars... option, which brings up the +Configure Toolbars dialog box. The Main and Extra Toolbars +are divided into sections, such as Main Toolbar <&konqueror;>, Main +Toolbar <khtmlpart> and Extra Toolbar <khtmlsettingsplugin>. The +number and type of these sections will depend on whether &konqueror; is in Web +Browser or File Manager mode and whether you have &konqueror; plugins +installed. + + + + +Shortcuts +To change the shortcut key arrangements used by &konqueror; select +SettingsConfigure Shortcuts... +. This will launch a dialog box as shown below. + + + + + + +Shortcut config screenshot 1 + + +Search through the combo box to find the action you want to add or +change the shortcut keys for and select it by left +clicking on the name. You will then be able to change the shortcut by +selecting the None, Default or +Custom radio button or by clicking on the large button in +the Shortcut for Selected Action area. + +If you select Define Shortcut, and then +select Advanced, the dialog box below will be shown: + + + + + + +Shortcut config screenshot 2 + + +Choose whether you want to change the Primary or +Alternate shortcut then press the key combination you +want to act as the shortcut, for example +&Ctrl;&Shift;S. +If the Auto-Close box is checked the dialog will vanish +as soon as you enter the key combination, otherwise it will remain until you +press OK or Cancel. Clicking on +the little black icon with a white cross in it clears the shortcut. + + +User Defined Menus +You can add your own pop up menu to &konqueror; so that pressing one key +combination will make the menu appear then pressing a second key, or using the +Up arrow and Down arrow keys and pressing +Enter, will select an item from it. +To do this add a Custom shortcut for each of the +actions you want to appear in the menu and in the Define Shortcut + dialog check the Multi-Key box, press the +key combination that you want to bring up your new menu then, separately, +press the key that will choose that item from the menu. + + + + +Other Settings +Selecting Settings +Configure Konqueror... brings up a dialog box +which you can use to control most aspects of &konqueror;'s behavior. +It contains several sections which are selected by left + clicking on one of the icons at the left of the dialog +box. +Pressing the Help button will give you +detailed instructions about how to use each of these sections, or you can +use the What's This? feature. + + + + + diff --git a/doc/konqueror/credits.docbook b/doc/konqueror/credits.docbook new file mode 100644 index 000000000..ed63a9b5f --- /dev/null +++ b/doc/konqueror/credits.docbook @@ -0,0 +1,182 @@ + + + + +&Pamela.Roberts; + + + +2003-11-06 +3.2 + + + +Credits and License + +&konqueror;. Program copyright 1999-2003, the &konqueror; + developers: + + + + +&David.Faure; &David.Faure.mail; +developer (parts, I/O lib) and maintainer + + + +&Simon.Hausmann; &Simon.Hausmann.mail; +developer (framework, parts) + + + +&Michael.Reiher; &Michael.Reiher.mail; +developer (framework) + + + +&Mattias.Welk; &Mattias.Welk.mail; +developer + + + +&Alexander.Neundorf; &Alexander.Neundorf.mail; +developer (list views) + + + +&Michael.Brade; &Michael.Brade.mail; +developer (list views, I/O lib) + + + +&Lars.Knoll; &Lars.Knoll.mail; +developer (HTML rendering +engine) + + + +&Antti.Koivisto; &Antti.Koivisto.mail; +developer (HTML rendering +engine) + + + +&Dirk.Mueller; &Dirk.Mueller.mail; +developer (HTML rendering +engine) + + + +&Peter.Kelly; &Peter.Kelly.mail; +developer (HTML rendering engine, +JavaScript) + + + +&Waldo.Bastian; &Waldo.Bastian.mail; +developer (HTML rendering engine, I/O +lib) + + + +&Matt.Koss; &Matt.Koss.mail; +developer (I/O lib) + + + +&Alex.Zepeda; &Alex.Zepeda.mail; +developer (I/O lib) + + + +&Stephan.Kulow; &Stephan.Kulow.mail; +developer (I/O lib) + + + +&Richard.J.Moore; &Richard.J.Moore.mail; +developer (&Java; applet support) + + + +Dima Rogozin dima@mercury.co.il +developer (&Java; applet support) + + + +Wynn Wilkes wynnw@calderasystems.com +developer (&Java;2 manager support and other major improvements +to applet support) + + + +&Harri.Porten; &Harri.Porten.mail; +developer (JavaScript) + + + +Stefan Schimanski schimmi@kde.org +developer (&Netscape; plugin support) + + + +&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; +developer (framework) + + + +&George.Staikos; &George.Staikos.mail; +developer (SSL support) + + + +Dawit Alemayehu adawit@kde.org +developer (I/O lib, Authentication support) + + + +&Torsten.Rahn; &Torsten.Rahn.mail; +Graphics / icons + + + +Torben Weis weis@kde.org +kfm author + + + +&Joseph.Wenninger; &Joseph.Wenninger.mail; +developer (navigation panel framework) + + + +&Stephan.Binner; &Stephan.Binner.mail; +developer (misc stuff) + + + + +Documentation copyright 2000-2003 + + +&Erwan.Loisant; &Erwan.Loisant.mail; +&Pamela.Roberts; &Pamela.Roberts.mail; + + +Documentation updated for &kde; 3.2 by &Philip.Rodrigues; &Philip.Rodrigues.mail;. + + +&underFDL; +&underGPL; + + + diff --git a/doc/konqueror/dirtree.png b/doc/konqueror/dirtree.png new file mode 100644 index 000000000..fc20b2cc6 Binary files /dev/null and b/doc/konqueror/dirtree.png differ diff --git a/doc/konqueror/dragdrop.png b/doc/konqueror/dragdrop.png new file mode 100644 index 000000000..8994a5c89 Binary files /dev/null and b/doc/konqueror/dragdrop.png differ diff --git a/doc/konqueror/faq.docbook b/doc/konqueror/faq.docbook new file mode 100644 index 000000000..5429c71e7 --- /dev/null +++ b/doc/konqueror/faq.docbook @@ -0,0 +1,169 @@ + + + +&Pamela.Roberts; + + + +2003-11-06 +3.2 + + +Questions and Answers + + + + + + +Can I run &konqueror; from another window +manager? + +Just install &Qt;, kdelibs and kdebase, and from your favorite +window manager, launch &konqueror;. It should work just fine, but if it +doesn't (&kde; developers don't test that case often), report it to http://bugs.kde.org and try running +kdeinit before running &konqueror;; it usually +helps. + + + +Where does &konqueror; keep all its configuration +data? +Generally in the ~/.kde folder (this may +be ~/.kde3 on your system, depending on how &kde; 3 +was installed). Don't alter these files unless you really know what you are +doing. + + + +The ~/.kde/share/apps/konqueror/profiles folder +holds individual files containing settings for each of your profiles. + +Your bookmarks are held in ~/.kde/share/apps/konqueror/bookmarks.xml +Cookies are held in ~/.kde/share/apps/kcookiejar/cookies +Your history, as used for the auto-completion feature, is in +~/.kde/share/config/konq_history + +In the folder ~/.kde/share/config/ the files +konqiconviewrc, konqlistviewrc and +konquerorrc hold a whole lot of general configuration +settings. + +The folder +~/.kde/share/cache/http/ +contains the browser cache. + +The Navigation Panel uses the files and subfolders in +~/.kde/share/apps/konqsidebartng + + +Any folder specific view settings are put into .directory files in the individual +folders. + + + +How do I clear out the history file? +There are two histories: + +One is used for text completion in the Location Toolbar text entry +box. To clear this right click on the text entry +box and select Clear History +. + +The other is the log of visited locations. Select the History +page in the Navigation Panel, +right click on an entry and choose +Remove Entry to remove just that entry or +Clear History to delete all +entries. + + + + + + + +How do I enable, disable or clear the browser +cache? +If you select Cache in the dialog launched by +selecting +SettingsConfigure Konqueror... +, you will be presented with a dialog box that lets +you disable the cache, clear it or set its size, and change the caching +policy. + + + + +How can I change the timeout values used by &konqueror; +when web browsing? +In the Control Center Internet & Network +Preferences page. + + + + +How do I set my home page - the page loaded +on startup? +Start &konqueror; with the Web Browser icon +on the panel. Open the page you want to be loaded in any new Web +Browser window and select Save View Profile "Web +Browsing" from the Settings menu. + +All new &konqueror; windows that are started with the Web +Browser icon on the panel, or from the location +menu, and new empty tabs, will now start at this page. + +This does not change the behavior of the +Home button on the &konqueror; toolbar, which will +continue to take you to the &URI; defined in the &konqueror; configuration +module. You can reach that module from within &konqueror;, via +SettingsConfigure +KonquerorBehavior. By +default this is set to ~, which is your Home folder. +You may set this to any &URI;, either local or remote, and pressing the +Home icon on the toolbar will display it. + +To have &konqueror; start up with no page loaded, use +about:blank. + + + + +I can't find the answer to my question here. + +Take a look at +http://www.konqueror.org/faq.html or + +http://www.konqueror.org/konq-java.html. + + + + + + + diff --git a/doc/konqueror/filemanager.docbook b/doc/konqueror/filemanager.docbook new file mode 100644 index 000000000..c6fb880ba --- /dev/null +++ b/doc/konqueror/filemanager.docbook @@ -0,0 +1,898 @@ + + + +&Pamela.Roberts; + + + +2005-04-01 +3.4 + + +&konqueror; the File Manager + + +Folders and Paths +In &UNIX; and &Linux; all folders are arranged in a simple +inverted tree structure descending and branching down from from a single top +level folder. This means that you can get from any folder to +any other by going up until you reach a common point then +down through the appropriate subfolders until you reach +your +target. + +The position of any file or folder in the tree can be described by its +path, which is a simple list of the folders you would have +to descend through to get to the target folder or file. For example +/home/pam is the subfolder pam of the subfolder home of the top level folder, and +/home/pam/words.txt is the file words.txt in +that subfolder. The leading / in these paths represents the +top level folder. + +Every folder accessible by your system — including those on +other hard disk partitions, your floppy and &CD-ROM; — will appear +in the tree descending +from /, their exact paths will depend on how your system was set up (see +also +the section on Floppy and &CD-ROM; Drives). + +Every user on a &UNIX; / &Linux; system has their own home +folder to hold their personal files and settings; for example +/home/john and +/home/mary. The +symbol ~ is often used to represent the user's home +folder, so that ~/letter.txt refers to the file +letter.txt in my home folder. +Note that the term directory is often used instead of +folder. + + + +View Modes +In File Manager mode, &konqueror; shows you what files and +subfolders are held in a folder, and can provide you with some +information about them. +The path of the folder you are looking at is shown in +the Titlebar, and also in the Location Toolbar, prefixed with file: + to indicate that the folder is part of your computer's normal file +system. For example file:/home/pam. + +The way that &konqueror; displays the files and folders depends mainly +on your choice of View Mode. This can be selected from the +ViewView Mode +sub menu, which gives you the following options: + + + + + +Icon View +Displays the name and a suitable icon for each file or folder. + + + + +MultiColumn View +Similar to Icon View except that the +display is neatly formatted into regular columns. + + + + +Detailed List View +Displays each file or folder on a separate line, as a small +icon followed by the file or folder name followed by information about the +item. The amount of information shown is controlled by the +ViewShow Details +sub menu settings. + + + + +Text View +Similar to Detailed List View +except that icons are not shown and the first character in each line will be +/ if the item is a folder. + + + + +Tree View +This option is useful for +navigating through the folder tree below the current folder. +The display is similar to Detailed List View +except that the start of each line will show a small + sign +in a box if the item is a folder. +Left clicking on the box will expand the display to +show the contents of that folder. + + + + +Info List View +Similar to Detailed List View +except that, where applicable, it shows the number of lines, words and +characters and file format for each file. + + + + +The default file icons shown in Icon View and +MultiColumn View modes can be replaced by small +preview images of the file contents, see the section +File Previews of this handbook for more details. + + +File Tip Info +Checking the Show file tips box in the +Behavior page of the &konqueror; Configuration dialog causes a +small pop up information +window to appear when the mouse pointer is hovered over a file or folder name +or icon in Icon View or +MultiColumn View mode. + +If the Show previews in file tips checkbox is +checked the pop up window will also show a small image of the file contents. + + + + +File Previews +Selecting ViewPreview + from the Menubar will bring up a sub menu +that lets you enable file previews for certain types of file. +Generally this means that the file's icon will be replaced by a small +image showing the file contents. +If file preview is enabled for Sound Files +the file will be played whenever the mouse cursor is hovering over the file +name or icon. +Note that file previews are only available in Icon View + and MultiColumn View modes. +Because &konqueror; has to read much more data than just the file name +details to generate a preview, file previews may not be appropriate +when viewing files on a floppy or from a remote system. The Previews + page of the File Manager Configuration +dialog allows you to disable file previews for protocols such as +ftp where reading the extra data would take too +long. + + + + + +Navigation +To get to a file with &konqueror; you first need to navigate +through the folder tree to find the folder containing that +file. + +To move between folders you can simply step up and down the +tree: + + +To descend into a subfolder left + click on its name or +icon -- or if you have already selected it (see below) -- then just press +Enter. +To go up the folder tree you can click on the Up + button in the Toolbar, use&Alt;Up Arrow, or use the Menubar +GoUp +option. + + +To select a file or folder in the displayed folder +without opening it in any way use the up and down + arrow keys to move through the items. +The selected item will be highlighted and some information about it +will be displayed in the Status Bar. + +Setting the View Mode to +Tree View can help you locate folders in the tree below the +current folder; in this mode each folder is shown with a small box at +the left. If the box contains a + sign, left + clicking on the box (not on the folder name or icon) will +display a sub tree showing files and subfolders contained in that folder. +The small box will then change to show a - sign. +Left click on that to collapse the sub tree. Once +you have found the folder you are looking for, left + click on the folder name or icon to open it. + +The Navigation Panel can also help you +find your way around the file system. + +You can go directly to any folder by typing its path into the +Location Toolbar window or into the dialog box invoked by the Menubar +LocationOpen Location + item or by &Ctrl; +O. &konqueror;'s +Text Completion feature may be useful when you do this. Don't forget +that in &Linux; / &UNIX; file and folder names are case sensitive. + +When you have moved to a new folder you can go back to your +previous choice by using the Toolbar Back button, the +Menubar +Go Back +item, or &Alt;Left +Arrow. Once you have gone back you can go forward. Use the Toolbar +Forward button, the Menubar +Go +Forward item or &Alt;Right +Arrow. + +Alternatively, you can also choose to enter the parent folder by clicking on the Toolbar Up, the Go Up item, or with &Alt;Up +Arrow. + +Holding the &LMB; pressed while the mouse pointer is +over the Toolbar Up, Back or +Forward buttons brings up a menu of recently visited +locations. + + +Finding Files and Folders + +If you don't know or can't remember where a file or folder is within +your system, then use the Toolbar Find File button or the +Menubar ToolsFind +File... option. This will embed the file finder +application &kfind; into &konqueror;'s window. See the &kfind; Handbook +for help in using &kfind;. + + +If the name of a file or folder begins with a period (dot), then +it is a hidden file or folder, and will not normally be shown +by &konqueror;. To see hidden files or folders use the Menubar +ViewShow Hidden Files + option. +Another reason &konqueror; may not show the file or folder you are +looking for is that you may have the +View Filter plugin set to display only certain types of +file. + + + + +Floppy and &CD-ROM; Drives + +Any floppy disk, &CD; drive or other hard disk partition that you have +on your system will usually appear in the / +, /media, /mnt or +/auto folder, having a path something +like /mnt/floppy or +/cdrom. The details will depend on +how your system was set up. + +&UNIX; / &Linux; requires that you mount a floppy disk +or &CD-ROM; when you have inserted it into the drive, and mount + other hard disk partitions when you want to access them. You also +need to unmount a floppy disk or &CD-ROM; before removing it to register that +it is no longer available. + +How you do this will depend on how your system: + + +You may have an Automount facility, +in which case you don't have to bother about explicitly mounting and +unmounting, +although you may find that the &CD-ROM; occasionally starts up by itself for no +apparent reason. + +You may have Floppy, &CD-ROM; and hard disk +icons on your desktop, in which case &LMB; click on the icon to mount it. +Doing this should also bring up a &konqueror; window showing the contents of +the floppy, &CD-ROM; or partition. To unmount, right +click on the icon and choose the Unmount item. +Visit the section Create New... in this Handbook +to see how to create such an icon. + +Or you can do it the traditional way by typing into a text +console window: + +mount /mnt/floppy + + + +to mount, for example, the floppy drive, and + + + +umount /mnt/floppy + +to unmount it (umount not unmount). + + +Rather than having to open a text console to type the +mount + or umount commands, you may prefer to use +&konqueror;'s ToolsExecute Shell +Command +(&Ctrl;E) + feature. + + + + + + + + + + +Deleting Files and Folders + +&konqueror; gives you two ways to dispose of an unwanted file or +folder: + + +You can move it to the Trash folder, which +is the safest method as you can get it back if you realize that you have made a +mistake. + +You can just plain Delete it, which +removes the entry from the folder and adds the disk area occupied by the +file(s) to the system's list of free disk areas, in the same way as the +rm command. + + +The simplest way to remove a file or folder is to position +the mouse pointer over its name or icon and press the &RMB;, which +will bring up a menu containing the options Move to +Trash and Delete. + +Or, if you have selected the item, the Menubar +Edit menu will give you the choice of +Move to Trash and +Delete options. + +Del will move the selected item or items to Trash. + +&Shift;Del +will really, truly and irrevocably delete the selected item or +items. + +You won't be able to remove a file or folder if you don't have +the necessary permissions; see the section on Super +User Mode for further details. + + + + +Moving and Copying + +To copy a file or subfolder between folders you can: + + +Position the mouse pointer over its name or icon and hold down +the &RMB;, which will bring up a menu containing the +Copy option. Choose that. + +Or if the item is selected you can use the +Copy button on the Toolbar or the Menubar +Edit +Copy +item, or the &Ctrl;C +shortcut key combination. You can also select multiple files or folders to copy/move as well. + +Navigate to the folder you want to copy the item into then +Paste the item into the new folder by using the Toolbar +Paste button or the Menubar +Edit +Paste option or the &Ctrl;V shortcut, or by +moving the mouse pointer to a clear area of the window and holding the &RMB; +down to bring up a menu containing the Paste option. + + + +Moving a file or subfolder between folders can be done in the +same +way as copying, except that you choose the Cut +option +or &Ctrl;X +instead of Copy. The item that you have +Cut will be removed from the original folder when +you do the Paste into the new folder. + +You can also copy or move selected item(s) to another folder by using +Edit +Copy Files (F7) or +EditMove Files + (F8), or by selecting +Copy To or Move To from +the drop down menu you get when you right click on +an file or folder name in the File Manager window. + +You may not be able to copy or move a file or folder if +you don't have the necessary permissions. See the section on Super User Mode for further +details. + + +Using Drag 'n Drop + +&konqueror; also supports Drag and Drop copying and moving of files and +folders. + +You can do this by having two instances of &konqueror;, one showing the +folder you want to copy from, the other showing the target folder. +Position the mouse pointer over the item you wish to copy or move, then, +holding the &LMB; pressed, drag it to a clear space in the +target + +folder. Release the button and you will be +presented with a menu choice of Copy or +Move. Take care to drop the item into + an empty area of the target +folder view - dropping it on top of another file name or icon can cause +problems. + +You can also set up &konqueror; to show more than one folder within +its window and drag & drop between them. + + + + +Split Views for Drag & Drop + + + +This screenshot illustrates the use of the Menubar +Window Split View +Left/Right option, also available with the shortcut +&Ctrl;&Shift;L +, +to split the main &konqueror; window into two views, each showing the contents +of a different folder. + +To be able to show different folders in each view they should not be +linked; the little boxes at the bottom right of each view should be empty. + + +The active view, that is the one whose path is shown in +the Location Toolbar and which responds to navigation and Menubar commands, is +shown by the little green light in the bottom left corner. To make a view +active, left click on an empty area of the view or +on its Status Bar. + +To remove an active view from &konqueror;'s window use the &Ctrl;&Shift;R + shortcut, or the Menubar Window +Remove +Active View option, or &RMB; click on the Status Bar +and choose the Remove Active View option from the +resulting menu. + +If you use &konqueror; tabs, you can drag and drop between tabs +by dragging the file to the tab label, without letting go yet. The +destination tab will pop to the front, allowing you to continue +dragging and then drop the file. + + + + +Duplicate File Names +If you try to paste a file into a folder that already +contains a file with the same name, &konqueror; will pop up a dialog box warning +you that the file already exists. You can then choose to: + + + +Overwrite the old file with the newly copied one. +The Overwrite All button can be used if you have copied +multiple items. +Cancel the paste operation by pressing the Skip + or Skip All button. +Give the file that is being copied a different name. You can +do this by typing a new name into the text entry box or get &konqueror; to +Propose one. When you have done this press the +Rename button. + + + + + +Selecting Multiple Files + +You sometimes want to delete, copy or move a number of files that are +similar in some way. For example you may wish to move all of the .png graphics +files from one folder to another. &konqueror; makes this easy by letting you +select multiple files based on similarities in their file names. + +Use the Menubar +EditSelection +Select... item or the shortcut +&Ctrl;+. This +brings up a little dialog box in which you enter a filename containing +the wildcard characters *, which matches any number +of characters, and ? which matches a single +character. Press OK and &konqueror; will +highlight all files with matching names. For example; + + + flag*.png will +select all filenames starting with the letters flag and ending +with .png. +memo?.txt will +select memo1.txt and memo9.txt but +not memo99.txt. + + +When you have selected a range of files, you can narrow down the +selection +by uing the Menubar Edit +Unselect... option or &Ctrl;- to specify +which of the selected files should be removed from the selection. + +Use &Ctrl;U +or the Menubar Edit +Unselect All option or just +&LMB; click on a clear area of the view to cancel the +selection. + +You can even invert the selection: that is, deselect all selected +files and select those that were previously unselected. Use the +Menubar EditInvert +Selection option or &Ctrl;* to do this. + +You can also select multiple files and folders by holding the &Ctrl; button while you click on each individual file or folder. This enables you to then move or copy multiple files and folders to a different location at one time by using the same method above. + +A number of useful shortcut keys can be used in list, tree and text +view modes: + + + +Space + +Toggle the current selection. + + + + + +Insert + +Toggle the current selection and move down to the next item. + + + + + +&Ctrl;Up Arrow, +&Ctrl;Down Arrow, +&Ctrl;Home, +&Ctrl;End, +&Ctrl;Page Up, +&Ctrl;Page Down + + +Move the selection, toggling the selection of everything on the way. + + + + + +&Shift;Up Arrow, +&Shift;Down Arrow, +&Shift;Home, +&Shift;End, +&Shift;Page Up, +&Shift;Page Down + + +Deselect everything, then move the selection, selecting everything on +the way. + + + + + +Once you have selected the right files then the normal delete, copy or +move commands will act on all of the selected files at once. + +Depending on your keyboard type and locale, you may find +that the &Ctrl;+, &Ctrl;- and &Ctrl;* shortcuts +only work with the Numeric keypad +, - and +* keys. + + + + +Create New + +When &konqueror; is in File Manager mode, picking +Create New from the Edit +menu or from the context menu you get by &RMB; clicking on a free +area in a folder view gives you a submenu letting you create any +of the following in the current folder: + + + + +FileLink To Application... + +This option is most useful if you want to create an icon that +will open a particular application. It opens a dialog box with three tabbed +pages. The first, General, is where you choose an icon and +the text that will appear with it. The second page, +Permissions, lets you select who can use or modify the +icon. In the Application page you must enter the Command that +will run the application, for example, kedit to start up +the &kedit; text editor. kedit /home/pam/todo.txt would +open the file /home/pam/todo.txt in &kedit;. Advanced +options such as the file types which the application can open are also +available from this page. + +To make the application icon appear on your desktop, create the link in +your ~/Desktop folder (this may be +called something slightly different depending on how &kde; was installed on +your system) or get to the +Create New... sub menu by +right clicking on a free area of the desktop +instead of within &konqueror;'s window. + +If you have a lot of specialized application links and don't want to +clutter up the desktop, then why not create them in your Applications +folder. You can get there in &konqueror; by choosing +Go +Applications. Then create a single icon +on your desktop to open your Applications folder, which is usually in +~/.kde/share/applnk. + +To put an application link icon into the panel, first create it in the +Applications folder then drag the icon onto a clear area of the +panel. + + + + + +FileLink To Location (URL)... +This lets you create an icon to open &konqueror; at a +particular +folder or web page. As with Link To +Application... +you can make the application icon appear on your desktop by creating the link +in +your ~/Desktop folder or going to the +Create +New... sub menu by right clicking on a free area of the +desktop. When you first create it the text shown with the icon will be the full +path or &URL;. You can change it by right clicking on the icon, selecting +Properties... and entering the preferred text in +the +General tab page. + + + +DeviceFloppy Device... +Use this option to create an icon that will mount a floppy disk +and open an instance of &konqueror; showing the disk's contents. To unmount the +disk when you have finished with it right click on +the icon and select Unmount. In practice it doesn't +have to be a floppy disk but can be any hard disk or partition on your system +that is not normally mounted. However, in most cases you will want to create the icon +on +your desktop. + + + +Hard Disk... +This option is similar to Floppy +Device... but for a hard disk drive or + partition. + + + +CD/DVD-ROM Device... +This option is similar to Floppy +Device... but for a CD or DVD +drive. + + + +Folder... +An easy way of creating a new (sub)folder. + + + +Text File... +Use this to create an ordinary, empty, text file. A +dialog box will be opened for you to enter the name of your new +file. + + + +HTML File... +Creates a skeleton HTML source file. When +you +type the new file's name into the dialog box it is probably best to give +it a .html extension to avoid +confusion. + + + +Presentation Document... +Creates a skeleton &koffice; +&kpresenter; document. Give its name a .kpr +extension. + + + +Text Document... +Creates a skeleton KOffice &kword; +document using the standard &kword; style template. Give its name a .kwd extension. + + + +Spread Sheet Document... +Use this to create a new KOffice +&kspread; spreadsheet file, and name it with a .ksp extension. + + + +Illustration Document... +Creates a new KOffice &kontour; +document. Name it with the extension .kil. + + + + + + + +Changing Names and Permissions + +The two easiest ways to change the name of a file or folder is to either +right click on it and select +Rename, or select the file or folder and then press the F2 button. + +To change the name or permissions of a file or folder +right click on its name or icon and select the +Properties... item, or if you have +selected the file or folder, then you can use the Menubar +Edit +Properties option. + +This will bring up the Properties dialog box with two tabbed +pages: + + +General, which gives you some +information about the item and lets you change its name and, for a folder, +the associated icon. +Permissions, which shows you the item's +ownership and access permissions and lets you change the permissions. + + + + +Copy and Rename +If you want to make a copy of an existing file with a different name -- +perhaps as a backup -- in the same folder as the original file, do a normal +Copy then when you Paste +it a dialog box will pop up complaining that the file already exists. +Just type the new name into the dialog's text box and press the +Rename button (or if you are feeling lazy pressing the +Propose button will generate a new name for you). + + + +Super User Mode + +If you are running as a normal user and try to access files outside of +your own home folder you will often be prevented from doing so and get an +error message such as Access Denied. + +To access these files you need to be logged in as the system +administrator, often known as the Super User or root. + +Rather than logging out then in again, you can launch &konqueror; from +the +K Menu in Super User mode by selecting +SystemFile Manager - Super + User Mode +. You will be asked for the root +login password but as long as you can provide that &konqueror; will be started +up with full access privileges to all files on your system. + +Take care. As Super User (root), you have complete control of +your system, and a wrong command can easily do irrevocable damage. +Also, connecting to the internet as root is an extremely bad idea, as it +seriously increases your vulnerability to malicious hacking. + + + + + +Configuring File Associations + + + +&kde; provides many applications which can open many different +types of file. Most of the time, the defaults will work with no +problems, but &konqueror; provides a powerful system to allow you to +change the applications used to open each file type. For more details, +choose the +SettingsConfigure +Konqueror... menu item, select +File Associations in the configuration dialog, +and click on Help. + + + + + +At the Command Line + +Although &konqueror; is a very powerful and flexible +GUI file manager, there are occasions when the experienced +&Linux; / &UNIX; user wants to get down to the basics and work at the text +command line level. + +You can, of course, open an instance of &konsole;, perhaps with +&konqueror;'s Menubar ToolsOpen +Terminal option or with &Ctrl;T. +If you only want to launch a program or view a &URL;, the +ToolsRun Command +(&Alt;F2) option may be +easier. + +ToolsExecute Shell Command... + (&Ctrl; +E) opens a small command line dialog window where +you can enter a shell command such as ps -ax | grep kdeinit +. Note that it does not support full featured terminal control +characters, so applications such as top and +less will not work properly, but it is available immediately +without the delay involved in starting &konsole;. + + +For more complex operations, &konqueror; has another nice feature: the +Menubar WindowShow Terminal +Emulator option, which opens up a terminal window as +a new view within &konqueror;. As long as the link icon is visible at the +bottom right corner of each view, the terminal will follow any folder changes +you make in the normal file manager view. + + + + +Including the terminal emulator + + + + + + + diff --git a/doc/konqueror/index.docbook b/doc/konqueror/index.docbook new file mode 100644 index 000000000..ef4c485d3 --- /dev/null +++ b/doc/konqueror/index.docbook @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + +]> + + + + +The &konqueror; Handbook + + +&Pamela.Roberts; &Pamela.Roberts.mail; + + +The KDE Team +Developers + + + + + + +2000 2002 +Erwan Loisant +Pamela Roberts + + +&FDLNotice; + +2002-09-22 +3.1 + +&konqueror; is &kde;'s advanced File Manager, Web Browser and + Universal Viewing Application. + + + +KDE +Konqueror +Kdebase +File Manager +Browser +Viewer + + + + + +&konqueror-introduction; +&konqueror-basics; +&konqueror-filemanager; +&konqueror-browser; +&konqueror-path-complete; +&konqueror-bookmarks; +&konqueror-sidebar; +&konqueror-save-settings; +&konqueror-plugins; +&konqueror-config; +&konqueror-commands; +&konqueror-faq; +&konqueror-credits; + + + +Installation + +&konqueror; is part of the kdebase package which an essential part of +&kde;. + +For instructions on acquiring &kde; please see http://www.kde.org. + +For further information about &konqueror; you might like to visit +http://www.konqueror.org. + + + + + + + +&documentation.index; + + + diff --git a/doc/konqueror/introduction.docbook b/doc/konqueror/introduction.docbook new file mode 100644 index 000000000..14fc2a6c8 --- /dev/null +++ b/doc/konqueror/introduction.docbook @@ -0,0 +1,64 @@ + + + +&Pamela.Roberts; + + + +2003-10-20 +3.2 + + +Overview + +&konqueror; is an advanced +file manager for the +K Desktop Environment, providing file management functions ranging from simple +cut/copy and paste operations to advanced local and remote network file +browsing. Folder contents can be displayed in a variety of text and icon +view modes, which can include thumbnail +preview images of file contents. File and folder properties can easily be +examined and changed and applications launched with a simple click of the +&LMB;. + +&konqueror; is an HTML 4.01 +compliant web browser with built in support for +JavaScript (ECMA-262), CSS (Cascading Style Sheets) and +bidirectional scripts (such as Arabic and Hebrew). It provides support for the secure +running of &Java; applets, &Netscape; plugins for viewing &Flash;, &RealAudio; and &RealVideo; and SSL for secure +communications. Advanced features include automatic &URL; and form completion, +the ability to import bookmarks from other browsers and tabbed browsing. + + +&konqueror; is also an excellent full featured +FTP client. + +&konqueror; is a universal viewing application, +capable of displaying images and documents without having to launch another +application. It does this by embedding components (&kde; Parts) provided by +other applications; from &kview; for image viewing, &kdvi; for +DVI viewing, &kghostview; for &PostScript; documents and +from the various &koffice; applications for their document types. + + +&konqueror; is a fully customizable application +which anyone can configure to suit their own +needs, from changing the overall style and the sizes of text and icons to +selecting which items appear in the Menubar, changing the number and +positions of the toolbars and even defining new shortcut key combinations. +Different configuration profiles can be +saved for easy recall as needed. + + + + + diff --git a/doc/konqueror/konqorg.png b/doc/konqueror/konqorg.png new file mode 100644 index 000000000..0812aa045 Binary files /dev/null and b/doc/konqueror/konqorg.png differ diff --git a/doc/konqueror/man-kbookmarkmerger.1.docbook b/doc/konqueror/man-kbookmarkmerger.1.docbook new file mode 100644 index 000000000..dab890556 --- /dev/null +++ b/doc/konqueror/man-kbookmarkmerger.1.docbook @@ -0,0 +1,112 @@ + + + +kbookmarkmerger"> +]> + + + + KDE User's Manual + + &Frerich.Raabe; + &Frerich.Raabe.mail; + + February 1st, 2005 + K Desktop Environment + + + + &kbookmarkmerger; + 1 + + + + &kbookmarkmerger; + A program for merging a given set of bookmarks into the + user's list of bookmarks. + + + + + &kbookmarkmerger; + Qt Options + KDE Options + directory + + + + +Description +&kbookmarkmerger; is a program for merging a given set of bookmarks into +the user's set of bookmarks; if the user doesn't have any bookmarks created +yet, a new bookmark list is created and the given bookmarks are inserted into +it. While doing this, &kbookmarkmerger; keeps track of which files were +merged in a previous run already, so no bookmark will get installed to the +user's bookmarks more than once. In case &kde; is running while +&kbookmarkmerger; is executed, the &kde; bookmark subsystem will be informed +of any changes to the user's bookmarks, so that all applications accessing +that information (&ie; &konqueror;) will pick the changes up instantly. + +The traditionally used approach to achieve something like this was to +use carefully crafted skeleton home directories when creating a new user +account, to provide the user with a standard set of bookmarks. The problem +with this approach is that after the user account has been created, no new +bookmarks can be propagated. + +This mechanism is useful for system administrators who want to propagate +a bookmark pointing to a certain document (for instance, important notes about +the system) to all users. Distributors might find it useful as well, for +instance by augmenting the software packages they supply with bookmark files +which &kbookmarkmerger; merges into the user's bookmark list when the +package is installed. That way, documentation shipped with a software package +is easily and visibly accessible right after the package has been +installed. + +The only parameter required by &kbookmarkmerger; is the name of a +directory which shall be scanned for bookmark files. All files in the given +directory will be considered for being merged into the user's setup. The +files in the given directory should be valid XBEL +files. + + + +See Also +&konqueror; manual + + + +Examples +joe@hal9000:~> kbookmarkmerger /usr/local/extra-bookmarks +Merges all bookmark files stored in +/usr/local/extra-bookmarks into joe's list of +bookmarks. + + + +Standards + + + XBEL specification + + + + + +Restrictions +When determining whether a given bookmark file has been merged into the +user's bookmarks already or not, &kbookmarkmerger; merely looks at the +filename of the bookmark file - the contents are not checked at all. This means +that changing a bookmark file which was already merged into a user's bookmarks +will not trigger merging it once again. + +Also note that in case a user modifies a bookmark which was merged into +his setup, the original bookmark file will be left unmodified. + + + +Author +&Frerich.Raabe; &Frerich.Raabe.mail; + + + diff --git a/doc/konqueror/parts.png b/doc/konqueror/parts.png new file mode 100644 index 000000000..1439d0b89 Binary files /dev/null and b/doc/konqueror/parts.png differ diff --git a/doc/konqueror/path-complete.docbook b/doc/konqueror/path-complete.docbook new file mode 100644 index 000000000..a05f0845c --- /dev/null +++ b/doc/konqueror/path-complete.docbook @@ -0,0 +1,82 @@ + + + + +&Pamela.Roberts; + + + +2003-11-05 +3.2 + + + +Automatic Text Completion + +You can get &konqueror; to help you enter a path or &URL; into the +Location Toolbar by enabling one of the Text Completion +features. To do this right + click on a clear part of the Location Toolbar text entry box and select +Text Completion from the pop up menu. This will let you +choose between the following options: + + + + +None +What you get is what you type. + + + +Manual +When you have typed part of a path or &URL;, pressing +&Ctrl;E will complete the entry if it is +possible to do so unambiguously. + + + +Automatic +As you type into the Location Toolbar window &konqueror; will +automatically extend what you type to complete one possible path or &URL;, +highlighting the characters it has added. Continue typing if that's not what +you wanted or press &Enter; to accept it. + + + +Dropdown List +A drop-down window will appear as you type, showing the +possible matches to what you have typed so far. When the path or &URL; that +you want appears in the window double click on it with the &LMB;. +You can also use the +Down Arrow and Up Arrow +keys to select it then press &Enter;. + + + +Short Automatic +This is like Automatic mode except that it only extends +what you have typed as far as the next / symbol in the path +or &URL;. Press &Ctrl;E to accept the +suggestion, &Enter; when the complete path or &URL; is +shown. + + + +You should try out these different modes and pick the one that suits you + best. +The history of recently visited &URL;s that &konqueror; uses for the +Text Completion function can be viewed and edited in the History + page of the Navigation Panel. + + + + diff --git a/doc/konqueror/plugins.docbook b/doc/konqueror/plugins.docbook new file mode 100644 index 000000000..83ca89075 --- /dev/null +++ b/doc/konqueror/plugins.docbook @@ -0,0 +1,162 @@ + + + + +&Pamela.Roberts; + + + +2002-09-22 +3.1 + + + +Plugins + + +&Netscape; Plugins + +Currently, &konqueror; supports &Netscape; 4.x plugins. + +Selecting Settings +Configure Konqueror...Plugins + will give you a dialog box with two tabbed pages; +Scan and Plugins. + +The Scan page controls how &kde; scans for new +&Netscape; plugins, either manually by pressing the Scan for New +Plugins button or automatically each time &kde; starts up. + +The scan is done by looking through the folders listed in the +Scan Folders list for .so files containing plugin code. It examines every +such file to find out which MIME types the plugin +supports. It then creates MIME type definitions for &kde; in +the user's ~/.kde/share/mimelnk +folder to make other applications aware of them. + +The Plugins page shows you the &Netscape; plugins +that &kde; has found, and for each plugin it lists the MIME +types and the filename suffixes it uses to recognize them. + +The dialog box also contains a checkbox +Enable plugins globally which you can use to enable or disable +plugins that can be contained in HTML pages (these can +be considered a security risk). + + + + +&konqueror; Plugins + +The package kdeaddons contains several useful plugins that interact with +&konqueror; in various ways. These are explained briefly below, more detailed +information may be obtained by looking through the Konqueror +Plugins section in the &kde; Help Center. + + + + +Web Page Translation +This uses AltaVista's BabelFish site to translate the current +HTML page to whatever language you want (within reason). It +can be launched with ToolsTranslate +Web Page. + + + +Folder View Filter +This is controlled by +ToolsView +Filter and allows you to choose which types of item +are displayed in a folder. + + + +DOM Tree Viewer +Selecting ToolsShow +DOM Tree opens a new window which displays the +document object model (DOM) of the current HTML +page. + + + +HTML Validator +This is started with +ToolsValidate Web +PageValidate HTML. It +uses the W3C HTML validator to validate the current page, very useful when +creating web pages. + + + +CSS Validator +Started with +ToolsValidate Web +PageValidate CSS, it uses +the W3C CSS validator to validate the current page's Cascading Style +Sheets. + + + +HTML Settings +Select ToolsHTML +Settings to enable or disable a number of HTML +settings without going through the Settings dialog. + + + + +Image Gallery +In File Manager mode, you can select +ToolsCreate Image +Gallery to create an HTML page with +thumbnails of all the images in the current folder. By default the HTML page +is called images.html and the thumbnails are put into a +new thumbs folder. + + + + +User Agent Changer +Select ToolsChange +Browser Identification to get a menu that allows +you to change the User Agent string without going through the Settings + dialog procedure. + + + + +Archive Web Page +Invoked with Tools +Archive Web Page, this tool creates an archive +(.war ) file containing the web page being +viewed including the images. Left click on the +archive file name to view the saved page. + + + + +Navigation Panel Media Player +This is a simple media player, embedded as a tab page in the +Navigation Panel. You can drag songs or videos onto this page to play them. + + + + + + + + + + + diff --git a/doc/konqueror/save-settings.docbook b/doc/konqueror/save-settings.docbook new file mode 100644 index 000000000..9fb248815 --- /dev/null +++ b/doc/konqueror/save-settings.docbook @@ -0,0 +1,92 @@ + + + + +&Pamela.Roberts; + + + +2003-11-06 +3.2 + + +Saving Settings & Profiles + +General Settings +When you close down &konqueror; your current View +menu settings (such as the View Mode, +Use index.html and Show Hidden Files + items) are not automatically saved as the default +options; however, you can have &konqueror; remember these settings by +selecting SettingsSave View +Profile "Web Browsing"... and the current +setting will become the default option to be used the next time +&konqueror; is started. + +But you can also specify different View menu settings +for an individual folder. To do this check the View Properties +Saved in Folder box in the Settings menu, +change the View settings to whatever you want then uncheck +the +View Properties saved in Folder box. Doing this +creates a .directory file in that folder to hold the +folder View settings. Use the +SettingsRemove Folder Properties + option to remove the folder specific +settings (or just delete the .directory file). +One nice use of this feature is if you have a folder full of +pictures. You can set that particular folder to display thumbnails of the +pictures (by choosing Icon View and +PreviewShow Previews + from the View menu) when you open it, while +not displaying images as thumbnails in other folders. + + + +View Profiles +&konqueror; can save a whole set of options as a View +Profile. Some view profiles are part of the standard &konqueror; +installation, such as Web Browsing and File +Management, but you can add your own, too. + +To modify a view profile (say, the Web Browsing +profile), load the profile with +SettingsLoad View +ProfileWeb Browsing , and +change the &konqueror; settings to whatever you want. Now select +SettingsSave View Profile "Web +Browsing".... In the dialog which appears, you can +change the name of the profile, which will create a new profile with that name, +or you can leave the name as it is to modify the current profile. If you select +Save URLs in profile, the current &URL; will be loaded +when you load that view profile. This functions in a similar way to the +Home Page in many web browsers. If you want &konqueror; to start +up with an empty window enter about:blank into the +location bar before saving the profile. + +You can create a desktop icon to start &konqueror; with your new +profile. First create a desktop icon by dragging the &konqueror; icon from the +K menu onto the desktop and selecting Copy +Here. Then right click on the new +icon, select +Properties... and change Program +Name in the Execute tab page to +kfmclient , +MyNewProfile being what you called the new +profile. Then in the General tab page change the name to +something like MyNewProfile and pick a more +suitable icon. + + + + diff --git a/doc/konqueror/shortcut1.png b/doc/konqueror/shortcut1.png new file mode 100644 index 000000000..4d7a77c30 Binary files /dev/null and b/doc/konqueror/shortcut1.png differ diff --git a/doc/konqueror/shortcut2.png b/doc/konqueror/shortcut2.png new file mode 100644 index 000000000..7c461b417 Binary files /dev/null and b/doc/konqueror/shortcut2.png differ diff --git a/doc/konqueror/sidebar.docbook b/doc/konqueror/sidebar.docbook new file mode 100644 index 000000000..9ba4cb923 --- /dev/null +++ b/doc/konqueror/sidebar.docbook @@ -0,0 +1,201 @@ + + + + +&Pamela.Roberts; + + + +2002-09-22 +3.1 + + +The Navigation Panel + +The Navigation Panel appears as a separate view at the left of +&konqueror;'s window. It can be invoked with Window +Show Navigation Panel or +toggled on and off with the F9 key. + + + + +With the Navigation Panel + + + +It contains a number of tabbed pages; left +click on a tab's icon to view that page. Left +clicking on the icon for the visible page will collapse the Navigation Panel +so that only the tab icons are visible. + + + +Bookmarks +This page shows a tree view of your Bookmarks. +Left click on an item to open it in the main view. + + + + +History +This page shows a tree view of your browsing History. +Left clicking on an item will open it in the main +view, or you can open it in a new &konqueror; window by right + clicking and selecting New Window +from the pop up menu. +You can remove an item from the history by right + clicking on it and selecting Remove Entry +. Selecting Clear History... will +clear out the entire history. +The pop up menu you get when you right click +on any entry in the History page also gives you the option of choosing +whether the entire history is sorted by name or by date. +Selecting Preferences... from this pop up +menu brings up the History Sidebar control module. This +can be used to set the maximum size of your history and set a time after which +items are automatically removed. You can also set different fonts for new and +old &URL;s. +The Detailed tooltips checkbox controls how much +information is displayed when you hover the mouse pointer over an item in the +history page. + + + +Home Folder +This page shows a tree view of the subfolders your home +folder. Note that hidden folders (those with names +beginning with a dot) are not shown. +Left click on an item to open it in the +main view, or right click to display a pop up +menu allowing you to open the subfolder in a new window or as a new tab +page of the main view. + + + + +Network +This page is intended to show a tree view of your important +network connections, although local folders can also be included. Again, +you can left click on an item to open it in the +main view or right click to bring up a menu with +a wider range of possibilities. +The folders shown in the Network page are held in +the folder +~/.kde/share/apps/konqsidebartng/virtual_folders/remote/, and you can make +new ones just as you would make any other subfolder. The items within +these folders are held as .desktop files +and can be created with &konqueror;'s Create New +Link to Location (URL)... option. + + + + +Root Folder +The Root Folder tree has the path /, and is the base folder of your system's +local files. If you expand the Root folder you will find +another folder called root. This +belongs to the system administrator or Super User and is her home folder. +You will also find a folder called +home, in which you should be able to +find your own Home folder again. + + + + +Services +This page provides quick access to the following services: + +The Audio CD Browser. +Devices. This shows your hard disc +partitions, floppy and &CD-ROM;. Left click on +a device or partition name to mount it and display its contents in the main +view. A mounted device or partition can be unmounted by right + clicking on the device name and selecting Unmount + from the pop up menu. + +The LAN Browser allows you to browse other +machines connected to your Local Area Network. +The Print System Browser tree gives you quick +access to &kde;'s print manager Kprinter. + + + + +The Navigation Panel configuration can be changed by right + clicking on the empty area below the bottom tab icon or by +left clicking on the Configuration +Button icon (the top icon in the previous screenshot, it may not +be present in your setup). Doing this brings up a menu with the following +options: + + + +Add New +This option lets you add a new tab page to the Navigation +Panel. The new page can contain the Sidebar Media Player + (a &konqueror; Plugin +feature) or a new +Folder tree view. + + + + +Multiple Views +Selecting this option splits the Navigation Panel so that +two tab pages can be seen at once. + + + + +Show Tabs Left +This option lets you choose whether the tab icons are shown at +the left or right of the Navigation Panel. + + + + +Show Configuration Button +Use this option to show or hide the Configuration +Button icon. + + + + + +Right clicking on a tab icon brings up a +menu with the following options: + + + +Set URL +Only available for folder pages, this option lets you +change the &URL; (path) of the folder viewed in that page. + + + +Set Icon +To change the tab icon. + + + +Remove +To remove the tab page from the Navigation Panel. + + + + + + + + diff --git a/doc/konsole/Makefile.am b/doc/konsole/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/konsole/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/konsole/index.docbook b/doc/konsole/index.docbook new file mode 100644 index 000000000..826964fa4 --- /dev/null +++ b/doc/konsole/index.docbook @@ -0,0 +1,1465 @@ + + + + + +]> + + + + +The &konsole; Handbook + +&Jonathan.Singer; &Jonathan.Singer.mail; +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; + + +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; + + + +&Waldo.Bastian; &Waldo.Bastian.mail; + + + + +&Mike.McBride; &Mike.McBride.mail; + + + + + + + + +200020012002 +&Jonathan.Singer; + + +2005 +&Kurt.Hindenburg; + + +&FDLNotice; + +2006-08-16 +1.6.2 + +This document is the user handbook for the &konsole; + application. +&konsole; is an X terminal emulator for &kde;. + + +KDE +konsole +kdebase +command +line + + + + + +Introduction to &konsole; + + +What is a terminal? +&UNIX; operating systems were +originally designed as text-only systems, controlled by keyboard +commands -- what is known as a command-line interface +(CLI). The &X-Window; and &kde; and other projects +have since added the graphical interface you are now using. However, +the underlying CLI system is still there, and is +frequently the easiest, fastest and most powerful way to perform many +tasks. +&konsole; is what is known as an X terminal +emulator, often referred to as a terminal or a shell. It gives you the +equivalent of an old-fashioned text screen on your desktop, but one +which can easily share the screen with your graphical +applications. &Windows; users may be familiar with the +MS-DOS Prompt utility, which has the analogous +function of offering a DOS command-line under +&Windows;. (Although the &UNIX; CLIs offer far more +power and ease of use than does DOS!) + +Explaining the use of the &UNIX; CLI is +beyond the scope of this document, as it would require a lengthy +book. Fortunately, many such books are available in every language in +any good bookstore or library. There are also tutorials available on +the Internet. Enjoy &kde;, but don't be shy about learning to use the +command-line! You will find that even learning just the basics will +make your computer use much more efficient and enjoyable. + + + +What makes &konsole; special? +&konsole;'s +advanced features include simple configuration and the ability to use +multiple terminal shells in a single window, making for a less +cluttered desktop. + +Using &konsole;, a user can open: + +&Linux; console sessions +Shell sessions +Screen sessions +Midnight Commander file manager +sessions +Root console + sessions +Root + Midnight Commander sessions +User created sessions + + +These sessions can be renamed to help you keep track of all your shells, +or signaled (STOP, CONT, +HUP, INT, +TERM, KILL). + +For more control over &konsole;, a user can: + +hide/show the menubar and/or +frame +select the size of a &konsole; window, fonts, color +schemes, and key mapping +change location of the scrollbar or hide the +scrollbar +change location of the tabbar or hide the +tabbar + + +All chosen settings can be made the default for forthcoming sessions by +saving them. + +For those with a deep interest in the taxonomy of free X +terminals, there are two others of this kind: +xterm, the original, written even before X +itself (a month or two), and xvt, a +lightweight xterm clone, on which most +other currently available derivatives (notably +eterm) are based. + +After a decade, &konsole; is the first rewrite from the ground +up. While xterm has definitely been hacked +to death (its README begins with the words +Abandon All Hope, Ye Who Enter Here), &konsole; offers +a fresh start using contemporary technologies and understanding of +X. + + + + + +Use of &konsole; + + +Startup + +When &konsole; is started, an application (typically a &UNIX; +shell) runs in the window. Simply type at the prompt. + + +&konsole; Screen + + + + + +&konsole; Screen + +&konsole; with 4 +terminal sessions open. + + +A Tip of the Day window may also appear on +startup, offering hints on the use of &konsole;. If you do not wish to +receive tips, uncheck the Show tips on startup +box. + + + +History + +As lines 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 (provided the History option is on). + +In addition, &konsole; mimics the FreeBSD console when +scroll lock is pressed. When scroll lock is on, +ordinary in- and output from the shell is suspended, and you can +scroll through the history with Page Up, Page +Down, and Up Arrow and Down +Arrow. + +&konsole;'s history can be configured via +SettingsHistory... + + + +&konsole; provides a number of history related actions located in the +Edit menu. + + + + +Find in History... + + +Find Next + + +Find Previous + + +Save History As... + + +Clear History + + +Clear All Histories + + + +In &konsole;, references to history are to +the text that is displayed in &konsole;'s window. +The shell that is running in &konsole; (e.g. bash) also +has a history which is unrelated to &konsole;'s +history. + + + + +Sessions +If you often have to log into remote machines, or always run a similar set of +terminal applications, you can use &konsole;'s Session feature +along with &kde;'s session management to automate a lot of this for you. +Let's take the following example: +You often have open an ssh session to the machine +administration ready for generic administration +tasks. +You may have noticed the New Session button on &konsole;'s tab +bar contains a menu if you click and hold on it, and you can choose new session +types here. We are going to add new entries to this menu. + + +Click on the menu entry SettingsConfigure &konsole;... + +Choose the Session tab. + + +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 lower part of the panel, configure this +session's appearance. You can have a different font, colour scheme, +and $TERM type for each session. + +Press the Save +Session... button. A dialog will ask you to confirm the filename. + + +Press OK. + + + +You should now be able to press and hold the New Session button +on the tab bar, and select your new session type from the list. A new shell +session will open within the &konsole; window, with the result of your executed +command. In our example, you will be at an ssh +passphrase prompt, and when you provide your passphrase, you will be logged +into the remote machine. +You can avoid this step also, by using +ssh-agent, but that is a topic for another goodie. +Perhaps you want to remotely tail your http error logs on a +webserver, you could use a commandline something like +ssh +webserver tail + +/var/log/httpd-error.log. + +You can use this to execute local commands as well. Try creating a +session where the command is tail /var/log/messages. + In this case, exiting the +running application will close the shell session as well. + +One really nice use of this feature is if you find you always have the +same set of open sessions, &kde; can open them all for you automatically +when you start a new &kde; session. Simply have them open as you like +when you exit &kde;, and they will be saved with your &kde; session, and +restored just like any other application when you restart &kde;. + +You can assign +shortcuts +to any session. + + + + + +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 + +The items that appear in the menu when the &RMB; +is pressed depend on whether the menubar is visible. + +Menubar is visible: +Set Selection End, +Copy, +Paste, +Send Signal, +Detach Session, +Rename Session..., +Bookmarks +and Close Session +menu items. + +Menubar is hidden: +Show Menubar, +Set Selection End, +Copy, +Paste, +Send Signal, +New Session, +Detach Session, +Rename Session..., +Bookmarks, +Settings +and Close Session +menu items. + +In a mouse-aware application, press the &Shift; key along with the +&RMB; to get the pop-up menu. + + +Pressing the &Ctrl; key and &RMB; brings up the +Session menu. + + + + + + + + + +Menu Bar + +The menubar is at the top of the &konsole; window. +The menubar can be activated and deactivated by the +&Alt; key. +SettingsHide +Menubar allows the menubar to be hidden. When +the menubar is hidden, Show Menubar can be +reached by right clicking in the +window or by &Alt;&Ctrl;M +, which is the default shortcut for activating the menubar. +The menubar can also be toggled by assigning it a shortcut. + + + +<guimenu>Session</guimenu> Menu + + + +SessionNew +Shell +Open a new session with a terminal +shell. &Alt;&Ctrl;N + can also be used, as described in more detail below. + + + +SessionNew +Window +Open a new &konsole; window. + + + +SessionNew Linux +Console +Open a new session emulating a text-only &Linux; +system. +See the file README.linux.console in +the &konsole; source package for detailed information on how the &Linux; +console differs from a typical &UNIX; console. If this doesn't mean anything +to you, you almost certainly don't need to worry about it. + + + + +SessionNew Midnight +Commander +Open a new session with the + Midnight +Commander file browser. +This menu entry will only be visible if Midnight Commander +(mc) is installed on your system. + + + + + + +Session +New Root Midnight Commander + + +Open a new session with the Midnight +Commander file browser, as the root user. + +After being prompted for the root password, the # +prompt appears under the browser window, indicating that the user is +working with root +privileges. Again, working as root is frequently necessary but care +should be taken to avoid accidental damage. + +This menu entry will only be visible if Midnight Commander +(mc) is installed on your system. + + + + + + +Session +New Root Shell + + +Open a new session with a terminal shell, as the +root user. + +After being prompted for the root password, the # +prompt appears, indicating that the user is working with root privileges. This is frequently +necessary for installing new software and other system maintenance, but +care should be taken to avoid accidental damage. + + + + +SessionNew +Screen Session +Open a new session with the + Screen virtual terminal manager. +See man +for more information. +This menu entry will only be visible if Screen +(screen) is installed on your system. + + + + +Session +New Shell at Bookmark +Start a new terminal shell, in a folder +chosen from the bookmark list. + + + +Session +Print Screen... +Print the current screen. + + + + +Session +Close Session +Close the current session. + + + + +Session +Quit +Quit &konsole;, closing all sessions and any +applications launched from them. + + + + +You can also open a new session with a key shortcut. By default, +&Alt;&Ctrl;N +is used. You can also define your own key shortcuts through the +Settings +Configure Shortcuts... menu command. + +The list of available sessions will reflect what programs are +installed along with any user defined sessions. +The session list will be alphabetized for quick viewing. + +Finally, note that the session types can be modified, and new +types created, by using the configuration dialog, reached from the +Settings +Configure Konsole... +menu entry. + + + +<guimenu>Edit</guimenu> Menu + + + +Edit +Copy +Copy the selected text to the clipboard. + + + + +&Shift;Insert +EditPaste + +Paste text from the clipboard at the cursor +location. + + + +Edit +Send Signal +Send Signal - Send the specified signal to the shell +process, or other process, that was launched when the new session was +started.Currently available signals are: + + + + + +STOP +to stop process + + +CONT +continue if stopped + + +HUP +hangup detected on controlling terminal, or death of controlling +process + + +INT +interrupt from keyboard + + +TERM +termination signal + + +KILL +kill signal + + +USR1 +user signal 1 + + +USR2 +user signal 2 + + + + + +Refer to your system manual pages for further details by giving the +command man . + + + + +&Alt;&Ctrl;U +EditZModem Upload... +Send a file via ZModem. + + + +EditClear Terminal +Clear all text from the session window. + + + + +EditReset & Clear Terminal +Reset and clear the session window. + + + + +EditFind +in History... +Find a word or string of text in the current +history. Options allow case sensitive or backwards searches, and the use of regular +expressions in searches. Press the Edit button to use the &kde; +graphical editor to create a regular expression. + + + + +EditFind +Next +Move to the next instance of the +text for which you are searching. + + + + +EditFind +Previous +Move to the previous instance of the +text for which you are searching. + + + + +EditSave +History As... +Save the current history as a text + file. + + + + +EditClear + History + +Clear the history for the current + session. + + + +EditClear All + Histories + +Clear the history +for all sessions. + + + + + + +<guimenu>View</guimenu> Menu + + + +ViewDetach +Session +Open the current session in a +separate window. The name of the session is +displayed on the titlebar of the new window. + + + + +&Alt;&Ctrl;S +ViewRename +Session... +Open a dialog box allowing you to change +the name of the current session. The name is displayed +on the session tab. &Alt;&Ctrl;S + can also be used. + + + +ViewMonitor for +Activity +Flag the current session so it will show +an alert if activity occurs. An icon of a lit light bulb will +appear in the session's tab. Use this to alert you if something +happens while you are working in another session. The time before an alert can be +modified in the &konsole; preferences. + + + +ViewMonitor for +Silence +Flag the current session so it will show an alert +if no activity occurs for 10 seconds. An icon of a dark light bulb will +appear in the session's tab. Use this to alert you if a task stops +while you are working in another session. The time before an alert can be +modified in the &konsole; preferences. + + + +ViewSend +Input to All Sessions +Flag the current session so any commands entered +into it will be sent to all sessions. The session will have a small +icon in its tab to remind you to be careful of what you enter! +rm -rf *, +for instance, is probably not a good idea. + + + + + +&Ctrl;&Shift;Left +ViewMove +Session Left +Move the tab of the current session one tab to the +left. + + + + +&Ctrl;&Shift;Right +ViewMove +Session Right +Move the tab of the current session one tab to the +right. +&Shift; Left and &Shift; Right can be also +be used to move between sessions. + + + +View +Session icons... +At the bottom of the menu is a list of the available +sessions. Selecting one makes that session active.You can also use + the &Shift;Left/&Shift;Right keys to +cycle through the available sessions. + + + + + + + +<guimenu>Bookmarks</guimenu> Menu + + + + +BookmarksAdd Bookmark +Add the current location to the bookmark list. + + + +BookmarksEdit Bookmarks +Edit the bookmark list. + + + +BookmarksNew Bookmark Folder... +Add a new folder to the bookmark list. + + + + +The bookmark list is displayed at the bottom of the menu. Select a bookmark to change to +that location. + +You can use the bookmark editor to manually add URLs +like ssh://user@host or telnet://host to open remote connections. + + + + + + + +<guimenu>Settings</guimenu> Menu + + + + +SettingsHide +Menubar +Hide the menubar. + + + +Settings +Tab Bar +Control visibility/location of tabbar: +Hide, Top, or +Bottom. + + + +Settings +Scrollbar +Control visibility/location of scrollbar: +Hide, Left, or +Right. + + + + +&Ctrl;&Shift;F +Settings +Full Screen Mode +Toggle window between full-screen and normal +size. + + + +Settings +Bell +Set the bell: +System Bell, +System Notification, +Visible Bell, or +None. + + + + +Settings +Font +Set font size: +Enlarge Font or +Shrink Font. + +Use the Select... option to pick any +combination of font, size and style. + + + + +Settings +Encoding +Select character encoding. + + + +Settings +Keyboard +Choose desired keymapping. +The list of these keymappings is taken from +$KDEDIR/share/apps/konsole/*.keytab. The file +$KDEDIR/share/apps/konsole/README.KeyTab +describes the *.keytab format in more detail. +Add to or modify these files to match your needs. The default keytab is taken from +$KDEDIR/share/apps/konsole/README.default.Keytab. + + + + +Settings +Schema +Set colors of text and background. +The list is taken from +$KDEDIR/share/apps/konsole/*.schema. The file +$KDEDIR/share/apps/konsole/README.Schema +describes the *.schema format in more detail. +Add to or modify these files to match your needs. You can also create custom +schemas through the preferences dialog at Settings +Configure &konsole;.... + + + + +Settings +Size +Set size of text area (given in columns x +rows). + + + +Settings +History... +Open a dialog +where you can configure the history. The +Enable check box toggles saving of lines that have +scrolled off the top of the window. You can enter the Number +of lines to remember in the text field, or use the spinner +buttons to increase or decrease the number in steps of 100 lines. The +Defaults button will reset the history to 1000 +lines. Selecting Set Unlimited will cause all history to be saved. +Press OK to save your changes, or +Cancel to close the dialog without saving your +settings. + + + +SettingsSave +as Default +Save the current settings as the new +default. + + + +SettingsSave Sessions Profile... +Save the current set of sessions under a name you choose. +The profile can then be used by starting &konsole; from the command-line with the +--profile and the name of the profile. + + + + +SettingsConfigure +Notifications... +Customize notifications for &konsole;. + + + + +SettingsConfigure +Shortcuts... +Customize keyboard shortcuts for &konsole; commands. + + + + +SettingsConfigure +&konsole;... +Open the &kcontrolcenter; module, allowing +many additional changes to &konsole;'s interface and behavior, including the creation +of custom schemas and modification of the available sessions. + + + + + + + +<guimenu>Help</guimenu> Menu + + + +HelpKonsole +Handbook +Open the table of contents of this +document. + + + +Help +Tip of the Day +Display a helpful tip about the use of &konsole;. +Check the Show on start box to display a tip +each time &konsole; is started. + + +HelpReport +Bug... +Submit a bug report or a feature request for +&konsole;. + + + +HelpAbout +Konsole +Information about &konsole;'s +author + + + +HelpAbout +KDE +Information about the &kde; +project + + + + + + + + +Tab Bar + +The tabbar allows multiple terminal sessions to be attached to a single &konsole; window. + + +Tabbar Image + + + + + +Tabbar Image + +&konsole; with 4 terminal sessions open with the tabbar on the bottom. + + + +The SettingsTab +Bar menu item allows the tabbar to be moved to +the Top or Bottom. +The tabbar can also be hidden by selecting Hide. + +On the left side of the tabbar is a button which allows for a multitude of actions. + +Click on the button to start a new +standard session. +Clicking and holding on the button will popup +a list of sessions to select. +Right-clicking on the button (or any empty +space on the tabbar) will popup up a menu to set certain options: + + Tab Bar: + Hide, + Top, + Bottom. + + + Tab Options: + Text & Icons, + Text Only, + Icons Only. + + + Dynamic Hide + will hide the tabbar when there is only one session opened. + + + + Auto Resize Tabs + will automatically resize the tabs to the width of the tabbar. + + + + + + +On the right side of the tabbar is a button that closes +the current session. This button will be disabled when there +is only one session running. + +Right-clicking on any tab will popup another menu: + +Detach Session +Rename Session... +Monitor for Activity +Monitor for Silence +Send Input to All Sessions +Select Tab Color... +Switch to Tab... +Close Session + + + + + +Command-line Options + +When &konsole; is started from the command-line, various options +can be specified to modify its behavior. + + + + +List the various options. + + + + command +Execute +command instead of the normal shell. +Any arguments after command will be passed to +command, not &konsole;. + + + + + file +Start &konsole; using a specified .keytab +file to customize key bindings. + + + + +List all of the available keytabs. + + + + + +Start with a login shell environment. +What that does varies depending on your system, but generally it +means that files such as ~/.profile or +~/.bash_profile will be read. (If that doesn't mean +anything to you, don't worry about it, but keep in the back of your mind +for when you realize you need it.) + + + + name +Set the name that appears in the +titlebar. + + + + +Prevent &konsole; from closing when an +exit +command is issued in the only session window. + + + + +Start &konsole; without a + frame. + + + + +Disable the saving of lines + that scroll off the top of the window. + + + + +Start &konsole; with +the menubar hidden. + + + + +Disable the resizing + of the terminal window. + + + + +Start &konsole; with +the scrollbar hidden. + + + + +Start &konsole; +with the tabbar hidden. + + + + +Start &konsole; without Xft antialiasing. +Antialiasing of a small font may be difficult to read. + + + + file +Start &konsole; using a saved set of sessions. + + + + +List all of the available profiles. + + + + + name | file +Start &konsole; using schema 'name' or specified in 'file' to customize appearance. + + + + +List all of the available schemata. + + + + + +Enable extended &DCOP; &Qt; functions. + + + + + title +Set the window title. + + + + terminal +Sets the environment variable TERM to the specified +value. Read man + for more information on TERM. + + + + type +Start a session of the given type + rather than the default. + + + + +List all of the available session types. + + + + + CCxLL +Start a terminal window of CC Columns and LL +lines. + + + + dir +Open with +dir as the working folder. + + + + + +Examples: +% konsole 90x25 + +Starts a &konsole; window with 90 columns and 25 rows, with no +history + +% konsole echo_args Hello, thanks for using &konsole;! + +Starts a &konsole; window with the text printed 'Hello, thanks for using &konsole;!' + +The echo_args is a simple Bash script: +#!/bin/bash +echo $* + + + +&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 + + + + + + +&DCOP; + +For an introduction to +&DCOP; and using dcop please look at +the User Guide entry on &DCOP;. + + + + + + + +Credits and Copyright + +As of &kde; 3.4, &konsole; is maintained by &Kurt.Hindenburg; &Kurt.Hindenburg.mail; + +Previously, &konsole; was maintained by &Waldo.Bastian; &Waldo.Bastian.mail; + +The application &konsole; Copyright © 1997-2005 +&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; + +Originally converted to DocBook SGML by +&Mike.McBride; and &Lauri.Watts; + + + +&underFDL; +&underGPL; + + + +&konsole; on non-&Linux; platforms + +Information on building &konsole; on platforms other than &Linux; +is available in the README.ports file in the +&konsole; source package. It provides a list of experts for certain +platforms (Tru64, &Solaris;, OpenBSD) and requests volunteers from other +&UNIX; platforms. + +For more infomation please visit these websites: + +&kde; on +FreeBSD +&kde; on &Solaris; + + + + +&documentation.index; + + + + + + diff --git a/doc/konsole/konsole.png b/doc/konsole/konsole.png new file mode 100644 index 000000000..8ec9a1b4e Binary files /dev/null and b/doc/konsole/konsole.png differ diff --git a/doc/konsole/tabbar.png b/doc/konsole/tabbar.png new file mode 100644 index 000000000..fb0fb0dbe Binary files /dev/null and b/doc/konsole/tabbar.png differ diff --git a/doc/kpager/Makefile.am b/doc/kpager/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kpager/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kpager/index.docbook b/doc/kpager/index.docbook new file mode 100644 index 000000000..e2779abf5 --- /dev/null +++ b/doc/kpager/index.docbook @@ -0,0 +1,381 @@ + + + + + +]> + + + + +The &kpager; Handbook + + +&Dirk.Doerflinger; &Dirk.Doerflinger.mail; + + +&Antonio.Larrosa.Jimenez; &Antonio.Larrosa.Jimenez.mail; + + + + +&Matthias.Elter; +&Matthias.Elter.mail; + + + + +&Matthias.Ettrich; &Matthias.Ettrich.mail; + + + + + + + + +2000 +&Dirk.Doerflinger; + + +&FDLNotice; + +2001-01-28 +0.02.00 + + + +&kpager; gives you a thumbnail view of all virtual desktops. + + + + +KDE +pager +kpager +desktop +overview + + + + + +Introduction + +&kpager; gives you a thumbnail sketch of all your desktops. It is a handy +tool to let you see, resize or close windows on any desktop and move windows +around within or between desktops. + + + + + +Using &kpager; + + +Here's a screenshot of &kpager; + + + + + + Screenshot + + + + + +More &kpager; features + +&kpager; can show all virtual desktops and the applications within them. +It +can be used to chose an application or even to move applications within virtual +desktops or to others. + + + + + +Command Reference + + +The main &kpager; window + + +Using the mouse + +In &kpager; you can activate applications by clicking them with the +left button. + +The middle button of the mouse can be used for +dragging applications within &kpager;. Applications can either be moved within a +virtual desktop or to another one. + +Clicking the right mouse button anywhere in +&kpager; will open a context menu. + + + + +The Context Menu + +The context menu depends on where the right +mouse button is clicked: If it is clicked on the empty background of &kpager;, +it +only has two items: Configure KPager and +Quit. Otherwise, if clicked on a window, there are +also the name and the icon of the application, and +Minimize, Maximize, +To Desktop and Close are +displayed. See below for a detailed description of the menu items. + + + + +Maximize + +Maximizes the application window to the whole +desktop. This item only appears if right clicked on an application +window. + + + + +Minimize + +Iconifies the application. This item only appears if +right clicked on an application window. + + + + +To Desktop + +Sends the application window to the chosen virtual +desktop. This item only appears if right clicked on an application +window. + + + + +Close + +Closes the clicked application. This item only appears +if right clicked on an application window. + + + + +Configure Pager + +Opens the settings +dialog. + + + + +Quit + +Quits &kpager;. + + + + + + + + +The Settings Dialog + + +Here's a screenshot of the settings dialog + + + + + + Screenshot + + + + +In the settings dialog you will find five check boxes and two groups of +radio buttons. + + + +Enable Window Dragging +If this box is checked, you can drag windows inside of &kpager; +with the &MMB;. +Windows can be dragged over the desktop or even to another +desktop. + + + +Show Name +If this box is checked, the names of the desktops are shown in +the main view of &kpager;. + + + +Show Number +If this box is checked, the numbers of the desktops are shown in +the main view of &kpager;. If it is checked together with the Show +Name box, the name is displayed with ordinals, e.g. +1. Desktop. + + + +Show Background +If this box is checked, the wallpaper of each desktop - if set - +will be shown as backgrounds in &kpager;, too. + + + +Show Windows +If this box is checked, the applications on the desktops are +shown in &kpager; as small views. Otherwise, &kpager; will remain empty, just +for +choosing the virtual desktops. + + + +Type of Window +This group of radio buttons sets the kind of view for the +application window views. Plain will show just empty +rectangles with the proportions of the application window, +Icon will show them with their standard icon and +Pixmap with a small view of the contents of the application +window. Note that using the pixmap mode is only recommended for very fast +machines. + + + +Layout +In this group the layout of the &kpager; main view can be +set. Classical will show &kpager; in a 2xn grid like pager +applications in some other window managers, Horizontal will +show the virtual desktops in a horizontal view and Vertical +in a vertical row, which may perfectly fit on the side of the +desktop. + + + + + + + + +Questions and Answers + + + + +Why could I need &kpager;? + +&kpager; can be used as an alternative to the pager applet in the +panel. It has the advantage of being resizeable and within this able to show +icon or pixmap views of the running applications, move the windows across +desktops and run outside of the panel. + + + +How can I change the behavior of &kpager;? + +Clicking the right mouse button +anywhere within &kpager; lets you chose Configure from the +context menu for displaying the settings +dialog + + + + +Windows are transparent by default, how do I turn this off? + + +Currently, you cannot turn that option off within the config dialog, but +you can do it manually like this: + +Open the file $KDEHOME/share/config/kpagerrc with any +text editor like &kedit; or vi. If you have no +rights to write that file, you may need to do it as root or contact your system +administrator. In this file you will have to add a new key with the name +windowTransparentMode with a number as value. Values +are: + + +0 - No transparent windows at all. +1 - Only maximized windows are transparent. +2 - all windows are transparent (default). + + + + + + + + + + +Credits and License + + +&kpager; + + + +Program copyright 2000 Antonio Larrosa larrosa@kde.org + + + +Documentation copyright 2000 by Dirk Doerflinger +ddoerflinger@web.de + + +&underFDL; +&underGPL; + + + + +Installation + + +How to obtain &kpager; + +&install.intro.documentation; + + + + +Requirements + +As &kpager; is part of the &package; package, you will just need an +installation of the main &kde; packages. + + + + +Compilation and Installation + +&install.compile.documentation; + + + + + +&documentation.index; + + + + + diff --git a/doc/kpager/screenshot.png b/doc/kpager/screenshot.png new file mode 100644 index 000000000..ef895c128 Binary files /dev/null and b/doc/kpager/screenshot.png differ diff --git a/doc/kpager/settings.png b/doc/kpager/settings.png new file mode 100644 index 000000000..6aab9773f Binary files /dev/null and b/doc/kpager/settings.png differ diff --git a/doc/ksplashml/Makefile.am b/doc/ksplashml/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/ksplashml/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/ksplashml/index.docbook b/doc/ksplashml/index.docbook new file mode 100644 index 000000000..b64c2816c --- /dev/null +++ b/doc/ksplashml/index.docbook @@ -0,0 +1,1354 @@ + + + + + +]> + + + + +The &ksplash; Handbook + + + +&Teemu.Rytilahti; &Teemu.Rytilahti.mail; + + + +&Brian.C.Ledbetter; &Brian.C.Ledbetter.mail; + + + +&Ravikiran.Rajagopal; &Ravikiran.Rajagopal.mail; + + + + + + + +2003 +Teemu Rytilahti + + +2003-04 +Ravikiran Rajagopal + +&FDLNotice; + +2003-01-10 +1.01.00 + + + +&ksplash; is a nice splash screen that shows the progress of an +application that is loading. + + + +KDE +kdebase +ksplash +ksplashml +splashscreen +eye candy + + + + + +Introduction + +&ksplash; is a nice splash screen that shows the progress of an +application that is loading. Please report any problems or feature +requests to the &kde; mailing lists. The principal features of +&ksplash;: + + +Themeable +Uses plugins for complete customizability +Can be used by any application that uses DCOP + + + +This handbook will show you how to create themes for use with plugins +that are already available. If none of the plugins available satisfy +your tastes, you can learn how to customize the appearance of +&ksplash; completely by writing a plugin in C++. + + + + +Using themes + +To use themes from KDE-Look, extract them to +~/.kde/share/apps/ksplash/Themes/ for a single user, or +to +$KDEDIR/share/apps/ksplash/Themes/ +to make them available to all users of your system. + +You can also use the Splash Screen module under +Appearance in the &kde; control center to do this +automatically. + + +Using the &kcontrol; Module + +This module allows you to install, test and remove &ksplash; +themes. + +Down the side of the module is a list of currently available +&ksplash; themes. As you select one, a preview will display in the main +part of the window. When you have selected the one you wish to use, press +OK or Apply. Press +Cancel to exit the module without making changes, and +Defaults to restore the system default splash +screen. + +To install new modules, press Add..., and +find the theme on your computer. You do not have to unpack theme files, you +can safely select the compressed theme file. Installing a theme does not +make it the theme in use until you select it in the list and press either +OK or Apply. + +Although you can see a preview of the splash screen, you may like to +see how it looks in real use, for instance to see what the animation looks +like. You can test themes by selecting them in the list and clicking the +Test button. + +You can also remove themes you no longer wish to use, by selecting +them and pressing the Remove button. Note that your +user account may not have the right to remove themes installed system-wide. +It is also recommended you do not uninstall the Default +splash screen. + + + + + + +How to make themes for &ksplash; + +General +Making your own themes for &ksplash; is easy. After you have +finished your themes you can post them on the KDE-Look so that others can use +it. + + +Identifying your theme + +Let us create a theme called MyCoolTheme. For +the theme to be recognized by &ksplash;, it should be stored in a +folder called MyCoolTheme +under ~/.kde/apps/ksplash/Themes/. It should +have a file called Theme.rc, containing the +settings of the theme. You can specify large numbers of special things +to theme, change the plugin engine to use, and so on. You do not have +to use all the settings available; usually, the settings have an +acceptable default value. The basic syntax for entries in the +Theme.rc file is [option] = +[value] You can find the definitions of the various options +in the following sections. + + +Simple <filename>Theme.rc</filename> file + +[KSplash Theme: MyCoolTheme] +Name = MyCoolTheme +Description = A nice theme using XpLike engine +Version = 1.0 +Author = Real Name <realmail@mail.com> +## Use the XpLike engine for this theme. +Engine = XpLike +Show Icon = false +Welcome Text = Loading KDE + + + +After specifying the name, the description and the author of the +theme, you should first choose a theme engine (also known as a +plugin). Then, you can customize various features of the theme engine +by assigning key-value pairs as in the example file above. + + +Ensure that the name of the directory that contains the theme files +(~/.kde/apps/ksplash/Themes/MyCoolTheme +in this example) and the identifier ([KSplash Theme: +MyCoolTheme] in this example) of the theme in the +Theme.rc file are identical. Otherwise, &ksplash; will not +recognize the theme. + + + + + +Background files + +When &ksplash; starts, it tries to find a background image for +your current screen resolution, if the theme engine uses one. The +background image file should be named in the following format: +Background-WWWxHHH.png. + +For example, you might use a file called +Background-1024x768. If the background image for +your screen resolution cannot be found, it tries to resize the +original Background.png or the file specified in +Theme.rc to suit the current resolution. Resizing +on-the-fly will certainly take some time, so you should provide +background images for at least the following sizes: 1280x1024, 1024x768 +and 800x600. + + + + +Options for Theme Engines + + +Default Theme + +Default Theme Options + + + +Name +Argument +Explanation + + + +Always Show Progress +[true/false] +Indicates whether loading progress should be shown. Default is +true. + + +Label Foreground +[color] +Determines what color to use for the statusbar text. Default is #FFFFFF (white). + + + +Icons Flashing +[true/false] +Indicates whether icons should flash. Default is true. + + + +
+ + + +Standard Theme + +Standard Theme Options + + + +Name +Argument +Explanation + + + +Statusbar Position +[top/bottom] +Toggles the position of the statusbar on the screen. Default is +bottom. + + +Statusbar Visible +[true/false] +Indicates whether the statusbar should be shown. Default is true. + + +Progress Visible +[true/false] +Indicates whether loading progress should be shown. Default is +true. + + + +Statusbar Font +[fontname] +The font used in statusbar. Default is Helvetica. + + +Statusbar Font Size +[size] +The font size for the statusbar. Default is 16. + + +Statusbar Font Bold +[true/false] +Indicates whether the statusbar font should be bold. Default is +true. + + +Statusbar Font Italic +[true/false] +Indicates whether the statusbar font should be italic. Default is +false. + + + +Statusbar Foreground +[color] +The foreground color of statusbar. Default is white. + + +Statusbar Background +[color] +The background color of statusbar. Default is black. + + +Statusbar Icon +[true/false] +Indicates whether the statusbar should have an icon. + + +Icons Visible +[true/false] +Indicates whether icons should be visible. Default is true. + + +Icons Jumping +[true/false] +Indicates whether icons should be jumping. Default is true. + + +Icon Position +[0-3,10-13] +Position where the icons are shown. Default is bottom-left. + + +Splash Screen +[name] +Changes the splash screen image that is shown. + + + +
+ + + +Redmond theme + +Redmond theme options + + + +Name +Argument +Explanation + + + +Background Image +[filename] +User defined background image to use. + + +User Icon +[Iconname] +Name of standard icon to show for user. Default is +go. + + +Welcome Text +[text] +Text shown in splash screen. Default is "Welcome". + + +Username Text +[text] +Text shown instead of user's real name. + + + +Welcome Text Position +[x,y] +Position on the screen where the Welcome Text is shown. + + +Username Text Position +[x,y] +Position on the screen where the username is shown. + + +Action Text Position +[x,y] +Position on the screen where the current action is shown. + + +Icon Position +[x,y] +Position on the screen where the user icon is shown. + + + +Show Welcome Text +[true/false] +Toggles showing of welcome text. Default is true. + + +Show Welcome Shadow +[true/false] +Toggles showing of welcome text's shadow. Default is true. + + +Show Username +[true/false] +Toggles showing of username. Default is true. + + +Show Action +[true/false] +Toggles showing of action currently being performed. Default is +true. + + +Show Icon +[true/false] +Indicates whether icon should be shown. Default is true + + +Use KDM User Icon +[true/false] +Show user's login icon. Default is true. + + + +
+ + + +MacX Theme + +MacX Theme Options + + + +Name +Argument +Explanation + + +Icon Size Minimum +[size] +Assign the minimum size for icons. Default is 16. + + +Icon Size Maximum +[size] +Assign the maximum size for icons. Default is 64. + + +Optimized Icon Rendering +[true/false] +Optimize icon rendering. Default is true. + + +Progress Bar Visible +[true/false] +Default is true. + + +Progress Bar Position +[top/bottom] +Toggles whether statusbar should be in bottom or top. Default is +bottom. + + +Icons Jumping +[true/false] +Indicates whether icons should be jumping. Default is false. + + + +
+ + + +MacClassic Theme + +MacClassic Theme Options + + + +Name +Argument +Explanation + + +Icon Position +[0-3,10-13] +Position of the icons on the screen. Default is bottom left. + + +Icons Jumping +[true/false] +Indicates whether icons should be jumping. Default is false. + + +Icons Visible +[true/false] +Indicates whether icons should be visible. Default is true. + + +Splash Screen +[name] +Changes the splash screen image that is shown. + + + +
+ + + +2k theme + +2k theme options + + + +Name +Argument +Explanation + + +Title Background Color +[color] +The background color of title. Default is dark blue. + + +Title Foreground Color +[color] +The foreground color of title. Default is white. + + +Status Text Color +[color] +The color of status texts. Default is the same as Title Background +Color. + + +Rotator Color 1 +[color] +Defines the color of rotator 1. Default is dark blue. + + +Rotator Color 2 +[color] +Defines the color of rotator 2. Default is cyan. + + +Rotator Speed +[value] +Defines the speed of the rotator. Default is 30. + + +Window Title +[text] +Specifies the title text of the window. + + +Logo File +[filename] +Defines the logo used. + + + +
+ + + + + +Using &ksplash; From Within Your Own Application + + In this chapter, we describe a simple method for using +&ksplash; as the splash screen for your &kde; application. If you do +not develop applications for &kde;, you can skip this chapter. + + +Basic Requirements + + Your &kde; application must be &DCOP;-aware. &DCOP; is the &kde; +technology used to communicate between applications. If you use the +standard &kde; application +framework, this is taken care of automatically. For +information about &DCOP; and related &kde; technologies, please visit +the &kde; developers' +corner. + + + +Starting &ksplash; + +Before your application starts its computation intensive work, +or before it starts loading plugins, &etc;, invoke &ksplash; as +follows: + + +DCOPClient *c = kapp->dcopClient(); +QString error; +QCString KSplashName; +int pid = 0; +QStringList args; +args << "--theme=MyCoolTheme" << "--managed"; +if (kapp->startServiceByDesktopName("ksplash", args, &error, +&KSplashName, &pid)) +{ + KMessageBox::sorry(0, error, "Unable to invoke KSplash"); + // Some error processing here. +} + + +We will assume that there is only one instance of &ksplash; +running. Other cases are slightly more complex. Please see the &DCOP; +documentation for further details. + + + +Showing messages + +Before you show any messages, you need to set up the number of +steps you will show. For example, the &kde; startup procedure uses 7 +steps. + + + QByteArray data; + QDataStream arg(data,IO_WriteOnly); + arg << someNumber; + if (!(c->send(KSplashName, "KSplashIface", "setStartupItemCount(int)", +data)) + // Some error processing here. + + +Whenever you want to display a message with or without an icon, use + + + arg << QString("iconName") << QString("programName") << +QString("Some description"); + if (!(c->send(KSplashName, "KSplashIface", +"programStarted(QString,QString,QString)", data)) + { + // Some error processing here. + } + + + Each time you call programStarted, the +steps completed is incremented. When your program has finished its +startup, do the following to make the splash screen go away: + + + if (!(c->send(KSplashName, "KSplashIface", "startupComplete()", data)) + { + // Some error processing here. + } + + +That's it! You don't need anything more to take advantage of all +that &ksplash; has to offer you. + + + + + + + + +Writing new &ksplash; plugins + +Writing new &ksplash; plugins is not difficult. In this chapter, we will +write +a simple plugin that will emulate the splash screen of a well known operating +system. This +tutorial assumes that you know the basics of C++, and a little bit of KDE/Qt +programming. + + +Basic Requirements + +We will create a plugin called 2k. The plugin name is used in +various +places, and is important that you consistently use it so that the plugin is +recognized by +&ksplash;. &ksplash; plugins are actually dynamically loadable libraries with +the following +naming convention: + + +The library should be named as +ksplash+lowercasethemename. For our +theme, it will be ksplash2k. +It should have a corresponding desktop file which is named as +ksplash+lowercasethemename.desktop. For our theme, it will +be +ksplash2k.desktop. +Finally, the object that is returned by the library should be a class +which is named +Theme+themename. For our example, it will be +Theme2k. + +Do not worry about it if you don't understand all of the above. We will +consider each +of those points in detail later. The other very important detail is that the +plugin class +should be derived from ThemeEngine. + + + +Building the skeleton framework +We will use the &kde; application framework which will take care of +building the plugin +and will provide us with platform independence without any work on our part. To +do that, +make sure you have the kdesdk package installed. Run the +command +kapptemplate to produce an application named "2k". It will +create a +toplevel folder which contains generic files such as AUTHORS, &etc;. We are most +interested +in the subfolder called 2k. Go into that +subfolder +and delete all the files there. Now we have the skeleton we require. + + +The next step is to create a .desktop file which, when +installed, will +tell &ksplash; that our plugin is available. Consistent with the naming +conventions laid out +in the preceding section, +create a file called +ksplash2k.desktop in that folder. It should contain the +following lines: + + + +[Desktop Entry] +Encoding=UTF-8 +Type=Service +Comment=KSplash Plugin +Name=KSplash2k +ServiceTypes=KSplash/Plugin +X-KDE-Library=ksplash2k +X-KSplash-Default=true +X-KSplash-PluginName=2k +X-KSplash-ObjectName=Theme2k + + + +The Encoding, Type, +Comment and +ServiceTypes are the same for all plugins. The plugin name +and the library +name follow the conventions noted earlier. The entry +X-KSplash-Default takes +a boolean value which determines whether it is shown in the control panel +configuration +module by default. Except for some very rare cases, it should be +true. + + + +Declaration of plugin class +Now that we have the preliminary work done, let us get into the actual fun +part - creating +a class that will provide the behavior we want. While we are free to make this +class do +almost anything we want it to do, there are a few restrictions. + +Plugin classes must inherit the ThemeEngine +class. +Plugin classes must be named according to the rule: +Theme+PluginName. +Plugin classes should provide a static +function called names +that returns a list of names by which it can be invoked. +If the plugin can be configured in the control center module, it +should provide a +ThemeEngineConfig-based class for the +configuration. +Plugin classes must override at least one of the virtual +functions slotSetText, +slotSetPixmap, slotUpdateProgress and +slotUpdateSteps to make it usable. +The constructor should take the form +ThemeEngine( QWidget *parent, const char *name, const QStringList +&args ) +so that it can be used with +KGenericFactory. + +The last requirement may seem complicated, but, as we will see later, by +adding a single +line to your source files, you can usually ignore it. + + +Code for the header file +Given the constaints, we will now see what the header file +theme2k.h looks +like this: + +Listing for <filename>theme2k.h</filename> + +#ifndef __THEME2K_H__ +#define __THEME2K_H__ + +#include <qlabel.h> +#include <qwidget.h> + +#include <kdialogbase.h> +#include <kpixmap.h> +#include <ksplash/themeengine.h> + +class RotWidget; + +class Cfg2k: public ThemeEngineConfig +{ + Q_OBJECT +public: + Cfg2k( KConfig * ); +}; + +class ObjKsTheme; +class Theme2k: public ThemeEngine +{ + Q_OBJECT +public: + Theme2k( QWidget *, const char *, const QStringList& ); + + inline const QString name() + { + return( QString("KSplash2k") ); + } + inline const KDialogBase *config( KConfig *kc ) + { + return new Cfg2k( kc ); + } + static QStringList names() + { + QStringList Names; + Names << "KSplash2k"; + Names << "ks2k"; + Names << "2k"; + Names << "2000"; + return( Names ); + }; + +public slots: + inline void slotSetText( const QString& s ) + { + if( mText && mText->text() != s ) mText->setText( s ); + }; + +private: + void initUi(); + void readSettings(); + + QLabel *mText; + RotWidget *mRotator; + QColor mTBgColor, mTFgColor, mRotColor1, mRotColor2, mStatusColor; + int mRotSpeed; + QString mWndTitle, mLogoFile; +}; + +#endif + + +Let us analyze the listing above. The Theme2k class +satisfies +the naming conventions, and is inherited from +ThemeEngine. It provides +a Theme2k::names(), and has a constructor that takes +the required +parameters: Theme2k( QWidget *, const char *, const QStringList& +); +and also provides a simple Theme2k::slotSetText() +method. For the moment, +do not worry about the RotWidget class. It is a small +widget that provides +some eye candy for the user. Our plugin is very simple and does not display any +icons or show +a progressbar. If you would like to display icons, override the +slotSetPixmap +function. Similar functions exist for setting the progressbar range +(slotUpdateSteps) +and incrementing(slotUpdateProgress) the current step. + + + +Implementation of the plugin +We will examine only the relevant parts of the implementation. For a +listing of the whole +implementation, please see the appendix. The first thing we will do is to get +the library +requirement out of the way: + +Library requirement + +K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> ); + + + The macro K_EXPORT_COMPONENT_FACTORY is declared in +kgenericfactory.h. Onwards to the constructor! +Since this is a very simple plugin, the constructor is pretty +straightforward. + +Plugin constructor + +Theme2k::Theme2k( QWidget *parent, const char *name, const QStringList &args + ) + :ThemeEngine( parent, name, args ) +{ + readSettings(); + initUi(); +} + + +The method readSettings() illustrates the +proper way to obtain your theme settings. (You do want people to use your +plugins +in their themes, don't you?) + +Obtaining theme settings + +void Theme2k::readSettings() +{ + if( !mTheme ) + return; + + KConfig *cfg = mTheme->themeConfig(); + if( !cfg ) + return; + + cfg->setGroup( QString("KSplash Theme: %1").arg(mTheme->theme()) ); + + QColor DefaultTBgColor( Qt::darkBlue ); + QColor DefaultTFgColor( Qt::white ); + + mTBgColor = cfg->readColorEntry( "Title Background Color", +&DefaultTBgColor ); + mTFgColor = cfg->readColorEntry( "Title Foreground Color", +&DefaultTFgColor ); + mStatusColor = cfg->readColorEntry("Status Text Color", &mTBgColor ); + + QColor DefaultRot1( Qt::darkBlue ); + QColor DefaultRot2( Qt::cyan ); + mRotColor1 = cfg->readColorEntry( "Rotator Color 1", &DefaultRot1 ); + mRotColor2 = cfg->readColorEntry( "Rotator Color 2", &DefaultRot2 ); + + mRotSpeed = cfg->readNumEntry( "Rotator Speed", 30 ); + mWndTitle = cfg->readEntry( "Window Title", i18n("Please wait...") ); + mLogoFile = cfg->readEntry( "Logo File", QString::null ); +} + + +Since we like our users, we provide sensible defaults for parameters that +are not +present in the theme file. Note that we should always set our group to "KSplash +Theme: themename" +to remain compatible with future theme specifications. The +initUI() method is +not very interesting, as it merely builds up the widgets. Please see the +appendix for details. + + + +Compiling the plugin +Since we decided to use the &kde; framework for compiling the plugin, we +need to create a +Makefile.am. It should look like this: + +Listing of <filename>Makefile.am</filename> + +INCLUDES = $(all_includes) + +kde_module_LTLIBRARIES = ksplash2k.la + +ksplash2k_la_SOURCES = theme2k.cpp rotwidget.cpp +ksplash2k_la_LDFLAGS = $(all_libraries) $(KDE_RPATH) +ksplash2k_la_LIBADD = $(LIB_KDEUI) -lksplashthemes + +METASOURCES = AUTO + +noinst_HEADERS = theme2k.h rotwidget.h + +servicesdir = $(kde_servicesdir) +services_DATA = ksplash2k.desktop + +themedir = $(kde_datadir)/ksplash/Themes/2k +theme_DATA = Theme.rc Preview.png + + +For more information on writing Makefile.am files for +&kde;, please see +the &kde; developers' +website. +The only thing of note is that we provide a default theme based on this plugin, +and provide +a preview image for it. As a matter of courtesy to your users, you should +provide an example +Theme.rc file illustrating the use of the various +options. + + + + +Questions and Answers + +&reporting.bugs; +&updating.documentation; + + + + +I can't find any themes that work in &ksplash;. Why is that? + + +You probably don't have the correct plugins for the theme. The +plugins are in the kde-artwork package. Download +and install it, and try then again. + + + + +What is file Theme.rc and how do I make one? + + + +Theme.rc is the file where you can specify a +theme's settings. For more information, take a look at How to make themes for &ksplash;. + + + + + + + +Credits and License + +&ksplash; + +Program Copyright © 2003 &Ravikiran.Rajagopal; +&Ravikiran.Rajagopal.mail; + + +Contributors +&Brian.C.Ledbetter; &Brian.C.Ledbetter.mail; + + + +Documentation Copyright © 2003 &Teemu.Rytilahti; +&Teemu.Rytilahti.mail; + +&underFDL; +&underGPL; + + + + +Installation + + +Requirements + +In order to successfully use &ksplash;, you need &kde; version 3.2 or +higher. Some themes may require specific plugins. If a theme does not +work, please contact the theme author to find out where to obtain the +appropriate plugin. + + + + +Compilation and Installation + +&install.compile.documentation; + + + + +Source code + +Listing of <filename>theme2k.cpp</filename> + +#include <qlabel.h> +#include <qwidget.h> + +#include <kapplication.h> +#include <kconfig.h> +#include <kdebug.h> +#include <kdialogbase.h> +#include <kgenericfactory.h> +#include <kglobalsettings.h> +#include <klocale.h> +#include <ksplash/objkstheme.h> +#include <kstandarddirs.h> + +#include "rotwidget.h" +#include "theme2k.h" +#include "theme2k.moc" + +K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> ); + +Cfg2k::Cfg2k( KConfig * ) +{} + +Theme2k::Theme2k( QWidget *parent, const char *name, const QStringList &args + ) + :ThemeEngine( parent, name, args ) +{ + readSettings(); + initUi(); +} + +void Theme2k::initUi() +{ + QVBox *vbox = new QVBox( this ); + vbox->setFrameShape( QFrame::WinPanel ); + vbox->setFrameShadow( QFrame::Raised ); + + QHBox *labelBox = new QHBox( vbox ); + labelBox->setPalette( mTBgColor ); + labelBox->setMargin( 1 ); + QLabel *lbl = new QLabel( mWndTitle, labelBox ); + lbl->setFont( QFont( "Arial", 12, QFont::Bold ) ); + lbl->setPaletteForegroundColor( mTFgColor ); + + QLabel *logo = new QLabel( vbox ); + logo->setPalette( Qt::white ); + + QString px( locate( "appdata", mTheme->themeDir() + +(mLogoFile.isNull()?QString("/Logo.png"):mLogoFile) ) ); + if (px.isNull()) + px = locate("appdata","Themes/Default/splash_top.png"); + if( !px.isNull() ) + { + QPixmap pix( px ); + logo->setPixmap( pix ); + } + else + { + logo->setText( "<B>KDE</B>2000" ); + logo->setAlignment( AlignCenter|AlignVCenter ); + } + + mRotator = new RotWidget( vbox, mRotColor1, mRotColor2, mRotSpeed ); + + QHBox *hbox = new QHBox( vbox ); + labelBox->setSpacing( 4 ); + labelBox->setMargin( 4 ); + + mText = new QLabel( hbox ); + mText->setPaletteForegroundColor( mStatusColor ); + mText->setPaletteBackgroundColor( mTFgColor ); + mText->setText( mWndTitle ); + mText->setFixedHeight( 48 ); + + setFixedSize( vbox->sizeHint() ); + QRect rect(KGlobalSettings::splashScreenDesktopGeometry()); + move( rect.x() + (rect.width() - size().width())/2, + rect.y() + (rect.height() - size().height())/2 ); +} + +void Theme2k::readSettings() +{ + if( !mTheme ) + return; + + KConfig *cfg = mTheme->themeConfig(); + if( !cfg ) + return; + + cfg->setGroup( QString("KSplash Theme: %1").arg(mTheme->theme()) ); + + QColor DefaultTBgColor( Qt::darkBlue ); + QColor DefaultTFgColor( Qt::white ); + + mTBgColor = cfg->readColorEntry( "Title Background Color", +&DefaultTBgColor ); + mTFgColor = cfg->readColorEntry( "Title Foreground Color", +&DefaultTFgColor ); + mStatusColor = cfg->readColorEntry("Status Text Color", &mTBgColor ); + + QColor DefaultRot1( Qt::darkBlue ); + QColor DefaultRot2( Qt::cyan ); + mRotColor1 = cfg->readColorEntry( "Rotator Color 1", &DefaultRot1 ); + mRotColor2 = cfg->readColorEntry( "Rotator Color 2", &DefaultRot2 ); + + mRotSpeed = cfg->readNumEntry( "Rotator Speed", 30 ); + mWndTitle = cfg->readEntry( "Window Title", i18n("Please wait...") ); + mLogoFile = cfg->readEntry( "Logo File", QString::null ); +} + + + +Listing of <filename>rotwidget.h</filename> + +#ifndef __ROTWIDGET_H__ +#define __ROTWIDGET_H__ + +#include <qlabel.h> +#include <qtimer.h> +#include <qwidget.h> + +#include <kdialogbase.h> +#include <kpixmap.h> + +/** + * @short Display a rotating-gradient widget. + */ +class RotWidget: public QWidget +{ + Q_OBJECT +public: + RotWidget( QWidget *, const QColor&, const QColor&, int ); + ~RotWidget(); + +private slots: + void stepEvent(); + +protected: + void preparePixmap( int ); + void paintEvent( QPaintEvent * ); + void resizeEvent( QResizeEvent * ); + + QColor m_color1, m_color2; + int m_step, m_speed; + QTimer *m_stepTimer; + + QList<KPixmap> m_stepPixmap; +}; + +#endif + + + +Listing of <filename>rotwidget.cpp</filename> + +#include <kdebug.h> +#include <kdialogbase.h> +#include <kpixmapeffect.h> + +#include <qlabel.h> +#include <qpainter.h> +#include <qwidget.h> + +#include "rotwidget.h" +#include "rotwidget.moc" + +RotWidget::RotWidget( QWidget *parent, const QColor& c1, const QColor& +c2, int sp ) + :QWidget(parent), m_color1(c1), m_color2(c2), m_step(0), m_speed(sp) +{ + if( (m_speed <= 0) || (m_speed > 20) ) + m_speed = 1; + setFixedHeight( 6 ); + + for( int i = 0; i <= width(); i++ ) + preparePixmap( i ); + + m_stepTimer = new QTimer( this ); + connect(m_stepTimer, SIGNAL(timeout()), this, SLOT(stepEvent())); + m_stepTimer->start( 50 ); +} + +RotWidget::~RotWidget() +{ +} + +void RotWidget::stepEvent() +{ + // This is inefficient as we create too many pixmaps, optimize later. + m_step += m_speed; + if( m_step > width() ) + m_step = 0; + repaint( true ); +} + +// Todo: Optimize drawing. +void RotWidget::paintEvent( QPaintEvent *pe ) +{ + QPainter p; + p.begin( this ); + + QRect r = pe->rect(); + + if( m_stepPixmap.at( m_step ) ) + bitBlt( this, r.x(), r.y(), m_stepPixmap.at( m_step ), r.x(), r.y(), +r.width(), r.height() ); + else + p.fillRect( rect(), Qt::black ); + p.end(); +} + +void RotWidget::resizeEvent( QResizeEvent *re ) +{ + m_stepPixmap.clear(); + for( int i = 0; i <= re->size().width(); i++ ) + preparePixmap( i ); +} + +void RotWidget::preparePixmap( int step ) +{ + if( step < 0 ) + return; + + // Explicitly draw our first pixmap. The rest we will bitBlt() from here. + if( step == 0 ) + { + KPixmap tmp; tmp.resize( size().width() / 2, size().height() ); + KPixmap tmp2(tmp); + KPixmapEffect::gradient( tmp, m_color1, m_color2, +KPixmapEffect::HorizontalGradient ); + KPixmapEffect::gradient( tmp2, m_color2, m_color1, +KPixmapEffect::HorizontalGradient ); + KPixmap *px = new KPixmap( size() ); + QPainter p; + p.begin( px ); + p.drawPixmap( 0, 0, tmp ); + p.drawPixmap( size().width()/2, 0, tmp2 ); + p.end(); + m_stepPixmap.append( px ); + } + else if( m_stepPixmap.at( step-1 ) ) + { + QPixmap *prev = m_stepPixmap.at( step-1 ); + QPixmap next; next.resize( size() ); + // convert + // prev = "[------------]" + // to + // next = "------------][" + bitBlt( &next, 0, 0, prev, 1, 0, prev->width()-1, prev->height() +); + bitBlt( &next, width()-1, 0, prev, 0, 0, 1, prev->height() ); + KPixmap *n = new KPixmap( next ); + m_stepPixmap.append( n ); + } +} + + + + +&documentation.index; + + + diff --git a/doc/ksysguard/Makefile.am b/doc/ksysguard/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/ksysguard/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/ksysguard/index.docbook b/doc/ksysguard/index.docbook new file mode 100644 index 000000000..cfeb64098 --- /dev/null +++ b/doc/ksysguard/index.docbook @@ -0,0 +1,496 @@ + + + + + +]> + + + +The &ksysguard; Handbook + + + +&Chris.Schlaeger;&Chris.Schlaeger.mail; + + + +&Chris.Schlaeger;&Chris.Schlaeger.mail; + + + + +&Tobias.Koenig;&Tobias.Koenig.mail; + + + + + + + + +2000 +&Chris.Schlaeger; + + +&FDLNotice; + +2000-12-14 +1.00.00 + +&ksysguard; is a network enabled task manager and system monitor +application, with the additional functionality of +top. + + +KDE +KSysGuard +process monitor +top +ps + + + + +Introduction + +&ksysguard; is the &kde; Task Manager and Performance Monitor. It features + +a +client/server architecture that allows monitoring of local as well as remote +hosts. The graphical front end uses so-called sensors to retrieve the +information it displays. A sensor can return simple values or more complex +information like tables. For each type of information, one or more displays are +provided. Displays are organized in work sheets that can be saved and loaded +independently from each other. So, &ksysguard; is not only a simple task manager +but also a very powerful tool to control large server farms. + + + + + +Using &ksysguard; + + +Getting started + +&ksysguard; can be started from the start menu, using the entry +KDE System +Guard in the Systems menu. Alternatively, you +can start it by typing ksysguard in a terminal. + +The &ksysguard; main window consists of a menu bar, an optional tool bar +and +status bar, the sensor browser and the work space. When first started you see +your local machine listed as localhost in the sensor +browser and 2 pages in the work space area. This is the default setup. + +This default setup is sufficient enough for an inexperienced user to do +some system management. An experienced user or even a system administrator of a +large computer lab has different needs. To address a wide range of users, +&ksysguard; +is highly flexible. + + + +The Sensor Browser + +The sensor browser displays the registered hosts and their sensors in a +tree form. Click on the tree handles to open or close a branch. Each sensor +monitors a certain system value. + + +Connecting to other hosts + +To connect to a new host use Connect Hosts +from the File menu. A dialog box will appear and allows you +to +enter the name of the host you want to connect to. Below the name you can choose +the connection method. The default is ssh, the secure +shell. Alternatively the rsh, the remote shell, or +the daemon mode can be used. Click OK to +establish the connection. Shortly afterwards the new host will appear in the +sensor browser and you can browse the list of sensors. + +To establish a connection, a program called +ksysguardd, that can be started in the following +two modes, must be installed on the new host. + + + +daemon mode + +You can start ksysguardd at boot time in +Daemon mode by adding -d as the +argument. In this case, you have to select daemon mode at the connection +dialog of ksysguard. +A disadvantage of this connection type is that you won't be able to kill or +renice a process with the Process Controller and +the data exchange over network won't be encrypted. + + + +shell mode + +In this mode ksysguardd is started at +connecting time by ksysguard. To make that possible, +its location needs to be included in your PATH. +Unfortunately the ssh does not source your .profile file, +so your regular PATH setting will not be available. +Instead it uses a default PATH like +/bin:/usr/bin. +Since it is very likely that &kde; is not installed in these folders you need +to create or update a file in your home folder. The file is called +environment and needs to be in a hidden folder called +.ssh. See the manual page for +ssh for more details. The file needs to contain a +line similar to: + + +PATH=/bin:/usr/bin:/opt/kde/bin + + +assuming that ksysguardd can be found under +/opt/kde/bin/ksysguardd. + +When using ssh you should make sure that +you have your identity.pub installed on the remote machine +and the host key of the remote machine is already registered on your machine. +The easiest way to check this is to type ssh in a shell. If you are greeted by +ksysguardd you can type quit +and everything is in order. + + + + +For experts: ksysguardd is a +very small program that is only linked against the libc. So it can +also be used on machines that do not have a full blown &kde; +installed, such as servers. If you choose the custom command option in +the host connector you need to specify the complete command to start +ksysguardd. + + + + +Disconnecting hosts + +To disconnect from a host, select the host in the sensor browser and +choose Disconnect Host from the +File menu. If you still have sensors in use, the display +frames will be grayed and the displays won't update any longer. + + + + +The Work Space + +The work space is organized as work sheets. Select +New from the File menu to create a +new work sheet. A dialog will appear where you can set the name, the +dimension and the update interval of the work sheet. To remove a work sheet +again, select +Close from the File menu. Any +modifications will be saved to the work sheet file. If a work sheet has +never been saved, you will be asked for a file name. Work sheets consist of +cells +organized as a grid. + +Each cell can be filled with a display for one or more sensors. You can +fill a cell by dragging a sensor from the sensor browser and dropping it over +the cell. If there is more than one type of display available for that type +of sensor, a popup menu will appear. You can then select which display you +prefer +to use. Certain types of displays can display more than one sensor. Add more +sensors to a display by dragging them over from the sensor browser and dropping +them over the already existing display. + +Work sheets can be configured by clicking Configure Worksheet + at the Edit menu. In the appearing dialog +you can set the dimension and the update interval. This update interval is +used by all displays of the worksheet, which has the use update +interval of worksheet set in its timer configuration dialog. + +The entry Configure Style of the +Settings menu gives you the possibility to configure the +global style attributes and apply them to the current active worksheet. + +Displays can be configured by clicking with the right mouse button on +them. A popup menu appear where you can select whether you want to change the +properties of that display, remove it from the work sheet, change its update +interval type and value or pause and restart its updating. + + +Signal Plotter + +The signal plotter prints samples of one or more sensors over time. If, +several sensors are displayed, the values are piled in different colors. If +the display is large enough a grid will be displayed to show the range of the +plotted samples. By default, the automatic range mode is active so the minimum +and maximum values will be set automatically. Sometimes you want fixed +minimum and maximum values. In that case, you can deactivate automatic range +mode and set the values in the properties dialog. + + + +Multimeter + +The multimeter displays the sensor values as a digital meter. In the +properties dialog you can specify a lower and upper limit. If the range +is exceeded, the display is colored in the alarm color. + + + +Process Controller + +The Process Controller gives you a list of processes on your +system. The list can be sorted by each column. Just press the left +mouse button at the head of the column. + +The list shows the following information about each process. Please note +that not all properties are available on every operating system. + + + +Name +The name of the executable that started the process. + + + + +PID +The Process ID. A unique number for each +process. + + + +PPID +The Process ID of the process parent. + + + + +UID +The ID of the user that started the +process. + + + + +GID +The ID of the group the process +belongs to. + + + + +Status +The process status. + + + +User% + +The processor load of the process in user space (in percent). + + + + +System% + +The processor load of the process in system space (in percent). + + + + +Nice +The scheduling priority. + + + +VmSize +The total amount of virtual memory used by the process +(in kBytes). + + + +VmRss +The total amount of physical memory used by the process +(in kBytes). + + + +Login +The login name of the user that started the process. + + + + +Command +The complete start command of the process. + + + +Underneath the table you find four buttons which will be described now +from left to right. + + +The <guibutton>Tree</guibutton> View + +The tree view has been designed to show the relationships between the +running processes. A process that is started by another process is called the +child of that process. A tree is an elegant way to show this parent-child +relationship. The init process is the ancestor of all +processes. + +If you are not interested in the children of a particular process you can +click on the little box to the left of the parent and the subtree will +collapse. Another click on that box will unfold the subtree again. + + + + +The Process Filter + +The Process Filter can be used to reduce the number of processes displayed +in the table. You can filter out processes you are not interested in. Currently +you can display all processes, system processes only, user processes only or +your processes only. + + + + +The <guibutton>Refresh</guibutton> Button + +This button can be used to force an immediate update of the process +list. + + + + +The <guibutton>Kill</guibutton> Button + +If you have selected one or more processes you can press the kill button +to kill them. A so called SIGKIL is sent to the processes + +which causes them to +terminate immediately. If these applications still have unsaved data this data +will be lost. So use this button with care. + + + + + +BarGraph + +The bargraph displays the sensor values as dancing bars. In the +properties dialog you can specify minimum and maximum values of range and +a lower and upper limit. If the range is exceeded, the display is +colored in the alarm color. + + + +Sensor Logger + +The sensor logger does not display any values, but logs them in +a file with additional date and time information. For each sensor +you can specify a lower and upper limit in the properties dialog. +If the range is exceeded, the entry of the sensor table is colored in +the alarm color and a knotify event is sent. + + + +Log File + +The log file monitor displays the content of a file ⪚ +/var/log/messages. +In the properties dialog, you can compose a list of regular expressions that +will be compared with the content of the file. If one of the expressions match, +a knotify +event will be sent. + + + + +List View + +The listview displays the data of some sensors in the form of a +table. + + + + + + +Configuring <application>ksysguardd</application> + +The graphical front-end is available on any platform that &kde; runs +on. The back-end is at the moment available on the following flavors of +&UNIX;: + + + +&Linux; 2.x + For ksysguardd to work it +is necessary to compile the &Linux; Kernel +with the /proc Filesystem enabled. This is the default +setting and most &Linux; Distributions have it already. + + +FreeBSD +The ksysguardd program +needs to be owned by the kmem group and needs to have the setgid +bit set. + + +&Solaris; +To be written + + + +Support for other platforms is in progress. Your help is greatly +appreciated. + + + +Credits and Licenses + +&ksysguard; is currently developed and maintained by Chris Schläger +cs@kde.org. &ksysguard; is a rewrite of +KTop, the KDE 1.x task manager. Several other people +have worked on KTop: + + + A. Sanda alex@darkstar.ping.at + Ralf Mueller ralf@bj-ig.de + Bernd Johannes Wuebben +wuebben@math.cornell.edu + Nicolas Leclercq +nicknet@planete.net + + +The porting to other platforms than &Linux; was done by: + + + FreeBSD: Hans Petter Bieker +zerium@traad.lavvu.no + + +&underFDL; +&underGPL; + + + + + + diff --git a/doc/kwrite/Makefile.am b/doc/kwrite/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kwrite/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kwrite/index.docbook b/doc/kwrite/index.docbook new file mode 100644 index 000000000..b1762a201 --- /dev/null +++ b/doc/kwrite/index.docbook @@ -0,0 +1,2952 @@ + + + + + +]> + + + + +The &kwrite; Handbook + +&Thad.McGinnis; &Thad.McGinnis.mail; +&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; +&Anders.Lund; &Anders.Lund.mail; + +&Christoph.Cullmann; &Christoph.Cullmann.mail; + + + + +&Lauri.Watts; &Lauri.Watts.mail; + + + + + + + + +20002001 +&Thad.McGinnis; + + +2005 +&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; +&Anders.Lund; &Anders.Lund.mail; + +&FDLNotice; + +2005-12-27 +4.5.0 + + +&kwrite; is a text editor for &kde; + + + +KDE +KWrite +text +editor + + + + + +Introduction + + +&kwrite; is more than a text editor for the &kde; Desktop. It is meant +to be a programmer's editor, and could be considered as at least a +partial alternative to more powerful editors. It may be best used in +conjunction with &konqueror; for source file browsing for different +languages. &kwrite; also works very well as a simple text editor. One +of &kwrite;'s main features is the colorized syntax, customized for many +different programming languages such as: C/C++, &Java;, Python, Perl, +Bash, Modula 2, &HTML;, and Ada. + + + + + +Some Fundamentals + + +&kwrite; is very simple to use. Anyone that has used a text editor +should have no problems. + + + +Drag and Drop + + +&kwrite; uses the &kde; Drag and Drop protocol. Files may be dragged and +dropped onto &kwrite; from the Desktop, &konqueror; or some remote &FTP; +site opened in one of &konqueror;'s windows. + + + + +Command Line Options + + +Though &kwrite; may most often be started from the &kde; program menu, or +a desktop icon, it can also be opened at the command line prompt of a +terminal window. There are a few useful options that are available when +doing this. + + + +Specify a File + +By specifying the path and name of a particular file the user can +have &kwrite; open (or create) that file immediately upon startup. This +option might look something like the following: + + +% kwrite + + + + + + +Specify a file on the internet + +The above-mentioned method could even be used to open files on the +internet (if the user has an active connection at the time.) An example of +this might look like the following: + + +% kwrite + + + + + + + +Other Command Line Options + +The following command line help options are available + + + +kwrite + +This lists the most basic options available at the command +line. + + +kwrite + +This lists the options available for changing the way +&kwrite; interacts with &Qt;. + + +kwrite + +This lists the options available for changing the way +&kwrite; interacts with &kde;. + + +kwrite + +This lists all of the command line options. + + +kwrite + +Lists &kwrite;'s authors in the terminal +window + + +kwrite + +Lists version information for &Qt;, &kde;, and &kwrite;. Also +available through kwrite + + + +kwrite + +Causes &kwrite; to read the document content from STDIN. This +is similar to the common option used in many command line +programs, and allows you to pipe command output into &kwrite;. + + +kwrite + encoding +&URL; +Causes &kwrite; to use the specified encoding for the document. + + + +kwrite + line +&URL; +Navigate to the specified line after opening the document. + + + +kwrite + column +&URL; +Navigate to the specified column after opening the document. + + + + + + + + +Shortcuts + +Many of the shortcuts are configurable by way of the Settings menu. By default &kwrite; honors the +following shortcuts: + + + + +Insert + Toggle between Insert and Overwrite mode. When in insert mode the +editor will add any typed characters to the text while pushing along any data to +the right of the text cursor. Overwrite mode causes the entry of each character +to eliminate the character immediately to the right of the text +cursor. + + +Left +Arrow +Move the cursor one character to the left + + +Right +Arrow + Move the cursor one character to the right + + +Up +Arrow + Move the cursor up one line + + +Down +Arrow + Move the cursor down one line + + +Page +Up + Move the cursor up one page + + +&Alt;Page +Up +Previous Bookmark + + +Page +Down +Move the cursor down one page + + +&Alt;Page +Down +Next Bookmark + + +Backspace + Delete the character to the left of the cursor + + +Home + Move the cursor to the beginning of the line + + +End + Move the cursor to the end of the line + + +Delete +Delete the character to the right of the cursor (or any selected +text) + + +&Shift;Left +Arrow + Mark text one character to the left + + +&Shift;Right +Arrow + Mark text one character to the right + + +F1 + Help + + +&Shift;F1 +What's this? + + +F3 + Find again + + +&Shift;F3 + Find Previous + + +&Ctrl;A +Select All + + +&Ctrl;&Shift;A +Deselect + + +&Ctrl;&Shift;B +Block Selection Mode + + +&Ctrl;B +Set a Bookmark + + +&Ctrl;C + Copy the marked text to the clipboard. + + +&Ctrl;D + Comment + + +&Ctrl;&Shift;D + Uncomment + + +&Ctrl;F + Find + + +&Ctrl;G + Go to line... + + +&Ctrl;I + Indent selection + + +&Ctrl;&Shift;I + Unindent selection + + +&Ctrl;J +Join Lines + + +&Ctrl;N + New document + + +&Ctrl;O +Open a document + + +&Ctrl;P +Print + + +&Ctrl;Q +Quit - close active copy of editor + + +&Ctrl;R + Replace + + +&Ctrl;S +Invokes the Save command. + + +&Ctrl;U +Uppercase + + +&Ctrl;&Shift;U +Lowercase + + +&Alt;&Ctrl;U +Capitalize + + +&Ctrl;V + Paste the clipboard text into line edit. + + +&Ctrl;W +Close + + +&Ctrl;X +Delete the marked text and copy it to the clipboard. + + + +&Ctrl;Z +Undo + + +&Ctrl;&Shift;Z +Redo + + +&Ctrl;- +Collapse One Local Level + + +&Ctrl;&Shift;- +Collapse Toplevel + + +&Ctrl;+ +Expand One Local Level + + +&Ctrl;&Shift;+ +Expand Toplevel + + +F5 + Reload + + +F6 +Show/Hide Icon Border + + +F7 + Switch to Command Line + + +F9 + Show/Hide Folding Markers + + +F10 + Dynamic Word Wrap + + +F11 + Show/Hide Line Numbers + + + + + + + + +The Menu Entries + + +The <guimenu>File</guimenu> Menu + + + + + + + +&Ctrl;N + +File +New + + +This starts a new Document in the editor. If there is a current +document with unsaved changes the user is given a chance to save it. + + + + + + + + +&Ctrl;O + +File +Open... + + + + + +Displays a standard &kde; Open File +dialog. Use the file view to select the file you want to open, and +click on Open to open it. You can find more +information about the &kde; Open File dialog in +the &kde; User Guide. + + + + + + + +File +Open Recent + + + + +This is a shortcut to open recently saved documents. Clicking on this +item opens a list to the side of the menu with several of the most +recently saved files. Clicking on a specific file will open it in +&kwrite; - if the file still resides at the same +location. + + + + + + + + +&Ctrl;S + +File +Save + + + + +This saves the current document. If there has already been a save of +the document then this will overwrite the previously saved file without +asking for the user's consent. If it is the first save of a new +document the save as dialog (described below) will be invoked. + + + + + + + +File +Save As... + + + + +This allows a document to be saved with a new file name. This is done by +means of the file dialog box described above in the Open section of this help file. + + + + + + + + +F5 + +File +Reload + + + + +Reloads the active file from disk. This command is useful if another program or +process has changed the file while you have it open in &kwrite;. + + + + + + + + +&Ctrl;P + +File +Print... + + + + +Opens a simple print dialog allowing the user to specify what, where, +and how to print. + + + + + + + +File +Export as HTML... + + + + +Export your file in HTML format so your document can be viewed as a web page. + + + + + + + + +&Ctrl;W + +File +Close + + + + +Close the active file with this command. If you have made unsaved changes, you +will be prompted to save the file before &kwrite; closes it. + + + + + + + + +&Ctrl;Q + +File +Quit + + + + +This will close the editor window, if you have more than one instance of +&kwrite; running, through the New View or +New Window menu items, those instances will +not be closed. + + + + + + + + + +The <guimenu>Edit</guimenu> Menu + + + + +&Ctrl;Z +Edit +Undo + +This is used to eliminate or reverse the most recent user action +or operation. + + + + + + + +&Ctrl;&Shift;Z +EditRedo + +This will reverse the most recent change (if any) made using Undo + + + + + +&Ctrl;X +EditCut + +This command deletes the current selection and places it on the +clipboard. +The clipboard is a feature of &kde; that works invisibly to provide a way to +transfer data between applications. + + + + + +&Ctrl;C +EditCopy + +This copies the currently selected text to the clipboard so that it may +be pasted elsewhere. The clipboard is a feature of &kde; that works invisibly +to provide a way to transfer data between applications. + + + + + +EditCopy as +HTML + +This copies the currently selected text to the clipboard as HTML. + + + + + +&Ctrl;V +EditPaste + +This will insert the contents of the clipboard at the cursor position. +The clipboard is feature of &kde; that works invisibly to provide a way to +transfer data between applications. + + + + + +&Ctrl;A +EditSelect All + +This will select the entire document. This could be very useful for +copying the entire file to another application. + + + + + + +&Ctrl;&Shift;A + +EditDeselect + +Deselects the selected text in the editor if any. + + + + + + +&Ctrl;&Shift;B + +EditBloc +Selection Mode + +Toggles Selection Mode. When the Selection Mode is “BLOCK”, you can make +vertical selections, ie select column 5 to 10 in lines 9 to 15. +The status bar shows the current state of the Selection Mode, either “NORM” or +“BLK”. + + + + + + +Insert + +EditOverwrite +Mode + +Toggles the Insert/Overwrite modes. When the mode is "INS", you +insert characters where the cursor is. When the mode is "OVR", writing +characters will replace the current characters if your cursor is positioned +before any character. The status bar shows the current state of the Overwrite +Mode, either “INS” or “OVR”. + + + + + +&Ctrl;F +EditFind + +This opens the find dialog which is used to specify the Text to +Find in the document. There is small text box for entering the search +pattern which also doubles as a dropdown box. Clicking on the dropdown arrow at +the side of the box makes available other recent search patterns. Other +parameters are included to make the search more efficient. Selecting +Case Sensitive will limit finds to entries that match the +case (upper or lower) of each of the characters in the search pattern. +Find Backwards directs the search to proceed in an upwardly +direction. The Selected Text option keeps the search +within currently selected text. Checking Whole Words Only +prevents the search from stopping on words that contain the searched for +pattern. The Search from Cursor option begins the search +from the current position of the cursor within the document rather than from +the beginning. + + + + + +F3 +EditFind Next + +This repeats the last find operation, if any, without calling the find +dialog box. + + + + + + + + +&Shift;F3 + +Edit +Find Previous + + + + +This repeats the last find operation, if any, without calling the find +dialog box, and searching backwards instead of forwards through the +document. + + + + + + +&Ctrl;R +EditReplace... + +This command opens the replace dialog box. The replace dialog is +almost identical to the above-mentioned find dialog. In addition to the features +in the find dialog it contains a Replace With: text +entry/dropdown box. Using this dialog the user can specify both the text to be +found and text with which to replace it. The additional Prompt +On Replace option allows the user to have &kwrite; ask for +confirmation before each replacement. + + + + + + + + +&Ctrl;G + +Edit +Go to line + + +This opens the goto line dialog box which is used to have the cursor +jump to a particular line (specified by number) in the document. The +line number may be entered directly into the text box or graphically by +clicking on the up or down arrow spin controls at the side of the text +box. The little up arrow will increase the line number and the down +arrow decrease it. There is also a slide control to the right of the +text box which allows the user to move the goto point in the document in +an analog manner. + + + + + + + +The <guimenu>View</guimenu> menu + +The View menu allows you to manage settings +specific to the active editor, and to manage frames. + + + + + + + +View +New Window + + + +Opens a new window with the same text. + + + + + + + +F7 +View +Switch to Command Line + + + +Displays the Katepart command line at the bottom of the window. +In the command line, type "help" to get help and "help list" to get a list of +commands. + + + + + + + +View +Schema + + + +Select a font schema. + + + + + + + +F10 +View +Dynamic Word Wrap + + + +The text lines will be wrapped at the view +border on the screen. + + + + + + + +F10 +View +Dynamic Word Wrap Indicators + + + + Choose when and how the dynamic word wrap indicators should be +displayed. This is only available if the Dynamic Word +Wrap option is checked. + + + + + + + +View +Show Static Word Wrap Marker + + + +If this option is checked, a vertical line will be drawn at the +word wrap column as defined in the +Settings +Configure Editor... in the +Editing tab. Please note that the word wrap marker is only drawn if you +use a fixed pitch font. + + + + + + + +F6 +View +Show Icon Border + + + +This is a toggle item. Setting it on checked will make the +side of the active editor, and vice versa. + + + + + + + +F11 +View +Show Line Numbers + + + +This is a toggle Item. Setting it on checked will make a pane displaying +the line numbers of the document visible in the left border of the active +editor, and vice versa. + + + + + + + +View +Show Scrollbar Marks + + + +If this option is checked, the view will show marks on the vertical +scrollbar. + + + + + + + +F9 +Hide Folding Markers + + + +If this option is checked, the marks for code folding will be +hidden. + + + + + + + +Code Folding + + + + + +Ctrl +Shift- +Collapse Toplevel + +Collapse all toplevel regions in the document. + + +Ctrl +Shift+ +Expand Toplevel + +Expand all toplevel regions in the document. + + +Ctrl +- +Collapse One Local Level + +Collapse the region closest to the cursor. + + +Ctrl ++ +Expand One Local Level + +Expand the region closest to the cursor. + + + + + + + + + + +The <guimenu>Bookmarks</guimenu> Menu + + + + + + +&Ctrl;B + +Bookmarks +Set Bookmark + + + + +Sets or removes a bookmark in the current line of the active document. (If it's +there, it is removed, otherwise one is set). + + + + + + + +Bookmarks +Clear All Bookmarks + + + + +This command will remove all the markers from the document as well as +the list of markers which is appended at the bottom of this menu item. + + + + + +Alt +Page Up +BookmarksPrevious + +This will move the cursor to beginning of the first above line +with a bookmark. The menuitem text will include the line number and the first +piece of text on the line. This item is only available when there is a bookmark +in a line above the cursor. + + + +Alt +Page Down +BookmarksNext +This will move the cursor to beginning of the next line with a +bookmark. The menuitem text will include the line number and the first piece of +text on the line. This item is only available when there is a bookmark in a line +below the cursor. + + + + + +At the bottom of this menu, a list of markers appears if any markers are +available for this window. + + + + + +The <guimenu>Tools</guimenu> Menu + + + + +Tools +Read Only Mode + +Set the current document to Read Only mode. This prevents any text +addition and any changes in the document formatting. + + + + + +Tools +Filletype + +Choose the filetype scheme you prefer for the active document. This +overwrites the global filetype mode set in +Settings +Configure +Editor... in the Filetypes tab for your current +document only. + + + + + +Tools +Highlighting + +Choose the Highlighting scheme you prefer for the active document. This +overwrites the global highlighting mode set in +Settings +Configure +Editor... for your current document only. + + + + + +Tools +Indentation + +Choose the style of indentation you want for your active document. +This overwrites the global indentation mode set in +Settings +Configure +Editor... for your current document only. + + + + + +Tools +Encoding + +You can overwrite the default encoding set in +Settings +Configure +Editor... in the Open/Save tab +to set a different encoding for your current document. The encoding you +set here will be only valid for your current document. + + + + + +Tools +End of Line + +Choose your prefered end of line mode for your active +document. This overwrites the global end of line mode set in +Settings +Configure +Editor... for your current document only. + + + + + +ToolsSpelling... + + +This initiates the spellchecking program - a program +designed to help the user catch and correct any spelling errors. +Clicking on this entry will start the checker and bring up the speller dialog +box through which the user can control the process. There are four settings +lined up vertically in the center of the dialog with their corresponding labels +just to the left. Starting at the top they are: + + + +Unknown word: +Here, the spellchecker indicates the word currently under +consideration. This happens when the checker encounters a word not in its +dictionary - a file containing a list of correctly spelled words against which +it compares each word in the editor. + + +Replace with: + If the checker has any similar words in its dictionary the +first one will be listed here. The user can accept the suggestion, type in his +or her own correction, or choose a different suggestion from the next +box. + + +Suggested Words: + The checker may list here a number of possible replacements for +the word under consideration. Clicking on any one of the suggestions will cause +that word to be entered in the Replacement: box, +above. + + +Language: + If you have installed multiple dictionaries, here you can +select which dictionary/language should be used. + + + +On the right side of the dialog box are 5 buttons that allow the user to +control the spellcheck process. They are: + + + +Add to Dictionary +Pressing this button adds the word in the Misspelled +Word: box to the checker's dictionary. This means that in the future +the checker will always consider this word to be correctly +spelled. + + +Replace + This button has the checker replace the word under +consideration in the document with the word in the +Replacement: box. + + +Replace All + This button causes the checker to replace not only the current +Unknown word: but to automatically make the same +substitution for any other occurrences of this Misspelled +Word: in the document. + + +Ignore +Activating this button will have the checker move on without +making any changes. + + +Ignore All + This button tells the checker to do nothing with the current +Unknown word: and to pass over any other instances of +the same word. This only applies to the current spellcheck +run. If the checker is run again later it will stop on this same +word. + + + + + + + +Three more buttons are located horizontally along the bottom of the +spellcheck dialog. They are: + + + +Help + This invokes the &kde; help system starting at the &kwrite; help +pages (this document). + + + +Finished + This button ends the spellcheck process, and returns to the +document. + + + +Cancel + This button cancels the spellcheck process, all modifications +are reverted, and you will return to your document. + + + + + + + + + +Tools +Spelling (from cursor)... + +This initiates the spellchecking program but it starts where your cursor +is instead of at the beginning of the document. + + + + + +Tools +Spellcheck Selection... + +Spellchecks the current selection. + + + + + + +&Ctrl;I + +ToolsIndent + +This increases the paragraph's indentation by one step. The size of the +step depends on the indentation +settings. + + + + + + +&Ctrl;&Shift;I + +ToolsUnindent + + +This reduces the paragraph's indentation by one step. The size of the step + +depends on the indentation settings. + + + + + + +ToolsClean +Indentation +This cleans the indentation for the current selection or for the +line the cursor is currently in. Cleaning the indentation ensures that +all your selected text follows the indentation mode you choose. + + + + + +Tools +Align + + +Causes a realign of the current line or selected lines using the +indentation mode and indentation settings in the doucment. + + + + + + +&Ctrl;D + +Tools +Comment + +This adds one space to the beginning of the line +where the text cursor is located or to the beginning of any +selected lines. + + + + + + +&Ctrl;&Shift;D + +Tools +Uncomment + +This removes one space (if any exist) from the beginning of the +line where the text cursor is located or from the beginning of any +selected lines. + + + + + +&Ctrl;U + +Tools +Uppercase + +Put the selected text or the letter after the cursor in +uppercase. + + + + + +&Ctrl;&Shift;U + +Tools +Lowercase + +Put the selected text or the letter after the cursor in +lowercase. + + + + + +&Alt;&Ctrl;U + +Tools +Capitalize + +Capitalize the selected text or the current +word. + + + + + +&Ctrl;J + +Tools +Join Lines + +Joins the selected lines, or the current line and the line below +with one white space character as a separator. Leading/trailing white space on +joined lines is removed in the affected ends. + + + + +Tools +Word Wrap Document + +Apply static word wrapping on all the document. That means that +a new line of text will automatically start when the current +line exceeds the length specified by the Wrap words at: option +in the Editing tab in +SettingsConfigure +Editor... + + + + + + + + +The <guimenu>Settings</guimenu> Menu + + + + +Settings +Show Toolbar + + + + +When checked, this displays a movable toolbar containing buttons used to +initiate frequently used commands. When unchecked the toolbar is hidden. + + + + + + +SettingsShow +Statusbar + +When checked, this displays a small bar at the bottom of the editor +containing information about the status of the current document. When unchecked +the statusbar is hidden. + + + + + +SettingsShow +Path + +When selected, this displays in the titlebar the path (its location in the +file system) of the current document. When unchecked the path is hidden. + + + + + +Settings +Configure Editor... + + + + +This menu item opens a dialog whereby several different settings may be adjusted. + + + + + + +Settings +Choose Editor... + + + + +Choose the default text editing component that you wish to use in &kwrite;. You +can choose System Default, Embedded +Advanced Text Editor or &Qt; Designer Based +Text Editor (note that the &Qt; Designer Based Text Editor is +only available if you have KDevelop installed on your system). If you choose +System Default, &kwrite; will honor your changes in +&kcontrolcenter;. All other choices will override that setting. + + + + + + +SettingsConfigure +Shortcuts... + +This command opens a dialog box whereby the shortcuts may be changed. A display window at the +top of the dialog box shows the list of commands (actions) that can have +keyboard shortcuts. Below the display are three radio buttons. The user may +choose between No Key, Default Key, and Custom Key. (Note that a set of radio +buttons only allows the selection of one of the offered items - in the way that +buttons on a car radio only offer the selection of one preset station. Also, +the Default Key selection is only available for those commands that actually +have a 'default' shortcut.) Selecting the Custom Key option activates the three +check boxes and key button at the bottom of the dialog. The user may then select +a key combination for the command in question by means of the check boxes and +key button. For example, with the About &kde; command selected in the display +window, the user could select &Ctrl; and Alt, click on the key +button, and then press the K key on the keyboard. This would +mean that anytime he or she held down the &Ctrl; and Alt +buttons and pressed K (while using +&kwrite;) the About &kde; display box would be called. + + + + + +SettingsConfigure +Toolbars... +This will open the dialog whereby the toolbar configuration may +be changed. The user can choose which shortcut buttons should appear on the +toolbar. A display window on the left lists the commands available to placed +on the toolbar. A display on the right lists those commands already on the +toolbar. A set of four arrow buttons between the two displays manipulates the +selections. The right pointing arrow places any command selected in the left +pane onto the right pane, i.e., it is added to the toolbar. +The left arrow does just the opposite, removing any action selected in the right + +window from the toolbar. The up and down pointing arrows change the position of + +an action selected in the right window which changes the position of its button + +in the toolbar. + + + + + + + + + + + + + + + + + + +The <guimenu>Help</guimenu> Menu + +&help.menu.documentation; + + + + + +Configure &kwrite; + + +Selecting SettingsConfigure +Editor... from the menu brings up the +Configure Editor dialog box. This dialog can be +used to alter a number of different settings. The settings available +for change vary according to which category the user chooses from a +vertical list on the left side of the dialog. By means of three buttons +along the bottom of the box the user can control the process. + + + +She or he may invoke the Help system, accept the +current settings and close the dialog by means of the +OK button, or Cancel the +process. The categories Colors, +Fonts Indent, +Select, Edit, +Spelling and Highlighting are +detailed below. + + + +Appearance + + + +Word Wrap + + + +Dynamic word wrap +If this option is checked, the text lines +will be wrapped at the view border on the screen. + + +Dynamic word wrap indicators +Choose when the Dynamic word wrap indicators +should be displayed. + + +Vertically align dynamically wrapped lines +to indentation depth: + +Enables the start of dynamically wrapped +lines to be aligned vertically to the indentation level of the first +line. This can help to make code and markup more +readable.Additionally, this allows you to +set a maximum width of the screen, as a percentage, +after which dynamically wrapped lines will no longer be vertically aligned. +For example, at 50%, lines whose indentation levels are deeper than 50% of the +width of the screen will not have vertical alignment applied to subsequent +wrapped lines. + + + + + + +Code Folding + + + +Show folding markers (if available) + +If this option is checked, the current view will display marks +for code folding, if code folding is available. + + + + + + +Borders + + + +Show icon border + +If this is checked, you will see an icon border on the left +hand side. The icon border shows bookmark signs for instance. + + +Show line numbers + +If this is checked, you will see line numbers on the left +hand side. + + +Show scrollbar marks + +If this option is checked the current view +will show marks on the vertical scrollbar. These marks will +for instance show bookmarks. + + + + + + +Sort Bookmarks Menu + + + + +By position + +The bookmarks will be ordered by the line +numbers they are placed at. + + +By creation + +Each new bookmark will be added to the bottom, +independently from where it is placed in the document. + + + + + + +Show identation lines + +If this is checked, the editor wil display +vertical lines to help identifying indent lines. + + + + + +Fonts & Colors + +This section of the dialog lets you configure all fonts and colors in +any color scheme you have, as well creating new schemes or deleting existing +ones. Each scheme has settings for colors, fonts and normal and highlight text +styles. + + +&kwrite; will preselect the currently active scheme for you, if you want to +work on a different scheme start by selecting that from the +Schema combobox. + + +Colors + + + +Text Area Background + + + + + +Normal text +This is the default background for the editor area, it will be +the dominant color on the editor area. + + + +Selected Text +This is the background for selected text. The default is +the global selection color, as set in your &kde; color preferences. + + + + +Current Line +Set the color for the current line. Setting this a bit different +from the Normal text background helps to keep focus on the current line. + + + + +Bookmark +This combo lets you set overlay colors for various mark types. +The color is mixed into the background color of a marked line, so that a line +with more marks or a marked line that is current has a background that is a mix +of more colors. The mark colors are also used if you enable display of scrollbar +marks. + + + + + + + +Other Elements + + + +Left Border Background +This color is used for the marks, line numbers and folding +marker borders in the left side of the editor view when they are displayed. + + + +Line Numbers +This color is used to draw the line numbers on the left side of +the view when displayed. + + +Bracket Highlight +This color is used to draw the background of matching brackets. + + + +Word Wrap Markers +This color is used to draw a pattern to the left of dynamically +wrapped lines when those are aligned vertically, as well as for the static word +wrap marker. + + +Tab Markers +This color is used to draw white space indicators when enabled. + + + + + + + + + + +Fonts + +Here you can choose the font for the schema. You can choose from +any font available on your system, and set a default size. A sample text +displays at the bottom of the dialog, so you can see the effect of your choices. + + + + +Normal Text Styles +The normal text styles are inherited by the highlight text styles, +allowing the editor to present text in a very consistent way, for example comment +text is using the same style in allmost all of the text formats that kate can +highlight. +The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. + +Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. + + + +Highlighting Text Styles +Here you can edit the text styles used by a specific highlight definition. +The editor preselects the highlight used by your current document. To work on a +different highlight, select one in the Highlight combobox +above the style list. + +The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. + +Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. In addition you can see if a style is equal to the default style +used for the item, and set it to that if not. +You will notice that many highlights contain other highlights represented +by groups in the style list. For example most highlights import the Alert +highlight, and many source code formats imports the Doxygen highlight. Editing +colors in those groups only affects the styles when used in the edited highlight +format. + + + + + + +Cursor & Selection + + + + +Text Cursor Movement + + + +Smart home + +When selected, pressing the home key will cause the cursor to +skip white space and go to the start of a line's text. + + + +Wrap cursor + +When on, moving the insertion cursor using the Left and Right keys will +go on to previous/next line at beginning/end of the line, similar to most +editors.When off, the insertion cursor cannot be moved left of the +line start, but it can be moved off the line end, which can be very handy for +programmers. When this option is chosen, moving the cursor with the arrow keys +off the end of a line (to the right) causes it to jump down to the beginning of +the next line. Likewise when the cursor is moved past the beginning of a line +(to the left) it jumps up to the end of the preceding line. When this option is +not selected, moving the cursor right past the end of a line merely causes it to +continue horizontally in the same line and trying to move it left past the +beginning does nothing. + + + +Page Up/Page Down moves cursor + +This option changes the behavior of the cursor when the user presses +the Page Up or Page Down key. If unselected +the text cursor will maintain its relative position within the visible text in +&kwrite; as new text becomes visible as a result of the operation. So if the +cursor is in the middle of the visible text when the operation occurs it will +remain there (except when one reaches the beginning or end.) With this option +selected, the first key press will cause the cursor to move to either the top or +bottom of the visible text as a new page of text is displayed. + + + +Autocenter cursor (lines): + +Sets the number of lines to maintain visible above and below the cursor +when possible. + + + + + + + +Selection Mode + + + +Normal + +Selections will be overwritten by typed text and will be lost on +cursor movement. + + + +Persistent + +Selections will stay even after cursor movement and typing. + + + + + + + + + + +Editing + + + +Tabulators + + + +Insert spaces instead of tabulators + +When this is enabled the editor will insert a calculated number of spaces +according to the position in the text and the setting +when you press the TAB key. + + + +Show tabulators + +When this is enabled &kwrite; will display a small dot as a visual +representation of tabulator characters. +This also causes dots to be drawn to indicate trailing white space. +This will be fixed in a future version of &kwrite; + + + +Tab Width If the +Replace Tabs By +Spaces +option is selected this entry determines the number of +spaces with which the editor will automatically replace +tabs. + + + + + + +Static Word Wrap + +Word wrap is a feature that causes the editor to automatically start a new line +of text and move (wrap) the cursor to the beginning of that new line. &kwrite; +will automatically start a new line of text when the current line reaches the +length specified by the Wrap Words +At: option. + + +Enable static word wrap + +Turns static word wrap on or off. + + + +Show static word wrap markers +(if applicable) + +If this option is checked, a vertical line will be drawn at the word wrap +column as defined in the Settings +Configure Editor... in the Editing tab. +Please note that the word wrap marker is only drawn if you use a fixed pitch +font. + + + +Wrap words at: + +If the Word Wrap option is selected +this entry determines the length (in characters) at which the editor will +automatically start a new line. + + + + + + + +Remove Trailing Spaces +&kwrite; will automatically eliminate extra spaces +at the ends of lines of text. + + +Auto Brackets When +the user types a left bracket ([, (, or {) &kwrite; automatically enters the +right bracket (}, ), or ]) to the right of the cursor. + + + Maximum undo steps: +Here the user may specify the number of steps &kwrite; will +retain in memory for purposes of undoing entries and actions. This means that +the higher the number of steps set the more memory &kwrite; will use for this. +Setting this entry to 10 would mean that the user would be be able reverse the +last ten operations, i.e. click the undo +button 10 times and obtain results. + + Smart search text from: +This determines where &kwrite; will get the search +text from (this will be automatically entered into the Find Text +dialog): + +Nowhere: Don't guess the search +text. +Selection Only: Use + the current text selection, if available. +Selection, then Current Word: +Use the current selection if available, otherwise use the current word. + +Current Word +Only: Use the word that the cursor is currently resting on, if +available. +Current Word, then Selection: +Use the current word if available, otherwise use the current selection. + + +Note that, in all the above modes, if a +search string has not been or cannot be determined, then the Find Text Dialog +will fall back to the last search text. + + + + + + + +Indentation + + +Automatic indentation + + + +Indentation mode: + +Select the automatic indentation mode you want to use as default. It is +strongly recommended to use None or +Normalhere, and use filetype configurations to set other +indentation modes for text formats like C/C++ code or &XML;. + + + +Insert leading Doxygen "*" when typing + +Automatically insert a leading "*" while typing within a doxygen +style comment. This setting is only enabled when applicable. + + + + + + + +Indentation with Spaces + + + +Use spaces instead of tabs to indent + +This replaces tabs with the number of spaces set in Number of +spaces: below. + + + +Emacs style mixed mode + +Use a mix of tabs and space characters for indentation. + + + +Number of spaces: + +Set the number of spaces you want to use for indentation when you +check Use spaces instead of tabs to indent +above. + + + + + + + +Keep Indent Profile +When this is enabled, the editor will not unindent lines in a +selection further when the line with the least indentation becomes unindented. +If you sometimes unindent blocks of indented code, this may be helpful. + + + + +Keep Extra Spaces +Indentations of more than the selected number of spaces +will not be shortened. + + + +Keys to use + + + +Tab key indents + +This allows the tab key to be used to indent. + + + +Backspace key indent + +This allows the backspace key to be used to +indent. + + + + + + + +Tab Key Mode if Nothing Selected + + + +Insert indent characters + +This allows the Tab key insert indent +characters. + + + +Insert tab character + +This allows the Tab key insert a tab. + + + +Indent current line + +This allows the Tab key indent the current +line. + + + + + + + + + + + +Open & Save + + + + +File Format + + + +Encoding: + +This sets the default character encoding for your files. + + + +End of line: + +Choose your prefered end of line mode for your active +document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh. + + + +Automatic end of line detection + +Check this if you want the editor to autodetect the end of line +type. The first found end of line type will be used for the whole file. + + + + + + + +Memory Usage + + + +Maximum loaded blocks per file: + +The editor will load given number of blocks (of around 2048 lines) of +text into memory; if the filesize is bigger than this the other blocks +are swapped to disk and loaded transparently as-needed. +This can cause little delays while navigating in the document; a +larger block count increases the editing speed at the cost of memory. +For normal usage, just choose the highest possible block count: +limit it only if you have problems with the memory usage. + + + + + + + +Automatic Cleanups on Load/Save + + + +Remove trailing spaces + +The editor will automatically eliminate extra spaces at the ends of lines +of text while loading/saving the file. + + + + + + + +Folder Config File + + + +Search depth for config file: + +The editor will search the given number of folder levels upwards +for &kwrite; config file and load the settings line from it. + + + + + + + +Backup on Save +Backing up on save will cause &kwrite; to copy the disk file to +<prefix><filename><suffix>' before saving changes. +The suffix defaults to ~ and prefix is empty by +default. + + +Local files + +Check this if you want backups of local files when +saving. + + + +Remote files + +Check this if you want backups of remote files when saving. + + + +Prefix + +Enter the prefix to prepend to the backup file names. + + + +Suffix + +Enter the suffix to add to the backup file names. + + + + + + + + + + + +Highlighting +This group of options is used to customize the highlighting styles for +each programming language type. Any changes you made in other areas of this +dialog apply only to this type. + + + +Highlight: +This is used to choose the language type to +configure. + + + +Informations + + +View the properties of the chosen language highlighting rules: +author name and license. + + + + + +Properties + + + +File extensions: +This is the list of file extensions used to determine which +files to highlight using the current syntax highlight mode. + + +MIME types: +Clicking the wizard button will display a dialog with a list of +all available mime types to choose from.The File Extensions entry will automatically be edited as +well. + + +Priority: +Set the priority of the highlight rule. + + + + + + +Download... + + +Click this button to download new or updated syntax highlight descriptions +from the &kate; website. + + + + + + + + + +Filetypes +This page allows you to override the default configuration for documents +of specified mimetypes. When the editor loads a document, it will try if it +matches the file masks or mimetypes for one of the defined filetypes, and if so +apply the variables defined. If more filetypes match, the one with the highest +priority will be used. + + + +Filetype: +The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are +also listed. + + +New +This is used to create a new filetype. After +you click on this button, the fields below get empty and you +can fill the properties you want for the new filetype. + + +Delete +To remove an existing filetype, select it from the drop down +box and press the Delete button. + + + + + +Properties of current filetype +The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are also +listed. + + +Name: +The name of the filetype will be the text of the corresponding +menu item. This name is displayed in the +ToolsFiletypes + + + +Section: +The section name is used to organize the file types in +menus. This is also used in the +ToolsFiletypes + menu. + + +Variables: +This string allows you to configure &kwrite;'s settings for the +files selected by this mimetype using &kwrite; variables. You can set almost any +configuration option, such as highlight, indent-mode, encoding, +etc.For a full list of known variables, see the +manual. + + +File extensions: +The wildcards mask allows you to select files by filename. A +typical mask uses an asterisk and the file extension, for example +*.txt; *.text. The string is a semicolon-separated list of +masks. + + +MIME types: +Displays a wizard that helps you easily select +mimetypes. + + +Priority: +Sets a priority for this file type. If more than one file type +selects the same file, the one with the highest priority will be +used. + + + + + + + + +Shortcuts +You can change here the shortcut keys configuration. Select an +action and click on Custom if you want a different shortcut +for this action. +The search line alllows you to look for a specific action and see +its associated shortcut. + + + +Plugins +This tab lists all available plugins and you can check those you +want to use. Once a plugin is checked, the +Configure button is enabled and you can click it +in order to configure the highlighted plugin. + + + + +Credits and Licenses + +&kwrite; Copyright 2001 by the &kate; team. + + +Based on the original &kwrite;, which was Copyright 2000 by Jochen Wilhelmy +digisnap@cs.tu-berlin.de + + +Contributions: + + + +&Christoph.Cullmann; &Christoph.Cullmann.mail; + + + +Michael Bartl michael.bartl1@chello.at + + + +Phlip phlip_cpp@my-deja.com + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Matt Newell newellm@proaxis.com + + + +&Joseph.Wenninger; &Joseph.Wenninger.mail; + + + +Jochen Wilhely digisnap@cs.tu-berlin.de + + + +&Michael.Koch; &Michael.Koch.mail; + + + +&Christian.Gebauer; &Christian.Gebauer.mail; + + + +&Simon.Hausmann; &Simon.Hausmann.mail; + + + +Glen Parker glenebob@nwlink.com + + + +Scott Manson sdmanson@altel.net + + + +&John.Firebaugh; &John.Firebaugh.mail; + + + + +Original documentation by &Thad.McGinnis; &Thad.McGinnis.mail; + + + +Updated by &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; and +&Anders.Lund; &Anders.Lund.mail; + + + +This version of the &kwrite; Handbook is based on the original by +&Cristian.Tibirna; &Cristian.Tibirna.mail; + + + +Converted to docbook/proofreading by &Lauri.Watts; &Lauri.Watts.mail; + + + + +&underFDL; +&underGPL; + + +&documentation.index; + + + diff --git a/doc/kxkb/Makefile.am b/doc/kxkb/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kxkb/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kxkb/index.docbook b/doc/kxkb/index.docbook new file mode 100644 index 000000000..6f3673aba --- /dev/null +++ b/doc/kxkb/index.docbook @@ -0,0 +1,358 @@ + + + + + +]> + + + +The &kxkb; Handbook + + + +&Andriy.Rysin; &Andriy.Rysin.mail; + + +&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; + + +&Andriy.Rysin; &Andriy.Rysin.mail; + + + + + + + + +2003 +&Andriy.Rysin; + + +2006 +&Anne-Marie.Mahfouf; + + +&FDLNotice; + +2006-02-16 +3.5.2 + +&kxkb; is a keyboard layout switching +utility based on X11 xkb extension. + + +KDE +kxkb +keyboard +layout + + + + +Introduction + +&kxkb; is the &kde; keyboard layout switching utility. +It is based on X11 xkb extension and allows to use different keyboard +layouts for inputing text. &kxkb; features keyboard layout indicator. + + + + + +Using &kxkb; + + +Getting Started + +&kxkb; starts automatically and stays in system tray as a flag +with 2 or 3 letter abbreviation of layout name on top of it if more +than one layout is defined or Show indicator for single +layout option is turned on. + +When &kxkb; is running you can change layouts clicking on its +tray icon with the mouse or pressing its keyboard shortcut. Keyboard +shortcut or mouse click will switch to next layout or alternatively you +can &RMB; click the &kxkb; icon and select layout from the +list. + +&RMB; clicking on the &kxkb; icon you can start its +configuration by selecting Configure... or +by opening Control Center and selecting +Localization/Keyboard Layout. Alternatively, you can start it by +typing kcmshell keyboard_layout in a +terminal. + + + + + +Configuring &kxkb; + + +General Information + +&kxkb; Configuration consists of three tabs: Layout, Switching + Options and Xkb Options. Layout and Xkb Options are mutually independent. +The Layout tab defines layouts you want to use and their options, the Switching +Options tab defines how you want to switch keyboards and the Xkb Otions tab +defines parameters for Xkb extension on which &kxkb; is based. +Xkb options are property of X and are not handled in any way by &kxkb; - +it just sets it up. + + +&kxkb; configuration does not change anything in XFree86 configuration +files and Layout settings from XFree86 configuration are overridden +by &kxkb; if option is turned on. + + +To make your XFree86 configuration work you have to turn off both + in layout configuration tab +and in +Xkb options configuration tab (for the latter the same effect can be +reached if is turned off and +none of xkb options are set). + + +&kxkb; does most of its actions through setxkbmap command. +You can see the commandline to be executed for each active layout +when you select it and, on the xkb options tab, its available xkb option set. + + + + +Layout Configuration + + +The Layout tab + + + + + + The Layout tab + + + + + +In layout configuration dialog the list of available layouts on your left. +You have to choose each layout you want to use and add them (one by one) +to the list of active layouts on the right. You can also change the order +in which active layouts will be switched when toggled by keyboard shortcut +or mouse button. The first layout in the list becomes default layout. + + +Some layouts have several variants. Layout variants usually represent +different key maps for the same language. For example, Ukrainian +layout might have four variants: basic, winkeys (as in Windows), typewriter +(as in typewriters) and phonetic (each Ukrainian letter is placed on a +transliterated latin one). If your layout is multi-variant one +you can the variant in combobox below the active layouts list. + + +Keyboard model setting is independent of your keyboard layout and refers +to the "hardware" model, i.e. the way your keyboard is manufactured. +Modern keyboards that come with your computer usually have two extra keys +and are referred to as "104-key" models, which is probably what you want +if you don't know what kind of keyboard you have. + + +You can also choose switching policy for keyboard layout. By default it's + all applications will share the same current layout. + means each application will have it's own layout and +switching layout while you are working with one application will not impact layout for any +others. will make every window have its own layout even if they belong +to the same program. + + +If you set only one active layout, at startup kxkb configures the keyboard and exits thus +its indicator will not appear. If you still want kxkb indicator select + option. + + + +If you leave active layout list empty keyboard layouts will be disabled + + + + + +Switching Options + + +The Switching Options tab + + + + + + The Switching Options tab + + + + + + +Show indicator for single layout +Shows icon in system tray even when thee is +only one layout. + + +Show country flag +Shows country flag on background of layout name in tray +icon. + + +Switching Policy +If you select Application or +Window switching policy, +changing the keyboard layout will only affect the current application or +window. Global will make the switching +policy work globally for all applications and windows. + + +Sticky Switching +If you have more than two layouts and check Enable +sticky switching, switching with the keyboard shortcut or clicking on +the kxkb indicator will only cycle through the last few layouts. You can specify +the number of layouts to rotate below in the Number of layouts to +rotate box. You can still access all layouts by right-clicking on the +&kxkb; indicator. + + + + + +XKB Options Configuration + + +The Xkb tab + + + + + + The Xkb tab + + + + + +Xkb options allow you to select behavior of your keyboard. These options are not +handled by &kxkb; but may help tune your keyboard to your needs. You can set Xkb +extension options instead of, or in addition to, specifying them in the X11 +configuration file. + + + + + + +Troubleshooting + + +Common Problems + +If you switch to some layout and you can not see some characters +from your layout as you type, please check your local settings. ⪚ +~/.i18n or +/etc/sysconfig/i18n, locale you have before +starting kde applications must have an encoding which contains +characters from your layout. For example, to enter ukrainian symbols +you must have encoding KOI8-U, CP1251 or UTF-8. The last one is a good +choice to try for most of the languages if you have such a problem. + + +If kxkb does not switch with keyboard shortcut when you switch +it to some layout but switching with mouse is ok may mean +that your layout does not contain the key +assigned in shortcut. + +In XFree86 prior to version 4.3.0 non-latin layouts mutually included +latin group and this group was the default thus pressing +&Ctrl;&Alt;k +always yielded the right combination. From version 4.3.0 by default +all layouts contain only one group thus non-latin layouts may not work +here. + +Possible solutions are: + + + +add your layout to $nonlatin or $oldlayouts lists in +/etc/X11/xkb/rules/xfree86 or the location of the +xkb rules on your computer. + + +Change the shortcut to something language neutral, ⪚ +&Ctrl;Menu + + +Turn on the option to include the us group in +your layout (effectively the same as solution 1). + + + + + + + +Files and Layout Descriptions + +<application>xkb</application> Files and Layouts + +All available keyboard layouts are described in +/etc/X11/xkb/rules/xfree86.lst (and +/etc/X11/xkb/rules/xfree86.xml since XFree86 +4.3.0), the layouts themselves can be found in +/etc/X11/xkb/symbols/pc (or +/etc/X11/xkb/symbols for XFree86 4.2.x and +older). Note that the location of these files may differ depending on +your operating system and distribution. + +&kxkb; now uses the xkb extension instead of xmodmap, so to +define your own layout you have to get one from /etc/X11/xkb/symbols which is closest to +what you want to get (or /etc/X11/xkb/symbold/pc for XFree86 +4.3.0), rename it to something you like and edit it. Then just add the +name to /etc/X11/xkb/rules/xfree86.lst (and for +XFree86 4.3.0 or later it is a good idea to add the name also to +/etc/X11/xkb/ruls/xfree86.xml - some packages +already use it, not &kxkb; though yet) kxkb will pick it up on +restart. Note: you have to be root to edit those files. + + + + + + +Credits and Licenses + +&kxkb; is currently developed and maintained by Andriy Rysin +rysin@kde.org. Several other people +have worked on kxkb: + + +Shaheed Haque srhaque@iee.org +Ilya Konstantinov kde-devel@future.galanet.net + + +&underFDL; +&underGPL; + + + + + + diff --git a/doc/kxkb/layout.png b/doc/kxkb/layout.png new file mode 100644 index 000000000..dfb30cbf6 Binary files /dev/null and b/doc/kxkb/layout.png differ diff --git a/doc/kxkb/switching.png b/doc/kxkb/switching.png new file mode 100644 index 000000000..504eaa7b2 Binary files /dev/null and b/doc/kxkb/switching.png differ diff --git a/doc/kxkb/xkb.png b/doc/kxkb/xkb.png new file mode 100644 index 000000000..df2db58f7 Binary files /dev/null and b/doc/kxkb/xkb.png differ diff --git a/doc/quickstart/Makefile.am b/doc/quickstart/Makefile.am new file mode 100644 index 000000000..7e42282c4 --- /dev/null +++ b/doc/quickstart/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/quickstart diff --git a/doc/quickstart/index.docbook b/doc/quickstart/index.docbook new file mode 100644 index 000000000..7828c7121 --- /dev/null +++ b/doc/quickstart/index.docbook @@ -0,0 +1,1340 @@ + + + + + +]> + + + + +An Introduction to &kde; + + + + +The &kde; Team + + + + +2004-08-28 +3.00.00 + + +1999200020012002 +The &kde; Team + + +&FDLNotice; + + +An introduction to the K Desktop Environment +Quick Start Guide to &kde; + + +KDE +quick start +introduction + + + + +Introduction + + +This document is a brief introduction to the K Desktop Environment. It +will familiarize you with some of the basic features of &kde;. + + + +This guide is far from covering all aspects of the K Desktop or even most +of them. It will only describe some of the most basic ways to accomplish a few +of the most common tasks. + + + +We assume that you are already familiar with at least one graphical +user interface, for example CDE, +Geos, GEM, &NeXTSTEP;, +&Mac;, OS/2 or &Microsoft; &Windows;. So we +will not explain the usage of the mouse or the keyboard but +concentrate on hopefully more interesting things. + + + + + +An Overview of &kde; + + +This section is for users who prefer to learn by exploring and want +only a brief orientation to get started. Later sections provide a more +thorough introduction to the environment, with helpful hints and +shortcuts. If you are impatient to get started, skim this section, go +play for a bit, then come back and peruse the other sections of this +guide as needed. + + + + +&kde; provides a highly configurable desktop environment. This +overview assumes that you are using the default environment. + + + + +The &kde; Desktop + +A typical &kde; desktop consists of several parts: + + + +A panel at the bottom of the screen, used +to start applications and switch between desktops. Among other things, it +contains the &kmenu;, a large &kicon; +which displays a menu of applications to start when clicked. + + + + + +A taskbar, by default embedded in the panel, used +to switch between and manage currently running applications. Click on an +application on the taskbar to switch to the application. + + + + + +The desktop itself, on which frequently used +files and folders may be placed. &kde; provides multiple desktops, +each of which has its own windows. Click on the numbered buttons on +the panel to switch between desktops. + + + + + + + +Ready, Set, Go! + +Here are a few quick tips to get you up and running. + + + + +To start an application, click on the &kicon; button on +the panel (called the &kmenu;) +and choose an item from the menu. + + + + +Click the icon that looks like a picture of a house on +the panel to access the files in your home folder using +&konqueror;, &kde;'s File Manager utility. + + + +Choose K menu +System +Konsole to get a &UNIX; +command prompt, or press &Alt; +F2 to get a mini command prompt window to +execute a single command. + + + + + +Choose the Control Center +item on the &kmenu; +to configure &kde;. + + + + + +Press &Alt;Tab to +switch between applications and &Ctrl;Tab to switch between +desktops using the keyboard. + + + + + +Use the &RMB; mouse button to access context menus for the panel, +desktop, and most &kde; applications. + + + + + + + + +Launching Applications + + +Using the &kmenu; and the Panel + + +At the bottom of the screen you will find the desktop panel, which is called +&kicker;. You use the panel to launch applications. Have a look at the +button on the left with a large &kicon;. + + + +This button is called the &kmenu;. It has +a small arrow on the top to indicate that it will pop up a menu if you +click on it. Just do it! The popup offers you easy access to all &kde; +applications installed on your computer system. + + + +Customizing &kicker; + + + +If you use one application or tool very often, then you may want to have even faster +access to it. In this case you can add a single application or an entire sub-menu of the +&kmenu; as a special quick-launch button on the panel. If you want to reach an application +directly via a launch button, click with the &RMB; either on a clear space on the panel or on the +&kmenu; icon. Select Panel Menu Add Application to Panel... + and then navigate to the application or menu you would like to add to +the panel. + + + +You can add an entire menu this way, or one of the &kicon; +button sub-menus. For example, if you have &koffice; installed and +want quick access to all the &koffice; applications, without having to +navigate through the &kmenu;, then instead of choosing an +application, click on the Add this menu menu +entry. Now you will have instant access to all the &koffice; +applications, without having to put an icon for each on the panel. + + + + +You can move all items of the panel around with the +Move command of the context menu. Just click +with the third mouse button (the +third mouse button is normally the +right button, but if you have configured your +mouse differently, for example for left-handers, it might also be the +left one). A menu will pop up where you can +choose Move. Now move the mouse and see how +the icon follows while still staying on the panel. When you are done, +simply hit the first mouse button (by default +the left one). As you may have noticed, +there is also a menu entry Remove in case you +are tired of a certain launch button on your desktop. + + + + + + +Using Context menus + + +This leads us to another interesting topic: in many places, you can +click the right mouse button to display a +context menu with choices that are applicable to +the item you clicked. It is therefore always a good idea to try out the +third mouse button on something, if you do +not know what to do with it. Even the background of the desktops has +such a menu! + + + + + +Other Panel features + + +There are other interesting things possible with the panel. One +may be important if you have a low resolution on your monitor: it is +the hide-and-show function, activated by clicking on the +small arrowed button, which is at one or both ends of the panel. + + + +Perhaps you just do not like the panel extending the full width of the +screen. That's easily changed! &RMB; on an empty space in the panel, +and choose Configure Panel.... In the &kcontrolcenter; +dialog that pops up, you can choose Length on +the Appearance tab, and use the slider there to set +the panel to less than 100% width. + + + +If you're following along, and have that dialog open anyway, then feel +free to play with all the options, and use the +Apply to see the effect they have. You can +easily reset everything to the default configuration, by simply pressing +the Use Defaults button. + + + +By the way, if you are not sure what a certain button does in &kde;, +just move the mouse pointer over it and wait for a short while: &kde; +has a built-in mini context help, called tool tips, which +explains the functionality of such controls in a few words. + + + + + + + +But I want my command line back! + + +Just calm down, there is nothing to fear. &kde; does not want to take your +beloved (and sometimes very effective) command line away from you. You can move +your files with the desktop, but you can also use the &UNIX; commands you are +accustomed to. In fact,&kde; puts command line power at your fingertips, +in perhaps some surprising places. + + + +&kde; provides a very sophisticated command line window called +&konsole;. Choose K menu +System +Konsole to start it. This may +be something you want on your panel: luckily it's already there in the +default configuration! + + + +Sometimes, you only want to enter one command on the command line. In +these cases, you do not need a full-blown terminal. Just hit +&Alt;F2 and you get a +small command line where you can enter one command. The command line +window will disappear afterwards, but it remembers your command. + + + +When you pop up this window (which we call +minicli by the way) and hit the Up +arrow, you can browse through all the commands you have +previously entered. Also, you can enter &URL;s in +minicli to open a &konqueror; window with +the specified &URL;. + + + +&konqueror; and the editor &kate; can both display terminal windows, +which behave just like &konsole;. In &konqueror;, you can turn this +on with the menu choice +WindowShow Terminal +Emulator. The embedded terminal will display +at the bottom of your &konqueror; window, and the really clever thing +is that it will follow your clicks in the file manager view, changing +folder as you do. In &kate; you can display a terminal with the +menu choice SettingsShow +Console. + + + + +To display a &UNIX; man page, enter +man:command +in minicli, where command +is the name of a &UNIX; command. + + + + + +To search for a word or words on the Google search engine, you can try entering +gg:word or +words. There are a whole lot more of these +shortcut commands, and you can even add your own! Take a look in +&kcontrolcenter;, in the tab Web Browsing + Enhanced Browsing. + + + + +Finally, there's a way to have your command line always available, no +matter what you're doing - add one to your &kicker; panel! + + +Simply &RMB; click on an empty space in the panel and choose +Add Applet to Panel.... In the dialog that appears, +scroll down until you see the Run Command list item. Select +it with the &LMB; and click Add to Panel. This will embed a mini-cli +directly into your panel, complete with command history. + + +So, in conclusion, the command line is never far from view when you're +using &kde;. + + + + + + +Working with Windows + + +If you have not already done so, start an application using the &kmenu;; say, +Find Files. + + + +A window! What now? + + +Well, usually people work inside windows, but +sometimes you may want to manipulate windows. Here's a quick overview +of some of the most common window related functions: + + + + +Move a window + + +Drag the window's title bar, or hold the &Alt; key down +and drag anywhere in the window. + + + + + +Resize a window: + + +Drag the window's border, or hold the &Alt; key down and drag with the +&RMB; anywhere in the window. + + + + + +Maximize a window + + +Click the maximize button in the titlebar (in the default decoration it +is the square, next to the X) to make the window fill the screen, or if +the window is already maximized, to shrink it back to its original +size. Clicking with the &MMB; maximizes the window vertically, and with +the &RMB;, horizontally. + + + + + +Iconify a window + + +Click the Minimize button in the titlebar (next to Maximize) +to hide the window. Restore it by clicking on the window's icon in the +taskbar. + + + + + +Switch between windows + + +Aside from the usual mouse click to switch to another window, +you can use &Alt; +Tab to switch windows. See below for more +techniques. + + + + + + +Titlebar buttons + + +&kde; windows have some pretty standard buttons on their titlebars which +give you fast access to some common operations. The default button +layout looks like this: + + + +On the left side: + + +A Menu button. This usually shows a mini icon for the application. Click +on it to get a window operations menu. Shortcut: &Alt;F3 opens the window +menu. + + + + + + +On the right side: + + +A Minimise button. + + + + + +A Maximize button. + + + + + +A Close button. This closes the window. Shortcut: &Alt;F4. + + + + + + + +Switching between windows + + +Now that we know how to deal with windows, we encourage you to open +some other windows using the panel, since we will now discuss how to +switch between different windows. Since this is such a common +activity, &kde; offers several ways to do it; pick your favorite! + + + +Many window systems require you to click the mouse in another window +to begin using it. This is &kde;'s default behavior, termed +Click To Focus focus policy. But you can also configure +your desktop in a way that moving the mouse pointer on to a window will +activate it. This is called Focus Follows Mouse. If you +select this policy using the &kde; Control +Center, the window under the mouse pointer is always the active +one. It does not necessarily come to the front automatically, but you +can still click on to the titlebar or the border of a window or, a +&kde; special, you can use the &Alt; key and click the &MMB; +anywhere on the window to raise it. + + + +Here are some other methods to switch windows: + + + + + +Pick a window from the window list menu. To open +the menu, click the &MMB; on +an empty area of the desktop, or click the icon with several windows +on the panel, or finally click the up arrow at the left hand end of +the taskbar in the panel. + + + + + +Hold down the &Alt; key and press Tab to cycle through +the windows. + + + + + +Use the taskbar (see below). + + + + + + + + +Using the Taskbar + + +The taskbar displays a list of small icons, one +for each window on the desktop. In the default &kde; setup the taskbar +is located inside the panel, but it can also be located at the top or +the bottom of the screen. + + +The taskbar is very powerful. In the default configuration, if you +have more than one window from the same application open, they will be +grouped, so that you see one icon per application in +the taskbar. + +A simple &LMB; +click on the taskbar button will pop up a list of the open windows for +that application and you can choose the window you want to +use. Choosing one of these entries with the +left will bring you to the selected +window immediately. Click on a taskbar entry with the +right and you will see a menu allowing you +to operate on all the windows grouped under that icon, or each window +individually. + + +You can choose to see all the windows on all the desktops in your +taskbar, no matter which desktop you are currently viewing, or to only +see the icons for the desktop you are looking at. You can also choose +to ungroup the icons, so that each open window will have its own icon +in the taskbar. These and many more options are available simply by +right clicking on the taskbar handle (the small textured bar at the +left hand side) and choosing Configure Taskbar.... + + + +The icons on the taskbar resize themselves to make room for +applications, so you can fit many more applications than you might +think. Making the panel wider will let the taskbar icons take on a row +and column layout, but they will still resize to fit more icons. + + + + + +Using Virtual Desktops + + +Now, what was that sticky thing? + + + +It may happen that you have more windows open than space on your +desktop. In this case you have three possibilities: + + + + + +Leave all windows open (cluttered desktop) + + + + + +Iconify those windows which you do not need at present and use +the taskbar or &Alt; +Tab to switch between them +(still a bit confusing and much work!) + + + + + +Recommended: Do what a real operating system does if there is not enough +physical memory: Use virtual memory, in this case virtual desktops. + + + + + +The third option is the way to go! &kde; can handle several different desktops, +each with its own windows. The default configuration provides four +desktops. You can switch between the virtual desktops easily with a +click on one of the desktop buttons on the panel. Also &Ctrl;F1...F4 will send you +to the corresponding desktop immediately, or &Ctrl; Tab will cycle through +the desktops. + + + +Virtual desktops are very nice. But sometimes you want a window to be +present on every desktop. This could be, for example, +a small chat window, an alarm clock or whatever. In this case you can +use the above mentioned sticky button which will pin the +window on the background so that it will appear on every virtual +desktop. + + + +The sticky button can also be used to move a window from one virtual +desktop to another one: push the sticky pin on the window, switch to a +different desktop, and release the pin by pushing it again. You can +achieve the same result by using the context popup menu of the +window's entry in the taskbar (menu item To Current +Desktop) or the To Desktop +option on the window operations menu. + + + + + + +Managing your files + + + + +A common metaphor of graphical desktops is the use of folders to +represent folders on your hard disk. Folders contain files and +other folders. A &kde; application called &konqueror;, the K File +Manager, uses this metaphor to help you manage your files. + + + +Using &konqueror; + + +The first time you start &kde;, a window with lots of icons in it +appears. This is a &konqueror; window displaying the files in your +home folder (the area where your personal files are stored). The +pathname of the folder is displayed under the window's tool bar. If +you do not see such a window now, click the icon on the panel that +looks like a folder with a picture of a house. + + + +To open a file or folder, simply click it once with the &LMB;. +You can also choose +WindowShow +Navigation Panel from the menu to display the folder +hierarchy for more direct navigation. Or you can edit the path +displayed under the toolbar to get to a specific folder quickly. + + + +Opening Files + + +&kde; comes with a set of applications to view and edit files of many +common types, and when you click a file containing, say, a document +or image, &konqueror; will start the appropriate application to +display the file. If it does not know what application to start to open +a file you clicked, &konqueror; will prompt you for the name of the +application to run, and when you have chosen, &konqueror; will offer +to remember your choice for the next time you open a file of that type. + + + + +&konqueror; uses MIME types to associate +files with applications. + + + + + + +Dragging and Dropping Icons + + +To copy or move a file, simply drag its icon to the desktop, to +another &konqueror; window, or to a folder icon. When you release the +button, &konqueror; displays a menu to allow you to choose to copy, +move, or create a link to the file. + + + + +Note that if you choose to create a link, &kde; creates a &UNIX; +symbolic link (not a hard link), so if you move or delete the original +file, the link will be broken. + + + + +Most &kde; applications also support drag and drop operations: you can +drag an icon on to a window of a running application, or on to an icon of +an application that is not started, to have the application open the +file. Try it! + + + + + +Setting File Properties + + +To change file properties, such as its name and permissions, &RMB; +click the icon and choose Properties from +the menu. + + + + + + +Working with Archives and Networks + + +In the recent past, you needed special software to access files on the +Internet. Not any more! + + + +&kde; supports a technology called Network Transparent +Access (NTA) which allows you to work with +files on the other side of the world as easily as those on your local +hard disk. + + +For example, to access files on an &FTP; server, just choose +LocationOpen +Location from a &konqueror; menu, and enter +the URL of an &FTP; server. You can drag and drop +files to and from the folders on the server just as if they were on +your local disk. You'll even be able to open files on the &FTP; server +without having to manually copy them to your local disk (&kde; does it for you +when necessary). + + + + +Note that &konqueror; uses anonymous &FTP; access, which may restrict +your access to files on the &FTP; server. If you have an account on +the server, you can supply your user ID as part of +the URL, like this: +ftp://userid@server/folder + + + +&konqueror; will prompt you for your password, and if the login +succeeds, you will have full access to your files on the server. + + + + +If you are used to the +WinZip utility on +&Microsoft; &Windows;, then you will be happy to hear that &kde; can +look into tar archives, too. It treats such archives just like a +normal folder, and you can browse into the archive, open files, &etc; In +general, accessing files on the Internet and in archives should look +and feel just like accessing files on your local disk, except for +delays imposed by the network and extracting the archive. + + + + +Using Templates to access Applications and Devices + + +In &kde; it's easy to put icons on the panel or the desktop to access +your applications. It's just as easy to add icons to access other +items of interest. &kde; has templates for shortcuts to: + + + + + +Applications + + + + +Printers + + + + +Mountable Devices (⪚ floppy drives) + + + + +Internet resources (⪚ WWW documents, &FTP; +folders) + + + + +Documents for some of &kde;'s &koffice; applications. + + + + + +You can add any of these items to the desktop by &RMB; clicking where +you want the icon, and choosing Create New +and selecting the item you want to link to. + + + +Nearly every item in the &kmenu;, on the desktop, and on +the panel refers to a .desktop +file on disk. The .desktop file +specifies what icon to display, as well as specific information about +what the icon represents (an application, device, or +URL). You can drag any .desktop file to the panel to create a +quick-launch button. + + + + + +Mounting devices + + +&UNIX; provides access to storage devices other than the primary +hard disk through a process called +mounting. &kde; uses .desktop files to allow you to easily +mount, unmount, and access files on secondary storage devices such as +floppy drives and &cdrom; drives. + + + +As an example, here are the steps needed to create an icon to access +files on a floppy disk: + + + + +Many systems require you to be logged in as root to mount and unmount devices. + + + + + +Right click on the desktop and choose +Create +NewDevice +Floppy Device.... + + + + +On the General tab of the resulting dialog, change +the name to whatever you like, in the text box at the top. + + + + + +On the Device tab, enter /dev/fd0 (or the path to the floppy device +as it is named on your system) as the Device. + + + + +You can add a Mount Point here too. This should be +an existing folder, but empty. Common mount points are /mnt/floppy or /floppy, but you can just as easily have floppy +disks mounted on ~/mydisk if you +want. + + + + +Click the Unmounted Icon and select the picture +of a floppy disk without the green light. + + + + +Once you're happy with your choices, choose OK +and you are finished! + + + + + +Now, place a properly formatted floppy in the drive and click the +Floppy icon to have &kde; mount the floppy drive and display +the files on the disk. Before removing the disk from the drive, &RMB; +click the Floppy icon and choose +Unmount from the menu. + + + + + + + +Configuring your desktop + + +If you do not like something about the way the desktop looks or +operates, you can probably change it. &kde; is very configurable and you +can change almost every aspect of the appearance and the behavior of +your desktop. Unlike many other &UNIX; desktop environments, you do not +have to edit cryptic configuration files either (but you can if you +really want to!) You use the &kcontrolcenter;, a special program for +configuring your desktop. + + + +Using the <application>&kde; Control Center</application> + + +Launch the &kcontrolcenter; from the &kmenu;. +A window with two panes appears, displaying a list of +modules in the left pane. + + + +Open a module by clicking its name; a list of submodules will +appear. Then, click one of the submodule category names to edit its +configuration in the right pane. + + + +Changing the configuration is fairly straightforward. A help button is +available on each configuration panel to explain settings that are not +obvious. Each panel has buttons labeled Help, +Use Defaults, Apply, and +Reset, which work as follows: + + + + +Help + + +Displays a short help text in the left hand pane, including a link to a +longer manual for the module in question. + + + + + +Use Defaults + + +Sets all the options in the current module back to the default at the +time &kde; was installed. + + + + + +Apply + + +Applies the current settings in the currently open module. + + + + + +Reset + + +Resets the options to the state they were in when you opened the module. +If you have already used the Apply button, then +this button will reset the options to the state they were in when you +pressed Apply. + + + + + + + +If you make changes on one configuration panel and move to a different module +without clicking OK or Apply +first, &kcontrolcenter; will prompt you to ask whether your changes should be applied +first. + + + + + + + + +Logging out + + +We sincerely hope that using &kde; gives you so much fun and +pleasure that you never want to log out. But if you do, simply choose +K menu +Logout. + + + +There is also a logout button directly on the panel, which looks like a +small power button. Or you can press &Ctrl; +&Alt; Delete to log out. + + + +Session Management + + +When you log out, &kde; can remember which applications you had open, as +well as where all the windows were located, so that it can open them +for you the next time you log in. This feature is termed +Session Management. &kde;-aware applications will +restore themselves to the state they were in when you logged out. For +example, &kate; remembers which files you were editing. + + +Non-&kde; applications do not memorize their state on logout, and +&kde; will warn you to make sure that you have saved any important +data in them when you start to log out. + + + +To illustrate session management, choose +K menuEditors +Kate to start &kate;. Open +a text document to edit. Now log out and back in. You will observe +that &kate; will be restored to the exact same position on the screen, +including the right virtual desktop, and the document we left open in +&kate; before we logged out is opened again automatically. &kate; +will even remember whether you had unsaved changes to your document +before you logged out and will save them to the file you were working +on if you choose Save from the +File menu. + + + + + + +&kde;, an exciting Journey + + +We hope you enjoyed this brief tour of the K Desktop environment and +that this unique desktop environment will help you get your work done +faster and more comfortably than ever. + + + +Please remember that the &kde; project is not a commercial venture, +but rather a project run by volunteers from all over the world. We +would like to invite you to join the &kde; project and become part of +this unique network of people. If you are a programmer you might +consider helping us write &kde; applications. If you are an artist or +have experience with graphic design, consider creating icons sets, +color schemes, sound schemes and logos for &kde;. If you enjoy +writing we would love for you to join our documentation project. + + + +As you can see there are many ways in which you can help. You are +cordially invited to join this world-wide network of people dedicated +to making &kde; the best desktop environment for any computer. Please +visit www.kde.org for more +information. + + + +Welcome aboard on this exciting journey, + + +Your &kde; Team + + + + + +Credits + +Authors + + +Matthias Ettrich +ettrich@kde.org +Kalle Dahlheimer kalle@kde.org +Torben Weiss weis@kde.org +Bernd Wuebben wuebben@kde.org +Stephen Schaub sschaub@bju.edu - +Editor +Robert Williams rwilliams@kde.org - +Editor +Lauri Watts lauri@kde.org + + + + +&underFDL; + + + + + + + diff --git a/doc/userguide/Makefile.am b/doc/userguide/Makefile.am new file mode 100644 index 000000000..488634323 --- /dev/null +++ b/doc/userguide/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/userguide + diff --git a/doc/userguide/a-window.png b/doc/userguide/a-window.png new file mode 100644 index 000000000..3a0072f99 Binary files /dev/null and b/doc/userguide/a-window.png differ diff --git a/doc/userguide/accessibility.docbook b/doc/userguide/accessibility.docbook new file mode 100644 index 000000000..e3195635a --- /dev/null +++ b/doc/userguide/accessibility.docbook @@ -0,0 +1,168 @@ + + + + + + +Gary +Cramblitt + + + + +Accessibility + +Accessibility + +KDEAP (the &kde; Accessibility Project) aims to ensure that &kde;, as a desktop environment, is accessible to all users, including those of us with physical disabilities. In addition to the accessibility aids in the Control Center, &kde; has several other accessibility tools, which are available in the &kde;-Accessibility package. This package may not be installed on your computer; if it is not, you can download it from here: + + +kdeaccessibility-1.0.0.tar.gz, or +kdeaccessibility-1.0.0.tar.bz2 +MD5 +lsm file + + +For more information on the project, visit the &kde; Accessibility Home Page. + + +<application>KMouseTool</application> + +Mouseclicking +automatically + + + KMouseTool is a &kde; program, which clicks the mouse for you, so you + do not have to. KMouseTool works with any mouse or pointing device. + + + + + + + + KMouseTool + + + + +Related Information + MouseTool Website: http://mousetool.com + KMouseTool Handbook + + + + + +KMagnifier + +Magnifier + +KMagnifier (or kmag, to use its &UNIX; name) is a small utility for Linux to magnify + a part of the screen. It magnifies the area of the screen around the + mouse pointer or, optionally, a user-defined area. Additionally, it can save + a magnified screenshot to disk. + + + + + + + + + KMag + + + + +Related Information + Website: http://kmag.sourceforge.net + KMag Handbook + + + + + +<application>KMouth</application> + +Speech + +KMouth is a KDE program which enables people who cannot speak to let their + computer speak, ⪚ mutal people or people who have lost their voice. + It has a text-input field and speaks the sentences that you enter. It also has + support for user-defined phrasebooks. + + + + + + + + + First screenshot of KMouth + + + + + + + + + + Second screenshot of KMouth + + + + + + + + + + Third screenshot of KMouth + + + + +Related Information + Website: http://www.schmi-dt.de/kmouth/index.en.html + KMouth Handbook + + + + + +<application>KTTS</application> - Text-to-Speech + +KTTS is a &kde; application for the conversion of text into audible speech. Currently, since &kde; 3.4, you can use KTTS to speak any text from the &klipper;, the &kde; clipboard, any text from a plain text file (using &kate; or otherwise), speak any portion of text from a &HTML; page in &konqueror;, and much more. + +To get KTTS up-and-running you will need to start by running kttsmgr, the &kde; Text-to-Speech manager. + + + +Related Information + Website: http://accessibility.kde.org/developer/kttsd/ + KTTSD Handbook + + + + + + + diff --git a/doc/userguide/amarok-icon.png b/doc/userguide/amarok-icon.png new file mode 100644 index 000000000..575d9a274 Binary files /dev/null and b/doc/userguide/amarok-icon.png differ diff --git a/doc/userguide/amarok.png b/doc/userguide/amarok.png new file mode 100644 index 000000000..ddcb285bc Binary files /dev/null and b/doc/userguide/amarok.png differ diff --git a/doc/userguide/base-kde-applications.docbook b/doc/userguide/base-kde-applications.docbook new file mode 100644 index 000000000..863271b37 --- /dev/null +++ b/doc/userguide/base-kde-applications.docbook @@ -0,0 +1,441 @@ + + + + + +&Francis.Giannaros; +&Francis.Giannaros.mail; + + + + +The Base &kde; Applications + +What follows is a brief description of a few of the base &kde; applications. For more information on any of the applications you should check the links recommended with each respective entry. + + + + + + +Fundamentals + + + +&konqueror; + &kde;'s file manager, web browser, FTP client and much more. &konqueror; is the canvas for all the latest &kde; technology, from KIO slaves (which provide mechanisms for file access) to component embedding, allowing it to be a universal viewing application, capable of displaying various image files as well as documents. + + + Website: http://konqueror.org + View the handbook by typing help:/konqueror in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;. + + + + + + +&kate; + &kde;'s advanced multi-view text editor. &kate; is excellent for things such as viewing the &HTML; source of a webpage to handling advanced coding in C++, PHP and XML with its powerful syntax highlighting engine and code folding capabilities. &kate; is a very speedy application, being capable of opening huge text files in a matter of seconds, as well as allowing you to view a hefty amount of multiple views in order to see more instances of the same document and/or more documents at any particular time. + + + Website: http://kate.kde.org + &kate; Handbook + + + + + + + + + +&konsole; + The X terminal emulator for &kde;. &konsole;, like many &kde; applications, is extremely customizable; while you can create your own user sessions, you can also of course open &Linux; console sessions, shell sessions, as well as standard root and sudo sessions. + + + Website: http://konsole.kde.org + &konsole; Handbook + User Guide + + + + + + + +&kicker; + The &kde; Panel, used for handling your currently running applications, a pager allowing you to switch between desktops, quick launch buttons to act as application launchers and much more. + + + See for altering some of its settings. + &kicker; Handbook + + + + + + +kdcop + + A GUI front-end to the powerful &DCOP; (Desktop COmmunications Protocol). &DCOP; provides a comprehensive protocol for interprocess communication between &kde; applications. While this is increasingly useful to &kde; programmers, it is also beneficial to the ordinary user who would want to create a script, or, say, a SuperKaramba theme. + + + In the User Guide and + Other Documentation: http://developer.kde.org/documentation/library/kdeqt/dcop.html + + + + + + +&kcontrol; + The control center for the K Desktop Environment. You can alter a myriad of different things, ranging from themes, fonts and screensavers, to Internet, security and system administration. + + + See . + &kcontrol; Handbook + + + + + + +&khelpcenter; + The &kde; help system is used to provide access to the base &UNIX; help pages (man or info) as well as the native &kde; documentation provided by the &kde; documentation team or the application authors. You should be able to access all of the &kde; application handbooks from here. + + + &khelpcenter; Handbook + For information on the &kde; Documentation team, how to possibly join and help &kde;, see: http://kde.org/documentation + + + + + + + + +Related Information + http://kde-apps.org -- The largest directory of third-party &kde; applications. + As you may have noticed, a wealth of information is accessible from the respective handbooks themselves, which can be accessed either by using the help KIO slave in &konqueror; (that is, type help:/application in the Location toolbar), or by selecting it in the &khelpcenter;. + You can also likely find out quite a bit of information from the &kde; website, itself, at http://kde.org. + + + + + + + + +&Francis.Giannaros; +&Francis.Giannaros.mail; + + + + +Personal Information Management + +&kde; PIM (Personal Information Manager) is a sub-project of &kde;, and it aims to provide an application suite to manage personal information. It has several components, but these can all be brought under one application -- &kontact;, which is the personal information manager. Below is an overview of a few of its popular components; that is, a few of the applications that integrate into it. + + + +&kontact; + This serves as the medium by which the rest of the applications in &kde; PIM can integrate with one another. All of the applications in &kde; PIM can be displayed inside here, and you can easily choose which ones to display. It also contains a Summary page by which you can get a brief overview of events and information in the other components. + + + Website: http://kontact.kde.org + View the handbook by typing help:/kontact in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;. + + + + + + +&kmail; + The mail component. &kmail; comes with full IMAP, POP3 and SMTP support. Signing and encrypting of emails is permitted, and there are many comprehensive anti-spam functions available. A spell check can easily be used, &HTML; emails can be viewed appropriately, and there is an advanced search feature. + + + Website: http://kmail.kde.org + &kmail; Handbook + + + + + + +&korganizer; + A fully customizable organizer which constitutes as the calender component. &korganizer; provides management of events and tasks, alarm notification, web export, network transparent handling of data, group scheduling, import and export of calendar files, and much more. + + + Website: http://korganizer.kde.org + &korganizer; Handbook + + + + + + +&kaddressbook; + The contacts component. &kaddressbook; enables you to manage your contacts efficiently and comfortably; contacts can be easily exported and imported from a plethora of different address book standards, and it can be efficiently integrated with &kopete;, &kde;'s multi-protocol instant messenger. Other features include support for all international character sets and advanced search functions. + + + Website: http://pim.kde.org/components/kaddressbook.php + &kaddressbook; Handbook + + + + + + +&knotes; + A handy component which can serve to handle all your digital sticky notes. You can have them displayed on your desktop, they can be dragged n' dropped into emails, printed, or even be displayed after &kontact; is closed down. + + + Website: http://pim.kde.org/components/knotes.php + &knotes; Handbook + + + + + + +&knode; + The newsreader component. It is GNSKA (The Good Net-Keeping Seal of Approval) compliant, has support for MIME and multiple servers. + + + Website: http://knode.sourceforge.net/ + &knode; Handbook + + + + + + +&akregator; + A lightweight and fast program to display news items provided by feeds, supporting all commonly used versions of RSS and Atom feeds. Useful features include searching in article titles, management of feeds in folders and setting archiving preferences. + + Website: http://akregator.sourceforge.net + &akregator; Handbook + + + + + + + +Related Information + See http://kontact.kde.org and http://kdepim.kde.org for more information. + &kontact; Handbook + + + + + + +Network + +There are several network-related applications in &kde;. Below is a description of a few of these. + + + +&kopete; + A fully-featured and advanced IM (Instant Messaging) client, which has a number of protocols including MSN, Yahoo, and AIM. &kopete; can fetch display pictures, set aliases for particular persons, as well as run multiple IM sessions at any particular time. &kopete; is quite extensible, and has a comprehensive plugin system which comes with a searchable History of previous chats, statistics on a user's status, as well as a note system allowing you to create notes for each contact. + + Website: http://kopete.kde.org + &kopete; Handbook + + + + + +&kdict; + A &GUI; front-end to the DICT protocol. It enables you to search through dictionary databases for a word or phrase, then displays suitable definitions. + + &kdict; Handbook + The DICT Development Group: http://www.dict.org/bin/Dict. + + + + + +&kget; + A manager for your downloads which integrates with &konqueror;. &kget; allows you to group your downloads, pause and resume them, as well as several other things. + + + Website: http://kget.sourceforge.net + &kget; Handbook + + + + + + + +Related Information + Several more &kde; network applications can be found in the &kde; Extragear; see , under . + + + + + + +Office + +This includes all applications in the &koffice; suite. See for a summary of the components. + + + + + +Graphics + +&kde; has several graphics-related applications, ranging from PDF viewers to applications enabling you to take screenshots. Below is a delineation, as well as some related links, for a few of them. + + + + +KColorEdit + A small and handy application for editing color palettes, as well as color choosing and naming. Colors can be chosen by giving the RGB hex code, by choosing the color from a myriad of different colors in the program, or even by grabbing the precise color of any particular thing on your screen. + + + KColorEdit Handbook + + + + + +KPDF + An advanced PDF viewer, based on xpdf, for &kde;. KPDF contains a number of ways to search through the document (standard find dialog, thumbnail filter, etc.) and has other features such as hands-free reading. + + + Website: http://kpdf.kde.org + KPDF Handbook + + + + + +KView + An image viewer program which supports a number of different image filetypes including JPEG, GIF, PNG, TIFF and many others. Kview has full integration with &kde; and it can be embedded into &konqueror; for viewing image files on your diskdrive as well as your FTP site or webserver, using its &URL; open support. Other features include a few image manipulations such as zoom, rotate, grayscale and flip. + + + Website: http://www.ph.unimelb.edu.au/~ssk/kde/kview/ + KView Handbook + + + + + +&ksnapshot; + An application for taking screenshots. It is capable of capturing images of the whole desktop, a single window, or a selected region. The images can then be saved in a variety of formats, including JPG and PNG. + + + Website: http://www.ipso-facto.demon.co.uk/ksnapshot/ + &ksnapshot; Handbook + + + + + +&kolourpaint; + A simple and easy-to-use paint program, with features such as basic painting (drawing diagrams and finger painting), image manipulation and icon editing. + + + Website: http://kolourpaint.sourceforge.net + &kolourpaint; Handbook + + + + + + +&kooka; + An intuitive raster image scan program. &kooka; helps you to handle the most important scan parameters, find the correct image file format to save and manage your scanned images. + + + Website: http://kooka.kde.org + &kooka; Handbook + + + + + + + +Related Information + Several more advanced &kde; graphics applications can be found in the &kde; Extragear; under the , see for a list of a few of them. + + + + + +Multimedia + +A brief overview of a few of the multimedia-related applications below. + + + +&juk; + An easy-to-use music player for &kde;. &juk; is playlist and meta-data focused, allowing you to quickly search through the dynamic playlist provided. Some of the features include &CD; cover-art fetching from Google images, MusicBrainz integration for file identification over the Internet, and multiple audio backends, including &arts;, GStreamer and aKode. + + + Website: http://developer.kde.org/~wheeler/juk.html + &juk; Handbook + + + + + +&kmix; + An application that allows you to change the volume of your sound card, and it supports several sound drivers. Each mixer device is represented by a volume slider, and you have basic options such as to mute that particular mixer device. + + + &kmix; Handbook + + + + + +&noatun; + A media player capable of playing WAV, Ogg Vorbis, as well as DivX encoded AVIs and other media formats. &noatun; features audio effects, a six-band graphic equalizer, a full plugin architecture, network transparency, and various look and feels. + + + Website: http://noatun.kde.org + &noatun; Handbook + + + + + + + +Related Information + Several more advanced &kde; multimedia applications can be found in the &kde; Extragear; under the , see for a list of a few of them. + + + + + + + diff --git a/doc/userguide/browser-fine-tuning.docbook b/doc/userguide/browser-fine-tuning.docbook new file mode 100644 index 000000000..0a503b6bb --- /dev/null +++ b/doc/userguide/browser-fine-tuning.docbook @@ -0,0 +1,71 @@ + + + + + + +Fine Tuning your Browsing Experience + + +Using your own style for webpages + +Webpages come in every possible set of colors and fonts, and +sometimes this doesn't give the best result. For example, if you have +visual difficulties, it may be impossible to read certain combinations +of background and text colors. &konqueror; provides a way to choose +your own colors and apply them to all webpages. Here's how: + + +Open &konqueror; and go to +SettingsConfigure Konqueror.... + +In the configuration dialog that appears, select the +Stylesheets page on the left hand side. + +On this page, choose Use accessibility +stylesheet defined in "Customize" tab, then go to the +Customize tab, and choose the settings you prefer. + +Close all &konqueror; windows (you may need to restart +&kde; to be sure) and when you re-open them, your settings should be applied. + + + + + + + + + + + + diff --git a/doc/userguide/burning-cds.docbook b/doc/userguide/burning-cds.docbook new file mode 100644 index 000000000..901709ff4 --- /dev/null +++ b/doc/userguide/burning-cds.docbook @@ -0,0 +1,38 @@ + + + + + + +Burning CDs and DVDs + +Brief overview of k3b + + + + diff --git a/doc/userguide/control-center.docbook b/doc/userguide/control-center.docbook new file mode 100644 index 000000000..240046c73 --- /dev/null +++ b/doc/userguide/control-center.docbook @@ -0,0 +1,922 @@ + + + + + + +The &kcontrolcenter; + +&kcontrolcenter; +&kcontrol; +Configuration +Customization + + + + + +The &kcontrolcenter; +The &kcontrolcenter; + + +The &kcontrolcenter; is the place to go to change any settings that +affect the whole of your &kde; environment. You can open it using the +Control Center item in the &kmenu;, or with its +command-line name, kcontrol. + +The settings are divided into several major categories, which each +contain several pages of settings. To display a settings page, expand the +major category by clicking on the + button next to it, +and then click on the name of the page you want. The settings page then +appears on the right, and you can change settings to your heart's +content. No changes take effect until you click on the +Apply button. If you decide, after making some +changes, that you want to leave the settings as they were, just click on +Reset. + +If you need more help with a page, visit that page, then click on the +Help tab. You might also want to look at the +&kcontrolcenter; Handbook, which you can open with the +Help&kcontrolcenter; +Handbook. + + + + + + +&J.Hall; +&J.Hall.mail; + + + + +Appearance & Themes + +Here you will find settings that change the way your &kde; desktop and +applications look. + + + +Background + +This section controls the color or image that is set as your desktop +background. These settings can be applied to all virtual workspaces, or to +only a specific one. There are a range of background wallpapers that come +with &kde; or you can supply your own. + + + + +Colors + +This is where you can modify the colors for your kde applications. +There are a variety of color schemes installed with &kde; by default, and +you can find others at kde-look.org. You can also create your own. Here you +can also modify the contrast and choose whether you want your &kde; colors +to be applied to non-kde applications, for a more consistant overall +appearance. + + + + +Fonts + +Here you can control the various font settings for &kde; applications. +You can also modify here anti-aliasing settings, including what range of +fonts to exclude from anti-aliasing settings. + + + + +Icons + +This section is where you can manage your icon themes and other +settings related to icons. New icon themes can be downloaded from +kde-look.org, and installed here. Conversely, you can remove icon themes by +highlighting them in the list and clicking remove. You can also set icon +sizes for various uses in &kde; and effects to apply to icons. + + + + +Launch Feedback + +This is where you can modify what kind of cursor and/or taskbar +feedback you'd like for launching applications. You can also set the +duration of this feedback here. For example, the default setting is for a +bouncing cursor with a duration of 30 seconds, or when the application has +loaded. + + + + +Screen Saver + +Here you can configure options about your screensaver. You can +configure the timeout before it starts, and whether it requires a password +to unlock the screen. + + + + +Splash Screen + +This is where you can install, remove and test the splash screens that +display on &kde; startup. More splash screens can be downloaded from + + +http://www.kde-look.org. + + + + +Style + +This section allows you to modify your widget style. A variety of +styles come with &kde;, and more can be downloaded from http://www.kde-look.org. This is also +where you would enable or disable interface options such as transparent +menus, showing icons on buttons and tooltips. Some styles have more +configuration options than others. + + + + +Theme Manager + +This is where you can create and manage themes that are made up of +personalized settings. They are a combination of desktop background, colors, &kde; widget styles, icons, fonts and what Screensaver you'd like to display . This allows you to save your favorite +looks and apply them with the click of a mouse button. + + + + +Window Decorations + +Here you can configure your window decorations. You can modify the +style as well as place the buttons in custom positions. Some window +decorations will have more configuration options than others. + + + + + + +Related Information If &kcontrolcenter; +doesn't have the setting you want, you may need to edit a configuration file +manually. See for more +information about how to do this. + + +If you enjoy modifying the appearance of your &kde; desktop, +you can find plenty of themes and styles at kde-look.org. + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + +Desktop + +This is where you will find settings to configure the appearance and +behavior of your &kde; desktop. + + + +Behavior + +Here you can configure the behavior of your desktop. This is where +you would go to configure options such as showing or hiding desktop icons, +showing tooltips and icon layout. You can also specify if you would like to +see previews of particular filetypes on the desktop, and which devices you'd +like to see icons for. + + + + +Multiple Desktops + +This is where you would configure the number of virtual desktops or +workspaces you would like to have, and what you would like them to be +called. By default &kde; has 4 virtual desktops, and you can configure up to +20. You can also enable switching between virtual desktops using the scroll +button on your mouse. + + + + +Panels + +Here you can modify options to do with &kicker; and other &kde; +panels. Among the options are size, position, length and hiding. You can +also modify the appearance of the panel with transparency, background images +and icon zooming. This is also where you would configure various menu +options including what applications you'd like to show in your +&kmenu;. + + + + +Taskbar + +The Taskbar module allows you to configure options related to your +taskbar. You can configure whether to show windows from all desktops, +grouping of similar tasks and what actions you would like to assign to your +mouse buttons. + + + + +Window Behavior + +This is where you would configure options related to the behavior of +&kde;'s window manager, &kwin;. &kwin; is extremely configurable and has +advanced features such as focus stealing prevention and different focus +policies such as focus follows mouse. You can also configure what actions +you would like to bind to certain keys and mouse events. + + + + +Window-Specific Settings + +This is an advanced configuration dialog where you can set options for +the behavior of specific windows. There are many options here for the fine +tuning of your window layout, including what position on the screen you +would like certain windows to open to, and whether they should be shown on +the taskbar or pager. You can select windows by application, or even by +their specific role within an application. + + + + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + +Internet & Network + +This section is where you would configure settings to do with internet +and networking under &kde;. + + + +Connection Preferences + +Here you can set advanced networking options such as timeout values +for server connects. Usually you would leave these options at the defaults +unless you really knew what you were doing. + + + + +Desktop Sharing + +Desktop Sharing allows you to invite someone to share your session +with you, or can enable you to log in remotely to your machine from another +location. You would then use a VNC client like &kde;'s Remote Desktop +Connection application to control your desktop over the network. This is +extremely useful if you want someone to help you perform a task. + +Here you can create and manage invitations as well as set your +security policy for uninvited connections. You can also configure whether to +show a background image and which port for the service to 'listen' +on. + + + + +File Sharing + +File sharing allows you to configure Samba (&Microsoft; &Windows;) and +NFS (&UNIX;) file sharing. To make changes in this module +you need to have the root or administrator password. This is where you would +set up whether users are allowed to share files without knowing the root +password, and which users are allowed to do so. You can also configure which +folders you're like to be shared, using which type of sharing and who is +allowed to view these shares. + + + + +Local Network Browsing + +Here you can configure options related to browsing network shares in +&konqueror;. &konqueror; is able to browse a variety of network shares and +manipulate remote files as though they were on your local machine. You can +configure it to remember your preferred username and password for connecting +to &Windows; shares (Samba). You can also set what types of network shares +you would like to be able to browse, including &FTP;, NFS +and SMB. + + + + +Local Network Chat + +This module allows you to configure options relating to the &UNIX; +talk daemon. It is a very simple network chat program +that runs in a terminal, designed for chatting over a local area +network. Some of it's features are being able to set up an 'answering +machine' that will email to you messages left for you, and being able to +forward messages to another location. + + + + +Proxy + +This is where you would configure &kde; to connect to a proxy server +rather than directly to the internet. Once again you would generally leave +these options at their defaults unless you really knew what you were +doing. If you do use a proxy server your network administrator will be able +to tell you what details to fill in here. + + + + +Samba + +The Samba Configuration module requires the +root or administrator password. It is +an advanced configuration tool that allows you to control Samba's security, +shares, users and printers in an intuitive graphical interface. This is a +very powerful tool with support for configuring everything from simple file +and printer sharing, to using your Samba server as a &Windows; NT Domain +Controller. + + + + +Service Discovery + +You can set up services browsing with ZeroConf. You can for example browse +your local network using multicast DNS. + + + + +Web Browser + +This module is where you would configure options relating to +&konqueror; as a web browser. The usual options you would expect from a +web browser, such as cookie configuration, cache and history can be found +here as well as sections to modify keyboard shortcuts, plugins and +fonts. + + + + +Wireless Network + +Here you can set up different profiles for your Wireless card, to be +able to quickly switch settings if you connect to multiple networks. You can +select a profile to be loaded on &kde; startup. + + + + + + + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + + +&kde; Components + +This section is where you can modify advanced &kde; options such as +file associations and default applications. + + + +Component Chooser + +The component chooser allows you to select the default +applications you would like to use for various services. Here you can define +what Email Client, Embedded Text Editor, Instant Messenger, Terminal +Emulator and Web Browser to use. If you prefer to use +Xterm, Vim or +Mozilla, this is the place to specify those +preferences. + + + +File Associations + +This is where you configure everything to do with file +associations. Here you can select a filetype, and choose what applications +you would like to be able to open it with. You can also select which icon +you would like to represent each filetype, and whether to show it in an +embedded or a separate viewer. + + + +File Manager + +Here you can configure the behavior of &konqueror; in file +manager mode. Among the options are fonts and font sizes, previews over +various network protocols and context menus. &konqueror; is an extremely +powerful and configurable file management tool with a plethora of +options. For more information, consult the &konqueror; handbook. + + + +KDE Performance + +Here are settings related to the memory usage of +&konqueror;. Minimize Memory Usage allows you to +control whether separate instances of &konqueror; will open or whether all +new &konqueror; windows connect to the same instance. This has the effect of +reducing memory usage. You can also select whether to pre-load &konqueror; +after &kde; startup, to reduce start times. + + + +KDE Resources Configuration + +To be written + + + +Service Manager + +The Service Manager module displays a static list of +services that are started on demand, and a second list of services that can +be manipulated by the user. The services in the first list cannot be +modified or changed. The services in the second list you can enable or +disable a service loading at start up, and manually start and stop +services. + + + +Session Manager + +Here you can configure how you would like &kde; to handle +sessions. You can configure &kde; to remember your previous session and +restore the applications you were using the next time you log in. You can +also specify individual applications to exclude from being restored, or +disable restoring sessions on login entirely. + + + +Spell Checker + +This module allows you to configure the &kde; Spell +checker. It allows you to modify what spell checker to use, what types of +error to check for and also what default dictionary to use. &kde; supports +the use of both ASpell and +ISpell. + + + + +Vim Component Configuration + +This module allows you to configure the use of +Vim as an embeddable component. You need to have +a recent version of Gvim or +Kvim installed for this. You can configure the +appearance of the editor as well as which vim binary to +use. + + + + + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + +Peripherals + +This section is where you would change settings related to peripheral +devices such as keyboards and joysticks. + + +Display + +Here you can modify settings to do with the size, +orientation and refresh rate of your display, and whether you would like +these settings to be applied on &kde; startup. On the Power +Control tab, you can configure your power management options for +this screen such as blanking. + + +Joystick + +This section allows you to configure your joystick and test +that it is working properly. You can also calibrate your joystick here, and +manually specify the joystick device if it is not autodetected correctly. + + + +Keyboard + +This module allows you to configure basic keyboard settings. +These include keyboard repeat delay and rate, and what state you would +prefer numlock to be on KDE startup. + + +Mouse + +Here is where you can configure settings to do with your +mouse device. You can switch the button order, reverse the scroll direction +or modify the behaviour of clickable icons. You may also preview, install +and select cursor themes. The Advanced tab allows you +to fine tune your mouse settings further. + + +Printers + + This dialog allows you to configure printers using a +variety of print systems. You can add local and remote printers, check +current jobs and look at printer properties. + + + + + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + + +Power Control + +This section has a single module, Laptop Battery. +Here you can configure the appearance and behaviour of the Klaptopdaemon +battery monitor. You can select battery icons to represent different power states, and set up +notification of certain events. In the case that your battery runs down to a critical level, you can +configure the daemon to suspend or shutdown your laptop, to save you from losing data. + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + + +Regional & Accessibility +This section is where you can configure options to do with region +and locale, and also acessibility related options for disabled +persons. + + + +Accessibility + +Here is where you can configure options for users who have +difficulty hearing system sounds or using a keyboard. You can configure the +system bell to use a visual signal, such as flashing the screen or inverting +screen colors. You can also configure keyboard accessibility options such +as sticky keys and slow keys. + + +Country/Region & Language + +This module allows you to configure options that are +specific to your location such as language, currency and date format. To +make available more languages, install the kde-i18n packages for your +distribution. + + +Input Actions + +Here is where you would configure input actions, such as +mouse gestures and keyboard shotcuts for launching applications and running +commands. + + +Keyboard Layout + +This module is where you would configure +Kxkb, a keyboard layout switching utility that +uses the &X-Window; xkb extension. It allows you to switch between different +layouts using a tray indicator or a keyboard shortcut. You can +enable/disable keyboard layouts through this dialog, and add more. Some of +the more powerful features are the ability to configure switching of layouts +globally, per application or per window. + + +Keyboard Shortcuts + +Here you can configure global &kde; keyboard +shortcuts. There are several predefined shortcut schemes you can use if you +are more used to another windowing environment, like &Windows; or +&MacOS;. If you prefer, you can customise your own scheme and modifier keys. + + + + + + + + + + + + + + +&Anne-Marie.Mahfouf; +&Anne-Marie.Mahfouf.mail; + + +Javier +Martín Diez + + +Rocco Stanzione + + + + +Security & Privacy + +This section is where you can configure options related to +security and privacy such as the use of cryptography, enabling the KDE +wallet, setting your identity and managing caches. + + +Crypto +This module allows you to configure SSl for use with most +KDE applications, as well as manage your personal certificates +and the known certificate authorities. + + +KDE Wallet + +Here you can change your KDE Wallet Manager settings. + +KDE Wallet aims to provide secure storage for passwords and web form data. +You can group different passwords in different wallets, and each one will only +be opened with a master password (which you should never forget!). The +default wallet is named "kdewallet", and you can either create a new wallet +for your local passwords or accept the default wallet for all data in +the "Automatic Wallet Selection" section. + +KDE programs like Konqueror, Kmail and Kopete are fully compatible with +the KDE Wallet Manager. All of them will ask at least once for permission to +access to actual wallet. You can give different access levels, such as "always +allow", "allow once", etc. If you want to change that access level, you can do +it from the "Access Control" tab by deleting the program entry and selecting a +new preference the next time that application requests access to the +wallet. + + + + Wallet Preferences + + To enable the KDE wallet subsystem, check the +Enable the KDE wallet subsystem box. +Unchecking this box will disable the KDE Wallet on your system. + +By default, KDE Wallet Manager is kept opened until the +user session is closed, but you can change that in the Close +Wallet section to close it when unused for a time, when a screen +saver starts or when the last application stops using it. + +As you can have several wallets, Automatic Wallet +Selection allows you start KDE with a given wallet. + +KDE Wallet will appear in your system tray by default, but you can hide +it. Uncheck Show manager in the system tray to keep it +always hidden, or check Hide system tray icon when last wallet +closes to hide it only when all wallets are closed. These items are +in the Wallet Manager section. + + + +Access Control + +You can set here what policy you want for your +KDE applications, regarding to the wallet use. + + + + + + + +Password & User Account +You can change here your personal information +which will be used in mail programs and word processors. You +can change your login password by clicking the Change +Password... button. + + +Privacy +This module allows you to erase traces which +KDE leaves on your system such as command histories or +browser caches. + + + + + + + + + + + + +&J.Hall; +&J.Hall.mail; + + + + +System Administration +This module allows you to configure aspects of your system such as +the bootloader, the kernel and helps you perform essential system tasks. Most of these +sections will require the root or Administrator password to effect changes. + + + +Boot Manager (LILO) +If you use the popular bootloader +LILO this section will allow you to configure it. +You can configure the location to install the bootloader to, set the timeout +on the LILO boot screen as well as add or modify +kernel images for the boot list. + + + + +Date & Time +This configuration module allows you to configure the system date and time +settings. You can set the date, time, and also the current time zone. These settings will be applied system-wide. + + + +Font Installer +Here is where you would configure both personal and system-wide fonts. +This dialog allows you to install new fonts, delete old ones and preview the fonts you +have installed. By default, it displays personal fonts. To modify system-wide fonts click the Administrator Mode button. + + +IBM Thinkpad Laptop +This configuration module allows you to configure the special keys on an IBM thinkpad + laptop. You will need the nvram module to use these features. + + +Linux Kernel +If you run &kde; on &Linux; there is a &kcontrol; module to create or modify +configuration files for a &Linux; kernel. This configurator is compatible with kernels previous to 2.5. + + +Login Manager +This module allows you to configure the &kde; login manager, &kdm;. &kdm; is +a powerful login manager with a large range of options. It supports user switching, remote graphical logins and has a fully customizable appearance. For more information, see the &kdm; handbook. + + +Paths +This dialog allows you to configure the default locations where certain +important files are kept. The Desktop directory contains all the files on your desktop. The Autostart directory contains files or links to files that you want run when &kde; starts, and the Documents directory is the default location &kde; applications will open or save documents to. + + +Sony Vaio Laptop +This configuration module allows you to configure features specific to +Sony Vaio laptops. If you have a Sony Vaio, you will have to install the sonypi +driver to use this section. + + + + + + + + + diff --git a/doc/userguide/creating-graphics.docbook b/doc/userguide/creating-graphics.docbook new file mode 100644 index 000000000..30407b0c4 --- /dev/null +++ b/doc/userguide/creating-graphics.docbook @@ -0,0 +1,48 @@ + + + + + + +Creating Graphics + +How to create graphics with &kde; apps.. (ok, maybe not) + + + + + + + + + + diff --git a/doc/userguide/credits-and-license.docbook b/doc/userguide/credits-and-license.docbook new file mode 100644 index 000000000..19c9b2641 --- /dev/null +++ b/doc/userguide/credits-and-license.docbook @@ -0,0 +1,315 @@ + +Credits + +&kde; is written by and copyright The &kde; Team. + + +This document is copyright 2006 The &kde; Documentation +Team. Individual credits are as follows: + + + +Tom Albers tomalbers@kde.nl + + + +Wrote . + + + + + + + +Waldo Bastian bastian@kde.org + + + +Wrote the notes which became . + + + + + + + +Gardner Bell gbell72@rogers.com + + + +Wrote . + +Wrote . + + + + + + + +Gary Cramblitt garycramblitt@comcast.net + + + +Wrote . + + + + + + + +David Faure faure@kde.org + + + +Wrote . + + + + + + + +Nicolas Goutte goutte@kde.org + + + +Wrote . + + + + + + + +&Francis.Giannaros; &Francis.Giannaros.mail; + + + + Proofreading and update on various parts. + Wrote . + Wrote . + Wrote . + Wrote . + Re-wrote . + Wrote . + + + + + + +Adriaan de Groot groot@kde.org + + + +Wrote . + +Wrote . + + + + + + + +J Hall jes.hall@kdemail.net + + + +Wrote . + +Wrote . + +Wrote . + +Wrote . + +Wrote . + +Wrote . + +Wrote . + +Wrote . + + + + + + + +&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; + + + + Proofreading and update on various parts. + + + + + + +&Richard.J.Moore; &Richard.J.Moore.mail; + + + +Wrote the kstart and +ksystraycmd sections. + + + + + + + + +Peter Nuttall p.s.nuttall@dur.ac.uk + + + +Wrote . + + + + + + + +Steven Robson s.a.robson@sms.ed.ac.uk + + + +Took the screenshots for , , and . + + + + + + +&Philip.Rodrigues; &Philip.Rodrigues.mail; + + + +Reviewing and proofreading. + +Wrote . + +Wrote . + +Wrote . + +Wrote . + +Marked up parts of . + + + + + + + +Deepak Sarda antrix@gmail.com + + + +Wrote . + + + + + + + +Robert Stoffers robert_angie@ozemail.com.au + + + +Wrote . + + + + + + + +Juan Carlos Torres carlosdgtorres@gmail.com + + + +Wrote . + + + + + + + +Simon Vermeersch titeuf@ph34rus.org + + + +Wrote . + + + + + + +&Lauri.Watts; &Lauri.Watts.mail; + + + +Wrote the outline. + +Wrote . + +Marked up parts of . + + + + + + +Christian Weickhmann +christian.weickhmann@gmx.de + + + +Wrote . + +Wrote . + + + + + + + + + + + diff --git a/doc/userguide/customizing-desktop.docbook b/doc/userguide/customizing-desktop.docbook new file mode 100644 index 000000000..eb427d599 --- /dev/null +++ b/doc/userguide/customizing-desktop.docbook @@ -0,0 +1,365 @@ + + + + +Juan Carlos +Torres + + + + +Customizing the Appearance of your &kde; Desktop + +Changing the appearance of your &kde; desktop can be done quite easily and +flexibly by either individually controlling different parts of the visual +appearance or by using a predefined theme. This guide explains the various +customizable parts of &kde; and how to control their appearance. + + +Background +The desktop background, more commonly known as the wallpaper, allows you +to display certain images on your desktop. The settings for the background are +found in the &kcontrolcenter;, or by right-clicking +on the desktop and selecting Configure Desktop.... + +In &kde;, you have the option to use no picture, a single picture, or a +slideshow of images. If No picture is chosen to be the +desktop background, the Colors options are used instead. +You can also choose whether to use a single +background on all virtual desktops or to apply a different background for each +desktop. This is done by selecting All desktops or the +specific desktop name from the drop-down menu. + +Other background images can be downloaded using the +Get New Wallpapers button on the right or you can visit +the +Wallpapers section of the kde-look.org website. + + + +Colors +The Colors settings of the &kcontrolcenter; allow you to control the +colors that are used for various window elements, such as window titlebars, +window backgrounds, text, and buttons. You can change the color of each window +element by selecting the element from the drop down list and choosing a color +for it. You can then save your changes by clicking on +Save Scheme.... This will save your settings in a Color +Scheme file. Color schemes are text files, with a .kcsrc extension, that contain +entries for each window widget and its color, in RGB format. It is also very +easy to add color schemes that you have downloaded by clicking on +Import Scheme... and pointing to the .kcsrc file. With color schemes, you can save the +changes you have done in one convenient file or easily change to a predefined +color setting, without having to change each window element separately. + +Additional color schemes can be downloaded from the Color Schemes +section of kde-look.org. + + + +Icons +An icon theme contains the images used to represent actions, files, +devices, and applications. Managing icon themes is easily done through the Icons +module in the &kcontrolcenter;. Simply select the icon theme you want to use and +click on Apply to switch to the new theme. To install new +icon themes, all you need to do is to click on Install New +Theme... and browse to the location of the icon theme archive. There +is no need to extract the contents of the archive into a directory. In fact, the +Icons module only accepts archived icon themes. To remove an icon theme, simply +select the theme from the list and click on Remove Theme. +Note that you cannot remove the icon theme that you are currently using. You +need to switch to some other theme before the current one will become removable. +You also cannot remove icon themes that were installed by the administrator +(root) or by your distribution's +package manager. +Other icon themes can be found in the Icon Themes +subsection of kde-look.org. + + + +Splash Screen + + + + + +The default &kde; splash screen +The default &kde; splash screen + + +The splash screen is the animated image or screen that is displayed while +&kde; loads after you log in. Each user can have a different splash screen. +Changing the splash screen for the current user can be done in the Splash +Screen module of the &kcontrolcenter;. Select the splash screen you want to +use and click on Apply. You can also test what a splash +screen will look like by selecting the splash screen and clicking on +Test. Installing a new splash theme is very easy. Just +click on Add... and browse to the splash screen archive you +want to add. There is no need to extract the contents of the archive. Removing +splash screens is also easily done by selecting the splash screen and clicking +on Remove. Note that you cannot remove splash screens +installed by the administrator (root) +or by your distribution's package manager. + +Splash screen themes can be found on kde-look.org, in the Splash Screens +section. Take note that some splash screens require a specific &ksplash; +engine to be installed. + + + +Window Decorations +You can change the appearance of window borders, titlebars and buttons in +&kde; using window decorations. Some window decorations even have the capability +to apply effects such as translucency. Window decorations must be able to do all +these without sacrificing speed and performance. This is the reason why window +decorations come in source code that must be compiled, or as binary packages +that must be installed. Basically, Window decorations are plugins or small +programs that instruct &kwin;, &kde;'s Window Manager, +how to display window frames. + +In order to add a new window decoration, you need to compile it from +source code. If a binary package for your distribution or system is provided, +you simply need to install it using your distribution's package manager. Please +refer to your distribution's manual for instructions on how to do this. Once the +window decoration has been installed, it can be accessed in the Window +Decorations settings in the &kcontrolcenter;. In the +Window Decoration tab, +a list of installed window decorations can be seen in the drop down box. Simply +select the decoration you want to use and click on Apply. +Different window decorations have different capabilities and settings. Play +around with the different options available. The Buttons tab allows you to +control the buttons on the window titlebar. Enable the Use custom +titlebar button positions check box in order to rearrange, remove, or +add buttons. To add buttons to the titlebar, drag an item from the list to the +titlebar preview above it. To remove a button, drag the button from the titlebar +preview to the item list. Simply drag buttons in the titlebar preview to +rearrange them. + +While all window decorations need to be compiled from source code, some +window decorations can load pixmap-based theme files that do not need to be +compiled. &kde; ships with a pixmap-based window decoration called the IceWM +window decoration. Another pixmap-based window decoration is deKorator, +which can be found on kde-look.org. Please refer to your distribution's +documentation on how to install these. The advantage of using pixmap-based +window decorations is it is relatively easy to make themes for them, by using +images and editing a configuration file. The tradeoff is a slight loss of performance, +while this may be unnoticeable on very fast systems. + +To add an IceWM theme, select IceWM as the window decoration and click on +the Open &kde;'s IceWM theme folder link in the window +decoration description area. This will open a &konqueror; window +to $KDEHOME/share/apps/kwin/icewm-themes. +Extract your IceWM theme to this folder. The theme will then be added to +the list of IceWM themes. Select the theme you want to use and click on +Apply. + +To add a deKorator theme after you've installed deKorator, select +deKorator from the window decorations list and go to the Themes +tab. Click on Install New Theme and locate +your deKorator theme archive. Make sure that the version of the deKorator theme +matches the deKorator version installed on your system. Once the theme has been +added, select the theme you want to use and click on Set Theme +Paths. Click on Apply for the changes to +take effect. + +Some more window decorations are available at kde-look.org under the +Native &kde; 3.x and the +Native &kde; 3.2+ subsections. Themes for the IceWM and +deKorator window +decorations have their own subsections under the Window Decorations +category. + + + +Style +Widgets are the basic elements of a graphical user interface, such as +buttons, scrollbars, tabs, and menus. A widget style is a plugin or a small +program that instructs &kde; how widgets are displayed. Since widgets are the +very basic parts of an interface, they are frequently accessed and must be able +to respond very quickly. This is why widget styles must come as source code to +be compiled or as binary packages to be installed, just like window decorations. +Please refer to your distribution's documentation on how to compile from source +or install binary packages. + +Once a widget style has been installed, it will be added to the list of +available styles in the Style module in the &kcontrolcenter;. +The Style tab allows +you to select a widget style from the list and to configure it if the style has +a Configure... feature. Different styles have different options. A preview of the +selected style is available at the lower portion of the tab. The +Effects tab +controls different visual effects for some widgets like comboboxes and tooltips. +The Toolbar tab gives some options on the general appearance of toolbars. + +Additional widget styles can be found in the different &kde; subsections of the +Themes/Styles of kde-look.org. Take note that styles come in source +code or binary package forms. They are not &kde; theme files. + + + +&kde; Theme +&kde; allows you to save the different changes you made to your desktop's +appearance in one file, using the Theme Manager in &kcontrolcenter;. Once you +have set up your desktop the way you want, click on Create New +Theme.... Enter the details you want to give your theme, such as theme +name, author, version, &etc;, then click OK when done. +This will add your theme to the list of available themes and save your settings +in a &kde; theme. A &kde; theme (.kth file) +instructs &kde; on what window decoration, style, or color scheme to use for +that particular theme. To add a &kde; theme from an outside source, click on +Install New Theme... and locate the &kde; theme file. +Removing a theme is easily done by clicking on Remove +Theme. If you made changes to your theme, you have to either create +a new theme name for it, or remove the previous version first to be able to use +the same theme name. + +The following are the settings that are saved and indicated in a &kde; +Theme: + + + +Background + + + +Screen Saver + + + +Icon Theme + + + +System Notifications + + + +Color Scheme + + + +Cursor Theme + + + +Window Decoration + + + +&konqueror; background (File Management) + + + +Panel background + + + +Style + + + +Fonts + + + +One very important thing to consider when using or installing a &kde; +Theme is that it only indicates what settings to use for the above. A &kde; +Theme includes only system notifications, desktop background, panel background, +&konqueror; background, and the color scheme in its package. The other +components must be installed separately if they do not already come with +&kde;. + +&kde; Themes can be downloaded from the Theme-Manager +subsection of +kde-look.org, under the Themes/Styles section. + + + +Glossary + + + +Background +Background/wallpaper image or color for the +desktop + + + +Color Scheme +(.kcsrc) +Configuration file that indicates what colors to use +for certain widgets + + + +Icons +Images representing applications, files, +devices, &etc; + + + +Splash Screen +Animated image or screen that displays while &kde; +loads after logging in + + + +Window Decoration +Plugins or small programs that instruct the window +manager how to display window frames + + + +Style +Plugin or a small program that instructs &kde; +how widgets are displayed + + + +&kde; Theme +(.kth) +A file that contains instructions on what settings to use for +different GUI components + + + +Widgets +Basic elements that build up a graphical user +interface: buttons, scrollbars, menus, tabs, &etc; + + + + + + + + + diff --git a/doc/userguide/desktop.png b/doc/userguide/desktop.png new file mode 100644 index 000000000..c5e683f61 Binary files /dev/null and b/doc/userguide/desktop.png differ diff --git a/doc/userguide/email.docbook b/doc/userguide/email.docbook new file mode 100644 index 000000000..04e95c9b2 --- /dev/null +++ b/doc/userguide/email.docbook @@ -0,0 +1,254 @@ + + + + + +&Daniel.Naber; + + +&David.Rugge; + + + + + + +Getting Started with Email + +Emailgetting +started + +&kmail; + +&kde; features a powerful and easy-to-use email client called +&kmail;, which allows you to send, receive, and organize your email +quickly and efficiently. Let us look at how to set it up. If you have +any problems with this procedure, refer to the full &kmail; manual. + + +Information you will need before you start + +Many email settings can vary greatly depending on the setup of +your system, your ISP's configuration, or your local network +setup. You will need to find out some information before you can start +setting up your email: + + + +Your email address +This should be provided by your ISP or system administrator. + + + +Your username and password for your email account +The username is often the same as the part before the +@ symbol in your email address, but not always: check +with your ISP. + + + + + + +EmailSMTP +server +Your outgoing email (SMTP) server name and +details +Again, your ISP should have provided +you with this information. If not, you can try the form smtp.your-isp-name.com. + + + + + +EmailIMAP +server + +EmailPOP3 +server + +Your incoming email (IMAP or +POP) server name and details +If you do not have this information to hand, you can +try imap.your-isp-name.com +for IMAP or pop.your-isp-name.com +if you use POP3. + + + + +Once you have that information, you are ready to start setting +up &kmail;. Open &kmail; from the K menu (you can +find it in the Internet submenu, or use one +of the methods described in .) Once +&kmail; has opened, select the menu entry +SettingsConfigure KMail... +. The next sections describe how to use the dialog that +appears to set up &kmail;. + + + + +Setting your Identity + + +The settings in the Identities page are fairly +straightforward. Select the default identity and +click Modify.... Fill in the Your +name field with your full name (⪚ John +Doe) and, optionally, the +Organization field with the appropriate +information. + + +Next, fill in the Email address field with +your email address (⪚ john@example.net). + + +That is all for this dialog unless you want to use the more +advanced features (cryptography, a signature, &etc;). You can find +more information about these features in the full &kmail; +manual. Click on the OK button to close this +dialog, and move on to the next configuration page... + + + + +Setting up your Account + +Click on the Network icon to move to the +network configuration page. It contains the settings that +tell &kmail; how to send and receive your email messages. You will see +two tabs on the right-hand side: Sending and +Receiving. You need to set up both, so let us look +at them each in turn: + + +Sending Messages + +Emailsending + +The Sending tab provides a list of +ways to send messages. The first item in the list is the default +way to send messages. Using the Add... +button you can choose between two different ways of sending messages: +SMTP and +Sendmail. &Sendmail; here +means a local software installation — this has a +reputation of being difficult to set up, so if you do not already have a +working &Sendmail; configuration, choose +SMTP and fill in the Name +field with a descriptive name +(⪚ My Mail Account) +and the Host +field with the name and domain of your mail server +(⪚ smtp.provider.com). You will probably +not need to change the Port setting (the default is +25). + +A description of the other options can be found +in the full &kmail; manual. Click on OK to +close this dialog, and then click on the +Receiving tab. + + + + +Receiving Messages + +To set up an account so you can receive mail, press the +Add... button in the +Receiving tab. You will then be prompted for the +type of your email account; most users should select +POP3 or IMAP. If you wish to +use a different system, consult the &kmail; manual. + +You will then be presented with +the Add account window. First, fill in the +Name field to name your account. You can choose any name +you like. Login, Password, and +Host should be filled in with the information you +gathered earlier. You should not usually need to change the Port setting. + +You are now ready to send and receive mail. For +IMAP, just open your folders in the +folder tree in &kmail;'s main window. &kmail; then connects to your +server and displays the messages it finds. For POP3 use +FileCheck +Mail. + + + + + + +Testing your Setup + +Emailtesting + +First, you should send yourself a message to test your +configuration. To send a message, either hit &Ctrl;N, select the +New Message icon or select +the MessageNew +Message... menu item. The +composer window will appear. Fill in the +To: field with your email address and type +something in the Subject field. Send the message by +selecting Message Send +. + +To check your email, select +FileCheck +Mail. In the lower-right corner of the main +window, a progress bar will indicate how many messages are being +downloaded. If you receive the message you just sent, then +congratulations! If, however, you receive any error messages while +testing your setup, make sure that your network connection is working +and recheck your settings at +Settings Configure +&kmail;.... + + + +Related Information + +The &kmail; Handbook has full descriptions of advanced +email settings and so on. You can read it in the &khelpcenter; or by +entering help:/kmail in &konqueror;'s +Location bar. + + +The &kmail; website at http://kmail.kde.org contains +latest news, tips and tricks, and plenty more. + + + + + + + + + + + diff --git a/doc/userguide/extragear-applications.docbook b/doc/userguide/extragear-applications.docbook new file mode 100644 index 000000000..fd55985aa --- /dev/null +++ b/doc/userguide/extragear-applications.docbook @@ -0,0 +1,199 @@ + + + + + +&Francis.Giannaros; +&Francis.Giannaros.mail; + + + + +&kde; Extragear Applications + +These are applications that are directly associated with &kde;, the project, but do not appear and are not shipped with the main &kde; distribution. This can be down to a number of reasons, but a common case is either down to a duplication of functionality, or because they're simply too specialised. Perhaps the most popular occurence however is that the developers themselves may not want it to appear in the main &kde; distribution; choosing, rather, to handle their own release schedules. Nevertheless, the applications in Extragear are distinguished by &kde;, and many are increasingly popular. + + +Available in the &kde; Extragear + + + +Multimedia + + + +&amarok; + An advanced and comprehensive music player with the capability to play MP3, WAV, and OGG audio filetypes and others. There is not room here to mention all of &amarok;'s features, but by default, &amarok; can automatically fetch cover art, embed song lyrics, and display aesthetically pleasing visualizations. &amarok; remains, as much of &kde; does, highly customizable; it contains a powerful scripting interface, and the context browser can be stylised easily using &CSS;. &amarok; also supports several backends, including GStreamer, xine, NMM, MAS, aKode and &arts;. + + + Website: http://amarok.kde.org + View the handbook by typing help:/amarok in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;; if you do not already have &amarok; installed (and hence do not have the handbook), then you can view it online here. + + + + + + + + + +K3b + The definitive &CD;/DVD burning application for &kde;. With K3b you can create data, video, and audio (it comes with plugins for WAV, MP3, FLAC, and Ogg Vorbis) &CD;s. Projects can be saved and loaded, &CD;-ripping is supported, and you can appropriately make &CD;/DVD copies. + + + Extragear Summary: http://extragear.kde.org/apps/k3b/ + Website: http://k3b.org + K3b Handbook + + + + + + + + + + +Graphics + + +&digikam; + A photo management application which can conveniently organize and import digital photos. Features include complete tagging functionality, a plugin system, and a fully-featured comment system. &digikam; also makes use of KIPI (&kde; Image Plugin Interface), therefore contributing to the initiative to create a common plugin infrastructure, which allows development of image plugins that can be shared among graphical applications in &kde; (others include Gwenview, ShowImg and KimDaBa). + + + Website: http://digikam.org + &digikam; Handbook + + + + + + +Gwenview + Another advanced image viewer which can load and save all image formats supported by &kde;, as well as being able to display the GIMP (*.xcf) image filetype. Gwenview can perform a few graphical manipulations (rotate, mirroring) and has full support for KIO slaves (allowing you to use it via &FTP;). Other features also include file management operations, such as copy, paste, move and delete. + + + Website: http://gwenview.sourceforge.net/ + Gwenview Handbook + + + + + + + +ShowImg + A feature-rich image viewer, written for &kde;, which can display numerous formats, including JPEG, PNG, [animated] GIF and MNG. It consists of a tree-view frame, a directory/preview frame, and a view frame. The (larger) view frame can be exchanged with the (smaller) directory/preview frame. It can preview and display images from multiple directories and search for identical images. ShowImg also features a full-screen mode, zooming, sorting, drag and drop with &konqueror;, and support for images in compressed archives. + + + Website: http://www.jalix.org/projects/showimg/ + ShowImg Handbook + + + + + + +KimDaBa + KimDaBa (&kde; Image Database) attempts to provide an efficient solution for the organization of hundreds (or even thousands) of images. Having been highly optimized for annotating images, KimDaBa can help you locate an image in a matter of seconds. + + + Website: http://ktown.kde.org/kimdaba/ + KimDaBa Handbook + + + + + + + + + + + +Network + + +&konversation; + A fully-featured IRC client which supports per channel encoding, downloading and resuming file transfers, nick completion and highlighting, as well as tight integration with &kontact; and the rest of &kde;. + + + Website: http://konversation.kde.org + &konversation; Handbook + + + + + + +KMldonkey + A &kde; frontend for MLDonkey, a powerful P2P file-sharing tool. Highly configurable, real-time graphical bandwidth and network statistics, and much more. + + + Website: http://kmldonkey.org/ + KMldonkey Handbook + + + + + + +KNemo + Displays for every network interface an icon in the systray. Tooltips and an info dialog provide further information about the interface. Passive popups inform about interface changes and a traffic plotter is also integrated. + + + &kde;-apps entry: http://www.kde-apps.org/content/show.php?content=12956 + + + + + + + + + + + +Utilities + + +Filelight + A simple, yet ideal, application for graphically displaying where your diskpace is being used. Filelight displays this information by representing your filesystem as a set of concentric segmented-rings. + + + Website: http://www.methylblue.com/filelight/ + Filelight Handbook + + + + + + + +Krecipes + A &kde; recipe tool that can manage a recipe database with an easy-to-use interface. Full support for creating and removing ingredients as well as units; helps with diets, can calculate the amount of calories, vitamins, carbohydrates etc. Other advantages are its flexilibity and potential to extend further. + + + Website: http://http://krecipes.sourceforge.net + Krecipes Handbook + + + + + + + + + + + +Related Information + +Related Information and Links + It should be stressed that the above is but a preview of what is available in the &kde; extragear. To view all of the applications and utilities available there visit http://extragear.kde.org, where a briefer summary of each application is provided. + The handbooks for the majority of applications in extragear can be viewed from http://docs.kde.org. + Once again, you can find a plethora of other [third-party] &kde; applications at the popular http://kde-apps.org. + + + + \ No newline at end of file diff --git a/doc/userguide/file-sharing.docbook b/doc/userguide/file-sharing.docbook new file mode 100644 index 000000000..395e7b9e2 --- /dev/null +++ b/doc/userguide/file-sharing.docbook @@ -0,0 +1,109 @@ + + + + + +&Lauri.Watts; + + + + + +File Sharing + +How to share files with &kpf; + +File sharing +Shared Folders + +&kpf; provides simple file sharing using &HTTP; (the Hyper Text +Transfer Protocol,) which is the same protocol used by web sites to provide +data to your web browser. &kpf; is strictly a public fileserver, which means +that there are no access restrictions to shared files: whatever you select +for sharing is available to anyone. + +&kpf; is designed to be used for sharing files with friends, not to +act like a fully-fledged web server such as +Apache. &kpf; was primarily conceived as an easy +way to share files with others while chatting on IRC +(Internet Relay Chat, or chat rooms.) + +&kpf; runs as an applet inside &kicker;. This means that it takes up +little space on your screen and its status is always visible. To start the +&kpf; applet, right click on &kicker; and choose +Add Applet to Panel... to open the Add +Applet dialog. Select Public File Server and +click the Add to Panel button. + +&kpf; employs the concept of shared folders. You may choose one or +more folders to make public, and all files in that folder (and any +subfolders) will be shared. + +Please be extremely careful about which folders you share. Remember +that all files in the folder and its subfolders, including +hidden files (dotfiles to the techies) will be +made available to the world, so be careful not to share sensitive +information, such as passwords, cryptographic keys, your addressbook, +documents private to your organization, &etc;. + +Once &kpf; is running, you will see a square applet with a thin sunken +bevel and an icon depicting an hot air balloon. The +balloon is visible when no folders are being shared. + +To share a folder, right click on the +balloon icon and a pop-up menu will appear, containing only one item, +New Server.... Selecting this entry will cause a +wizard to appear, which will ask you a few simple +questions. Completing the questions will set up a folder for sharing. + +There is an alternative to using the applet directly when you want to +share a folder. &kpf; is integrated with &konqueror;. + +With &konqueror; open and displaying a folder, +right click on the background and bring up the +Properties dialog. On install, &kpf; added a +Sharing tab to this dialog. You will be offered the +option of starting &kpf; if it is not running. Choosing +Ok will send a signal to the &kpf; applet, asking it +to add a new share. + +For more detailed information, such as how to share different +directories to different people, see the &kpf; handbook. + + + + + + + + + + diff --git a/doc/userguide/font-installation.docbook b/doc/userguide/font-installation.docbook new file mode 100644 index 000000000..bca1a2308 --- /dev/null +++ b/doc/userguide/font-installation.docbook @@ -0,0 +1,79 @@ + + + + + + +Simon +Vermeersch + +titeuf@ph34rus.org + + + + +Fonts - Installing and Configuring + +Fonts + +Fonts are really easy to configure in &kde;. Open up the Control +Center (with K-MenuControl +Center) and choose +Font Installer in System +Administrationin the tree view. + +There are two kinds of fonts: Personal and Global fonts. +Personal fonts are only accessible to your user, whereas global fonts are +accessible to everyone. When you open the Font +Installer, you're in Personal mode (you can see this in +the Location bar). When you click on the Administrator Mode +button, and put the root password, +you can access global mode, where you can change the fonts for every user on +this computer. + +For the rest, there is no difference between those two kind of fonts. + +Fontspreviewing + +There is a list of fonts in the center. Click on a font to see a preview. +In the toolbar on the top you have buttons to access the top directory, +refresh and change the view. + +If you want to, you can organise your fonts in multiple directories, so that +you can easily find them later. + +Fontsinstalling + +To install a font, click on the Add +Fonts... button. A file open dialog will appear where you can +choose your font. + +Alternatively, you can drag fonts from &konqueror; to the +list. To remove a font, right click on it and +choose Delete. + + + +Configuration (anti-aliasing) + +kfontinst and kfontview should probably get a mention too, since +they don't seem to have any existing docs. + + + diff --git a/doc/userguide/getting-help.docbook b/doc/userguide/getting-help.docbook new file mode 100644 index 000000000..c3a872c7c --- /dev/null +++ b/doc/userguide/getting-help.docbook @@ -0,0 +1,213 @@ + + + + +&Lauri.Watts; + + + + + +Getting Help + + +User Manuals + +User Manual +Most applications come with a comprehensive user manualUser ManualHandbook, which you can +reach various ways: + + + +By pressing F1 inside the application. + + +From the menu bar: +HelpApplication name + + + +By browsing to it in &khelpcenter;&khelpcenter; + + +By using the help KIOslave in &konqueror;. So, in the Location Toolbar, simply type help:/Application name + + + +Online at http://docs.kde.org + + + + + + +Context and <quote>What's This</quote> Help + +Many applications also provide context help in two forms: +Tooltips, and What's This help. + + +Tooltips + +Tooltips +Tooltips are small informational windows or balloons that display when +you hover the mouse over an item on your screen without clicking. + +&kde; uses tooltips in many places to provide brief help or +information about an item on your screen. For instance, most toolbar buttons +inside applications will display their name in a tooltip if you rest or hover +your mouse over them. + +Tooltips have another function, which is not specifically tied to +help. In the &konqueror; file manager and on your Desktop, tooltips can +provide information about files. This is commonly referred to as meta information. + +You can find out more about meta-information tooltips in the section +about the &konqueror; file manager. + + + + +<quote>What's This?</quote> + +What's This? + +What's This? help is usually more detailed than tooltips. +You can access What's This? help in two ways: + + + +By pressing the ? button in the titlebar of the +window. + + +By pressing the key combination +&Shift;F1 + + + +The cursor will change to a pointer with a question mark next to it. +Click on the item you want to know about, and a small window will +pop up displaying information. + + + + + +Mailing Lists, Newsgroups and <acronym>IRC</acronym> + + +Mailing Lists + +Mailing Lists +&kde; provides many mailing lists which can provide you with help +and guidance in using and configuring your Desktop. + +Some of the lists you might find useful are: + + + +The &kde; User List +&kde; User Mailing List + +This mailing list focuses specifically on OS-independent questions +and discussions regarding using &kde;. Operating-system-specific questions and +discussion are off-topic here. For +example, the question How do I change the margin size for KWord +documents is appropriate for this list; whereas How do I set +up my printer using &kde; under UnixOS X.Y is not. Questions asked and +discussions here should apply to all &kde; users using the applicable &kde; +software, not just those using the same operating system. +You can subscribe to this list at https://mail.kde.org/mailman/listinfo/kde. +You can find archives at http://lists.kde.org/?l=kde. + + + + +The &kde;-&Linux; List +kde-linux Mailing List + +This mailing list focusses specifically on questions and discussions +regarding using &kde; on &Linux;. Questions and discussions can involve any +issue confronting desktop users who run &kde; on a &Linux; system. Hence, +questions such as How do I setup a networked printer for printing from +&kde; on LinuxDistro X.Y are appropriate here. If you prefer a list +limited to OS-independent questions and discussions +concerning &kde;, please use the general &kde; mailing list. +You can subscribe to this list at https://mail.kde.org/mailman/listinfo/kde-linux. +You can find archives at http://lists.kde.org/?l=kde-linux. + + + + + + +IRC + +There is a #kde channel on Freenode (irc.freenode.net) for support and other general talk about &kde;. As usual, you can access this channel by using any of &kde;'s popular IRC clients which include konversation, &ksirc;, as well as &kopete;. For more information, check the section. + + + + + + +More Resources + +There are many other resources which you may found useful; some of these are listed below: + + + +dot.kde.org +&kde; News Resource + +This website has a searchable &kde; news resource where you can find out about a superfluity of innovations in the world of &kde;. + + + + + + +kde-look.org +icandy for &kde; + +The paramount resource for &kde; icandy, including themes, window decorations, wallpapers, mouse themes and icons for your &kde; desktop. Note also that the site contains a howto section on how to install the most common of these. + + + + + + +wiki.kde.org +&kde; wiki + +The official &kde; Wiki. From here you can have access to a plethora of information ranging from frequently asked questions and HOWTOs to tips and tricks. The wiki should never, however, be used as a substitute for the respective application's handbook or the official &kde; documentation. + + + + + + + + + diff --git a/doc/userguide/glossary.docbook b/doc/userguide/glossary.docbook new file mode 100644 index 000000000..1e4b85d74 --- /dev/null +++ b/doc/userguide/glossary.docbook @@ -0,0 +1,38 @@ + + + + + + +Glossary of Terms + +KDE/GUI/UNIX terms that are worth explaining. + + + + diff --git a/doc/userguide/groupware-kontact.docbook b/doc/userguide/groupware-kontact.docbook new file mode 100644 index 000000000..beaf1f338 --- /dev/null +++ b/doc/userguide/groupware-kontact.docbook @@ -0,0 +1,614 @@ + + + + + + +Marco +Menardi + +gnu@kde.org + + + + + + +Sharing data with &kontact; via <acronym>IMAP</acronym> + + +Introduction + +For my small office, I was looking for a long time for a +PIM solution that let me share data, so my secretary and +I can share contacts, appointments and so on. Being a &kde; user, I've heard +about the Kroupware project and wait its completion. But when I saw how +complicated is the architecture and setup of the +Kolab server 1.0 (the server side of the +project), I gave up, waiting for an easier to deploy +Kolab 2.0. In any case, the +Kolab stuff was clearly too much for my +needs. Fortunately in the &kde; wiki I've found some piece of +IRC conversation where they were talking about sharing +data without the Kolab infrastructure... mmm so +interesting! + +For small offices and needs, you can have &kontact; use shared data +without the need of installing the Kolab server +or another groupware backend. It can work with just an +IMAP server, that can be easily set up. + +My scenario is a server with Debian unstable and &kde; 3.4. I access +&kontact; and other fabulous GNU/Linux apps from windows using Cygwin/X, +while waiting Wine project to be able to run the last Windows programs I +need (and that are not available under GNU/Linux). I want to share contacts, +events, todo, notes with my secretary. + + + + +What is <acronym>IMAP</acronym> + +This definition is from the ComputerUser.com High-Tech Dictionary: +
Internet Message Access Protocol. A protocol that allows a +user to perform certain electronic mail functions on a remote server rather +than on a local computer. Through IMAP the user can create, delete, or +rename mailboxes; get new messages; delete messages; and perform search +functions on mail. A separate protocol is required for sending mail. Also +called Internet Mail Access Protocol.
 + +So it can be considered a data storage. To use it you you need an +IMAP server, such as Cyrus, +Courier or UW. + + + + +<application>Kolab</application> or <acronym>IMAP</acronym>? + +Kolab brings the ability to share data +between different clients. It makes possible for your secretary to use +Outlook and you use &kontact;, for +instance. + +You will have a configuration interface which does user management, mail +account setup, a central LDAP config data and addressbook +server, spam and virus filtering, vacation scripts, free busy list handling, +resource handling (rooms, cars), groups, distribution lists, automatic +invitation handling, &etc; + +But that can cause initial setup troubles. For a newbie like me it +means: a long long frustrating nightmare, and too much complexity to manage +once working. So no, thanks, I'll go to simple +IMAP. + + + + +How to set up <acronym>IMAP</acronym> server <application>Cyrus</application> + +My choice is Cyrus, that is part of the +Kolab set of software, so if l will go for +Kolab in the future, at least I'm acquainted with +it. Let's start the installation and the setup! + +Become root. + +# apt-get install cyrus21-imapd cyrus21-common cyrus21-admin cyrus21-client sasl-bin sasl2-bin +Installing cyrus21-imapd...The installer asks something I've not understood about an search address... I just pressed Enter. + +The installer also created the user cyrus that is in the (automatically created) +group sasl, that is the +owner of all cyrus files. At the end with ps + you can find the new processes: +cyrmaster and notifyd. + +The real problem in setting up Cyrus is the +authentication, just because it's not trivial and I'm a newbie, with limited +knowledge about what I'm doing. + +Cyrus can use different +SASL (Simple Authentication and Security Layer) +mechanisms, the default being sasldb (it stores usernames and passwords in +the SASL secrets file sasldb), but also getpwent, +kerberos4, kerberos5, PAM, rimap, shadow and LDAP are supported. + + Since I don't want to define users/passwords different than the ones +that access my &Linux; box I choose then shadow mechanism so +Cyrus will use &Linux; passwords for +authenticate. + +To do so we have to tell sasl to use saslauthd as +password authentication method, and then setup saslauthd +to use shadow (or getpwent) as the +authentication mechanism. + +OK, let's start! + +As root, change the Linux +password of cyrus user: + +# passwd + +Enter the password you like (and you will remember) we will use for +this example cyrus as the cyrus +administrator password. + +# vi /etc/imapd.conf + +sasl_pwcheck_method: saslauthd instead of the default auxprop + +remove the # remark from the line: + +#admins: cyrus + +this way you can administer cyrus logging +in as cyrus user (what a fantasy I +have!) + +# vi /etc/default/saslauthd + +Uncomment the line: + +# START=yes + +(otherwise the saslauthd will not start at +boot time, even if referenced in some /etc/rcx.d!) + +and instead of MECHANISMS="pam" put +MECHANISMS="shadow" this way at the boot a +saslauthd will be executed. + +Once exited from your editor, restart sasl +and cyrus. + +To test IMAP: + + su +$ imtest + +You are prompted for the cyrus (user) password, so enter it. + +If the user cyrus is +correctly authenticated, the following lines will appear: + +S: L01 OK User logged in +Authenticated. +To exit type . logout (&ie; dot space logout) + +Now add a user named groupware and set a password for it, using +your usual system tools. It should be in an unprivileged group such as +nobody and does not require a +login shell or a home directory. + +Now I have to create the user and an IMAP in +cyrus also: + +# cyradm +after entering the password for the admin user cyrus, you get the prompt localhost> +localhost> cm +localhost> lm lists the mailbox only just created +user.groupware (\HasNoChildren)) +localhost> quit + +You can type help for a list +of available commands. + +You can check what has happened with: + +# ls /var/spool/cyrus/mail/g/user/groupware +total 12 +-rw------- 1 cyrus mail 4 Oct 29 20:55 cyrus.cache +-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header +-rw------- 1 cyrus mail 76 Oct 29 20:55 cyrus.index + +Now you should be able to connect with an IMAP client +as the groupware user and see the +INBOX. +In the IMAP protocol, selecting the mailbox +INBOX is a magic word, a sort of alias for +the above directory structure. The client sees INBOX, and +the IMAP server maps it in the /var/spool/cyrus/mail/... folder and file +structure. + + + + +How to setup &kontact; clients + +I connect to my GNU/Linux office server PC (a sort of "black box" +without monitor and keyboard) from 2 &Windows; 2000 PC with +Cygwin/X, using them as a X-Window server (in the +near future I hope to replace both with 2 mini-itx thin clients using the +LTSP). With this setup every user runs &kontact; on the same machine where +Cyrus is installed and running +(localhost). + +To have &kontact; work with IMAP, there are these +steps to complete: + + + +Create an IMAP account on the +Cyrus for fake groupware user (already previously +done!) + +Create/configure an IMAP account in &kmail; +for login as that user Use kresources to make +&kontact; components work with data taken from IMAP +source + +Enable groupware functionality and make related subfolders of +that IMAP INBOX (if not +already) + +Enjoy &kontact; and shared data through +Cyrus IMAP + + + +So login to &kde; with the first real user account you +want to provide groupware functionality to. + +Let's create the IMAP account in &kmail;. + +Run &kontact; and select Mail (the &kmail; +component). From the menu choose +SettingsConfigure KMail +AccountsReceiving tab, press the Add... button. You will then be +prompted for the type of your email account, and select +disconnected IMAP (not just +IMAP). Then in the General tab +enter the following data: + + + +Account Name: office_gwdata + +A name that will be used for the local folder that +points to this IMAP account. + + + +Login: groupware + +The Cyrus user we have chosen as +owner of all of the office data + + +Password: + +The password of the groupware user. + + + +Host: localhost + +Remember for our example, the &kontact; client runs on the same +computer as the IMAP server + + + +Port: 143 + +The default + + + + +Check store IMAP password +so you will not be asked for it next time you run &kontact;. Check the +Enable interval mail checking and set a value in +minutes. + +Note that we have checked the disconnected IMAP +type account. This has the effect that a copy of the groupware data is +stored locally to the client (under the home folder), and it +is synchronized every time the client connects. This seems very inefficient, +since your data is duplicated many times (&ie; if you have 10 users that use +&kontact;, you have 10+1 times the data), but it is the only way to make +things run fast, because at every connection &kontact; has to fetch all data +and have &korganizer; and &kaddressbook; interpret it. If you use +disconnected IMAP data is cached locally, and only the +delta (&ie; the data that has changed) is sent. + +On the other end, if your users run &korganizer; on the same PC that +runs the IMAP server, it seems reasonable to use +IMAP (that is called online IMAP) to save +space, since transfer speed should not be an issue. But unfortunately this +does not work because &kontact; does not update automatically the +Calendar folder in online IMAP, so you +are not updated when someone adds events (you must manually switch to +&kmail; application and click on the Calendar +folder). In addition, at start up when it does read +Calendar folders, you may see a tremendous flicker and +slow data updates. + +Now we have to tell &kontact; to use IMAP as the +data source for it's various components. From the &kmenu;, choose +Run command, run kcmshell +kresources. In the combo box select +Contacts, then press the Add... +button, and choose Addressbook on IMAP Server via KMail. Then select that new line and +press Use as Standard button. Do the same for +Calendar and Notes. + +Now we have to enable the &kmail; (and as a consequence, the whole +&kontact;) groupware functionality: + + + +Choose from the menu +SettingsConfigure +KMailMiscGroupware + + +Check Enable IMAP resource functionality + + +Choose English as Language of the +groupware folders (this is in case you already have the folders +in the IMAP server created by a different program in a +different language). + + +Now move to Resource folder are in account and +select the the Inbox subfolder of the +office_gwdata folder. +Leave Hide groupware folders unchecked for now, +so we can see that happens. You can return here and check it once everything +is clear. + + +When you press OK you are prompted with: +&kmail; will now create the required folders for the IMAP +resource as subfolders of Inbox +If you do not want this, press No, and the +IMAP resource will be disabled. Press +Yes (this happens only the first time with the first +real user). You will immediately see that in the &kmail; +folder tree, under +office_gwdataInbox +these subfolders are created: + +Calendar +Contacts +Notes +Tasks +Journal + +if you now do a: +# ls +drwx------ 2 cyrus mail 144 Oct 31 16:36 Calendar +drwx------ 2 cyrus mail 144 Oct 31 16:36 Contacts +drwx------ 2 cyrus mail 144 Oct 31 16:36 Journal +drwx------ 2 cyrus mail 144 Oct 31 16:36 Notes +drwx------ 2 cyrus mail 144 Oct 31 16:36 Tasks +-rw------- 1 cyrus mail 4 Oct 31 15:28 cyrus.cache +-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header +-rw------- 1 cyrus mail 76 Oct 31 15:28 cyrus.index + +As you see, the office_gwdata Inbox is stored not +local to the &kontact; current user home, but in the IMAP +groupware user's folders. + + + +Now &kontact; is ready to work and store data there. In the calendar +application, if &kmail; IMAP account was of type +disconnected, the resource window should +display the item Imap resource with 3 subitems, that +are paths to local home files. Instead, the Contacts +application does not show subitems below the Imap +resource. + +You can now login to &kde; with a different username and set up +his/her &kontact; client in a very similar manner: + + + +Open &kontact; and in the Mail component add an +IMAP account specifying as host the +computer where Cyrus server runs (in my case: +192.168.1.3). + +Remember to check the Enable interval mail +checking and set a value in minutes. When you confirm, you are +not prompted for the subfolder creation (since they are found in the +IMAP server), and you see them in the folder tree. + + +Activate the groupware functionality to be able to save data in the +IMAP server. + + +Beware that in disconnected IMAP, +data are transmitted from a client to IMAP server only +when the clients connects to check for new mail. So if you have your +&kontact; clients with an interval mail checking of, +for instance, 5 minutes, in the worst case you have a 10 minutes delay +between the event being written and it's appearance to the other +users. + + +How to have Read Only Access + +Beware that I've been confirmed that Notes +IMAP implementation in &kontact; prior to version 1.01 is +broken, so this setup will not work for them, so you want to use them, you +need to use the previous setup. + +In the previous setup, we have the same fake user, named +groupware, that is used by all the +real &kontact; users (&ie; tony, rohn, amanda, &etc;) through the +IMAP account with it's login and password. But this way +every real user has the same read/write permissions of the others, since +everyone connects as the user groupware to the IMAP +server. + +To limit access to some users (typically, providing read-only access), +we can use the ACL (Access Control Lists). + +Select in &kmail; a subfolder of office_gwdata +inbox, for instance Calendar, and right click the +mouse. Select PropertiesAccess +Control tab. Here you can enter the users you want give access to +this folder and what they can do. + +Just to experiment trying to exchange events, we give +All permission to the user mary + +At cyrus level (in the +PC that runs IMAP server cyrus, with +cyrus tools), we first need to add the user +mary, so it's an +IMAP recognized user, and create an +IMAP folder for her. + +Then we login to GNU/Linux as mary and enter &kontact;. As previously shown, +we will setup an IMAP account in &kmail; with the same +data but the one of the user (instead of the fake user groupware and it's password, we will use +mary and her password). + +In &kmail; folder tree, this time you will see this structure: +office_gwdatauser +groupwareCalendar and +Tasks. Check the mail +(FileCheck +Mail) and you will also have an +inbox folder under office_gwdata. + +Now enable &kmail; groupware functionality, and in Resource +folders are subfolders of put the +inbox that is subfolder of +office_gwdata. + +Now enable &kmail; groupware functionality, and in Resource +folders are subfolders of put the +inbox that is subfolder of +office_gwdata. + +Now you have two branches of folder under +office_gwdata: + + + +inbox with Calendar, Contacts, Notes, Tasks and +Journal, that are saved on mary +IMAP folders on the IMAP server + + +user, with the subfolder groupware and +the subfolders to which mary has +access to (in this example, Calendar and Tasks) + + +&RMB; click on the user Calendar and +check if it's of type Calendar (if not, set it to be), and also if +userTasks is of type Tasks. +Now in Calendar you have two available IMAP +resources to write against, so if you create a new event, you are prompted +which one use (or if you left the local resources available, you have +3!). +You have go to the lower left small window in Calendar, the one that +shows available resources, and uncheck the ones that don't point to +.groupware.directory path (see the tail part of each +resource path). + + + + +Credits + +I'm a newbie, and for this howto I've only provided my time and my +will. For the knowledge I have really to thank some guys in freenode +channels for their competence, patience and helpfulness. + + +Special thanks to: + +For the Cyrus IMAP part +in #cyrus channel: + + +[protagonist] Andy Morgan morgan@orst.edu + + +[plixed] Okke Timm okke.timm@web.de + + + + +For the &kontact; part in #kontact channel: + + +[till] Till Adam adam@kde.org + + +[dfaure] David Faure faure@kde.org + + +[mdouhan] Matt Douhan matt@fruitsalad.org + + + + + +Thank a lot guys! + +Ah, and there is also me, [markit] Marco Menardi +mmenaz@mail.com + + + + +Further Reading + + +Reference +KDE: http://www.kde.org +&kontact; website: http://www.kontact.org +Kroupware project: http://www.kroupware.org +&kde; Community Wiki: http://wiki.kde.org +Wine project: http://www.winehq.org +Cygwin/X project http://x.cygwin.com +LTSP project: http://www.ltsp.org + + + + + + + diff --git a/doc/userguide/index.docbook b/doc/userguide/index.docbook new file mode 100644 index 000000000..b039979ce --- /dev/null +++ b/doc/userguide/index.docbook @@ -0,0 +1,611 @@ + + KApp"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + +The &kde; User Guide + + + +The &kde; Documentation Team + + + + + + +20042005 +The &kde; Documentation Team + + +&FDLNotice; + +2004-06-16 +0.0.1 + + +A general user guide to &kde; + + +Please report any problems with this document to +kde-doc-english@kde.org. + + + + +KDE +desktop +handbook +tutorial + + + + + +Introduction + + +Welcome to the &kde; User Guide + +This User Guide aims to provide an overview of the entire &kde; experience. We +assume here that you have a standard, working installation of a complete &kde; +desktop environment, and the accompanying packages. This book should be +your first point of reference for any simple &kde; configuration question, or +to find out how to perform a common task. + + +What this book aims to be + +The first place to look and a one stop shop for all questions you have +regarding your &kde; experience. + +A Quick Start Guide to commonly performed tasks - In most cases, you do not +need to know the details of how to configure every option in an application, +in order to get down to work. You will find step-by-step guides which +will work in most common situations, along with links to sources of +further information in case you have any problems. + +There are also some tips and tricks showing you the most useful and +impressive features of &kde;, and ways to save you time and effort. + + + + +What this book is not + +The User Guide is not intended to be a replacement for the application +manuals. You should turn to the handbook for help with specific program +configuration and troubleshooting issues not covered in this book. If the +answer is outside the scope of this book, we will tell you here precisely +where to look for further help. + +You may also have a variety of third party packages, and some of these +applications are mentioned briefly here, but we normally cover only the +applications provided as part of a &kde; release. This is not a judgment on +the value of third party applications, and in fact many of them are +excellent. + +The User Guide is not specific to a distribution, and covers a default &kde; +installation. Your local installation may be customized by your +distribution provider, or by yourself, and so our advice here is +generic. You may have to adjust paths in order to locate the files that are +discussed. + + + +Conventions used in this book + +We'll use the following formatting conventions to make it clear what +we're referring to: + + + + + +Type of Text +Style +Example + + + + + +Text appearing in the &GUI; (on buttons, &etc;) +Light gray background +Settings + + + +Names of keys +Bold font +&Ctrl; + + + +Menu entries +Menu Name->Menu Item +FileQuit + + + + +Key combinations (pressed simultaneously) +Modifier Key+Action Key +&Ctrl;Q + + + + +Text you should enter +Bold, fixed width font +ls -al kde/ + + + +Text you should replace as appropriate +Italic green font +user + + + + + + + + + + +System Locations + +You may need to know the following system locations: + + + + +&kde; prefix +&kde; installs into its own folder tree, which you can find by +running the command kde-config . This folder is referred to +by the environment variables $KDEDIRS and possibly +$KDEDIR. + + + + +&kde; user-specific settings +The environment variable $KDEHOME +points to the folder where &kde; should find user-specific settings. If it is not +set, the default value of ~/.kde is used. + + + + + + + + + +Overview, or <quote>Where to look in the User Guide</quote> + +Here's an overview of what's in the User Guide: + + contains an introduction to the basic +use of &kde;, such as , and the tools +that you'll be using in all &kde; applications, like . If you're new to &kde; or even +computers in general, you will probably find this section +helpful. + + explains some important components +of a &kde; installation and how they fit together: &kde;'s multimedia +and networking capabilities are extensive, and not covered thoroughly +here, but there's a taster of both of them in this part of the User +Guide. At the end of this part, you'll find a guide to tweaking &kde; +just that little bit more, in . + + highlights &kde;'s suite of +Internet applications. &kde; includes a powerful web browser, +&konqueror;, a full-featured email client, &kmail;, a news reader, +&knode;, and many more applications to make your Internet experience +easier and more productive. This part of the User Guide contains +information about setting up these applications. + + is a reference guide to +some &kde; features which will be useful to administrators setting up +multi-user systems. This part also has information that may be useful +to &kde; users with single-user systems: where configuration files are +stored, what environment variables affect &kde;, and so on. The KIOSK +framework is the &kde; system which allows administrators to limit +what users can do in &kde;. It is potentially useful in many +situations, but especially for running single-function kiosks with, +for example, just a web browser, hence the name. + + + + + + +The Desktop + + +The Basics +The desktopDesktop + is just the name for the layout of +the screen when you start &kde;. It looks something like this (on your +own system, it might look slightly different, but the main features +should be the +same): + + + + + + +A default desktop layout + + + + +Let us look at the most important parts: + +Most of the screen is +taken up by the backgroundBackground. At the moment, there is a picture making up +the background. This picture is usually referred to as the +wallpaper,Wallpaper and you can change it to make &kde; suit your +taste. + + +In the top left-hand corner are two icons: +Trash and Home. Clicking on +these will open your Trash folder and Home +folder, respectively. You can add more icons to the desktop so that +you can open your favorite programs, or access removable media, with +just one click. + + +At the bottom is the &kde; PanelPanel, also known as +&kicker;. The Panel contains several useful ways of +interacting with &kde;. It houses the &kmenu;, from where you can open +any &kde; application installed on your computer, it shows all the +programs that are currently running, as well as the time, and more. +Take a look at for more +information about the &kde; Panel. + + + + + + + + + + + +&Philip.Rodrigues; + + + + +Logging In and Logging Out +Basic KDM & startkde stuff. + + +There are two ways to log into &kde;: graphically and via the +command line. We'll look at them both briefly: + + +Logging in Graphically +login +&kdm; + +If you see a screen a little bit like the one below when you +start up your computer, then you are all set for logging in +graphically. Just enter your username in the +Login text box and your password in the +Password text box. Your password will not be shown +as you type it; it will probably be shown as asterisks. When you have +entered that information, click on the Login +button, and &kde; will start up. The &kde; splash screen will appear, +and keep you informed about the progress of &kde; startup, and when +it is done, &kde; will be ready to use. + + + +Logging in via the Command Line +startkde +startx + +If you prefer using the command line, you can log in to &kde; +with the startx command. Add the line +exec startkde to the +.xinitrc file in your home folder (create it +if it does not exist), save the file, and then run +startx. &kde; should start in the same way as if +you had logged in graphically. + + + +Logging Out +logout + +Once you have finished using &kde; for the moment, you will +want to log out until next time. The easiest way to do this is to +click on the &kmenu; at the bottom left of your screen, and then +select the Log Out... item. A dialog with the +text End session for +username will appear. To confirm +that you want to log out, click on the End Current Session +button. If you change your mind, and decide to carry on using &kde; +for now, hit Cancel. + + +Related Information +The &kdm; Handbook has information about using and setting up +the &kde; graphical login manager. You can read it in &khelpcenter; or +by entering help:/kdm in &konqueror;'s +Location bar. + + + + + + +&getting-help; +&windows-how-to; + +&the-filemanager; + + + + +&panel-and-desktop; + +&programs-and-documents; + + + + +&kde; Components + +&control-center; + +&base-kde-applications; + +&extragear-applications; + + +Multimedia With &kde; + +&removable-disks; + +&playing-music; + +&playing-audiocds; + +&playing-movies; + + + + +&kde; the Multiuser Desktop + +&your-kde-account; + +&kde-as-root; + +&switching-sessions; + + + +Networking with &kde; + +&file-sharing; + +&networking-with-windows; + +&shared-sessions; + + + +Graphics, Printing, and Fonts + +&printer-setup; + +&printing-from-apps; + +&pdf-files; + +&font-installation; + +&creating-graphics; + + +&customizing-desktop; + +&konsole-intro; + +&kde-edutainment; + +&accessibility; + +&under-the-hood; + + + +&kde; and the Internet + +&net-connection-setup; + +&email; + + +&konqueror; + +Intro to the browser + +&internet-shortcuts; + +&browser-fine-tuning; + + +&usenet; + +&messaging-intro; + + + +&kde-office; + +&kde-for-admins; + + +More Tools + +&migrator-applications; + +&migrator-dictionary; + +&standard-menu-entries; + +&glossary; + + +Troubleshooting Problems + +Problems that aren't + +Frozen apps (how to kill them) + +Things won't open + +That scary crash dialog + +Reporting Bugs + +More Resources + +&troubleshooting-network-x; + +&troubleshooting-no-open; + + + + +Contributing to &kde; + +Some basic information to get encourage people to contribute to +&kde;, information about what's available, and how to get +started. + + + + + + + +Credits and Licenses + +&credits-and-license; + + +License + + + +&underFDL; + + + + +&documentation.index; + + + + + diff --git a/doc/userguide/internet-shortcuts.docbook b/doc/userguide/internet-shortcuts.docbook new file mode 100644 index 000000000..f6705c292 --- /dev/null +++ b/doc/userguide/internet-shortcuts.docbook @@ -0,0 +1,80 @@ + + + + + +Simon +Vermeersch + +titeuf@ph34rus.org + + + + +Internet Shortcuts + +Web shortcuts +Internet Shortcuts +gg: + +Internet shortcuts are a really useful feature of &konqueror;: +once you get used to them, you'll wonder how you ever lived without them. + +To see what internet shortcuts are, open up &konqueror; and type +gg:kde in the Location +bar. + +You will go to Google, searching for &kde;. + +They are many such shortcuts like ggl: (Google +I'm feeling lucky), bug: (bugs.kde.org) and so +on. + +To get a full list, click on Settings in the +&konqueror; menu, and select Web Shortcuts. Here you will find a full list of all the shortcuts. You can create +new ones, change existing ones, or delete unused shortcuts. You can also +disable web shortcuts if you don't like them. If you set the Default +search engine, you don't have to type the shortcut anymore. For +instance if you set it to Google, you can just type +kde in the Location bar, +and it will search Google for &kde;. + +In Keyword delimiter you can choose if you want +to separate a shortcut with a colon (gg: kde) or a +space (gg kde). + +A nice tip with Internet shortcuts is that you can use them from the +Run Command dialog. Just open it (through the &kmenu; +or with &Alt;F2) and +type your shortcut, ⪚ gg: kde, and press +&Enter;. It will automatically open &konqueror; with a Google +search for &kde;. + + + + + + + + + diff --git a/doc/userguide/juk-icon.png b/doc/userguide/juk-icon.png new file mode 100644 index 000000000..2b58a33d3 Binary files /dev/null and b/doc/userguide/juk-icon.png differ diff --git a/doc/userguide/juk.png b/doc/userguide/juk.png new file mode 100644 index 000000000..9ec3ae91e Binary files /dev/null and b/doc/userguide/juk.png differ diff --git a/doc/userguide/kaboodle-icon.png b/doc/userguide/kaboodle-icon.png new file mode 100644 index 000000000..87ac58b8c Binary files /dev/null and b/doc/userguide/kaboodle-icon.png differ diff --git a/doc/userguide/kaboodle.png b/doc/userguide/kaboodle.png new file mode 100644 index 000000000..dbbcfd923 Binary files /dev/null and b/doc/userguide/kaboodle.png differ diff --git a/doc/userguide/kcalc-systray.png b/doc/userguide/kcalc-systray.png new file mode 100644 index 000000000..5e0ac5cc5 Binary files /dev/null and b/doc/userguide/kcalc-systray.png differ diff --git a/doc/userguide/kcontrol.png b/doc/userguide/kcontrol.png new file mode 100644 index 000000000..3de78f3f8 Binary files /dev/null and b/doc/userguide/kcontrol.png differ diff --git a/doc/userguide/kde-as-root.docbook b/doc/userguide/kde-as-root.docbook new file mode 100644 index 000000000..7e6bb6fe9 --- /dev/null +++ b/doc/userguide/kde-as-root.docbook @@ -0,0 +1,52 @@ + + + + + +&Francis.Giannaros; &Francis.Giannaros.mail; + + + + + +Using &kde; as Root + +For &UNIX; operating systems there are often different users, which in turn might have different privileges. The conventional method is to have an ordinary user account, whose files are generally stored in /home/username, and then to also have a root account. The root, or Super User, account has system-wide privileges, being able to modify any file on the system. + +Although this means that it is easy to perform administrative tasks without hassle, it also means that there are no security restrictions imposed upon it. Thus, a small typographical error or other mistake can result in irrevocable damage. + +Some of the operating systems that run &kde; come with a graphical root login enabled. Despite this, you should never log in to &kde; as root, and you should never need to. Your system is far more open to attack, particularly if you are browsing the Internet as root, and you dramatically increase your chances of damaging your system. + +Some &Linux; distributions have tried to stress this point so much that they have disabled the root account altogether, and instead use the sudo model. Nevertheless, the basic security model in sudo is the same as su, and thus they share the same security strengths and weaknesses, essentially. + +If you should ever need to run a program with Super User privileges, then it is always recommend that you use &kdesu;. From &konsole; or from hitting &Alt;F2, enter kdesu application, and the application will be run with the appropriate Super User privileges. + +Even if you have set up your system to use sudo, or you are on a distribution that uses sudo, such as &kubuntu;, you should still use &kdesu;. The program will be appropriately modified by the developers to use the correct settings. You should not, however, ever use sudo application to run an application with root permissions; it can derange permissions of certain configuration files for a program. Running a graphical applications as root in general is not a good idea, but using &kdesu; will always be your safest bet with it. + + + +Related Information +&kdesu; Handbook + + + + + + + diff --git a/doc/userguide/kde-edutainment.docbook b/doc/userguide/kde-edutainment.docbook new file mode 100644 index 000000000..11c6faae7 --- /dev/null +++ b/doc/userguide/kde-edutainment.docbook @@ -0,0 +1,342 @@ + + + +&kde; Edutainment + +The &kde; Edutainment Project offers children, families, and teachers some +educational programs. You can find applications to help you improve +your language skills and train your vocabulary, like &kvoctrain; and +&kwordquiz;; or Scientific programs, like the +very advanced &kstars; (a planetarium) and &kig; (interactive +geometry), which will bring you to the edge of knowledge. Have fun learning +touch-typing with &ktouch;. Teachers will find an easy way to make +their lessons with &keduca;. You can find a complete list of &kde; +educational software on the KDE-Edu +website. What follows is an overview of a few of them. + +View the handbook of each application by typing help:/<appname> in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;. + + +Improve your language skills + + + +&khangman; + An easy-to-use application which implements the classical hangman game. You can choose for the words to be from a particular topic and even choose from a selection of difficulty levels. The program comes in twenty-four languages, and is therefore quite ideal for learning the spelling of basic nouns in other languages. + + + Website: http://edu.kde.org/khangman + &khangman; Handbook + + + + + + +&klettres; + An application specially designed to help the user learn the alphabet of a new language and then to learn to read simple syllables. Ideal for children, or any person attempting to learn and familiarize themselves with a foreign language's alphabet. A number of alphabets are currently supported. + + + Website: http://edu.kde.org/klettres + &klettres; Handbook + + + + + + +&kanagram; + A simple mind-training game, in which you have to figure out the word that has been given in the program. The letters from the word are disordered, and from the given words you have to solve which word the letters might make, if rearranged. Similar to the popular Countdown game as seen on Television. + + + Website: http://edu.kde.org/kanagram + &kanagram; Handbook + + + + + + +&kverbos; + A simple way to learn and study Spanish verb forms. The program suggests a verb and a tense and the user enters the different forms. The program corrects the user input and gives feedback. The user can edit the list of the verbs that can be studied and the program can build regular verb forms, and the forms of the most important verb groups, by itself. Irregular verb forms can be entered by the user. + + + Website: http://edu.kde.org/kverbos + &kverbos; Handbook + + + + + + +&kvoctrain; + Another advanced vocabulary training application, using the flash card approach. Vocabulary files and be downloaded and loaded into the application. + + + Website: http://edu.kde.org/kvoctrain + &kvoctrain; Handbook + + + + + + + +&kiten; + A Japanese reference and learning tool. Words from both English and Japanese can be looked up, and filtered, using the Edict and Kanjidic dictionary protocols. Other features in &kiten; include a few comprehensive search functions, a history of searches, and a learning section which contains various different learning modes. + + + Website: http://edu.kde.org/kiten + &kiten; Handbook + + + + + + +&klatin; + A program to help revise Latin. There are vocabulary, grammar, and verb testing sections. In addition there is a set of revision notes that can be used for self-guided revision. + + + Website: http://edu.kde.org/klatin + &klatin; Handbook + + + + + + + + + + +Mathematics + +Several applications to help you with Mathematics and Geometry. + + + +&kbruch; + An application with several exercise types in order to enhance your calculating with fractions. Different tasks include exercises to find the sum of two fractions, the conversion of fractions into the respective decimal, the comparison (with less than, more than) of fractions, and more. + + + Website: http://edu.kde.org/kbruch + &kbruch; Handbook + + + + + + +&kig; + A great application with interactive geometry. Ideal for teachers attempting to draw a graph on the computer, or students who wish to find out more and investigate with graphs and curves. Currently many things are supported, and you can very easily construct several things from parabolas and hyperbolas, to ellipses. + + + Website: http://edu.kde.org/kig + &kig; Handbook + + + + + + +&kpercentage; + Essentially an application to help you improve your skills in calculating percentages. Different exercises are included, and there are varying difficulty levels to target persons with varying abilities. + + + Website: http://edu.kde.org/kpercentage + &kpercentage; Handbook + + + + + + + +&kmplot; + A mathematical function plotter. It has built in a powerful parser. You can plot different functions simultaneously and combine their function terms to build new functions. &kmplot; supports functions with parameters and functions in polar coordinates. Several grid modes are possible and plots may be printed with high precision in correct scale. + + + Website: http://edu.kde.org/kmplot + &kmplot; Handbook + + + + + + + + + + +Science + + + +&kstars; + A desktop Planetarium for &kde;. It provides an accurate graphical simulation of the night sky, from any location on Earth, at any date and time. The display includes 130,000 stars, 13,000 deep-sky objects,all 8 planets, the Sun and Moon, and thousands of comets and asteroids. + + + Website: http://edu.kde.org/kstars + &kstars; Handbook + + + + + + + &kalzium; + A fully-featured periodic table, with the full list of all elements, and extended information about each individual element is accessible. As well as being able to view a basic overview, other features include being able to view its chemical data, atomic model, energies, as well as a picture of the element. + + + Website: http://edu.kde.org/kalzium + &kalzium; Handbook + + + + + + + + + +Teaching Tools + + + &keduca; + A flash card application, which allows you to make interactive form-based tests. It also currently comes with support to add servers from which you can fetch tests from. Several languages supported. + + + Website: http://edu.kde.org/keduca + &keduca; Handbook + + + + + + + + + +Miscellaneous + + + &ktouch; + An application for learning touch-typing. &ktouch; displays the keyboard on the screen, and the color of the keys changes when they need to be depressed. Text appears on the screen, and the user is asked to type it out. A few default lectures are contained in the program by default, with various different difficulty levels. + + + Website: http://edu.kde.org/ktouch + &ktouch; Handbook + + + + + + + + + &kwordquiz; + A flash card application, which allows you to make interactive form-based tests. It also currently comes with support to add servers from which you can fetch tests from. Several languages supported. + + + Website: http://edu.kde.org/kwordquiz + &kwordquiz; Handbook + + + + + + + + &kturtle; + An educational programming environment using the Logo programming language, with several languages currently supported. + + + Website: http://edu.kde.org/kturtle + &kturtle; Handbook + + + + + + + + &kgeography; + &kgeography; is a geography learning tool for &kde;. You can browse the maps by clicking in a map division to see its name and you can also answer several types of questions where the program shows you a map division or a capital for example and you have to guess its name. + + + Website: http://kgeography.berlios.de/ and http://edu.kde.org/kgeography + &kgeography; Handbook + + + + + + + + &blinken; + &blinken; is a Simon Says game for &kde;. The player should remember the sequence of lights in the correct order and is then presented with an identical sequence with one extra step. + + + Website: http://edu.kde.org/blinken + &blinken; Handbook + + + + + + + + + + +Related Information + +The &kde;-Edu website at http://edu.kde.org has news and +information about all the &kde; Edutainment applications. + + + + + + + + diff --git a/doc/userguide/kde-for-admins.docbook b/doc/userguide/kde-for-admins.docbook new file mode 100644 index 000000000..f7d5d2ee0 --- /dev/null +++ b/doc/userguide/kde-for-admins.docbook @@ -0,0 +1,2747 @@ + + + + + +Waldo +Bastian + +bastian@kde.org + + +&Philip.Rodrigues; +&Philip.Rodrigues.mail; + + + + +&kde; for Administrators + + +&kde; Internals + + +Overview +to be written + + + +Directory Layout + +&kde; defines a filesystem hierarchy which is used by the &kde; +environment itself as well as all &kde; applications. In general &kde; +stores all its files in a directory tree with a fixed structure. + + +By default &kde; uses two directory trees: + + +One at the system level (for example /opt/kde3). +One at the user level in the user's home directory +(usually +~/.kde) + + +As a system administrator you can create additional trees. Such +additional trees can be used for profiles + +&SuSE; &Linux; for example uses: + + +$HOME/.kde +/opt/kde3. (This is +&SuSE;-specific; other distributions may use +/usr or /usr/kde3) +/etc/opt/kde3. (This was added by +&SuSE;). + + +If you have the KIOSK Admin tool v0.7 or later installed you can +check which directory trees are used with the following command: +kiosktool-kdedirs + + + +&kde; and &kde; applications look up files by scanning all the +&kde; directory trees. The directory trees are checked in order of +precedence. When a file is present in multiple directory trees, the +file from the last tree takes precedence. Normally, the tree +located in the user's home directory has the highest precedence. This +is also the directory tree to which changes are written. + + +For information about the text/plain &MIME; type +the following files are searched: + + +$HOME/.kde/share/mimelnk/text/plain.desktop +/opt/kde3/share/mimelnk/text/plain.desktop +/etc/opt/kde3/share/mimelnk/text/plain.desktop + + +If a user makes a change, the change is written to $HOME/.kde/share/mimelnk/text/plain.desktop + + +For configuration files the story is slightly different. If +there are multiple configuration files found in the directory trees +with the same name, their content is combined. The precedence order of +the directory trees plays a role here. When two files define the same +configuration key, the file with the highest precedence determines +which value is used for the key. + + +For example, if the following two files exist, with these contents: + +$HOME/.kde/share/config/foobar + +Color=red +Shape=circle + + + + + +/etc/opt/kde3/share/config/foobar + +Color=blue +Position=10,10 + + + + + +The files will be merged to result in: + + +Color=red +Shape=circle +Position=10,10 + + + + + + +Specifying Directories + + + + +Environment Variable +Example Setting(s) +Comment + + +KDEHOME +~/.kde + + + + +KDEROOTHOME +/root/.kde +Different variable to prevent +root writing to $KDEHOME of the user after running +su. + + + +KDEDIR +/opt/kde3, /usr, /usr/kde3 +Vendor dependent. Used by &kde; 2. If not set, falls back to +compiled-in default. + + + +KDEDIRS +/opt/kde3, /usr, /usr/kde3 +New in &kde;3. Can list multiple locations separated by a +colon. If not set, falls back to $KDEDIR + + + + +Don't need to be set, defaults work just fine. +Running &kde;2 next to &kde;3? Point $KDEDIR to +&kde; 2 and $KDEDIRS to &kde; 3. + + +A staff member at a university could have the following +settings: + +KDEHOME='~/.kde3' +KDEROOTHOME='/root/.kde3' +KDEDIRS='/opt/kde_staff:/opt/kde3' + + + + + + + +User Profiles + +In the previous example /opt/kde_staff contained additional settings +and applications for staff members. User Profiles allow you +to add this directory only for certain users and not for others. Add the +following to /etc/kderc: + + +[Directories-staff] +prefixes=/opt/kde_staff + + +This creates a profile named staff that adds the +/opt/kde_staff directory +tree. (Note that &SuSE; &Linux; uses +/etc/kde3rc instead of +/etc/kderc. Now that we have a named profile it +can be assigned to users. + +To map profiles to users a mapping file needs to be specified in +/etc/kderc: + + +[Directories] +userProfileMapFile=/etc/kde-user-profile + + +It is now possible to assign a profile based on either the user name +or based on the &UNIX; group the user is part of. + +To assign the staff profile to all users that are a member of the +&UNIX; group staff_members add the following to +/etc/kde-user-profile: + + +[General] +groups=staff_members +[Groups] +staff_members=staff + + +It is also possible to assign a profile to a single user: + + +[Users] +bastian=staff + + + + + +Directory Layout Revisited + +Each directory tree used by &kde; has a fixed directory structure. +Directories that are not relevant for a certain tree, or simply not used can +be left out though. For example, directories used for temporary files are +usually only found under $KDEHOME but not in any other +directory tree. + + + + +Architecture-specific Directories + +Architecture (OS and CPU type) specific directories: + + + +bin +Used for &kde; executables. + + + +lib +Used for &kde; libraries. + + + + +lib/kde3 +This directory contains components, plugins, and other +runtime loadable objects for use by &kde; 3.x +applications. + + + + + + +Shared Directories + +Shared: Not architecture specific, can be shared between different +archs. + + + +share/applnk +.desktop files for +&kde;-menu (old) + + + +share/applications +.desktop files for +&kde;-menu (since &kde; 3.2) + + + + +share/apps +Contains application-specific data files. Each +application has a sub-directory here for storing additional data +files. + + + +share/config +Configuration files. Configuration files are normally +named after the application they belong to plus the letters +rc. A special case is kdeglobals. +This file is read by all &kde; applications. + + + +share/config/session +This directory is used by session management and is +normally only available under $KDEHOME. At the end of a +session &kde; applications store their state here. The file names +consist of the name of the application followed by a number. The +session manager ksmserver stores references to +these numbers when saving a session in +ksmserverrc. + + + +share/doc/HTML +This directory contains documentation for &kde; +applications. Documentation is categorized by language and the +application it belongs to. Normally at least two files can be found in +a directory: index.docbook, which contains the +documentation in the unformatted DocBook format, and +index.cache.bz2, which contains the same +documentation formatted as bzip2-compressed +&HTML;. The &HTML; version is used by &khelpcenter;. If the &HTML; +version is missing, &khelpcenter; will regenerate it from the DocBook +version but this is a time-consuming process. + + + + +share/icons +Under this directory icons are stored. Icons are +categorized by theme, dimension and usage category. + + + +share/mimelnk +In this directory,.desktop files that describe &MIME; types +are stored. &kde; uses &MIME; types to identify the type of a +file. + + + + +share/services +This directory contains .desktop files that describe services. Services +are like applications but are usually launched by other applications instead +of the user. Services do not appear in the &kde; menu. + + + + +share/servicetypes +This directory contains .desktop files that describe +servicetypes. A servicetype usually represents a certain programming +interface. Applications and Services include in their >.desktop files the servicetypes that they +provide. + + +share/sounds +This directory contains sound files. + + + +share/templates +This directory contains templates for creating files +of various types. A template consists of a .desktop file that describes the file and +that includes a reference to a file in the .source sub-directory. The templates in +this directory appear in the Create New menu +available on the desktop and in the file browser. When a user selects +a template from the menu its source file is copied. + + + + +share/wallpapers +This directory contains images that can be used as +background picture + + + + + + + +Host-specific Directories + +There are three host-specific directories that are usually +symlinked to other locations. If the directories do not already exist, +the following symlinks and directories will be created using the +lnusertemp utility: + + + + +$KDEHOME/socket-$HOSTNAME +Usually /tmp/ksocket-$USER/, this +is used for various &UNIX; sockets. + + + + +$KDEHOME/tmp-$HOSTNAME +Usually /tmp/kde-$USER/, this is used for temporary files. + + + + +$KDEHOME/cache-$HOSTNAME +Usually /var/tmp/kdecache-$USER/, +this is used for cached files. + + + + +Since both /tmp and +/var/tmp are world writable, +there is a possibility that one of the above directories already +exists but is owned by another user. In that case the +lnusertemp utility will create a new directory with +an alternative name and link to that instead. + + + + +Configuration Files &kde; uses a simple +text-based file format for all its configuration files. It consists of +key-value pairs that are placed in groups. All &kde; configuration +files use UTF-8 encoding for text outside the +ASCII range. + +The start of a group is indicated by a group name that is placed +in square brackets. All the key-value entries that follow belong to +the group. The group ends when either another group starts or when the +end of the file is reached. Entries at the top of the +file that are not preceded by a group name belong to the default +group. + +The following example shows a configuration +file that consists of two groups. The first group contains the keys +LargeCursor and SingleClick, the +second group contains the keys Show hidden files +and Sort by: + + +[KDE] +LargeCursor=false +SingleClick=true + + + +[KFileDialog Settings] +Show hidden files=false +Sort by=Name + + + +Entries in a group consist of a key and value separated by an equals +sign. The key can contain spaces and may be followed by options placed in +square brackets. The part after the equals sign is the value of the +entry. Any white space surrounding the equals sign is ignored, as is any +trailing white space. Put more concisely, the format is: + + +entry=value + + +If a value is supposed to include a space at the begin or end +then this can be achieved by using a backslash followed by an +s. + +There are several other backslash codes; here is a complete +list: + +\s can be used as space + +\t can be used to include a tab + +\r for a carriage return character + +\n for a linefeed character (new line) + +\\ to include the backslash itself + + + +In the following example the value of the +Caption entry starts with two spaces while the +Description entry contains three lines of +text. Linefeeds in backslash notation are used to separate the +different lines. + + +[Preview Image] +Caption=\s My Caption +Description=This is\na very long\ndescription. + + + +Empty lines in configuration files are ignored, as are lines that +start with a hash mark (#). The hash mark can be used to add +comments to configuration files. It should be noted that when a &kde; +application updates a configuration file the comments are +not preserved. + +There can be multiple configuration files with the same name in the +share/config sub-directory of the +various &kde; directory trees. In this case the information of all these +configuration files is combined on a key-by-key basis. If the same key +within a certain group is defined in more than one place, the key value read +from the directory tree with the highest precedence will be used. +Configuration files under $KDEHOME always have the highest +precedence. If a key in a certain group is defined multiple times in a +single file, the value of the last entry is used. + + +If $HOME/.kde/share/config/foobar +contains: + +[MyGroup] +Color=red +Shape=circle + +and /etc/opt/kde3/share/config/foobar contains + +[MyGroup] +Color=blue +Position=10,10 + +the result will be: + +[MyGroup] +Color=red +Shape=circle +Position=10,10 + + + + + +If + $HOME/.kde/share/config/foobar + contains + +[MyGroup] +Color=red +Shape=circle +[MyGroup] +Color=green + +and /opt/kde_staff/share/config/foobar contains + +[MyGroup] +Color=purple +Position=20,20 + +and /etc/opt/kde3/share/config/foobar contains + +[MyGroup] +Color=blue +Position=10,10 + +the result will be: + +[MyGroup] +Color=green +Shape=circle +Position=20,20 + + + + +To prevent users being able to override default settings, +settings can be marked immutable. Settings can be made immutable +individually, per group or per file. An individual entry can be locked +down by adding [$i] behind the key, ⪚: + +Color[$i]=blue + + +A group of entries can be locked down by placing +[$i] behind the group name, ⪚: + +[MyGroup][$i] + + +To lock down the entire file, start the file with +[$i] on a single line, &ie;: + +[$i] + + + + +If + $HOME/.kde/share/config/foobar + contains: + +[MyGroup] +Color=red +Shape=circle + +and /etc/opt/kde3/share/config/foobar contains: + +[MyGroup][$i] +Color=blue +Position=10,10 + +the result will be: + +[MyGroup] +Color=blue +Position=10,10 + + + + +If + $HOME/.kde/share/config/foobar + contains: + +[MyGroup] +Color=red +Shape=circle + +and /opt/kde_staff/share/config/foobar contains + +[MyGroup] +Color=purple +Shape=rectangle + +and /etc/opt/kde3/share/config/foobar contains + +[MyGroup][$i] +Color=blue +Position=10,10 + +the result will be + +[MyGroup] +Color=purple +Shape=rectangle +Position=10,10 + + + + + +So-called Shell Expansion can be used to provide more +dynamic default values. With shell expansion the value of a configuration +key can be constructed from the value of an environment variable or from the +output of a shell command. To enable shell expansion for a configuration +entry, the key must be followed by [$e]. Normally the +expanded form is written into the user's configuration file after first use. +To prevent that, it is recommend to lock the configuration entry down by +using [$ie]. The user can't change it then of course. + + +In the following example the value for the Host +entry is determined by the output of the hostname +program. This setting is also locked down to ensure that the value is always +determined dynamically. + +The value for the Email entry is determined by +filling in the values of the $USER and $HOST +environment variables. When joe is +logged in on joes_host this will +result in a value equal to joe@joes_host. The setting is +not locked down. + + +[Mail Settings] +Host[$ie]=$(hostname) +Email[$e]=${USER}@${HOST} + + + +Most configuration entries can be indexed with a language code. In +this case, the language that the user has selected for use on the desktop is +used to look up the key value. If the default language (American English) +has been selected or if there is no index that corresponds to the selected +language, the key entry without index is used. + + +In the following example the value of the Caption +entry depends on the language. If the user has selected French as language +(language code fr) the value of the entry will be +Ma Légende. In all other cases the value My +Caption will be used. + + +[Preview Image] +Caption=My Caption +Caption[fr]=Ma Légende + + + + +In this example the value of the Caption entry +depends on the language. If the user has selected French as language +(language code fr) the value of the entry will be +Ma Légende. In all other cases the value My +Caption will be used. + + +[Preview Image] +Caption=My Caption +Caption[fr]=Ma Légende + + + +In general the entries that can appear in a configuration file are not +documented. With &kde; 3.2 a start has been made to change this. In +$KDEDIR/share/config.kcfg, files +can be found that provide a formal description of the possible entries in a +configuration file. These are used by the new &kde; Configuration Editor +when available. + + +Here is an example &XML; configuration file: + + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd"> +<kcfg> + <kcfgfile name="korganizerrc"/> + <group name="General"> + <entry type="Bool" key="Auto Save"> + <label>Enable automatic saving of calendar</label> + <default>true</default> + </entry> + <entry type="Int" key="Auto Save Interval"> + <default>10</default> + </entry> + </group> +</kcfg> + + + +It has the same effect as: + +[General] +Auto Save=false +Auto Save Interval=25 + + + + + + + +&kde; Startup Sequence + + +&kdm; + +Always runs as root! Uses +$KDEDIR/share/config/kdmrc and +/etc/X11/xdm/Xservers. The latter contains entries +like: + + +:0 local /usr/X11R6/bin/X :0 vt07 + + +Relevant startup files are also: + + +[X-*-Core] section in kdmrc + + +Setup - /etc/X11/xdm/Xsetup + + +User enters username & password + + +Startup - /etc/X11/xdm/Xstartup - prepare as root + + +Session - /etc/X11/xdm/Xsession - starts session as user + + += For a KDE session: kde or startkde + + += If present ~/.xsession or ~/.xinitrc + + +Reset - /etc/X11/xdm/Xreset - after session finished + + + + + + +The &kde; Startup Script: <command>startkde</command> + +The &kde; startup sequence starts with the +startkde script. In most cases this script gets called +from the display manager (&kdm;) once the user has been authenticated. Their +are two very important lines in the startkde +script: + + +LD_BIND_NOW=true kdeinit +kcminit +knotify and kwrapper +ksmserver $KDEWM + + +The first line starts the kdeinit master process. +The kdeinit master process is used to start all other +&kde; processes. It show up in the output of ps + as kdeinit: +Running.... The arguments after kdeinit +are the names of additional processes to be started. The + +indicates that kdeinit needs to wait till the process has +finished. kdeinit also starts +dcopserver, klauncher and +kded. + +The second of the two lines asks kdeinit to start +the ksmserver session manager process. The session +manager determines the lifetime of the session. When this process exits, the +user is logged out. + + + + + +Background Processes + +All &kde; background services are user-specific: unlike system daemons +they are not shared between users. As well as being unique per user they are +also unique per X-server display. The processes are: + + + +dcopserver +Desktop communication + + + + +kded +Generic service daemon. +Triggers Sycoca database updates when +needed + + + + +kcminit +Initialization service +See for more information. + + + + +klauncher +Program launch (this is not the +&Alt;F2 +dialog!) +See for more information. + + + + +knotify +User notifications. +See for more information. + + + + +ksmserver +Session management +See for more information. + + + + + + +<command>kdeinit</command> +kdeinit is used to start all other &kde; +programs. kdeinit can start normal binary program files +as well as kdeinit loadable modules +(KLMs). KLMs work just like binary +program files but can be started more efficiently. KLMs +live in $KDEDIR/lib/kde3 + +The drawback is that programs started this way appear as +kdeinit in the output of +top and ps. Use top + or ps +to see the actual program name: + + +%ps + +waba 23184 0.2 2.1 23428 11124 ? S 21:41 0:00 kdeinit: Running... +waba 23187 0.1 2.1 23200 11124 ? S 21:41 0:00 kdeinit: dcopserver --nosid +waba 23189 0.2 2.4 25136 12496 ? S 21:41 0:00 kdeinit: klauncher +waba 23192 0.7 2.8 25596 14772 ? S 21:41 0:00 kdeinit: kded +waba 23203 0.8 3.4 31516 17892 ? S 21:41 0:00 kdeinit: +knotify + + + +kdeinit: Running... indicates the +master kdeinit process. The other processes listed are +programs started as KLMs. + +When kdeinit starts for the first time it will +launch dcopserver, klauncher, and +kded, as well as any additional programs specified on its +command line in the startkde script, normally +kcminit and knotify. + + + + +<command>dcopserver</command> + +dcopserver is a daemon which provides inter-process +communication (&DCOP;) facilities to all &kde; applications. The &DCOP; +facilities are accessible from the command shell via the +dcop command line tool. &DCOP; is essential for all &kde; +applications. + +Some related files: + + + +$HOME/.DCOPserver_$HOSTNAME_$DISPLAY +⪚ .DCOPserver_linux__0. Controlled by $DCOPAUTHORITY + + + + +/tmp/.ICE-unix/dcoppid-number +⪚ dcop7634-1069677856. This is +the file that the DCOPserver file above points to. + + + + +$HOME/.ICEauthority +Authorization information controlled by +$ICEAUTHORITY + + + + + + + +kcminit + +kcminit executes initialization services during +startup. Initialization services are specified in the .desktop files of +applications or services via the X-KDE-Init line: + + +[Desktop Entry] +Encoding=UTF-8 +Exec=kcmshell energy +Icon=energy_star +Type=Application +X-KDE-Library=energy +X-KDE-Init=energy + + +Initialization services are typically used for initializing +hardware based on user-specified settings. + +kcminit + can be used to show all +initialization services and kcminit +service can be used to +execute a single service explicitly. This can be useful when investigating +startup problems. + + + + +<command>klauncher</command> + +klauncher is a daemon which is responsible for +service activation within &kde;. It operates in close connection with the +kdeinit master process to start new processes. &kde; +applications communicate with klauncher over &DCOP; in +order to start new applications or services. + +Best known from the error message: +KLauncher could not be reached via DCOP which +either indicates a serious problem with the dcopserver or +that klauncher crashed. + +klauncher can be restarted by restarting +kdeinit from a console window. Make sure that +$HOME, $DISPLAY and the various +$KDEDIR(S) are set correctly when doing so! + + + + +<command>knotify</command> + +The primary task of knotify is to relay sound +notifications to the sound server, it also provides alternative notification +methods. + + + + + + + +KSMServer + +ksmserver is &kde;'s session manager. On startup +the session manager launches auto-start applications and restores +applications from the previous session. The applications to auto-start are +indicated by .desktop files in the +$KDEDIR/share/autostart +directory. Whether or not to auto-start an application can be made +conditional upon some configuration entry determined by the +X-KDE-autostart-condition entry in the .desktop file. + + +The ktip.desktop file for example +contains: + + +X-KDE-autostart-condition=ktiprc:TipOfDay:RunOnStart:true + + +This means that the ktiprc configuration +file is checked for a RunOnStart entry in the +[TipOfDay] section. If no such entry is found, +true is assumed, which means that +ktip is one of the applications that is +auto-started by default. + + +Some of the applications auto-started by ksmserver +are: + + + + +kdesktop +The &kde; desktop + + + + +&kicker; +The &kde; panel + + + + +ktip +A tip of the day program + + + + +kwrited +A utility to receive system messages sent to the user + + + + +&klipper; +A clipboard utility that docks in the panel + + + + +kalarm +A utility that warns about upcoming events and appointments + + + + + +kdesktop in its turn automatically starts +applications stored in $KDEHOME/Autostart. kdesktop +will automatically open any files stored in this directory including +documents, binary files or applications in the form of .desktop files. + +The &kde; session manager also restores one of the previous +sessions. A session contains a collection of applications as well as +application-specific information that reflects the state of the applications +at the time the session was saved. Sessions are stored in the +ksmserverrc configuration file which contains +references to application-specific state information. The +application-specific state information is saved in $KDEHOME/share/config/session. +The state information of &kwin; contains the location of the application +windows of all the other applications in the session. + + + + + +Environment variables + +Some important environment variables used by &kde;: + + + + +$KDEDIR +Has to be set if +KDEDIRS is not set and has to point to the root of the +&kde; installation tree. Allows &kde; to find its data like icons, +menus and libraries. + + + +$KDEDIRS +Overrides KDEDIR and allows you to specify +multiple directories where &kde; searches for its data. Useful if you want +or have to install some programs to a different prefix than the rest of +&kde;. + + + +$KDEHOMEIf +not set, &kde; uses ~/.kde as +the directory where personal data is stored. + + + +$KDEROOTHOMEIf +not set, &kde; uses ~root/.kde +as the directory for root's +personal data. Was introduced to prevent &kde; from accidently +overwriting user data with root permissions when the user runs a &kde; +program after switching with su to root. + + + +$KDEWMIf the +KDEWM environment variable has been set, then it will +be used as &kde;'s window manager within the +startkde script instead of &kwin;. + + + +$KDE_LANGOverrides +the &kde; language configuration, ⪚ KDE_LANG=fr kprogram +& starts a program with French translation if the +necessary files are installed. + + + +$KDE_MULTIHEADSet +this variable to true to indicate that &kde; is running +on a multi-head system. + + + +$KDE_FORK_SLAVES +(Since &kde; 3.2.3) Set this variable to spawn +KIO-slaves directly from the application process +itself. By default KIO-slaves are spawned using +klauncher/kdeinit. This option is +useful if the KIO-slave should run in the same +environment as the application. This can be the case with +Clearcase. + + + +$KDE_HOME_READONLY +Set this variable to indicate that your home directory is +mounted as read-only. + + + +$KDE_NO_IPV6 +(Since &kde; 3.2.3) - Set this variable to disable IPv6 +support and IPv6 DNS +lookups. + + + +$KDE_IS_PRELINKED +(Since &kde; 3.2) - Set this variable to indicate that you have prelinked +your &kde; binaries and libraries. This will turn off +kdeinit. + + + +$KDE_UTF8_FILENAMESIf +this environment variable is set, &kde; assumes all filenames are in +UTF-8 encoding regardless of the current C +locale. + + + +$KDE_FULL_SESSION +(Since &kde; 3.2) Automatically set to true by &kde; startup, it is used +by ⪚ &konqueror; to know if it should consider remaining in memory +for future re-use when being closed. If not set, &konqueror; will exit +after being closed (⪚ &kdesu; does that, it's also useful for +debugging). + + + +$KDESYCOCAAllows +you to specify the path and the name of the generated &kde; system +configuration cache file. + + + +$KDETMPAllows +to specify another path than /tmp where &kde; stores its temporary +files. + + + +$KDEVARTMPAllows +to specify another path than /var/tmp where &kde; stores its variable +files. + + + +$XDG_DATA_HOME +(Since &kde; 3.2) Defines the base directory relative to which user-specific +data files should be stored. Default is $HOME/.local/share + + + +$XDG_DATA_DIRS +(Since &kde; 3.2) Defines the preference-ordered set of base directories to +search for data files in addition to the $XDG_DATA_HOME base +directory. Default is +/usr/local/share/:/usr/share/ + +&kde; adds locations from $KDEDIRS and profiles +as well. Used for .desktop and +.directory menu files. .desktop files under $XDG_DATA_DIRS/applications. +.directory files under +$XDG_DATA_DIRS/desktop-directories + + + + +$XDG_CONFIG_HOME +(&kde; 3.2) - Defines the base directory relative to which user +specific configuration files should be stored. Default is +$HOME/.config. + + + +$XDG_CONFIG_DIRS +(&kde; 3.2) - Defines the preference-ordered set of base directories +to search for configuration files in addition to the $XDG_CONFIG_HOME +base directory. The default is /etc/xdg &kde; adds locations from +$KDEDIRS and profiles as well. Used by .menu descriptions in +$XDG_CONFIG_DIRS/menus. + + + + + + + + +The kdeinit Mystery + + + +kdeinit is used to start all other &kde; +programs. kdeinit can start normal binary program f iles +as well as kdeinit loadable modules +(KLMs). KLMs work just like binary +program files but can be started more efficiently. KLMs +live in $KDEDIR/lib/kde3 + +The drawback is that programs started this way appear as +kdeinit in the +output of top and ps. Use +top or ps + to see the actual program name: + + +% ps aux | grep bastian + +bastian 26061 0.0 2.2 24284 11492 ? S 21:27 0:00 kdeinit: Running... +bastian 26064 0.0 2.2 24036 11524 ? S 21:27 0:00 kdeinit: dcopserver +bastian 26066 0.1 2.5 26056 12988 ? S 21:27 0:00 kdeinit: klauncher +bastian 26069 0.4 3.2 27356 16744 ? S 21:27 0:00 kdeinit: kded +bastian 26161 0.2 2.7 25344 14096 ? S 21:27 0:00 kdeinit: ksmserver +bastian 26179 1.1 3.4 29716 17812 ? S 21:27 0:00 kdeinit: kicker +bastian 26192 0.4 3.0 26776 15452 ? S 21:27 0:00 kdeinit: klipper +bastian 26195 1.0 3.5 29200 18368 ? S 21:27 0:00 kdeinit: kdesktop + + +As you might have noticed, this has another side effect, making it +difficult to kill a process that is causing trouble: + +% killall kdesktop +kdesktop: no process killed + +You might be tempted to try killall +kdeinit, but killing all kdeinit processes will have +the effect of shutting down all of &kde;. In effect, total +destruction! + +There are two simple solutions to this: + +% kdekillall kdesktop +or good old +% kill 26195 +kdekillall is part of the &kde; SDK +package. + + + + + + +Customizing &kde; + + + +Desktop Icons + +&kde; uses several types of icons: + +Documents + +Links to Websites (using .desktop file) + +Links to Applications (using .desktop file) + +Devices - Disks, Partitions & Peripherals: + +Explicit using .desktop file + +Automatic via devices:// io-slave + + + + +Vendor-specific (⪚ &SuSE;'s My Computer) + + + + +Websites + +Links to Websites using .desktop +file: Create +NewFileLink to +Location (URL). Change Icon using +Properties dialogs. The resulting .desktop file: + +[Desktop Entry] +Encoding=UTF-8 +Icon=/opt/kde3/share/apps/kdesktop/pics/ksslogo.png +Type=Link +URL=http://www.kde.org/ + + + + + +Applications + +Links to Applications using .desktop file: Create +NewFileLink to +Application. You must provide details +yourself. Drag from &kde; Menu: Either copy or link (creates symlink), +much easier + + + + + + +[Desktop Entry] +Encoding=UTF-8 +GenericName=IRC Client +GenericName[af]=Irc Kliët +GenericName[de]=IRC Programm +... +GenericName[zu]=Umthengi we IRC +SwallowExec= +Name=KSirc +Name[af]=Ksirc +Name[de]=KSirc +... + + + +Boiler plate + +Translated generic description, not used on desktop + +Legacy, can be removed + +Translated name as it appears on desktop + + + +Desktop Icons + +... +Name[zu]=Ksirc +MimeType= +Exec=ksirc %i %m +Icon=ksirc +TerminalOptions= +Path= +Type=Application +Terminal=0 +X-KDE-StartupNotify=true +X-DCOP-ServiceType=Multi +Categories=Qt;KDE;Network + + + +Supported &MIME; types, not used on +desktop + +The command line to execute + +The icon, from icon theme or full path + +Only used if terminal is +needed + +Working directory for command + +More boiler plate + +Use true if terminal is needed, +text application + +Show bouncy cursor, +disable if it doesn't work. + +Has app started ok? +Remove if it doesn't work + +Categories for &kde; Menu, not +used on desktop + + + + + + + + +The <varname>Exec</varname> option in <literal +role="extension">.desktop</literal> files + +Following the command, you can have several place holders which will +be replaced with the actual values when the actual program is run: + + +%f A single file name; used when dropping +file on icon, or with file associations. + + + + +%F +A list of files; use for applications that can +open several local files at once. + + + + +%u +A single &URL;: if the app can +handle ⪚ &FTP; or &HTTP; &URL;s itself, otherwise &kde;. + + + + +%U +A list of +&URL;s; will download the file first and pass a local file to the app +(!!) + + + + +%d +The folder of the file to open; useful if app needs to +have file in current working directory. + + + + +%D +A list of folders, not very practical. + + + + +%i +The icon; option; &kde; app +will use icon from Icon= line in taskbar. + + + + +%m +The mini-icon; legacy. + + + + +%c +The caption; option; &kde; +app will use name from Name= line in +taskbar. + + + + + + + +Examples: + +Exec line +Command executed +ksirc %iksirc --icon ksirc + +cd %d; kedit $(basename %f)cd /tmp; kedit file.txt + + + + + + + + + + + +Devices + +Links to Devices using .desktop file: +o Create New -> Device + + + + + +Where to Define + +Many places to define Desktop Icons: + + +~/Desktop: +copied from /etc/skel/Desktop + +$KDEDIR/apps/kdesktop/Desktop +(merged) + +$KDEDIR/apps/kdesktop/DesktopLinks +(copied) + +Device Icons (dynamically +merged) + +Distribution Specific SUSE Linux copies certain icons +in startkde.theme from /opt/kde3/share/config/SuSE/default/ + + + + + + + +&kde; Menu + + +How it Works + +In &kde; 3.2 a common menu format is introduced at +http://freedesktop.org/Standards/menu-spec/ +Before &kde; 3.2: + + +Directory structure under share/applnk + +Directory structure represents menu +structure + +Each .desktop file +represents a single application + + + + +It was difficult to rearrange the structure in &kde; 3.2 so the +new menu format: + +Defines structure in a single .menu file +Is based on categories +is shared between GNOME and &kde; +Supports applnk style menus as well + + + + +Example from applications.menu: + + + <Menu> + <Name>Office</Name> + <Directory>suse-office.directory</Directory> + <Include> + <Filename>Acrobat Reader.desktop</Filename> + <Filename>kde-kpresenter.desktop</Filename> + <Filename>kde-kword.desktop</Filename> + </Include> + <Menu> + + + +Menu entry with 3 applications: + + +/usr/share/applications/Acrobat +Reader.desktop + +/opt/kde3/share/applications/kde/kpresenter.desktop + +/opt/kde3/share/applications/kde/kword.desktop + + + + + + + +Stored Where? + +.menu files describing the +menu structure. The files are stored in $KDEDIR/etc/xdg/menus and +/etc/xdg/menus. These store the +system-wide menu structure and are controlled by +$XDG_CONFIG_DIRS. $HOME/.config/menus stores +user-specific changes to the menu structure and is controlled by +$XDG_CONFIG_HOME. For more information, see http://www.freedesktop.org/Standards/basedir-spec. + +.desktop files describe the +applications and are stored in: $KDEDIR/share/applications, +/usr/share/applications, +/usr/local/share/applications. These are +the system-wide application .desktop files which are controlled by +$XDG_DATA_DIRS. + +$HOME/.local/applications +contains user-specific .desktop +files and user-specific changes. It is controlled by +$XDG_DATA_HOME. For more information, see http://www.freedesktop.org/Standards/basedir-spec + + +.directory files describing +the sub-menus are stored in: $KDEDIR/share/desktop-directories, +/usr/share/desktop-directories, /usr/local/share/desktop-directories. +These are the system-wide menu .directory files, controlled by +$XDG_DATA_DIRS. The user-specific changes are stored in $HOME/.local/desktop-directories. +These are controlled by $XDG_DATA_HOME. For more +information, see http://www.freedesktop.org/Standards/basedir-spec + + +Example from applications.menu: + + + <Menu> + <Name>Art</Name> + <Directory>suse-edutainment-art.directory</Directory> + <Include> + <Category>X-SuSE-Art</Category> + </Include> + </Menu> + + + + +Art is the internal name for this +menu. suse-edutainment-art.directory defines the +name and icon for this menu, and the menu includes all applications +that have X-SuSE-Art listed as a category, ⪚: + +Categories=Qt;KDE;Education;X-SuSE-Art + + +suse-edutainment-art.directory defines the +name and icon for this menu: + +[Desktop Entry] +Name=Art and Culture +Icon=kcmsystem + + + + + + +Common Pitfalls + +Applications not in the menu do +not exist with regard to other applications or +file associations: If you remove an application from the menu, &kde; assumes you don't want to use it. + +When applications are unwanted in the menu, either place them in +.hidden menu or a dedicated menu with + +NoDisplay=true + in the .directory file + + + +Essential Menus + +$KDEDIR/etc/xdg/menus/applications-merged/ +contains kde-essential.menu which includes some +essential menus that are normally not shown in the &kde; menu itself: + +Control Center has a hidden Settings menu whose +contents are defined by kde-settings.menu and +whose icon and name are defined by kde-settings.directory + +Info Center has a hidden Information menu whose +contents are defined by kde-information.menu and +whose icon and name are defined by kde-information.directory. + + +Screensavers contains a hidden System/Screensavers menu, +whose contents are defined by +kde-screensavers.menu and whose icon and name +are defined by +kde-system-screensavers.directory. +$KDEDIR/share/desktop-directories/kde-system-screensavers.directory +contains: + +NoDisplay=true + + + + + + + +Old-Style Menus + +&kde; continues to support old-style menus that are defined by +the directory structures in $KDEDIR/share/applnk +(system wide) and $HOME/.kde/share/applnk +(user specific). This is observed unless the .desktop file has a Categories= line. In that case the categories determine the location in the menu. + + + +<application>KSycoca</application> +KSycoca caches menu structure and +information about all available applications. You can rebuild the +database with +kbuildsycoca. The database +which is built lives in /var/tmp/kdecache-${USER}/ksycoca. +It is automatically updated by KDED, +checked during &kde; login, and KDED +watches for changes while logged in. + +To disable watching for changes (since it may hurt over NFS) add +the following to kdedrc: + +[General] +CheckSycoca=false + + + +To force regeneration, run touch $KDEDIR/share/services/update_ksycoca. + + + + +&kmenuedit; + +&kmenuedit; is aimed at a single user setup. Changes to menu +structure are saved to +~/.config/menus/applications-kmenuedit.menu, +changes to applications are saved in ~/.local/share/applications/ and changes +to sub-menus (icon, name) are saved in ~/.local/share/desktop-directories/. The +KIOSK Admin Tool uses &kmenuedit; and copies the above changes to +profile- or system-wide locations. + + + + + + + + +&kde; Panel + +The &kde; panel is also known as &kicker;. It is modular and +consists of the following components: + +Applets +Application buttons +Special Buttons + + + +By default, the panel contains the following applets: + +Pager - shows the virtual desktops +Taskbar +System Tray +Clock + +and the following special buttons: + +&kde; menu +Desktop Button + + + +Various application buttons are also added, space permitting: + +Home Button +Browser Button +KMail Button + + + + + +File Associations + +File associations associate a file type with an application or +applications. The type of a file is established by determining its +&MIME; type. &MIME; types known by &kde; are stored in $KDEDIR/share/mimelnk and +each application's .desktop file +contains a list of &MIME; types supported by that application. + + +kview.desktop: + +MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg; +image/x-bmp;image/png;image/x-ico;image/x-portable-bitmap; +image/x-portable-pixmap;image/x-portable-greymap; +image/tiff;image/jp2 + + + +kuickshow.desktop: + +MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg; +image/png;image/tiff;image/x-bmp;image/x-psd;image/x-eim; +image/x-portable-bitmap;image/x-portable-pixmap; +image/x-portable-greymap + + + +Both can open image/gif Which one is used to open a .gif file? + +The application with highest +preference!. kview.desktop contains + +InitialPreference=3 + +whereas kuickshow.desktop contains + +InitialPreference=6 + +Therefore, &kuickshow; will be used to open .gif files. + + +How can we make &kview; default? + +A user can change file association in the +&kcontrolcenter;. These changes are stored in +$HOME/.kde/share/config/profilerc. +To use the same settings for multiple users, store these settings in +user profile directory or the global &kde; config directory to use as +default for multiple users. + + + + + + + + +Locking Down &kde; + + +How It Works - The Basics + +&kde;'s lock down features are centered around the following +options: + + +Make +configuration options immutable +Restriction of specific +actions +Restrict access to certain +&URL;s +Restrict access to +certain configuration modules + + + + + +Immutable Configuration Options +Locking Down &kde; + +Immutable options allow system administrator to provide default +settings that can not be changed by the user. + +Pre-existing configuration options of the user will be ignored once a +configuration option is made immutable. + +Options can be controlled either on a per entry basis, per group of +entries or on a file by file basis. + +If a file or group is immutable, all configuration options for that +file or group are immutable, even those options for which the system +administrator has no default provided. + +The support in applications for immutable options may vary from +application to application. Although the user will not be able to make +permanent changes to immutable configuration options, the user may still be +presented with an user interface option to make such change. + + + + +Action Restrictions + +&kde; applications are built around the action-concept. Actions can be +activated in various ways, typically via the menu-bar, one of the toolbars +or a keyboard shortcut. Save Document is an example of an +action. If you know the internal action name it is possible to restrict an +action. When an action is restricted it will no longer appear in the +menu-bar or toolbar. The internal name for the Save +Document action is . The lock +down framework also provides a set of more abstract restrictions which can +be used to disable functionality not covered by a single action. An example +is the restriction which disables all +functionality that would offer the user access to a &UNIX; shell. + + +Restrict User Access to Shells + +In order to prevent the user access to a command shell we can restrict +the action by adding the following to +kdeglobals: + + +[KDE Action Restrictions] +shell_access=false + +Since this affects the &kde; menu and the available applications, we +must force an update of the sycoca database: + +touch $KDEDIR/share/services/update_ksycoca + +Now re-login to &kde; and check the following points: + + +The &kmenu; +In &konqueror;, +ToolsOpen +Terminal +The &Alt;F2 run +command + + +Full documentation about available actions can be found on http://www.kde.org/areas/sysadmin/. + +A few of the more interesting actions are listed below: + + + + +The Configure option form the +Settings menu + + + +The Report Bug option from the +Help menu. + + + +&RMB; mouse button menu on the desktop. + + + +&RMB; mouse button menu on the panel. + + + +Hide all actions or applications that require root access. + + + +Hides all actions or applications that provide shell +access. + + + +Disables the option to select the printing system +(backend). + + + +Whether the user will be able to lock the +screen + + + +Whether the user may start a second X session (see also +&kdm;) + + + +Whether OpenGL screensavers are allowed to be +used. + + + +Permit screensavers that do not hide the entire +screen + + + + + + +&URL; Restrictions + +There are three types of restrictions that can be applied to +&URL;s: + + + +list +To control whether a directory listing is +allowed. + + +open +To control whether certain &URL;s can be +opened + + +Redirect +To control whether one &URL; can open another &URL;, either +automatically or via a hyperlink. + + + +Rules are checked in the order in which they are defined. The last +rule that is applicable to a &URL; defines whether the &URL; may be +accessed. + +The following rules disable opening http and https &URL;s outside +.ourcompany.com: + + + + + + +[KDE URL Restrictions] +rule_count=2 +rule_1=open,,,,http,,,false +rule_2=open,,,,http,*.ourcompany.com,,true + + + +The first four commas skip over the selection criteria with respect to +the originating &URL;. This part is only needed with redirect type +rules. + + forbids the +opening of any http or https &URL; + allows the +opening of any http and https &URL; in the .ourcompany.com domain. Note the wildcard +* is only allowed at the start of a domain. + + +The following rules makes that the user can no longer browse +directories on the local file system that are outside his +$HOME directory: + + + + + +[KDE URL Restrictions] +rule_count=2 +rule_1=list,,,,file,,,false +rule_2=list,,,,file,,$HOME,true + + + forbids the +listing of any local directory + allows listing +directories under the users own $HOME +directory. + + +$HOME and $TMP are special values to +indicate the users home directory and the &kde; temporary directory of the +user, ⪚ /tmp/kde-bastian + +The following rules makes that the user can no longer open local files +that are outside his $HOME directory: + + + + + + +[KDE URL Restrictions] +rule_count=3 +rule_1=open,,,,file,,,false +rule_2=open,,,,file,,$HOME,true +rule_3=open,,,,file,,$TMP,true + + + forbids the +opening of any local file + allows opening +files under the users own $HOME directory. + allows opening +files in the &kde; temporary directory of the user. This is needed by +certain &kde; applications that first download a file or document to the +temporary directory and then open it in an application. + + + +The redirection option controls whether documents from a certain +location can refer, either automatically or manually via a hyperlink, to a +certain other location. A set of default rules is present as a general +security measure. For example documents located on the Internet may not +refer to locally stored documents. + +For example, if we want to give the intranet-server www.mycompany.com the possibility to refer +to local files we could add the following rule: + +[KDE URL Restrictions] +rule_count=1 +rule_1=redirect,http,www.mycompany.com,,file,,,true + +Instead of listing a protocol by name, it is also possible to specify +a whole group of protocols. For that the following groups have been +defined: + + + +:local +Protocols that access locally stored information, examples +are file:/, man:/, fonts:/, floppy:/ + + +:internet +Common internet protocols such as http and +ftp + + + +Information about protocols is stored in *.protocol files stored in +$KDEDIR/share/services. + +The = entry defines the group a protocol is part +of: +grep +$KDEDIR/share/services/*.protocol + +General rules: + + +The :local protocols may refer to any other +protocol +It's always allowed to refer to an :internet +protocol +Not all protocols are part of a group, fish:/ for +example. + + + + + +Configuration Modules + +&kde; has configuration modules to configure various aspects of the +&kde; environment. Configuration modules appear in the Control Center, in the +Configuration dialog of an application or in both. + + +The proxy configuration module appears in the Control Center but also +as part of the Configure Konqueror dialog in +&konqueror; + +Individual configuration modules can be started with +kcmshell module + +To start the Proxy module use: + +kcmshell +kde-proxy.desktop +kcmshell proxy + + +Not all applications use configuration modules, often the +configuration dialog is an integral part of the application +itself. + + +All configuration modules are strictly speaking part of the &kde; +menu. + + + +The modules that are visible in the Control Center normally +have a .desktop file in $KDEDIR/share/applications/kde +and are sorted under the hidden Settings-Modules menu by +the kde-settings.menu, included from +kde-essential.menu +kbuildsycoca 2> /dev/null | grep Settings-Modules + + +Application specific modules normally have a .desktop file under +$KDEDIR/share/applnk/.hidden which +corresponds to the hidden .hidden menu, included as a result of +<KDELegacyDirs/> +kbuildsycoca 2> /dev/null | grep .hidden + +In &kde; 3.3 it is possible to edit the Control Center with +kcontroledit. +kcontroledit works just like +kmenuedit, changes for current user only. Use +kiosktool to make changes for +everyone. + + +Individual configuration modules can be disables by adding the +following to kdeglobals: + +[KDE Control Module Restrictions] +module-id=false +For example, to disable the proxy module use +[KDE Control Module Restrictions] +kde-proxy.desktop=false +Check the Control Center and the Configure +Konqueror dialog if the proxy configuration is still +there. + + + + + + +The Lazy Admin + + + + + + + +Remote Desktop Sharing + +Remote desktop sharing allows remote users to view and optionally +control the desktop of the current user. The remote user needs to be sent +an invitation, and it is possible to create a password protected standing +invitation. This is ideal for tech support teams or administrators to gain +access to users desktops in order to troubleshoot or remedy a problem or +guide a user through a procedure. + +Remote desktop sharing involves two applications: &krfb; (&kde; remote +frame buffer, a VNC server) and &krdc; (&kde; remote desktop connection; a +VNC client.) + +&krfb; can be used by any user to create and manage invitations. +Invitations create a one time password that allows the recipient to connect +to your desktop. By default it is valid for only one successful connection, +and expires after one hour if not used. + +Incoming connections are handled by the kinetd kded module. You can +use the command dcop kded kinetd +services to see if it is running. &krfb; waits for connections +on port 5900 by default. When an incoming connection is made, a dialog will +appear to ask for confirmation by the current user. + + + + + + +&kde; DIY - Building Your Own Tools + + +DCOP + + +Desktop COmmunication Protocol, DCOP, is a lightweight mechanism for inter-process communication. +DCOP allows the user to interact with programs that are currently running. +&kde; supplies two programs to utilitize DCOP: +dcop, a command-line program, and +kdcop, a GUI program. + + +A few notes about using dcop: + + + + + + +dcop [options] [application [object [function [arg1] [arg2] ... ] ] ] + + + + +Applications that can open more than one window at a time will be listed as +<application>-PID + + + + +All the arguments are case-sensitve. setFullScreen and setfullscreen are two different functions. + + + + +The regular expression token * can be used in the application and object arguments. +% dcop +konqueror-16006 +konsole-8954 + + + + + + + + +Some example commands and their output are below: + + + +% dcop +konsole-8954 + +One &konsole; is running with a PID of 8954. + +% dcop +KBookmarkManager-.../share/apps/kfile/bookmarks.xml +KBookmarkManager-.../share/apps/konqueror/bookmarks.xml +KBookmarkNotifier +KDebug +MainApplication-Interface +konsole (default) +konsole-mainwindow#1 +ksycoca +session-1 +session-2 +session-3 +session-4 + +Here you see that there are four sessions running. + +% dcop +QCStringList interfaces() +QCStringList functions() +int sessionCount() +QString currentSession() +QString newSession() +QString newSession(QString type) +QString sessionId(int position) +void activateSession(QString sessionId) +void nextSession() +void prevSession() +void moveSessionLeft() +void moveSessionRight() +bool fullScreen() +void setFullScreen(bool on) +ASYNC reparseConfiguration() + +Here are the options for the main &konsole; program. + + +% dcop +QCStringList interfaces() +QCStringList functions() +bool closeSession() +bool sendSignal(int signal) +void clearHistory() +void renameSession(QString name) +QString sessionName() +int sessionPID() +QString schema() +void setSchema(QString schema) +QString encoding() +void setEncoding(QString encoding) +QString keytab() +void setKeytab(QString keyboard) +QSize size() +void setSize(QSize size) + +Here are the options for the first session, session-1. + +% dcop true + +This sets &konsole; to full screen. + + + + +When there is more than one application/object, which one should you use? + Got a reference? + +% echo +DCOPRef(konsole-7547,konsole) + +% dcop +session-6 + +% dcopstart +konsole-9058 + + +#!/bin/sh +konsole=$(dcopstart konsole-script) +session=$(dcop $konsole konsole currentSession) +dcop $konsole $session renameSession Local + +session=$(dcop $konsole konsole newSession) +dcop $konsole $session renameSession Remote + +session=$(dcop $konsole konsole newSession) +dcop $konsole $session renameSession Code +dcop $konsole $session sendSession 'cd /my/work/directory' + + + + + + +KDialog +&kde; DIY - Building Your Own Tools + +You can use &kde; dialogs from your own scripts, to combine the power +of &UNIX; shell scripting with the ease of use of &kde;. + +kdialog + +kdialog + +The KDialog part can be replaced via + option + +kdialog + +Saves whether to show again in +$KDEHOME/share/config/myfile (by writing +into this file the following lines: + +[Notification Messages] +mykey=false + +Instead of you can also use + and , as appropriate. For +instance, you might use kdialog or kdialog +. + +It is also possible to create message boxes that accept a yes or no +answer. + +kdialog echo $? + + + + + +Return Value +Meaning + + + +0Yes, OK, Continue +1No +2Cancel + + + + +Make sure to store the result in a variable if you do not use it +directly, the next command will fill $? with a new value You can use + here as well, it will remember the users choice +and returns it the next times without showing the dialog any more. + +Further variations are: + + + + + +like but with a different +icon + + + + +With Continue and +Cancel buttons. + + + + +With Yes, No +and Cancel button. For example: +kdialog + + + + +kdialog + +The result is printed to stdout, to put it in a variable you can use +name=$(kdialog --inputbox "Enter your name:" +"YourName"). The last argument is optional, it is used to +pre-fill the dialog. + +password=$(kdialog ) + +The option does not work with + or + +There are two dialogs that let the user make a choice from a +list: + + + + + +Lets the user select a single item from a list. + + + + + +Lets the user select one or more items from a list. + + + + +city=$(kdialog ) + +$city will a, b, c or d. + +city=$(kdialog ) + +Madrid and Paris will be pre-selected. The result with Madrid and +Paris selected will be "b" +"c". + +If you add the option, it will put +b and c each on a line +of its own, making the result easier to process. + +file=$(kdialog --getopenfilename $HOME) +file=$(kdialog --getopenfilename $HOME "*.png *.jpg|Image Files") +file=$(kdialog --getsavefilename $HOME/SaveMe.png) +file=$(kdialog --getexistingdirectory $HOME) + + + + + + + +&groupware-with-kontact; + + + + diff --git a/doc/userguide/kde-office.docbook b/doc/userguide/kde-office.docbook new file mode 100644 index 000000000..176180294 --- /dev/null +++ b/doc/userguide/kde-office.docbook @@ -0,0 +1,321 @@ + + + + + +Raphael +Langerhorst + +raphael.langerhorst@kdemail.net + + + + + + + +Office + + +Introduction to KOffice + + +Overview + +The &kde; project has also created a fully featured office suite +called &koffice; which adheres to standards and fits very well into +the &kde; desktop. This section was written with version 1.4 of +&koffice; in mind. + + +&koffice; is a highly integrated office suite that builds directly on the +KDE technology. This has many advantages in terms of integration, features, +performance, familiar look and feel and so on. All technologies like &DCOP;, +KIO, KParts are directly available. + + +In particular the KParts technology is extended for the &koffice; +components to allow very flexible embedding of documents inside documents. + + +Because much technology is already present inside &kde; itself, &koffice; is +a very lightweight office suite, which results in fast application startup +and low memory consumption. This makes &koffice; a very suitable office suite +for older hardware as well, which can save lots of costs in some cases. + + +&koffice; is also a very feature complete office suite. It is not limited to +word processing, spreadsheets or presentations, but has also components for +image manipulation, flow charts, business report generation, database +management and project management. Because of the flexible component +integration smaller utilities like the diagram and chart engine as well +as the formula editor are available as stand alone tools. + + +As you can see &koffice; brings a lot of features that can enrich your +office experience. Its straight forward and &kde; like approach in look +and feel as well as familiar usability makes &koffice; quite useful for +daily office work. + + + + + +Features + +This list gives a general outline of the &koffice; features. +The &koffice; office suite is too large to list every detail. + + +&koffice; features: +Fully builds on &kde; which makes these technologies available at low costs. +Fully integrates into &kde; which is vital for business environments. +&kde; technologies include document location abstraction, DCOP scripting, parts and plugins,... +Full Component embedding. +Low memory footprint, fast startup, lightweight. +Feature complete: many components are offered. +Intuitive, good looking and easy to learn user interface. +Adheres to standards: OASIS OpenDocument file format. + + + + +OASIS OpenDocument file format + +It is important for an office suite to use standards where possible, +especially for the file format. The OASIS OpenDocument file format +specification is an open standard for office applications. This +format is spreading more and more, it is also the same file format +OpenOffice.org uses, which means that file exchange with any +user of this office suite is easily possible. + + +Adhering to official standards is always a good thing. For business +environments it is even vital to exactly know about their documents. + + +&koffice; has more components to offer than what is covered by the +OASIS specification. Still, all components covered by the specifications +actually use the OASIS OpenDocument file format. + + + + + + + +&koffice; Components Overview + +Keep in mind that all these components can integrate very well into each other. So basically a spreadsheet can contain anything from charts to presentations, reports and even text documents. Likewise almost any component can contain almost any other. + + + + +&kword; + The textprocessing component, but it includes many aspects of a desktop publishing application. This creates a rather unique mixture of features that makes interesting layouts easily possible. + + + Website: http://www.koffice.org/kword/ + &kword; Handbook + + + + + + +&kspread; + The spreadsheet component. &kspread; is a scriptable spreadsheet program which provides both table-oriented sheets and support for complex mathematical formulas and statistics. Features include Hyperlinks, cell data validity checking with configurable warnings/actions, scripting and specific cell customization. + + + Website: http://www.koffice.org/kspread/ + &kspread; Handbook + + + + + + +&kpresenter; + The presentation component. It can be used to create on-screen presentations or to design and print transparencies. Features include embedding images and clip-art, easy working with objects, and the ability to make &HTML; or &XML; slideshows. + + + Website: http://www.koffice.org/kpresenter/ + &kpresenter; Handbook + + + + + + +&kivio; + The flowcharting and diagramming component. Additional stencil sets can be used for custom needs, there is a plugin framework for additional functionality, and even UML diagrams are possible. + + + Website: http://www.koffice.org/kivio/ + &kivio; Handbook + + + + + + +&karbon14; + A vector-drawing application. + + + +&krita; + The painting and image manipulation component. &krita; contains both ease-of-use, fun features like guided painting, as well as high-end features like support for 16-bit images, CMYK and even OpenEXR HDR images. + + + Website: http://www.koffice.org/krita/ + &krita; Handbook + + + + + + +&kugar; + The appropriate component for creating business reports, which is accomplished with an advanced designer that it has. Features include report printing in postscript, full control of fonts, colors, text alignment and wrapping, as well as open report definition files (with the layout stored as &XML;). + + + Website: http://www.koffice.org/kugar/ + &kugar; Handbook + + + + + + +KPlato + The component for project management, allowing for the planning and scheduling of various projects. + + + Website: http://www.koffice.org/kplato/ + + + + + + +&kexi; + The data management component. It can be used for creating database schemas, inserting data, performing queries, and processing data. Forms can be created to provide a custom interface to your data. All database objects -- tables, queries and forms -- are stored in the database, making it easy to share data and database design. + + + Website: http://www.koffice.org/kexi/ and http://kexi-project.org. + &kexi; Handbook + + + + + + +&kchart; + The chart drawing component; it is used to embed charts into one of the other &koffice; components. It's easy to use, highly customizable allowing all of the parameters to be changed, and has a flexible layout. + + + Website: http://www.koffice.org/kchart/ + &kchart; Handbook + + + + + + +&kformula; + A formula editor which provides the basic input facilities and support functionality that appears in other &koffice; applications. Some of its features include intelligent cursor management, multi-level undo support and advanced syntax highlighting. + + + Website: http://www.koffice.org/kformula/ + &kformula; Handbook + + + + + + + + +Related Information + Main website: http://www.koffice.org. + &koffice; Handbook + + + + + + +Further Information + +Application Manuals +Each Koffice component comes with its own manual. +These manuals offer all the latest information about the +various components &koffice; has to offer and should be +read to learn more about &koffice;. The application manuals can be accessed by using the documentation KIO Slave in &konqueror; (that is, typing help:/application into the Location toolbar) or by selecting the respective handbook from the &khelpcenter;. The website is +also a good place to find out more; it is at http://www.koffice.org. + + + +Internet Resources +The primary site on the internet is +http://www.koffice.org +You will also find information about the user and developer +mailing lists as well as additional developer resources. +The Kexi project has even an additional website, which can be +found at http://www.kexi-project.org + + + + +Plugin development +&koffice; can easily be extended with plugins. Plugin development is +not very difficult and can be used to optimize your everyday workflow. Such +capabilities are probably very interesting in business environments to +make &koffice; meet individual requirements. You can either take a look +at existing plugins or read a general introduction at + +the developer's site. The general KDE developers website is available +at http://developer.kde.org. + + + + + diff --git a/doc/userguide/kmag.png b/doc/userguide/kmag.png new file mode 100644 index 000000000..cba958528 Binary files /dev/null and b/doc/userguide/kmag.png differ diff --git a/doc/userguide/kmousetool.png b/doc/userguide/kmousetool.png new file mode 100644 index 000000000..371f041ae Binary files /dev/null and b/doc/userguide/kmousetool.png differ diff --git a/doc/userguide/kmouth.png b/doc/userguide/kmouth.png new file mode 100644 index 000000000..c5507eaba Binary files /dev/null and b/doc/userguide/kmouth.png differ diff --git a/doc/userguide/kmouth2.png b/doc/userguide/kmouth2.png new file mode 100644 index 000000000..6cf0e613e Binary files /dev/null and b/doc/userguide/kmouth2.png differ diff --git a/doc/userguide/kmouth3.png b/doc/userguide/kmouth3.png new file mode 100644 index 000000000..8bed5a532 Binary files /dev/null and b/doc/userguide/kmouth3.png differ diff --git a/doc/userguide/knode-identity.png b/doc/userguide/knode-identity.png new file mode 100644 index 000000000..c9f63347f Binary files /dev/null and b/doc/userguide/knode-identity.png differ diff --git a/doc/userguide/knode-mail-account.png b/doc/userguide/knode-mail-account.png new file mode 100644 index 000000000..f2271662f Binary files /dev/null and b/doc/userguide/knode-mail-account.png differ diff --git a/doc/userguide/knode-news-account.png b/doc/userguide/knode-news-account.png new file mode 100644 index 000000000..e046870f1 Binary files /dev/null and b/doc/userguide/knode-news-account.png differ diff --git a/doc/userguide/knode-start.png b/doc/userguide/knode-start.png new file mode 100644 index 000000000..1057f946b Binary files /dev/null and b/doc/userguide/knode-start.png differ diff --git a/doc/userguide/konq-sidebar.png b/doc/userguide/konq-sidebar.png new file mode 100644 index 000000000..0e9328e3a Binary files /dev/null and b/doc/userguide/konq-sidebar.png differ diff --git a/doc/userguide/konq-simple.png b/doc/userguide/konq-simple.png new file mode 100644 index 000000000..a35133865 Binary files /dev/null and b/doc/userguide/konq-simple.png differ diff --git a/doc/userguide/konsole-intro.docbook b/doc/userguide/konsole-intro.docbook new file mode 100644 index 000000000..d42b4f59a --- /dev/null +++ b/doc/userguide/konsole-intro.docbook @@ -0,0 +1,126 @@ + + + + + +Gardner +Bell + + + + + +&konsole; Introduction + +Extremely brief intro to managing in a shell + +Emergency procedures: killing wild apps, etc + +SSH, sessions, envars, other fun things + +Some tips and tricks + + + + +&konsole; is a terminal emulator for the X Window System. It is +essentially based on the DEC's VT100 +and many of its succesors. &konsole; – also referred to as a +shell – is an +essential tool on &Linux; and &UNIX; based machines for fast and productive +work. + +Emergency Procedures: + +On &Linux; and &UNIX;-based systems every process runs independently in its own memory +space so it can't accidentally overwrite any other processes memory, unless +of course it has root privileges. +If a process in &kde; crashes due to a bug one should not need to worry +about it accessing any other active process. + +To keep track of all system processes use the top +command or ps in &konsole;. Using these utilities will +make it much easier to find and kill off rogue programs. + +An example of using signals in &konsole;, &konqueror; has crashed +leaving behind a running process of +nspluginviewer which is taking up 12% of your +memory and 10% of your cpu cycles. In top use the k +command switch to kill the task. You will be prompted for the PID and then +the signal to send to kill it. For more on info on what signals you can +send to a running process see the full manual on signals (type +man signal in a &konsole; or go to +#signal in &konqueror;). + +SSH, sessions, envars, other fun things. + +If you are using &konsole; for remote administration consider using +&konsole;'s Session feature. To use this click on the menu +entry +SettingsConfigure &konsole;. +From here choose the Sessions tab and fill in the +name for your new session. This will now become your default session when +you start &konsole;. + +When &konsole; is invoked bash specific +commands and &kde; specific variables are read and executed from +~/.bashrc or ~/.bash_profile. +The preferred configuration file for user environments is +~/.bash_profile, the commands +printenv or env can be used to +display all currently set variables. To set a variable in the shell use +VARNAME=value. For a full +list of variables that can be set in &kde; see the wiki +. + +Some tips and tricks + +To rename &konsole;'s session use &Ctrl;&Alt;S and enter the new +name. + +If you find the need to run any &kde; program with root privileges, you can use the &kdesu; command with the switch +from the command line like this: kdesu +, using +the switch will prevent &kde; from remembering your +passwords. + + + +Related Information + + +The &konsole; +Handbook has much more information about the features available in +&konsole;. You can read it in &khelpcenter; or by entering +help:/konsole in &konqueror;'s +Location bar. + + + + + + + + + + + diff --git a/doc/userguide/kopete.png b/doc/userguide/kopete.png new file mode 100644 index 000000000..446a26655 Binary files /dev/null and b/doc/userguide/kopete.png differ diff --git a/doc/userguide/kppp-dialer-tab.png b/doc/userguide/kppp-dialer-tab.png new file mode 100644 index 000000000..bb344979f Binary files /dev/null and b/doc/userguide/kppp-dialer-tab.png differ diff --git a/doc/userguide/kppp-wizard.png b/doc/userguide/kppp-wizard.png new file mode 100644 index 000000000..cbb731fcb Binary files /dev/null and b/doc/userguide/kppp-wizard.png differ diff --git a/doc/userguide/messaging-intro.docbook b/doc/userguide/messaging-intro.docbook new file mode 100644 index 000000000..8d042a451 --- /dev/null +++ b/doc/userguide/messaging-intro.docbook @@ -0,0 +1,188 @@ + + + + + +Peter +Nuttall + + + +Tom +Albers + + + + + + + +Introduction to messaging + + +The default way to send instant messages in &kde; is to use the IM +client, &kopete;. This is a multi-protocol IM client, meaning that it +handles several different protocols including MSN, +Jabber, AOL and IRC. It also has +useful features including support for &kaddressbook;, meta-contacts, +encryption support and lots more. + + +&kopete;, the &kde; IM client. + + + + +&kopete;, the &kde; IM client. + + +&kopete;, the &kde; IM client. + + + + + +How to get started + +Start up &kopete; from the menu (it can normally be found in the +Internet folder) When it starts up you should see a window with &kopete; +at the top, menus and a tool bar below, and then your contacts below. +You should add some accounts by clicking on the +Settings menu and selecting the Configure +Kopete option. By selecting the Accounts +option you should see a list of your accounts (initially empty) and +options to add new accounts and to edit or remove existing accounts. +By clicking on the add new account button, you can +add a new account using the wizard. When you have added an account, you can +connect to this account by clicking on the relevant icon at the bottom of +your main &kopete; window. This should make your contacts appear in the +contacts window. + + + + +Meta-contacts + +Meta contacts are one of the features of &kopete; that make sense +once you figure out what they are. Until you do, they annoy you. They are +basically a way of taking a contact on one network (such as +MSN) and linking it to another contact on a different +network. This is useful for when people have accounts on different networks +as you can chat to them without needing to know which account they are +signed on to. This also lets you assign names to your meta-contacts that +don't change when people change their names on their account, this is useful +if you have contacts who insist upon setting their +MSN nick to something like +=EF=81=8A. + +You can do other useful things with meta-contacts like link them to +entries in your address book. See + + + + +<acronym>IRC</acronym> + +Internet Relay Chat (IRC) has been around far longer than most IM +systems, and is still widely used. It is mainly designed for group (many-to-many) communication in discussion forums called channels, but also allows one-to-one communication. + +The #kde channel is under Freenode, the IRC server, which provides an interactive environment for coordination and support of peer-directed projects, including -- and placing particular stress upon -- those relating to free software and open source projects, such as &kde;. + + +While &kopete; has a IRC plugin, and handles both channels and nicks well, +long time IRC users might prefer a client designed just +for that role, which is what Konversation is. It supports features such +as granting and taking op status, banning, easy nick changing, special +channel support for passwords and invites, and other things that the power +IRC users expect. It also is far better at handling +large channels such as #debian. If you have used another +power-IRC client before, you should have no trouble using +Konversation. + + + + + +Linking email and messaging + +Did it happen to you? You received an email and the first thing +you would like to do is to give a reaction on it, but not by +email. So you switch to your instant messaging client and/or IRC +client and look if that person is online via MSN, Jabber or IRC. Well +&kde; 3.3 has made that a lot easier. A step-by-step manual: + +The requirements are &kmail;, &kaddressbook; and &kopete; +(Konversation should do as well). Make sure &kmail; is configured and +fully functional for email, and Kopete is well configured for IRC, +Jabber and/or MSN and/or any other protocol. + +If an email comes in from a contact you know, the first thing +you have to do is to add it to your address book. This can be achieved +by right clicking the address and choosing the entry Add to Address +Book. + +If you know the nickname which the user uses on, for example, IRC, +go to &kopete;. Go to +FileAdd +contact . In the wizard, select the +checkbox at the bottom called Use the KDE address book for +this contact and choose Next. Select +the right Address Book entry for that contact and press +Next. Now you can set the display name and the +group it belongs to for &kopete;. In the next screen select which +protocol should be used if you have set up more then one protocol. You +can select more than one protocol. After that, depending on the +protocol, there will be some other questions, which you can answer as +you like. + +Although we did specify to choose from the address book, +&kopete; has not automatically linked your contact to the address +book. So select the contact and choose +EditProperties +. On the General tab check the box +labeled Has address book entry. Press +... and select the contact. Close these two +windows. + +Now go to your addressbook, if you select the contact you will +see that it shows an extra field Presence, followed by the current +status. This status will automatically update as soon as the contact +goes away, offline, online, and so on. Now go to &kmail;, select another email and return to the original email (in other words: reload +the current email). You can now see behind the email address the +current state of your contact. + +If you want to chat with this person, just right click the +address in &kmail; and choose Chat With.... Your +Instant Messenger will start a conversation with the contact. + + + + + + + + + + + diff --git a/doc/userguide/migrator-applications.docbook b/doc/userguide/migrator-applications.docbook new file mode 100644 index 000000000..fee1caacd --- /dev/null +++ b/doc/userguide/migrator-applications.docbook @@ -0,0 +1,272 @@ + + + + +&Francis.Giannaros; &Francis.Giannaros.mail; + + + + +Application Guide for Migrates + + + +&kde; has many applications, often prefixed with (or containing) the letter k. The names are generally self-explanatory, but it can still be difficult sometimes to find the appropriate packages. Migrates from operating systems such as Microsoft Windows or Apple Macintosh might have some difficulty in locating an application for a particular job. Below is a table with an expansion on the &kmenu; and the respective Win/Mac equivalent. + +Sample Table + + + + + + + + + &kmenu; Location + &kde; Application + Windows Equivalent + Macintosh Equivalent + Notes + + + + + + File Manager + &konqueror; (Home Folder) + Windows Explorer + Integrated file manager, content +viewer/player and web browser + + + System and User Settings + &kcontrol; + Control Center + + + Office + Office Suite: + + Word Processing + Spreadsheets + Slide Presentations + Flowchart & Diagram Editing + Scalable Graphics + Image Manipulation + Report Generator + Chart + Database Creation + Formula Editor + + + + + + + &kword; + &kspread; + &kpresenter; + &kivio; + &karbon14; + &krita; + &kugar; + &kchart; + &kexi; + &kformula; + + + + + + + MS Word + MS Excel + MS Powerpoint + Adobe Illustrator + Adobe Photoshop + Report Generator + Chart + MS Access + + + + + + + + + + + + Personal Information Management: + + Mail + Address Book + Personal Organizer + News Reader + Pop-up Notes + RSS Reader + + + + + + &kmail; + &kaddressbook; + &korganizer; + &knode; + &knotes; + &akregator; + + + + + MS Outlook + + The Personal Information Manager is &kontact;; all other &kde; PIM applications integrate into it. + + + + + Internet + Web Browser + &konqueror; + MS Internet Explorer + Safari + Integrated file manager, web browser, FTP manager, and univerval viewing application. + + + + + + Instant Messaging + &kopete; + + AIM + MSN + ICQ + Jabber + Novell GroupWise + Yahoo + IRC + SMS + + + + MSN Messenger + Comprehensive multi-network compatible instant messaging software + + + + Chat (IRC) + &ksirc; + mIRC + + + + Multimedia + Music/Audio + &juk; + Windows Media Player + + + + &CD;/DVD Burner + K3b + Nero + + + + Video Player + &noatun; + Windows Media Player + + + + Audio &CD; Ripper + KAudioCreator + + + + Sound Controls + &kmix; + + + + System + System Info Center + &kinfocenter; + + + + Terminal + &konsole; + CMD + + + + User Manager + &kuser; + User Manager + + + + Package Manager + &kpackage; + Add/Remove Programs + + + + Utilities + Archiver + &ark; + WinZip + + + + Password Manager + KWallet + + + + Text Editor + &kate; + Notepad + + + + + + +
+ + +Related Information +Many more &kde; applications are available from the &kde; extragear (see for more information) or from http://kde-apps.org. +Reference: http://kudos.berlios.de/kf/kf1.html#pkgtablestock + + + \ No newline at end of file diff --git a/doc/userguide/migrator-dictionary.docbook b/doc/userguide/migrator-dictionary.docbook new file mode 100644 index 000000000..4bd2efa5d --- /dev/null +++ b/doc/userguide/migrator-dictionary.docbook @@ -0,0 +1,38 @@ + + + + + + +Dictionary for Migrators + +Tables of terminology differences + + + + diff --git a/doc/userguide/net-connection-setup.docbook b/doc/userguide/net-connection-setup.docbook new file mode 100644 index 000000000..cd44fda34 --- /dev/null +++ b/doc/userguide/net-connection-setup.docbook @@ -0,0 +1,238 @@ + + + + + +&Lauri.Watts; + + + + + +Setting up an Internet Connection + + + +&kde; offers a complete Internet experience, with all the +programs you'll need to make the most of the Web, email, Usenet and +many other Internet technologies. But before you can enjoy &kde;'s +advanced features, you'll need to get online. Here's how: + +If you're using dialup (that is, connecting to +the Internet with a modem connected to a telephone line), you'll want +to set up the &kde; dialing program, &kppp;. If that sounds +complicated, don't worry: &kppp; has an advanced configuration wizard, +which will usually take the pain out of setting up your dialup +connection. Take a look at the next two sections for more +details. + +If you're using a broadband connection, or connecting via a +local network, things are easier (from the point of view of +&kde;). Once you've set up the connection with the tools provided by +your &Linux; or &UNIX; distribution, &kde; will use the connection +automatically. + + +Getting online the easy way + + +A few things you should have ready before you start + +If you have a fairly modern &Linux; distribution, you might find the rest +of this document superfluous. &kppp; comes with a clever little wizard that in +many cases can have you up and running with an internet connection in just a few +minutes. + +Whether using the wizard or not, you should know the following information +before you begin: + + +Your ISP modem pool phone +number. +Your username and password for your +ISP. +Your ISP's DNS servers +(one is sufficient, but two is better). + + +Other optional information you should find out to fully access your +ISP's services are: + + +The incoming mail server address (often pop.yourisp.com or mail.yourisp.com).Also find out if +your ISP uses the POP3 protocol or IMAP. +The outgoing (SMTP) mail server address (it +could be the same as the incoming mail server, or it is often called something +like smtp.yourisp.com). +The Usenet News (NNTP) server address (possibly +news.yourisp.com or nntp.yourisp.com). +Any proxy servers your ISP has set +up. + + +All this information is probably available on any paperwork you received +from your ISP when you signed up with them, or you can find +it out from your ISP's support telephone line. + +Armed with the above, and a fairly recent default installation +of &Linux;, you may well find that setting up an internet connection +is as simple as running the &kppp; wizard. + + + + + + + +The &kppp; wizard + + +Starting the Wizard. + +You can start the wizard from &kppp;'s initial screen. Start &kppp; from +your K menu, where you will find its entry in the +Internet as &kppp; (Internet Dial-Up +Tool. + +The following dialog will appear: + + +The &kppp; dialer startup dialog + + + + +The &kppp; dialer startup dialog + +The &kppp; dialer startup dialog + + + +It will probably not have any entries to begin with, and that's +what we're about to do now. + +Click the Configure... button to begin setting up a new +Internet connection. + +The wizard will offer you three choices, Wizard, +Dialog Setup and Cancel + + +The wizard asks you what you want to do... + + + + +The wizard asks you what you want to +do... +The wizard asks you what you want to do + + + + + +Cancel +Choose this if you really don't want to be setting up a new +account right now. The message box will go away, and you will be left with the +dialer window as before. + + + +Wizard +If you have a fairly standard modem, and use one of the larger +ISP's for your country, the wizard will probably be able to set you up +immediately with a working Internet Connection. Try this first, before you try +to set up the connection manually. + + + +Dialog Setup +If you don't succeed with the Wizard, or you just want to do +things yourself, choose this. The wizard currently is only useful for a small +subset of countries and Internet Providers. + + + + +For the purposes of this chapter, we'll assume you are choosing +Wizard, and the dialog based setup will be +described in a later chapter. + + + + +The Rest of the Wizard + +The first window you see contains just introductory text, explaining the +things you read about in the first section of this chapter. Click +Next to move on. + +The second window asks you to choose the country you live in. Not all +countries are represented here, and if the country you live in is not listed, +you will have to click Cancel, in which case the Dialog-based setup will start for you to continue +with. + +On the next window, you will be given a choice of Internet +Providers that &kppp; knows about, based on your choice of location in +the previous window. Again, if your ISP is not +listed here, you will have to click Cancel and +do your setup in the Dialog-based setup + +You will now be asked to enter your username and password for your +internet connection. Please note, that for some ISPs this +differs from your mail account user name and password, so make sure you use the +right one. Choose Next to continue. + +On the next window, you have a chance to enter any special dial prefixes +you might have - for example, if you must dial 0 for an outside +line, or if you have a prefix you can dial to turn off call waiting. Choose +Next to continue. + +And that's all! If you want to revisit any of your choices, you can use +the Back and Next buttons to move +back and forth through the dialogs. When you're done with your settings, click the +Finish button, and you're all done. + +If you need more details, you can read the full &kppp; +manual in the &kde; Help Center, or by typing +help:/kppp in the Location +bar in &konqueror;. + + + + + + + + + + + + + + + diff --git a/doc/userguide/networking-with-windows.docbook b/doc/userguide/networking-with-windows.docbook new file mode 100644 index 000000000..ba8ef0596 --- /dev/null +++ b/doc/userguide/networking-with-windows.docbook @@ -0,0 +1,128 @@ + + + + +Gardner +Bell + + + + + +Networking With Windows + + This section is borrowed and modified from Alexander Neundorf's +README file on LISa. + +&kde; features two powerful servers called the Lan Information +Server (LISa) and Restricted Lan +Information Server (resLISa) which are used +to identify CIFS and other servers on your local network providing a +function similar to Network Neighbourhood in +&Microsoft; &Windows;. + + +How It Works + +&lisa; only depends on the TCP/IP stack so samba configuration is not +required to make it work but the samba package is a dependency. To find +hosts on your local network you set a range of IP-Addresses in your +configuration file that &lisa; will check. When you start the &lisa; daemon +it will send a ICMP, +echo request message to all the IP addresses given in the configuration file +and await a response. + +The &lisa; daemon requires root privileges to open the socket, +but once the socket has been established root privileges are immediately +dropped. + +You can also execute &lisa; using nmblookup +.If you do not have the +nmblookup program it can be found at http://www.samba.org or through packages +provided by your distribution. The samba command +nmblookup will send a broadcast +message to the attached network and any host that is running the +smb-services will send a reply stating that it is accepting +connections. + + + +<application>resLISa</application> + +If your company network has very strict guidelines governing what +ports can and cannot be opened you will have to use &reslisa; to communicate +with other hosts on your network. Because &reslisa; cannot ping entire +networks or address ranges you will have to add each host by name to your +confiuration file. Currently you are able to add up to 64 hosts, and these +addresses are pingable. + +&reslisa; will only provide the information over a &UNIX; domain +socket, &ie; not over the network. The name of the socket is +/tmp/resLISa-YourLoginName, +so &reslisa; can be safely run on the same machine by more than one +user. + + + +Configuration + +At startup &lisa; first parses the configuration file in the users +home directory under $HOME/.lisarc. If +this file does not exist &lisa; will then look for a system wide +confiuration located at /etc/lisarc. Now for a sample +example configuration file: + + +PingAddresses = 192.168.100.0/255.255.255.0;192.168.100.10-192.168.199.19;192.168.200.1; +PingNames = my_host1;my_host2 #Hosts by name (required for resLISa) +AllowedAddresses = 192.168.0.0/255.255.0.0 +BroadcastNetwork = 192.168.100.0/255.255.255.0 +SearchUsingNmblookup = 1 #also try nmblookup +FirstWait = 30 #30 one-hundredth's of a second +SecondWait = -1 #Only try once +#SecondWait = 60 #Try twice and wait 0.6 seconds +UpdatePeriod = 300 #Update every 300 sec's +DeliverUnnamedHosts = 0 #Don't publish unnamed hosts +MaxPingsAtOnce = 256 #Send up to 256 ICMP echo requests at once + + +&lisa; can also be configured graphically in the +&kcontrolcenter;Internet +& NetworkLocal Network Browsing + item in the &kmenu;. However, to use this option &lisa; must +be started with the command line switch. + + + + + +Related Information +For a full list of command line switches and further +examples see the entire &lisa; manual by entering +help:/lisa in &konqueror;. + + + + + + + + diff --git a/doc/userguide/noatun-icon.png b/doc/userguide/noatun-icon.png new file mode 100644 index 000000000..c440d0924 Binary files /dev/null and b/doc/userguide/noatun-icon.png differ diff --git a/doc/userguide/noatun.png b/doc/userguide/noatun.png new file mode 100644 index 000000000..2f807e715 Binary files /dev/null and b/doc/userguide/noatun.png differ diff --git a/doc/userguide/oggfolder.png b/doc/userguide/oggfolder.png new file mode 100644 index 000000000..ac1527c32 Binary files /dev/null and b/doc/userguide/oggfolder.png differ diff --git a/doc/userguide/open-file-dialog.png b/doc/userguide/open-file-dialog.png new file mode 100644 index 000000000..38378aa0c Binary files /dev/null and b/doc/userguide/open-file-dialog.png differ diff --git a/doc/userguide/panel-and-desktop.docbook b/doc/userguide/panel-and-desktop.docbook new file mode 100644 index 000000000..1e92d3a82 --- /dev/null +++ b/doc/userguide/panel-and-desktop.docbook @@ -0,0 +1,325 @@ + + + + + +&Philip.Rodrigues; + + + + + +The Panel and the Desktop + + +&kicker;, the &kde; Panel + +Panel +&kicker; + +&kicker; is the application launcher panel of the K Desktop +Environment. By default, it appears along the bottom of the screen, +and takes up the whole of the width of the screen, but this is +configurable. &kicker; is something of a one-stop shop for (almost!) +everything that you might want quick access to. Besides the &kicon; +Menu, where you can start applications, &kicker; is also capable of +running docked applets like the pager, the taskbar or the clock, and +extensions, such as child panels. With all these options, you will +probably want to configure &kicker; so that it works best for you. The +next section describes some common ways to customize the panel. + + + + + +Configuring &kicker; + + + +Customizing the icons on the panel + +When you first start &kde;, kicker displays some icons next to +the K menu. These can be used to start the +applications that they represent. To see which application is launched + by each icon, hold the mouse cursor over the icon until a tooltip (a +small popup label) appears telling you the name of the application. + +These default icons might not represent the applications you use +most often, so you can remove the ones you do not want and add icons +for other applications that you use. To remove an icon, &RMB;-click on +the icon, and select Remove application +name Button in the popup menu that +appears. To add a new icon, &RMB;-click on an empty space on the +panel, and follow the menu entry Add Application to Panel +. This leads you to a copy of the +K menu, where you can find all of the &kde; +applications. For example, to add an icon for the &juk; music player, +follow through the menus to Add Application +to PanelMultimedia&juk; (Music +Player). The icon will appear on the +panel in the space that you right-clicked on. + + + + + +Adding extras and applets + +Applets + +&kicker; can add many types of items as well as application +launch icons. You can find these items using the same menu as before, +but this time selecting +Add Applet to Panel... +or +Add New Panel. +The items in the Add Applet window are small +programs that can reside on the panel. An example of an applet is the +Desktop Preview & PagerPager, which shows a small image of each of your virtual +desktops. (For more information about virtual desktops, see ). You can switch to a different +virtual desktop by clicking on its image in the desktop pager. + +You can find information about the other applets available for +&kicker; in the &kicker; manual. Just enter +help:/kicker in the +Location bar in &konqueror;. + + + + + + + +Simon +Vermeersch + +titeuf@ph34rus.org + + + + +The System Tray + + +The system tray is where programs that are run, but not directly needed are +kept. Some programs (like music players) are shown there, because you +probably want to keep them open, but so that it does not take too much space on +your screen, it will put an icon in the system tray. + +When you right click on such an icon, a +popup menu will appear where you can see some options of the program (like +play, pause, stop, ... in a music player). +When you left click on it, the main window +of the program will appear. If you hover your mouse above the icon, a tool +tip will appear with some information (in the music player case information +like the current song). Programs that normally support system tray icons are +music players, IRC clients, organizers, ... + +In most of these programs you can configure if you want an icon to be +shown or not. For other tricks and tips with the system tray see the section on . + + + + +Removing Panel Items + + + + +You can remove applets and other special items from the panel +using the arrow on its handle on the applet's left. Right click on the +arrow, and choose Remove applet +name. + + + + + +The Taskbar + +The taskbar is an item on the panel which displays an entry for +each window that you have opened. You can use the taskbar to switch +between windows by clicking on the entry of the window you want to +activate. The taskbar has entries for windows on each virtual desktop, +including windows which have been minimized. + + + + + + +&Philip.Rodrigues; + + + + +Using the Clipboard + +Clipboard + +Very often, it's useful to move some text, or an object in a +program, from one place to another. It's also very common to need to +duplicate some text, for example, if you're typing the same thing +several times. The system used for doing this is known as the +clipboard. There are two slightly different ways to use this system, +known technically as the selection and the +clipboard. We'll look at them separately: + + + + + +The Selection +Selection + +This method uses the mouse to copy text from one place to +another. The method is: + + +Select the text you want to copy. + + +Click the &MMB; at the place you want the text to be +copied to. This can be in the same program as you copied the text +from, or in another program entirely. + + +If you have three buttons on your mouse, this is easy, but if not, all +is not lost! If you have only two buttons, try clicking them both at +the same time instead of the &MMB;. + + + + + +The Clipboard +Cut +Paste +With this method, you can copy text, or cut it +(that is, remove it from one place and move it to another). You can +use either the mouse and the menu entries, or the keyboard with this +method. I'll list both ways, with the menu entry to use, followed by +the keyboard shortcut which will do the same thing, like this: + +&Ctrl;X + +EditCut + + + +Moving (<quote>Cutting</quote>) Text +Select the text you want to cut. + +From the menu, select +&Ctrl;X + +EditCut +, and the text will be removed from its current location. + +Position the text cursor at the point you want to +insert the text. This can be in the same application you got the text +from, or another application entirely. Select +&Ctrl;V + +EditPaste +, and the text will appear at the point where you placed +the cursor. + + + + + +Copying text from one place to another is very similar: + +Copying Text +Select the text you want to copy. + +From the menu, select +&Ctrl;C + +EditCopy +, and the text will be copied in the clipboard. + +Position the text cursor at the point you want to +insert the text. This can be in the same application you got the text +from, or another application entirely. Select +&Ctrl;V + +EditPaste + + + + + + + + +More Advanced Clipboard Use +&klipper; +ClipboardHistory + +The instructions above describe the default clipboard +behavior. The &klipper; application, which you can add as an applet in +the panel (see for instructions +on how to do this), provides some useful clipboard-related features, +like a clipboard history, and the ability to change the behavior of +the clipboard and selection. Take a look at the &klipper; Handbook for +more information. + + + +Related Information + +You can find more information about &kicker;, the +&kde; Panel, in &khelpcenter; or by entering +help:/kicker in &konqueror;'s +Location bar. + + +The &klipper; +Handbook has information about the advanced clipboard management +features in &kde;. You can read it in &khelpcenter; or by entering +help:/klipper in &konqueror;'s +Location bar. + + + + + + + + + + +Related Information + +Related Information +Though some information has been presented here, there is a lot more information on &kicker; tips, options, tricks and hacks, in the &kicker; handbook. You can access it via the &khelpcenter; or by simply entering help:/kicker in the &konqueror; Location toolbar. + + + + + + + + diff --git a/doc/userguide/pdf-files.docbook b/doc/userguide/pdf-files.docbook new file mode 100644 index 000000000..0dd83c2e3 --- /dev/null +++ b/doc/userguide/pdf-files.docbook @@ -0,0 +1,40 @@ + + + + + + +PDF Files + +How to print to a pdf file + +Viewing pdf files + + + + diff --git a/doc/userguide/playing-audiocds.docbook b/doc/userguide/playing-audiocds.docbook new file mode 100644 index 000000000..3f96a6056 --- /dev/null +++ b/doc/userguide/playing-audiocds.docbook @@ -0,0 +1,142 @@ + + + + +Deepak +Sarda + +antrix@gmail.com + + + +Audio CD Ripping in &kde; + +The conventional way of ripping Audio CDs to MP3 or Ogg files is to +use a standalone program such as iTunes, Winamp or &kde;'s own +KAudioCreator. But if we stick to conventions, +where's the fun?! So in this article, I am going to show you how to feel +elite by ripping your CDs in the, umm.. elite way. ;-) + + +Ingredients + +What do we need to be cool? Vanilla &kde;, without any extra +ingredients, will be able to rip your CDs. But to encode them, you'll need +to install the relevant codecs. At the moment, Ogg Vorbis, MP3 and FLAC formats +are supported. To enable encoding to these formats, you'll have to install +libogg, lame and flac respectively. How exactly you install these depends on +your distribution: take a look at their documentation to find out how. + +Once you have your favourite codec(s) installed, open &kcontrolcenter; and navigate your way to Sound & +MultimediaAudio CDs +and configure the settings on the various tabs to your liking. You can leave +everything in the default state if you so wish, but it's helpful to take a +look so you at least know what's on offer. Again, take a look at +Sound & MultimediaCDDB +Retrieval and change anything that's not to your +liking. CDDB, in case you didn't know, stands for CD DataBase (or Compact +Disc DataBase in it's more free flowing form). This functionality enables +&kde; to retrieve the Artist/Album/Track information about your CDs from the +Internet. This metadata is also used to write tags to the MP3 or Ogg files +that you'll be encoding your CDs to anytime now. + + + + + + + + + + + +Recipe + +Without further delay, let's get down to the business of being cool. +First, pop in the CD you want to rip (obviously!). Next, fire up a +&konqueror; window and open the Services tab on the Navigation panel. The +Navigation panel sits on the left side of the window, as shown in the +screenshot below. If it's not visible, you can produce it out of thin air by +pressing the magic F9 key. + + + + + + + + + +Now click on Audio CD Browser and in a few seconds, you'll see a lot +of folders which you can start browsing. If it's taking some time to show +anything, it's because it's trying to fetch information about the CD from +the CDDB database you configured earlier. + +In the screenshot below, you can see the contents of the Ogg Vorbis +folder. It shows all the songs in the Ogg format; it even shows their file +size! But, you and I both know that audio CDs don't contain Ogg tracks. So +what exactly is happening here? + + + + + + + + + +All the folders you see under Audio CD Browser are virtual folders. +They show contents of the CD through different filters, so to speak. When +you open the Ogg Vorbis folder, you are actually seeing the contents of the +CD as if it were stored in the Ogg format. You can go through the other +folders and you'll find MP3, flac and wav representations of the CD's +contents. You can even see the approximate file sizes when encoded in the +various formats. + + +So how do we rip and encode the CD? I think you can guess the answer +by now. Just decide which format you wish to rip to, open that folder, and +copy and paste those files in your target folder. That's it! &kde; will start +ripping and encoding the files on the fly! If you copy any of the files in +the Full CD folder, you'll be ripping the entire CD as +one continuous stream. + + + + + + + + + + + +Related Information +The amaroK website at +http://amarok.sf.net has the +latest news and information about amaroK. + + + + + + + + + diff --git a/doc/userguide/playing-movies.docbook b/doc/userguide/playing-movies.docbook new file mode 100644 index 000000000..89e986cbb --- /dev/null +++ b/doc/userguide/playing-movies.docbook @@ -0,0 +1,48 @@ + + + + + + +Playing Movies + +Intro to xine plugin to aRts + +Alternatives (kaffeine, kmplayer) + + + + + + + + diff --git a/doc/userguide/playing-music.docbook b/doc/userguide/playing-music.docbook new file mode 100644 index 000000000..22c129f1e --- /dev/null +++ b/doc/userguide/playing-music.docbook @@ -0,0 +1,150 @@ + + + + + + +&Lauri.Watts; + + + +Playing Music +Music +Sound +Audio +&arts; + +Intro to &arts; + +Performance tuning, sharing devices + + +Music Players + +There are several &kde; music players with somewhat overlapping +feature sets, however, each is quite different in style. + + + + + + + + +&noatun; +&noatun; + + +Noatun is the default &kde; music player. It features a highly +configurable interface, including several styles of playlist manager, and +many plugins to provide different &GUI;s, visualizations, and other +features. +&noatun; is part of the kdemultimedia package. + + + + + + + + + + + + + + + +&juk; +&juk; + +&juk; is a media manager, playlist manager, and metadata tagger. It is a +highly efficient way to manage all your music files, make and maintain +playlists, and maintain the metadata tags in your music. +It is equally useful as your primary music player, or managing +playlists and files for use in another application. +&juk; is part of the kdemultimedia package. + + + + + + + + + + + + + + + +&kaboodle; +&kaboodle; + +&kaboodle; is a one shot player. That means, it will run, play a file, +and stop. &kaboodle; is useful for instance if you want to quickly listen +to a single file without interupting your current playlist from another +media player. +&kaboodle; is part of the kdemultimedia package. + + + + + + + + + + + + + + + +amaroK + +amaroK is a popular third party application. You should be able to +find packages from your normal distribution source. + + + + + + + + + + +Most of the &kde; based movie players such as +Kaffeine and kmplayer +also make useful music players. + + + + + + + + + diff --git a/doc/userguide/printer-setup.docbook b/doc/userguide/printer-setup.docbook new file mode 100644 index 000000000..658be16ac --- /dev/null +++ b/doc/userguide/printer-setup.docbook @@ -0,0 +1,47 @@ + + + + + + +Setting Up a Printer + +Assume everything is pre-configured, how to set up a printer, refer to +big manual if there is trouble + + + + + + + + diff --git a/doc/userguide/printing-from-apps.docbook b/doc/userguide/printing-from-apps.docbook new file mode 100644 index 000000000..975149cdb --- /dev/null +++ b/doc/userguide/printing-from-apps.docbook @@ -0,0 +1,40 @@ + + + + + + +Printing From Applications + +Printing from &kde; apps + +Printing from non-kde apps + + + + diff --git a/doc/userguide/programs-and-documents.docbook b/doc/userguide/programs-and-documents.docbook new file mode 100644 index 000000000..c5eef682d --- /dev/null +++ b/doc/userguide/programs-and-documents.docbook @@ -0,0 +1,565 @@ + + +Programs and Documents + + + + + +Robert +Stoffers + + + +Launching Programs + +&kde; offers a varying number of ways to launch programs. You may: + + + Simply select the relevant item in the &kmenu;. + + + Run the program from &konsole;, or by clicking the &kmenu; and choosing Run Command... (while you still might prefer the quick keyboard shortcut, which is simply &Alt;F2). + + + Create a shortcut on the desktop or use &kicker;'s quick launcher. + + + +The &kmenu; functions much like the Start menu of &Windows;, however +it breaks programs up by what they do. Programs on the &kmenu; are broken +into category menus, such as Multimedia and +Office. Under these category menus there are +subcategory menus, such as Sound, +Video and Graphics. Under +the subcategory menus lie program launchers, which, when clicked on, launch +the associated application. + +Depending on the program, there may not be a launcher in the &kmenu;. +To search your hard drive for more applications, click the &kmenu;, choose +Run Command and type +kappfinder. In +&kappfinder;, click Scan, and the hard drive will be +searched for programs. Click the checkbox next to each program to be added +to the &kmenu;, and click Apply and +Close. The &kmenu; now will have new program +launchers under the relevant category menus. + +Launchers to programs may also be placed on the desktop. To create a +new launcher, right click on the desktop, and +choose Create +NewLink to +Application. On the &kdesktop; properties dialog +box, type in the name of the program on the General +tab. You may also wish to choose a custom icon by clicking on the gear icon. +Click the Application tab and type a short sentence +about the program in the Description textbox. In the +Command textbox, type the name of the program (case +sensitive), and any command line options you wish to use. Choose +OK, and your new program launcher will be created on +your desktop. Simply click on the new launcher on the desktop and the + associated program will run. + +To launch a program using &konsole;, click the &kmenu; and choose +SystemTerminals +Konsole. Once &konsole; +appears on the screen, simply type the name of the program you wish to +launch (remembering that bash, the command language interpreter that &konsole; uses by default, is case-sensitive) and press +Enter. If you are unsure about the name of a program, type +the first few letters then press the key on your keyboard. By pressing + , bash (through &konsole;) will try to guess the name of the program you wish to +launch. If it finds more then one matching program, a list of + matching programs will be printed on the screen. Type the name of the + program from the list and press Enter to launch. + +Whichever way you choose, launching a program is a simple affair with +&kde;. From the &kmenu;, to &konsole;, all your programs are just a few +clicks or key-presses away. + + + +Related Information +Check the &kicker; handbook for more information on enabling or disabling the &kmenu;, adding applications to the quick launch, or on organizing the categorization of the applications in the &kmenu;. You can view the &kicker; handbook either via the &khelpcenter; or by using &konqueror;'s KIOslave by typing help:/kicker in the Location toolbar. + + + + + + + +&programs-controlling; + + + + + + +Christian +Weickhmann + +christian.weickhmann@gmx.de + + + + +Opening and Saving Files + + + + +&kde; provides a unified way to open or save files via the file +dialog. In almost every &kde; program you will find a +FileOpen + and File +Save (and/or Save +As...) entry. + + +The File Dialog + + + + + + + + + + + + + + + + + + + + +This dialog consists of between three and five areas. The +top area is where you find the navigation and configuration functions. The +main area (in the middle) is where all your files are being displayed as +icons. This is called an icon view. The bottom area is where you can edit +filename or filter expressions and say Save or +Open. + +In addition to that you can add two even more sophisticated areas: +the Quick Access Navigation Panel and +the Preview Panel. + + + + + +Next to the three navigation buttons (one directory +up, back and +forward) and the new folder button +there is the bookmarks menu. Here you can mark any folder +you visit often to find it quickly. The wrench icon holds +the different functions to sort your files by name, date or size and to +enable the two extra panels mentioned above. Next to it you can type the +directory and choose (on the very right side) the encoding. + + + + + +You'll find the icon view in the middle of the dialog. You will find +most of the navigation functions in the context menu by clicking on the +items or the background with the right mouse +button. + + + + + + +The bottom of the dialog consists of the address field holding the +file name you chose or typed in and the maybe most powerful tool: The +filter. Here you can make the icon view display only items that match the +criteria you define. Try filtering files whose names contain +air by typing *air* into the filter +field. + + + + + + + +The Quick Access Panel (activate it by typing the +F9 key on your keyboard or through the wrench icon on top +of the dialog) provides configurable shortcuts to frequently used +locations on your hard drive or even on the Internet. There are several +preconfigured locations such as your home directory. Try right clicking on +any item to configure it or to empty space to add a new entry. You will be +shown a context menu. Here you can choose the icon size and to add, modify +or rename any entry. Choose Add Entry and you +will see a window containing anything you need: Type your description, enter +the location (or choose it via the dialog opening by clicking on the +folder symbol), choose a symbol from a vast variety in the symbol dialog +opening when you click on the predefined icon (usually a simple folder +symbol). + + + + + + +The Preview area (activate it by typing the F11 +key on your keyboard or via the wrench icon on top of the dialog) +makes it easy to preview almost any file on your filesystem. Images +will be displayed as thumbnails. Usually also sound files (such as +MP3, Ogg or Wave-Files), text files (among them raw text, PDF and +&HTML;) and even video files (MPG, AVI and so on) will be +previewed. + +Note that large files might take a long time to be previewed +(⪚ scaled down if they are large images). You can disable automatic +previews by unselecting Automatic Preview below the +preview. You can still preview individual files: just click Preview. You can also disable previews for files above a certain +size. Go to &kcontrolcenter;, choose KDE +componentsFile manager, go to +the Preview and Metafiles tab and change the +Maximum Filesize value. + + + + + + + + + + + + + + + + + +&Philip.Rodrigues; + + + + +Configuring Programs + + +Application Configuration + +Configuration +Customization + +&kde; applications are intended to be as useful and usable as +possible out of the box, but they also offer a wide +range of options which you can change to make &kde; work for you. As +well as the settings which affect the whole of &kde; (see ), each application has a set of +configuration options, which you can access using the menu option +SettingsConfigure +Application +. This is the same for all &kde; applications, which +makes it easy to find the configuration dialog for an +application. + + + +On the left of the configuration dialog is a list of +sections. Clicking on one of these sections displays the configuration +page for that section on the right-hand side of the dialog. You can +change these options to fit your preferences. + +When you have made the changes you want, you can click on +OK to save your changes and close the +configuration dialog. If you want to see the effect of your changes, +but not close the configuration dialog, click on the +Apply button. This is useful if you aren't sure +about the change you've made, and might want to change back, because +the dialog is still open, ready for you to do so. + +If you decide that you don't want to keep the changes you've +made, just click Cancel to close the dialog +without saving your changes. + + + + +Configuring Keyboard Shortcuts + +Shortcuts +Keybindings + +Most &kde; applications offer keyboard shortcuts for the main +actions in the application. If you find that you don't like the +default keyboard shortcuts, or that they conflict with the shortcuts +of another application (maybe one that's not part of &kde;), you can +change them with the +SettingsConfigure +Shortcuts... + menu entry. This brings up the +Configure Shortcuts dialog for the +application. As an example of how to use this dialog, let's add a +shortcut for the Send Link Address... action to +&konqueror;, so that we can email the locations of interesting pages +to friends just by hitting a key (or two): + +Open the Configure Shortcuts +dialog in &konqueror;, as described above. + +Click on the Send Link Address... item +in the main listbox (it's near the bottom, in the +Konqueror section). + +In the Shortcut for Selected +Action panel, select Custom, since we +are going to give this action a keyboard shortcut that we have chosen. + +A small shortcut entry dialog pops up. Just hit +&Ctrl;E + (or whatever you want to change the shortcut to), and the +dialog disappears. The key icon in the +Configure Shortcuts dialog now shows the new +shortcut. + +If you made a mistake, or change your mind about what +to use as the shortcut, just click on the key icon showing the current +shortcut. The shortcut entry dialog reappears, and you can press the +key combination for the shortcut you want. + + + + + + + + +Configuring Notifications + +Notifications +Sounds + +Something about +SettingsConfigure Notifications... +. + + + + + + +Adriaan +de Groot + + +Configuring Toolbars + +Nearly every &kde; application has one or more toolbars at the top of +the application window, underneath the menu. The toolbar contains icons +(toolbar buttons) that represent commonly used actions and configuration +settings. The &kmail; window, for instance, has a toolbar that contains +buttons for New Message, Check Mail +and several others. Each of these actions is something you do often, so +that's why they have toolbar buttons as well as menu entries (New +Message is under +MessageNew +Message, Check Mail is +FileCheck +Mail). + +Not everybody agrees on what actions are commonly used, though, (I +never use the New Message toolbar button or the menu +item, I use the keyboard shortcut &Ctrl;N). To ensure that your +screen isn't cluttered with things you don't need, each toolbar can be +customized. Additionally, you can usually customize which toolbars are +displayed and how, as well. + + +Customizing Toolbar Displays + +The easiest thing to customize with the toolbars of any given +application is whether they are displayed at all. Most applications have a +SettingsToolbars + menu where you can select which toolbars are displayed and +which are not. &konqueror; has four toolbars, Main, +Extra, Location and +Bookmark. It can be convenient to turn off the +Bookmark toolbar to save +screen space. To do so, click on the Settings menu, +choose Toolbars, and then uncheck the +Bookmark Toolbar entry (do this just by clicking +on the menu item). + +If there is no Settings menu, you can also +right click on the toolbar itself, and choose the +Toolbars sub-menu from the resulting context +menu. + +The same Toolbar context menu, accessed by +right clicking on the toolbar, allows you to +customize other properties of the toolbar: + + + +Its orientation, so that instead of appearing at the top of the +window under the menu bar you can place it on the left, right or bottom of +the window. + + +Its orientation, so that the toolbar floats as a +separate window which you can move independently. + + +Its orientation, so that the toolbar is squashed into a little flat +grip that you can re-open by double-clicking on it (this is subtly +different from making the toolbar vanish completely, since it it easier to +cause it to re-appear). + + +The appearance of text alongside, underneath, or instead of the icons +on the toolbar. + + +The size of the icons (if they are not supplanted by +text). + + + + + +Customizing the Icons on the Toolbar + +The toolbar is intended for actions that you perform often, so what do +you do if there is some useless icon there, like Cut? Or +what if you really want a cut button on the toolbar, but +the application doesn't give you one? This is where the customize toolbars +dialog comes in — it give you complete control over the actions that +are available on each toolbar. + +Choose SettingsConfigure +Toolbars from the application's menu, or +Configure Toolbars from the context menu of the +toolbar itself. This displays the configure toolbars dialog, which consists +of a combobox with which you can select +which toolbar to customize, and two lists of items +— one of the available actions, and one of the actions that are +already in use on the toolbar. + +Often there are many many more actions available ( activate +tab #12, for instance) than you would ever want on the toolbar, or +even that you know exist in the application. The customize toolbar dialog +can be a learning experience. You can drag actions from one list box to the +other, rearrange the items on the toolbar , or change the icon for a +selected action. This allows you to drag the actions you don't want off of +the toolbar and into the list of available actions; similarly, the actions +you do want can be dragged into the toolbar. Clicking +OK in the dialog immediately updates the toolbar with +your new preferred actions. + +There are a few special items that can end up in the listbox for the +current toolbar: + + + +separators, which exist in two flavors: + +line separator appears as a line +between two action icons + +separator appears as a larger +space between two action icons + + + + + +<Merge>, which is a special item that +allows plugins and other loadable components of the application to insert +their actions into the toolbar as well. It is generally not a good idea to +remove this, since you cannot get it back. + + +ActionList:, these appear in various flavors +(there is a viewmode_toolbar one in &konqueror;) and again these +represent lists of actions that might be inserted by +plugins. + + + +Whenever you click on an action in the list of current actions, a +description of it is shown in the dialog. This description will warn you if +it is a bad idea to remove the action. + +If you do not like to drag things around, there are four buttons in +the middle of the dialog which allow you to move the selected action from +one list to the other, and to move a selected current action up or down in +the list. There must be a way to restore the default toolbars in an +application, in order to recover from accidentally deleting an important +action like <Merge>, but I don't know what it +is. + + + + + + + + + + + + + diff --git a/doc/userguide/programs-controlling.docbook b/doc/userguide/programs-controlling.docbook new file mode 100644 index 000000000..a1f072e6f --- /dev/null +++ b/doc/userguide/programs-controlling.docbook @@ -0,0 +1,39 @@ + + + + + + +Controlling Programs + +Standard Toolbar layout + +Keybindings + + + diff --git a/doc/userguide/removable-disks.docbook b/doc/userguide/removable-disks.docbook new file mode 100644 index 000000000..7b07941e4 --- /dev/null +++ b/doc/userguide/removable-disks.docbook @@ -0,0 +1,140 @@ + + + + + +Edward +Haven +edward.haven@gmail.com + + + + +Removable Disks + +For &kde; to use any device, removable or not, the device must +first be mounted. When a device is mounted, &kde; gets all the needed +information about the device: how to read it, how to write information to +it, and much more. + +The use of a device is controlled by the operating +system and it is important your operating system has tools for managing +these devices. &kde; can also auto mount devices, working with +HAL (Hardware Abstraction Layer). Your distribution +should have set up HAL automatically; if not, +consult the documentation provided by your distribution. +There are several ways to find the list of media devices: use +whichever one suits you best: + + + +Enter media:/ or +system:/media into the &konqueror; location bar. + + + +Navigate to it by clicking on the Services +tab in &konqueror;'s Navigation Panel, then selecting Storage +Media. + + + +Select GoStorage Media + from the &konqueror; menus. + + + +Click the System desktop icon, then from +the window that appears, click on Storage +Media. + + + + + +The Storage Media location (also known as +the media:/ protocol) will show all devices which are recognized by +&kde;, including the hard drive and &CD; and DVD +drives, as well as USB and Firewire devices, +provided that your distribution is set up correctly to tell &kde; +about them. + + + You can also setup &kde; to display a device icon +on the desktop. To start or configure this feature in the &kcontrolcenter; go +to +DesktopBehavior +and select the Device Icons Tab. The device icon action +can be used to show both mounted and unmounted devices, or to only create an +icon when media is detected and automounted (only if automount is properly +configured), by not checking the unmounted boxes. + + +Automount + +With &kde; 3.5 and newer, devices can be automounted, meaning one only +has to insert the removable disk. &kde; will then open an automount prompt +asking the user What do you want to do? with the media. To +configure the list of options prompted for devices open the &kcontrolcenter; and +navigate to PeripheralsStorage +Media. Here you can add and remove programs from the +list of devices. + +The automount feature will only work if +dbus, hal and +udev are installed and the kernel is properly +configured. To find out if they are running on your system check the +Process Table in &ksysguard; for: +hald, dbus-deamon, and +udevd. &kde; does not provide any of these +components. You must check with you distribution. + + +Related Information +HOWTO: setting up D-BUS and HAL with KDE's media ioslave +edit (A community maintained HOWTO on the &kde; wiki) +The DBus page +HAL - Hardware Abstraction Layer + + + + + +Mounting + +If your system does not automount, &kde; is configured to mount and +unmount devices which the current user has permission to mount. If a device +is mounted as the root partition (&ie; /), and you log in +to &kde; as a user, &kde; can not mount or unmount it without being given a +higher permission. To check a devices mount permission see the +/etc/fstab file. + +To mount and unmount devices manually in &kde; one only has to &RMB; +click the device icon in media:/ or on the desktop and select +Mount or Unmount, for +removable devices one can also unmount with Safely Remove. &kde; still requires the device to be setup in +/etc/fstab. + + + + + + + + diff --git a/doc/userguide/rip.png b/doc/userguide/rip.png new file mode 100644 index 000000000..0a044efb9 Binary files /dev/null and b/doc/userguide/rip.png differ diff --git a/doc/userguide/ripsettings.png b/doc/userguide/ripsettings.png new file mode 100644 index 000000000..21f53fbfd Binary files /dev/null and b/doc/userguide/ripsettings.png differ diff --git a/doc/userguide/screen-captures.docbook b/doc/userguide/screen-captures.docbook new file mode 100644 index 000000000..35d1a726a --- /dev/null +++ b/doc/userguide/screen-captures.docbook @@ -0,0 +1,38 @@ + + + + + + +Screen Captures + +Grabbing screen caps + + + + diff --git a/doc/userguide/services.png b/doc/userguide/services.png new file mode 100644 index 000000000..d281c88b7 Binary files /dev/null and b/doc/userguide/services.png differ diff --git a/doc/userguide/shared-sessions.docbook b/doc/userguide/shared-sessions.docbook new file mode 100644 index 000000000..688a4b93f --- /dev/null +++ b/doc/userguide/shared-sessions.docbook @@ -0,0 +1,46 @@ + + + + + + +Shared Sessions + +Sharing your desktop with krfb and pals + + + + + + + + diff --git a/doc/userguide/splash-screen.png b/doc/userguide/splash-screen.png new file mode 100644 index 000000000..ccc6a29ea Binary files /dev/null and b/doc/userguide/splash-screen.png differ diff --git a/doc/userguide/standard-menu-entries.docbook b/doc/userguide/standard-menu-entries.docbook new file mode 100644 index 000000000..cfa37b453 --- /dev/null +++ b/doc/userguide/standard-menu-entries.docbook @@ -0,0 +1,319 @@ + + + + +&Philip.Rodrigues; + + + + + +The Standard Menu Entries + + + +One of the main ways that you'll control programs in &kde; is +via the program's menus. They provide access to nearly everything +you'll need to do with that program. So that you can more easily +remember where things are in the menus, and to help you learn new +programs more easily, the menus have a standard layout. This means +that once you know how to open a file in one program, you know how to +open a file in any &kde; program. Let's take a look at the standard +menus: + + + + +The <guimenu>File</guimenu> Menu + +&Ctrl;N + +New + +This entry will start a new, blank document that's +appropriate to the program you're using. For example, in &kate; (the +&kde; Advanced Text Editor) this entry creates a new text file. + + + + +&Ctrl;O + +Open... + +The Open... menu entry +displays the &kde; Open File dialog box, where you can +choose a file to open in the program you're using. The Open +File dialog is also standardized, so it's the same for all +&kde; programs. You can find out more about using this dialog +somewhere else in this guide . +You probably noticed that this menu entry had an ellipsis (...) +after the name of the entry. This means that clicking on the entry +will open a dialog box of some kind. If you make any changes in the +dialog box that appears, they won't take effect until you click on the +OK button in the dialog. You can always ignore +any changes you made, and close the dialog, by clicking on the +Cancel button. + + + + +&Ctrl;S + +Save + +This menu entry will save any changes you've made to +the file that you are currently working on. If this is the first time +that you've saved the file, the &kde; Save File dialog +will appear, and ask you for a name and location for the file. + + + + + + +Save As... + +The Save As... menu entry +will save the file you're working on with a different name. The +Save File dialog appears, and you can choose a name and +location as usual. Note that after you save the file with +Save As.., you will be working on the +new file. If you save changes, they will be saved +under the new filename. To make this a bit clearer, let's take an +example: + + +You are working on a file called +hello.txt that contains the text Hello +World! + + +You use the Save As... menu +entry to save the file with the new name +newhello.txt. + + +You add the text Nice to see you! to +the file, and use the Save menu entry to +save these changes. + + + + + +Now, the file newhello.txt contains the text +Hello World! Nice to see you!, while the file +hello.txt contains only the text Hello +World!. + + + + + +&Ctrl;P + +Print... + +This menu entry displays the &kde; +Print dialog, read to print the current +document. Youcan find more information about the options available in +this dialog in . + + + + +&Ctrl;W + +Close + +This menu entry closes the current document. If you +have made any changes since you last saved the document, you will be +asked whether you want to save those changes. You can choose to +Save or Discard those +changes. If you didn't really want to close the file, just click +Cancel. + + + + +&Ctrl;Q + +Quit + +Use this entry to close the program you're using. If +you have unsaved changes in any files, you will be asked whether you +want to +save them. + + + + + + + + +The <guimenu>Edit</guimenu> Menu + + +&Ctrl;Z + +Undo + +Use this entry to remove the effect of the last +action you performed in the application. For example, if you deleted a +line of text, the Undo menu entry will +replace that line. + + + + +&Ctrl;&Shift;Z + +Redo + +Use this menu entry to perform the last action that +you removed with the Undo menu entry. For +example, if, as in the example above, you had replaced a deleted line +of text with Undo, the +Redo entry would redo the action of +deleting the line. + + + + +&Ctrl;X + +Cut + +This menu entry cuts the contents of the current +selection to the clipboard. See +for more information. + + + + + +&Ctrl;C + +Copy + +This menu entry copies the contents of the current +selection to the clipboard. See +for more information. + + + + + +&Ctrl;V + +Paste + +This menu entry inserts the contents of the clipboard +in the current document. The clipboard contents are inserted where the +cursor is currently positioned. + + + + +&Ctrl;A + +Select All + +Use this item to select the whole of the current +document. + + + + +&Ctrl;F + +Find... + +This menu entry displays the Find +Text dialog, which you can use to search for a particular +word or phrase in the current document. + + + + + +F3 + +Find Next + +Use this item to find the next occurrence of the most +recent text you searched for using Find.... + + + + + + + +The <guimenu>Settings</guimenu> Menu + + +Configure Shortcuts... +In the dialog displayed by this menu entry, you can +change the keyboard shortcuts used by the application. See . + + + + + +Configure +Toolbars... + +In the dialog displayed by this menu entry, you can +change which buttons appear on the application's toolbars. See . + + + + + +Configure Notifications... +In the dialog displayed by this menu entry, you can +change the notifications (sounds, error messages, &etc;) used by the +application. See . + + + + + +Configure Application +In the dialog displayed by this menu entry, you can +change settings relating to how the application works in general. + + + + + + + +&help.menu.documentation; + + + + diff --git a/doc/userguide/switching-sessions.docbook b/doc/userguide/switching-sessions.docbook new file mode 100644 index 000000000..d869d0808 --- /dev/null +++ b/doc/userguide/switching-sessions.docbook @@ -0,0 +1,92 @@ + + + + + +Christian +Weickhmann + +christian.weickhmann@gmx.de + + + + +Switching Sessions + +From version 3.3 onwards, &kde; provides a session management +system which allows you to switch between different user account on +one computer. You can stay logged in and ⪚ let your sister, +brother, wife, neigbour or whoever read her or his emails just for a +moment. Before you had to log off (therefore ⪚ close programs or +save documents) and let her or him log in. + +Now it's almost as easy as switching to another virtual desktop. + + +Switching Sessions: How it works + + +The Switch User Menu + +The &kmenu; now bears a new entry. Rather at the bottom of the menu +you will find a Switch User submenu. It contains +the command to lock the current and start a new session which means that +your desktop will start the screensaver and after a few seconds can log in +with KDM as always. The Start New Session entry +skips the activation of your screensaver. + +Once you have running more than one session you can either choose to +press &Ctrl;&Alt;F7 + or F8 and so on (what is usually configured by default) or +— even more comfortable — choose from the list of active +sessions at the bottom of the Switch User +submenu. + + + + +Switch User with the screensaver +If you have activated your screensaver and another user +wants to log in she or he can simply press the Switch +User... button and log into another session. + + + + +Switch Session in &kdm; +If you are in &kdm; and want to switch to another active +session you can press the Menu button and choose +Switch User which is mainly the same as described +above. + + + + + + + + + + + + diff --git a/doc/userguide/the-filemanager.docbook b/doc/userguide/the-filemanager.docbook new file mode 100644 index 000000000..a56628cf8 --- /dev/null +++ b/doc/userguide/the-filemanager.docbook @@ -0,0 +1,291 @@ + + + + + +Christian +Weickhmann + + + + +The File Manager +&konqueror;File +Management +File Management + + + + + +&konqueror; with simple settings + + + +Introduction + +&kde; includes a versatile and powerful file manager called +&konqueror; which allows you to do everything you want with the files +stored on your computer, your network, and even the Internet. There +are too many features of &konqueror; to describe here, so we will just +take an overview. If you want more details about what &konqueror; can +do, take a look at the &konqueror; Handbook&konqueror;Handbook by selecting +HelpKonqueror +Handbook in the &konqueror; menus; or, alternatively, you can use the help KIOslave in &konqueror; by entering help:/konqueror in the Location Toolbar. + + + +Folders + +When you first open &konqueror; in file management mode, you can +see two panes: on the right is the folder view; on the left is the +sidebar. The folder view contains icons for +each item inside the current folder. These items can be +folders or files. Many file types can be previewed +without opening a new application to edit them in.Previews To preview a file, +hold the mouse cursor over the name of the file for about a second: a +popup window will appear, showing the contents of the file and other some +useful information, like file's size and which user owns the file. + +You can open any item by clicking (just once – &kde; +does not use double-clicking in its default settings) on the icon for the +file. Folders will be opened in the same window; files will either be +opened in the appropriate program, or the file manager will ask you +what program to use. For instance, if do not have a word-processor set up to +open &Microsoft; Word documents, the file manager will +ask you what to do. + +You can go back to the last-opened folder by clicking on the +Back button or go up one folder by clicking +the Up button. + + + +The Navigation Panel (aka <quote>The Sidebar</quote>) + +Navigation Panel +Sidebar + + + + + +The &konqueror; sidebar + + +Navigating through the folders by using +the folder view can become impractical. The sidebar provides +shortcuts and special functions that make it easier to +find what you are searching for. + +On the left edge of the sidebar you will find a number of buttons, each + with a different icon: + + + + + +Bookmarks + + +As &konqueror; (the file manager) also serves as a very powerful +web browser, it also has a bookmark functionality. Here you will find the +same structure as in your Bookmarks menu. + + + + +Devices + + +Next the sidebar provides a list of all known devices +on your computer. These devices can be either physical drives — +such as your hard disk, &CD-ROM; drive, or floppy disk drive — +or virtual drives — such as remote shares or hard disk partitions. + + + + +History + + +&konqueror; will remember the web pages you have visited and list them +either by date or alphabetically in a tree structure. You can select the +behavior by right clicking on the History item and +selecting Sort by. Left click on an item (⪚ +www.kde.org) and &konqueror; will show you the documents you have visited. Left +clicking on a document (⪚ index.html) will open +the web site in the folder view. +Right clicking on a history item, like www.kde.orgindex.html +, opens a slightly different popup menu: you will also find the +item New Window, which makes &konqueror; open the +site in a new window. + + + + +Home Directory + + +The Home Directory item is in the sidebar's navigation +panel. You will find your home directory as the first entry. Below you will +find all folders of your home directory. Left clicking on any +folder in this view opens the folder in the folder view. Alternatively, you can also +work with the folders' context menus, create subfolders, and so on. + + + + +Sidebar Media Player + + + + +Try dragging a music file (like MP3, Ogg, or +.wav files) +on the sidebar. The file will immediately be played. + + + + +Newsticker + + +Newsticker will display a customisable list of news sources. Right-click +either on the Configure button or on one of the +newssource buttons (e.g. KDE News, which is usually predefined) to add a new +newsticker source. + + + + +Network + + +Here you can browse the services provided by other computers on +the network. The &lisa;-Daemon has to be started in order to work +correctly. The network browser allows you to see a variety of services +provided by a computer. You can easily browse SMB +shares, &HTTP; sites, or transfer files via the secure FISH +layer. + + + + +Root Directory + + +Everything on a &UNIX;-based system is organized in a file +system tree. This tree must have a root and here it is. The +Root Directory function is like the +Home Directory function. The only difference is +that every folder is being displayed, not only your home +directory. + + + + +Services + + +This is somehow the "rest". Try browsing through the different +items. If an Audio &CD; is in your &CD; or DVD +drive you will be able to find everything on it and even more in the +Audio CD Browser item (you can even compress +audio files and save them on your hard drive with this +function). + + + + + + + +Icons + + +To select only one icon hold down the &Ctrl; key and click on the icon +you want to select. If you want to select more than one icon, hold +down &Ctrl; while you click on each of the items you want to select. +Once one or more icons are selected you can do what you want with +them. If you want to move or copy items, select them and then drag them +(with the left mouse button down) to the desired location. When +you release the mouse button a menu will come up offering you to +MoveMoving +Files, +CopyCopying +Files, or Link the +selected items. You can also Cancel your +action. + + +Many other actions can be applied to the selected items by +right-clicking on one of the selected items, and choosing the action +from the menu which appears. (The exact contents of this menu depend on the +type of files selected, so it is called a context menu). + + + +Links and Shortcuts + + +As already mentioned above you can link files or folders anywhere. It means +that the linked folder will appear and behave just like the original in +another location without consuming additional space on your harddrive. +So if you, for example, have a number of documents, and only a few are used +regularly, you can easily group them in a folder and create links in it. + + + + + +The Trash + +Trash +Recycle Bin + +Before a file is deleted in the &kde; file manager it will be +moved to the Trash folder to give you the +possibility of getting it back if you deleted it by accident. The +trash bin will show all deleted items. You can select the one to be +recovered and move it to its original place as described in . If you right click on the trash bin and select +Empty trash bin the files in it will be +deleted permanently. + + + +Related Information + +As mentioned in the introduction, the &konqueror; +Handbook has much more information about the features available in +&konqueror;. You can read it in &khelpcenter; or by entering +help:/konqueror in &konqueror;'s +Location bar. + + + + + + + + + + + diff --git a/doc/userguide/titlebar-menu.png b/doc/userguide/titlebar-menu.png new file mode 100644 index 000000000..d9d672982 Binary files /dev/null and b/doc/userguide/titlebar-menu.png differ diff --git a/doc/userguide/troubleshooting-network-x.docbook b/doc/userguide/troubleshooting-network-x.docbook new file mode 100644 index 000000000..45c55196c --- /dev/null +++ b/doc/userguide/troubleshooting-network-x.docbook @@ -0,0 +1,41 @@ + + + +&J.Hall; + + +Networking and X + +Misconfigured networking can often be the cause of &kde; applications launching slowly, or in the worst case not launching at all. Your &X-Server; has a very powerful client/server interface and is very network aware. + + + X uses the hostname to create both a unique key for authorization, and to figure out where (via $DISPLAY) to send + the actual windows it's drawing on screen. If your computer doesn't know it's own name, it will spend inordinate amounts of time + trying to look itself up, a fate you can avoid by simply teaching your computer what it's own name is. + + +Check your /etc/hosts file and ensure there is an entry for localhost that looks +something like this at the top of the file (after any comments). + + +127.0.0.1 localhost + + +You also should add your computers fully qualified domain name, short name, and it's usual ip address if it has a static ip. If your ip address is assigned dynamically using DHCP you can simply use the address for the loopback device. + + +127.0.0.1 hal.btl hal (for dhcp) +192.168.0.1 hal.btl hal (static) + + +Make sure that your firewall is not so restrictive that it stops packets to the loopback device. For example in iptables if the default rule on the INPUT chain for this device is set to anything other than >ACCEPT this will cause performance problems in X. To check this, you can type in: + + +%iptables-save | grep + INPUT lo ACCEPT + + + +The rule INPUT lo ACCEPT should always work, unless there are other misconfigured rules (Such as a DROP on the OUTPUT chain) + + diff --git a/doc/userguide/troubleshooting-no-open.docbook b/doc/userguide/troubleshooting-no-open.docbook new file mode 100644 index 000000000..682f4b675 --- /dev/null +++ b/doc/userguide/troubleshooting-no-open.docbook @@ -0,0 +1,49 @@ + + + +&Lauri.Watts; + + +When An Application Will Not Open + +Sometimes when you start an application, it does not open the expected +window. Here are some questions to answer and steps to help you figure out +what is wrong. + + + +Did the application ever start, when launched in the same +manner? +If it did, for instance you have clicked an icon on your +desktop that previously worked, then it is unlikely to be a problem with the +launcher itself. +If, however, you normally start your application from an icon on +&kicker; and this time started it with a desktop icon, then it could simply +be that the launcher itself is wrong. + + + +But I can see the launch notification spinning cursor and taskbar entry. + +Foo + + + + + diff --git a/doc/userguide/under-the-hood.docbook b/doc/userguide/under-the-hood.docbook new file mode 100644 index 000000000..094a01d63 --- /dev/null +++ b/doc/userguide/under-the-hood.docbook @@ -0,0 +1,521 @@ + + + + + + +Tinkering Under the Hood of &kde; + + + + + + +Nicolas +Goutte + +goutte@kde.org + + + +Hand-Editing Configuration Files + + +Introduction +In &kde;, the configuration files are easy to edit with a simple +editor like &kate; as the configuration files are text files. + +An example of a text file: + +[General] +AutoSave=1 +LastFile=/var/tmp/test.txt + +The user-specific configuration files are stored in .kde/share/config (replace +.kde with your $KDEHOME setting) and +the global ones are in the share/config sub-directory of &kde;'s +installation path. (You can find this path by running the command +kde-config --prefix.) Their filenames typically +end in rc (without an initial period), for example kopeterc. + + +Editing configuration files by hand can risk the stability of your +&kde; installation. Applications usually do not check what they read from the +configuration files. This means that they can be disturbed by what they +get as configuration and might even +crash. + + + + +Backups + +So the first rule is to make a backup of your file before modifying +it. The backup is better stored outside any +.kde subdirectory +(or the corresponding $KDEHOME directory). Backups are anyway +a good idea in case of a major failure of &kde; that would +destroy important configuration files (for example your &kmail; settings, +which are in in the file kmailrc). +(Such a major failure should not happen but it still can happen.) + + + +Editing + +So why would you want to touch the configuration files at all? Well, first you need it +when you want to enforce the KIOSK mode. Perhaps a developer has asked you +to add an entry to help him to solve a problem with the application. Perhaps you want to recover from +a problem without having to remove all the .kde directory. Perhaps you want to learn more +about the depths of &kde;. + +Anyway, whatever your reason, you want to modify by hand a +configuration file. + +When planning to edit such a file, make sure that the application +using it is not running. If it is one of the basic configuration files, +consider editing the file while &kde; is not running at all. + +Ready? So make a backup of the file (Did I tell you this already?), +start you favorite editor (let us assume it is &kate;), load the file +(Be careful to load as UTF-8, &kate; displays it as +utf8). + +Now you have a file like: + +[Group] +Key1=Value1 +Key2=Value2 +Key3=Value3 + +You can now modify it (with care!) and then save it (Be sure that it +is as UTF-8 again). + +Now you can test the application and if the application does not run +correctly anymore, close the application and restore the backup of the +configuration file. + + +Related Information + + + has more +information about &kde;'s directory structure, to help you find the +file you need to edit. + + + + + + + + + +Scripting the Desktop + +&kde; provides a powerful interprocess communication system in +&DCOP;, the Desktop COmmunication Protocol. Using &DCOP;, you can +control a wide range of functions in &kde; from the command line or +from a script written in your favorite scripting language. You can +also get information out of &kde; applications: for example, several +&kde; media players provide methods to query the player for +information about the currently-playing track. + +Broadly speaking, each &kde; application provides one or more +&DCOP; interfaces, which in turn provide +methods (or, if you prefer, functions) that another application can +call. So, the first step in using &DCOP; is to find the appropriate +method for the task. The easiest way to do this is using the +kdcop frontend to the available &DCOP; +methods. + +Run kdcop from a &konsole; or the +mini-CLI (the window which pops up on &Alt;F2 ). The +kdcop window shows the applications +currently running which provide &DCOP; interfaces, using a tree +view. + +In general, finding the correct method requires a little bit of +searching through the tree view, but a useful hint is that the +interface marked (default) usually contains the most +frequently-used functions. + + + +To test that the function does what we expect, double-click on +the setColor entry. To set the color +c, click on the color selector button, and choose a +color. Set whether the color should be color A with the +checkbox. Click OK and the background color is +set. + +To access the &DCOP; method from your favorite scripting +language, you can either use &DCOP; bindings, if available in the +kdebindings module, or call the dcop command-line +application. For simple usage, calling the +dcop command-line application is sufficient. To +call a &DCOP; method on the command line, we need to specify the +application and interface owning the method, the method itself, and +the arguments, in a form suitable for the shell. + +We specify the application, interface and method in that order, +followed by the arguments in the same order that they are shown in +kdcop. dcop +has plenty of other options: take a look at the output of +dcop +. + +That's enough theory: time for an example: + + +A Background Color Changing Script with &DCOP; + +With the dcop command-line application and a +little bit of Perl, we're going to make a simple script which slowly +cycles the desktop background through the spectrum. + +Firstly, we look for the appropriate method with +kdcop. For this example, we'll short +circuit the searching, and go straight to it: the method we want is +kdesktopKBackgroundIfacesetColor +. The arguments and return type of the function are shown +in the style of the C++ language. For +setColor, the arguments are a color, +c, which specifies the new background color, and a +boolean (true or false) value, isColorA, which +specifies whether the color is the first or second (this is useful for +setting gradients and so on). + +To use our setColor method on the +command line, we use the following: + + +% dcop kdesktop KBackgroundIface setColor '#ffffff' false + + + +To specify the color, we used the +hexadecimal RGB value, as used in &HTML;. Note that it is enclosed in +single quotes to protect the # from the shell. + +To find the hexadecimal RGB value of a color, open any +color chooser dialog in a &kde; application (for example, in +&kcontrolcenter;, Appearance & ThemesColors +), select the color you want, and use the value given in +the HTML text box. + + +So, that's all we need from &DCOP;; now it's just a case of +writing a script around it. Here's a (very!) rough implementation: + + += $min) and ($colour[$which] <= $max)); + } +} +]]> + + + +Just run the script with no arguments, and it will cycle the +background colour through a slightly muted spectrum until it is +killed. Voilà! + + + +Of course, Perl isn't the only language you can use to write +scripts with &DCOP;—if you prefer shell scripting, that's +available too: + + +Setting a background from the Internet + +The following script gets the main image from the User +Friendly comic strip and sets it as the desktop wallpaper, +using commonly available tools and a little bit of &DCOP;: + + +.*,,"` +TMPFILE=`mktemp /tmp/$0.XXXXXX` || exit 1 +wget -q -O $TMPFILE $COMICURL +dcop kdesktop KBackgroundIface setWallpaper $TMPFILE 1 +]]> + + +The first line after the #!/bin/sh uses wget and some regular +expression magic to extract the image location from the main page's +&HTML; source. The second and third lines download the image, and +finally, dcop sets the downloaded image as +wallpaper. + + + + + + + + + + + +Adding Extra Keybindings to &kde; + +Many modern keyboards contain extra keys that are not by default +assigned to any action. + +Multimedia keys often generate a signal, and can simply +be chosen as a keybinding within an application just like choosing any other +key. Some keys however, are not detected and pressing them in a +Configure Shortcuts has no effect. + +Some IBM laptops, for instance, have extra keys about the left and right +arrows, which look like page left and page +right. + + +Use xev to find the code of the keys. In +this case, they are 233 and 234 + +Choose key symbols. There are quite a range of these that are not +used by default, so many are free. You can find the list in +/usr/X11R6/include/X11/keysymdef.h (or its equivalent +on your system). +Create a file in your home directory called +.Xmodmap, and add to it the following: +keycode 233 = Next_Virtual_Screen +keycode 234 = Prev_Virtual_Screen + +Run the command xmodmap +~/.Xmodmap + + +At this point, you should be able to run xev again +and see that the keys now generate the keysym that you assigned. You can now +simply assign them to any action as normal. + + +Related Information +The xev manpage. You can see this by typing +man:/xev into a &konqueror; window or by typing +man xev into a terminal. + + + + + +Adding Keybindings for New Actions + +Most actions in either the desktop or in applications are readily +available to assign a keybinding to. If the action you want a +shortcut for is something you wrote yourself, or is otherwise not available, +you can still assign a shortcut. + +To bring together the two previous sections, perhaps you want to +assign an otherwise unused key on your keyboard to a script or dcop +command. Our example here will be to assign the two keys we added +in to go to the previous or +next virtual desktop, two functions for which you will need DCOP (as discussed in +). + +This can be achieved easily using the following method: + + + +Open &kcontrol;, and in the Regional & Accessibility +section, select Input Action + + +Choose New Action + + +Name the new action, ⪚ Next Virtual +Screen + + +Select Keyboard shortcut -> Command/URL (simple) +for the Action type: + + +In the Keyboard Shortcut tab, click the button +you wish to use to trigger the command. For this example, you would press +the one with the Next Page picture on it. +Next_Virtual_Screen will appear in the key image. + + +In the Command/URL Settings tab, enter the +command to run in the field: dcop kwin default +nextDesktop + + + +Repeat the above with the Prev_Virtual_Screen key and +dcop kwin default +previousDesktop. + +Now pressing the Prev_Virtual_Screen or +Next_Virtual_Screen will switch you to the previous or next +virtual desktop, respectively. + +Obviously you can assign any free key to any action. + + +Related Information +See the KHotKeys documentation by +looking it up in &khelpcenter;, or typing +help:/khotkeys in a &konqueror; +window. + + + + + + + + + + + +Adriaan +de Groot + +groot@kde.org + + + + +&kdebugdialog; - Controlling &kde;'s Debugging Output + + +Basic Usage + +&kdebugdialog; is not in the &kmenu; by default. You will need to run +it from the shell or from the mini-CLI with +the command kdebugdialog. +&kdebugdialog; pops up a window with a long list of debugging areas. Each +area has a checkbox that you can check or uncheck in order to enable or disable debugging output for +that part of &kde;. + +The list of debugging areas is sorted numerically, not alphabetically, +so kio (127) comes before artskde (400). The numbers go up to 200000 or so, +but there are really only 400 areas. You don't have to scroll through the +entire list to find the area you need, though. There is a line edit box at the top of the dialog where you can enter a part of +the name of the area you want. The list of entries that is displayed is +filtered to include only those debug areas that contain the text you have +entered. ⪚ entering k does not filter very much at +all, but entering kont will show you just the &kontact; debugging areas. As an even +quicker way of enabling or disabling debugging output, there are also +select all and deselect all +buttons which will cause &kde; to produce a mountain of debugging output, or +very little. + + + +KDebugDialog in full mode + + + +In full mode, which is what you get when you start kdebugdialog as +kdebugdialog +, the same list of debugging areas +as in plain mode is available, but you can select only one at a time from a +drop-down box. You may then independently set the output +for various types of messages: Information, Warning, Error and Fatal Error. +For each of these types, you can choose where the messages are sent. The +choices are: + +File, in which case you can enter a filename. This file is written into your +$HOME directory. + +Message Box. Each debugging message is displayed in an information dialog, +which you must OK to continue with the +application. + +Shell, the default entry. Messages are printed to stderr, and will appear + either in the shell window where the application was started, or +in .xsession-errors. + +Syslog. This sends each debugging message to the system's syslog facility, +which can perform its own processing of the message. + +None. This suppresses the output of this type of message. + +For messages generated by fatal errors, it is generally a bad idea to choose +None or Syslog, since in both cases you most likely will not see the message +and the application that encounters the fatal error will vanish without +leaving a clue as to why it vanishes. Whether or not the application will +vanish on fatal errors can be controlled by the checkbox abort on +fatal errors, which is checked by default — but you might +expect an application to crash (in a messy fashion) if a fatal error is +encountered anyway. + + + + + + + + + + + diff --git a/doc/userguide/usenet.docbook b/doc/userguide/usenet.docbook new file mode 100644 index 000000000..2aba10a2b --- /dev/null +++ b/doc/userguide/usenet.docbook @@ -0,0 +1,251 @@ + + + + + + +Usenet News + +Usenet newsgroups are forums in which you can post messages to discuss +various topics: almost any subject you like (and many you don't!) can +be found there. Although usenet has become less popular than it once +was, because of the increasing use of web forums, &etc;, it is still a +useful tool. &kde; provides a powerful usenet news reader called &knode;. + +You can find &knode; in the K Menu under the +Internet entry: the menu entry +&knode; (News Reader) launches the program. + + +The main window of &knode; should now be displayed on your +desktop as shown; on the first start, the settings dialog will be +invoked. + + +Setting up &knode; + + + + +&knode; after first start + + +&knode; after first start + + + + + +Personal settings + +The first page of the settings dialog is for personal settings: + +Dialog for entering personal information + + + + +Entering personal information + + +Entering personal information + + + + + + + +Name + +In the field Name, enter your name. This +name will later appear in the newsgroups as sender, and can be seen by +anyone. + +Filling out the field Name is +mandatory. + + + + + +Email address + +The email address you enter here will be used as sender in news +articles, &ie; as actual address of the author, in conjunction with +the real name (set in the field Name). + +Filling out the Email Address field is +mandatory. + + + + + + + + + +Configuring the news account + + +Now we must tell &knode; about where we get the news from or +where to send the articles to later on. In the list on the +right, there is an Accounts entry; click on it and choose the +Newsgroup servers tab, because we first want to configure +the news account: the list of accounts is still empty. + +To create a new account click on Add.... The +following dialog appears: + + +The New Account dialog + + + + +The New Account dialog + + +The New Account dialog + + + + + + + +Name + +The Name field can be filled in as you +like; the text you enter will later be visible in the folder view. You +could, for example, enter the name of your Internet Provider; for our example we +enter the name My News Account. + + + + +Server + + +The next field is labelled Server. Unlike +the field Name, what you enter here is important. +The name of the news server is fixed and you should be able to get it +from your Internet service provider; if you do not know the name of +the news server, you should get it now: without this information you +cannot read any news. If your Internet service provider doesn't own a +news server you can use a public one (universities often provide +public news servers.) + +For our example configuration we enter the name +news.server.com; you will, +of course, enter the real name of your news server. + + + + +Port + +You probably will not need to change this from the default in most +cases. + + + + + + + + +Setting up the mail account + +Sometimes you need to answer to the author of an article +directly, without posting to the newsgroup; for example, when you want +to make a very personal comment or want to correct an error. If you +want to do this, select the Mail Server (SMTP) tab. The +following dialog box appears: + + +Dialog Box for setting up the mail account + + + + +Setting up the mail account + + +Setting up the mail account + + + + + + + +Server + +The name (address) of your mail server as provided by your +Internet service provider or system administrator; all you have to do +here is enter the mail server's name in the +Server field. + +In our example we enter mail.server.com + + + + + +Port + + +Again, you probably will not need to change the +Port setting. + + + + + + +Related Information +The comp.windows.x.kde newsgroup is the main user +support group for &kde; on usenet. You can find other resources for +getting help with &kde; in . + +Gmane provides a +usenet frontend to many mailing lists, including most of the &kde; +lists, so you can read them with &knode;. + + + + + + + + + diff --git a/doc/userguide/where-next.docbook b/doc/userguide/where-next.docbook new file mode 100644 index 000000000..2da8d3e84 --- /dev/null +++ b/doc/userguide/where-next.docbook @@ -0,0 +1,40 @@ + + + + + + +Where To Next? + +Web Sites + +Books + + + + diff --git a/doc/userguide/windows-how-to.docbook b/doc/userguide/windows-how-to.docbook new file mode 100644 index 000000000..914e228da --- /dev/null +++ b/doc/userguide/windows-how-to.docbook @@ -0,0 +1,559 @@ + + + + +&Philip.Rodrigues; + + + + + +Windows, How To Work Them + + +Basic Window Management +Window Management + +Each application running in &kde; has its own window, and some +applications may use more than one window. You can manipulate these +windows in many ways to make your desktop work for you. Here is a +normal window: + + + + + +A normal window + + + + + + +Switching Between Windows +Focus (windows) + +If you want to use a window, it must be active. A window +automatically becomes active when you open it, so that the application +you opened is immediately ready to use. Only one window can be active +at a time. The active window is the one into which you can type, and can +be distinguished from the others because it has a different colored +titlebar. (With the &kde; default theme, the active window has a +light blue titlebar, and the inactive +windows have gray titlebars.) + + +Raising Windows +When you want to work in a different window, you need to make +it active. There are two ways to do this: + + + +&LMB;-click on the window that you want to make active. The +window will become active and will be raised above other windows if it +overlaps them. + + + +&Alt; +Hold down &Alt; and press (do not release the &Alt; +key). A popup dialog appears with a list of available windows, one of +which is highlighted. You can select a different window by pressing + again to move through the list, all the time holding down +&Alt;. When you release the &Alt; key, the window which was highlighted +is made active. + + + + + + + +Moving Windows +Moving Windows + +The first way to organize the windows on your desktop is to move +them around. You can move windows so that they overlap other windows, +or so that you can see the whole window. There are three ways to move +a window: + + +Click the &LMB; on the window titlebar and hold it down. Move +the mouse cursor and the window moves with it. Release the mouse +button, and the window remains where you left it. + + + + + + + +Open the window menu using the leftmost button on the window +titlebar (as displayed below), and select Move. The mouse cursor +moves to the center of the current window and by moving the mouse +around, you can move the window. Once you have moved the window to the +position you want, click the &LMB; to release it. +Window Menu + + +The Window Menu + + + + + +The Window Menu + + + + + + +Hold down &Alt; and the &LMB; when the mouse cursor is +above the window you want to move. The mouse cursor changes to a +compass, and by moving the mouse, you can move the window. Just +release the mouse button to release the window. This method is +particularly useful if the window titlebar has been moved off the +screen, so you cannot use the other methods. + + + + + + + +Resizing Windows + +Resizing Windows + +You can make windows bigger or smaller, wider, or taller in +one of two ways. Just use whichever you are most comfortable with: + + +Move the mouse cursor over the border of the window (it is light +blue in the screenshot above). The pointer will turn into a +double-headed arrow. Click and drag, and the edge of the window +follows the mouse cursor, making the window bigger or smaller. If you +click on the borders on the top or bottom of the window, you can +adjust the height on its own. If you click on the borders on the left +or right of the window, you can adjust the width. To change both at +the same time, move the mouse cursor over the corner of the +window. When the pointer becomes a diagonal double-headed arrow, click +and drag. + + +Use the leftmost button on the window titlebar to display the +window menu. Choose the Resize entry, and +the mouse pointer will become a double-headed arrow. Move the mouse +cursor around to resize, and click the &LMB; when you are done +to release the window. + + +If you cannot see the window border or the button for the window +menu, you can use &Alt; and the &RMB;: Hold down &Alt; and drag with +the &RMB;. The window will resize. You just release the &RMB; when +you are done. + + + + +If you just want to make a window as big as possible, so it +takes up the whole screen, use the +MaximizeMaximizing +Windows button, which is the second +button from the right on the window titlebar. Clicking with the &LMB; +on this button will make the window as big as possible in both +directions; while clicking with the &MMB;Maximizing +WindowsVertically or the +&RMB;Maximizing WindowsHorizontally +will increase the window's size in only the vertical or horizontal +direction, respectively. + + + + + +Hiding Windows +Hiding Windows + + + +Minimize +When you need to keep a program open, but you do not want it to +take up space on your desktop, you can minimize it or shade it. To +minimize a window, click the Minimize button, +which is third from the right on the window titlebar. The window will +not be displayed, but the program is still running, and an entry for +it appears in the taskbar on the panel. To display the window again, +click on its entry in the taskbar. You can also use &Alt; &Alt; : see . + + +Shade +Shading windows is very similar to minimizing them, but this +time, only the titlebar of the window is shown. To shade a window, +double-click on the titlebar. To restore the window, just double-click +on the titlebar again. + + + +Cascading Windows + +Sometimes you might have a whole lot of windows open and all over the place. By selecting to cascade windows &kde; will automatically line them up as a succession from the top-left of your screen. To use this option use your &MMB; on the desktop, and then select Cascade Windows. + + + + +Uncluttering Windows + +By selecting to unclutter your opened windows &kde; will attempt to use the maximum available space of the desktop in order to display as much of each window as possible. For example, should you have four windows open and you request that they be uncluttered, they will each be placed in a corner of the desktop, regardless of where they were originally. To use this option once again use your &MMB; on the desktop and then select Unclutter Windows. + + + + +Closing Windows + +Closing Windows + +When you finish using an application, you will want to stop +the application and close its window. Once again, you have the choice +of a few options: + + +Click on the rightmost button on the window titlebar. + If you are editing a document with that application, +you will be asked whether you want to Save your +changes, Discard them, or +Cancel your command to close the application. + + +Use the FileQuit + option on the menubar. You will be presented with the +same choice of Save, +Discard, or +Cancel. + + + + Right-click on the respective window in &kicker;, the &kde; panel, and then select Close. You will be prompted with an option to save any documents that were being edited. + + + +Press &Alt;F4&Alt;F4 + +. Once again, the confirmation dialog will be shown if you +were editing any documents. + + + + + + + + + + + + + +Advanced Window Management + +kstart + + + +&Richard.J.Moore; +&Richard.J.Moore.mail; + + +&kstart; + +The simplest way to access the advanced window management +facilities in &kde; is to use a little known +utility called &kstart;, which is included in &kde; since version 2.1 &kstart; lets you control the way an application interacts with +the window manager. The command is usually +used to define special behavior for commonly-used applications, but +it can also be useful for integrating non-&kde; applications into your +desktop. + +Using &kstart; is easy: you simply put +kstart and some options +before a command. To begin, let's look at how we might use +&kstart; to customize the behaviour of a +&kcalc; window. The command we'll use is as follows: + +% kstart + + +With luck, the effect this command has +should be fairly obvious - the kcalc window will stay on top of all +the others and be visible on every virtual desktop. A feature that is +less obvious is that this command will work with any NET compliant +environment, not just &kde;. + +We can pass arguments to programs we invoke with &kstart; as normal, for +example: + +% kstart + +1 xmessage'Hello World' + + + +This command displays Hello +World with xmessage and +ensures that the window will be shown on the first virtual desktop and +will be omitted from the taskbar. The fact that this program is +written using the Xt toolkit rather than being a native &kde; +application does not cause any problem for +&kstart;, hopefully this illustrates how +&kstart; can be used to integrate foreign +applications into your &kde; desktop. + + + +Other Special Window Settings +While you can use &kstart; to assign particular window settings, &kde; also allows you to alter these -- as well as other similar settings -- from the program window itself. Simply select the leftmost button in the window titlebar (or just hit &Alt;F3 once the window is focued), and then go to AdvancedSpecial Window Settings.... As you can see, from here you change various things from its geometry upon startup, to whether it should have a border or not. + + + + + +&Richard.J.Moore; +&Richard.J.Moore.mail; + + + +The System Tray + +Now that we know how to customize the decoration of a window +let's take a look at another aspect of the desktop: the system +tray. The system tray is an area in which an application can display a +small window. It is used to display status information or provide +quick access to commands. A window that has an item in the system tray +usually disappears from the task manager when minimised with the tray +icon providing a replacement. Normally tray icons are specifically +developed as part of an application, but as with window decorations, +&kde; provides a tool for changing this: +ksystraycmd. + +To begin with, we'll take the standard application &kcalc; and turn +it into a system tray application. This is acheived with one simple +command: +% ksystraycmd 'kcalc' kcalc + + + +The icon shown in the tray is the one specified in the window +hints and will be updated if the icon changes. The window title is +shown as a tooltip if you hold the mouse over the icon. +ksystraycmd follows standard &kde; +behaviour so the target window can be shown and hidden by clicking the +tray icon, and a standard context menu is available. + + + + + + + + +&Richard.J.Moore; +&Richard.J.Moore.mail; + + + +More Complex Uses of +<application>ksystraycmd</application> + +To illustrate the other features of +ksystraycmd, we'll use a more complicated example: a &konsole; window tracking the +.xsession-errors file (this is the log file that records what's +happening on your desktop). To begin with, we'll simply look at how +we can view this: +% konsole +log 'X Log' \ + + \ + tail -f ~/.xsession-errors + + + The and +arguments are provided as standard by &kde; applications. You can get +a full list of these global options by running an application with the + and +parameters. Here we give our &konsole; window the title 'X Log' and +the icon log. You can use these options with any &kde; application and +as mentioned above, ksystraycmd takes account of these when creating +the tray icon. The argument is specific to &konsole; and tells it +to run the less command. Despite its complexity, we can easily move +this window into the tray with ksystraycmd: + +% ksystraycmd + 'X Log' \ +konsole --icon log --caption 'XLog' \ +--nomenubar --notabbar --noframe \ +-e tail -f .xsession-errors + + + In addition to being the +most complex command we've used, this example demonstrates the + option which starts the command with only the system tray +icon visible. This example achieves our aim of providing quick access +to the log file, but we can do things a little more efficiently if we +only run the konsole process when it is visible. The command we use +is +% ksystraycmd \ + -- log 'X Log' \ +konsole --icon log --caption 'X Log' \ +--nomenubar --notabbar --noframe \ +-e tail -f ~/.xsession-errors + + +The addition of the parameter tells +ksystraycmd to start with only the tray +icon visible (like the parameter), and to wait until the user +activates the tray icon before running the target command. We've also +used the parameter which tells ksystraycmd to terminate +the target app whenever its window is hidden. Using both these +parameters ensures that our &konsole; tray icon doesn't waste resources +when we aren't using it. Creating and destroying the target window as +we do here prevents the standard icon and title handling of +ksystraycmd from working, so we now need to +specify the initial icon and tooltip explicitly +too. + + + + + +&Richard.J.Moore; +&Richard.J.Moore.mail; + + + +Improving Reliability + +In all of our previous examples we've relied on +&kstart; and +ksystraycmd to figure out which window we +want to affect, and unless we say otherwise, they assume that the first +window to appear is the one we want. This policy is usually OK because +we are starting the application at the same time, but it can fail +badly when lots of windows are appearing (such as when you log on). To +make our commands more robust we can use the + parameter. This specifies the title +of the target window. The following example uses the parameter +to ensure that a particular konsole window is affected: + +% kstart 'kstart_me' konsole +--caption 'kstart_me' -e tail -f +~/.xsession-errors + + + +Here we've used the tried and tested technique of specifying a +title for both &kstart; and the target application. This is generally +the best way to use &kstart; and ksystraycmd. The argument is +supported by both &kstart; and and can be regular expression +(⪚ window[0-9]) as well as a particular title. (Regular +expressions are a powerful pattern matching tool you'll find used +throughout &kde;.) + + + + + + +Using Multiple Desktops + +Virtual Desktops +Multiple Desktops + +Sometimes, one screen's worth is just not enough space. If you +use many applications at the same time, and find yourself drowning in +different windows, virtual desktops offer the solution. By default, +&kde; has four virtual desktops, each one of which is like a separate +screen: you can open windows, move windows around, and set backgrounds and +icons on each of the desktops. If you are familiar with the concept of +virtual terminals, you will have no trouble with &kde;'s virtual +desktops. + + +Switching Virtual Desktops +To move to a different virtual desktop, you can use &Ctrl; + in the same way as you would use &Alt; + to switch between windows (see ): Hold down &Ctrl; and then press + . A small popup window appears, showing the virtual desktops, +with one highlighted. If you release &Ctrl;, &kde; will switch to the +highlighted virtual desktop. To select a different desktop, press + repeatedly, while holding down &Ctrl;. The selection moves +through the available desktops. When the desktop you want to switch to +is highlighted, release &Ctrl;. + + + + + + +Windows and Virtual Desktops +You can move windows around your virtual desktops with the +To Desktop item in the window menu: just +select the desktop to which you want to move the window. You can make the +window appear on all desktops with the All +DesktopsSticky +Windows item. + + + + + + + + + diff --git a/doc/userguide/your-kde-account.docbook b/doc/userguide/your-kde-account.docbook new file mode 100644 index 000000000..aa37dddac --- /dev/null +++ b/doc/userguide/your-kde-account.docbook @@ -0,0 +1,79 @@ + + + + + + +About Your &kde; Account + +&kde; stores information about your personal settings in a few +different places: + + +The hidden directory .kde (note the +period at the beginning), located in your home directory, contains a +large number of files that store &kde; settings. Some subdirectories +you may find useful are:.kde/share/config, which +contains configuration files for individual applications; +.kde/Autostart, which contains links to +applications which should start each time you start &kde;; and +.kde/share/apps/kabc, where your address book is +stored. + + + +The environment variables KDEDIR and +KDEDIRS tell &kde; where its files are stored. You will +usually only need to set KDEDIR to the directory in which +&kde; is installed, but sometimes you might have other &kde; +programs installed elsewhere: in this case, you can use the +KDEDIRS environment variable. Set +KDEDIRS to a list of all the directories containing +&kde; programs, separated by commas. For example, if you have &kde; +programs in both /usr/local/kde and +/home/phil/kde, you can use export +KDEDIR=/usr/local/kde,/home/phil/kde if you use +bash or setenv +KDEDIR=/usr/local/kde,/home/phil/kde if you use sh. + + + + + + + +Related Information + contains +more information about the directories that &kde; uses. + + + + + + + diff --git a/doc/visualdict/Makefile.am b/doc/visualdict/Makefile.am new file mode 100644 index 000000000..81064650f --- /dev/null +++ b/doc/visualdict/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/visualdict + diff --git a/doc/visualdict/index.docbook b/doc/visualdict/index.docbook new file mode 100644 index 000000000..c950ca395 --- /dev/null +++ b/doc/visualdict/index.docbook @@ -0,0 +1,349 @@ + + + + + + +]> + + + + +The &kde; Visual Guide + + +The &kde; Team + + + + +2006-12-06 +3.00.00 + + +20002006 +The &kde; Team + + +&FDLNotice; + +A visual guide to &kde;'s interface. This is a very early +version +of the document. Eventually, this will be a graphical tour of +&kde;. + + +KDE +Visual +Dictionary +Guide + + + + + + + + + + +&kde; Visual Dictionary of terms + +This project was started to help unify the vocabulary used in &kde; +documentation. + +We provide this for you here as an aid to learning your way around the +&kde; +Graphical User Interface. These names have been standardized within &kde; +documentation, so that you will always find interface items referred to in the +same way. + +The term Widget refers to the basic building +block of a computer program's interface. +Each widget operates in a +similar manner each time it is used, but the effect that the widget has depends on +its place within the program. + + + +Listing of Common &kde; Widgets +Currently, this guide consists of a table of the names of the graphical +elements often found in &kde; documentation, and an example of each one. +Our hope, eventually, is to make this a much more complete document, +which will take you on a visual tour of &kde;. + + + + + + +Button + + + + + + + + + + +Check Boxes + + + + + + + + + + +Color Selector + + + + + + + + + + +Combo Box + + + + + + + + + + +Context Menu + + + + + + + + + + +Dialog Box + + + + + + + + + + +Drop Down Box + + + + + + + + + + +Icon List + + + + + + + + + + +List Box + + + + + + + + + + + + + + + +Menubar + + + + + + + + + + +Progress Bar + + + + + + + + + + +Radio Buttons + + + + + + + + + + +Scroll Bar + + + + + + + + + + +Slider + + + + + + + + + + +Spin Box + + + + + + + + + + +Status Bar + + + + + + + + + + +Tab + + + + + + + + + + +Tabbed Window + + + + + + + + + + +Text Box + + + + + + + + + + +Toolbar + + + + + + + + + + +Tree View + + + + + + + + + + + +Window Titlebar + + + + + + + + + + + + + + + +Credits and Licenses +&kappname; + +Documentation by the &kde; Documentation Team. + +&underFDL; + + + + diff --git a/doc/visualdict/pict1.png b/doc/visualdict/pict1.png new file mode 100644 index 000000000..de9cf8695 Binary files /dev/null and b/doc/visualdict/pict1.png differ diff --git a/doc/visualdict/pict10.png b/doc/visualdict/pict10.png new file mode 100644 index 000000000..4d526ca74 Binary files /dev/null and b/doc/visualdict/pict10.png differ diff --git a/doc/visualdict/pict11.png b/doc/visualdict/pict11.png new file mode 100644 index 000000000..5968a7a2d Binary files /dev/null and b/doc/visualdict/pict11.png differ diff --git a/doc/visualdict/pict12.png b/doc/visualdict/pict12.png new file mode 100644 index 000000000..49643c607 Binary files /dev/null and b/doc/visualdict/pict12.png differ diff --git a/doc/visualdict/pict13.png b/doc/visualdict/pict13.png new file mode 100644 index 000000000..26a615502 Binary files /dev/null and b/doc/visualdict/pict13.png differ diff --git a/doc/visualdict/pict14.png b/doc/visualdict/pict14.png new file mode 100644 index 000000000..1f32bfe83 Binary files /dev/null and b/doc/visualdict/pict14.png differ diff --git a/doc/visualdict/pict15.png b/doc/visualdict/pict15.png new file mode 100644 index 000000000..6fc7a5ca2 Binary files /dev/null and b/doc/visualdict/pict15.png differ diff --git a/doc/visualdict/pict16.png b/doc/visualdict/pict16.png new file mode 100644 index 000000000..c5692e751 Binary files /dev/null and b/doc/visualdict/pict16.png differ diff --git a/doc/visualdict/pict17.png b/doc/visualdict/pict17.png new file mode 100644 index 000000000..a49a9a271 Binary files /dev/null and b/doc/visualdict/pict17.png differ diff --git a/doc/visualdict/pict18.png b/doc/visualdict/pict18.png new file mode 100644 index 000000000..0853ddb52 Binary files /dev/null and b/doc/visualdict/pict18.png differ diff --git a/doc/visualdict/pict19.png b/doc/visualdict/pict19.png new file mode 100644 index 000000000..e366a3da1 Binary files /dev/null and b/doc/visualdict/pict19.png differ diff --git a/doc/visualdict/pict2.png b/doc/visualdict/pict2.png new file mode 100644 index 000000000..87724f8ea Binary files /dev/null and b/doc/visualdict/pict2.png differ diff --git a/doc/visualdict/pict20.png b/doc/visualdict/pict20.png new file mode 100644 index 000000000..82c4a738e Binary files /dev/null and b/doc/visualdict/pict20.png differ diff --git a/doc/visualdict/pict21.png b/doc/visualdict/pict21.png new file mode 100644 index 000000000..573c7a2a0 Binary files /dev/null and b/doc/visualdict/pict21.png differ diff --git a/doc/visualdict/pict22.png b/doc/visualdict/pict22.png new file mode 100644 index 000000000..052be0b83 Binary files /dev/null and b/doc/visualdict/pict22.png differ diff --git a/doc/visualdict/pict23.png b/doc/visualdict/pict23.png new file mode 100644 index 000000000..1e09a5787 Binary files /dev/null and b/doc/visualdict/pict23.png differ diff --git a/doc/visualdict/pict3.png b/doc/visualdict/pict3.png new file mode 100644 index 000000000..124986e53 Binary files /dev/null and b/doc/visualdict/pict3.png differ diff --git a/doc/visualdict/pict4.png b/doc/visualdict/pict4.png new file mode 100644 index 000000000..498ca7212 Binary files /dev/null and b/doc/visualdict/pict4.png differ diff --git a/doc/visualdict/pict5.png b/doc/visualdict/pict5.png new file mode 100644 index 000000000..f383ca563 Binary files /dev/null and b/doc/visualdict/pict5.png differ diff --git a/doc/visualdict/pict6.png b/doc/visualdict/pict6.png new file mode 100644 index 000000000..542b2f278 Binary files /dev/null and b/doc/visualdict/pict6.png differ diff --git a/doc/visualdict/pict7.png b/doc/visualdict/pict7.png new file mode 100644 index 000000000..4ed9d6074 Binary files /dev/null and b/doc/visualdict/pict7.png differ diff --git a/doc/visualdict/pict8.png b/doc/visualdict/pict8.png new file mode 100644 index 000000000..6f896ea4b Binary files /dev/null and b/doc/visualdict/pict8.png differ diff --git a/doc/visualdict/pict9.png b/doc/visualdict/pict9.png new file mode 100644 index 000000000..9a4aac405 Binary files /dev/null and b/doc/visualdict/pict9.png differ -- cgit v1.2.3