[PATCH] doc: move namespaces.rst out of kbuild directory

[PATCH] doc: move namespaces.rst out of kbuild directory

[Masahiro Yamada]

I did not notice this document was added to Documentation/kbuild/,
and I do not understand how it is related to the build system.

Kick it out of the kbuild directory.

I am not sure if this is the perfect place, but I added its index
close to the module-signing.

Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
---

 Documentation/admin-guide/index.rst                  | 1 +
 Documentation/{kbuild => admin-guide}/namespaces.rst | 0
 MAINTAINERS                                          | 1 +
 3 files changed, 2 insertions(+)
 rename Documentation/{kbuild => admin-guide}/namespaces.rst (100%)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 34cc20ee7f3a..ca632fda700f 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -65,6 +65,7 @@ configure specific aspects of kernel behavior to your liking.
    parport
    md
    module-signing
+   namespaces
    rapidio
    sysrq
    unicode
diff --git a/Documentation/kbuild/namespaces.rst b/Documentation/admin-guide/namespaces.rst
similarity index 100%
rename from Documentation/kbuild/namespaces.rst
rename to Documentation/admin-guide/namespaces.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index 55199ef7fa74..91815dcc5914 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11547,6 +11547,7 @@ NSDEPS
 M:	Matthias Maennich <maennich@google.com>
 S:	Maintained
 F:	scripts/nsdeps
+F:	Documentation/admin-guide/namespaces.rst
 
 NTB AMD DRIVER
 M:	Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
-- 
2.17.1

Re: [PATCH] doc: move namespaces.rst out of kbuild directory

[Adam Zerella]

On Mon, Oct 07, 2019 at 01:36:11PM +0900, Masahiro Yamada wrote:
> I did not notice this document was added to Documentation/kbuild/,
> and I do not understand how it is related to the build system.
> 
> Kick it out of the kbuild directory.

Should we delete the file entirely or does it belong somewhere else? It
was added in c4f4af4094d6c7dbca3acd8d04df2759d268a116 and is referenced
in `Documentation/kernel-hacking/hacking.rst`.

Can we put into the `kernel-hacking` directory?

> I am not sure if this is the perfect place, but I added its index
> close to the module-signing.
> 
> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
> ---
> 
>  Documentation/admin-guide/index.rst                  | 1 +
>  Documentation/{kbuild => admin-guide}/namespaces.rst | 0
>  MAINTAINERS                                          | 1 +
>  3 files changed, 2 insertions(+)
>  rename Documentation/{kbuild => admin-guide}/namespaces.rst (100%)
> 
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 34cc20ee7f3a..ca632fda700f 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -65,6 +65,7 @@ configure specific aspects of kernel behavior to your liking.
>     parport
>     md
>     module-signing
> +   namespaces
>     rapidio
>     sysrq
>     unicode
> diff --git a/Documentation/kbuild/namespaces.rst b/Documentation/admin-guide/namespaces.rst
> similarity index 100%
> rename from Documentation/kbuild/namespaces.rst
> rename to Documentation/admin-guide/namespaces.rst
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 55199ef7fa74..91815dcc5914 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11547,6 +11547,7 @@ NSDEPS
>  M:	Matthias Maennich <maennich@google.com>
>  S:	Maintained
>  F:	scripts/nsdeps
> +F:	Documentation/admin-guide/namespaces.rst
>  
>  NTB AMD DRIVER
>  M:	Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
> -- 
> 2.17.1
> 

Re: [PATCH] doc: move namespaces.rst out of kbuild directory

[Matthias Maennich]

Hi!

On Mon, Oct 07, 2019 at 01:36:11PM +0900, Masahiro Yamada wrote:
>I did not notice this document was added to Documentation/kbuild/,
>and I do not understand how it is related to the build system.
>
>Kick it out of the kbuild directory.
>
>I am not sure if this is the perfect place, but I added its index
>close to the module-signing.

When searching for a place for this documentation, kbuild/ was the
closest I could find. admin-guide/ seems to target system administrators
while the symbol namespace feature documentation is relevant for kernel
developers. I am ok to take maintainership for the file, but the new
location suggested seems not to be a good fit either.

Cheers,
Matthias

>Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
>---
>
> Documentation/admin-guide/index.rst                  | 1 +
> Documentation/{kbuild => admin-guide}/namespaces.rst | 0
> MAINTAINERS                                          | 1 +
> 3 files changed, 2 insertions(+)
> rename Documentation/{kbuild => admin-guide}/namespaces.rst (100%)
>
>diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
>index 34cc20ee7f3a..ca632fda700f 100644
>--- a/Documentation/admin-guide/index.rst
>+++ b/Documentation/admin-guide/index.rst
>@@ -65,6 +65,7 @@ configure specific aspects of kernel behavior to your liking.
>    parport
>    md
>    module-signing
>+   namespaces
>    rapidio
>    sysrq
>    unicode
>diff --git a/Documentation/kbuild/namespaces.rst b/Documentation/admin-guide/namespaces.rst
>similarity index 100%
>rename from Documentation/kbuild/namespaces.rst
>rename to Documentation/admin-guide/namespaces.rst
>diff --git a/MAINTAINERS b/MAINTAINERS
>index 55199ef7fa74..91815dcc5914 100644
>--- a/MAINTAINERS
>+++ b/MAINTAINERS
>@@ -11547,6 +11547,7 @@ NSDEPS
> M:	Matthias Maennich <maennich@google.com>
> S:	Maintained
> F:	scripts/nsdeps
>+F:	Documentation/admin-guide/namespaces.rst
>
> NTB AMD DRIVER
> M:	Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
>-- 
>2.17.1
>

