Skip to content

terms.md

Latest commit

 

History

History
182 lines (133 loc) · 6.7 KB

terms.md

File metadata and controls

182 lines (133 loc) · 6.7 KB

Terms

Instead of just using an logical anchor as target for a markdown reference, it may be used as text also. Therefore, it must be enriched by some text used as term.

The term name is an alias for the given text. It can be used to consistently use some terminology across the complete document tree defined and changeable at a single place.

Term Anchors

Anchors for terms are just defined by using the logical anchor syntax adding a text separated by a colon ( :).

For example

# My Chapter
{{term:text}}

Like regular logical anchors, a term anchor might be placed anywhere in a Markdown document, therefore, it is possible to link to any location, not only section headers.

Another possibility is to define the term text by some text substitution commands like include or execute by preceding those commands by {term}{<term>}:

  {{term}{<term>}{<cmd>}...}}

For example the term declaration

  {{term}{text}{include}{../../../scan.go}{symbol}{func *([a-zA-Z]+) *\(}}

imports the term value "ParseTerm" from some source file. It is then used by {{{text}}} to refer to the value in any document of the document tree.

Optionally, formatting options man be given:

  • `: format as code
  • *: format in bold
  • _: format in italic

For example

  {{term}{`symbol}{include}{../../../scan.go}{symbol}{func *([a-zA-Z]+) *\(}}

defines some code symbol ParseTerm, which is formatted as code.

Term Usage

Term anchors may be used as usual for regular references, also. But there are two additional use cases:

  • Usage as link labeled with the term text. In this case the logical reference appears inside the [] pair of a markdown reference, but without the target part, which is automatically inserted from the term anchor:

    A [{{<name>}}] is a ....

    Such a reference is called term reference. It refers to an anchor providing an additional text. This term reference is substituted by a complete link for the term text and the term reference.

  • Just as text without any hyperlink. In this case the logical reference appears inside a {} pair:

    A {{{<name>}}} is a ....

Term Substitution Flavors

There are several flavors for using a term:

  • The term text is used as given
  • The term text is converted into its plural form. Here, the name is preceded by an asterisk (*). For example [{{*term}}].
  • The term text should be capitalized, for example if used as first word in a sentence. Here the first letter of the name is taken in upper case, for example [{{Term}}].
  • If the plural form as well as upper case should be substituted, both mechanisms can be combined, like in [{{*Term}}]

Term Extraction Pattern

The extraction filter for include and execute are using regular expressions. This has been used to extract term text assignments directly from the source base.

To simplify this, mdref supports some standard patterns, which can be specified by name instead of a regular expression.

  • go-const: the name of a Go constant ("(?m)^\s*const +([_a-zA-Z]+) *= *")
  • go-const-value: the value of a Go constant ("(?m)^\s*const +[_a-zA-Z]+ *= *(.*)\n")
  • go-var: the name of a Go variable ("(?m)^\s*var +([_a-zA-Z]+) *= *")
  • go-type: the name of a Go type ("(?m)^\s*([_a-zA-Z]+) *(?:struct|func|interface|\[|=)")
  • go-func: the name of a Go function ("(?m)^\s*func\s+(?:\(\s*\w+\s+[\w*]+\s*\)\s+)?(\w+)")

Other Patterns

There are also other useful patterns, like:

  • go-line-comment: ("(?m)^\s*//\s*(.*)\n") extract comment text from a Go source file using line comment syntax.

  • go-comment: ("/\*\s*([^&ast;]*(?:\*+[^/][^&ast;]*)*)\s*\*/") extract comment text from a Go source file using standard comment syntax. It does not support the exclusion of comment lines starting with *.

  • html-comment: ("<!--+\s*([\s\S]*?)\s*-+->") extract HTML comment.

This complete list is generated by

{{term}{`go-line-comment}{include}{../../../patterns.go}{go-line-comment}{go-const}{$(1/_/-)}}
{{term}{`go-line-comment-value}{include}{../../../patterns.go}{go-line-comment}{go-const-value}}
- {{{go-line-comment}}}:  ({{{go-line-comment-value}}})
  {{include}{../../../patterns.go}{go-line-comment}{go-line-comment}}
{{term}{`go-comment}{include}{../../../patterns.go}{go-comment}{go-const}{$(1/_/-)}}
{{term}{`go-comment-value}{include}{../../../patterns.go}{go-comment}{go-const-value}}
- {{{go-comment}}}:  ({{{go-comment-value}}})
  {{include}{../../../patterns.go}{go-comment}{go-comment}}
{{term}{`html-comment}{include}{../../../patterns.go}{html-comment}{go-const}{$(1/_/-)}}
{{term}{`html-comment-value}{include}{../../../patterns.go}{html-comment}{go-const-value}}
- {{{html-comment}}}:  ({{{html-comment-value}}})
  {{include}{../../../patterns.go}{html-comment}{html-comment}}

This complete list is generated by 

{{include}{terms.md}{other patterns}}

surrounded by the key selector for other patterns.

Pattern Definition

With the pattern command patterns can be created as part of the document tree.

For example

{{pattern}{my-pattern}{(?m)^.*content: ?(.*)$}}

defines a new pattern. It is used here with

{{include}{_definitions.md}{content}{my-pattern}&rcub;

to provide the following result:

this is some test content
provided by a definition file.

The pattern and the content are defined in a file _definitions.md, which is evaluated but not generated into the target folder.

Here we define some new pattern

<!--- begin pattern --->
{{pattern}{my-pattern}{(?m)^.*content: ?(.*)$}}
<!--- end pattern --->

and define some match for it:

<!--- begin content --->
Only the prefixed content will be matched by 
the pattern defined above:
content: this is some test content
content: provided by a definition file.
<!--- end content --->
	
{{variable}{root}{../../..}}