Re: ReST style guide?
Em Mon, 1 May 2017 21:48:50 -0300 Mauro Carvalho Chehab escreveu: > Hi Kees, > > Em Mon, 1 May 2017 14:24:24 -0700 > Kees Cook 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()``. There are some examples for the way we're doing this document on media, under kapi directory, like: Documentation/media/kapi/dtv-core.rst > > (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). Forgot to mention: if you want also to document it inside a ReST file, you could use: .. c:function:: int ioctl( int fd, VIDIOC_G_CTRL, struct v4l2_control *argp ) :name: VIDIOC_G_CTRL .. c:function:: int ioctl( int fd, VIDIOC_S_CTRL, struct v4l2_control *argp ) :name: VIDIOC_S_CTRL The :name: here is used in order to distinguish it from other sysctls with the same name. If not used, it will use the "function" name, e. g. "ioctl", and will complain because you would have two duplicated definitions for the same function. With :name: each ioctl can be referenced using the value after name, e. g. :c:func:`VIDIOC_G_CTRL`. The cross-reference index will also use the value inside the name. That's particularly useful for filesystem syscalls (like read, write, open, close, ioctl), as each subsystem may have their own particularity and description for those. > > > - 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 Thanks, Mauro -- 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: ReST style guide?
Hi Kees, Em Mon, 1 May 2017 14:24:24 -0700 Kees Cook 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
ReST style guide?
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. 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) - how to mark and link to kernel command line arguments? (e.g. loadpin.enabled=1) - how to mark and link to functions? (e.g. put_seccomp()) - how to mark and link to fields? (e.g. siginfo->si_arch) - how to mark and link to defines/literals? (e.g PR_SET_NO_NEW_PRIVS) - how to mark and link to sysctls? (e.g. net.syn_cookies) - how to mark and link to manpage-look-up-able things? (e.g. setuid(2)) - 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_*) 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. :) -- Kees Cook Pixel Security -- 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
