Quarry

This page collects snippets for copy/paste that have been found useful to have on quick-dial.

Snippets for YAML front matter

kramdown_options in YAML

These are processing options that are often selected:

• ol_start_at_first_marker starts a numbered list with the number found at the start of the first item. (This would be the default, but there are dusty decks that rely on starting at 1 always.)
• nested_ol_types automatically selects the formats given (see type= in <ol>) for nested numbered lists.
• transliterated_header_ids transliterates non-ASCII characters in headers when automatically generating anchor IDs; this is useful where non-Latin writing systems (e.g., for names, formulae) are used in headers. gem install stringex to obtain the gem with the transliteration functionality.
• auto_id_prefix adds the given prefix to automatically generated anchor IDs, sec- is a popular prefix for Section numbers.

kramdown_options:
  ol_start_at_first_marker: true
  nested_ol_types: 1, i, a
  transliterated_header_ids: true
  auto_id_prefix: sec-

Upon ingestion of markdown, kramdown detects certain typographical symbols (dashes, ellipses, certain kinds of quotes). By a default specificaly in kramdown-rfc, these are written out in the XML output in the form shown below. The below can be added explicitly to the header to specify different output, e.g., selecting a format for the Em-dash that may be more comfortable for the RFC editor. Specifying any of this at all returns the output from the ASCIIized kramdown-rfc defaults to kramdown defaults, which is using Unicode characters. If that is not desired, it may be beneficial to copy all of the below and make the adaptations where needed.

typographic_symbols:
  mdash: "---"
  ndash: "--"
  hellip: "..."
  laquo_space: "<< "
  raquo_space: " >>"
  laquo: "<<"
  raquo: ">>"

Note that detection of typographical quotation marks (quotes) uses a different mechanism, which lists representations for left single quotes, right single quotes, left double quotes, right double quotes, in an array of four elements that are either Unicode scalar values (integers) or HTML entity names.

smart_quotes: false                          # default typewriter
smart_quotes: [apos, apos, quot, quot]       # " spelled out
smart_quotes: [39, 39, 34, 34]               # " " numerically

smart_quotes: true                           # EN (normal)
smart_quotes: [lsquo, rsquo, ldquo, rdquo]   # " spelled out

smart_quotes: [sbquo, lsquo, bdquo, ldquo]   # DE Anführungszeichen
smart_quotes: [rsaquo, lsaquo, raquo, laquo] # DE Möwchen
smart_quotes: [lsaquo, rsaquo, laquo, raquo] # CH
smart_quotes: [sbquo, lsquo, 187, 171]       # mixed
smart_quotes: [sbquo, lsquo, 10095, 10094]   # " weirder

xml2rfc v3 options

These are processing instructions understood by xml2rfc. Right now, this includes silencing warnings and selecting layout variants for rendering tables in the plaintext form.

v3xml2rfc:
  silence:
  - Expected one of the permitted words or phrases from RFC 2119
  - The document date .*? is more than 3 days away from today's date
  - Found SVG with width or height specified
  # table_borders: full
  table_borders: light
  # table_borders: minimal

author or contributor section:

Use the vertical bar | to separate first name(s) from last name(s). A text string in the contributor list is used to start the section. contribution: is used for a small text string attached to an entry.

author:
- name: Carsten Bormann
  org: Universität Bremen TZI
  street: Postfach 330440
  city: Bremen
  code: D-28359
  country: Germany
  phone: +49-99-421-218-63921
  email: [email protected]

contributor:
- >
    The following people have substantially contributed to this document:
- name: Peter | van der Stok
  org: consultant
  phone: "+3199625097806"
  email: [email protected]
  uri: https://vanderstok.tech
  role: editor
  contribution: >
    Peter started all this.

Tools

Looking for missed opportunities for section references

Emacs (occur on HTML): [^>]\(Section\|Appendix\)