On Mon, Nov 28, 2016 at 12:54:13PM +0100, Peter Zijlstra wrote: > On Mon, Nov 28, 2016 at 09:08:55AM -0200, Mauro Carvalho Chehab wrote: > > - use *foo* (for italics) or **foo** (for bold) instead of _foo_; > > That's daft, and also you're wrong. The normal convention is: > > /italic/ > *bold* > _underlined_ I dont think anything is lost if we don't use the rst flavour but keep the traditional one. The html output meant for newbies looks a bit more funny, but if that means the old guard is more likely to type the docs then that's more than worth it. > > :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` > > That seems to work, as in 'gf' doesn't get confused by the spurious > characters attached. Is there any way to enforce that? > > > - if you have something that you want to use a monotonic font on > > PDF/LaTeX/HTML, use ``foo``. > > Bit weird, somewhere in the typewriter age they invented the " symbol so > we didn't have to type double quotes anymore. "Quote" just gives you a quote, not fixed-width. The `` noise is what upset Christoph, and I think it's perfectly fine to not use them. > > - if you use special characters like '*' in the middle of the text > > (outsize a literal block), prepend with a \ in order to escape > > parsing it. > > That's a bit inconvenient I suppose. > > > Btw, a lot of editors recognize ReST files and are capable of > > parsing the ReST tags while displaying the file, including vim > > and emacs, using different colors and/or bold to display those tags. > > So, even for text-editing, converting to ReST brings improvements. > > Doesn't seem to really work though; if I open > Documentation/development-process/1.Intro.rst the :ref:s at the start of > the document don't work with the regular 'follow-ref' key combo of ^]. For that we need to integrate some rst/sphinx ctags generator into the kernel's ctags target. Not sure we want to do that (it might upset people who want to follow to a C symbol with clashing naming), at least not by default. But if this desired we can make it happen. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- 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
