Documentation
¶
Overview ¶
Package mdspan rewrites named regions of a committed markdown document in place.
The convention it implements predates it: tools/survey-gen has been rendering live/SURVEY.md, live/LIMITATIONS.md and live/COVERAGE.md from committed artifacts since issue #49, marking each generated region with a pair of HTML comments and passing the rest of the file through byte-for-byte. Generated and hand-written prose live in one document, and a reader can tell which is which by looking.
<!-- survey-gen:begin residue-deprecated --> ...generated... <!-- survey-gen:end residue-deprecated -->
GitHub issue #110 added a second generator writing into the same document, which is what made the convention worth extracting rather than copying. The tool name is a parameter so each generator owns its own spans and two of them cannot silently claim the same region.
Every operation is strict: exactly one begin marker, exactly one end marker, in that order. A generator writes the file in place, so a missing or duplicated marker has to be an error rather than a guess about which region was meant.
Index ¶
- type Markers
- func (m Markers) Block(name string) (begin, end string)
- func (m Markers) Content(doc, md, name string) (string, error)
- func (m Markers) ContentInline(doc, md, name string) (string, error)
- func (m Markers) Inline(name string) (begin, end string)
- func (m Markers) Replace(doc, md, name, body string) (string, error)
- func (m Markers) ReplaceInline(doc, md, name, body string) (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Markers ¶
type Markers struct {
// contains filtered or unexported fields
}
Markers is one generator's marker vocabulary, built by For.
func For ¶
For returns the marker vocabulary for a generator, named as it appears in the comments: "survey-gen", "limits-gen".
func (Markers) Block ¶
Block returns the begin and end markers for a span whose body occupies whole lines - a paragraph, a table, a run of headings.
The begin marker carries a trailing newline, which is what puts the body on its own line. That is wrong for a span inside a table cell or mid sentence; see Markers.Inline.
func (Markers) Content ¶
Content returns the committed text between a block span's markers, which is what a drift test compares against a fresh render.
func (Markers) ContentInline ¶
ContentInline is Markers.Content for an inline span.
func (Markers) Inline ¶
Inline returns the begin and end markers for a span that has to stay on one physical line, such as a markdown table cell or a phrase inside a sentence, both of which break if a literal newline lands in them.
func (Markers) Replace ¶
Replace swaps the text between a block span's markers for body.
doc names the document in error messages only; it does not affect which bytes are replaced.
func (Markers) ReplaceInline ¶
ReplaceInline is Markers.Replace for an inline span.
Source Files