Date: Mon, 14 May 2012 08:33:53 GMT From: Alberto Villa <avilla@FreeBSD.org> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/167864: [patch] Update KDE documentation in Handbook and Porter's Handbook Message-ID: <201205140833.q4E8XrGQ099781@red.freebsd.org> Resent-Message-ID: <201205140840.q4E8e2CJ012772@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 167864
>Category: docs
>Synopsis: [patch] Update KDE documentation in Handbook and Porter's Handbook
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon May 14 08:40:01 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator: Alberto Villa
>Release:
>Organization:
>Environment:
>Description:
KDE documentation is quite outdated both in the Handbook and in the Porter's Handbook. The attached patch updates it and cleans it up, and fixes a serious documentation bug within the KDM section.
>How-To-Repeat:
>Fix:
Patch attached with submission follows:
Index: handbook/x11/chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v
retrieving revision 1.212
diff -u -r1.212 chapter.sgml
--- handbook/x11/chapter.sgml 16 Feb 2012 05:06:57 -0000 1.212
+++ handbook/x11/chapter.sgml 14 May 2012 08:30:41 -0000
@@ -1323,9 +1323,9 @@
<para>Several replacements for the default
<application>XDM</application> program exist. One of them,
- <application>kdm</application> (bundled with
+ <application>KDM</application> (bundled with
<application>KDE</application>) is described later in this
- chapter. The <application>kdm</application> display manager offers many visual
+ chapter. The <application>KDM</application> display manager offers many visual
improvements and cosmetic frills, as well as the
functionality to allow users to choose their window manager
of choice at login time.</para>
@@ -1460,7 +1460,7 @@
<para>Yet another option is to configure the display manager to
allow choosing the window manager at login time; the section on
<link linkend="x11-wm-kde-details">KDE details</link>
- explains how to do this for <application>kdm</application>, the
+ explains how to do this for <application>KDM</application>, the
display manager of <application>KDE</application>.</para>
</sect3>
</sect2>
@@ -1504,7 +1504,7 @@
<listitem>
<para>Internationalization: <application>KDE</application>
- is available in more than 40 languages</para>
+ is available in more than 55 languages</para>
</listitem>
<listitem>
@@ -1525,13 +1525,15 @@
can be found on the <ulink url="http://www.kde.org/">KDE
website</ulink>. For FreeBSD specific information and
resources on <application>KDE</application>, consult
- the <ulink url="http://freebsd.kde.org/">KDE on FreeBSD
- team</ulink>'s website.</para>
+ the <ulink url="http://freebsd.kde.org/">KDE/FreeBSD
+ initiative</ulink>'s website.</para>
- <para>There are two versions of <application>KDE</application> available on FreeBSD. Version 3
- has been around for a long time, and is very mature. Version 4,
- the next generation, is also available in the Ports Collection.
- They can even be installed side by side.</para>
+ <para>There are two versions of <application>KDE</application> available
+ on FreeBSD. Version 3 has been around for a long time, and is still
+ available in the Ports Collection though it's now unmaintained and
+ partially broken. Version 4 is punctually updated and is the default
+ choice for <application>KDE</application> users. They can even be
+ installed side by side.</para>
</sect3>
<sect3 id="x11-wm-kde-install">
@@ -1541,12 +1543,12 @@
other desktop environment, the software can be easily installed
from a package or the Ports Collection:</para>
- <para>To install the <application>KDE3</application> package
+ <para>To install the <application>KDE 3</application> package
from the network, simply type:</para>
<screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen>
- <para>To install the <application>KDE4</application> package
+ <para>To install the <application>KDE 4</application> package
from the network, simply type:</para>
<screen>&prompt.root; <userinput>pkg_add -r kde4</userinput></screen>
@@ -1554,13 +1556,13 @@
<para>&man.pkg.add.1; will automatically fetch the latest version
of the application.</para>
- <para>To build <application>KDE3</application> from source,
+ <para>To build <application>KDE 3</application> from source,
use the ports tree:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
- <para>To build <application>KDE4</application> from source,
+ <para>To build <application>KDE 4</application> from source,
use the ports tree:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput>
@@ -1571,12 +1573,12 @@
instead of the default window manager. This is accomplished
by editing the <filename>.xinitrc</filename> file:</para>
- <para>For <application>KDE3</application>:</para>
-
+ <para>For <application>KDE 3</application>:</para>
+
<screen>&prompt.user; <userinput>echo "exec startkde" > ~/.xinitrc</userinput></screen>
- <para>For <application>KDE4</application>:</para>
-
+ <para>For <application>KDE 4</application>:</para>
+
<screen>&prompt.user; <userinput>echo "exec /usr/local/kde4/bin/startkde" > ~/.xinitrc</userinput></screen>
<para>Now, whenever the X Window System is invoked with
@@ -1587,7 +1589,7 @@
<application>XDM</application> is being used, the
configuration is slightly different. Edit the
<filename>.xsession</filename> file instead. Instructions
- for <application>kdm</application> are described later in
+ for <application>KDM</application> are described later in
this chapter.</para>
</sect3>
</sect2>
@@ -1618,28 +1620,28 @@
<link linkend="x-xdm">XDM</link> can be
used, as described earlier. However,
<application>KDE</application> includes an
- alternative, <application>kdm</application>, which is designed
+ alternative, <application>KDM</application>, which is designed
to look more attractive and include more login-time options.
In particular, users can easily choose (via a menu) which
desktop environment (<application>KDE</application>,
<application>GNOME</application>, or something else) to run
after logging on.</para>
- <para>To enable <application>kdm</application>, different files
+ <para>To enable <application>KDM</application>, different files
need to be edited depending on the version of
<application>KDE</application>.</para>
- <para>For <application>KDE3</application>, the <literal>ttyv8</literal>
+ <para>For <application>KDE 3</application>, the <literal>ttyv8</literal>
entry in <filename>/etc/ttys</filename> has to be adapted as
follows:</para>
<programlisting>ttyv8 "/usr/local/bin/kdm -nodaemon" xterm on secure</programlisting>
- <para>For <application>KDE4</application>, you have to add the
- following lines to <filename>/etc/rc.conf</filename>:</para>
+ <para>For <application>KDE 4</application>, you have to mount
+ &man.procfs.5; and add the following line to
+ <filename>/etc/rc.conf</filename>:</para>
- <programlisting>local_startup="${local_startup} /usr/local/kde4/etc/rc.d"
-kdm4_enable="YES"</programlisting>
+ <programlisting>kdm4_enable="YES"</programlisting>
</sect3>
</sect2>
Index: porters-handbook/book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.1186
diff -u -r1.1186 book.sgml
--- porters-handbook/book.sgml 2 May 2012 10:21:37 -0000 1.1186
+++ porters-handbook/book.sgml 14 May 2012 08:30:44 -0000
@@ -1742,8 +1742,7 @@
<row>
<entry><filename>kde*</filename></entry>
<entry>Ports from the <ulink
- url="http://www.kde.org">K Desktop Environment
- (KDE)</ulink> Project.</entry>
+ url="http://www.kde.org">KDE</ulink>; Project.</entry>
<entry></entry>
</row>
@@ -6004,7 +6003,8 @@
<entry><makevar>QTNONSTANDARD</makevar></entry>
<entry>Suppress modification of
<makevar>CONFIGURE_ENV</makevar>,
- <makevar>CONFIGURE_ARGS</makevar>, and
+ <makevar>CONFIGURE_ARGS</makevar>,
+ <makevar>CPPFLAGS</makevar> and
<makevar>MAKE_ENV</makevar>.</entry>
</row>
</tbody>
@@ -6019,30 +6019,26 @@
<tbody>
<row>
<entry><makevar>QT_COMPONENTS</makevar></entry>
- <entry>Specify tool and library dependencies for Qt4.
+ <entry>Specify tool and library dependencies for Qt 4.
See below for details.</entry>
</row>
<row>
<entry><makevar>UIC</makevar></entry>
<entry>Set to the path of <command>uic</command>
- (read-only variable). Default set according to
- <makevar>USE_QT_VER</makevar> value.</entry>
+ (read-only variable).</entry>
</row>
<row>
<entry><makevar>QMAKE</makevar></entry>
<entry>Set to the path of <command>qmake</command>
- (read-only variable). Default set according to
- <makevar>USE_QT_VER</makevar> value.</entry>
+ (read-only variable).</entry>
</row>
<row>
<entry><makevar>QMAKESPEC</makevar></entry>
<entry>Set to the path of configuration file for
- <command>qmake</command> (read-only variable).
- Default set according to
- <makevar>USE_QT_VER</makevar> value.</entry>
+ <command>qmake</command> (read-only variable).</entry>
</row>
</tbody>
</tgroup>
@@ -6056,8 +6052,9 @@
--with-qt-libraries=${QT_PREFIX}/lib \
--with-extra-libs=${LOCALBASE}/lib \
--with-extra-includes=${LOCALBASE}/include
-CONFIGURE_ENV+= MOC="${MOC}" CPPFLAGS="${CPPFLAGS} ${QTCPPFLAGS}" LIBS="${QTCFGLIBS}" \
- QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}"</programlisting>
+CONFIGURE_ENV+= MOC="${MOC}" LIBS="${QTCFGLIBS}" \
+ QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}"
+CPPFLAGS+= ${QTCPPFLAGS}</programlisting>
<para>If <makevar>USE_QT_VER</makevar> is set to
<literal>4</literal>, the following settings are also
@@ -6070,8 +6067,8 @@
<sect2 id="qt4-components">
<title>Component Selection (Qt 4.x Only)</title>
- <para>When <makevar>USE_QT_VER</makevar> is set to 4,
- individual Qt4 tool and library dependencies can be
+ <para>When <makevar>USE_QT_VER</makevar> is set to <literal>4</literal>,
+ individual Qt 4 tool and library dependencies can be
specified in the <makevar>QT_COMPONENTS</makevar> variable.
Every component can be suffixed by either
<literal>_build</literal> or <literal>_run</literal>, the
@@ -6088,7 +6085,7 @@
<filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para>
<table frame="none">
- <title>Available Qt4 Library Components</title>
+ <title>Available Qt 4 Library Components</title>
<tgroup cols="2">
<thead>
@@ -6122,7 +6119,7 @@
<row>
<entry><literal>qt3support</literal></entry>
- <entry>Qt3 compatibility library</entry>
+ <entry>Qt 3 compatibility library</entry>
</row>
<row>
@@ -6154,7 +6151,7 @@
executable after a successful compilation.</para>
<table frame="none">
- <title>Available Qt4 Tool Components</title>
+ <title>Available Qt 4 Tool Components</title>
<tgroup cols="2">
<thead>
@@ -6178,7 +6175,7 @@
<row>
<entry><literal>rcc</literal></entry>
- <entry>resource compiler (need if the application
+ <entry>resource compiler (needed if the application
comes with <filename>*.rc</filename> or
<filename>*.qrc</filename> files)</entry>
</row>
@@ -6195,7 +6192,7 @@
</table>
<table frame="none">
- <title>Available Qt4 Plugin Components</title>
+ <title>Available Qt 4 Plugin Components</title>
<tgroup cols="2">
<thead>
@@ -6223,17 +6220,18 @@
</table>
<example id="qt4-components-example">
- <title>Selecting Qt4 Components</title>
+ <title>Selecting Qt 4 Components</title>
- <para>In this example, the ported application uses the Qt4
- graphical user interface library, the Qt4 core library,
- all of the Qt4 code generation tools and Qt4's Makefile
- generator. Since the gui library implies a dependency on
- the core library, corelib does not need to be specified.
- The Qt4 code generation tools moc, uic and rcc, as well as
- the Makefile generator qmake are only needed at buildtime,
- thus they are specified with the <literal>_build</literal>
- suffix:</para>
+ <para>In this example, the ported application uses the Qt 4
+ graphical user interface library, the Qt 4 core library,
+ all of the Qt 4 code generation tools and Qt 4's Makefile
+ generator. Since the <literal>gui</literal> library implies
+ a dependency on the core library, <literal>corelib</literal>
+ does not need to be specified. The Qt 4 code generation tools
+ <literal>moc</literal>, <literal>uic</literal> and
+ <literal>rcc</literal>, as well as the Makefile generator
+ <literal>qmake</literal> are only needed at buildtime, thus they
+ are specified with the <literal>_build</literal> suffix:</para>
<programlisting>USE_QT_VER= 4
QT_COMPONENTS= gui moc_build qmake_build rcc_build uic_build</programlisting>
@@ -6252,7 +6250,7 @@
do-configure:
@cd ${WRKSRC} && ${SETENV} ${CONFIGURE_ENV} \
- ${QMAKE} -unix PREFIX=${PREFIX} texmaker.pro</programlisting>
+ ${QMAKE} PREFIX=${PREFIX} texmaker.pro</programlisting>
<para>Note the similarity to the <command>qmake</command> line
from the provided <filename>BUILD.sh</filename> script.
@@ -6271,14 +6269,14 @@
<itemizedlist>
<listitem>
<para><emphasis>Missing additional
- includepaths.</emphasis> Many applications come with
+ include paths.</emphasis> Many applications come with
system tray icon support, but neglect to look for
includes and/or libraries in the X11 directories. You
can tell <command>qmake</command> to add directories to
- the include and library searchpaths via the command
+ the include and library search paths via the command
line, for example:</para>
- <programlisting>${QMAKE} -unix PREFIX=${PREFIX} INCLUDEPATH+=${LOCALBASE}/include \
+ <programlisting>${QMAKE} PREFIX=${PREFIX} INCLUDEPATH+=${LOCALBASE}/include \
LIBS+=-L${LOCALBASE}/lib sillyapp.pro</programlisting>
</listitem>
@@ -6287,12 +6285,12 @@
Sometimes data such as icons or .desktop files are by
default installed into directories which aren't scanned
by XDG-compatible applications. <filename
- role="package">editors/texmaker</filename> is an
+ role="package">editors/texmaker</filename> is an
example for this - look at
<filename>patch-texmaker.pro</filename> in the
<filename>files</filename> directory of that port for a
- template on how to remedy this directly in the Qmake
- project file.</para>
+ template on how to remedy this directly in the
+ <command>qmake</command> project file.</para>
</listitem>
</itemizedlist>
</sect2>
@@ -6336,13 +6334,18 @@
<para>If your application depends on KDE 4.x, set
<makevar>USE_KDE4</makevar> to the list of required
- components. The most commonly used components are listed
- below (up-to-date components are listed in
- <makevar>_USE_KDE4_ALL</makevar> in
+ components. <literal>_build</literal> and <literal>_run</literal>
+ suffixes can be used to force components dependency type
+ (e.g., <literal>baseapps_run</literal>). If no suffix is set,
+ a default dependency type will be used. If you want to force
+ both types, add the component twice with both suffixes
+ (e.g., <literal>automoc4_build automoc4_run</literal>).
+ The most commonly used components are listed below (up-to-date
+ components are documented at the top of
<filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para>
<table frame="none">
- <title>Available KDE4 Components</title>
+ <title>Available KDE 4 Components</title>
<tgroup cols="2">
<thead>
@@ -6354,36 +6357,18 @@
<tbody>
<row>
- <entry><literal>akonadi</literal></entry>
- <entry>Personal information management (PIM) storage
- service</entry>
- </row>
-
- <row>
- <entry><literal>automoc4</literal></entry>
- <entry>Makes port use automoc4 build tool</entry>
- </row>
-
- <row>
- <entry><literal>kdebase</literal></entry>
- <entry>Basic KDE applications (Konqueror, Dolphin,
- Konsole)</entry>
- </row>
-
- <row>
- <entry><literal>kdeexp</literal></entry>
- <entry>Experimental KDE libraries (with non-stable
- API)</entry>
+ <entry><literal>baseapps</literal></entry>
+ <entry>Basic applications for KDE Desktop</entry>
</row>
<row>
<entry><literal>kdehier</literal></entry>
- <entry>Provides common KDE directories</entry>
+ <entry>Hierarchy of common KDE directories</entry>
</row>
<row>
<entry><literal>kdelibs</literal></entry>
- <entry>The base set of KDE libraries</entry>
+ <entry>KDE Developer Platform</entry>
</row>
<row>
@@ -6395,60 +6380,58 @@
<row>
<entry><literal>pimlibs</literal></entry>
- <entry>PIM libraries</entry>
+ <entry>KDE-Pim libraries</entry>
</row>
<row>
<entry><literal>workspace</literal></entry>
- <entry>Applications and libraries which form desktop
- (Plasma, KWin)</entry>
+ <entry>KDE user environments</entry>
+ </row>
+
+ <row>
+ <entry><literal>akonadi</literal></entry>
+ <entry>Storage server for KDE-Pim</entry>
+ </row>
+
+ <row>
+ <entry><literal>automoc4</literal></entry>
+ <entry>Automatic moc for Qt 4 packages</entry>
</row>
</tbody>
</tgroup>
</table>
<para>KDE 4.x ports are installed into
- <literal>${KDE4_PREFIX}</literal>, which is
+ <makevar>KDE4_PREFIX</makevar>, which is
<filename>/usr/local/kde4</filename> currently, to avoid
conflicts with KDE 3.x ports. This is achieved by
specifying the <literal>kdeprefix</literal> component, which
overrides the default <makevar>PREFIX</makevar>. The ports
however respect any <makevar>PREFIX</makevar> set via
<envar>MAKEFLAGS</envar> environment variable and/or
- <application>make</application> arguments.</para>
-
- <para>KDE 4.x ports may conflict with KDE 3.x ports, so when
- the <literal>kdeprefix</literal> component is enabled, they
- are installed in <literal>${KDE4_PREFIX}</literal>.
- The default value of <literal>KDE4_PREFIX</literal> is
- currently <filename>/usr/local/kde4</filename>. Installing
- the KDE 4.x ports into a custom <literal>PREFIX</literal> is
- also possible. When <literal>PREFIX</literal> is set via
- the <envar>MAKEFLAGS</envar> environment variable or via
- <application>make</application> options it overrides the
- value configured by <literal>kdeprefix</literal>.</para>
+ <command>make</command> arguments.</para>
<example id="kde4-components-example">
<title><makevar>USE_KDE4</makevar> Example</title>
- <para>This is a simple example for KDE 4 port.
- <makevar>USE_CMAKE</makevar> instructs port to utilize
+ <para>This is a simple example for a KDE 4 port.
+ <makevar>USE_CMAKE</makevar> instructs the port to utilize
<application>CMake</application> — configuration
tool widely spread among KDE 4 projects.
<makevar>USE_KDE4</makevar> brings dependency on KDE
libraries and makes port using
- <application>automoc4</application> at build stage.
+ <command>automoc4</command> at build stage.
Required KDE components and other dependencies can be
determined through configure log.
<makevar>USE_KDE4</makevar> does not imply
<makevar>USE_QT_VER</makevar>. If a port requires some
- Qt4 components, <makevar>USE_QT_VER</makevar> should be
+ Qt 4 components, <makevar>USE_QT_VER</makevar> should be
set and then needed components can be specified.</para>
<programlisting>USE_CMAKE= yes
-USE_KDE4= automoc4 kdelibs kdeprefix
+USE_KDE4= kdelibs kdeprefix automoc4
USE_QT_VER= 4
-QT_COMPONENTS= qmake_build moc_build rcc_build uic_build</programlisting>
+QT_COMPONENTS= moc_build qmake_build rcc_build uic_build</programlisting>
</example>
</sect2>
</sect1>
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205140833.q4E8XrGQ099781>