Improve the readability of the OSTree repository documentation.

Change-Id: I2d8a77a146951dcb39f569e0fb285deb2fe093d5

1 files changed, 93 insertions, 162 deletions

diff --git a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java
index 028f4cd..7ff12f7 100644
--- a/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java
+++ b/jgvariant-ostree/src/main/java/eu/mulk/jgvariant/ostree/package-info.java
@@ -7,178 +7,109 @@
  *
  * <p>An OSTree repository has the following layout:
  *
- * <table>
- *   <caption>OSTree repository layout</caption>
- *
- *   <tr>
- *     <td>{@code config}</td>
- *     <td>
- *       <p>
- *         A plain text file that contains various settings.  Among other things, this defines
- *         the <a href="https://ostreedev.github.io/ostree/formats/#the-archive-format">archive
- *         format</a> of the repository and whether files are compressed ({@code mode=archive-z2})
- *         or plain ({@code mode=bare}, {@code mode=bare-user}).
- *       </p>
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td>{@code summary}</td>
- *     <td>
- *       <p>
- *         A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is
- *         available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}.
- *       </p>
- *
- *       <p>This file may or may not exist and, if it exists, may or may not be up to date.</p>
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td>{@code refs/heads/{name...}}</td>
- *     <td>Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format
- *     (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to
- *     {@link eu.mulk.jgvariant.ostree.Commit} objects.  See below for the layout of the
- *     {@code objects/} directory that this refers to.</td>
- *   </tr>
- *
- *   <tr>
- *     <td>{@code objects/{checksumHead}/{checksumRest}.{fileExtension}}</td>
- *     <td>
- *       <p>
- *         Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType}
- *         and keyed by {@link eu.mulk.jgvariant.ostree.Checksum}.
- *       </p>
- *
- *       <p>
- *         Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit}
- *         ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}),
- *         and {@link eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as
- *         plain ({@code .file}) or compressed files ({@code .filez}).
- *       </p>
- *
- *       <p>
- *         Static delta information is not stored here, but in the {@code deltas/} and
- *         {@code delta-indexes/} directories (if available).
- *       </p>
- *
- *       <p>
- *         The individual parts of the file path are defined as follows:
- *       </p>
- *
+ * <dl>
+ *   <dt>{@code config}
+ *   <dd>
+ *       <p>A plain text file that contains various settings. Among other things, this defines the
+ *       <a href="https://ostreedev.github.io/ostree/formats/#the-archive-format">archive format</a>
+ *       of the repository and whether files are compressed ({@code mode=archive-z2}) or plain
+ *       ({@code mode=bare}, {@code mode=bare-user}).
+ *   <dt>{@code summary}
+ *   <dd>
+ *       <p>A {@link eu.mulk.jgvariant.ostree.Summary} object containing information on what is
+ *       available under {@code refs/}, {@code deltas/}, and {@code delta-indexes/}.
+ *       <p>This file may or may not exist and, if it exists, may or may not be up to date.
+ *   <dt>{@code refs/heads{/name...}}
+ *   <dd>
+ *       <p>Plain-text files containing {@link eu.mulk.jgvariant.ostree.Checksum}s in hex format
+ *       (see {@link eu.mulk.jgvariant.ostree.Checksum#ofHex}) referring to {@link
+ *       eu.mulk.jgvariant.ostree.Commit} objects. See below for the layout of the {@code objects/}
+ *       directory that this refers to.
+ *   <dt>{@code objects/{ξ₀ξ₁}/{ξ₂ξ₃ξ₄ξ₅...}.{ext}}
+ *   <dd>
+ *       <p>Objects of various types as described by {@link eu.mulk.jgvariant.ostree.ObjectType} and
+ *       keyed by {@link eu.mulk.jgvariant.ostree.Checksum}.
+ *       <p>Among other things, this is where you find {@link eu.mulk.jgvariant.ostree.Commit}
+ *       ({@code .commit)}, {@link eu.mulk.jgvariant.ostree.DirTree} ({@code .dirtree}), and {@link
+ *       eu.mulk.jgvariant.ostree.DirMeta} ({@code .dirmeta}) objects as well as plain ({@code
+ *       .file}) or compressed files ({@code .filez}).
+ *       <p>Static delta information is not stored here, but in the {@code deltas/} and {@code
+ *       delta-indexes/} directories (if available).
+ *       <p>The individual parts of the file path are defined as follows:
  *       <dl>
- *         <dt>{@code {checksumHead}}
- *         <dd>
- *           the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()}
- *         <dt>{@code {checksumRest}}
- *         <dd>
- *           the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the
- *           3rd character
- *         <dt>{@code {fileExtension}}
- *         <dd>
- *           the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type
+ *         <dt>{@code {ξ₀ξ₁}}
+ *         <dd>the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#hex()}
+ *         <dt>{@code {ξ₂ξ₃ξ₄ξ₅...}}
+ *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#hex()} starting from the
+ *             3rd character
+ *         <dt>{@code {ext}}
+ *         <dd>the {@link eu.mulk.jgvariant.ostree.ObjectType#fileExtension()} of the object type
  *       </dl>
- *     </td>
- *   </tr>
- *
- *   <tr id="delta-superblock">
- *     <td>{@code deltas/{targetChecksumMbase64Head}/{targetChecksumMbase64Rest}/superblock}</td>
- *     <td>
- *       <p>
- *         A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit)
- *         to the commit named by the checksum encoded in the path.
- *       </p>
- *
- *       <p>
- *         The individual parts of the file path are defined as follows:
- *       </p>
- *
+ *   <dt id="delta-superblock">{@code objects/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}.{ext}}/superblock
+ *   <dd>
+ *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from nothing (an empty commit)
+ *       to the commit named by the checksum encoded in the path.
+ *       <p>The individual parts of the file path are defined as follows:
  *       <dl>
