On Fri, 16 Feb 2018, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
>> Am 16.02.2018 um 19:56 schrieb Markus Heiser <markus.heiser@xxxxxxxxxxx>:
>>
>>
>>> Am 01.10.2017 um 20:33 schrieb Randy Dunlap <rdunlap@xxxxxxxxxxxxx>:
>>>
>>> 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:
Shouldn't this be ".. note:"?
BR,
Jani.
> + *
> + * __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 majordomo@xxxxxxxxxxxxxxx
>> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
--
Jani Nikula, Intel Open Source Technology Center
--
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
