Improving kdump/kexec documentation

[Bhupesh Sharma]

Hi,

Presently it seems that the kdump/kexec documentation is scattered
over several files which is not very intuitive for a user/system admin
installing the kexec-tools rpm on his system.

We have presently the following documentation helpers. I propose to
make the following changes to the overall documentation:

1. kexec-kdump-howto.txt and fadump-howto.txt:

Background:
----------------
Contains very descriptive information about kdump and kexec, but is
normally not the first place where a user/system admin looks for
information when he installs the kexec-tools.

Proposal:
------------
To deprecate these howto and move the information from here to
respective man pages for kdump, kexec, kdumpctl and kdump.conf

This will avoid duplication of similar information and also ensure
that the user/system admin has the right man pages at his disposal.

2. man page for kdump / kdump service:

Background:
----------------
One doesn't exist yet for kdump service. The existing one is a placeholder only.

Proposal:
------------
Add a proper man page for kdump (one lines of the man page for dracut)
which links properly to man pages for kdumpctl and kdump.conf (again
see man page for dracut.conf for details).

Move the relevant kdump information from kexec-kdump-howto.txt and
fadump-howto.txt to here.

3. man page for kexec:

Background:
----------------
Descriptive man page exists.

Proposal:
------------
Move the relevant kexec information from kexec-kdump-howto.txt and
fadump-howto.txt to here.

4. man page for kdumpctl:

Background:
----------------
Descriptive man page exists.

Proposal:
------------
Link this to man page of kdump or kdump services.

Please share your views and add any missing bits.

Regards,
Bhupesh

[Xunlei Pang]

On 04/12/2017 at 01:55 PM, Bhupesh Sharma wrote:
> Hi,
>
> Presently it seems that the kdump/kexec documentation is scattered
> over several files which is not very intuitive for a user/system admin
> installing the kexec-tools rpm on his system.
>
> We have presently the following documentation helpers. I propose to
> make the following changes to the overall documentation:
> kexec-kdump-howto.txt and fadump-howto.txt:
> Background:
>
> Contains very descriptive information about kdump and kexec, but is
> normally not the first place where a user/system admin looks for
> information when he installs the kexec-tools.
> Proposal:
>
> To deprecate these howto and move the information from here to
> respective man pages for kdump, kexec, kdumpctl and kdump.conf
>
> This will avoid duplication of similar information and also ensure
> that the user/system admin has the right man pages at his disposal.
> man page for kdump / kdump service:
> Background:
>
> One doesn't exist yet for kdump service. The existing one is a placeholder only.
> Proposal:
>
> Add a proper man page for kdump (one lines of the man page for dracut)
> which links properly to man pages for kdumpctl and kdump.conf (again
> see man page for dracut.conf for details).
>
> Move the relevant kdump information from kexec-kdump-howto.txt and
> fadump-howto.txt to here.

Hi Bhupesh,

Yes, it should be improved, it caused confusion.

We have one bug reported the same issue: https://bugzilla.redhat.com/show_bug.cgi?id=1428604
since you are doing this, would you like to take it?

We can show ideas in this thread, here is my personal one:
1) Since /usr/bin/kdump has been useless for us, we can confirm again, if none, just remove it from upstream kexec-tools
2) Then we use "man kdump" to describe our own stuff, like Bhupesh said, moving
    some information from the HOWTO doc sounds good to me.

Regards,
Xunlei
> man page for kexec:
> Background:
>
> Descriptive man page exists.
> Proposal:
>
> Move the relevant kexec information from kexec-kdump-howto.txt and
> fadump-howto.txt to here.
> man page for kdumpctl:
> Background:
>
> Descriptive man page exists.
> Proposal:
>
> Link this to man page of kdump or kdump services.
>
> Please share your views and add any missing bits.
>
> Regards,
> Bhupesh
> _______________________________________________
> kexec mailing list -- [e-mail]
> To unsubscribe send an email to [e-mail]