[PATCH] docs: serial: fix a reference file name in driver.rst

[PATCH] docs: serial: fix a reference file name in driver.rst

[Wan Jiabing]

Fix the following 'make refcheckdocs' warning:
Warning: Documentation/driver-api/serial/driver.rst references a file
that doesn't exist: Documentation/driver-api/serial/tty.rst

Signed-off-by: Wan Jiabing <wanjiabing@vivo.com>
---
 Documentation/driver-api/serial/driver.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst
index 31bd4e16fb1f..06ec04ba086f 100644
--- a/Documentation/driver-api/serial/driver.rst
+++ b/Documentation/driver-api/serial/driver.rst
@@ -311,7 +311,7 @@ hardware.
 	This call must not sleep
 
   set_ldisc(port,termios)
-	Notifier for discipline change. See Documentation/driver-api/serial/tty.rst.
+	Notifier for discipline change. See Documentation/tty/tty_ldisc.rst.
 
 	Locking: caller holds tty_port->mutex
 
-- 
2.35.1

Re: [PATCH] docs: serial: fix a reference file name in driver.rst

[Jiri Slaby]

On 04. 03. 22, 11:03, Wan Jiabing wrote:
> Fix the following 'make refcheckdocs' warning:
> Warning: Documentation/driver-api/serial/driver.rst references a file
> that doesn't exist: Documentation/driver-api/serial/tty.rst
> 
> Signed-off-by: Wan Jiabing <wanjiabing@vivo.com>

Reviewed-by: Jiri Slaby <jirislaby@kernel.org>

> ---
>   Documentation/driver-api/serial/driver.rst | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst
> index 31bd4e16fb1f..06ec04ba086f 100644
> --- a/Documentation/driver-api/serial/driver.rst
> +++ b/Documentation/driver-api/serial/driver.rst
> @@ -311,7 +311,7 @@ hardware.
>   	This call must not sleep
>   
>     set_ldisc(port,termios)
> -	Notifier for discipline change. See Documentation/driver-api/serial/tty.rst.
> +	Notifier for discipline change. See Documentation/tty/tty_ldisc.rst.
>   
>   	Locking: caller holds tty_port->mutex
>   

thanks,
-- 
js
suse labs

Re: [PATCH] docs: serial: fix a reference file name in driver.rst

[Jonathan Corbet]

Jiri Slaby <jirislaby@kernel.org> writes:

> On 04. 03. 22, 11:03, Wan Jiabing wrote:
>> Fix the following 'make refcheckdocs' warning:
>> Warning: Documentation/driver-api/serial/driver.rst references a file
>> that doesn't exist: Documentation/driver-api/serial/tty.rst
>> 
>> Signed-off-by: Wan Jiabing <wanjiabing@vivo.com>
>
> Reviewed-by: Jiri Slaby <jirislaby@kernel.org>

I've applied this.  But I have to wonder why Documentation/tty exists at
all; is there any reason not to move it all under driver-api?

Thanks,

jon

Re: [PATCH] docs: serial: fix a reference file name in driver.rst

[Greg Kroah-Hartman]

On Fri, Mar 11, 2022 at 02:06:00PM -0700, Jonathan Corbet wrote:
> Jiri Slaby <jirislaby@kernel.org> writes:
> 
> > On 04. 03. 22, 11:03, Wan Jiabing wrote:
> >> Fix the following 'make refcheckdocs' warning:
> >> Warning: Documentation/driver-api/serial/driver.rst references a file
> >> that doesn't exist: Documentation/driver-api/serial/tty.rst
> >> 
> >> Signed-off-by: Wan Jiabing <wanjiabing@vivo.com>
> >
> > Reviewed-by: Jiri Slaby <jirislaby@kernel.org>
> 
> I've applied this.  But I have to wonder why Documentation/tty exists at
> all; is there any reason not to move it all under driver-api?

No reason at all, it should probably be moved someday.

thanks,

greg k-h

Re: [PATCH] docs: serial: fix a reference file name in driver.rst

[Jiri Slaby]

