<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
Hi,<br>
<br>
<p>I've done some tests with help2man but it doesn't fit very good
with Xfce applications. A this point I prefer to write a basic man
page with only these information: the app's name, description and
available command line options, lastly a link to the on-line
documentation. I'll try to send some merge request in the next
weeks!</p>
<p>Have a good day!<br>
</p>
<div class="moz-cite-prefix">On 02/10/2020 01:07, André Miranda
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CAHdpay+zCgO4qS-H0PTH2nrQzAXam+g83bYvTEJwL5PeqsAwdg@mail.gmail.com">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<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>
<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"
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">
<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"
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></fieldset>
<pre>_______________________________________________
Xfce4-dev mailing list
<a href="mailto:Xfce4-dev@xfce.org" target="_blank" moz-do-not-send="true">Xfce4-dev@xfce.org</a>
<a href="https://mail.xfce.org/mailman/listinfo/xfce4-dev" target="_blank" moz-do-not-send="true">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"
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>
<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>