Re: Proposing help for documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux