Closed astamm closed 2 years ago
Thanks for the report. Could you give a reproducible example? A link to a github repo will do.
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 insertCite
s 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.
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 eginsertCite
. I am away from computers this week and cannot check myself but I am pretty sure that if you change the inline citation to useinsertCite
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 furtherinsertCite
s paired withinsertAllCited
. If you want a single reference list contains all cited references in the doc file this could be achieved by putting a singleinsertAllCited
after all citations were done. For R6 you can't do that but as a workaround for now you can putinsertAllCited
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
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.
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.
... 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.)
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?
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.
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 file
DESCRIPTION`.
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
.
Thanks a lot @GeoBosh ! It works like a charm. Are you planning a CRAN release anytime soon?
Yes, probably within a week or so, after I do further tests and check the reverse dependencies and nothing wrong turns up.
This is now on CRAN, Rdpack v2.4.
Great, thanks a lot!
In R6 documentation, both the class and methods are documented using all usual roxygen tags but only the description and details tags can be different for the class and the methods. As such, citations in method description field are listed in the class reference section only and actually not discovered at class level since cited at method level.