Hi Kees,
Em Mon, 1 May 2017 14:24:24 -0700
Kees Cook <[email protected]> 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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
