Handling of updates to kernel Documentation/ tree
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).
[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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 5 lines · Stephan Mueller
Hi Michael,
how shall an update to the
Documentation/tree be handled in man pages that contain a pointer to these documents?
Quoted 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 10 lines · Christoph Hellwig
Quoted 9 lines · 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.
Quoted 7 lines
Quoted 3 lines
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
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 2 lines · Michael Kerrisk (man-pages)
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 9 lines · Christoph Hellwig
Quoted 2 lines · Michael Kerrisk (man-pages)
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
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Am Montag, 9. März 2015, 08:07:39 schrieb Christoph Hellwig:
Hi Christoph,
Quoted 11 lines · Stephan Mueller
Quoted 10 lines
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.
Quoted 7 lines
Quoted 3 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 8 lines · Christoph Hellwig
Quoted 7 lines · Stephan Mueller
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.
Quoted 7 lines
Quoted 3 lines
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
Quoted 13 lines · Mike Frysinger
Quoted 12 lines · Christoph Hellwig
Quoted 10 lines · Stephan Mueller
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).
Quoted 6 lines
Quoted 3 lines
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.
Quoted 2 lines
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
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 6 lines · Mike Frysinger
Quoted 3 lines
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.
Quoted 2 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Am Dienstag, 10. März 2015, 07:11:04 schrieb Christoph Hellwig:
Hi Christoph,
Quoted 14 lines · Mike Frysinger
Quoted 7 lines
Quoted 4 lines
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.
Quoted 2 lines
i think having the man pages refer to the public docbook kernel.org pages should be fine.
Quoted 7 lines
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 [email protected] 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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html