> Am 16.02.2018 um 19:56 schrieb Markus Heiser <[email protected]>:
>
>
>> Am 01.10.2017 um 20:33 schrieb Randy Dunlap <[email protected]>:
>>
>> A different "problem" this time:
>>
>> Documentation/driver-api/basics.rst pulls in include/linux/kernel.h.
>> <linux/kernel.h> has kernel-doc notation for (among others) trace_printk()
>> and trace_puts().
>>
>> Part of the text for trace_printk() says:
>>
>> * Note: __trace_printk is an internal function for trace_printk and
>> * the @ip is passed in via the trace_printk macro.
>>
OK found the problem, this comment results in reST markup:
<SNIP>--
**Note**
__trace_printk is an internal function for :c:func:`trace_printk()` and
the **ip** is passed in via the :c:func:`trace_printk()` macro.
This function allows a kernel developer to ...
<SNAP>---
in reST this is a definition list item [1] like:
<SNIP>--
term (up to a line of text)
Definition of the term, which must be indented
next term
Description.
<SNIP>--
Anyway, the 'Note:' is quite unfortunate at this point. It starts
a new section with title 'Note'. I guess this is not what we wan't
here. To tag a node-block correct I recommend to patch the comment
like:
modified include/linux/kernel.h
@@ -638,8 +638,10 @@ do {
\
* trace_printk - printf formatting in the ftrace buffer
* @fmt: the printf format for printing
*
- * Note: __trace_printk is an internal function for trace_printk() and
- * the @ip is passed in via the trace_printk() macro.
+ * .. node:
+ *
+ * __trace_printk is an internal function for trace_printk() and
+ * the @ip is passed in via the trace_printk() macro.
*
* This function allows a kernel developer to debug fast path sections
* that printk is not appropriate for. By scattering in various
I hope the explanation could help clarify.
[1] http://www.sphinx-doc.org/en/master/rest.html#lists-and-quote-like-blocks
-- Markus --
>> I am seeing this 'produced' (when I view the output html) as:
>>
>> __trace_printk is an internal function for trace_printk and
>> the ip is passed in via the trace_printk macro.
>>
>> (BUT the first line is all BOLD).
>>
>> I tried changing that to
>> \_\_trace_printk is an internal function...
>> with the same BOLD result.
>>
>> So I tried the source as
>> ``__trace_printk`` is an internal function...
>> with the same BOLD result.
>>
>> Maybe this is a s/w bug?
>> Running Sphinx v1.3.1
>
> Sorry for my late reply. It is not only you, see:
>
> - (perl kernel-doc)
> https://www.kernel.org/doc/html/latest/driver-api/basics.html#c.trace_printk
> - (python kernel-doc)
> https://h2626237.stratoserver.net/kernel/linux_src_doc/include/linux/kernel_h.html#trace-printk
>
> I have to dig.
>
> -- Markus ----
> 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
--
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
