InsertAllCited on R6 class documentation about rdpack HOT 14 CLOSED

Thanks for the report. Could you give a reproducible example? A link to a github repo will do.

from rdpack.

Sure. In the rgudhi package, you can see the effect of that.

from rdpack.

Thanks for the link.

There are potential problems here but could you check the bellow notes. Once I get clear understanding of what is needed I may be able to make suitable changes.

For class SimplexTree Repack reports that there are no references but it seems to me that the only citation is actually written inline, i.e. not using eg insertCite . I am away from computers this week and cannot check myself but I am pretty sure that if you change the inline citation to use insertCite it will be processed successfully.

Actually, insertAllCited lists all references cited up to that point in the documentation file. It also currently clears the list, allowing further insertCites paired with insertAllCited. If you want a single reference list contains all cited references in the doc file this could be achieved by putting a single insertAllCited after all citations were done. For R6 you can't do that but as a workaround for now you can put insertAllCited in the last method for the class (deleting all other instances of insertAllCited). This should list all references for the class and methods.

Another workaround would be to put insertNoCite entries for the reference list at the class level. Not ideal, of course.

from rdpack.

For class SimplexTree Repack reports that there are no references but it seems to me that the only citation is actually written inline, i.e. not using eg insertCite . I am away from computers this week and cannot check myself but I am pretty sure that if you change the inline citation to use insertCite it will be processed successfully.

I do use \insertCite{} in one of the method (collapse_edges()) already.

Actually, insertAllCited lists all references cited up to that point in the documentation file. It also currently clears the list, allowing further insertCites paired with insertAllCited. If you want a single reference list contains all cited references in the doc file this could be achieved by putting a single insertAllCited after all citations were done. For R6 you can't do that but as a workaround for now you can put insertAllCited in the last method for the class (deleting all other instances of insertAllCited). This should list all references for the class and methods.

I tried that unsuccessfully.

What I would like to accomplish is to cite via \insertCite{} some papers in the method documentation, and ideally with one call to \insertAllCited, Rdpack would generate reference sections in each method in which there was an insertCite

from rdpack.

This is a summary of what works and what doesn't, as well as a TODO.

I do use \insertCite{} in one of the method (collapse_edges()) already.

It is also paired with a insertAllCited and, as far as I can see, the reference is rendered properly
(at the time of writing, also in the pkgdown documentation for the collapse_edges() method at
https://astamm.github.io/rgudhi.

For citations in the class section, you can use also a normal section "References". For example, I added a reference in "REFERENCES.bib" for the inline one towards the beginning of "simplex_tree.R"

@article{Boissonnat2014efficient,
  title = {The Simplex Tree: An Efficient Data Structure for General Simplicial Complexes},
  author = {Jean-Daniel Boissonnat and Cl\'ement Maria},
  journal = {Algorithmica},
  pages = 1–22,
  year = 2014,
}

Then modified the doc for the class:

#' R6 Class for Simplex Tree
#'
#' @description The simplex tree is an efficient and flexible data structure for
#'   representing general (filtered) simplicial complexes. The data structure is
#'   described in \insertCite{Boissonnat2014efficient}{rgudhi}. 
#' ...
#'...
#' @references
#' \insertAllCited{}
#' @export

After running the package through pkgdown::build_site() or R CMD Rd2pdf, the citation and the reference for the class are rendered ok.

What I would like to accomplish is to cite via \insertCite{} some papers in the method documentation, and ideally with one call to \insertAllCited, Rdpack would generate reference sections in each method in which there was an insertCite

Unfortunately, this is not possible. The macros can insert stuff only at places, where they are used. They don't see the global picture. Hence the need to put \insertAllCited at the place(s), where you want the references to appear.

TODO: However, currently insertALLCited doesn't clear the list after finishing its work (despite my first comment above). As a result, the reference lists produced by second and subsequent insertAllCited accumulate. I will fix this.

from rdpack.

Thanks for this detailed answer. However the fact that the citation in the collapse_edges() documentation is rendered properly is only due to my trick of generating a reference section for methods manually as a subsection of the details section. That way, it is not all wrapped up at class level.

from rdpack.

... is only due to my trick of generating a reference section for methods manually ... That way, it is not all wrapped up at class level.

I don't understand this - if you drop the (sub)section, #' ## References the references appear at the same place, only without being in a subsection; they do not go to the class.
On the other hand, if you use @references in a method, this starts a new top level section, which is a section for the class. roxygen2 seems to (rightly) consider this to be aimed at the top level at merges the contents there, meaning that if you have two or more @references sections, they are merged.

insertAllCited doesn't make a section, it just produces the references. There may be a case for another macro that creates a (sub)section. I don't think that it would be particularly helpful, though I am open to suggestions. (in LaTeX, standard BibTeX creates a section automatically and that is very annoying when one doesn't want that or wants to name it differently.)

from rdpack.

I don't understand this - if you drop the (sub)section, #' ## References the references appear at the same place, only without being in a subsection; they do not go to the class.
On the other hand, if you use @references in a method, this starts a new top level section, which is a section for the class. roxygen2 seems to (rightly) consider this to be aimed at the top level at merges the contents there, meaning that if you have two or more @references sections, they are merged.

You are right here. I would have liked for @references to create a References section by method instead of merging everything at class level. For instance, there is a whole paper on collapse_edges() which has nothing to do with the other methods of the SimplexTree class, hence should not be referenced at class level. But your point is that it might be an roxygen2 issue or more precisely, choice of design, am I getting this correctly?

from rdpack.

The important thing is that we came to common understanding:).

I don't think that this is an issue with roxygen2. It actually does a very sensible think by merging contents from @xxx section at the top level, since this allows you to write stuff that is specific to a method that you want to add to the class section. roxygen2 does similar things elsewhere, as well.

There may be a case to ask rogygen2 developers for @references in methods sections to be treated similarly to @description and @details. For simplicity of your request, it would be better not to mention Rdpack since this is not related to Rdpack - if you just put manually created references in @references they will be collected and put in a references section at top level. There is a rationale for such a request, since merging @references doesn't make sense - if two methods share a reference, it is duplicated in the merged list.

A more general request, which may have better chances of being accepted, is to ask for user sections in methods, e.g. @usersec, such that, @usersec Xxxx would be rendered in methods sections as a subsection titled Xxx at the same sectioning level as @details and @description.

As I said, I will fix insertAllCited to clear the list, so that it does not accumulate results when used more than once in a doc unit.

from rdpack.

I added now (with commit b959fe0) a new Rd macro \insertCited which works like \insertAllCited but empties the references list after finishing its work. This means that the second and subsequent \insertCited in the same help page will list only citations done since the preceding \insertCited.

So, just use \insertCited insead of \insertAllCited to produce separate references lists for each method and the class in R6 documentation.

When using \insertCited, put Rdpack (> 2.3.1) in the Imports:field in fileDESCRIPTION`.

Please let me know if you encounter buggy behaviour. Suggestions for a better name of the macro are also welcome since \insertCited differs very little from \insertCite.

from rdpack.

Thanks a lot @GeoBosh ! It works like a charm. Are you planning a CRAN release anytime soon?

from rdpack.

Yes, probably within a week or so, after I do further tests and check the reverse dependencies and nothing wrong turns up.

from rdpack.

This is now on CRAN, Rdpack v2.4.

from rdpack.

Great, thanks a lot!

from rdpack.