[kde-doc-english] [smb4k] doc: Updated handbook.
Alexander Reinholdt
alexander.reinholdt at kdemail.net
Sun Jan 18 15:41:02 UTC 2015
Git commit f927b95d5e1687c1ace3b6de1b7df341f3d6d34e by Alexander Reinholdt.
Committed on 18/01/2015 at 15:28.
Pushed by areinholdt into branch 'master'.
Updated handbook.
M +81 -42 doc/index.docbook
http://commits.kde.org/smb4k/f927b95d5e1687c1ace3b6de1b7df341f3d6d34e
diff --git a/doc/index.docbook b/doc/index.docbook
index 4073d63..3e2194c 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -24,11 +24,11 @@
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
-<year>2005-2014</year>
+<year>2005-2015</year>
<holder>Alexander Reinholdt</holder>
</copyright>
<legalnotice>&underFDL;</legalnotice>
-<date>2014-11-xx</date>
+<date>2015-01-xx</date>
<releaseinfo>5.1.0</releaseinfo>
<abstract>
<para>&smb4k; is an advanced network neighborhood browser and Samba share mounting utility for KDE.</para>
@@ -1391,7 +1391,7 @@
<para>Under NetBSD, &smb4k; is able to run since version 1.2.0. However, some modifications have to be made in order to be able to mount and unmount shares:</para>
<para>Assuming that the prefix of your &kde; installation is <filename class="directory">/usr/pkg</filename>, the following steps have to be taken to make &smb4k; work properly:</para>
<itemizedlist>
- <listitem><para>Configure, compile and install &smb4k; according to the directions given in the <link linkend="appendix_compilation">Compilation and Installation</link> section of the appendix.</para></listitem>
+ <listitem><para>Configure, compile and install &smb4k; according to the directions given in the <link linkend="appendix_compilation">Configuration, Compilation and Installation</link> section of the appendix.</para></listitem>
<listitem><para>After installation, link (or copy) the file <filename>net.sourceforge.smb4k.mounthelper.conf</filename> from the <filename class="directory">examples</filename> directory to the right location:</para>
<para><screen><userinput><prompt>$</prompt> <command>cd</command> <filename class="directory">/usr/pkg/etc/dbus-1/system.d/</filename></userinput>
<userinput><prompt>$</prompt> <command>sudo ln</command> -s \
@@ -1405,7 +1405,6 @@
</sect3>
</sect2>
</sect1>
-
</chapter>
@@ -4416,7 +4415,8 @@ of the &kde; Fundamentals.</para>
<listitem><para>Provide the version of &smb4k; and &kde;.</para></listitem>
<listitem><para>Mention your operating system (&Linux;, FreeBSD, &etc;) and the distribution that is running on your computer.</para></listitem>
<listitem><para>Include the full error message if an error dialog was displayed.</para></listitem>
-<listitem><para>Add additional data, &ie; attach the backtrace if you experienced a crash, send a screen shot if you are reporting a &GUI; related problem, &etc;</para></listitem>
+<listitem><para>If you experienced a crash, attach a full backtrace. For this it is recommended that you (re-)compile &smb4k; with debugging symbols. How this is done is mentioned in the <link linkend="appendix_compilation">Configuration, Compilation and Installation</link> appendix.</para></listitem>
+<listitem><para>Add additional data, ⪚ send a screen shot if you are reporting a &GUI; related problem.</para></listitem>
</itemizedlist>
<para>The recommended method to report a bug is to go to our <ulink url="https://sourceforge.net/p/smb4k/tickets/">bug tracking system</ulink> and fill out the form. But you can also use the dialog that opens when you click the <menuchoice><guimenu>Help</guimenu><guimenuitem>Report Bug...</guimenuitem></menuchoice> menu item.</para>
</chapter>
@@ -4427,7 +4427,7 @@ of the &kde; Fundamentals.</para>
<chapter id="credits" >
<title>Credits and License</title>
-<para>Copyright © 2003 - 2014, Alexander Reinholdt <email>alexander.reinholdt at kdemail.net</email></para>
+<para>Copyright © 2003 - 2015, Alexander Reinholdt <email>alexander.reinholdt at kdemail.net</email></para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
@@ -4454,8 +4454,8 @@ of the &kde; Fundamentals.</para>
<!-- Appendix -->
-<appendix id="appendix_installation" >
-<title>Installation</title>
+<appendix id="appendix">
+ <title>Appendix</title>
<sect1 id="appendix_getting_smb4k" >
<title>How to obtain &smb4k;</title>
@@ -4465,43 +4465,82 @@ of the &kde; Fundamentals.</para>
<sect1 id="appendix_requirements" >
<title>Requirements</title>
-<para>&smb4k; officially supports &Linux; (>= 2.2.x) and FreeBSD (>= 4.10). NetBSD support is experimental. Other Unix systems haven't been tested.</para>
-<para>If you want to compile &smb4k; from source, you need to have &Qt; (version 4.8 or later, but <emphasis role="bold">not</emphasis> &Qt; 5.x) as well as kdelibs (including header files) and kde-runtime (&kde; SC 4.8 or later) installed. For the plasmoid, &kde; SC 4.10 or later is required.</para>
-<para>In order to use &smb4k; successfully, you have to install the Samba software suite (3.x or 4.x, 4.x recommended), &GNU; grep, &GNU; awk or similar, &GNU; sed and the &GNU; findutils. If you are using &Linux;, you also need support of the <filename class="directory">/proc</filename> file system compiled into your kernel.</para>
-<para>To enable full functionality, you should also install rsync.</para>
+<para>&smb4k; officially supports &Linux;, FreeBSD and NetBSD. Other operating systems might work as well, but haven't been tested.</para>
+<para>To compile &smb4k;, you need:</para>
+<itemizedlist>
+ <listitem><para><ulink url="http://www.cmake.org">CMake</ulink> (>= 2.8)</para></listitem>
+ <listitem><para><ulink url="http://gcc.gnu.org">GNU Compiler Collection</ulink> (g++ >= 4.0) or <ulink url="http://clang.llvm.org">clang/LLVM</ulink> (>= 3.0)</para></listitem>
+</itemizedlist>
+<para>&smb4k; depends on the following libraries:</para>
+<itemizedlist>
+ <listitem><para><ulink url="http://www.kde.org">kdelibs and kde-runtime</ulink> (>= 4.8.0 or >= 4.10.0 for the plasmoid)</para></listitem>
+ <listitem><para><ulink url="http://www.qt.io">&Qt;</ulink> (>= 4.8.0, but < 5.x)</para></listitem>
+ <listitem><para>an implementation of the C library</para></listitem>
+</itemizedlist>
+<para>For a proper operation, you also need:</para>
+<itemizedlist>
+ <listitem><para><ulink url="http://www.samba.org">Samba</ulink> (3.x or 4.x, 4.1 recommended)</para></listitem>
+ <listitem><para><ulink url="http://http://www.gnu.org/software/grep/">GNU grep</ulink></para></listitem>
+ <listitem><para><ulink url="http://www.gnu.org/software/gawk/">GNU awk (gawk)</ulink> or similar</para></listitem>
+ <listitem><para><ulink url="http://www.gnu.org/software/sed/">GNU sed</ulink></para></listitem>
+ <listitem><para><ulink url="http://www.gnu.org/software/findutils/">GNU findutils (xargs)</ulink></para></listitem>
+ <listitem><para>Support of the /proc file system compiled into your kernel (&Linux;)</para></listitem>
+</itemizedlist>
+<para>To enable full functionality, you may also want to install these programs:</para>
+<itemizedlist>
+ <listitem><para><ulink url="http://rsync.samba.org">rsync</ulink></para></listitem>
+</itemizedlist>
<para>&smb4k; uses about 20 MB of memory to run, but this may vary depending on your platform and configuration.</para>
-<para>Links to all required libraries and programs as well as &smb4k; itself can be found on <ulink url="http://smb4k.sourceforge.net" >the &smb4k; home page</ulink>.</para>
<para>The list of changes can be found in the <filename>ChangeLog</filename> file.</para>
</sect1>
-<sect1 id="appendix_compilation" >
-<title>Compilation and Installation</title>
-<para>This section describes the configuration, compilation and installation of &smb4k;.</para>
-<orderedlist>
-<listitem><para>Unpack the downloaded source tarball: <screen><prompt>$</prompt> <userinput><command>tar</command> -xvfj smb4k-x.x.x.tar.bz2</userinput></screen> (Replace x.x.x with the version number)</para></listitem>
-<listitem><para>Create a build directory:
-<screen><prompt>$</prompt> <userinput><command>cd</command> smb4k-x.x.x</userinput>
-<prompt>$</prompt> <userinput><command>mkdir</command> build</userinput>
-</screen> (The build directory can have any name you want.)</para></listitem>
-<listitem><para>Change into the build directory: <screen><prompt>$</prompt> <userinput><command>cd</command> build</userinput></screen></para></listitem>
-<listitem><para>Configure the source code with at least the following command:
-<screen><prompt>$</prompt> <userinput><command>cmake</command> -DCMAKE_INSTALL_PREFIX=`<command>kde4-config</command> --prefix` -DCMAKE_BUILD_TYPE=Release ..</userinput></screen>
-If you also want to install &smb4k;'s core header files, add the <option>-DINSTALL_HEADER_FILES=true</option> to the command line. Several more options can be added. Read the <ulink url="http://www.cmake.org/HTML/Documentation.html">cmake documentation</ulink> for more information.</para></listitem>
-<listitem><para>Compile the source code: <screen><prompt>$</prompt> <userinput><command>make</command></userinput></screen></para></listitem>
-<listitem><para>Install the application. Run <screen><prompt>$</prompt> <userinput><command>sudo</command> <command>make</command> install</userinput></screen> in the <filename class="directory">build</filename> directory. If you want to be able to remove &smb4k; with your package manager, install the <application>checkinstall</application> package and run <screen><prompt>$</prompt> <userinput><command>sudo</command> <command>checkinstall</command></userinput></screen> instead.</para></listitem>
-</orderedlist>
-</sect1>
-
-<sect1 id="appendix_debugging">
-<title>Debugging the Source Code</title>
-<para>If you experience crashes or similar and want to debug the source code yourself, compile it with debugging symbols. The procedure is similar to the one described in the <link linkend="appendix_compilation">Compilation and Installation</link> section except that you need to modify the cmake command slightly:</para>
-<screen><prompt>$</prompt> <userinput><command>cmake</command> -DCMAKE_INSTALL_PREFIX=`<command>kde4-config</command> --prefix` -DCMAKE_BUILD_TYPE=Debug ..</userinput></screen>
-<para>Now compile and install the program as stated <link linkend="appendix_compilation">before</link>. If you do not want to
-install but only debug the newly compiled program, you may execute &smb4k; from
-within the source code directory. Change into the <filename role="directory">smb4k</filename> subdirectory and run:</para>
-<screen><prompt>$</prompt> <userinput><command>./smb4k</command> --nofork</userinput></screen>
-<para>If you found the cause for a bug, please let us know. A backtrace or a patch will be much appreciated.</para>
+<sect1 id="appendix_compilation">
+<title>Configuration, Compilation and Installation</title>
+
+<para>This section describes the configuration, compilation and installation of &smb4k;. Make sure, you have read the <link linkend="appendix_requirements">Requirements</link> page before you start.</para>
+<para><ulink url="https://sourceforge.net/projects/smb4k/files">Download</ulink> the version of Smb4K you are interested in and extract the source tarball:</para>
+<para><screen><prompt>$</prompt> <userinput><command>tar</command> xvfJ smb4k-x.y.z.tar.xz</userinput></screen></para>
+<para>Replace x.y.z with the version number. Change into the source code directory and create a <filename class="directory">build</filename> directory:</para>
+<para><screen><prompt>$</prompt> <userinput><command>cd</command> <filename class="directory">smb4k-x.y.z</filename></userinput>
+<prompt>$</prompt> <userinput><command>mkdir</command> <filename class="directory">build</filename></userinput></screen></para>
+<para>Change into the <filename class="directory">build</filename> directory and configure the source code:</para>
+<para><screen><prompt>$</prompt> <userinput><command>cd</command> <filename class="directory">build</filename></userinput>
+<prompt>$</prompt> <userinput><command>cmake</command> -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` -DCMAKE_BUILD_TYPE=Release <filename class="directory">..</filename></userinput></screen></para>
+<para>If you want to compile Smb4K with debug symbols, replace Release by Debug. There are also some &smb4k; specific arguments you might be interested in:</para>
+<para>
+ <informaltable frame="all">
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
+ <thead>
+ <row>
+ <entry>Argument</entry>
+ <entry>Since</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-DINSTALL_HEADER_FILES=yes|no</entry>
+ <entry align="center">1.0.0</entry>
+ <entry>Install the core header files. This is off by default.</entry>
+ </row>
+ <row>
+ <entry>-DINSTALL_PLASMOID=yes|no</entry>
+ <entry align="center">1.1.0</entry>
+ <entry>Install the plasmoid. KDE SC 4.10 or higher is required. This is on by default, if the right KDE version is detected.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+</para>
+<para>After the configuration, compile and install &smb4k;:</para>
+<para><screen><prompt>$</prompt> <userinput><command>make</command> && <command>sudo make</command> install</userinput></screen></para>
+<para>If you want to be able to remove &smb4k; with your package manager later on, use <application>checkinstall</application> instead of <command>make install</command>. The package should be present in your distribution's repository. Run:</para>
+<para><screen><prompt>$</prompt> <userinput><command>make</command> && <command>sudo checkinstall</command></userinput></screen></para>
+<note>
+<para>If you experience a crash or similar and want to either debug &smb4k; yourself or report a bug including a full backtrace, please compile the program with debugging symbols. The procedure is similar to the one described above except that the <application>cmake</application> command has to look like this:</para>
+<screen><prompt>$</prompt> <userinput><command>cmake</command> -DCMAKE_INSTALL_PREFIX=`<command>kde4-config</command> --prefix` -DCMAKE_BUILD_TYPE=debugfull ..</userinput></screen>
+<para>Compile and install the program as stated above. If you found the cause for the bug, please let us <link linkend="reporting_bugs">know</link>.</para>
+</note>
</sect1>
</appendix>
-
-</book>
+</book>
\ No newline at end of file
More information about the kde-doc-english
mailing list