Some thought about man pages

Tue Sep 29 23:58:45 CEST 2020

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.xfce.org/pipermail/xfce4-dev/attachments/20200929/39e7e4bd/attachment.html>