Guest blog post from Reese on bibdata encoding

[ronaldtse]

For @ReesePlews. A guest post on how to encode bibliographic data using the span syntax from his experience in IEEE P2874.

A sample below:

# How to Encode Bibliographic Items Using `span:[...]` Syntax in Metanorma

Metanorma is a powerful tool for authoring and maintaining standards and technical documents. One essential aspect of creating these documents is citing various bibliographic items correctly. In Metanorma, the `span:[...]` syntax is used to encode bibliographic items in a structured and consistent manner. This blog post will guide you through encoding different types of bibliographic items using this syntax, providing examples from the IEEE P2874 Spatial Web project.

## Basic Structure

The `span:[...]` syntax in Metanorma allows you to define various bibliographic attributes such as title, organization, date, type, and URL. Here’s a general structure:

```plaintext
* [[[reference_id,1]]]
span:organization[Organization]
span:title[Title]
span:type[Type]
span:date[Date]
Available at: span:uri[URL]

Below are specific examples illustrating how to encode bibliographic items for different types of sources.

ISO and IEC Standards

Example: IEC Electropedia

* [[[ievterms_m,1]]]
span:organization[International Electrotechnical Commission (IEC)]
span:title[IEC Electropedia: The World's Online Electrotechnical Vocabulary]
span:type[misc]
span:date[2024]
Available at: span:uri[https://www.electropedia.org/]

IEEE Standards

Example: IEEE P7003 Algorithmic Bias Considerations

* [[[IEEE_7003_2021,1]]]
span:organization[IEEE Software & Systems Engineering Standards Committee (S2ESC)]
span:title[IEEE P7003 Algorithmic Bias Considerations]
span:type[misc]
Available at: span:uri[https://standards.ieee.org/ieee/7003/6980/]

Books

Example: The Future of Global AI Governance

* [[[dentons_ai_gov,1]]]
span:organization[Dentons, The Spatial Web Foundation, Verses]
span:type[booklet]
span:title[The Future of Global AI Governance]
Available at: span:uri[https://www.verses.ai/ai-governance]

Articles

Example: Active Inference and Intentional Behaviour

* [[[friston_202312,1]]]
span:surname[Friston], span:initials[K. J.]
span:surname[Salvatori], span:initials[T.]
span:surname[Isomura], span:initials[T.]
span:surname[Tschantz], span:initials[A.]
span:surname[Kiefer], span:initials[A.]
span:surname[Verbelen], span:initials[T.]
span:surname[Koudahl], span:initials[M.]
span:surname[Paul], span:initials[A.]
span:surname[Parr], span:initials[T.]
span:surname[Razi], span:initials[A.]
span:surname[Kagan], span:initials[B.]
span:surname[Buckley], span:initials[C. L.]
span:surname[Ramstead], span:initials[M. J. D.]
span:type[misc]
span:title[Active Inference and Intentional Behaviour]
In: span:in_title[arxiv: Quantitative Biology - Neurons and Cognition]
span:date[December 2023]
Available at: span:uri[https://arxiv.org/abs/2312.07547]

Journals from Proceedings

Example: Stanford Encyclopedia of Philosophy

* [[[stanford_encyclopedia_identity,1]]]
span:surname[Noonan], span:initials[H.]
span:surname[Curtis], span:initials[B.]
span:type[misc]
span:title[Identity]
In: span:in_title[Stanford Encyclopedia of Philosophy]
span:date[July 2022]
Available at: span:uri[https://plato.stanford.edu/entries/identity/]

Websites

Example: H3 Geospatial Functions

* [[[H3_geo_functions,1]]]
span:organization[Apache Software Foundation]
span:title[databricks - H3 geospatial functions]
span:type[misc]
span:date[2024]
Available at: span:uri[https://docs.databricks.com/en/sql/language-manual/sql-ref-h3-geospatial-functions.html]

Organizations

Example: ITU Focus Group on Metaverse

* [[[itu_fg_mv,1]]]
span:organization[ITU Focus Group on Metaverse (FG-MV)]
span:type[misc]
Available at: span:uri[https://www.itu.int/en/ITU-T/focusgroups/mv/Pages/default.aspx]

Conclusion

Using the span:[...] syntax in Metanorma to encode bibliographic items ensures that your references are clear, consistent, and easy to manage. Whether you're referencing ISO standards, IEEE standards, books, articles, conference proceedings, websites, or organizations, the examples provided in this post should help you format your references correctly.

Metanorma's flexibility and power make it an excellent choice for creating standards and technical documents. By mastering the span:[...] syntax for bibliographic items, you'll enhance the professionalism and accuracy of your documents.

Happy documenting with Metanorma!

[ReesePlews]

thanks @ronaldtse this is a great start, i will work on this mid-June.