Re: docs build questions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Mon, 14 Aug 2017, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:
> On 08/13/2017 11:46 PM, Markus Heiser wrote:
>> Hi Randy,
>> 
>>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap <rdunlap@xxxxxxxxxxxxx>:
>>> Lots of ERRORs where a doc comment is of the form GPP_ (ending with a '_'):
>>>
>>> ../block/bio.c:404: ERROR: Unknown target name: "gfp".
>> 
>> Yes, this is a conflict since comments are reST Markup.
>> 
>>  https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
>> 
>> In sources we like to use FOO_ (ending with a '_'), which is a
>> hyperlink markup in reST:
>> 
>>  http://www.sphinx-doc.org/en/stable/rest.html#hyperlinks
>> 
>> The only solution I see is to replace FOO_ with ``FOO_``
>
> I guess that's OK in doc files, but most of these comments are in source files
> and requiring ``xyz_`` there is not nice.

I assume very few actual symbols end in underscore, and this is more of
a question of referencing a group of FOO_ prefixed symbols. In these
cases, I prefer using FOO_* as it both avoids the problem and makes
perfect sense in plain text.

BR,
Jani.


-- 
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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux