<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>