Some thought about man pages

Fri Oct 2 01:07:46 CEST 2020

Hi,
Yes, the current situation is a mess and something needs to be done.
Getting rid of man pages just because no one maintains them is a no go IMO.
I would say help2man would be a preferable flow, if that doesn't yield good
results, we can evaluate simplified manually written man pages.
If you're interested, please pick one or two components and send merge
requests.

Cheers,
Andre Miranda

On Wed, Sep 30, 2020 at 12:06 PM Emanuele Petriglia <
inbox at emanuelepetriglia.com> wrote:

> Hi,
>
> 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.
>
> 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.
>
> 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.
>
> If you want I can work on this task.
>
> Have a good day!
> On 29/09/2020 23:58, Simon Steinbeiss wrote:
>
> Hi everyone,
>
> 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.
> 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.
>
> 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).
>
> Cheers
> Simon
>
>
> On Tue, Sep 29, 2020 at 11:39 PM André Miranda <andre42m at gmail.com> wrote:
>
>> Hi,
>> 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.
>> My take is: keep man pages simple, short, with quick explanations of
>> available options and at the bottom a link to full documentation.
>>
>> Cheers,
>> Andre Miranda
>>
>> On Tue, Sep 29, 2020 at 9:28 AM Emanuele Petriglia <
>> inbox at emanuelepetriglia.com> wrote:
>>
>>> 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)
>>>
>>> _______________________________________________
>>> Xfce4-dev mailing list
>>> Xfce4-dev at xfce.org
>>> https://mail.xfce.org/mailman/listinfo/xfce4-dev
>>
>> _______________________________________________
>> Xfce4-dev mailing list
>> Xfce4-dev at xfce.org
>> https://mail.xfce.org/mailman/listinfo/xfce4-dev
>
>
> _______________________________________________
> Xfce4-dev mailing listXfce4-dev at xfce.orghttps://mail.xfce.org/mailman/listinfo/xfce4-dev
>
> --
> Emanuele Petriglia (ema-pe)
>
> _______________________________________________
> Xfce4-dev mailing list
> Xfce4-dev at xfce.org
> https://mail.xfce.org/mailman/listinfo/xfce4-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.xfce.org/pipermail/xfce4-dev/attachments/20201001/ffe61d0c/attachment-0001.html>