<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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">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">Xfce4-dev@xfce.org</a><br>
<a href="https://mail.xfce.org/mailman/listinfo/xfce4-dev" rel="noreferrer" target="_blank">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">Xfce4-dev@xfce.org</a><br>
<a href="https://mail.xfce.org/mailman/listinfo/xfce4-dev" rel="noreferrer" target="_blank">https://mail.xfce.org/mailman/listinfo/xfce4-dev</a></blockquote></div>