Save scientific work citations to a BibTeX file for ease of use in Doxygen

[jhlegarreta]

Description

Citations to scientific works should be stored in a BibTeX file and Doxygen's \cite should be used to cite them in the documentation. Currently, there is a variety of syntaxes that are used to cite works across the documentation, ranging from no syntax highlight at all, code-style indentation, or paragraph, e.g.:
https://itk.org/Doxygen/html/classitk_1_1STAPLEImageFilter.html
https://itk.org/Doxygen/html/classitk_1_1ScalarChanAndVeseSparseLevelSetImageFilter.html
https://itk.org/Doxygen/html/classitk_1_1BSplineScatteredDataPointSetToImageFilter.html

Expected information

Citatons should be hosted in a single BibTeX file so that they can easily be cross-referenced and reused across the documentation.

Actual information

Citation styles are inconsistent and the same work might be cited differently/citations cannot be re-used.

Versions

master

Additional Information

Doxygen \cite command documentation:
https://doxygen.nl/manual/commands.html#cmdcite

The IJ works' bibtex files can actually be retrieved from the IJ website, so that would save some work. Maybe an script that gathers all references could be developed to have them all in a single file. The file could be dynamically updated e.g. every month.

IJ repository: https://github.com/InsightSoftwareConsortium/InsightJournal

[zivy]

A limitation of the html version generated bibliography is that the style is fixed and even when the doi is available as part of the bib file it is not included in the output. This functionality is a longstanding feature request in doxygen.

[jhlegarreta]

I see. Anyways, I believe consistency is important, so even if the DOI is not displayed by Doxygen, having all references in a BibTeX file would still be an improvement: easier to maintain, consistent style when being displayed, etc. Maybe the Doxygen folks can afford addressing the DOI issue at some point in the future.

[zivy]

Agreed. Using the bibtex format forces us to provide more complete and consistent citation information. Some of the existing textual references were partial and ambiguous, required some searching to pinpoint the referenced paper.

[albert-github]

One thing I saw is that when the "doi" is in the url there is a link to the "doi" see e.g. https://doc.cgal.org/latest/Arrangement_on_surface_2/citelist.html (ind the link is forwarded again to springer) where the bib file entry is:

