Re: [PATCH 1/2] docs: kernel-doc comments are ASCII
From: Randy Dunlap
Date: Thu Aug 31 2017 - 11:54:16 EST
On 08/31/17 02:49, Mauro Carvalho Chehab wrote:
> Em Wed, 30 Aug 2017 15:02:59 -0700
> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
>
>> On 08/30/17 14:23, Jonathan Corbet wrote:
>>> On Mon, 28 Aug 2017 16:10:09 -0700
>>> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:
>>>
>>>> kernel-doc parsing uses as ASCII codec, so let people know that
>>>> kernel-doc comments should be in ASCII characters only.
>>>>
>>>> WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't decode byte 0xe2 in position 6368: ordinal not in range(128)
>>>
>>> So I don't get this error. What kind of system are you running the docs
>>> build on? I would really rather that the docs system could handle modern
>>> text if possible, so it would be better to figure out what's going on
>>> here...
>>
>> I'm OK with that. Source files in general don't need to be ASCII (0-127).
>>
>> I did this patch based on this (private) comment:
>>
>>> Yes, using ASCII should fix the problem.
>>
>> what kind of system? HP laptop.
>>
>> Linux midway.site 4.4.79-18.26-default #1 SMP Thu Aug 10 20:30:05 UTC 2017 (fa5a935) x86_64 x86_64 x86_64 GNU/Linux
>>
>>> sphinx-build --version
>> Sphinx (sphinx-build) 1.3.1
>
> I tried hard to reproduce the error here... I even added some Chinese
> chars on a kernel-doc markup and changed the language on my system
> to LANG=en_US.iso885915.
>
> No luck.
>
> As Documentation/conf.py has:
>
> # -*- coding: utf-8 -*-
>
> on its first line, I suspect that the error you're getting is likely
> due to the usage of a python version that doesn't recognize this.
>
> It seems that such dialect was introduced on python version 2.3:
>
> https://docs.python.org/2.3/whatsnew/section-encodings.html
>
> Yet, the documentation there seems to require a line before it,
> e. g.:
>
> #!/usr/bin/env python
> # -*- coding: UTF-8 -*-
>
> I suspect, however, that, if such line is added, on some systems it
> may not work, e. g. if both python 2 and 3 are installed, it could
> use the python version that doesn't have Sphinx installed.
>
> So, I suspect that the safest way to fix it is with something like the
> enclosed patch. Still, it could be useful to know what's happening,
> just in case we get other reports.
>
> Randy,
>
> What's your python version?
> python --version
Python 2.7.13
--
~Randy