<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <p>Hi,<br>
      <br>
      The problem is when you add a man page, you need to maintain it
      together with the on-line docs. However only command line options
      should be documented in the man pages, and these options don't
      change very often.<br>
      <br>
      Anyway the current situation is a bit messy. Some man pages are
      manually written, some are generated. I found packages (like
      xfwm4) that provide command line options but don't have a man
      page, or it is outdated.<br>
      <br>
      If we want to keep them, I propose to have a standard workflow and
      use a common template. Most of Xfce apps are GUI-oriented, so we
      can write the man page directly in Groff because they are not too
      long.<br>
      <br>
      If you want I can work on this task.</p>
    <p>Have a good day!<br>
    </p>
    <div class="moz-cite-prefix">On 29/09/2020 23:58, Simon Steinbeiss
      wrote:<br>
    </div>
    <blockquote type="cite"
cite="mid:CAApLaz1G66UMvvygdXtqWJ1QKVdqu9HhS5yNm+MZQCEOpkt3vQ@mail.gmail.com">
      <meta http-equiv="content-type" content="text/html; charset=UTF-8">
      <div dir="ltr">
        <div>Hi everyone,</div>
        <div><br>
        </div>
        <div>to me it's not an "either or". In my view man pages are for
          commandline tools whereas online documentation can also cover
          things that are implemented in a UI.</div>
        <div>Obviously that online documentation can also cover things
          that are in a man page, but I also wouldn't replace the man
          pages with online docs.</div>
        <div><br>
        </div>
        <div>So yeah, I'd also go wit AndrĂ©'s suggestion. Adding a link
          to our docs probably doesn't hurt (although in theory this
          should be a versioned link, as with the "Help" buttons in many
          of our settings dialogs).</div>
        <div><br>
        </div>
        <div>Cheers</div>
        <div>Simon<br>
        </div>
        <div><br>
        </div>
      </div>
      <br>
      <div class="gmail_quote">
        <div dir="ltr" class="gmail_attr">On Tue, Sep 29, 2020 at 11:39
          PM AndrĂ© Miranda <<a href="mailto:andre42m@gmail.com"
            moz-do-not-send="true">andre42m@gmail.com</a>> wrote:<br>
        </div>
        <blockquote class="gmail_quote" style="margin:0px 0px 0px
          0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
          <div dir="ltr">
            <div dir="ltr">
              <div>Hi,</div>
              <div>I wasn't around during 4.10 times, so I can't tell
                for sure what Nick really meant, but I suspect the idea
                was to drop documentation that was rendered into html
                and pdf files, not exactly man pages.</div>
              <div>My take is: keep man pages simple, short, with quick
                explanations of available options and at the bottom a
                link to full documentation.</div>
            </div>
            <div><br>
            </div>
            <div>Cheers,</div>
            <div>Andre Miranda<br>
            </div>
            <div><br>
            </div>
            <div class="gmail_quote">
              <div dir="ltr" class="gmail_attr">On Tue, Sep 29, 2020 at
                9:28 AM Emanuele Petriglia <<a
                  href="mailto:inbox@emanuelepetriglia.com"
                  target="_blank" moz-do-not-send="true">inbox@emanuelepetriglia.com</a>>
                wrote:<br>
              </div>
              <blockquote class="gmail_quote" style="margin:0px 0px 0px
                0.8ex;border-left:1px solid
                rgb(204,204,204);padding-left:1ex">Hello everyone!<br>
                <br>
                Since Xfce 4.10, the Xfce developers and contributors
                deprecated all man <br>
                pages in favour of online documentation[23] (<a
                  href="http://docs.xfce.org" rel="noreferrer"
                  target="_blank" moz-do-not-send="true">docs.xfce.org</a>).
                However, I <br>
                have noticed that some applications still have a man
                page, usually old, <br>
                and have different methods of being created. I would be
                interested in <br>
                working on improving the consistency in the existing man
                pages. I found <br>
                the following components still have man pages:<br>
                <br>
                * xfdesktop[1] (a)<br>
                * xfce4-session[2] (a)<br>
                * xfce4-session-logout[3] (a)<br>
                * xfce4-power-manager[4] (b)<br>
                * xdt-csource[5] (b)<br>
                * thunar[6] (b)<br>
                * exo-open[7] (b) (latest commit 10 years ago!)<br>
                * xfce4-whiskermenu-plugin[8] (a)<br>
                * xfce4-sensors-plugin[9] (a)<br>
                * xfce4-screensaver-command[10] (a)<br>
                * xfce4-screensaver-preferences[11] (a)<br>
                * xfce4-screensaver[12] (a)<br>
                * xfmpc[13] (a) (latest commit 11 year ago!)<br>
                * xfce4-terminal[14] (b)<br>
                * xfce4-screenshooter[15] (c) (the maintainer generated
                it, but it <br>
                should generated during configuration)<br>
                * xfce4-panel-profiles[16] (a)<br>
                * xfce4-notifyd-config[17] (a) (it was created by a
                Debian contributor)<br>
                * xfce4-mixer[18] (a)<br>
                * xfce4-dict[19] (a)<br>
                * xfburn[20] (b)<br>
                * gigolo[21] (a)<br>
                * catfish[22] (a)<br>
                <br>
                (a): manually written in groff<br>
                (b): docbook<br>
                (c): help2man<br>
                <br>
                The result is: 15 man pages are manually written, 6 are
                generated with <br>
                docbook, one is generated with help2man, but it is not
                configured <br>
                properly. All of the remaining packages, not listed, do
                not have a man page.<br>
                <br>
                I would like to improve the consistency in the existing
                Xfce <br>
                documentation by starting to handle these man pages. So
                I propose a <br>
                solution. For every Xfce package:<br>
                <br>
                1. If the package has a man page, remove it;<br>
                2. Add a basic man page that simply redirects to the
                on-line <br>
                documentation (because some operating systems, like
                Debian, always <br>
                require a man page);<br>
                3. If the package provides command line options,
                document these options <br>
                on <a href="http://docs.xfce.org" rel="noreferrer"
                  target="_blank" moz-do-not-send="true">docs.xfce.org</a>.<br>
                <br>
                The result is that every Xfce package (not only those
                have a man page) <br>
                will have a basic man pages that redirect to the
                up-to-date on-line <br>
                documentation, so the maintainer doesn't need to take
                care of all man <br>
                pages. If the user opens a man page, it is encouraged to
                view the <br>
                on-line documentation, but in the future I would like to
                allow to <br>
                download a offline copy (maybe with a dokuwiki plugin?).<br>
                <br>
                I have done some experiments with my solution on
                xfce4-screenshooter[24] <br>
                and xfce4-panel-profiles[25] development branch. Please
                review the <br>
                template[26] I want to apply to all packages, changing
                only the <br>
                necessary strings (like name, description and URLs).<br>
                <br>
                If you like this proposal, I can start to work to fix
                all packages :)<br>
                <br>
                Have a good day!<br>
                <br>
                [0]: <a href="https://www.gnu.org/software/help2man/"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://www.gnu.org/software/help2man/</a><br>
                [1]: <a
                  href="https://gitlab.xfce.org/xfce/xfdesktop/-/blob/master/xfdesktop.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/xfdesktop/-/blob/master/xfdesktop.1</a><br>
                [2]: <br>
                <a
