Re: Proposing help for documentation
On 02/11/16 17:01, Mauro Carvalho Chehab wrote: > Em Wed, 02 Nov 2016 16:05:13 + > Luis de Bethencourt <lui...@osg.samsung.com> escreveu: > >> On 02/11/16 10:41, Jani Nikula wrote: >>> On Wed, 02 Nov 2016, Luis de Bethencourt <lui...@osg.samsung.com> wrote: >>>> I also offer my help, let me know if you see anything I can do. >>> >>> Luis, Patrice, anyone else out there willing to help: here's a list of >>> stuff to do, off the top of my head. I'm sure Jon will amend this. >>> >>> 0) Some basics first >>> >>> Subscribe to linux-doc. Read it. >> >> Subscribed for a while. Reading it more close now. >> >>> >>> Read https://lwn.net/Articles/692705/ and >>> https://lwn.net/Articles/704613/ if you haven't already. >>> >> >> Done. > > I also wrote a series of articles at: > https://blogs.s-osg.org/new-improved-linux-kernel-media-documentation/ > > I intend to write also some articles there about PDF, with seems really > tricky to get it right on Sphinx. > Great series of articles. Thanks Mauro! Please write more about PDF. >> >>> Figure out how to build the documentation. Read the part about writing >>> kernel documentation. Also at >>> http://static.lwn.net/kerneldoc/kernel-documentation.html. >>> >>> For most things under Documentation, you'll want to use the docs-next >>> branch of git://git.lwn.net/linux.git. That has the latest stuff. If you >>> use Linus' master, you'll be working on old stuff. >>> >>> For fixing kernel-doc source code comments, you'll need to use the >>> appropriate subsystem tree, see MAINTAINERS. >>> >>> In any case, most changes need to be sent to both linux-doc and the >>> relevant subsystem/driver mailing list. See MAINTAINERS and >>> scripts/get_maintainer.pl. >>> >>> Whatever you do, don't spend forever polishing it privately. Otherwise >>> someone might beat you to it, and effort will be wasted. Read the list, >>> maybe someone's already posted patches that just haven't been merged >>> yet. >> >> Great summary of the development process. >> >>> >>> 1) Build documentation. Look at errors during build, fix them. >>> >>> Some of the issues come from source code comments via the kernel-doc >>> extension; those changes need to go through the appropriate subsystem, >>> not via the documentation tree. Watch out, some of the things may have >>> been fixed in the subsystem repo already. >>> >>> 2) Build documentation. Read the output, fix issues, improve the >>> language, improve the presentation. Ditto about source code comments. >>> >>> Personally, I think this is both very important and unfortunately >>> laborous, because this is mostly stuff that Sphinx won't warn about. >>> > > I'd complement that you should test the output also for PDF... There are > some special tags and, sometimes some spells to make it work. > I see in the patches sent to this mailing list that there are some build problems with PDF. >> It is also more rewarding because newcomers get to learn by reading the >> docs, while also contributing. Win win. >> >>> 3) Look at documentation patches on linux-doc, review them, test them, >>> give feedback. >>> >> >> I sent this yesterday, mind reviewing it? >> http://www.spinics.net/lists/linux-doc/msg41297.html > > Nothing wrong with the above patch, but, IMHO, it would be better to > only fix such typos on files already converted to ReST, as otherwise > it could conflict with a patch with someone else would be doing such > conversion. Just my 2 cents. > > In time: I'm not touching at Documentation/usb.tmpl, or on any other > DocBook document. > That's a good point. Will keep fixes to the rst files. >>> 4) Convert DocBook templates under Documentation/DocBook to Sphinx. >>> >>> The conversion is actually the easy part; figuring out whether the >>> documentation is still relevant and where to stick it in the Sphinx >>> build is harder. Jon may have some vision on this, but personally I'd >>> like to obliterate DocBook first, and then figure out what to do with >>> the resulting converted rst documents. > > Markus has a script with helps with such conversion. I guess he actually > has conversion for everything, but you'll need to dig into the kernel-doc > markups, as some will break after the conversion. > >>> >> >> Wil
Re: Proposing help for documentation
On 02/11/16 10:41, Jani Nikula wrote: > On Wed, 02 Nov 2016, Luis de Bethencourt <lui...@osg.samsung.com> wrote: >> I also offer my help, let me know if you see anything I can do. > > Luis, Patrice, anyone else out there willing to help: here's a list of > stuff to do, off the top of my head. I'm sure Jon will amend this. > > 0) Some basics first > > Subscribe to linux-doc. Read it. Subscribed for a while. Reading it more close now. > > Read https://lwn.net/Articles/692705/ and > https://lwn.net/Articles/704613/ if you haven't already. > Done. > Figure out how to build the documentation. Read the part about writing > kernel documentation. Also at > http://static.lwn.net/kerneldoc/kernel-documentation.html. > > For most things under Documentation, you'll want to use the docs-next > branch of git://git.lwn.net/linux.git. That has the latest stuff. If you > use Linus' master, you'll be working on old stuff. > > For fixing kernel-doc source code comments, you'll need to use the > appropriate subsystem tree, see MAINTAINERS. > > In any case, most changes need to be sent to both linux-doc and the > relevant subsystem/driver mailing list. See MAINTAINERS and > scripts/get_maintainer.pl. > > Whatever you do, don't spend forever polishing it privately. Otherwise > someone might beat you to it, and effort will be wasted. Read the list, > maybe someone's already posted patches that just haven't been merged > yet. Great summary of the development process. > > 1) Build documentation. Look at errors during build, fix them. > > Some of the issues come from source code comments via the kernel-doc > extension; those changes need to go through the appropriate subsystem, > not via the documentation tree. Watch out, some of the things may have > been fixed in the subsystem repo already. > > 2) Build documentation. Read the output, fix issues, improve the > language, improve the presentation. Ditto about source code comments. > > Personally, I think this is both very important and unfortunately > laborous, because this is mostly stuff that Sphinx won't warn about. > It is also more rewarding because newcomers get to learn by reading the docs, while also contributing. Win win. > 3) Look at documentation patches on linux-doc, review them, test them, > give feedback. > I sent this yesterday, mind reviewing it? http://www.spinics.net/lists/linux-doc/msg41297.html > 4) Convert DocBook templates under Documentation/DocBook to Sphinx. > > The conversion is actually the easy part; figuring out whether the > documentation is still relevant and where to stick it in the Sphinx > build is harder. Jon may have some vision on this, but personally I'd > like to obliterate DocBook first, and then figure out what to do with > the resulting converted rst documents. > Will wait in case Jon wants to add his opinion on this. > 5) Convert .txt files under Documentation to .rst. > > There are caveats here. Not everything needs to be converted. Some of > the stuff is obsolete, and converting might be wasted effort. Just > converting without updating to reflect current kernels is hazardous, > because the obsolete information will then be more accessible with the > converted documentation on the web. > > People like plain text, don't go overboard with rst markup. Use > discretion. > > > For both 4) and 5) I'd really like the seasoned kernel devs to actively > hand out stuff to willing new hands. > This is a great point. Greg and others worry about the rising barrier of entry to contribute to the kernel. This would be a great thing to hand out to newcomers. I am personally interested if any seasoned maintainers are reading this. > > HTH, > Jani. > Thank you so much for the thorough list Jani. Much appreciated. Luis -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Proposing help for documentation
On 01/11/16 21:52, Patrice wrote: > On Tue, Nov 1, 2016 at 5:40 PM, Luis de Bethencourt > <lui...@osg.samsung.com> wrote: >> On 01/11/16 19:35, Patrice wrote: >>> Following on Jonathan Corbet article on LWN, I'd like to propose my >>> help for the documentation. >>> >>> I'm a software developer, not much of a kernel or system dev though, >>> even if I've done a bit, but I know my way around the kernel and >>> source, I have studied it for a pretty long time, out of personal >>> interest. >>> >>> I can help anywhere you see fit. >>> >>> Patrice >> >> Which article on LWN is this? I feel like I missed it. >> >> Luis >> > > https://lwn.net/Articles/704613/ > > It's this week edition so for subscribers, but it will be online in a > few days I think for non-subscribers. > I missed it! "Documentation/ is a long name, and is the only top-level directory in the kernel starting with a capital letter. One can joke that this distinction highlights the importance of documentation" Hahahaaa Great read. Thanks Patrice. Jonathan, I also offer my help, let me know if you see anything I can do. I will follow this mailing list more closely now. Thanks, Luis -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Proposing help for documentation
On 01/11/16 19:35, Patrice wrote: > Following on Jonathan Corbet article on LWN, I'd like to propose my > help for the documentation. > > I'm a software developer, not much of a kernel or system dev though, > even if I've done a bit, but I know my way around the kernel and > source, I have studied it for a pretty long time, out of personal > interest. > > I can help anywhere you see fit. > > Patrice Which article on LWN is this? I feel like I missed it. Luis -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] USB: fix typo in documentation
A typo sneaked in the latest change on the USB documentation. Fixing it and also a trailing whitespace since it is also in the "USB Host-Side API Model" chapter. Signed-off-by: Luis de Bethencourt <lui...@osg.samsung.com> --- Documentation/DocBook/usb.tmpl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 8ec4d59..e322691 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -160,7 +160,7 @@ In theory, all HCDs provide the same functionality through the same API. In practice, that's becoming mostly true, but there are still differences that crop up especially with -fault handling on the less common controllers. +fault handling on the less common controllers. Different controllers don't necessarily report the same aspects of failures, and recovery from faults (including software-induced ones like unlinking an URB) isn't yet fully @@ -168,7 +168,7 @@ Device driver authors should make a point of doing disconnect testing (while the device is active) with each different host controller driver, to make sure drivers don't have bugs of -thei1r own as well as to make sure they aren't relying on some +their own as well as to make sure they aren't relying on some HCD-specific behavior. -- 2.8.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 2/5] Documentation: update Michael K. Johnson's work
The URL for "Writing Linux Device Drivers" hasn't been available in some time. Updating the entry to Michael K. Johnson's "Linux Kernel Hackers' Guide" Signed-off-by: Luis de Bethencourt <lui...@osg.samsung.com> --- Hi, I agree with Jon that changing the URL to a different work of the same author isn't the best idea. The three options we have IMHO are: - replace the entry with KHG (the patch below) - remove the entry altogether if the KHG is not interesting to be listed - leave "Writing Linux Device Drivers" as is with the broken URL so people can try to find the document elsewhere. I didn't manage to find it. Thanks, Luis Documentation/kernel-docs.txt | 16 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index fe217c1..b3af71e 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -194,15 +194,15 @@ simple---most of the complexity (other than talking to the hardware) involves managing network packets in memory". - * Title: "Writing Linux Device Drivers" + * Title: "Linux Kernel Hackers' Guide" Author: Michael K. Johnson. - URL: http://users.evitech.fi/~tk/rtos/writing_linux_device_d.html - Keywords: files, VFS, file operations, kernel interface, character - vs block devices, I/O access, hardware interrupts, DMA, access to - user memory, memory allocation, timers. - Description: Introductory 50-minutes (sic) tutorial on writing - device drivers. 12 pages written by the same author of the "Kernel - Hackers' Guide" which give a very good overview of the topic. + URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. * Title: "The Venus kernel interface" Author: Peter J. Braam. -- 2.5.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 5/5] Documentation: update URL for Porting Linux 2.0 Drivers to 2.2
On 31/03/16 07:52, Jonathan Corbet wrote: > On Sat, 19 Mar 2016 12:51:24 + > Luis de Bethencourt <lui...@osg.samsung.com> wrote: > >> - URL: http://www.linux-mag.com/1999-05/gear_01.html >> + URL: http://www.linux-mag.com/id/216/ > > So this URL doesn't appear to work for me..? > > Thanks, > > jon > I tried here and it works, but maybe it is flacky and it isn't permanently available. Dropping the patch if that is the case. Thanks for looking at it Jon :) Luis -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/5] Documentation: update URL for Michael K. Johnson's articles
On 19/03/16 12:51, Luis de Bethencourt wrote: > The URL for "Writing Linux Device Drivers" hasn't been available in some > time. Updating it to the URL of Michael K. Johnson's "Linux Kernel Hackers' > Guide" > > Signed-off-by: Luis de Bethencourt <lui...@osg.samsung.com> > --- > Documentation/kernel-docs.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt > index b250360..9a1b0d3 100644 > --- a/Documentation/kernel-docs.txt > +++ b/Documentation/kernel-docs.txt > @@ -196,7 +196,7 @@ > > * Title: "Writing Linux Device Drivers" > Author: Michael K. Johnson. > - URL: http://users.evitech.fi/~tk/rtos/writing_linux_device_d.html > + URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html > Keywords: files, VFS, file operations, kernel interface, character > vs block devices, I/O access, hardware interrupts, DMA, access to > user memory, memory allocation, timers. > Hi, I separated the docs URL updates into individual commits so they can easily be cherry-picked. I am happy to squash them all into one if you think it is better. Thanks :) Luis -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 5/5] Documentation: update URL for Porting Linux 2.0 Drivers to 2.2
The URL format of Linux Magazine articles has changed. Updating the URL of the "Porting Linux 2.0 Drivers to Linux 2.2" article by Alan Cox. Signed-off-by: Luis de Bethencourt <lui...@osg.samsung.com> --- Documentation/kernel-docs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 04f6d73..bfca1ed 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -376,7 +376,7 @@ * Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New Features " Author: Alan Cox. - URL: http://www.linux-mag.com/1999-05/gear_01.html + URL: http://www.linux-mag.com/id/216/ Keywords: ports, porting. Description: Article from Linux Magazine on porting from 2.0 to 2.2 kernels. -- 2.5.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
