Skip to content

Commit bddb8f7

Browse files
castedocastedo
committed
update BpDF page; point to draft spec
1 parent 48906c7 commit bddb8f7

File tree

4 files changed

+92
-66
lines changed

4 files changed

+92
-66
lines changed

‎docs/bdf/index.md

Lines changed: 4 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,4 @@
1-
Baseprint Document Format (BpDF)
2-
================================
3-
4-
BpDF is a format for encoding a *Baseprint document snapshot*.
5-
These snapshots can be identified with a
6-
[SoftWare Hash IDentifier (SWHID)](https://swhid.org).
7-
Baseprint document snapshots exemplify the concept of "baseprint" discussed in the
8-
document
9-
"[What is a baseprint?](https://perm.pub/HKSI5NPzMFmgRlb4Vboi71OTKYo)".
10-
11-
12-
Objectives
13-
----------
14-
15-
BpDF aims to minimize format rot.
16-
Unlike formats like LaTeX and Markdown, which are used for authoring, BpDF is designed
17-
for redistribution and archiving.
18-
19-
20-
BpDF'23
21-
-------
22-
23-
*BpDF'23* is the version of BpDF as supported by software circa 2023 that can read and
24-
write BpDF.
25-
26-
Technically, BpDF'23 is not a file format
27-
but a format for a directory-like data structure.
28-
This structure is addressable as
29-
a [Git](https://en.wikipedia.org/wiki/Git) tree and [SWHID](https://swhid.org)
30-
directory.
31-
32-
When working with BpDF data,
33-
it is often temporarily stored in a file system directory.
34-
However, for public long-term storage, BpDF data is stored in a SWHID addressable Git tree or
35-
an equivalent "directory" object in the Software Heritage Archive.
36-
37-
Inside BpDF'23, there is a file named `article.xml` encoded in a subset of the
38-
[JATS XML format](../jats.md).
39-
This file format can informally be referred to as *Baseprint JATS XML*.
40-
As of October 2023,
41-
all applications that read Baseprint document snapshots encoded in BpDF'23
42-
use the [epijats](https://gitlab.com/perm.pub/epijats) Python library.
43-
44-
45-
BpDF Reading Software
46-
---------------------
47-
48-
[epijats](https://gitlab.com/perm.pub/epijats):
49-
: An open-source library used by
50-
[perm.pub](https://perm.pub),
51-
[popgen.es](https://popgen.es),
52-
[BaseprintPress](https://gitlab.com/perm.pub/baseprintpress), and
53-
[Baseprinter](https://try.perm.pub/baseprinter/) (for previews).
54-
55-
### Snapshot Writing Software
56-
57-
[Baseprinter](https://try.perm.pub/baseprinter):
58-
: A BpDF authoring tool available through GitHub Actions, container, or local
59-
installation.
60-
61-
[Pandoc](https://try.perm.pub/pandoc):
62-
: This tool can output [JATS XML](../jats.md), which can be BpDF compatible.
63-
1+
---
2+
template: redirect.html
3+
location: ../bpdf/
4+
---

‎docs/bpdf/index.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
Baseprint Document Format (BpDF)
2+
================================
3+
4+
BpDF is the digital encoding format of a *Baseprint document snapshot*.
5+
These document snapshots can be identified with a
6+
[SoftWare Hash IDentifier (SWHID)](https://swhid.org).
7+
Baseprint document snapshots exemplify the concept of "baseprint" discussed in the
8+
document
9+
"[What is a baseprint?](https://perm.pub/HKSI5NPzMFmgRlb4Vboi71OTKYo)".
10+
As of 2024, these document snapshots are only used within
11+
[Baseprint document successions](../successions.md).
12+
13+
14+
Technical details of the format are being [documented in a draft specification on
15+
GitHub](https://github.com/castedo/bpdf-spec/).
16+
17+
18+
Objectives
19+
----------
20+
21+
The primary objective of BpDF is to minimize [format
22+
rot](https://doi.org/10.1038/scientificamerican1117-26) and maximize "format
23+
shelf-life", where software in the future is backward compatible with the present
24+
encoding format.
25+
Unlike formats like LaTeX and Markdown, which are used for authoring (in the present),
26+
BpDF is designed for redistribution and archiving (for the future).
27+
The primary tactic for minimizing format rot is to encode articles like those
28+
archived in [PubMed Central](https://en.wikipedia.org/wiki/PubMed_Central).
29+
30+
31+
Supporting Software
32+
-------------------
33+
34+
The BpDF format is implemented in the
35+
[open-source Python library epijats](https://pypi.org/project/epijats/).
36+
This library is used in the authoring tool
37+
[Baseprinter](https://try.perm.pub/baseprinter/) (for previews)
38+
and in
39+
[BaseprintPress](https://gitlab.com/perm.pub/baseprintpress)
40+
for generating websites, such as [pilot.perm.pub](https://pilot.perm.pub).
41+
42+
43+
Related Formats
44+
---------------
45+
46+
JATS XML:
47+
: The XML file inside BpDF is a sub-format of the [JATS XML Article Authoring
48+
format](https://jats.nlm.nih.gov/articleauthoring/).
49+
This Baseprint JATS XML subformat is more minimal than the JATS XML Article Authoring Tag Set.
50+
51+
52+
PubMed Central JATS XML Flavor:
53+
: The various different software systems of different
54+
organizations process different "flavors" of JATS XML.
55+
Baseprint JATS XML does not target supporting the various flavors of JATS.
56+
Baseprint JATS XML targets processing a subset of the JATS XML found in archived
57+
articles of the [PMC Open Access
58+
Subset](https://pmc.ncbi.nlm.nih.gov/tools/openftlist/).
59+
Baseprint JATS XML targets matching the rendering of the
60+
[PMC Article Previewer](https://pmc.ncbi.nlm.nih.gov/tools/article-previewer-intro/).
61+
62+
63+
JATS4R:
64+
: Baseprint JATS XML targets being similarly restrictive
65+
like [JATS4R (JATS for Reuse)](https://jats4r.niso.org/).
66+
However, Baseprint JATS XML targets re-use by
67+
[Free Open-Source Software](https://en.wikipedia.org/wiki/Free_and_open-source_software)
68+
for author self-archiving/publishing redistribution within
69+
[Baseprint document successions](../successions.md).
70+
71+
72+
Manuscript Exchange Common Approach (MECA):
73+
: Unlike JATS XML, BpDF is also a format for the packaging of the files included
74+
in a research document, such as images.
75+
In this respect, BpDF is similar to the
76+
[Manuscript Exchange Common Approach (MECA)](
77+
https://meca.niso.org/)
78+
Both BpDF and MECA are interchange formats between authoring and archiving.
79+
However, unlike MECA, BpDF targets author self-archiving/publishing and redistribution
80+
and not traditional publisher workflows.
81+
82+
83+
BpDF'23
84+
: *BpDF'23* is the version of BpDF supported by the
85+
[epijats](https://gitlab.com/perm.pub/epijats) Python library
86+
in 2023 and 2024.

‎docs/index.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,5 +28,4 @@ which can be redistributed and archived through various mechanisms.
2828
Some preprint servers could archive Baseprint document snapshots in a centralized
2929
approach.
3030
Alternatively, Baseprint document snapshots can be redistributed and archived
31-
in a distributed approach as [*Baseprint document successions*](successions.md).
32-
31+
in a distributed approach, such as [*Baseprint document successions*](successions.md).

‎mkdocs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ markdown_extensions:
2323
nav:
2424
- Interoperability Forum: index.md
2525
- Baseprint Document Format:
26-
- bdf/index.md
26+
- bpdf/index.md
2727
- jats.md
2828
- Document Successions: successions.md
2929
- About: about.md

0 commit comments

Comments
 (0)