| Message ID | 54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Mon, 28 Aug 2017 16:10:09 -0700 Randy Dunlap <rdunlap@infradead.org> 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... Thanks, jon
On 08/30/17 14:23, Jonathan Corbet wrote: > On Mon, 28 Aug 2017 16:10:09 -0700 > Randy Dunlap <rdunlap@infradead.org> 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
Em Wed, 30 Aug 2017 15:02:59 -0700 Randy Dunlap <rdunlap@infradead.org> escreveu: > On 08/30/17 14:23, Jonathan Corbet wrote: > > On Mon, 28 Aug 2017 16:10:09 -0700 > > Randy Dunlap <rdunlap@infradead.org> 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 suspect that the problem is not related to the version, but to what you might have set on LANG. Maybe if we add something like: LANG=C.utf-8 to the Documentation/Makefile or adding: .. -*- coding: utf-8; mode: rst -*- as the first line on the *.rst file that include the kernel-doc directive would solve the issue. Regards, Mauro
On Wed, 30 Aug 2017 19:15:53 -0300 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > I suspect that the problem is not related to the version, but to > what you might have set on LANG. > > Maybe if we add something like: > LANG=C.utf-8 > > to the Documentation/Makefile That's worth a try; Randy, can you give it a quick go? > or adding: > > .. -*- coding: utf-8; mode: rst -*- > > as the first line on the *.rst file that include the kernel-doc > directive would solve the issue. I guess I don't see how that would help, instead. Emacs reads that line, but it's not involved in the problem. I wish I could reproduce this, then we could see what in that massive try..except block in kerneldoc.py is throwing the exception. Putting in an explicit decode call might be enough to make the problem go away. Thanks, jon
On 08/30/17 15:31, Jonathan Corbet wrote: > On Wed, 30 Aug 2017 19:15:53 -0300 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > >> I suspect that the problem is not related to the version, but to >> what you might have set on LANG. >> >> Maybe if we add something like: >> LANG=C.utf-8 >> >> to the Documentation/Makefile > > That's worth a try; Randy, can you give it a quick go? Yes, that fixes it for me. Thanks. >> or adding: >> >> .. -*- coding: utf-8; mode: rst -*- >> >> as the first line on the *.rst file that include the kernel-doc >> directive would solve the issue. > > I guess I don't see how that would help, instead. Emacs reads that line, > but it's not involved in the problem. > > I wish I could reproduce this, then we could see what in that massive > try..except block in kerneldoc.py is throwing the exception. Putting in > an explicit decode call might be enough to make the problem go away.
On 08/30/17 16:01, Randy Dunlap wrote: > On 08/30/17 15:31, Jonathan Corbet wrote: >> On Wed, 30 Aug 2017 19:15:53 -0300 >> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: >> >>> I suspect that the problem is not related to the version, but to >>> what you might have set on LANG. >>> >>> Maybe if we add something like: >>> LANG=C.utf-8 >>> >>> to the Documentation/Makefile >> >> That's worth a try; Randy, can you give it a quick go? > > Yes, that fixes it for me. Thanks. Wait! I forgot to unpatch demux.h. I'll test again now.... >>> or adding: >>> >>> .. -*- coding: utf-8; mode: rst -*- >>> >>> as the first line on the *.rst file that include the kernel-doc >>> directive would solve the issue. >> >> I guess I don't see how that would help, instead. Emacs reads that line, >> but it's not involved in the problem. >> >> I wish I could reproduce this, then we could see what in that massive >> try..except block in kerneldoc.py is throwing the exception. Putting in >> an explicit decode call might be enough to make the problem go away. > > >
On 08/30/17 16:04, Randy Dunlap wrote: > On 08/30/17 16:01, Randy Dunlap wrote: >> On 08/30/17 15:31, Jonathan Corbet wrote: >>> On Wed, 30 Aug 2017 19:15:53 -0300 >>> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: >>> >>>> I suspect that the problem is not related to the version, but to >>>> what you might have set on LANG. >>>> >>>> Maybe if we add something like: >>>> LANG=C.utf-8 >>>> >>>> to the Documentation/Makefile >>> >>> That's worth a try; Randy, can you give it a quick go? >> >> Yes, that fixes it for me. Thanks. > > Wait! I forgot to unpatch demux.h. I'll test again now.... OK, still works for me. > >>>> or adding: >>>> >>>> .. -*- coding: utf-8; mode: rst -*- >>>> >>>> as the first line on the *.rst file that include the kernel-doc >>>> directive would solve the issue. >>> >>> I guess I don't see how that would help, instead. Emacs reads that line, >>> but it's not involved in the problem. >>> >>> I wish I could reproduce this, then we could see what in that massive >>> try..except block in kerneldoc.py is throwing the exception. Putting in >>> an explicit decode call might be enough to make the problem go away. >> >> >> > >
--- lnx-413-rc7.orig/Documentation/doc-guide/kernel-doc.rst +++ lnx-413-rc7/Documentation/doc-guide/kernel-doc.rst @@ -108,6 +108,9 @@ The function and type kernel-doc comment function or type being described. The overview kernel-doc comments may be freely placed at the top indentation level. +.. attention:: kernel-doc comments should be written **only** in ASCII + characters since they are processed as ASCII input. + Example kernel-doc function comment:: /**