Some thought about man pages
Emanuele Petriglia
inbox at emanuelepetriglia.com
Wed Sep 30 17:05:14 CEST 2020
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
> <mailto: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 <mailto: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
> <http://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 <http://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 <mailto:Xfce4-dev at xfce.org>
> https://mail.xfce.org/mailman/listinfo/xfce4-dev
>
> _______________________________________________
> Xfce4-dev mailing list
> Xfce4-dev at xfce.org <mailto: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
--
Emanuele Petriglia (ema-pe)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.xfce.org/pipermail/xfce4-dev/attachments/20200930/af49fb0c/attachment.html>
More information about the Xfce4-dev
mailing list