README
1Dear User/Packager,
2
3this Readme is targeted toward users who want to build Kile from source or plan to create binary packages on Linux systems
4
5
6(1) Checking dependencies
7============================
8
9You will need recent versions of
10
11- a C++ compiler that supports lambda expressions (like GCC 6.x)
12- CMake
13- Qt 5 (and corresponding development packages if installed from binary packages)
14- KDE Frameworks 5 (and corresponding development packages if installed from binary packages)
15- Okular 5 (and corresponding development packages if installed from binary packages)
16
17(2) Building Kile from source on Linux systems
18==============================================
19
20It is recommended to create a special directory which will contain the Kile executable and related files. In that way
21it is easier to upgrade Kile. We assume in the following that the directory $HOME/kile-install is used for that purpose.
22If you do not want to use a separate directory, you can also install Kile into the local KDE directory for your user,
23which is named $HOME/.kde usually. The different steps for compiling Kile are now as follows:
24
25- Extract the source code with "tar xjf kile-<x>.tar.bz2"
26- Create a "kile-build" directory somewhere for an out-of-source build.
27- Enter the "kile-build" directory and call CMake with:
28 " cmake <path to the Kile source directory> -DCMAKE_INSTALL_PREFIX=$HOME/kile-install -DCMAKE_BUILD_TYPE="Debug" "
29- Type "make -j 2" to compile the package.
30- Type "make install -j 2" to install the programs, data files and documentation.
31- Type "XDG_DATA_DIRS=$HOME/kile-install/:$XDG_DATA_DIRS $HOME/kile-install/bin/kile" to run Kile
32
33(3) Using Kile
34===============================
35
36To use Kile you (obviously) need some external programs.
37The following list is divided into basic, advanced and additional usage.
38
39Basic:
40- TeXLive LaTeX distribution, which will add, among others, the following programs:
41 - Tex/LaTeX
42 - PDFLaTeX
43 - XeLaTeX
44 - ConTeXt
45 - BibTeX
46 - MakeIndex
47
48Advanced:
49- ImageMagick, DVIPNG (for the bottom bar preview)
50
51By default Kile ships with pre-defined tool settings for following programs:
52- Tar/Zip/GZip/BZip2 (Archive)
53- DBLaTeX (Docbook to LaTeX)
54- Metapost and Asymptote
55- LaTeX2html (LaTeX to Web)
56- Tex4ht (LaTeX to Web)
57- Xindy (MakeIndex replacement)
58- Lilypond (Music Typesetting)
59- Konqueror/Firefox (Viewing HTML)
60- KBibTeX, KBib, JabRef, PyBliographer, GBib (View BibTeX files)
61
62If you have any questions, please don't hesitate to contact us via kile-devel@lists.sourceforge.net.
63
64The Kile development team
65
README.MacOSX
1[See below for an alternative way]
2
3In order to install Kile on MacOS X, you need the following things:
4- a working LaTeX distribution
5- the KDE libraries
6- and Kile itself, of course
7
8Installing X11
9--------------
10
11[X11 does not need to be installed with Qt4 as it can use the Aqua framework.]
12
13
14Installing all the rest through Fink
15------------------------------------
16
17Fink is the packaging system from Debian ported to MacOS X. Installing Fink itself is very straightforward, so only two things will be mentioned here:
18- you must download and install the latest Xcode version from Apple (free download, just requires registration),
19- make sure Fink uses the package repository compatible with your system (specifically, if you have MacOS X 10.4, use the 10.4 branch and *not* the 10.4-transitional branch).
20
21Fink lets you choose between precompiled, ready-to-use, packages, and compiling them yourself. Practically speaking, the Fink project provides few up-to-date precompiled packages, so compilation is often necessary. But don't worry, the procedure is automatic in any case.
22
23After that, installing the rest is very straightforward:
24
25- LaTeX distribution: install packages "tetex" and "tetex-base".
26- KDE libraries: the bare minimum would be package "kdebase3-unified", but you should also install packages like "kpdf", "kdvi" and "kghostview" to make best use of Kile. Installing a localisation package to have dialogs in your language would also be nice ; for example, the French package is called "kde-i18n-french".
27- Kile: its package is called "kile".
28- Other useful packages, depending on your habits: "bibview", "gnuplot", "xfig", "beamer", "texpower"... Just go shopping with Fink.
29
30Have fun!
31
32Fink project: http://fink.sourceforge.net
33
34
35Installing Kile through Macports
36--------------------------------
37
38Macports is a source-based package manager, from which it is possible to install the whole software suite needed for Kile.
39Macports can be installed from a package installer, which can be found for each Apple platform at: http://www.macports.org/install.php.
40
41Configuring Macports:
42When Macports is installed, it needs to be configured slightly in order to ensure that the correct configurations are prepared for Kile. For this, run:
43 sudo pico /opt/local/etc/macports/variants.conf
44and add:
45 +no_x11 +quartz +qt4
46at the end of the file.
47
48Then, run
49 sudo port selfupdate
50in order to ensure that latest versions of the softwares will be installed.
51
52Installing Kile:
53At this point, you can run
54 sudo port install kile-devel
55kile-devel is the KDE4 port for Kile. This will install all the libraries needed for Kile, including Qt4, and KDE packages. This compilation will take a lot of time, but you can follow the installation progress for each package. At the end of the installation, you need to run some commands in order to finish the configuration, to ensure that DBUS will work, and to ensure you have access to KDE preferences:
56 sudo launchctl load -w /Library/LaunchDaemons/org.freedesktop.dbus-system.plist
57 launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist
58 sudo chown -R $USER ~/Library/Preferences/KDE
59where $USER should be changed to your login name.
60
61Finding TeX paths:
62The application bundles of Apple do not recognize the $PATH variables set for xterm. We therefore need to set them for Kile. To set globally the $PATH variable for application bundles. For this, you can run the following commands:
63 mkdir ~/.MacOSX
64 pico ./.MacOSX/environments.plist
65and add the following text in environments.plist:
66 <?xml version="1.0" encoding="UTF-8"?>
67 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
68 <plist version="1.0">
69 <dict>
70 <key>KDEDIRS</key>
71 <string>/opt/local</string>
72 <key>PATH</key>
73 <string>/opt/local/bin:/opt/local/sbin:$TEXPATH</string>
74 </dict>
75 </plist>
76where you should replace $TEXPATH with the path to your TeX distribution. Typically, it should be /opt/local/bin if you are using the TeXLive port of Macports (so that you can leave it blank), or /usr/local/texbin if you are using MacTeX package.
77
78Starting Kile:
79You should first start the /Applications/Macports/KDE4/kdeinit4.app program to set up the KDE environment. Then, you can start Kile, and check that everything work fine by performing a system check from the Settings menu.
80
81
82Other installation methods
83--------------------------
84
85[i-installer is deprecated as of Jan 1 2007]
86
87[This upper part of the readme was contributed by Thibaut Cousin (cousin@kde.org)]
88
89
90Kile SVN for KDE 4
91------------------
92It is now possible to install the latest version of Kile from the Subversion repository using the KDE 4 libraries. This means that you no longer need to use the X11 libraries. To achieve this you need:
93
94- KDE 4.1 packages from http://mac.kde.org/
95- Kile source from SVN
96
97First download the latest packages from http://mac.kde.org/?id=download
98At the time of writing the latest version is 4.1.2. Install the packages in order. Once these
99are installed you should have a working version of KDE for the Mac. If applications crash, try issuing the command:
100
101launchctl load -F /Library/LaunchAgents/org.freedesktop.dbus-session.plist
102
103to launch D-BUS. If when a program starts but gives an error about D-BUS being uncontactable, try rebooting.
104
105Once you have a working copy of KDE 4.1 the next step is to download and compile Kile from the Subversion repository. Follow the instructions on:
106
107http://techbase.kde.org/Projects/KDE_on_Mac_OS_X/Macbook_Manifesto
108
109This will set up your build environment. Next get the latest version using the command:
110
111svn co svn://anonsvn.kde.org/home/kde/trunk/extragear/office/kile
112
113Go into this directory in a terminal and run the commands:
114- cmake .
115- make
116- sudo make install
117
118You now have a running native version of Kile on your Mac!
119
120[The lower part of this readme was contributed by Thomas Quillinan <t.quillinan@gm...>]
121
README.cwl
1CWL File Specification 0.1:
2
3Completion modes:
4 Kile supports three completion modes, which use their own cwl files:
5 - (La)TeX mode
6 - Dictionary mode
7 - Abbreviation mode
8
9Call of completion:
10 When completion is called with a shortcut or in auto mode, Kile must separate words, so that some restriction had to be made about the already typed prefix. If the prefix is to be analyzed as valid, the completion box will open, otherwise not.
11 - (La)TeX mode: all prefixes must start with a backslash, followed by letters, possibly with a trailing star
12 - Dictionary mode: letters, digits and underscore are valid characters
13 - Abbreviation mode: letters, digits and underscore are valid characters
14 Once the completion box is opened, there are no further restrictions. All characters are valid from this moment on.
15
16Naming scheme of the cwl file:
17 - If the commands in the file belong to a class the name is class-foo.cwl, if they belong to different classes the name is class-foo,bar.cwl.
18 - In any other case it belongs to a package and should therefore have the same name than the package (package foo -> foo.cwl)
19
20File syntax:
21 - There are only two types of content, comments and text.
22 - Comments start with a #, everything after # is ignored till the end of the line.
23 - Everything else is text.
24
25File content:
26 - The files should have a small header including your name (email address is not needed), the date, and a link where the package or the class file can be downloaded.
27 For example the header of textcomp.cwl:
28 # textcomp package
29 # tbraun 04/27/2006
30 # URL: http://www.ctan.org/tex-archive/help/Catalogue/entries/textcomp.html
31 - All commands given must have a description what to insert in the empty brackets:
32 -- \label{key} and not \label{}
33 -- \includegraphics[options]{name}
34 -- \footnotetext[number]{text} and so on
35 - All commands means all commands. So please add all possible combinations, including mandatory options and all optional options in all possible combinations.
36 This list can be quite long but all users will appreciate the completeness.
37 For example (taken from class-beamer.cwl):
38 \begin{frame}
39 \begin{frame}<overlay specification>
40 \begin{frame}<overlay specification>[<default overlay specification>]
41 \begin{frame}<overlay specification>[<default overlay specification>][options]
42 \begin{frame}<overlay specification>[<default overlay specification>][options]{title}
43 \begin{frame}<overlay specification>[<default overlay specification>][options]{title}{subtitle}
44 \begin{frame}[<default overlay specification>]
45 \begin{frame}[<default overlay specification>][options]
46 \begin{frame}[<default overlay specification>][options]{title}
47 \begin{frame}[<default overlay specification>][options]{title}{subtitle}
48 \begin{frame}[<default overlay specification>][options]{title}{subtitle}
49 \begin{frame}[options]
50 \begin{frame}[options]{title}
51 \begin{frame}[options]{title}{subtitle}
52 \begin{frame}[options]{title}{subtitle}
53 \begin{frame}{title}
54 \begin{frame}{subtitle}
55 \end{frame}
56 - Only include the \end{env} command once, but all combinations with \begin{env}{}[]<>...
57 - If you declare an environment in which the \item command is valid you have to suffix the \begin{...} declaration with \item, like in latex-document.cwl \begin{itemize}\item.
58 - A starred version of a command must also be added
59 \circle{diameter}
60 \circle*{diameter}
61
62Getting assistance:
63 - You can see some examples under http://projects.kde.org/projects/extragear/office/kile/repository/revisions/master/show/src/data/complete/tex
64 - If in doubt don't hesitate to mail to kile-devel@lists.sourceforge.net and ask, we will be glad to help you :)
65
66The Kile development team
67