<div dir="ltr"><div dir="ltr"><div>Hi,</div><div>Yes, the current situation is a mess and something needs to be done.</div><div>Getting rid of man pages just because no one maintains them is a no go IMO.</div><div>I would say help2man would be a preferable flow, if that doesn't yield good results, we can evaluate simplified manually written man pages.</div><div>If you're interested, please pick one or two components and send merge requests.</div><div><br></div><div>Cheers,</div><div>Andre Miranda<br></div><div></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Sep 30, 2020 at 12:06 PM Emanuele Petriglia <<a href="mailto:inbox@emanuelepetriglia.com">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">
<div>
<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>On 29/09/2020 23:58, Simon Steinbeiss
wrote:<br>
</div>
<blockquote type="cite">
<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" target="_blank">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>
<br>
<fieldset></fieldset>
<pre>_______________________________________________
Xfce4-dev mailing list
<a href="mailto:Xfce4-dev@xfce.org" target="_blank">Xfce4-dev@xfce.org</a>
<a href="https://mail.xfce.org/mailman/listinfo/xfce4-dev" target="_blank">https://mail.xfce.org/mailman/listinfo/xfce4-dev</a></pre>
</blockquote>
<pre cols="72">--
Emanuele Petriglia (ema-pe)</pre>
</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></div>