Some thought about man pages

[Emanuele Petriglia]

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)