diff --git a/docs/bdf/index.md b/docs/bdf/index.md index 767f0ea..8ad8e97 100644 --- a/docs/bdf/index.md +++ b/docs/bdf/index.md @@ -1,18 +1,29 @@ Baseprint Document Format (BDF) =============================== -BDF is a specific format for encoding a *Baseprint document snapshot*. -These snapshots can be referenced with a: - -* [SoftWare Hash IDentifier SWHID](https://swhid.org), and -* [*Document Succession Identifier (DSI)*](https://perm.pub/1wFGhvmv8XZfPx0O5Hya2e9AyXo) - plus edition number, as found inside a [perm.pub](https://perm.pub) URL. - +BDF is a format for encoding a *Baseprint document snapshot*. +These snapshots can be identified with a +[SoftWare Hash IDentifier (SWHID)](https://swhid.org). Baseprint document snapshots exemplify the concept of "baseprint" discussed in the document "[What is a baseprint?](https://perm.pub/HKSI5NPzMFmgRlb4Vboi71OTKYo)". -Technically, BDF is not a file format + +Objectives +---------- + +BDF aims to minimize format rot. +Unlike formats like LaTeX and Markdown, which are used for authoring, BDF is designed +for redistribution and archiving. + + +BDF'23 +------ + +*BDF'23* is the version of BDF as supported by software circa 2023 that can read and +write BDF. + +Technically, BDF'23 is not a file format but a format for a directory-like data structure. This structure is addressable as a [Git](https://en.wikipedia.org/wiki/Git) tree and [SWHID](https://swhid.org) @@ -23,16 +34,30 @@ it is often temporarily stored in a file system directory. However, for public long-term storage, BDF data is stored in a SWHID addressable Git tree or an equivalent "directory" object in the Software Heritage Archive. -Inside BDF, there is a file named `article.xml` encoded in a subset of the +Inside BDF'23, there is a file named `article.xml` encoded in a subset of the [JATS XML format](../jats.md). This file format can informally be referred to as *Baseprint JATS XML*. As of October 2023, -all applications that read Baseprint document snapshots encoded in BDF +all applications that read Baseprint document snapshots encoded in BDF'23 use the [epijats](https://gitlab.com/perm.pub/epijats) Python library. -Objectives ----------- -BDF aims to minimize format rot. -Unlike formats like LaTeX and Markdown, which are used for authoring, BDF is designed for archiving. +BDF Reading Software +-------------------- + +[epijats](https://gitlab.com/perm.pub/epijats): +: An open-source library used by + [perm.pub](https://perm.pub), + [popgen.es](https://popgen.es), + [BaseprintPress](https://gitlab.com/perm.pub/baseprintpress), and + [Baseprinter](https://try.perm.pub/baseprinter/) (for previews). + +### Snapshot Writing Software + +[Baseprinter](https://try.perm.pub/baseprinter): +: A BDF authoring tool available through GitHub Actions, container, or local + installation. + +[Pandoc](https://try.perm.pub/pandoc): +: This tool can output [JATS XML](../jats.md), which can be BDF compatible. diff --git a/docs/index.md b/docs/index.md index 6e7cb20..5061478 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,5 @@ + + Baseprints Interoperability Forum ================================= @@ -6,7 +8,7 @@ Baseprint open formats. The goal is to assist users and developers in assessing the interoperability between applications that read or write in a Baseprint format. - + Baseprint Feature D's --------------------- @@ -17,71 +19,16 @@ is available to facilitate discussions, decisions, proposals, definitions, etc.. that focus on specific features of a Baseprint format. -Baseprint Document Snapshots ----------------------------- +Snapshots vs. Successions +------------------------- [Baseprint Document Format (BDF)](bdf/index.md) is the -digital encoding format for Baseprint document snapshots, +digital encoding format for *Baseprint document snapshots*, which can be redistributed and archived through various mechanisms. - -### Snapshot Reading Software - -[epijats](https://gitlab.com/perm.pub/epijats): -: An open-source library used by BaseprintPress, [perm.pub](https://perm.pub), - [popgen.es](https://popgen.es), and Baseprinter (for previews). - -### Snapshot Writing Software - -[Baseprinter](https://try.perm.pub/baseprinter): -: A BDF authoring tool available through GitHub Actions, container, or local - installation. - -[Pandoc](https://try.perm.pub/pandoc): -: This tool can output JATS XML, which can be BDF compatible. - - - - -Baseprint Redistribution and Archiving --------------------------------------- - -Baseprint document snapshots can be redistributed and archived through various -mechanisms. Some preprint servers could archive Baseprint document snapshots in a centralized approach. Alternatively, Baseprint document snapshots can be redistributed and archived -in a distributed approach as *Baseprint document successions*. - -### Baseprint Document Successions - -*Baseprint document successions* are introduced at [try.perm.pub](https://try.perm.pub). - -Baseprint document snapshots can be stored within a document succession in -[Document Succession Git Layout (DSGL)](https://perm.pub/VGajCjaNP1Ugz58Khn1JWOEdMZ8) -format. -A [Document Succession Identifier (DSI)](https://perm.pub/1wFGhvmv8XZfPx0O5Hya2e9AyXo) -is a textual identifier for document successions and snapshots. -DSI, DSGL, and BDF together encode Baseprint document successions. - -#### Software Reading/Writing Baseprint Document Successions - -[Hidos](https://hidos.readthedocs.io): -: Software library and tool that reads/writes document successions in DSGL. - -[Document Succession Highly Manual Toolkit](https://manual.perm.pub): -: Manual for a software toolkit that reads/writes document successions in DSGL. - -[BaseprintPress](https://gitlab.com/perm.pub/baseprintpress): -: Software that generates web pages from Baseprint document successions. - For a tutorial, see ["Generate Pages for a Published Digital Succession"](https://try.perm.pub/tutorial/gen_pages/). - - -Related Technologies --------------------- - -- [JATS XML](jats.md) -- [Software Heritage Archive](https://www.softwareheritage.org/) -- [SoftWare Hash Identifier (SWHID)](https://www.swhid.org/) +in a distributed approach as [*Baseprint document successions*](successions.md). History diff --git a/docs/successions.md b/docs/successions.md new file mode 100644 index 0000000..0eea970 --- /dev/null +++ b/docs/successions.md @@ -0,0 +1,32 @@ +Baseprint Document Successions +============================== + +For an introduction to *Baseprint document successions*, +visit [try.perm.pub](https://try.perm.pub). + +A document succession encoded in the format +[Document Succession Git Layout (DSGL)](https://perm.pub/VGajCjaNP1Ugz58Khn1JWOEdMZ8) +records a succession of Baseprint document *snapshots*. +A [Document Succession Identifier (DSI)](https://perm.pub/1wFGhvmv8XZfPx0O5Hya2e9AyXo) +is a textual persistent identifier of a document succession. +DSI, DSGL, and [BDF](bdf/index.md) together encode Baseprint document successions. + +## Software Reading/Writing Baseprint Document Successions + +[Hidos](https://hidos.readthedocs.io): +: Software library and tool that reads/writes document successions in DSGL. + +[Document Succession Highly Manual Toolkit](https://manual.perm.pub): +: Manual for a software toolkit that reads/writes document successions in DSGL. + +[BaseprintPress](https://gitlab.com/perm.pub/baseprintpress): +: Software that generates web pages from Baseprint document successions. + For a tutorial, see ["Generate Pages for a Published Digital Succession"](https://try.perm.pub/tutorial/gen_pages/). + + +Related Technologies +-------------------- + +- [Software Heritage Archive](https://www.softwareheritage.org/) +- [SoftWare Hash Identifier (SWHID)](https://www.swhid.org/) + diff --git a/mkdocs.yml b/mkdocs.yml index 863980a..5821ec7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ nav: - Baseprint Document Format: - bdf/index.md - jats.md + - Document Successions: successions.md watch: - docs - theme