@article{cgal:bfhks-apsca-10,
  author      = {Eric Berberich and Efi Fogel and Dan Halperin and
                 Michael Kerber and Ophir Setter},
  title       = {Arrangements on Parametric Surfaces {II}: Concretizations
                 and Applications},
  journal     = {Mathematics in Computer Science},
  publisher   = {Birkh\"{a}user Basel},
  issn        = {1661-8270},
  keyword     = {Mathematics},
  pages       = {67--91},
  volume      = {4},
  issue       = {1},
  url         = {https://dx.doi.org/10.1007/s11786-010-0043-4},
  year        = {2010}
}

Note: just a mention or a thumbs up does not trigger an email (so not known there is extra need for it), a friendly ping might help.

[zivy]

Thanks @albert-github for the pointer. Will duplicate the doi info in the url field so that the current doxygen config will result in hyperlinks.

[albert-github]

Isn't this fixed now by means of #5149

[dzenanz]

That PR states it is the first of multiple PRs to accomplish that. Some citations were converted, but not all.

[zivy]

@jhlegarreta, @dzenanz
I just created the last PR for this issue. Note that this is a best-effort to identify all of the references throughout the code base. I'm sure there are references I missed and I intentionally did not include the Insight-Journal papers that are referenced throughout (their DOIs are listed so readily accessible to the reader).

[dzenanz]

Thank you Ziv!

[jhlegarreta]

Thanks for the effort @zivy.

I intentionally did not include the Insight-Journal papers that are referenced throughout (their DOIs are listed so readily accessible to the reader).

I would keep the issue open until we have the bandwidth to address those so that we never look back again to non-BibTeX refs in ITK.

[zivy]

@jhlegarreta, sure. I'll need to amend my last commit message so that merging the PR doesn't automatically close this issue.

[jhlegarreta]

I'll need to amend my last commit message so that merging the PR doesn't automatically close this issue.

👍 Maybe remove the 4/4 and final parts as well.

[zivy]

👍 Maybe remove the 4/4 and final parts as well.
Let me keep those. It's the final PR for me on this for a while (I didn't know what I was getting myself into when I assigned this issue to myself 😆 ).

[albert-github]

@zivy

Nice work.
There are still some problems (besides the references to the Insight Journal Paper):

• issue Warning about unknown command \dennis1983 #5218 with proposed patch
• issue Empty \cite label #5203 waiting for fix on ITK site or guidance what could be done (as I suspect that the problems are cased by clang-format)
• issue Warning about incorrect usage of command @cite found as part of a title section #5219 with proposed patch

[zivy]

@albert-github Thanks for identifying the issues and solutions. Will address these shortly.

[albert-github]

I've done a "small" grep on the sources to identify some more doi entries and created this bib file: doi2bib.bib.tar.gz
Edit created new file, see #3662 (comment)

Also thanks to https://github.com/schneiderfelipe/doi (especially the file: https://github.com/schneiderfelipe/doi/blob/master/src/doi2bib)

There were a few references for which I was unable to create a bibtex entry:

• https://doi.org/10.5281/zenodo.8136801
  Looks like to be a poster at SciPy 2023 conference, I copuldn't find a bibtex entry

• https://doi.org/10.54294/j8lsa66
  description in code doesn't help me anywhere further

• https://doi.org/10.54294/lf8u753
  description in code doesn't help me anywhere further

• https://doi.org/10.54294/olkmog2
  Looks like to be, is this correct?

  @article{McCormick2010
  author = "M. McCormick",
  title = "An Open Source, Fast Ultrasound B-Mode Implementation for Commodity Hardware",
  howpublished = "\url{http://hdl.handle.net/10380/3159}",
  year = 2010,
  month = 05,
  abstract = "This document describes an open source, high performance ultrasound B-Mode implementation based on the Insight Toolkit (ITK). ITK extensions are presented to calculate the radio-frequency (RF) signal envelope. A variety of 1D Fast Fourier Transform options are introduced including VNL, FFTW, and an OpenCL solution. Scan conversion is implemented for phased array or curvilinear transducers. The entire image processing pipeline is streamable to limit memory consumption during multi-frame or 3D acquisitions with the introduction of an itk::StreamingResampleImageFilter.
  ",
  institution = "University of Wisconsin-Madison",
  publisher = "The Insight Journal",
  doi = "10.54294/yjowe4",
  }
  

• https://doi.org/10.54294/olkmog9
  Looks like to be, is this correct?

  @article{Lowekamp2010,
    title = {A Streaming IO Base Class and Support for Streaming the MRC and VTK File Format},
    ISSN = {2327-770X},
    url = {http://dx.doi.org/10.54294/ufs19w},
    DOI = {10.54294/ufs19w},
    journal = {The Insight Journal},
    publisher = {NumFOCUS - Insight Software Consortium (ITK)},
    author = {Lowekamp,  Bradley and Chen,  David},
    year = {2010},
    month = jun
  }
  

[albert-github]

Independent of the above, I found 2 small problems, and thus incorrect link / no link, in the bib file, proposed patch: diff.patch

Citations with titles:

• Image characterizations based on joint gray level—run length distributions
• Digital image thresholding, based on topological stable-state

[blowekamp]

@albert-github I think McCormick2010 should reference the preferred DOI: https://doi.org/10.54294/yjowe4

Lowekamp2010 - looks right to me.

[albert-github]

Corrected new bib file (added 2 references as indicated in #3662 (comment) and #3662 (comment)): doi2bib_2.bib.tar.gz

[dzenanz]

I turned this into a PR: #5234.

[albert-github]

Proposed patch for the 2 "olkmog" type of references in the code: diff.patch.

[dzenanz]

Independent of the above, I found 2 small problems, and thus incorrect link / no link, in the bib file, proposed patch: diff.patch

Citations with titles:

• Image characterizations based on joint gray level—run length distributions
• Digital image thresholding, based on topological stable-state

Done via PR #5233.

[dzenanz]

@albert-github It would save me quite some time if you made PRs yourself. As your PRs are mostly documentation focused, I think it is fine if you skip hooks (git commit --no-verify -m "commit message" ) as per https://stackoverflow.com/questions/7230820/skip-git-commit-hooks. Afterwards you can push to a branch in your fork, and click on the link in the message from GitHub to open a PR. E.g.:

git.exe push --progress -- "myFork" master:olkmogDOI
Enumerating objects: 37, done.
Counting objects: 100% (37/37), done.
Delta compression using up to 24 threads
Compressing objects: 100% (19/19), done.
Writing objects: 100% (19/19), 1.46 KiB | 748.00 KiB/s, done.
Total 19 (delta 16), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (16/16), completed with 16 local objects.
remote:
remote: Create a pull request for 'olkmogDOI' on GitHub by visiting:
remote: https://github.com/dzenanz/ITK/pull/new/olkmogDOI
remote:
To github.com:dzenanz/ITK.git

• [new branch] master -> olkmogDOI

Success (1531 ms @ 2025-02-10 09:46:55)

[albert-github]

@dzenanz
Yes I can imagine it takes some time for you, would make my live a bit easier as well probably.
I'll think about it in the future.