Use more formal style in vignettes

[eoduniyi]

I had a question about how formal the documentation is supposed to be.

For example, the following:

 Thus, once _your_ data is in R's workspace, creating a `hyperSpec`{.r} object is easy.
We suggest wrapping the code to import your data and the line joining it into a `hyperSpec`{.r} object by _your_ own import function.
_You_ are more than welcome to contribute such import code to package **hyperSpec**.
Secion \@ref(sec:writing-Import)<!--, (p. \pageref{sec:writing-Import})--> discusses examples of custom import functions.

Could be written from a third-person perspective (more formal):

Thus, once the data is in R's workspace, creating a `hyperSpec`{.r} object is easy.
We suggest wrapping the code to import the data and the line joining it into a `hyperSpec`{.r} object by a user-created import function.
Users are more than welcome to contribute such import code to package **hyperSpec**.
Secion \@ref(sec:writing-Import)<!--, (p. \pageref{sec:writing-Import})--> discusses examples of custom import functions.

[GegznaV]

In my opinion, the style should be consistent throughout all the vignettes.

I think @eoduniyi's remark is good and I agree using a more formal style in situations like this.

---

@eoduniyi, some places of the vignettes can be totally overwritten to reflect the current situation of hyperSpec. I recommend reading the whole text of the vignette first without editing. And when you get the whole picture, it would be easier to fix/update the vignettes.

One more thing: fileio.Rmd should be split into separate vignettes which will be moved to appropriate packages. Otherwise, we will have to use "circular dependencies": hyperSpec should not depend on hySpc packages.

[bryanhanson]

Your instincts are correct Erick: re-write things in the style you suggest. As with #265 just go ahead and make these changes, you do not need to seek review on these stylistic changes. Just make them and merge them.

I will open another issue about how to split this vignette (per VG's comment above).

[eoduniyi]

@GegznaV so there should be a fileio.Rmd for all the different file formats?

[bryanhanson]

If it were up to me I'd keep all the file i/o stuff together. But, there is the complication that to keep hyperSpec independent of and not depending upon the file i/o packages we need to spin out the pieces since code runs in the vignettes (doesn't it?). @cbeleites your thoughts?

[eoduniyi]

If it were up to me I'd keep all the file i/o stuff together. But, there is the complication that to keep hyperSpec independent of and not depending upon the file i/o packages we need to spin out the pieces since code runs in the vignettes (doesn't it?). @cbeleites your thoughts?

@bryanhanson so like:

fileio_packges <- {hySpc.read.txt, ... , hySpc.io.format}
decompose(fileio.Rmd on fileio_packges)

So we could link (via URL) hyperSpec(vignette) <-> fileio_packges(vingette)

[bryanhanson]

The link would be via the list-of-vignettes.md mechanism.

If decompose means break it into pieces yes. One by one as new packages emerge.