href="https://gitlab.xfce.org/xfce/xfce4-session/-/blob/master/xfce4-session/xfce4-session.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/xfce4-session/-/blob/master/xfce4-session/xfce4-session.1</a><br>
                [3]: <br>
                <a
href="https://gitlab.xfce.org/xfce/xfce4-session/-/blob/master/xfce4-session-logout/xfce4-session-logout.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/xfce4-session/-/blob/master/xfce4-session-logout/xfce4-session-logout.1</a><br>
                [4]: <br>
                <a
href="https://gitlab.xfce.org/xfce/xfce4-power-manager/-/blob/master/data/appdata/xfce4-power-manager.appdata.xml.in"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/xfce4-power-manager/-/blob/master/data/appdata/xfce4-power-manager.appdata.xml.in</a><br>
                [5]: <br>
                <a
href="https://gitlab.xfce.org/xfce/xfce4-dev-tools/-/blob/master/docs/xdt-csource.xml"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/xfce4-dev-tools/-/blob/master/docs/xdt-csource.xml</a><br>
                [6]: <a
                  href="https://gitlab.xfce.org/xfce/thunar/-/blob/master/docs/Thunar.xml"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/thunar/-/blob/master/docs/Thunar.xml</a><br>
                [7]: <br>
                <a
href="https://gitlab.xfce.org/xfce/exo/-/blob/master/docs/reference/exo-open.xml"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/xfce/exo/-/blob/master/docs/reference/exo-open.xml</a><br>
                [8]: <br>
                <a
href="https://gitlab.xfce.org/panel-plugins/xfce4-whiskermenu-plugin/-/blob/master/panel-plugin/xfce4-popup-whiskermenu.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/panel-plugins/xfce4-whiskermenu-plugin/-/blob/master/panel-plugin/xfce4-popup-whiskermenu.1</a><br>
                [9]: <br>
                <a
