improved BDF page

singlesourcepub · Nov 3, 2023 · b8a5e33 · b8a5e33
1 parent 9c668f4
commit b8a5e33
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 36 deletions.
diff --git a/docs/bdf.md b/docs/bdf.md
diff --git a/docs/bdf/index.md b/docs/bdf/index.md
@@ -0,0 +1,38 @@
+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.
+
+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
+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)
+directory.
+
+When working with BDF data,
+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 JATS XML
+format.
+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
+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.
+
diff --git a/docs/index.md b/docs/index.md
@@ -3,27 +3,28 @@ Baseprints Interoperability Forum
 
 This website and associated GitHub repository are for sharing information about
 Baseprint open formats.
-A goal for this sharing is to help applications reading or writing data in a
+A goal of this sharing is to help applications reading or writing data in a
 baseprint format to better serve users with better interoperability.
 
 
 Baseprint Open Formats
 ----------------------
 
-Currently only one format uses the name "Baseprint".
+Currently, there is only one format using the word "Baseprint".
 However, [try.perm.pub](https://try.perm.pub) uses the phrase
-"Baseprint document succession" for data records in Document Succession Git Layout (DSGL).
+"Baseprint document succession" to refer to data records in Document Succession Git Layout (DSGL).
 
-[Baseprint Document Format (BDF)](bdf.md):
-:   "Document snapshot" is an intuitive phrase for what this format encodes.
+[Baseprint Document Format (BDF)](bdf/index.md):
+:   This format encodes a document snapshot.
 
-Document Succession Git Layout (DSGL) & Document Succession Identifier (DSI):
-:   Two formats which are a split and rename to be made from the specification for
+Document Succession Git Layout (DSGL)
+& Document Succession Identifier (DSI):
+:   These are two formats which are to be split out from and renamed from the specification of
     [Digital Succession Identifiers (DSI)](https://perm.pub/1wFGhvmv8XZfPx0O5Hya2e9AyXo).
-    This format is a succession of document snapshots in BDF.
+    A document succession is a succession of document snapshots.
 
-Existing Applications
----------------------
+Applications
+------------
 
 ### Websites
 
@@ -37,17 +38,17 @@ Existing Applications
 :   A BDF authoring tool that can be used via GitHub Actions, container or locally
     installed.
 
-[Pandoc](https://perm.pub/baseprinter):
-:   But only with JATS XML output that is BDF compatible.
+[Pandoc](https://try.perm.pub/pandoc):
+:   This tool can output JATS XML, which can be BDF compatible.
 
 [Hidos](https://hidos.readthedocs.io):
 :   Software library and tool that writes document successions in DSGL
-    (a.k.a., "Baseprint document successions").
+    (to encode a "Baseprint document succession").
 
 ### Software Reading in a Baseprint Format
 
 [epijats](https://gitlab.com/perm.pub/epijats):
-:   open-source library used by BaseprintPress, perm.pub and popgen.es and Baseprinter (for previews).
+:   An open-source library used by BaseprintPress, perm.pub and popgen.es and Baseprinter (for previews).
 
 [BaseprintPress](https://gitlab.com/perm.pub/baseprintpress):
 :   Generates web pages from Baseprint document successions.
@@ -66,8 +67,8 @@ Baseprint Feature D's
 
 The GitHub Discussions category
 [Baseprint Feature D's](https://github.com/singlesourcepub/baseprints/discussions/categories/baseprint-feature-d-s)
-is available to facilitate focused discussions, decisions, proposals, definitions etc...
-about a specific feature of a Baseprint format.
+is available to facilitate discussions, decisions, proposals, definitions etc...
+that focus on a specific feature of a Baseprint format.
 
 History
 -------

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -7,7 +7,7 @@ theme:
     - content.code.copy
 #    - toc.integrate
     - navigation.footer
-#    - navigation.indexes
+    - navigation.indexes
     - navigation.top
     - navigation.tracking
 markdown_extensions:
@@ -16,7 +16,8 @@ markdown_extensions:
   - def_list
 nav:
   - Interoperability Forum: index.md
-  - Baseprint Document Format: bdf.md
+  - Baseprint Document Format:
+    - bdf/index.md
 watch:
   - docs
   - theme