Some thought about man pages
Emanuele Petriglia
inbox at emanuelepetriglia.com
Fri Oct 2 15:17:24 CEST 2020
Hi,
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!
Have a good day!
On 02/10/2020 01:07, André Miranda wrote:
> 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 <mailto: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 <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 <mailto:Xfce4-dev at xfce.org>
>> https://mail.xfce.org/mailman/listinfo/xfce4-dev
>
> --
> 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
> 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/20201002/e27da3d0/attachment-0001.html>
More information about the Xfce4-dev
mailing list