Documentation
¶
Overview ¶
Package okf writes a doc.Outline as an Open Knowledge Format bundle.
OKF v0.2 is markdown files with YAML frontmatter in a directory tree, where only the `type` field is required and consumers must not reject a bundle for anything they do not recognize. That tolerance shapes this package: emit conservatively, add a field when it is trustworthy, and never invent a value to fill a slot.
One clause becomes one concept document, which is the point of the exercise. The specification is going into a bundle so a model can query it clause by clause to build the native libraries this repo is for, and a query that returns "somewhere in these 1,023 pages" is the failure this replaces. A clause is the unit the specification itself cross-references, so it is the unit a retrieval hit should be.
This is a sink, like sink/markdown: it consumes doc and knows nothing about PDFs. Unlike sink/markdown it does touch the filesystem, because a bundle *is* a directory tree — there is no io.Writer form of "981 files in a hierarchy". Rendering each file is still separable, and Bundle returns the files as values so a test never writes to disk.
Index ¶
Constants ¶
const MaxPath = 150
MaxPath is the length a bundle-relative path is kept within.
Windows is the binding constraint: MAX_PATH is 260 characters for the absolute path, so what a bundle may spend is 260 less whatever destination directory the user names. 150 leaves a little over 100 for that, which covers a home directory and a project folder without being so tight that clause names stop being readable. The bound is enforced rather than hoped for — see fit.
Exported so the corpus test asserts against this rather than against a second copy of the number, which would drift.
Variables ¶
var DefaultOptions = Options{ Type: "PDF Spec Clause", Generator: "pdfspec/dev", Preamble: true, Unplaced: true, }
DefaultOptions is what the CLI emits with no flags: everything the outline holds, because a bundle that drops content by default is a bundle whose omissions nothing reports.
Functions ¶
Types ¶
type File ¶
File is one rendered file, with a bundle-relative path that always begins with "/".
Returned as values rather than written directly so that the rendering is testable without a filesystem — the assertions worth making about a bundle are about its shape and its links, and both are answerable from this.
type Options ¶
type Options struct {
// Type is the OKF `type` of every concept document. It is a free string that
// consumers must tolerate not recognizing (§4), so the value's job is to be
// descriptive rather than registered.
Type string
// DocID is the identifier in each concept's resource URI — "iso32000-2:2020" gives
// "iso32000-2:2020#7.5.8". Derived from the document's title when empty, which is a
// heuristic tuned for standards; a caller converting anything else should set it.
DocID string
// Generator is the actor written to generated.by, in OKF §7 form. Defaults to
// "pdfspec/dev" rather than to a bare name, because a consumer reads the
// "<producer>/<version>" shape to decide the value is not a human.
Generator string
// GeneratedAt is the ISO 8601 timestamp for generated.at, omitted when empty. Passed
// in rather than read from the clock here: a sink that stamps its own output cannot be
// tested for byte-identical rendering, and two runs over one document should differ
// only where the document did.
GeneratedAt string
// Artifacts emits blocks with doc.RoleArtifact, matching sink/markdown.Options.
Artifacts bool
// Preamble writes the outline's pre-heading content — a title page, a copyright
// notice — as a concept document. On by default, and the reason is measured: the whole
// of WTPDF's preamble is "This work is licensed under CC-BY-4.0". A bundle that drops
// its source's license terms is the one omission with a consequence outside the
// software, and an earlier draft of this defaulted it off on the theory that front
// matter carries no knowledge.
Preamble bool
// Unplaced writes text no clause claimed as a concept document. On by default,
// because on ISO 32000-2 that text is the whole of clause 1: the file draws its Scope
// outside any marked-content sequence, so no structure element names it. Dropping the
// Scope of a standard from a bundle a model will query about that standard is the
// worst available outcome; the document says plainly that its attribution is unknown.
Unplaced bool
}
Options configures the bundle.
type Stats ¶
type Stats struct {
Concepts int // concept documents, one per clause plus any preamble or unplaced
Indexes int // index.md files
Links int // cross-clause links resolved into the bundle
Dirs int // directories, which is the count of parent clauses
}
Stats reports what a bundle contains.
Source Files