* [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues @ 2017-06-23 18:39 Jonathan Corbet 2017-06-23 23:09 ` Rafael J. Wysocki ` (2 more replies) 0 siblings, 3 replies; 25+ messages in thread From: Jonathan Corbet @ 2017-06-23 18:39 UTC (permalink / raw) To: ksummit-discuss The docs pull for 4.13 will include the conversion of the last DocBook template files, thanks mostly to Mauro. That's the good news; the bad news is that I get to explain a lot of merge conflicts to Linus, most of which result from other trees reaching into Documentation/ and changing files that have been converted. I can continue in this mode, but I do wonder if there's a better way out there somewhere. So I think there would be value in a session on the maintenance of "subsystems" that don't fit neatly into the kernel source-tree hierarchy. We could also talk about the state of the RST conversion and whether/how we'd like it to continue. Perhaps we would rather, as Peter recently suggested, "just delete all that nonsense and go back to 80 column 7bit ASCII"? In general, what do the maintainers want from the documentation subsystem, and how can we make it easy to continue improving our docs? jon ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-23 18:39 [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues Jonathan Corbet @ 2017-06-23 23:09 ` Rafael J. Wysocki 2017-06-24 12:03 ` Rafael J. Wysocki 2017-06-24 10:46 ` Mauro Carvalho Chehab 2017-06-26 12:19 ` Mark Brown 2 siblings, 1 reply; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-23 23:09 UTC (permalink / raw) To: Jonathan Corbet; +Cc: ksummit-discuss On Friday, June 23, 2017 12:39:36 PM Jonathan Corbet wrote: > The docs pull for 4.13 will include the conversion of the last DocBook > template files, thanks mostly to Mauro. That's the good news; the bad > news is that I get to explain a lot of merge conflicts to Linus, most of > which result from other trees reaching into Documentation/ and changing > files that have been converted. > > I can continue in this mode, but I do wonder if there's a better way out > there somewhere. So I think there would be value in a session on the > maintenance of "subsystems" that don't fit neatly into the kernel > source-tree hierarchy. > > We could also talk about the state of the RST conversion and whether/how > we'd like it to continue. Perhaps we would rather, as Peter recently > suggested, "just delete all that nonsense and go back to 80 column 7bit > ASCII"? In general, what do the maintainers want from the documentation > subsystem, and how can we make it easy to continue improving our docs? For one, I'm going to continue converting PM documentation to RST and I would not welcome deleting the existing .txt one until that is complete. Same goes for ACPI, pretty much. Also I don't expect too many documentation-related merge conflicts in the PM case going forward. Thanks, Rafael ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-23 23:09 ` Rafael J. Wysocki @ 2017-06-24 12:03 ` Rafael J. Wysocki 0 siblings, 0 replies; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-24 12:03 UTC (permalink / raw) To: Jonathan Corbet; +Cc: ksummit-discuss On Saturday, June 24, 2017 01:09:28 AM Rafael J. Wysocki wrote: > On Friday, June 23, 2017 12:39:36 PM Jonathan Corbet wrote: > > The docs pull for 4.13 will include the conversion of the last DocBook > > template files, thanks mostly to Mauro. That's the good news; the bad > > news is that I get to explain a lot of merge conflicts to Linus, most of > > which result from other trees reaching into Documentation/ and changing > > files that have been converted. > > > > I can continue in this mode, but I do wonder if there's a better way out > > there somewhere. So I think there would be value in a session on the > > maintenance of "subsystems" that don't fit neatly into the kernel > > source-tree hierarchy. > > > > We could also talk about the state of the RST conversion and whether/how > > we'd like it to continue. Perhaps we would rather, as Peter recently > > suggested, "just delete all that nonsense and go back to 80 column 7bit > > ASCII"? In general, what do the maintainers want from the documentation > > subsystem, and how can we make it easy to continue improving our docs? > > For one, I'm going to continue converting PM documentation to RST and I would > not welcome deleting the existing .txt one until that is complete. > > Same goes for ACPI, pretty much. > > Also I don't expect too many documentation-related merge conflicts in the PM > case going forward. I should probably add that I find RST much more appealing than "80 column 7bit ASCII" at least because of how it allows cross-references to be expressed if nothing else. Thanks, Rafael ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-23 18:39 [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues Jonathan Corbet 2017-06-23 23:09 ` Rafael J. Wysocki @ 2017-06-24 10:46 ` Mauro Carvalho Chehab 2017-06-24 12:20 ` Rafael J. Wysocki 2017-06-26 12:19 ` Mark Brown 2 siblings, 1 reply; 25+ messages in thread From: Mauro Carvalho Chehab @ 2017-06-24 10:46 UTC (permalink / raw) To: Jonathan Corbet; +Cc: ksummit-discuss Em Fri, 23 Jun 2017 12:39:36 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > The docs pull for 4.13 will include the conversion of the last DocBook > template files, thanks mostly to Mauro. That's the good news; the bad > news is that I get to explain a lot of merge conflicts to Linus, most of > which result from other trees reaching into Documentation/ and changing > files that have been converted. > > I can continue in this mode, but I do wonder if there's a better way out > there somewhere. So I think there would be value in a session on the > maintenance of "subsystems" that don't fit neatly into the kernel > source-tree hierarchy. Unfortunately, conflicts are unavoidable for such kind of conversion, as git won't identify it as a rename. > We could also talk about the state of the RST conversion and whether/how > we'd like it to continue. Perhaps we would rather, as Peter recently > suggested, "just delete all that nonsense and go back to 80 column 7bit > ASCII"? In general, what do the maintainers want from the documentation > subsystem, and how can we make it easy to continue improving our docs? From my side, going to plain ASCII is a very bad idea. After converting hundreds of text files to ReST, the big problem we have with text files is that they don't use the same notation. It is a big mess. Even before the ReST conversion, what we had is: Some files there doesn't even have titles Some files use markdown Some files use MediaWiki notation Some files use ReST Some files use their own notation. I guess the great benefit of adopting ReST (with would have been achieved if we had adopted any other notation) is that now we have a documentation style. Just placing all documents in the same style is a huge improvement from what we had before. Being able of grouping the documents into books is another big advantage. It is now clearer where some document should be placed. Also, several text editors (both TUI and GUI) are able to recognize ReST format and use colors for highlights. So, there are improvements even for those that don't care about fancy html/pdf books, as the documentation will look more coherent and better organized. In the specific case of media, converting to plain ASCII is a *huge* regression, and some tables simply don't fit at a 80 columns requirement. In summary, We have several tables there to describe bit fields on a 64-bits word (for example, do describe how images are encoded). For such tables, we would require at least 210+ characters per line. So, converting them to plain ASCII simply makes them a lot worse to read. Also, as our uAPI documentation was always using an enriched text language (they were originally written in LaTeX and PDF, back in the nineties), converting them to plain ASCII actually means to rewrite the entire thing. Even the conversion to ReST required us to change the format of several tables (as we were using a lot to have tables inside tables, and ReST doesn't support it). Thankfully, Markus found a way to do such conversion via script. Yet, we had lots of manual work to fix stuff after that. So, I think we should continue the conversion. - From my PoV, after the next merge window, we shouldn't expect more conflicts related to DocBook conversion. However, we'll still have conflicts for the files that are under Documentation/*.txt, as there are stuff there from random subsystems, although get_maintainers usually point them all to the docs subsystem. I recently took the effort of sending patches converting all those text patches to ReST (except for logo.txt). I opted to not rename them to ReST nor add them on any existing book[1], in order to avoid merge conflicts. [1] I added a patch that creates an "unsorted" book at the end of series meant just to allow testing the conversion. IMHO, the next step would be to merge those patches by the end of the next merge window (in order to avoid most conflicts). Then, I would move those files to subdirectories, renaming them to ReST and adding on some index.rst file. Thanks, Mauro ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-24 10:46 ` Mauro Carvalho Chehab @ 2017-06-24 12:20 ` Rafael J. Wysocki 2017-06-24 13:41 ` Mauro Carvalho Chehab 2017-06-25 16:13 ` Jonathan Corbet 0 siblings, 2 replies; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-24 12:20 UTC (permalink / raw) To: Mauro Carvalho Chehab; +Cc: ksummit-discuss On Saturday, June 24, 2017 07:46:41 AM Mauro Carvalho Chehab wrote: > Em Fri, 23 Jun 2017 12:39:36 -0600 > Jonathan Corbet <corbet@lwn.net> escreveu: > > > The docs pull for 4.13 will include the conversion of the last DocBook > > template files, thanks mostly to Mauro. That's the good news; the bad > > news is that I get to explain a lot of merge conflicts to Linus, most of > > which result from other trees reaching into Documentation/ and changing > > files that have been converted. > > > > I can continue in this mode, but I do wonder if there's a better way out > > there somewhere. So I think there would be value in a session on the > > maintenance of "subsystems" that don't fit neatly into the kernel > > source-tree hierarchy. > > Unfortunately, conflicts are unavoidable for such kind of conversion, > as git won't identify it as a rename. > > > We could also talk about the state of the RST conversion and whether/how > > we'd like it to continue. Perhaps we would rather, as Peter recently > > suggested, "just delete all that nonsense and go back to 80 column 7bit > > ASCII"? In general, what do the maintainers want from the documentation > > subsystem, and how can we make it easy to continue improving our docs? > > From my side, going to plain ASCII is a very bad idea. > > After converting hundreds of text files to ReST, the big problem we have > with text files is that they don't use the same notation. It is a big > mess. Even before the ReST conversion, what we had is: > > Some files there doesn't even have titles > Some files use markdown > Some files use MediaWiki notation > Some files use ReST > Some files use their own notation. > > I guess the great benefit of adopting ReST (with would have been > achieved if we had adopted any other notation) is that now we have a > documentation style. > > Just placing all documents in the same style is a huge improvement > from what we had before. Agreed. > Being able of grouping the documents into books is another big > advantage. It is now clearer where some document should be placed. I'm not so sure about this one. I sometimes find it somewhat hard to split things to make them fall nicely into one of the prescribed "bins". I guess it gets easier when writing documentation from scratch. > Also, several text editors (both TUI and GUI) are able to recognize > ReST format and use colors for highlights. Honestly, I've had a mixed experience with that. In some cases I wish they had not done that. :-) > So, there are improvements even for those that don't care about > fancy html/pdf books, as the documentation will look more coherent > and better organized. I actually think that being able to generate HTML output with active cross-reference links is a *huge* advantage as it makes it way easier to browse it (plus the fact that it is automatically made available in HTML by kernel.org). > In the specific case of media, converting to plain ASCII is a *huge* > regression, and some tables simply don't fit at a 80 columns > requirement. In summary, We have several tables there to describe > bit fields on a 64-bits word (for example, do describe how images > are encoded). For such tables, we would require at least 210+ characters > per line. So, converting them to plain ASCII simply makes them a lot > worse to read. > > Also, as our uAPI documentation was always using an enriched text > language (they were originally written in LaTeX and PDF, back in the > nineties), converting them to plain ASCII actually means to rewrite > the entire thing. > > Even the conversion to ReST required us to change the format of > several tables (as we were using a lot to have tables inside tables, > and ReST doesn't support it). Thankfully, Markus found a way to > do such conversion via script. Yet, we had lots of manual work to > fix stuff after that. > > So, I think we should continue the conversion. I agree and, as I said, I'm going to do that for the PM and ACPI documentation. At the same time I think it would be good to take that as an opportinity to improve the *content* of the documentation files as well, so not just convert them, but also make them more up to date etc in the process. > - > > From my PoV, after the next merge window, we shouldn't expect more > conflicts related to DocBook conversion. > > However, we'll still have conflicts for the files that are under > Documentation/*.txt, as there are stuff there from random subsystems, > although get_maintainers usually point them all to the docs subsystem. > > I recently took the effort of sending patches converting all those > text patches to ReST (except for logo.txt). I opted to not rename them > to ReST nor add them on any existing book[1], in order to avoid > merge conflicts. > > [1] I added a patch that creates an "unsorted" book at the end of > series meant just to allow testing the conversion. > > IMHO, the next step would be to merge those patches by the end of the > next merge window (in order to avoid most conflicts). > > Then, I would move those files to subdirectories, renaming them to ReST > and adding on some index.rst file. One comment on that. There are pieces of .txt documentation falling into the "well-knows source of information" category, with many references to them all over the Web. kernel-parameters.txt is probably the most spectacular example here, but there are others. Let us not move or rename these, please, or at least put symbolic links in place to point to the new locations or similar, such that the existing WWW links pointing to the documentation at kernel.org still work going forward. And if we have moved or renamed them already, can we possibly make these links work again somehow? Thanks, Rafael ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-24 12:20 ` Rafael J. Wysocki @ 2017-06-24 13:41 ` Mauro Carvalho Chehab 2017-06-25 20:56 ` Jiri Kosina [not found] ` <CAFhKne8ZttmqWYJToCw9EDywzeMdp=eiFpoZ+O5xrzmKnpA09Q@mail.gmail.com> 2017-06-25 16:13 ` Jonathan Corbet 1 sibling, 2 replies; 25+ messages in thread From: Mauro Carvalho Chehab @ 2017-06-24 13:41 UTC (permalink / raw) To: Rafael J. Wysocki; +Cc: ksummit-discuss Em Sat, 24 Jun 2017 14:20:40 +0200 "Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu: > On Saturday, June 24, 2017 07:46:41 AM Mauro Carvalho Chehab wrote: > > Em Fri, 23 Jun 2017 12:39:36 -0600 > > Jonathan Corbet <corbet@lwn.net> escreveu: > > > > Being able of grouping the documents into books is another big > > advantage. It is now clearer where some document should be placed. > > I'm not so sure about this one. > > I sometimes find it somewhat hard to split things to make them fall nicely into > one of the prescribed "bins". Yeah, one of the problems with existing documentation is that, sometimes, the same document describes both userspace-relevant info and kernelspace APIs. While sometimes it makes sense to split those two, on other cases, it doesn't. That's specially true on documentation for an specific driver. For example the cpia2 driver documentation: https://www.kernel.org/doc/html/latest/media/v4l-drivers/cpia2.html contains a mix of user's information and programmers information. I found lots of similar cases on the documentation for input drivers. I guess one of the discussions we need to have is with regards to how to better organize things. Anyway, that forces us to think about better organizing the stuff we have, so, IMHO, it is a good thing. > I guess it gets easier when writing documentation from scratch. Yes. > > > Also, several text editors (both TUI and GUI) are able to recognize > > ReST format and use colors for highlights. > > Honestly, I've had a mixed experience with that. In some cases I wish they > had not done that. :-) :-) Yeah, there are bugs on highlights on some tools. Yet, I like it, because, when visualizing docs in text mode, it does emphasis to things like bold, italics, etc. > > > So, there are improvements even for those that don't care about > > fancy html/pdf books, as the documentation will look more coherent > > and better organized. > > I actually think that being able to generate HTML output with active > cross-reference links is a *huge* advantage as it makes it way easier to > browse it (plus the fact that it is automatically made available in HTML > by kernel.org). Yes, that's a huge advantage. It also allows me reply with URLs when complaining about someone not doing the right thing, instead of writing otherwise longer explanations. > > In the specific case of media, converting to plain ASCII is a *huge* > > regression, and some tables simply don't fit at a 80 columns > > requirement. In summary, We have several tables there to describe > > bit fields on a 64-bits word (for example, do describe how images > > are encoded). For such tables, we would require at least 210+ characters > > per line. So, converting them to plain ASCII simply makes them a lot > > worse to read. > > > > Also, as our uAPI documentation was always using an enriched text > > language (they were originally written in LaTeX and PDF, back in the > > nineties), converting them to plain ASCII actually means to rewrite > > the entire thing. > > > > Even the conversion to ReST required us to change the format of > > several tables (as we were using a lot to have tables inside tables, > > and ReST doesn't support it). Thankfully, Markus found a way to > > do such conversion via script. Yet, we had lots of manual work to > > fix stuff after that. > > > > So, I think we should continue the conversion. > > I agree and, as I said, I'm going to do that for the PM and ACPI documentation. > > At the same time I think it would be good to take that as an opportinity to > improve the *content* of the documentation files as well, so not just > convert them, but also make them more up to date etc in the process. Agreed. From my experience of converting documents outside my main area of domain, a lot of documents are getting more attention in the conversion process, with attract patches for fixing broken stuff on them. > > - > > > > From my PoV, after the next merge window, we shouldn't expect more > > conflicts related to DocBook conversion. > > > > However, we'll still have conflicts for the files that are under > > Documentation/*.txt, as there are stuff there from random subsystems, > > although get_maintainers usually point them all to the docs subsystem. > > > > I recently took the effort of sending patches converting all those > > text patches to ReST (except for logo.txt). I opted to not rename them > > to ReST nor add them on any existing book[1], in order to avoid > > merge conflicts. > > > > [1] I added a patch that creates an "unsorted" book at the end of > > series meant just to allow testing the conversion. > > > > IMHO, the next step would be to merge those patches by the end of the > > next merge window (in order to avoid most conflicts). > > > > Then, I would move those files to subdirectories, renaming them to ReST > > and adding on some index.rst file. > > One comment on that. > > There are pieces of .txt documentation falling into the "well-knows source of > information" category, with many references to them all over the Web. > kernel-parameters.txt is probably the most spectacular example here, but there > are others. > > Let us not move or rename these, please, or at least put symbolic links in > place to point to the new locations or similar, such that the existing WWW > links pointing to the documentation at kernel.org still work going forward. > > And if we have moved or renamed them already, can we possibly make these > links work again somehow? Agreed. We discussed in the past about two alternatives for those "well known" documents: 1) write a small text on the old file pointing to the new location; 2) use symlink. Right now, we're actually mixing (1) and (2). IMHO, we should either do (1) or (2). My personal preference is for (1), as it force people to update cross-references to the right place, but I'm OK with (2) too. A separate matter is what are those "well known" documents. I bet different Kernel developers will point to different sets of documents they consider to be the ones that require some sort of symlinks ;-) Thanks, Mauro ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-24 13:41 ` Mauro Carvalho Chehab @ 2017-06-25 20:56 ` Jiri Kosina 2017-06-26 1:20 ` Mauro Carvalho Chehab ` (2 more replies) [not found] ` <CAFhKne8ZttmqWYJToCw9EDywzeMdp=eiFpoZ+O5xrzmKnpA09Q@mail.gmail.com> 1 sibling, 3 replies; 25+ messages in thread From: Jiri Kosina @ 2017-06-25 20:56 UTC (permalink / raw) To: Mauro Carvalho Chehab; +Cc: ksummit-discuss On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: > > There are pieces of .txt documentation falling into the "well-knows source of > > information" category, with many references to them all over the Web. > > kernel-parameters.txt is probably the most spectacular example here, but there > > are others. > > > > Let us not move or rename these, please, or at least put symbolic links in > > place to point to the new locations or similar, such that the existing WWW > > links pointing to the documentation at kernel.org still work going forward. > > > > And if we have moved or renamed them already, can we possibly make these > > links work again somehow? > > Agreed. We discussed in the past about two alternatives for those > "well known" documents: > > 1) write a small text on the old file pointing to the > new location; > 2) use symlink. > > Right now, we're actually mixing (1) and (2). IMHO, we should either > do (1) or (2). Unfortunately option (3) has also been applied to some of the files: $ ll Documentation/kernel-parameters.txt ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory I wasn't sure whether this was intentional or not. But if not, I'll happily send a patch that introduces a symlink. -- Jiri Kosina SUSE Labs ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-25 20:56 ` Jiri Kosina @ 2017-06-26 1:20 ` Mauro Carvalho Chehab 2017-06-26 21:18 ` Rafael J. Wysocki 2017-06-26 5:58 ` Takashi Iwai 2017-06-26 22:18 ` Jonathan Corbet 2 siblings, 1 reply; 25+ messages in thread From: Mauro Carvalho Chehab @ 2017-06-26 1:20 UTC (permalink / raw) To: Jiri Kosina; +Cc: ksummit-discuss Em Sun, 25 Jun 2017 22:56:07 +0200 (CEST) Jiri Kosina <jkosina@suse.cz> escreveu: > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: > > > > There are pieces of .txt documentation falling into the "well-knows source of > > > information" category, with many references to them all over the Web. > > > kernel-parameters.txt is probably the most spectacular example here, but there > > > are others. > > > > > > Let us not move or rename these, please, or at least put symbolic links in > > > place to point to the new locations or similar, such that the existing WWW > > > links pointing to the documentation at kernel.org still work going forward. > > > > > > And if we have moved or renamed them already, can we possibly make these > > > links work again somehow? > > > > Agreed. We discussed in the past about two alternatives for those > > "well known" documents: > > > > 1) write a small text on the old file pointing to the > > new location; > > 2) use symlink. > > > > Right now, we're actually mixing (1) and (2). IMHO, we should either > > do (1) or (2). > > Unfortunately option (3) has also been applied to some of the files: > > $ ll Documentation/kernel-parameters.txt > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory > > I wasn't sure whether this was intentional or not. But if not, I'll > happily send a patch that introduces a symlink. It was not intentional in the sense of "hiding" where it went. The idea is to keep the number of such references "minimum", in order to avoid bloating the Documents/ with lots of (1) or (2). So, the reason why there's currently no cross reference for it is just because nobody decided to put it at the list of "well known" docs that would require a cross-reference of type (1) or (2). Thanks, Mauro ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 1:20 ` Mauro Carvalho Chehab @ 2017-06-26 21:18 ` Rafael J. Wysocki 0 siblings, 0 replies; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-26 21:18 UTC (permalink / raw) To: Mauro Carvalho Chehab, Jiri Kosina; +Cc: ksummit-discuss On Sunday, June 25, 2017 10:20:57 PM Mauro Carvalho Chehab wrote: > Em Sun, 25 Jun 2017 22:56:07 +0200 (CEST) > Jiri Kosina <jkosina@suse.cz> escreveu: > > > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: > > > > > > There are pieces of .txt documentation falling into the "well-knows source of > > > > information" category, with many references to them all over the Web. > > > > kernel-parameters.txt is probably the most spectacular example here, but there > > > > are others. > > > > > > > > Let us not move or rename these, please, or at least put symbolic links in > > > > place to point to the new locations or similar, such that the existing WWW > > > > links pointing to the documentation at kernel.org still work going forward. > > > > > > > > And if we have moved or renamed them already, can we possibly make these > > > > links work again somehow? > > > > > > Agreed. We discussed in the past about two alternatives for those > > > "well known" documents: > > > > > > 1) write a small text on the old file pointing to the > > > new location; > > > 2) use symlink. > > > > > > Right now, we're actually mixing (1) and (2). IMHO, we should either > > > do (1) or (2). > > > > Unfortunately option (3) has also been applied to some of the files: > > > > $ ll Documentation/kernel-parameters.txt > > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory > > > > I wasn't sure whether this was intentional or not. But if not, I'll > > happily send a patch that introduces a symlink. > > It was not intentional in the sense of "hiding" where it > went. The idea is to keep the number of such references "minimum", > in order to avoid bloating the Documents/ with lots of (1) or (2). > > So, the reason why there's currently no cross reference for it is > just because nobody decided to put it at the list of "well known" > docs that would require a cross-reference of type (1) or (2). Which I'm reading as "please send a patch if you care" frankly. :-) Thanks, Rafael ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-25 20:56 ` Jiri Kosina 2017-06-26 1:20 ` Mauro Carvalho Chehab @ 2017-06-26 5:58 ` Takashi Iwai 2017-06-26 21:28 ` Rafael J. Wysocki 2017-06-26 22:18 ` Jonathan Corbet 2 siblings, 1 reply; 25+ messages in thread From: Takashi Iwai @ 2017-06-26 5:58 UTC (permalink / raw) To: Jiri Kosina; +Cc: Mauro Carvalho Chehab, ksummit-discuss On Sun, 25 Jun 2017 22:56:07 +0200, Jiri Kosina wrote: > > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: > > > > There are pieces of .txt documentation falling into the "well-knows source of > > > information" category, with many references to them all over the Web. > > > kernel-parameters.txt is probably the most spectacular example here, but there > > > are others. > > > > > > Let us not move or rename these, please, or at least put symbolic links in > > > place to point to the new locations or similar, such that the existing WWW > > > links pointing to the documentation at kernel.org still work going forward. > > > > > > And if we have moved or renamed them already, can we possibly make these > > > links work again somehow? > > > > Agreed. We discussed in the past about two alternatives for those > > "well known" documents: > > > > 1) write a small text on the old file pointing to the > > new location; > > 2) use symlink. > > > > Right now, we're actually mixing (1) and (2). IMHO, we should either > > do (1) or (2). > > Unfortunately option (3) has also been applied to some of the files: > > $ ll Documentation/kernel-parameters.txt > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory > > I wasn't sure whether this was intentional or not. But if not, I'll > happily send a patch that introduces a symlink. If we do symlinks, wouldn't it be cleaner to separate the old doc directory from the new doc directory? That is, Documentation/* keeps the old txt or symlinks while the ReST is put in another directory, say, docs/* as originally suggested. thanks, Takashi ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 5:58 ` Takashi Iwai @ 2017-06-26 21:28 ` Rafael J. Wysocki 2017-06-27 8:41 ` Daniel Vetter 0 siblings, 1 reply; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-26 21:28 UTC (permalink / raw) To: Takashi Iwai Cc: Mauro Carvalho Chehab, Jiri Kosina, ksummit-discuss, ksummit-discuss On Monday, June 26, 2017 07:58:27 AM Takashi Iwai wrote: > On Sun, 25 Jun 2017 22:56:07 +0200, > Jiri Kosina wrote: > > > > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: > > > > > > There are pieces of .txt documentation falling into the "well-knows source of > > > > information" category, with many references to them all over the Web. > > > > kernel-parameters.txt is probably the most spectacular example here, but there > > > > are others. > > > > > > > > Let us not move or rename these, please, or at least put symbolic links in > > > > place to point to the new locations or similar, such that the existing WWW > > > > links pointing to the documentation at kernel.org still work going forward. > > > > > > > > And if we have moved or renamed them already, can we possibly make these > > > > links work again somehow? > > > > > > Agreed. We discussed in the past about two alternatives for those > > > "well known" documents: > > > > > > 1) write a small text on the old file pointing to the > > > new location; > > > 2) use symlink. > > > > > > Right now, we're actually mixing (1) and (2). IMHO, we should either > > > do (1) or (2). > > > > Unfortunately option (3) has also been applied to some of the files: > > > > $ ll Documentation/kernel-parameters.txt > > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory > > > > I wasn't sure whether this was intentional or not. But if not, I'll > > happily send a patch that introduces a symlink. > > If we do symlinks, wouldn't it be cleaner to separate the old doc > directory from the new doc directory? That is, Documentation/* keeps > the old txt or symlinks while the ReST is put in another directory, > say, docs/* as originally suggested. That actually sounds like a good idea to me. :-) Question is if it's not too late to do that now that we have all that stuff under Documentation/. Thanks, Rafael ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 21:28 ` Rafael J. Wysocki @ 2017-06-27 8:41 ` Daniel Vetter 2017-06-27 10:31 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 25+ messages in thread From: Daniel Vetter @ 2017-06-27 8:41 UTC (permalink / raw) To: Rafael J. Wysocki Cc: Mauro Carvalho Chehab, ksummit-discuss, ksummit-discuss, Jiri Kosina On Mon, Jun 26, 2017 at 11:28 PM, Rafael J. Wysocki <rjw@rjwysocki.net> wrote: > On Monday, June 26, 2017 07:58:27 AM Takashi Iwai wrote: >> On Sun, 25 Jun 2017 22:56:07 +0200, >> Jiri Kosina wrote: >> > >> > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: >> > >> > > > There are pieces of .txt documentation falling into the "well-knows source of >> > > > information" category, with many references to them all over the Web. >> > > > kernel-parameters.txt is probably the most spectacular example here, but there >> > > > are others. >> > > > >> > > > Let us not move or rename these, please, or at least put symbolic links in >> > > > place to point to the new locations or similar, such that the existing WWW >> > > > links pointing to the documentation at kernel.org still work going forward. >> > > > >> > > > And if we have moved or renamed them already, can we possibly make these >> > > > links work again somehow? >> > > >> > > Agreed. We discussed in the past about two alternatives for those >> > > "well known" documents: >> > > >> > > 1) write a small text on the old file pointing to the >> > > new location; >> > > 2) use symlink. >> > > >> > > Right now, we're actually mixing (1) and (2). IMHO, we should either >> > > do (1) or (2). >> > >> > Unfortunately option (3) has also been applied to some of the files: >> > >> > $ ll Documentation/kernel-parameters.txt >> > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory >> > >> > I wasn't sure whether this was intentional or not. But if not, I'll >> > happily send a patch that introduces a symlink. >> >> If we do symlinks, wouldn't it be cleaner to separate the old doc >> directory from the new doc directory? That is, Documentation/* keeps >> the old txt or symlinks while the ReST is put in another directory, >> say, docs/* as originally suggested. > > That actually sounds like a good idea to me. :-) > > Question is if it's not too late to do that now that we have all that stuff > under Documentation/. I think it's a bit late, at least from more documentation-active susbsystems like gpu/. The docbook->rst switch was pains, dealing once more with piles of renames isn't really something I'd like to do. And one of the main selling points of .rst was that it integrates much more smoothly into our existing pile of .txt docs, whereas the DocBook/ subdir was always a bit a ghetto. Forcing another split seems ill-advised to me. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-27 8:41 ` Daniel Vetter @ 2017-06-27 10:31 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 25+ messages in thread From: Mauro Carvalho Chehab @ 2017-06-27 10:31 UTC (permalink / raw) To: Daniel Vetter; +Cc: Jiri Kosina, ksummit-discuss, ksummit-discuss Em Tue, 27 Jun 2017 10:41:27 +0200 Daniel Vetter <daniel.vetter@ffwll.ch> escreveu: > On Mon, Jun 26, 2017 at 11:28 PM, Rafael J. Wysocki <rjw@rjwysocki.net> wrote: > > On Monday, June 26, 2017 07:58:27 AM Takashi Iwai wrote: > >> On Sun, 25 Jun 2017 22:56:07 +0200, > >> Jiri Kosina wrote: > >> > > >> > On Sat, 24 Jun 2017, Mauro Carvalho Chehab wrote: > >> > > >> > > > There are pieces of .txt documentation falling into the "well-knows source of > >> > > > information" category, with many references to them all over the Web. > >> > > > kernel-parameters.txt is probably the most spectacular example here, but there > >> > > > are others. > >> > > > > >> > > > Let us not move or rename these, please, or at least put symbolic links in > >> > > > place to point to the new locations or similar, such that the existing WWW > >> > > > links pointing to the documentation at kernel.org still work going forward. > >> > > > > >> > > > And if we have moved or renamed them already, can we possibly make these > >> > > > links work again somehow? > >> > > > >> > > Agreed. We discussed in the past about two alternatives for those > >> > > "well known" documents: > >> > > > >> > > 1) write a small text on the old file pointing to the > >> > > new location; > >> > > 2) use symlink. > >> > > > >> > > Right now, we're actually mixing (1) and (2). IMHO, we should either > >> > > do (1) or (2). > >> > > >> > Unfortunately option (3) has also been applied to some of the files: > >> > > >> > $ ll Documentation/kernel-parameters.txt > >> > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory > >> > > >> > I wasn't sure whether this was intentional or not. But if not, I'll > >> > happily send a patch that introduces a symlink. > >> > >> If we do symlinks, wouldn't it be cleaner to separate the old doc > >> directory from the new doc directory? That is, Documentation/* keeps > >> the old txt or symlinks while the ReST is put in another directory, > >> say, docs/* as originally suggested. > > > > That actually sounds like a good idea to me. :-) > > > > Question is if it's not too late to do that now that we have all that stuff > > under Documentation/. > > I think it's a bit late, at least from more documentation-active > susbsystems like gpu/. The docbook->rst switch was pains, dealing once > more with piles of renames isn't really something I'd like to do. And > one of the main selling points of .rst was that it integrates much > more smoothly into our existing pile of .txt docs, whereas the > DocBook/ subdir was always a bit a ghetto. Forcing another split seems > ill-advised to me. Yeah, while I would love that the docs dir would be just docs/, I also think it is a bit late. Well, renaming patches are actually handled nice by git (a way nicer than docbook->rst conversion), and shouldn't hurt that much. Still, all references by filename will require changes due to the directory change, both inside the Kernel and on website URLs). So, we may end needing to have another set of symlinks. Thanks, Mauro ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-25 20:56 ` Jiri Kosina 2017-06-26 1:20 ` Mauro Carvalho Chehab 2017-06-26 5:58 ` Takashi Iwai @ 2017-06-26 22:18 ` Jonathan Corbet 2017-06-27 18:42 ` Bird, Timothy 2017-06-28 19:48 ` Geert Uytterhoeven 2 siblings, 2 replies; 25+ messages in thread From: Jonathan Corbet @ 2017-06-26 22:18 UTC (permalink / raw) To: Jiri Kosina; +Cc: Mauro Carvalho Chehab, ksummit-discuss On Sun, 25 Jun 2017 22:56:07 +0200 (CEST) Jiri Kosina <jkosina@suse.cz> wrote: > Unfortunately option (3) has also been applied to some of the files: > > $ ll Documentation/kernel-parameters.txt > ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory > > I wasn't sure whether this was intentional or not. But if not, I'll > happily send a patch that introduces a symlink. Worries about moving well-known files are why I delayed some of this stuff a bit so I could bring it up at conferences and the kernel summit. It only proceeded after I didn't get any real pushback in those settings. In general, we move files around in the kernel tree all the time. We don't normally leave symlinks behind; indeed, we never do. Instead, we figure out where the file moved to and get on with life. Are documentation files somehow different, needing different rules in this regard? I wouldn't mind some clarity on that point. My hope (cue inspirational music here) is that, someday, it will be possible to type "ls Documentation" and get back a reasonably sized listing that is easy to explore. Let's just say that's not the situation at the moment. Getting there will certainly involve moving files around; replacing them with symlinks or pointer files would, to a real extent, defeat the purpose. jon ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 22:18 ` Jonathan Corbet @ 2017-06-27 18:42 ` Bird, Timothy 2017-06-28 19:48 ` Geert Uytterhoeven 1 sibling, 0 replies; 25+ messages in thread From: Bird, Timothy @ 2017-06-27 18:42 UTC (permalink / raw) To: Jonathan Corbet, Jiri Kosina; +Cc: Mauro Carvalho Chehab, ksummit-discuss > -----Original Message----- > From: Jonathan Corbet on Monday, June 26, 2017 3:18 PM > On Sun, 25 Jun 2017 22:56:07 +0200 (CEST) > Jiri Kosina <jkosina@suse.cz> wrote: > > > Unfortunately option (3) has also been applied to some of the files: > > > > $ ll Documentation/kernel-parameters.txt > > ls: cannot access 'Documentation/kernel-parameters.txt': No such > file or directory > > > > I wasn't sure whether this was intentional or not. But if not, I'll > > happily send a patch that introduces a symlink. > > Worries about moving well-known files are why I delayed some of this stuff > a bit so I could bring it up at conferences and the kernel summit. It > only proceeded after I didn't get any real pushback in those settings. > > In general, we move files around in the kernel tree all the time. We > don't normally leave symlinks behind; indeed, we never do. Instead, we > figure out where the file moved to and get on with life. Are > documentation files somehow different, needing different rules in this > regard? I wouldn't mind some clarity on that point. My 2 cents is that files in Documentation are much more often linked to or referenced by things outside the kernel tree, than source code is. A quick perusal of elinux.org shows a fair number of references to text files under Documentation, some with direct links to online git trees. Documentation/SubmittingPatches is a good example. This one has a "This file has moved..." line in its content, which I believe suffices for getting people to the right place. IMHO that's better than a symlink, at least for web references. > > My hope (cue inspirational music here) is that, someday, it will be > possible to type "ls Documentation" and get back a reasonably sized > listing that is easy to explore. Let's just say that's not the situation > at the moment. Getting there will certainly involve moving files around; > replacing them with symlinks or pointer files would, to a real extent, > defeat the purpose. I like the suggestion by Takashi Iwai to separate the new docs from the old, putting symlinks and leaving legacy (not-yet-converted) docs in Documentation, and new stuff in 'docs/*'. I think that the new docs have not been 'pinned' yet by external references, and could still be moved around (in the short term), without much pain. Then "ls docs" could produce the nice listing, while "ls Documentation" would show ugly symlinks, placeholders, and legacy junk. -- Tim ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 22:18 ` Jonathan Corbet 2017-06-27 18:42 ` Bird, Timothy @ 2017-06-28 19:48 ` Geert Uytterhoeven 1 sibling, 0 replies; 25+ messages in thread From: Geert Uytterhoeven @ 2017-06-28 19:48 UTC (permalink / raw) To: Jonathan Corbet; +Cc: Mauro Carvalho Chehab, Jiri Kosina, ksummit-discuss Hi Jon, On Tue, Jun 27, 2017 at 12:18 AM, Jonathan Corbet <corbet@lwn.net> wrote: > On Sun, 25 Jun 2017 22:56:07 +0200 (CEST) > Jiri Kosina <jkosina@suse.cz> wrote: >> Unfortunately option (3) has also been applied to some of the files: >> >> $ ll Documentation/kernel-parameters.txt >> ls: cannot access 'Documentation/kernel-parameters.txt': No such file or directory >> >> I wasn't sure whether this was intentional or not. But if not, I'll >> happily send a patch that introduces a symlink. > > Worries about moving well-known files are why I delayed some of this stuff > a bit so I could bring it up at conferences and the kernel summit. It > only proceeded after I didn't get any real pushback in those settings. > > In general, we move files around in the kernel tree all the time. We > don't normally leave symlinks behind; indeed, we never do. Instead, we > figure out where the file moved to and get on with life. Are > documentation files somehow different, needing different rules in this > regard? I wouldn't mind some clarity on that point. Documentation files are special in that they (some of them) are much more likely to be linked from an external web page, and may be read by mere mortals. My gut feeling says this is mostly limited to SubmittingPatches and CodingStyle, which are (coincidently?) the only two files in the top level using CamelCase. Source files are mostly used by developers, who don't rely on external links, and who are used to work with the source file hierarchy on a regular basis. Gr{oetje,eeting}s, Geert -- Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds ^ permalink raw reply [flat|nested] 25+ messages in thread
[parent not found: <CAFhKne8ZttmqWYJToCw9EDywzeMdp=eiFpoZ+O5xrzmKnpA09Q@mail.gmail.com>]
[parent not found: <CAFhKne_W-EbjUd_Cm4kyBHrVK6K9r8Ss3gY0ogO1nztbQZYBEg@mail.gmail.com>]
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues [not found] ` <CAFhKne_W-EbjUd_Cm4kyBHrVK6K9r8Ss3gY0ogO1nztbQZYBEg@mail.gmail.com> @ 2017-06-25 21:32 ` Matthew Wilcox 2017-06-25 21:42 ` Rafael J. Wysocki 2017-06-26 0:58 ` Mauro Carvalho Chehab 0 siblings, 2 replies; 25+ messages in thread From: Matthew Wilcox @ 2017-06-25 21:32 UTC (permalink / raw) To: Mauro Carvalho Chehab; +Cc: ksummit-discuss [-- Attachment #1: Type: text/plain, Size: 753 bytes --] I find documentation comes in the following bins: 1. User documentation (possible sub-split into "how to use this from kernel space" and "how to use this from user space") 2. Information for someone who's interested in modifying the code. Possibly including architectural considerations (eg locking), performance, ideas for future improvement, etc. 3. Random swearing and abuse I think the second and third categories of documentation should be kept out of the kernel books and left as plain comments by the code. On 24 Jun 2017 9:41 am, "Mauro Carvalho Chehab" <mchehab@s-opensource.com> wrote: Yeah, one of the problems with existing documentation is that, sometimes, the same document describes both userspace-relevant info and kernelspace APIs. [-- Attachment #2: Type: text/html, Size: 1354 bytes --] ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-25 21:32 ` Matthew Wilcox @ 2017-06-25 21:42 ` Rafael J. Wysocki 2017-06-26 1:15 ` Mauro Carvalho Chehab 2017-06-26 0:58 ` Mauro Carvalho Chehab 1 sibling, 1 reply; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-25 21:42 UTC (permalink / raw) To: Matthew Wilcox, Mauro Carvalho Chehab; +Cc: ksummit-discuss On Sunday, June 25, 2017 05:32:31 PM Matthew Wilcox wrote: > I find documentation comes in the following bins: > > 1. User documentation (possible sub-split into "how to use this from kernel > space" and "how to use this from user space") > 2. Information for someone who's interested in modifying the code. Possibly > including architectural considerations (eg locking), performance, ideas for > future improvement, etc. > 3. Random swearing and abuse There also is information on various frameworks that driver writers are expected to use and honestly various mixtures of that with 1. above. Mutual exclusion mechanisms also need to be documented properly IMO and so on. > I think the second and third categories of documentation should be kept out > of the kernel books and left as plain comments by the code. > > On 24 Jun 2017 9:41 am, "Mauro Carvalho Chehab" <mchehab@s-opensource.com> > wrote: > > Yeah, one of the problems with existing documentation is that, > sometimes, the same document describes both userspace-relevant > info and kernelspace APIs. Right. But, alas, those things happen to be related, especially when framework-provided sysfs attributes and similar come into play. With the current layout of things it sometimes is hard to avoid documenting the same thing in two different places, risking that the two descriptions of the same thing will diverge in the future eventually. Moreover, does debugfs fall into "user documentation" or "developer documentation", for example? And generally documentation on how to diagnose problems for that matter? ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-25 21:42 ` Rafael J. Wysocki @ 2017-06-26 1:15 ` Mauro Carvalho Chehab 2017-06-26 21:16 ` Rafael J. Wysocki 0 siblings, 1 reply; 25+ messages in thread From: Mauro Carvalho Chehab @ 2017-06-26 1:15 UTC (permalink / raw) To: Rafael J. Wysocki; +Cc: ksummit-discuss Em Sun, 25 Jun 2017 23:42:20 +0200 "Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu: > On Sunday, June 25, 2017 05:32:31 PM Matthew Wilcox wrote: > > I find documentation comes in the following bins: > > > > 1. User documentation (possible sub-split into "how to use this from kernel > > space" and "how to use this from user space") > > 2. Information for someone who's interested in modifying the code. Possibly > > including architectural considerations (eg locking), performance, ideas for > > future improvement, etc. > > 3. Random swearing and abuse > > There also is information on various frameworks that driver writers are expected > to use and honestly various mixtures of that with 1. above. > > Mutual exclusion mechanisms also need to be documented properly IMO and so on. > > > I think the second and third categories of documentation should be kept out > > of the kernel books and left as plain comments by the code. > > > > On 24 Jun 2017 9:41 am, "Mauro Carvalho Chehab" <mchehab@s-opensource.com> > > wrote: > > > > Yeah, one of the problems with existing documentation is that, > > sometimes, the same document describes both userspace-relevant > > info and kernelspace APIs. > > Right. > > But, alas, those things happen to be related, especially when framework-provided > sysfs attributes and similar come into play. With the current layout of things > it sometimes is hard to avoid documenting the same thing in two different > places, risking that the two descriptions of the same thing will diverge in the > future eventually. > Well, sysfs attribute description is currently a little messy, IMHO. We have (or should have) all of them described under Documentation/ABI/, but it is not uncommon to have them described on some other random places. As things get bitrot, we end by having different descriptions on each place. I also suspect that some sysfs descriptions are only outside Documentation/ABI/ (although I never actually tried to seek for such issue). > Moreover, does debugfs fall into "user documentation" or "developer documentation", > for example? > > And generally documentation on how to diagnose problems for that matter? The same thing for sysfs applies to debugfs. IMHO, debugfs and information about how to diagnose problems belong to "user documentation" / "how to use this from user space" (using Matthew's classification), in the sense that an advanced admin may use them, in order to properly address some issue that will eventually generate a bug report (either for Kernel or to some application/library). Thanks, Mauro ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 1:15 ` Mauro Carvalho Chehab @ 2017-06-26 21:16 ` Rafael J. Wysocki 0 siblings, 0 replies; 25+ messages in thread From: Rafael J. Wysocki @ 2017-06-26 21:16 UTC (permalink / raw) To: Mauro Carvalho Chehab; +Cc: ksummit-discuss On Sunday, June 25, 2017 10:15:46 PM Mauro Carvalho Chehab wrote: > Em Sun, 25 Jun 2017 23:42:20 +0200 > "Rafael J. Wysocki" <rjw@rjwysocki.net> escreveu: > > > On Sunday, June 25, 2017 05:32:31 PM Matthew Wilcox wrote: > > > I find documentation comes in the following bins: > > > > > > 1. User documentation (possible sub-split into "how to use this from kernel > > > space" and "how to use this from user space") > > > 2. Information for someone who's interested in modifying the code. Possibly > > > including architectural considerations (eg locking), performance, ideas for > > > future improvement, etc. > > > 3. Random swearing and abuse > > > > There also is information on various frameworks that driver writers are expected > > to use and honestly various mixtures of that with 1. above. > > > > Mutual exclusion mechanisms also need to be documented properly IMO and so on. > > > > > I think the second and third categories of documentation should be kept out > > > of the kernel books and left as plain comments by the code. > > > > > > On 24 Jun 2017 9:41 am, "Mauro Carvalho Chehab" <mchehab@s-opensource.com> > > > wrote: > > > > > > Yeah, one of the problems with existing documentation is that, > > > sometimes, the same document describes both userspace-relevant > > > info and kernelspace APIs. > > > > Right. > > > > But, alas, those things happen to be related, especially when framework-provided > > sysfs attributes and similar come into play. With the current layout of things > > it sometimes is hard to avoid documenting the same thing in two different > > places, risking that the two descriptions of the same thing will diverge in the > > future eventually. > > > > Well, sysfs attribute description is currently a little messy, IMHO. > We have (or should have) all of them described under Documentation/ABI/, > but it is not uncommon to have them described on some other random > places. As things get bitrot, we end by having different descriptions > on each place. > > I also suspect that some sysfs descriptions are only outside > Documentation/ABI/ (although I never actually tried to seek for such > issue). That would be my guess too, although I don't remember any specific examples readily. My point is that some frameworks expose things via sysfs and drivers are expected to provide callbacks invoked from there or similar. The information on what is expected to be provided falls under the "driver API", but it is strictly related to the "admin guide" part as well. > > Moreover, does debugfs fall into "user documentation" or "developer documentation", > > for example? > > > > And generally documentation on how to diagnose problems for that matter? > > The same thing for sysfs applies to debugfs. > > IMHO, debugfs and information about how to diagnose problems > belong to "user documentation" / "how to use this from user space" > (using Matthew's classification), in the sense that an advanced > admin may use them, in order to properly address some issue that > will eventually generate a bug report (either for Kernel or to some > application/library). It also is part of driver developer's toolkit, however, like unit tests and such. Thanks, Rafael ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-25 21:32 ` Matthew Wilcox 2017-06-25 21:42 ` Rafael J. Wysocki @ 2017-06-26 0:58 ` Mauro Carvalho Chehab 1 sibling, 0 replies; 25+ messages in thread From: Mauro Carvalho Chehab @ 2017-06-26 0:58 UTC (permalink / raw) To: Matthew Wilcox; +Cc: ksummit-discuss Em Sun, 25 Jun 2017 17:32:31 -0400 Matthew Wilcox <willy6545@gmail.com> escreveu: > I find documentation comes in the following bins: > > 1. User documentation (possible sub-split into "how to use this from kernel > space" and "how to use this from user space") > 2. Information for someone who's interested in modifying the code. Possibly > including architectural considerations (eg locking), performance, ideas for > future improvement, etc. > 3. Random swearing and abuse > > I think the second and third categories of documentation should be kept out > of the kernel books and left as plain comments by the code. Having comments together the code is good, but sometimes it is not enough. Just as an example, last week I received two patch series, from different developers, that didn't get right how to collect quality measurements from digital TV frontends. The functions they use are documented via kernel-doc, and they looked on other drivers as examples. Still, that was not not clear enough, as both developers didn't quite get some things. So, I had to write a few patches to actually explain how a frontend driver is expected to collect statistics: https://patchwork.linuxtv.org/patch/42081/ And, today, I complemented with two additional texts: https://patchwork.linuxtv.org/patch/42115/ https://patchwork.linuxtv.org/patch/42116/ As those explanations complement the kernel-doc macros from dvb_frontend.h, they need cross references, in order for the driver developer to better understand how things are connected, and to avoid the need of having to explain everything that it is already documented via kernel-doc tags, as can be seeing at: https://www.infradead.org/~mchehab/kernel_docs/media/kapi/dtv-core.html#digital-tv-frontend-kabi That's just today's example. There are plenty of cases where we need to add images and complex tables, etc that just don't fit well as plain text. Thanks, Mauro ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-24 12:20 ` Rafael J. Wysocki 2017-06-24 13:41 ` Mauro Carvalho Chehab @ 2017-06-25 16:13 ` Jonathan Corbet 1 sibling, 0 replies; 25+ messages in thread From: Jonathan Corbet @ 2017-06-25 16:13 UTC (permalink / raw) To: Rafael J. Wysocki; +Cc: Mauro Carvalho Chehab, ksummit-discuss On Sat, 24 Jun 2017 14:20:40 +0200 "Rafael J. Wysocki" <rjw@rjwysocki.net> wrote: > At the same time I think it would be good to take that as an opportinity to > improve the *content* of the documentation files as well, so not just > convert them, but also make them more up to date etc in the process. This is certainly an area of ongoing concern. There has been a fair amount of energy put into the transition, which is great, but if it comes down to "make a bunch of crufty old stuff look better with cross-references to other crufty old stuff", it's not that big a win. My hope, I guess, is that making the documentation more coherent and approachable will inspire more people to also work to make it better. jon ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-23 18:39 [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues Jonathan Corbet 2017-06-23 23:09 ` Rafael J. Wysocki 2017-06-24 10:46 ` Mauro Carvalho Chehab @ 2017-06-26 12:19 ` Mark Brown 2017-06-27 8:38 ` Daniel Vetter 2 siblings, 1 reply; 25+ messages in thread From: Mark Brown @ 2017-06-26 12:19 UTC (permalink / raw) To: Jonathan Corbet; +Cc: ksummit-discuss [-- Attachment #1: Type: text/plain, Size: 1458 bytes --] On Fri, Jun 23, 2017 at 12:39:36PM -0600, Jonathan Corbet wrote: > I can continue in this mode, but I do wonder if there's a better way out > there somewhere. So I think there would be value in a session on the > maintenance of "subsystems" that don't fit neatly into the kernel > source-tree hierarchy. One thing I think it'd be good to do is work out a sensible way of keeping the maintainers of the relevant subsystems in the loop on things - a combination of the mechanics and how much effort we want to put into making sure people have at least seen things. For example it looks like the regulator DocBook got converted to RST without me being aware of it (it seems I did get copied on one mail at some point but I can't have read it and there don't seem to have been any resends), that case isn't a problem itself but it seems like an area where things could end up not running smoothly. I know I rely fairly heavily on subject lines to filter what I'm looking at since some of my subsystems mean that I get copied on lots of random stuff that's of at most passing relevance to me which ends up being an issue with things like DT bindings sometimes (I think this is also part of what went wrong with the regulator conversion) but that doesn't scale since the subject lines can't easily be useful for multiple subsystems simultaneously. I'm not sure what else to do though, we basically only have the subject lines and CC lists to work with here. [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 488 bytes --] ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-26 12:19 ` Mark Brown @ 2017-06-27 8:38 ` Daniel Vetter 2017-06-27 15:33 ` Mark Brown 0 siblings, 1 reply; 25+ messages in thread From: Daniel Vetter @ 2017-06-27 8:38 UTC (permalink / raw) To: Mark Brown; +Cc: ksummit-discuss On Mon, Jun 26, 2017 at 2:19 PM, Mark Brown <broonie@kernel.org> wrote: > On Fri, Jun 23, 2017 at 12:39:36PM -0600, Jonathan Corbet wrote: > >> I can continue in this mode, but I do wonder if there's a better way out >> there somewhere. So I think there would be value in a session on the >> maintenance of "subsystems" that don't fit neatly into the kernel >> source-tree hierarchy. > > One thing I think it'd be good to do is work out a sensible way of > keeping the maintainers of the relevant subsystems in the loop on things > - a combination of the mechanics and how much effort we want to put into > making sure people have at least seen things. For example it looks like > the regulator DocBook got converted to RST without me being aware of it > (it seems I did get copied on one mail at some point but I can't have > read it and there don't seem to have been any resends), that case isn't > a problem itself but it seems like an area where things could end up not > running smoothly. > > I know I rely fairly heavily on subject lines to filter what I'm looking > at since some of my subsystems mean that I get copied on lots of random > stuff that's of at most passing relevance to me which ends up being an > issue with things like DT bindings sometimes (I think this is also part > of what went wrong with the regulator conversion) but that doesn't > scale since the subject lines can't easily be useful for multiple > subsystems simultaneously. I'm not sure what else to do though, we > basically only have the subject lines and CC lists to work with here. Looking at MAINTAINERS, there's relatively few entries for files under Documentation/, and most are for individual files (about 450). None are for one of the remaining DocBook files still in 4.12 afaics. I think we can fix this problem by making sure that a) docs are sorted usefully into directories (e.g. we put all the gpu stuff into Documentation/gpu/) and b) there's MAINTAINERS entries for all of them (which atm doesn't seem to be the case for a lot of stuff). But I think the lack of clear maintainer responsibilities for docs was something Jon already brough up at the previous KS, and we didn't really get anywhere with it. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch ^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues 2017-06-27 8:38 ` Daniel Vetter @ 2017-06-27 15:33 ` Mark Brown 0 siblings, 0 replies; 25+ messages in thread From: Mark Brown @ 2017-06-27 15:33 UTC (permalink / raw) To: Daniel Vetter; +Cc: ksummit-discuss [-- Attachment #1: Type: text/plain, Size: 1072 bytes --] On Tue, Jun 27, 2017 at 10:38:54AM +0200, Daniel Vetter wrote: > Looking at MAINTAINERS, there's relatively few entries for files under > Documentation/, and most are for individual files (about 450). None > are for one of the remaining DocBook files still in 4.12 afaics. I > think we can fix this problem by making sure that a) docs are sorted > usefully into directories (e.g. we put all the gpu stuff into > Documentation/gpu/) and b) there's MAINTAINERS entries for all of them > (which atm doesn't seem to be the case for a lot of stuff). Yeah, there's directories there for my subsystems but I have to confess I'd not checked the broader picture recently. > But I think the lack of clear maintainer responsibilities for docs was > something Jon already brough up at the previous KS, and we didn't > really get anywhere with it. Is that a case of people actively getting in the way somehow or more a case that we're not able to generate enough interest for people to actually work on improving the docs (which is partly about us showing that we care of course)? [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 488 bytes --] ^ permalink raw reply [flat|nested] 25+ messages in thread
end of thread, other threads:[~2017-06-28 19:48 UTC | newest] Thread overview: 25+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-06-23 18:39 [Ksummit-discuss] [MAINTAINERS SUMMIT] Documentation issues Jonathan Corbet 2017-06-23 23:09 ` Rafael J. Wysocki 2017-06-24 12:03 ` Rafael J. Wysocki 2017-06-24 10:46 ` Mauro Carvalho Chehab 2017-06-24 12:20 ` Rafael J. Wysocki 2017-06-24 13:41 ` Mauro Carvalho Chehab 2017-06-25 20:56 ` Jiri Kosina 2017-06-26 1:20 ` Mauro Carvalho Chehab 2017-06-26 21:18 ` Rafael J. Wysocki 2017-06-26 5:58 ` Takashi Iwai 2017-06-26 21:28 ` Rafael J. Wysocki 2017-06-27 8:41 ` Daniel Vetter 2017-06-27 10:31 ` Mauro Carvalho Chehab 2017-06-26 22:18 ` Jonathan Corbet 2017-06-27 18:42 ` Bird, Timothy 2017-06-28 19:48 ` Geert Uytterhoeven [not found] ` <CAFhKne8ZttmqWYJToCw9EDywzeMdp=eiFpoZ+O5xrzmKnpA09Q@mail.gmail.com> [not found] ` <CAFhKne_W-EbjUd_Cm4kyBHrVK6K9r8Ss3gY0ogO1nztbQZYBEg@mail.gmail.com> 2017-06-25 21:32 ` Matthew Wilcox 2017-06-25 21:42 ` Rafael J. Wysocki 2017-06-26 1:15 ` Mauro Carvalho Chehab 2017-06-26 21:16 ` Rafael J. Wysocki 2017-06-26 0:58 ` Mauro Carvalho Chehab 2017-06-25 16:13 ` Jonathan Corbet 2017-06-26 12:19 ` Mark Brown 2017-06-27 8:38 ` Daniel Vetter 2017-06-27 15:33 ` Mark Brown
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.