[patch 1/2] adjtimex.2: remove nonexisting reference to adjtimex(8)

[patch 1/2] adjtimex.2: remove nonexisting reference to adjtimex(8)

[Laurent Georget]

Hello,

This is a patch I sent to mtk.manpages-Re5JQEeQqe9fmgfxC/sS/w@public.gmane.org It didn't make its way
to this mailing-list the first time. It's a trivial fix for an undefined
reference to adjtimex(8). Patch you received before (adjtimex.2: add
explanation about ADJ_TAI action) is patch 2/2 for adjtimex.2.

Sorry for the mistake,

Laurent

diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
index eb3fda1..20a2f0b 100644
--- a/man2/adjtimex.2
+++ b/man2/adjtimex.2
@@ -24,6 +24,7 @@
 .\" Modified 1997-01-31 by Eric S. Raymond <esr-4uCgticg2UFBDgjK7y7TUQ@public.gmane.org>
 .\" Modified 1997-07-30 by Paul Slootman <paul-pqePwCal/LhZiXb3D+6dPA@public.gmane.org>
 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
+.\" Modified 2014-11-28 by Laurent Georget <laurent.georget-vbcOdlJ0SulGWvitb5QawA@public.gmane.org>
 .\"
 .\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
 .\"		commit 153b5d054ac2d98ea0d86504884326b6777f683d
@@ -163,5 +164,4 @@ method of adjusting the system clock.
 .BR settimeofday (2),
 .BR adjtime (3),
 .BR capabilities (7),
-.BR time (7),
-.BR adjtimex (8)
+.BR time (7)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] adjtimex.2: remove nonexisting reference to adjtimex(8)

[Michael Kerrisk (man-pages)]

Hello Laurent,

On Fri, Nov 28, 2014 at 3:02 PM, Laurent Georget
<laurent.georget-vbcOdlJ0SulGWvitb5QawA@public.gmane.org> wrote:
> Hello,
>
> This is a patch I sent to mtk.manpages-Re5JQEeQqe9fmgfxC/sS/w@public.gmane.org It didn't make its way
> to this mailing-list the first time. It's a trivial fix for an undefined
> reference to adjtimex(8). Patch you received before (adjtimex.2: add
> explanation about ADJ_TAI action) is patch 2/2 for adjtimex.2.

This does not seem correct to me. Certainly on my Fedora system, there
is an "adjtimex" package that installs adjtimex(8) page. So, this
reference seems okay to me. Did I miss something?

Thanks,

Michael


> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
> index eb3fda1..20a2f0b 100644
> --- a/man2/adjtimex.2
> +++ b/man2/adjtimex.2
> @@ -24,6 +24,7 @@
>  .\" Modified 1997-01-31 by Eric S. Raymond <esr-4uCgticg2UFBDgjK7y7TUQ@public.gmane.org>
>  .\" Modified 1997-07-30 by Paul Slootman <paul-pqePwCal/LhZiXb3D+6dPA@public.gmane.org>
>  .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> +.\" Modified 2014-11-28 by Laurent Georget <laurent.georget-vbcOdlJ0SulGWvitb5QawA@public.gmane.org>
>  .\"
>  .\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
>  .\"            commit 153b5d054ac2d98ea0d86504884326b6777f683d
> @@ -163,5 +164,4 @@ method of adjusting the system clock.
>  .BR settimeofday (2),
>  .BR adjtime (3),
>  .BR capabilities (7),
> -.BR time (7),
> -.BR adjtimex (8)
> +.BR time (7)
> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] adjtimex.2: remove nonexisting reference to adjtimex(8)

[Laurent Georget]

Hello again,

Le 29/11/2014 10:17, Michael Kerrisk (man-pages) a écrit :
> Hello Laurent,
> 
> On Fri, Nov 28, 2014 at 3:02 PM, Laurent Georget
> <laurent.georget-vbcOdlJ0SulGWvitb5QawA@public.gmane.org> wrote:
>> Hello,
>>
>> This is a patch I sent to mtk.manpages-Re5JQEeQqe9fmgfxC/sS/w@public.gmane.org It didn't make its way
>> to this mailing-list the first time. It's a trivial fix for an undefined
>> reference to adjtimex(8). Patch you received before (adjtimex.2: add
>> explanation about ADJ_TAI action) is patch 2/2 for adjtimex.2.
> 
> This does not seem correct to me. Certainly on my Fedora system, there
> is an "adjtimex" package that installs adjtimex(8) page. So, this
> reference seems okay to me. Did I miss something?
> 