Re: [PATCH] doc: move namespaces.rst out of kbuild directory

[Jessica Yu]

+++ Matthias Maennich [07/10/19 07:06 +0100]:
>Hi!
>
>On Mon, Oct 07, 2019 at 01:36:11PM +0900, Masahiro Yamada wrote:
>>I did not notice this document was added to Documentation/kbuild/,
>>and I do not understand how it is related to the build system.
>>
>>Kick it out of the kbuild directory.
>>
>>I am not sure if this is the perfect place, but I added its index
>>close to the module-signing.
>
>When searching for a place for this documentation, kbuild/ was the
>closest I could find. admin-guide/ seems to target system administrators
>while the symbol namespace feature documentation is relevant for kernel
>developers. I am ok to take maintainership for the file, but the new
>location suggested seems not to be a good fit either.

This was my line of thought as well, since the audience of
admin-guide/ is sysadmins and users. Namespaces are mostly relevant to
module authors and kernel developers. Currently, I don't think there
is an existing good place in Documentation/ for this topic :-/
I suppose kernel-hacking/ might be the closest fit, as Adam suggested.

Thanks,

Jessica

Re: [PATCH] doc: move namespaces.rst out of kbuild directory

[Jonathan Corbet]

On Mon, 7 Oct 2019 10:12:42 +0200
Jessica Yu <jeyu@kernel.org> wrote:

> This was my line of thought as well, since the audience of
> admin-guide/ is sysadmins and users. Namespaces are mostly relevant to
> module authors and kernel developers. Currently, I don't think there
> is an existing good place in Documentation/ for this topic :-/
> I suppose kernel-hacking/ might be the closest fit, as Adam suggested.

I didn't see this thread before responding in the first, naturally...  

I think the core-api manual is probably as good a place as any for this.
Changing the name to something like symbol-namespaces.rst is probably a
good idea, since most people think of other things when they see
"namespaces".  Or perhaps that mythical Somebody could expand it into a
proper description of symbol exports in general...:)

Thanks,

jon

Re: [PATCH] doc: move namespaces.rst out of kbuild directory

[Matthias Maennich]

On Mon, Oct 07, 2019 at 07:29:30AM -0600, Jonathan Corbet wrote:
>On Mon, 7 Oct 2019 10:12:42 +0200
>Jessica Yu <jeyu@kernel.org> wrote:
>
>> This was my line of thought as well, since the audience of
>> admin-guide/ is sysadmins and users. Namespaces are mostly relevant to
>> module authors and kernel developers. Currently, I don't think there
>> is an existing good place in Documentation/ for this topic :-/
>> I suppose kernel-hacking/ might be the closest fit, as Adam suggested.
>
>I didn't see this thread before responding in the first, naturally...
>
>I think the core-api manual is probably as good a place as any for this.
>Changing the name to something like symbol-namespaces.rst is probably a
>good idea, since most people think of other things when they see
>"namespaces".  Or perhaps that mythical Somebody could expand it into a
>proper description of symbol exports in general...:)

As I said in the other thread, I am happy for it to be moved to a better
location. core-api/ as well as kernel-hacking/ seem to be good
locations.

I could imagine expanding the documentation, but would not like to
commit to it right now. (Even though I feel very encouraged by your talk
in Paris, Jon. Thanks for that!)

Cheers,
Matthias

>
>Thanks,
>
>jon

Re: [PATCH] doc: move namespaces.rst out of kbuild directory

[Randy Dunlap]

On 10/7/19 6:41 AM, Matthias Maennich wrote:
> On Mon, Oct 07, 2019 at 07:29:30AM -0600, Jonathan Corbet wrote:
>> On Mon, 7 Oct 2019 10:12:42 +0200
>> Jessica Yu <jeyu@kernel.org> wrote:
>>
>>> This was my line of thought as well, since the audience of
>>> admin-guide/ is sysadmins and users. Namespaces are mostly relevant to
>>> module authors and kernel developers. Currently, I don't think there
>>> is an existing good place in Documentation/ for this topic :-/
>>> I suppose kernel-hacking/ might be the closest fit, as Adam suggested.
>>
>> I didn't see this thread before responding in the first, naturally...
>>
>> I think the core-api manual is probably as good a place as any for this.
>> Changing the name to something like symbol-namespaces.rst is probably a
>> good idea, since most people think of other things when they see
>> "namespaces".  Or perhaps that mythical Somebody could expand it into a
>> proper description of symbol exports in general...:)
> 
> As I said in the other thread, I am happy for it to be moved to a better
> location. core-api/ as well as kernel-hacking/ seem to be good
> locations.

core-api/ please.  kernel-hacking/ does not make any sense to me.

> I could imagine expanding the documentation, but would not like to
> commit to it right now. (Even though I feel very encouraged by your talk
> in Paris, Jon. Thanks for that!)


-- 
~Randy