Some thought about man pages

[André Miranda]

Hi,
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.
My take is: keep man pages simple, short, with quick explanations of
available options and at the bottom a link to full documentation.

Cheers,
Andre Miranda

On Tue, Sep 29, 2020 at 9:28 AM Emanuele Petriglia <
inbox at emanuelepetriglia.com> wrote:

> Hello everyone!
>
> Since Xfce 4.10, the Xfce developers and contributors deprecated all man
> pages in favour of online documentation[23] (docs.xfce.org). However, I
> have noticed that some applications still have a man page, usually old,
> and have different methods of being created. I would be interested in
> working on improving the consistency in the existing man pages. I found
> the following components still have man pages:
>
> * xfdesktop[1] (a)
> * xfce4-session[2] (a)
> * xfce4-session-logout[3] (a)
> * xfce4-power-manager[4] (b)
> * xdt-csource[5] (b)
> * thunar[6] (b)
> * exo-open[7] (b) (latest commit 10 years ago!)
> * xfce4-whiskermenu-plugin[8] (a)
> * xfce4-sensors-plugin[9] (a)
> * xfce4-screensaver-command[10] (a)
> * xfce4-screensaver-preferences[11] (a)
> * xfce4-screensaver[12] (a)
> * xfmpc[13] (a) (latest commit 11 year ago!)
> * xfce4-terminal[14] (b)
> * xfce4-screenshooter[15] (c) (the maintainer generated it, but it
> should generated during configuration)
> * xfce4-panel-profiles[16] (a)
> * xfce4-notifyd-config[17] (a) (it was created by a Debian contributor)
> * xfce4-mixer[18] (a)
> * xfce4-dict[19] (a)
> * xfburn[20] (b)
> * gigolo[21] (a)
> * catfish[22] (a)
>
> (a): manually written in groff
> (b): docbook
> (c): help2man
>
> The result is: 15 man pages are manually written, 6 are generated with
> docbook, one is generated with help2man, but it is not configured
> properly. All of the remaining packages, not listed, do not have a man
> page.
>
> I would like to improve the consistency in the existing Xfce
> documentation by starting to handle these man pages. So I propose a
> solution. For every Xfce package:
>
> 1. If the package has a man page, remove it;
> 2. Add a basic man page that simply redirects to the on-line
> documentation (because some operating systems, like Debian, always
> require a man page);
> 3. If the package provides command line options, document these options
> on docs.xfce.org.
>
> The result is that every Xfce package (not only those have a man page)
> will have a basic man pages that redirect to the up-to-date on-line
> documentation, so the maintainer doesn't need to take care of all man
> pages. If the user opens a man page, it is encouraged to view the
> on-line documentation, but in the future I would like to allow to
> download a offline copy (maybe with a dokuwiki plugin?).
>
> I have done some experiments with my solution on xfce4-screenshooter[24]
> and xfce4-panel-profiles[25] development branch. Please review the
> template[26] I want to apply to all packages, changing only the
> necessary strings (like name, description and URLs).
>
> If you like this proposal, I can start to work to fix all packages :)
>
> Have a good day!
>
> [0]: https://www.gnu.org/software/help2man/
> [1]: https://gitlab.xfce.org/xfce/xfdesktop/-/blob/master/xfdesktop.1
> [2]:
>
> https://gitlab.xfce.org/xfce/xfce4-session/-/blob/master/xfce4-session/xfce4-session.1
> [3]:
>
> https://gitlab.xfce.org/xfce/xfce4-session/-/blob/master/xfce4-session-logout/xfce4-session-logout.1
> [4]:
>
> https://gitlab.xfce.org/xfce/xfce4-power-manager/-/blob/master/data/appdata/xfce4-power-manager.appdata.xml.in
> [5]:
>
> https://gitlab.xfce.org/xfce/xfce4-dev-tools/-/blob/master/docs/xdt-csource.xml
> [6]: https://gitlab.xfce.org/xfce/thunar/-/blob/master/docs/Thunar.xml
> [7]:
> https://gitlab.xfce.org/xfce/exo/-/blob/master/docs/reference/exo-open.xml
> [8]:
>
> https://gitlab.xfce.org/panel-plugins/xfce4-whiskermenu-plugin/-/blob/master/panel-plugin/xfce4-popup-whiskermenu.1
> [9]:
>
> https://gitlab.xfce.org/panel-plugins/xfce4-sensors-plugin/-/blob/master/src/xfce4-sensors.1.in
> [10]:
>
> https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver-command.1
> [11]:
>
> https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver-preferences.1
> [12]:
>
> https://gitlab.xfce.org/apps/xfce4-screensaver/-/blob/master/data/xfce4-screensaver.1
> [13]: https://gitlab.xfce.org/apps/xfmpc/-/blob/master/xfmpc.1
> [14]:
>
> https://gitlab.xfce.org/apps/xfce4-terminal/-/blob/master/doc/xfce4-terminal.xml
> [15]:
>
> https://gitlab.xfce.org/apps/xfce4-screenshooter/-/blob/master/xfce4-screenshooter.1
> [16]:
>
> https://gitlab.xfce.org/apps/xfce4-panel-profiles/-/blob/master/xfce4-panel-profiles.1
> [17]:
>
> https://gitlab.xfce.org/apps/xfce4-notifyd/-/blob/master/xfce4-notifyd-config/xfce4-notifyd-config.1
> [18]:
>
> https://gitlab.xfce.org/apps/xfce4-mixer/-/blob/master/xfce4-mixer/xfce4-mixer.1
> [19]: https://gitlab.xfce.org/apps/xfce4-dict/-/blob/master/xfce4-dict.1
> [20]: https://gitlab.xfce.org/apps/xfburn/-/blob/master/docs/xfburn.xml
> [21]: https://gitlab.xfce.org/apps/gigolo/-/blob/master/gigolo.1.in
> [22]: https://gitlab.xfce.org/apps/catfish/-/blob/master/catfish.1
> [23]: https://docs.xfce.org/contribute/documentation
> [24]:
>
> https://gitlab.xfce.org/ema-pe/xfce4-screenshooter/-/commit/640f94ab9b9525e0b3ff040d91b88e684155ab33
> [25]:
>
> https://gitlab.xfce.org/ema-pe/xfce4-panel-profiles/-/commit/ae2e1de41a04843ac415671b84f27d6698aad79e
> [26]:
>
> https://gitlab.xfce.org/ema-pe/xfce4-screenshooter/-/blob/640f94ab9b9525e0b3ff040d91b88e684155ab33/xfce4-screenshooter.1.in
>
>
> --
> Emanuele Petriglia (ema-pe)
>
> _______________________________________________
> Xfce4-dev mailing list
> Xfce4-dev at xfce.org
> https://mail.xfce.org/mailman/listinfo/xfce4-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.xfce.org/pipermail/xfce4-dev/attachments/20200929/4d7b5d0f/attachment-0001.html>