[network/smb4k] doc: Update handbook.

Alexander Reinholdt null at kde.org
Tue Feb 7 17:40:29 GMT 2023


Git commit c24c547e3faf4db20bf15a8884a33fb4c2dc46a4 by Alexander Reinholdt.
Committed on 07/02/2023 at 17:40.
Pushed by areinholdt into branch 'master'.

Update handbook.

M  +52   -20   doc/index.docbook

https://invent.kde.org/network/smb4k/commit/c24c547e3faf4db20bf15a8884a33fb4c2dc46a4

diff --git a/doc/index.docbook b/doc/index.docbook
index 0420ed52..2ef4b3a0 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -101,17 +101,7 @@
     
     <para>You can either launch &smb4k; from the K menu or from <ulink url="https://userbase.kde.org/Plasma/Krunner">&krunner;</ulink> by typing <userinput><command>smb4k</command></userinput>. &smb4k; comes with a <link linkend="plasmoid">&plasmoid;</link> for better desktop integration. It can be added as a widget to the desktop or panel.</para>
 
-    <para>If the system is missing some of the programs &smb4k; needs to operate properly, it notifies the user:</para>
-    
-    <screenshot id="notification_missing_program">
-      <screeninfo>Screenshot of the missing program notification</screeninfo>
-      <mediaobject>
-        <imageobject><imagedata fileref="notification_missing_program.png" format="PNG" /></imageobject>
-        <textobject><phrase>The missing program notification</phrase></textobject>
-      </mediaobject>
-    </screenshot>
-    
-    <para>In this case, please install the specified program or, if it is already present, add its location to the <envar>PATH</envar> environment variable in your shell's configuration file (for the <ulink url="man:/bash"><citerefentry><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink> shell it is the <filename>~/.bashrc</filename> file).</para>
+    <para>If &smb4k; encounters a problem on start-up or while running, the user will be notified. For the solution of some common problems see the <link linkend="trouble_shooting">Trouble Shooting</link> section.</para>
   </sect1>
 
 <!-- 
@@ -1417,17 +1407,59 @@
   </sect1>
 
 <!-- 
-      Using Smb4K : Special Remarks 
+      Using Smb4K : Trouble Shooting
 -->
 
-  <sect1 id="special_remarks">
-    <title>Special Remarks</title>
+  <sect1 id="trouble_shooting">
+    <title>Trouble Shooting</title>
+
+<!--
+    Using Smb4K : Trouble Shooting : Missing Programs
+    -->
+
+    <sect2 id="trouble_shooting_missing_programs">
+      <title>Missing Programs</title>
+
+      <para>If the system is missing some of the programs &smb4k; needs to operate properly, it notifies the user:</para>
+
+      <screenshot id="notification_missing_program">
+        <screeninfo>Screenshot of the missing program notification</screeninfo>
+        <mediaobject>
+          <imageobject><imagedata fileref="notification_missing_program.png" format="PNG" /></imageobject>
+          <textobject><phrase>The missing program notification</phrase></textobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>In this case, please install the specified program or, if it is already present, add its location to the <envar>PATH</envar> environment variable in your shell's configuration file (for the <ulink url="man:/bash"><citerefentry><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink> shell it is the <filename>~/.bashrc</filename> file).</para>
+    </sect2>
+
+<!--
+    Using Smb4K : Trouble Shooting : Zeroconf Daemon
+    -->
+
+    <sect2 id="trouble_shooting_zeroconf">
+      <title>Zeroconf Daemon Not Running</title>
+
+      <para>&smb4k; uses the Zeroconf service (<application><ulink url="https://avahi.org">Avahi</ulink></application>) to look up servers and shares in the network neighborhood using DNS Service Discovery (DNS-SD). For this to work, the Avahi daemon must be enabled and running on your system. If this is not the case, &smb4k; shows an error message:</para>
+
+      <screenshot id="notification_zeroconf_error">
+        <screeninfo>Screenshot of the Zeroconf error notification</screeninfo>
+        <mediaobject>
+          <imageobject><imagedata fileref="notification_zeroconf_error.png" format="PNG" /></imageobject>
+          <textobject><phrase>The Zeroconf error notification</phrase></textobject>
+        </mediaobject>
+      </screenshot>
+
+      <para>In most cases, the Avahi daemon is not running when an error is reported. Under those &Linux; distributions that use <application>systemd</application> you can start it by running the following or a similar command from the terminal:</para>
+      <para><screen><userinput><prompt>$</prompt> <command>sudo</command> <command>systemctl</command> enable --now avahi-daemon</userinput></screen></para>
+      <para>With all other &Linux; distributions and under BSD refer to the specific documentation how to start the Avahi daemon.</para>
+    </sect2>
   
 <!--
-    Using Smb4K : Special Remarks : Denied Privilege Escalation
+    Using Smb4K : Trouble Shooting : Denied Privilege Escalation
 -->
     
-    <sect2 id="special_remarks_polkit-1">
+    <sect2 id="trouble_shooting_polkit-1">
       <title>Denied Privilege Escalation</title>
       
       <para>In case the mount and unmount actions fail (most likely with an <guilabel>AuthorizationDeniedError</guilabel> message), your polkit-1 setup might need to be adjusted: Add a file, ⪚ named <filename>10-mounthelper.rules</filename>, to the <filename class="directory">$PREFIX/etc/polkit-1/rules.d/</filename> directory with the following content:</para>
@@ -1450,10 +1482,10 @@ polkit.addRule(function(action, subject) {
     </sect2>
   
 <!--
-      Using Smb4K : Special Remarks : Mounting Problems under BSD
+      Using Smb4K : Trouble Shooting : Mounting Problems under BSD
   -->
     
-    <sect2 id="special_remarks_mounting_problems_under_bsd">
+    <sect2 id="trouble_shooting_mounting_problems_under_bsd">
       <title>Mounting Problems Under BSD</title>
       
       <para>If mounting of password-protected shares from either a &Samba; or a &Windows; server fails, this might be because <ulink url="man:/mount_smbfs"><citerefentry><refentrytitle>mount_smbfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></ulink> only uses NTLMv1 authentication, and the server does not support it. To fix mounting for a &Samba; server, you can add the following entry to the [global] section of the <filename>smb.conf</filename> file of <emphasis>the server</emphasis>:</para>
@@ -1468,10 +1500,10 @@ ntlm auth = yes
     </sect2>
     
 <!-- 
-      Using Smb4K : Special Remarks : Other Desktops Than Plasma
+      Using Smb4K : Trouble Shooting : Other Desktops Than Plasma
 -->
 
-    <sect2 id="special_remarks_other_desktop_environments">
+    <sect2 id="trouble_shooting_other_desktop_environments">
       <title>Other Desktop Environments Than &plasma;</title>
 
       <para>When using a different desktop environment than &plasma;, &Qt; and &kf5; applications might be missing some icons. In that case, you might want to install the application <application>qt5ct</application> (the source code can be obtained <ulink url="https://sourceforge.net/projects/qt5ct/">here</ulink>). To use <application>qt5ct</application> with your desktop environment, add the following line to your <filename>~/.xinitrc</filename> or <filename>~/.profile</filename> file:</para>


More information about the kde-doc-english mailing list