Hi Kees, Em Mon, 1 May 2017 14:24:24 -0700 Kees Cook <keescook@xxxxxxxxxx> escreveu: > Hi, > > While doing some .txt conversions to .rst, I ended up with several > questions about markup style, and in looking at existing .rst files, > there didn't seem to be a common methodology. Well, some maintainers prefer to keep the conversion as simple as possible. So, there's no "enforcement" about the style. My personal preference on the documents I maintain is: > I'd love to have > definitive guide to how to do these things in the kernel > documentation: > > - how to mark and link to CONFIG items? (e.g. CONFIG_HARDENED_USERCOPY) ``CONFIG_foo`` > - how to mark and link to kernel command line arguments? (e.g. > loadpin.enabled=1) Idem: ``loadpin.enabled=1`` > - how to mark and link to functions? (e.g. put_seccomp()) If you want to generate cross-references, you can do: :c:func:`put_seccomp` > - how to mark and link to fields? (e.g. siginfo->si_arch) Right now, kernel-doc is not generating cross-references to fields, but you can do cross-references to struct and enums. What I do is: :c:type:`device_driver`.\ ``resume()``. (That's a cross reference to struct device_driver) > - how to mark and link to defines/literals? (e.g PR_SET_NO_NEW_PRIVS) ``literal`` > - how to mark and link to sysctls? (e.g. net.syn_cookies) That is a good question. The problem with syscalls is that each subsystem may override standard ioctls (open, close, write, ioctl, ...). Specifically in the case of ioctl, even inside a subsystem there will be multiple definitions. What I'm doing on media is that I'm creating a reference for each ioctl definition with a normal reference: .. _VIDIOC_G_CTRL: And then I'm referencing them via :ref:`VIDIOC_G_CTL`. On the specific cases where the syscall is subsystem-specific and there's just one meaning for it, then it is probably easier to use the C domain (e. g. :c:func: for reference, and use kernel-doc to generate its definition, as if it were a c function). > - how to mark and link to manpage-look-up-able things? (e.g. setuid(2)) I guess that there is a ReST markup for man pages, but if you're documenting it with a man look and feel, the best is to use something like what we do on media. Something like: Documentation/media/uapi/dvb/frontend_f_close.rst Markus is working on a way to convert something like that to man pages. > - how to mark internal filepaths? (e.g. samples/seccomp/) > - how to mark external filepaths? (e.g. /etc/passwd) > - how to mark environment variables (e.g. LD_*) For all the above: ``literal`` > > It seems most aren't explicitly marked up in existing docs. Sometimes > functions are wrapped in `` marks, same for pathnames. Any opinions > would be appreciated. :) > Thanks, Mauro -- 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
