internal: use markdown throughout Roxygen docs, move long examples sections into separate file

[markheckmann]

Some optional and mostly cosmetic housekeeping suggestions:

• We could move very long function @examples sections into a separate files (e.g. for ph_with)
• The Roxygen docs are currently a mixture of old .Rd-style code (e.g. \code{xxx} or \code{\link{xxx}}) and Markdown. We could make it Markdown throughout for consistency.

@davidgohel If you agree, please feel free to assign it to me.

[markheckmann]

point 2 done in edb326f

[davidgohel]

yes, I started that "very interesting" work so you don't have to do all the cleaning :)

(I need to work on officer these days but on the "MS Word" side)

[markheckmann]

It noticed that there is a new top level folder examples. There is an already already existing inst/examples folder, which is AFAIK a common choice (e.g., SO post, SO post). If you don't mind, I'd like to move the two files from examples to inst/examples and update the references.

[davidgohel]

I am so used to use examples so I did not notice inst/examples was already existing!

You can move them to inst/examples no problem