Ok, indeed, my mistake. This package is not part of the core system on
my distribution so I found it surprising to have a link from a man2 page
to a nonexisting man8 page. But now that I give a closer look, the case
is the same for request_key.2 linking to request_key.8 for example so
I'm wrong.

What is the policy to include a link from section 2 to section 1 or 8? I
guess I'm misundestanding something here? Given the case of adjtimex(2)
linking to adjtimex(8) because there is an adjtimex package which
installs it, should we include a link in inotify_{init,add,...} to
inotifywait.1 for example? I've always thought that pages in section 1
(or 8) and 2 should just include a link to a general page in section 7
to remain generic enough through time.

Thanks,

Laurent

> Thanks,
> 
> Michael
> 
> 
>> diff --git a/man2/adjtimex.2 b/man2/adjtimex.2
>> index eb3fda1..20a2f0b 100644
>> --- a/man2/adjtimex.2
>> +++ b/man2/adjtimex.2
>> @@ -24,6 +24,7 @@
>>  .\" Modified 1997-01-31 by Eric S. Raymond <esr-4uCgticg2UFBDgjK7y7TUQ@public.gmane.org>
>>  .\" Modified 1997-07-30 by Paul Slootman <paul-pqePwCal/LhZiXb3D+6dPA@public.gmane.org>
>>  .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> +.\" Modified 2014-11-28 by Laurent Georget <laurent.georget@supelec.fr>
>>  .\"
>>  .\" FIXME Document ADJ_TAI (added in Linux 2.6.26)
>>  .\"            commit 153b5d054ac2d98ea0d86504884326b6777f683d
>> @@ -163,5 +164,4 @@ method of adjusting the system clock.
>>  .BR settimeofday (2),
>>  .BR adjtime (3),
>>  .BR capabilities (7),
>> -.BR time (7),
>> -.BR adjtimex (8)
>> +.BR time (7)
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-man" in
>> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> 
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch 1/2] adjtimex.2: remove nonexisting reference to adjtimex(8)

[Michael Kerrisk (man-pages)]

Hello Laurent,

(Sorry for the delayed follow-up.)

On 11/29/2014 11:22 AM, Laurent Georget wrote:
> Hello again,
> 
> Le 29/11/2014 10:17, Michael Kerrisk (man-pages) a écrit :
>> Hello Laurent,
>>
>> On Fri, Nov 28, 2014 at 3:02 PM, Laurent Georget
>> <laurent.georget-vbcOdlJ0SulGWvitb5QawA@public.gmane.org> wrote:
>>> Hello,
>>>
>>> This is a patch I sent to mtk.manpages-Re5JQEeQqe9fmgfxC/sS/w@public.gmane.org It didn't make its way
>>> to this mailing-list the first time. It's a trivial fix for an undefined
>>> reference to adjtimex(8). Patch you received before (adjtimex.2: add
>>> explanation about ADJ_TAI action) is patch 2/2 for adjtimex.2.
>>
>> This does not seem correct to me. Certainly on my Fedora system, there
>> is an "adjtimex" package that installs adjtimex(8) page. So, this
>> reference seems okay to me. Did I miss something?
>>
> 
> Ok, indeed, my mistake. This package is not part of the core system on
> my distribution so I found it surprising to have a link from a man2 page
> to a nonexisting man8 page. But now that I give a closer look, the case
> is the same for request_key.2 linking to request_key.8 for example so
> I'm wrong.

It's not a really mistake on your part. See below.

> What is the policy to include a link from section 2 to section 1 or 8? I
> guess I'm misundestanding something here? Given the case of adjtimex(2)
> linking to adjtimex(8) because there is an adjtimex package which
> installs it, should we include a link in inotify_{init,add,...} to
> inotifywait.1 for example? I've always thought that pages in section 1
> (or 8) and 2 should just include a link to a general page in section 7
> to remain generic enough through time.

To date, the policy is implicit. I've tried to make it a little more 
explicit by just now adding the following text to man-pages(7):
 
    Given the distributed, autonomous nature of FOSS projects
    and their documentation, it is sometimes necessary—and in
    many cases desirable—that the SEE ALSO  section  includes
    references to manual pages provided by other projects.

Regarding your inotify example, I tried to address that case
a while ago with some additions in inotify(7). But, in the general
case, sometimes these references aren't in the man pages simply 
because no one yet thought to add or suggest them.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html