[R-pkg-devel] ω, α, η, ² in .Rd files

hi,

i'm trying to include some greek characters in my package documentation,
but am having difficulty getting it to work on windows. it works find on
macOS, linux, but throws errors on windows:

https://win-builder.r-project.org/guwReC6lhQaU/00check.log

so far i have tried:

?
\u03C9
\omega
\eqn{\omega}
\symbol{"03C9}
\enc{?}{omega}

i have `Encoding: UTF-8` specified in my DESCRIPTION

i have read:

https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Encoding-issues
https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Encoding
https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Insertions

any tips on how to get these symbols into documentation on windows? i'd
even by happy with it just saying 'omega' on windows (which is what i
thought \enc{}{} was supposed to do).

apparently i'm missing something.

with thanks

jonathon

On 10.02.2017 03:19, Jonathon Love wrote:

hi,

i'm trying to include some greek characters in my package documentation,
but am having difficulty getting it to work on windows. it works find on
macOS, linux, but throws errors on windows:

https://win-builder.r-project.org/guwReC6lhQaU/00check.log

so far i have tried:

?
\u03C9
\omega
\eqn{\omega}
\symbol{"03C9}
\enc{?}{omega}

The latter is right in principle, but two issues:

1- you use it in an .R file which should no assume a special encoding. 
I do not use roxygen2, hence don't know how it can work at all, I'd 
simply do it in the Rd file directly.

2- Thge LaTeX version on winbuilder cannot deal with an UTF-8 omega 
symbol. Hence I'd rather write
\eqn{\omega}{omega}
or to square it:
\eqn{\omega^2}{omega^2}

hi uwe,


On 10/2/17 23:40, Uwe Ligges wrote:

On 10.02.2017 03:19, Jonathon Love wrote:

hi,

i'm trying to include some greek characters in my package documentation,
but am having difficulty getting it to work on windows. it works find on
macOS, linux, but throws errors on windows:

https://win-builder.r-project.org/guwReC6lhQaU/00check.log

so far i have tried:

?
\u03C9
\omega
\eqn{\omega}
\symbol{"03C9}
\enc{?}{omega}

The latter is right in principle, but two issues:

1- you use it in an .R file which should no assume a special encoding.
I do not use roxygen2, hence don't know how it can work at all, I'd
simply do it in the Rd file directly.

2- Thge LaTeX version on winbuilder cannot deal with an UTF-8 omega
symbol. Hence I'd rather write
\eqn{\omega}{omega}
or to square it:
\eqn{\omega^2}{omega^2}

thanks for explaining this

unfortunately this doesn't work with the html or plain-text help (i
assume it does work with the PDF manuals). in the html/plain text help,
it always puts the plain ascii 'omega', rather than the actual symbol.

so it's seeming like it's not possible to have special chars in the html
or plain-text help, without upsetting the winbuilder?

if i have to use the plain ascii 'omega', 'eta', 'alpha', it won't be
the end of the world.

with thanks

jonathon

hi uwe,


On 10/2/17 23:40, Uwe Ligges wrote:

On 10.02.2017 03:19, Jonathon Love wrote:

hi,

i'm trying to include some greek characters in my package documentation,
but am having difficulty getting it to work on windows. it works find on
macOS, linux, but throws errors on windows:

https://win-builder.r-project.org/guwReC6lhQaU/00check.log

so far i have tried:

?
\u03C9
\omega
\eqn{\omega}
\symbol{"03C9}
\enc{?}{omega}

The latter is right in principle, but two issues:

1- you use it in an .R file which should no assume a special encoding.
I do not use roxygen2, hence don't know how it can work at all, I'd
simply do it in the Rd file directly.

2- Thge LaTeX version on winbuilder cannot deal with an UTF-8 omega
symbol. Hence I'd rather write
\eqn{\omega}{omega}
or to square it:
\eqn{\omega^2}{omega^2}

thanks for explaining this

unfortunately this doesn't work with the html or plain-text help (i
assume it does work with the PDF manuals). in the html/plain text help,
it always puts the plain ascii 'omega', rather than the actual symbol.

so it's seeming like it's not possible to have special chars in the html
or plain-text help, without upsetting the winbuilder?

if i have to use the plain ascii 'omega', 'eta', 'alpha', it won't be
the end of the world.

On 10/02/2017 8:52 AM, Jonathon Love wrote:

hi uwe,


On 10/2/17 23:40, Uwe Ligges wrote:

On 10.02.2017 03:19, Jonathon Love wrote:

hi,

i'm trying to include some greek characters in my package 
documentation,
but am having difficulty getting it to work on windows. it works 
find on
macOS, linux, but throws errors on windows:

https://win-builder.r-project.org/guwReC6lhQaU/00check.log

so far i have tried:

?
\u03C9
\omega
\eqn{\omega}
\symbol{"03C9}
\enc{?}{omega}

The latter is right in principle, but two issues:

1- you use it in an .R file which should no assume a special encoding.
I do not use roxygen2, hence don't know how it can work at all, I'd
simply do it in the Rd file directly.

2- Thge LaTeX version on winbuilder cannot deal with an UTF-8 omega
symbol. Hence I'd rather write
\eqn{\omega}{omega}
or to square it:
\eqn{\omega^2}{omega^2}

thanks for explaining this

unfortunately this doesn't work with the html or plain-text help (i
assume it does work with the PDF manuals). in the html/plain text help,
it always puts the plain ascii 'omega', rather than the actual symbol.

so it's seeming like it's not possible to have special chars in the html
or plain-text help, without upsetting the winbuilder?

if i have to use the plain ascii 'omega', 'eta', 'alpha', it won't be
the end of the world.

I suspect you are making things harder for yourself by using Roxygen2. 
As Uwe and the manual say, .R files need to be plain ASCII to be 
portable.  You can include Unicode escapes in strings.

Perhaps Roxygen2 has some way to process Unicode escapes in comments; 
you'll have to ask its authors.  If you include raw UTF-8 characters 
in the comments, they'll be processed differently in UTF-8 locales 
versus others.  So you might get away with doing this if Roxygen2 
always runs in a UTF-8 locale, but on Windows you will see problems.

hi duncan,


On 11/2/17 01:44, Duncan Murdoch wrote:

On 10/02/2017 8:52 AM, Jonathon Love wrote:

hi uwe,


On 10/2/17 23:40, Uwe Ligges wrote:

On 10.02.2017 03:19, Jonathon Love wrote:

hi,

i'm trying to include some greek characters in my package
documentation,
but am having difficulty getting it to work on windows. it works
find on
macOS, linux, but throws errors on windows:

https://win-builder.r-project.org/guwReC6lhQaU/00check.log

so far i have tried:

?
\u03C9
\omega
\eqn{\omega}
\symbol{"03C9}
\enc{?}{omega}

The latter is right in principle, but two issues:

1- you use it in an .R file which should no assume a special encoding.
I do not use roxygen2, hence don't know how it can work at all, I'd
simply do it in the Rd file directly.

2- Thge LaTeX version on winbuilder cannot deal with an UTF-8 omega
symbol. Hence I'd rather write
\eqn{\omega}{omega}
or to square it:
\eqn{\omega^2}{omega^2}

thanks for explaining this

unfortunately this doesn't work with the html or plain-text help (i
assume it does work with the PDF manuals). in the html/plain text help,
it always puts the plain ascii 'omega', rather than the actual symbol.

so it's seeming like it's not possible to have special chars in the html
or plain-text help, without upsetting the winbuilder?

if i have to use the plain ascii 'omega', 'eta', 'alpha', it won't be
the end of the world.

I suspect you are making things harder for yourself by using Roxygen2.
As Uwe and the manual say, .R files need to be plain ASCII to be
portable.  You can include Unicode escapes in strings.

yup, although if the encoding of the comments in the .R files are
completely misunderstood by system, it shouldn't make any difference to
the resultant package. Or is there a way that it could interfere?

of course, the CRAN checks are unlikely to appreciate this subtlety, so
i guess i'm on the hook there.

Perhaps Roxygen2 has some way to process Unicode escapes in comments;
you'll have to ask its authors.  If you include raw UTF-8 characters
in the comments, they'll be processed differently in UTF-8 locales
versus others.  So you might get away with doing this if Roxygen2
always runs in a UTF-8 locale, but on Windows you will see problems.

yup, i'd reached these conclusions - but always helpful to have someone
else spell things out.

with thanks

jonathon

yup, although if the encoding of the comments in the .R files are
completely misunderstood by system, it shouldn't make any difference to
the resultant package. Or is there a way that it could interfere?

Roxygen2 will take the comments and write out .Rd files.  Those files 
need to be written in ASCII, or the declared encoding of the package, 
not of the locale where Roxygen2 was run.  (R and CRAN know nothing 
about Roxygen2, they just look at the Rd files as though they were 
written by you.)

So I think it should be possible for all of this to work:  If you 
write your comments in UTF-8 and declare that as the encoding of the 
package, then Roxygen2 should read the .R files as UTF-8 files, and 
write out UTF-8 Rd files, regardless of the locale. But encodings of 
strings go through several translations internally in R, so there may 
be some step there that loses the original intent.  And Roxygen2 may 
be just ignoring encodings, which would almost certainly go badly.