On 12. 03. 22, 7:59, Greg Kroah-Hartman wrote:
> On Fri, Mar 11, 2022 at 02:06:00PM -0700, Jonathan Corbet wrote:
>> Jiri Slaby <jirislaby@kernel.org> writes:
>>
>>> On 04. 03. 22, 11:03, Wan Jiabing wrote:
>>>> Fix the following 'make refcheckdocs' warning:
>>>> Warning: Documentation/driver-api/serial/driver.rst references a file
>>>> that doesn't exist: Documentation/driver-api/serial/tty.rst
>>>>
>>>> Signed-off-by: Wan Jiabing <wanjiabing@vivo.com>
>>>
>>> Reviewed-by: Jiri Slaby <jirislaby@kernel.org>
>>
>> I've applied this.  But I have to wonder why Documentation/tty exists at
>> all; is there any reason not to move it all under driver-api?
> 
> No reason at all, it should probably be moved someday.

The only reason was that I don't completely understand what "driver-api" 
should contain. To be presice, documentation of line disciplines, tty 
buffer and tty internals (which is all contained in Documentation/tty) 
doesn't belong to "driver-api" IMO. If it it preferred to be there, I 
can move it, of course.

thanks,
-- 
js
suse labs

Re: [PATCH] docs: serial: fix a reference file name in driver.rst

[Jiri Slaby]

On 14. 03. 22, 7:16, Jiri Slaby wrote:
> On 12. 03. 22, 7:59, Greg Kroah-Hartman wrote:
>> On Fri, Mar 11, 2022 at 02:06:00PM -0700, Jonathan Corbet wrote:
>>> Jiri Slaby <jirislaby@kernel.org> writes:
>>>
>>>> On 04. 03. 22, 11:03, Wan Jiabing wrote:
>>>>> Fix the following 'make refcheckdocs' warning:
>>>>> Warning: Documentation/driver-api/serial/driver.rst references a file
>>>>> that doesn't exist: Documentation/driver-api/serial/tty.rst
>>>>>
>>>>> Signed-off-by: Wan Jiabing <wanjiabing@vivo.com>
>>>>
>>>> Reviewed-by: Jiri Slaby <jirislaby@kernel.org>
>>>
>>> I've applied this.  But I have to wonder why Documentation/tty exists at
>>> all; is there any reason not to move it all under driver-api?
>>
>> No reason at all, it should probably be moved someday.
> 
> The only reason was that I don't completely understand what "driver-api" 
> should contain. To be presice, documentation of line disciplines, tty 
> buffer and tty internals (which is all contained in Documentation/tty) 
> doesn't belong to "driver-api" IMO. If it it preferred to be there, I 
> can move it, of course.

Returning to this: staring into Documentation/index.rst and 
Documentation/driver-api/index.rst. Looking at documents/paths they 
reference, I still don't quite understand what is the rule to put the 
stuff to either of them.

What I used to decide to put the tty stuff to the root is that it's not 
only driver-api documented there. It documents also tty internals and 
implementation of some line disciplines.

So, now I'm confused why it does NOT belong to the root.

thanks,
-- 
js
suse labs

Re: [PATCH] docs: serial: fix a reference file name in driver.rst

[Jonathan Corbet]

Jiri Slaby <jirislaby@kernel.org> writes:

> Returning to this: staring into Documentation/index.rst and 
> Documentation/driver-api/index.rst. Looking at documents/paths they 
> reference, I still don't quite understand what is the rule to put the 
> stuff to either of them.
>
> What I used to decide to put the tty stuff to the root is that it's not 
> only driver-api documented there. It documents also tty internals and 
> implementation of some line disciplines.
>
> So, now I'm confused why it does NOT belong to the root.

My thinking is: for the same reason that drivers/tty is not in the root.

I've been pushing for some time to get our documentation organized for
the readers, which means arranging things in terms of the expected
audience.  Much of what's in Documentation/tty looks like driver-api
stuff, so that's where I would like it to be.  If you have material for
other audiences, perhaps that material should go into a different book.

When I started doing this, "ls Documentation" would scroll on for many
pages.  We've been slowly moving away from that directory as an
unorganized dumping ground, but there is still a ways to go.

Thanks,

jon