href="https://gitlab.xfce.org/panel-plugins/xfce4-sensors-plugin/-/blob/master/src/xfce4-sensors.1.in"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/panel-plugins/xfce4-sensors-plugin/-/blob/master/src/xfce4-sensors.1.in</a><br>
                [10]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver-command.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver-command.1</a><br>
                [11]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver-preferences.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver-preferences.1</a><br>
                [12]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver.1</a><br>
                [13]: <a
                  href="https://gitlab.xfce.org/apps/xfmpc/-/blob/master/xfmpc.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfmpc/-/blob/master/xfmpc.1</a><br>
                [14]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-terminal/-/blob/master/doc/xfce4-terminal.xml"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-terminal/-/blob/master/doc/xfce4-terminal.xml</a><br>
                [15]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-screenshooter/-/blob/master/xfce4-screenshooter.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-screenshooter/-/blob/master/xfce4-screenshooter.1</a><br>
                [16]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-panel-profiles/-/blob/master/xfce4-panel-profiles.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-panel-profiles/-/blob/master/xfce4-panel-profiles.1</a><br>
                [17]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-notifyd/-/blob/master/xfce4-notifyd-config/xfce4-notifyd-config.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-notifyd/-/blob/master/xfce4-notifyd-config/xfce4-notifyd-config.1</a><br>
                [18]: <br>
                <a
href="https://gitlab.xfce.org/apps/xfce4-mixer/-/blob/master/xfce4-mixer/xfce4-mixer.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-mixer/-/blob/master/xfce4-mixer/xfce4-mixer.1</a><br>
                [19]: <a
href="https://gitlab.xfce.org/apps/xfce4-dict/-/blob/master/xfce4-dict.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfce4-dict/-/blob/master/xfce4-dict.1</a><br>
                [20]: <a
                  href="https://gitlab.xfce.org/apps/xfburn/-/blob/master/docs/xfburn.xml"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/xfburn/-/blob/master/docs/xfburn.xml</a><br>
                [21]: <a
                  href="https://gitlab.xfce.org/apps/gigolo/-/blob/master/gigolo.1.in"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/gigolo/-/blob/master/gigolo.1.in</a><br>
                [22]: <a
                  href="https://gitlab.xfce.org/apps/catfish/-/blob/master/catfish.1"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/apps/catfish/-/blob/master/catfish.1</a><br>
                [23]: <a
                  href="https://docs.xfce.org/contribute/documentation"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://docs.xfce.org/contribute/documentation</a><br>
                [24]: <br>
                <a
href="https://gitlab.xfce.org/ema-pe/xfce4-screenshooter/-/commit/640f94ab9b9525e0b3ff040d91b88e684155ab33"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/ema-pe/xfce4-screenshooter/-/commit/640f94ab9b9525e0b3ff040d91b88e684155ab33</a><br>
                [25]: <br>
                <a
href="https://gitlab.xfce.org/ema-pe/xfce4-panel-profiles/-/commit/ae2e1de41a04843ac415671b84f27d6698aad79e"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/ema-pe/xfce4-panel-profiles/-/commit/ae2e1de41a04843ac415671b84f27d6698aad79e</a><br>
                [26]: <br>
                <a
href="https://gitlab.xfce.org/ema-pe/xfce4-screenshooter/-/blob/640f94ab9b9525e0b3ff040d91b88e684155ab33/xfce4-screenshooter.1.in"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://gitlab.xfce.org/ema-pe/xfce4-screenshooter/-/blob/640f94ab9b9525e0b3ff040d91b88e684155ab33/xfce4-screenshooter.1.in</a>
                <br>
                <br>
                <br>
                -- <br>
                Emanuele Petriglia (ema-pe)<br>
                <br>
                _______________________________________________<br>
                Xfce4-dev mailing list<br>
                <a href="mailto:Xfce4-dev@xfce.org" target="_blank"
                  moz-do-not-send="true">Xfce4-dev@xfce.org</a><br>
                <a
                  href="https://mail.xfce.org/mailman/listinfo/xfce4-dev"
                  rel="noreferrer" target="_blank"
                  moz-do-not-send="true">https://mail.xfce.org/mailman/listinfo/xfce4-dev</a></blockquote>
            </div>
          </div>
          _______________________________________________<br>
          Xfce4-dev mailing list<br>
          <a href="mailto:Xfce4-dev@xfce.org" target="_blank"
            moz-do-not-send="true">Xfce4-dev@xfce.org</a><br>
          <a href="https://mail.xfce.org/mailman/listinfo/xfce4-dev"
            rel="noreferrer" target="_blank" moz-do-not-send="true">https://mail.xfce.org/mailman/listinfo/xfce4-dev</a></blockquote>
      </div>
      <br>
      <fieldset class="mimeAttachmentHeader"></fieldset>
      <pre class="moz-quote-pre" wrap="">_______________________________________________
Xfce4-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Xfce4-dev@xfce.org">Xfce4-dev@xfce.org</a>
<a class="moz-txt-link-freetext" href="https://mail.xfce.org/mailman/listinfo/xfce4-dev">https://mail.xfce.org/mailman/listinfo/xfce4-dev</a></pre>
    </blockquote>
    <pre class="moz-signature" cols="72">-- 
Emanuele Petriglia (ema-pe)</pre>
  </body>
</html>