On 02/11/16 17:01, Mauro Carvalho Chehab wrote: > Em Wed, 02 Nov 2016 16:05:13 +0000 > Luis de Bethencourt <luisbg@xxxxxxxxxxxxxxx> escreveu: > >> On 02/11/16 10:41, Jani Nikula wrote: >>> On Wed, 02 Nov 2016, Luis de Bethencourt <luisbg@xxxxxxxxxxxxxxx> 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. > >>> >> >> 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 majordomo@xxxxxxxxxxxxxxx >> More majordomo info at http://vger.kernel.org/majordomo-info.html > > > > > Cheers, > Mauro > Thanks for your input Mauro, Luis -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
