References

[ArthurChapman]

1. Need to check in text references for consistency with respect to comma (Smith, 2017) versus (Smith 2017) - does GBIF have a policy?

2. Need to check all references for consistency of date. Wieczorek, J.R. (2015) .... or Wieczorek, J.R. 2015. ....

[kcopas]

1. (Smith 2017)
2. Wieczorek JR (2015)

Fewer marks/less ink wherever possible, e.g. Wieczorek JR, Zermoglio P & Chapman A (2015)

Call it Harvard minimalist.

[tucotuco]

Thanks Kyle. Is this already documented somewhere? Or should it be in the forthcoming Documentation Cookbook that will reside at https://github.org/gbif/docs-cookbook? Or maybe on https://www.gbif.org/article/3wHK3RUNHdCY2TMGYMcPsO/digital-documentation where there are already structural and naming conventions?

…

On Wed, Mar 27, 2019 at 9:27 AM Kyle Copas ***@***.***> wrote: 1. (Smith 2017) 2. Wieczorek JR (2015) Fewer marks/less ink wherever possible, e.g. Wieczorek JR, Zermoglio P & Chapman A (2015) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAcP64Y2Oec7pHrGOIFyPLQoPbCVu8O1ks5va2OwgaJpZM4cNqdJ> .

[kcopas]

No, not (well?) documented—long-standing practice prob. missing from out-of-date internal style guide, which should provide foundation for all this. Digital documentation page is out of phase with latest developments. Relevant repos are digital-documentation (where style guide should/will go) and document-template (for cloning). Moving house, so not much hope of cleaning up any of this systematically this week…sorry.

[tucotuco]

Rather than digital-documention, which isn't a GitHub repo, do you mean https://github.com/gbif/doc-documentation-guidelines? Good luck with the move! On Wed, Mar 27, 2019 at 10:23 AM Kyle Copas <notifications@github.com> wrote:

…

No, not (well?) documented—long-standing practice prob. missing from out-of-date internal style guide, which should provide foundation for all this. Digital documentation page is out of phase with latest developments. Relevant repos are digital-documentation (where style guide should/will go) and document-template (for cloning). Moving house, so not much hope of cleaning up any of this systematically this week…sorry. On Wed, 27 Mar 2019 at 13.47, John Wieczorek ***@***.***> wrote: > Thanks Kyle. Is this already documented somewhere? Or should it be in the > forthcoming Documentation Cookbook that will reside at > https://github.org/gbif/docs-cookbook? Or maybe on > https://www.gbif.org/article/3wHK3RUNHdCY2TMGYMcPsO/digital-documentation > where > there are already structural and naming conventions? > > On Wed, Mar 27, 2019 at 9:27 AM Kyle Copas ***@***.***> > wrote: > > > > > 1. (Smith 2017) > > 2. Wieczorek JR (2015) > > > > Fewer marks/less ink wherever possible, e.g. Wieczorek JR, Zermoglio P & > > Chapman A (2015) > > > > — > > You are receiving this because you are subscribed to this thread. > > Reply to this email directly, view it on GitHub > > < > #2 (comment) > >, > > or mute the thread > > < > https://github.com/notifications/unsubscribe-auth/AAcP64Y2Oec7pHrGOIFyPLQoPbCVu8O1ks5va2OwgaJpZM4cNqdJ > > > > . > > > > — > You are receiving this because you commented. > > > Reply to this email directly, view it on GitHub > < #2 (comment) >, > or mute the thread > < https://github.com/notifications/unsubscribe-auth/ALzkZCA9dU-hUOmA5R281AbItfZA7mvAks5va2hIgaJpZM4cNqdJ > > . > -- ===== *Kyle Copas* Lyngbyvej 323 DK-2820 Gentofte (+45) 28 75 14 75 | skype kylecopas — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#2 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAcP6xAhEh2qegYBm4KflhMP7oJEFIpQks5va3C_gaJpZM4cNqdJ> .

[MattBlissett]

I first commented on the Glossary issue, but this belongs here instead.

There are two main options for references / bibliography. The first (default) way is very minimal -- it's just a normal unordered list with some links.

The second way, using BibTeX, generates the citations from a BibTeX database automatically, so the author doesn't control commas, dots, brackets and so on.

Default way

The built-in AsciiDoctor way to do this is to make the references section into a bibliography by adding the [bibliography] line before the section header:

[bibliography]
== References

Then define an anchor for each reference, e.g.

- [[[asprs14,ASPRS 2014]]]. _ASPRS Positional Accuracy Standards…

The bit before the comma is the identifier, the optional bit after is how it is displayed.

And then change the text to use these anchors:

your **<<georeference>>** when using maps of this type <<asprs14>>.

The result is

your georeference when using maps of this type [ASPRS 2014].

in the prose and

[ASPRS 2014]. ASPRS Positional Accuracy Standards…

in the bibliography. It looks like this only supports the "square brackets" style, unless the processor is overridden in code.

---

BibTeX plugin way

The alternative is to use a bibliography management file.

1. Create a references.bib file in BibTeX format.

@article{ASPRS1990,
  author={{ASPRS Professional Practicing Division}},
  title={ASPRS Accuracy Standards for Large-Scale Maps},
  journal={Photogrammetric Engineering and Remote Sensing},
  year={1990},
  month={July},
  volume={56},
  number={7},
  pages={1068-1070},
  url={http://www.asprs.org/a/society/committees/standards/1990_jul_1068-1070.pdf},
  accessed={13 Dec 2019}
}

(I've not used BibTeX format before, so I've tried to make that a full example. It's probably worth using a tool that can manage these files, the format is a bit clunky.)

2. Include cite:[] and citenp:[] (no parentheses) macros in the prose:

the **<<accuracy>>** added by the digitizing process (see citenp:[ASPRS1990]).

3. Set up the BibTeX plugin in index.en.adoc

:bibtex-file: references.bib
:bibtex-style: gbif // Literally a thousand to choose from, yet not one showed DOIs, URLs and access dates.
:bibtex-order: alphabetical

The result is

the digitizing process (see ASPRS Professional Practicing Division (1990)).

And

ASPRS Professional Practicing Division (1990) ASPRS Accuracy Standards for Large-Scale Maps. Photogrammetric Engineering and Remote Sensing 56: 1068–1070. http://www.asprs.org/a/society/committees/standards/1990_jul_1068-1070.pdf (accessed 13 December 2019)

I've made a pull request #6 with the start of the second method, in case you/Kyle prefer that one.