[Roxygen-devel] usage section and long equasions

[meik michalke]

hi,

i have two layout issues with long lines in roxygen2.

the first is regarding the automatically generated usage section. this usally
works great, except when an option is very long. some automatic line breaks
and additional indentation would be great here. see this generated doc, page
70, on the function "readability":
o http://r.reaktanz.de/pckg/koRpus/koRpus.pdf

the second problem is similar and can be seen in the details section of the
same function, p. 71ff., this time regarding the documented formulas. in
theory LaTeX is capable of nicely displaying an equasion over several lines,
is there a way to get this into the Rd file via roxygen2?


thanks! :: m.eik
--
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20120209/d2c76427/attachment.pgp>

[Hadley Wickham]

Post by meik michalke
the first is regarding the automatically generated usage section. this usally
works great, except when an option is very long. some automatic line breaks
and additional indentation would be great here. see this generated doc, page
?o http://r.reaktanz.de/pckg/koRpus/koRpus.pdf

This is a little tricky because it's hard (in general) to tell when
whitespace matters (i.e. inside a string) and when it doesn't (between
commas of a list).

Post by meik michalke
the second problem is similar and can be seen in the details section of the
same function, p. 71ff., this time regarding the documented formulas. in
theory LaTeX is capable of nicely displaying an equasion over several lines,
is there a way to get this into the Rd file via roxygen2?

Can you introduce latex line breaks with \\ ?

Hadley

[meik michalke]

hi hadley,

Post by Hadley Wickham

Post by meik michalke
the first is regarding the automatically generated usage section. this
usally works great, except when an option is very long. some automatic
line breaks and additional indentation would be great here. see this
o http://r.reaktanz.de/pckg/koRpus/koRpus.pdf

This is a little tricky because it's hard (in general) to tell when
whitespace matters (i.e. inside a string) and when it doesn't (between
commas of a list).

sure, but couldn't roxygen2 just ignore spaces inside quotes, then? even if it
didn't, there're obviously two alternatives: *possibly* seeing a line break to
many in the PDF, or *definitely* not seeing most of the other options at all.
i'd prefer it the first way ;-)

Post by Hadley Wickham

Post by meik michalke
the second problem is similar and can be seen in the details section of
the same function, p. 71ff., this time regarding the documented
formulas. in theory LaTeX is capable of nicely displaying an equasion
over several lines, is there a way to get this into the Rd file via
roxygen2?

Can you introduce latex line breaks with \\ ?

no, line breaks are ignored in \deqn{}. to typeset this nicely, Rd files would
need to support something like the LaTeX eqnarray environment. but i'm afraid
we won't see that for a while:
o http://bugs.r-project.org/bugzilla3/show_bug.cgi?id=13287
so this is not something which could be fixed by roxygen2, sorry for the fuzz.

the workaround is to use several \deqn{} calls for one equasion, but that of
course looks pretty ugly. it would be really nice if both sides of the
equasion could be aligned relative to the "=" sign, as eqnarray allows.


viele gr??e :: m.eik
--
dipl. psych. meik michalke
abt. f"ur diagnostik und differentielle psychologie
institut f"ur experimentelle psychologie
heinrich-heine-universit"at d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20120209/97ce555c/attachment.pgp>

[Hadley Wickham]

Post by meik michalke
hi hadley,

Post by Hadley Wickham

Post by meik michalke
the first is regarding the automatically generated usage section. this
usally works great, except when an option is very long. some automatic
line breaks and additional indentation would be great here. see this
?o http://r.reaktanz.de/pckg/koRpus/koRpus.pdf

This is a little tricky because it's hard (in general) to tell when
whitespace matters (i.e. inside a string) and when it doesn't (between
commas of a list).

sure, but couldn't roxygen2 just ignore spaces inside quotes, then? even if it
didn't, there're obviously two alternatives: *possibly* seeing a line break to
many in the PDF, or *definitely* not seeing most of the other options at all.
i'd prefer it the first way ;-)

Well, it _could_, but that would involve writing a parser because
strings are complicated! i.e. where are the valid breaking spaces in
this vector:

c(" ", ' ', "' '", "\" \"", "\\ ")

Hadley

[meik michalke]

Post by Hadley Wickham

Post by meik michalke

Post by Hadley Wickham
This is a little tricky because it's hard (in general) to tell when
whitespace matters (i.e. inside a string) and when it doesn't (between
commas of a list).

sure, but couldn't roxygen2 just ignore spaces inside quotes, then? even
if it didn't, there're obviously two alternatives: *possibly* seeing a
line break to many in the PDF, or *definitely* not seeing most of the
other options at all. i'd prefer it the first way ;-)

Well, it _could_, but that would involve writing a parser because
strings are complicated! i.e. where are the valid breaking spaces in
c(" ", ' ', "' '", "\" \"", "\\ ")

in theory, i see the problem. allthough i'd suggest to break lines after
commas only, so the only problematic case would be a comma followed by space
inside a quote:

c(" ", ' ', "', '", "\" \"", "\\ ")

but still, even if we ignored this for the time being, i fail to see the
benefit that the current state

c(" ", ' ', "', '

has over the proposed

c(" ", ' ', "',
'", "\" \"",
"\\ ")

sure this isn't perfect either, but at least you get to see the rest of the
vector. so i'd consider this an improvement, nonetheless. it should work in
almost all of the cases, because it would only apply to options which are too
long anyway, and what are the odds that these also have a quoted comma+space
exactly in the problematic place?


viele gr??e :: m.eik
--
dipl. psych. meik michalke
abt. f"ur diagnostik und differentielle psychologie
institut f"ur experimentelle psychologie
heinrich-heine-universit"at d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20120209/7c65eb95/attachment.pgp>

[Hadley Wickham]

Post by meik michalke
in theory, i see the problem. allthough i'd suggest to break lines after
commas only, so the only problematic case would be a comma followed by space
?c(" ", ' ', "', '", "\" \"", "\\ ")
but still, even if we ignored this for the time being, i fail to see the
benefit that the current state
?c(" ", ' ', "', '
has over the proposed
?c(" ", ' ', "',
?'", "\" \"",
?"\\ ")
sure this isn't perfect either, but at least you get to see the rest of the
vector. so i'd consider this an improvement, nonetheless. it should work in
almost all of the cases, because it would only apply to options which are too
long anyway, and what are the odds that these also have a quoted comma+space
exactly in the problematic place?

Basically, I don't want to add code that I know doesn't work -
obviously, I'd prefer not to already have code that doesn't work, but
I want to make it better, not worse.

Hadley

[meik michalke]

Post by Hadley Wickham
Basically, I don't want to add code that I know doesn't work -
obviously, I'd prefer not to already have code that doesn't work, but
I want to make it better, not worse.

i agree. we just seem to have different views on what would be an improvement.
i'll leave it to this and switch back to manually defining usage sections.


best regards :: m.eik
--
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20120220/cc48b4c3/attachment.pgp>

[Hadley Wickham]

Post by meik michalke

Post by Hadley Wickham
Basically, I don't want to add code that I know doesn't work -
obviously, I'd prefer not to already have code that doesn't work, but
I want to make it better, not worse.

i agree. we just seem to have different views on what would be an improvement.
i'll leave it to this and switch back to manually defining usage sections.

It would help if you could file a bug report at
https://github.com/klutometis/roxygen/issues - that way if I ever
realise how to replace spaces with non-breaking space only within
strings, then I'll remember this problem.

Hadley

[meik michalke]

Post by Hadley Wickham

Post by meik michalke

Post by Hadley Wickham
Basically, I don't want to add code that I know doesn't work -
obviously, I'd prefer not to already have code that doesn't work, but
I want to make it better, not worse.

i agree. we just seem to have different views on what would be an
improvement. i'll leave it to this and switch back to manually defining
usage sections.

It would help if you could file a bug report at
https://github.com/klutometis/roxygen/issues - that way if I ever
realise how to replace spaces with non-breaking space only within
strings, then I'll remember this problem.

interestingly, if you decide to use @usage, roxygen2 *does* already break long
options automatically... :: m.eik
--
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20120222/5acd3517/attachment.pgp>