Handling of updates to kernel Documentation/ tree

Handling of updates to kernel Documentation/ tree

[Stephan Mueller]

Hi Michael,

how shall an update to the Documentation/ tree be handled in man pages 
that contain a pointer to these documents?

Specifically, socket(2) contains a reference to 
Documentation/crypto/crypto-API-userspace.txt. With the patch [1] the 
document is gone and its contents is moved into a DocBook.

Shall the kernel DocBook website [2] be referenced? If so, when is it 
appropriate to add the patch (note, the change is expected to be 
propagated to Linus' tree in 4.1-rc1).


[1] 
https://git.kernel.org/cgit/linux/kernel/git/herbert/cryptodev-2.6.git/commit/?id=dbe5fe7e1b3b3632bef2c09964a5f5505de4d744

[2] https://www.kernel.org/doc/htmldocs/crypto-API/index.html

Ciao
Stephan

--
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: Handling of updates to kernel Documentation/ tree

[Christoph Hellwig]

On Mon, Mar 09, 2015 at 03:17:58PM +0100, Stephan Mueller wrote:
> Hi Michael,
> 
> how shall an update to the Documentation/ tree be handled in man pages 
> that contain a pointer to these documents?
> 
> Specifically, socket(2) contains a reference to 
> Documentation/crypto/crypto-API-userspace.txt. With the patch [1] the 
> document is gone and its contents is moved into a DocBook.
> 
> Shall the kernel DocBook website [2] be referenced? If so, when is it 
> appropriate to add the patch (note, the change is expected to be 
> propagated to Linus' tree in 4.1-rc1).

Referencing a kernel Documentation file from a man page sounds like
a bad idea to me.  Why can't we include a nroff-yfied version of the
content in the man-pages repository?
--
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: Handling of updates to kernel Documentation/ tree

[Michael Kerrisk (man-pages)]

On 03/09/2015 04:07 PM, Christoph Hellwig wrote:
> On Mon, Mar 09, 2015 at 03:17:58PM +0100, Stephan Mueller wrote:
>> Hi Michael,
>>
>> how shall an update to the Documentation/ tree be handled in man pages 
>> that contain a pointer to these documents?
>>
>> Specifically, socket(2) contains a reference to 
>> Documentation/crypto/crypto-API-userspace.txt. With the patch [1] the 
>> document is gone and its contents is moved into a DocBook.
>>
>> Shall the kernel DocBook website [2] be referenced? If so, when is it 
>> appropriate to add the patch (note, the change is expected to be 
>> propagated to Linus' tree in 4.1-rc1).
> 
> Referencing a kernel Documentation file from a man page sounds like
> a bad idea to me.  Why can't we include a nroff-yfied version of the
> content in the man-pages repository?

Actually, a lot of man pages do refer to kernel Documentation files.
What's the problem?

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

Re: Handling of updates to kernel Documentation/ tree

[Christoph Hellwig]

On Mon, Mar 09, 2015 at 05:03:52PM +0100, Michael Kerrisk (man-pages) wrote:
> Actually, a lot of man pages do refer to kernel Documentation files.
> What's the problem?

It's not easily accessibe and coherent information.  It requires a
checked out kernel tree (or a web mirror these days), which might
be a different version than you expect.  Referencing actually installed
case documentation like man page or at least info pages is a lot easier
for the user.
--
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: Handling of updates to kernel Documentation/ tree

[Michael Kerrisk (man-pages)]

On 03/09/2015 05:05 PM, Christoph Hellwig wrote:
> On Mon, Mar 09, 2015 at 05:03:52PM +0100, Michael Kerrisk (man-pages) wrote:
>> Actually, a lot of man pages do refer to kernel Documentation files.
>> What's the problem?
> 
> It's not easily accessibe and coherent information.  It requires a
> checked out kernel tree (or a web mirror these days), which might
> be a different version than you expect.  Referencing actually installed
> case documentation like man page or at least info pages is a lot easier
> for the user.

I agree that installed documentation is preferable, but sometimes
it's not always practical to get that documentation in the desired form.
So, failing that man-pages does quite often reference kernel source files.

Cheers,

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

Re: Handling of updates to kernel Documentation/ tree

[Stephan Mueller]

Am Montag, 9. März 2015, 08:07:39 schrieb Christoph Hellwig:

Hi Christoph,

>On Mon, Mar 09, 2015 at 03:17:58PM +0100, Stephan Mueller wrote:
>> Hi Michael,
>> 
>> how shall an update to the Documentation/ tree be handled in man
>> pages
>> that contain a pointer to these documents?
>> 
>> Specifically, socket(2) contains a reference to
>> Documentation/crypto/crypto-API-userspace.txt. With the patch [1] the
>> document is gone and its contents is moved into a DocBook.
>> 
>> Shall the kernel DocBook website [2] be referenced? If so, when is it
>> appropriate to add the patch (note, the change is expected to be
>> propagated to Linus' tree in 4.1-rc1).
>
>Referencing a kernel Documentation file from a man page sounds like
>a bad idea to me.  Why can't we include a nroff-yfied version of the
>content in the man-pages repository?

You can see the compiled output at [1]. You see that the output is 
larger. Of course I can provide a patch of the output from make mandocs 
of that DocBook. I would think that this documentation is too large to 
be put into socket(2).

The only proposal I would have is to format the output into a separate 
man page for chapter 4.

[1] http://www.chronox.de/crypto-API/User.html


Ciao
Stephan
--
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: Handling of updates to kernel Documentation/ tree

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1047 bytes --]

On 09 Mar 2015 08:07, Christoph Hellwig wrote:
> On Mon, Mar 09, 2015 at 03:17:58PM +0100, Stephan Mueller wrote:
> > how shall an update to the Documentation/ tree be handled in man pages 
> > that contain a pointer to these documents?
> > 
> > Specifically, socket(2) contains a reference to 
> > Documentation/crypto/crypto-API-userspace.txt. With the patch [1] the 
> > document is gone and its contents is moved into a DocBook.
> > 
> > Shall the kernel DocBook website [2] be referenced? If so, when is it 
> > appropriate to add the patch (note, the change is expected to be 
> > propagated to Linus' tree in 4.1-rc1).
> 
> Referencing a kernel Documentation file from a man page sounds like
> a bad idea to me.  Why can't we include a nroff-yfied version of the
> content in the man-pages repository?

isn't that way worse ?  now we have to keep the man pages git repo in sync with 
the kernel Documentation/ subtree.

i think having the man pages refer to the public docbook kernel.org pages should 
be fine.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Handling of updates to kernel Documentation/ tree

[Michael Kerrisk (man-pages)]

On 03/09/2015 06:40 PM, Mike Frysinger wrote:
> On 09 Mar 2015 08:07, Christoph Hellwig wrote:
>> On Mon, Mar 09, 2015 at 03:17:58PM +0100, Stephan Mueller wrote:
>>> how shall an update to the Documentation/ tree be handled in man pages 
>>> that contain a pointer to these documents?
>>>
>>> Specifically, socket(2) contains a reference to 
>>> Documentation/crypto/crypto-API-userspace.txt. With the patch [1] the 
>>> document is gone and its contents is moved into a DocBook.
>>>
>>> Shall the kernel DocBook website [2] be referenced? If so, when is it 
>>> appropriate to add the patch (note, the change is expected to be 
>>> propagated to Linus' tree in 4.1-rc1).
>>
>> Referencing a kernel Documentation file from a man page sounds like
>> a bad idea to me.  Why can't we include a nroff-yfied version of the
>> content in the man-pages repository?
> 
> isn't that way worse ?  now we have to keep the man pages git repo in sync with 
> the kernel Documentation/ subtree.

Agreed. Unless it's totally automated, keeping things in synch is too 
painful.

> i think having the man pages refer to the public docbook kernel.org pages should 
> be fine.

It's acceptable, IMO, though proper installed documentation is better.

Cheers,

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

Re: Handling of updates to kernel Documentation/ tree

[Christoph Hellwig]

On Mon, Mar 09, 2015 at 01:40:57PM -0400, Mike Frysinger wrote:
> > Referencing a kernel Documentation file from a man page sounds like
> > a bad idea to me.  Why can't we include a nroff-yfied version of the
> > content in the man-pages repository?
> 
> isn't that way worse ?  now we have to keep the man pages git repo in sync with 
> the kernel Documentation/ subtree.

The content really should not change that much for public APIs.

> i think having the man pages refer to the public docbook kernel.org pages should 
> be fine.

Pointing to kernel.org posted html renderings sounds perfectly fine to
me.  The reference to files inside a kernel source tree is what I object
to.
--
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: Handling of updates to kernel Documentation/ tree

[Stephan Mueller]

Am Dienstag, 10. März 2015, 07:11:04 schrieb Christoph Hellwig:

Hi Christoph,

>On Mon, Mar 09, 2015 at 01:40:57PM -0400, Mike Frysinger wrote:
>> > Referencing a kernel Documentation file from a man page sounds like
>> > a bad idea to me.  Why can't we include a nroff-yfied version of
>> > the
>> > content in the man-pages repository?
>> 
>> isn't that way worse ?  now we have to keep the man pages git repo in
>> sync with the kernel Documentation/ subtree.
>
>The content really should not change that much for public APIs.
>
>> i think having the man pages refer to the public docbook kernel.org
>> pages should be fine.
>
>Pointing to kernel.org posted html renderings sounds perfectly fine to
>me.  The reference to files inside a kernel source tree is what I
>object to.
>--
>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

If this is the consensus, then I will wait with a patch to the man page 
until the code is merged into Linus' tree and the DocBook at kernel.org 
is updated.

The patch will then refer to the precise kernel.org web page.


Ciao
Stephan
--
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