- *         <dt>{@code {checksumHead}}
- *         <dd>
- *           the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()}
- *         <dt>{@code {checksumRest}}
- *         <dd>
- *           the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting
- *           from the 3rd character
+ *         <dt>{@code {μ₀μ₁}}
+ *         <dd>the first two characters of {@link
+ *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta
+ *             ends at
+ *         <dt>{@code {μ₂μ₃μ₄μ₅...}}
+ *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
+ *             target commit the delta ends at starting from the 3rd character
  *       </dl>
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td>{@code deltas/{targetChecksumMbase64Head}/{targetChecksumMbase64Rest}/{digit...}}</td>
- *     <td>
- *       <p>
- *         A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from
- *         nothing (an empty commit) to the commit named by the checksum encoded in the path.
- *       </p>
- *
- *       <p>
- *         The individual parts of the file path are defined as follows:
- *       </p>
- *
+ *   <dt>{@code deltas/{ν₀ν₁}/{ν₂ν₃ν₄ν₅...}/{digit...}}
+ *   <dd>
+ *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from
+ *       nothing (an empty commit) to the commit named by the checksum encoded in the path.
+ *       <p>The individual parts of the file path are defined as follows:
  *       <dl>
- *         <dt>{@code {checksumHead}}
- *         <dd>
- *           the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()}
- *         <dt>{@code {checksumRest}}
- *         <dd>
- *           the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting
- *           from the 3rd character
+ *         <dt>{@code {ν₀ν₁}}
+ *         <dd>the first two characters of {@link
+ *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target commit the delta
+ *             ends at
+ *         <dt>{@code {ν₂ν₃ν₄ν₅...}}
+ *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
+ *             target commit the delta ends at starting from the 3rd character
  *       </dl>
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td>{@code deltas/{sourceChecksumMbase64Head}/{sourceChecksumMbase64Rest}-{targetChecksumMbase64}/superblock}</td>
- *     <td>
- *       <p>
- *         A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit
- *         referenced by the first checksum encoded in the path to the target commit referenced
- *         in the second checksum encoded in the path.
- *       </p>
- *
- *       <p>
- *         The individual parts of the file path are defined as follows:
- *       </p>
- *
+ *   <dt>{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/superblock}
+ *   <dd>
+ *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaSuperblock} to get from the source commit
+ *       referenced by the first checksum encoded in the path to the target commit referenced in the
+ *       second checksum encoded in the path.
+ *       <p>The individual parts of the file path are defined as follows:
  *       <dl>
- *         <dt>{@code {checksumHead}}
- *         <dd>
- *           the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()}
- *         <dt>{@code {checksumRest}}
- *         <dd>
- *           the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting
- *           from the 3rd character
+ *         <dt>{@code {μ₀μ₁}}
+ *         <dd>the first two characters of {@link
+ *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta
+ *             starts from
+ *         <dt>{@code {μ₂μ₃μ₄μ₅...}}
+ *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
+ *             source commit the delta starts from starting from the 3rd character
+ *         <dt>{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}}
+ *         <dd>the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target
+ *             commit the delta ends at
  *       </dl>
- *     </td>
- *   </tr>
- *
- *   <tr>
- *     <td>{@code deltas/{sourceChecksumMbase64Head}/{sourceChecksumMbase64Rest}-{targetChecksumMbase64}/{digit...}}</td>
- *     <td>
- *       <p>
- *         A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from
- *         the source commit referenced by the first checksum encoded in the path to the target
- *         commit referenced in the second checksum encoded in the path.
- *       </p>
- *
- *       <p>
- *         The individual parts of the file path are defined as follows:
- *       </p>
- *
+ *   <dt>{@code deltas/{μ₀μ₁}/{μ₂μ₃μ₄μ₅...}-{ν₀ν₁ν₂ν₃ν₄ν₅...}/{digit...}}
+ *   <dd>
+ *       <p>A {@link eu.mulk.jgvariant.ostree.DeltaPartPayload} belonging to a delta that goes from
+ *       the source commit referenced by the first checksum encoded in the path to the target commit
+ *       referenced in the second checksum encoded in the path.
+ *       <p>The individual parts of the file path are defined as follows:
  *       <dl>
- *         <dt>{@code {checksumHead}}
- *         <dd>
- *           the first two characters of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()}
- *         <dt>{@code {checksumRest}}
- *         <dd>
- *           the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} starting
- *           from the 3rd character
+ *         <dt>{@code {μ₀μ₁}}
+ *         <dd>the first two characters of {@link
+ *             eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the source commit the delta
+ *             starts from
+ *         <dt>{@code {μ₂μ₃μ₄μ₅...}}
+ *         <dd>the substring of {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the
+ *             source commit the delta starts from starting from the 3rd character
+ *         <dt>{@code {ν₀ν₁ν₂ν₃ν₄ν₅...}}
+ *         <dd>the full {@link eu.mulk.jgvariant.ostree.Checksum#modifiedBase64()} of the target
+ *             commit the delta ends at
  *       </dl>
- *     </td>
- *   </tr>
- * </table>
+ * </dl>
  */
 @API(status = Status.EXPERIMENTAL)
 package eu.mulk.jgvariant.ostree;