Skip to contentSkip to conversation

Handling of updates to kernel Documentation/ tree

DISCUSSION Stephan Mueller 4 participants 10 messages Mar 9, 2015 – Mar 12, 2015 4 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

#1 lore raw
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

#3 lore raw
In reply to a message not in the archive
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
#5 lore raw
In reply to a message not in the archive
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

#8 lore raw
In reply to a message not in the archive

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

#9 lore raw
In reply to a message not in the archive
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

#7 lore raw
In reply to a message not in the archive
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
#10 lore raw
In reply to Mike Frysinger
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
#11 lore raw
In reply to Mike Frysinger
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

#13 lore raw
In reply to a message not in the archive

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