Man pages in cloud images - documentation

[Gergely Gombos]

Hello,

I just installed a F28 image on a Scaleway cloud server. Runs fine, except there were no
man pages, even after installing man-pages package.

It turned out after a lot of searching that this is not a bug but a feature.

Issue on GitHub:
https://github.com/fedora-cloud/docker-brew-fedora/issues/9#issuecomment-...

So the culprit is the Kickstarts file, here:
https://pagure.io/fedora-kickstarts/blob/master/f/fedora-docker-common.ks... (and other
nearby .ks files)
It says "%packages --excludedocs --instLangs=en --nocore  [...]"

According to the Kickstart docs
(http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#chapter-4...)
this won't install man pages, presumably to save space, but the end user won't
know this, because man will simply not find any man pages and that's it.

A solution was to edit /etc/dnf/dnf.conf, comment "tsflags=nodocs" and then
reinstall everything with dnf reinstall.

My question: I understand that it's important to save space with containers, but often
cloud users wish to use man pages, as they are using the cloud server just as any remote
computer. Is there a way to document the above situation e.g. when the user tries to view
a man page gets a notification about why they are not installed (and how to install
them)?

Thanks!
Best regards,
Greg Gombos

[Dusty Mabe]

On 06/28/2018 05:38 AM, Gergely Gombos wrote:
>  Hello, 
Hi Greg,

>  
>  I just installed a F28 image on a Scaleway cloud server. Runs fine, except there were no
> man pages, even after installing man-pages package.
>  
>  It turned out after a lot of searching that this is not a bug but a feature.
>  
>  Issue on GitHub:
> https://github.com/fedora-cloud/docker-brew-fedora/issues/9#issuecomment-...
>  
>  So the culprit is the Kickstarts file, here:
> https://pagure.io/fedora-kickstarts/blob/master/f/fedora-docker-common.ks... (and other
> nearby .ks files)
>  It says "%packages --excludedocs --instLangs=en --nocore  [...]"
>  
>  According to the Kickstart docs
> (http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#chapter-4...)
> this won't install man pages, presumably to save space, but the end user won't
> know this, because man will simply not find any man pages and that's it.
>  
>  A solution was to edit /etc/dnf/dnf.conf, comment "tsflags=nodocs" and then
> reinstall everything with dnf reinstall.
>  
>  My question: I understand that it's important to save space with containers, but
> often cloud users wish to use man pages, as they are using the cloud server just as any
> remote computer. Is there a way to document the above situation e.g. when the user tries
> to view a man page gets a notification about why they are not installed (and how to
> install them)? 
This is subjective to who you are, but here is my opinion. A "Cloud" server is
usually one that is spun up and provisioned automatically (i.e. a person does
not SSH into the machine to configure it). The cloud instance has a specific
purpose and can be thrown away easily and re-provisioned. In this scenario docs
are wasted space and people generally value smaller image size over having the
documentation.

Now there are certainly cases where you just spin up a cloud instance and want
to configure it yourself, but that's not what we're optimizing for. It would be
nice if 'man' were able to detect this situation and offer an alternative. Maybe
open an RFE BZ against man for this??

- Dusty

[Gergely Gombos]

Hi Dusty,

Yes, I understand your point. Cloud images are usually spun up and provisioned
automatically by cloud service providers, but they are often used as regular remote
machines by end users.
E.g. Scaleway offers a selection of "curated" cloud images for their servers
(for Fedora: https://github.com/scaleway/image-fedora) that the user can choose from,
which have been tested and customized with their provisioning scripts. Which is not
without issues but they sort them out at GitHub.
From an end-user perspective though, even if I was provisioning the server through some
automatic tool like Terraform (https://www.terraform.io/), I expect the operating system
to be working just as a regular Fedora system would. Even if it's a stripped-down
minimal version, I could install anything necessary for my tasks.
That's why I'm using Fedora in the first place, because it's familiar and
contains the latest necessary software.
The problem with the missing man pages from an end-user perspective:
This seems to be a bug at first glance (at first I thought it's a Scaleway deployment
issue)

It's not documented inside the image

It's not documented outside of the image in some official documentation

For an experienced user, a warning message would sufficient to know where to look at least
- to know why this is happening and how to solve the situation if necessary.

This wouldn't be the responsibility of the man software (in package man-db) because
this is package manager stuff.
So my solution proposal:
I'm going to create PRs to add this piece of info to the Scaleway Fedora
(https://github.com/scaleway/image-fedora), Docker Brew
(https://github.com/fedora-cloud/docker-brew-fedora), and possibly Docker library
(https://hub.docker.com/_/fedora/) readmes. Just a warning that documentation has been
permanently turned off, referencing to this discussion:
https://github.com/fedora-cloud/docker-brew-fedora/issues/9
I'll create an RFE for DNF (instead of man) - to show a warning when tsflags have been
set. Even something like: "Current transaction flags: [...]" would be
sufficient. This at least informs the user about the configuration.
What do you think?

Best regards,
Greg

On jún 28 2018, at 3:03 du, Dusty Mabe <dusty(a)dustymabe.com&gt; wrote:
>  On 06/28/2018 05:38 AM, Gergely Gombos wrote:
>  > Hello,
>
>
>  Hi Greg,
>  >
>  > I just installed a F28 image on a Scaleway cloud server. Runs fine, except there
> were no man pages, even after installing man-pages package.
>  > It turned out after a lot of searching that this is not a bug but a feature.
>  > Issue on GitHub:
> https://github.com/fedora-cloud/docker-brew-fedora/issues/9#issuecomment-...
>  > So the culprit is the Kickstarts file, here:
> https://pagure.io/fedora-kickstarts/blob/master/f/fedora-docker-common.ks... (and other
> nearby .ks files)
>  > It says "%packages --excludedocs --instLangs=en --nocore [...]"
>  >
>  > According to the Kickstart docs
> (http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#chapter-4...)
> this won't install man pages, presumably to save space, but the end user won't
> know this, because man will simply not find any man pages and that's it.
>  > A solution was to edit /etc/dnf/dnf.conf, comment "tsflags=nodocs" and
> then reinstall everything with dnf reinstall.
>  > My question: I understand that it's important to save space with containers, but
> often cloud users wish to use man pages, as they are using the cloud server just as any
> remote computer. Is there a way to document the above situation e.g. when the user tries
> to view a man page gets a notification about why they are not installed (and how to
> install them)?
>  This is subjective to who you are, but here is my opinion. A "Cloud" server is
>  usually one that is spun up and provisioned automatically (i.e. a person does
>  not SSH into the machine to configure it). The cloud instance has a specific
>  purpose and can be thrown away easily and re-provisioned. In this scenario docs
>  are wasted space and people generally value smaller image size over having the
>  documentation.
>
>  Now there are certainly cases where you just spin up a cloud instance and want
>  to configure it yourself, but that's not what we're optimizing for. It would be
>  nice if 'man' were able to detect this situation and offer an alternative. Maybe
>  open an RFE BZ against man for this??
>
>  - Dusty

[Dusty Mabe]

On 06/29/2018 03:23 AM, Gergely Gombos wrote:
>  So my solution proposal:
>  
>    *
>      I'm going to create PRs to add this piece of info to the Scaleway Fedora
> (https://github.com/scaleway/image-fedora), Docker Brew
> (https://github.com/fedora-cloud/docker-brew-fedora), and possibly Docker library
> (https://hub.docker.com/_/fedora/) readmes. Just a warning that documentation has been
> permanently turned off, referencing to this discussion:
> https://github.com/fedora-cloud/docker-brew-fedora/issues/9
>    *
>      I'll create an RFE for DNF (instead of man) - to show a warning when tsflags have
> been set. Even something like: "Current transaction flags: [...]" would be
> sufficient. This at least informs the user about the configuration.
>  
>  What do you think? 
Sounds good to me for DNF RFE. That would be useful.

Sorry about the delayed reply.

Dusty

[Gergely Gombos]

Hi Dusty,

Thanks for the response!
I've done that already: https://bugzilla.redhat.com/show_bug.cgi?id=1596568
I don't know what the triage result was though, it's still open.
Best regards,
Greg

On júl 11 2018, at 3:42 du, Dusty Mabe <dusty(a)dustymabe.com&gt; wrote:
>  On 06/29/2018 03:23 AM, Gergely Gombos wrote:
>  >
>  > So my solution proposal:
>  > *
>  > I'm going to create PRs to add this piece of info to the Scaleway Fedora
> (https://github.com/scaleway/image-fedora), Docker Brew
> (https://github.com/fedora-cloud/docker-brew-fedora), and possibly Docker library
> (https://hub.docker.com/_/fedora/) readmes. Just a warning that documentation has been
> permanently turned off, referencing to this discussion:
> https://github.com/fedora-cloud/docker-brew-fedora/issues/9
>  > *
>  > I'll create an RFE for DNF (instead of man) - to show a warning when tsflags
> have been set. Even something like: "Current transaction flags: [...]" would be
> sufficient. This at least informs the user about the configuration.
>  >
>  > What do you think?
>  Sounds good to me for DNF RFE. That would be useful.
>  Sorry about the delayed reply.
>  Dusty