Module: Propolize::Helpers

Included in:
PropositionalDocument, TextBeingProcessed
Defined in:
lib/propolize.rb

Overview

Propolize defines a very specific and constrained document structure which supports “propositional writing” It is similiar to Markdown, but with a limited set of Markdown features, and with some extensions particular to this document structure.

Propolize source code consists of the following types of ‘chunk’, where each chunk is one or more lines:

  1. A special property definition or command (starting with ‘##’ at the beginning of the line)

  2. A list (which will map to an HTML list) which starts with ‘* ’ at the beginning of the line for each list item. (The end of the list is marked by a blank line.)

  3. A ‘proposition’ (a special type of heading), which starts with ‘# ’ at the beginning of the line

  4. A secondary heading - a line with a following line containing only ‘———’ characters

  5. A paragraph - starting with a line which is not any of the above

(Note: secondary headings are only allowed in the appendix, because if they were in either the introduction

or the propositions, this would distract from the main idea that propositions in a propositional document
_are_ the headings. The appendix can be thought of as additional explanatory material that does not fit into
the main propositional format.)

Special property definitions and commands are terminated by a following blank line or end of file or by the start of another special property definition. All other chunks are terminated by a following blank line or the end of the file.

A propositional document also has a higher level structure in that it consists of an introduction followed by a sequence of propositions-with-explanations, followed by an optional appendix.

The introduction consists only of lists or paragraphs (i.e. no secondary headings)

Each proposition can be followed by zero or more lists of paragraphs (there are no secondary headings)

The appendix consists of a sequence of secondary headings, lists or paragraphs. The appendix is started by a special ‘##appendix’ command

Special property tags can occur anywhere. They are of the form ##date 23 May, 2014

(which defines the ‘date’ property to be ‘23 May, 2014’)

Required properties are ‘date’, ‘author’ and ‘title’. (Note: properties can be passed in via the ‘properties’ argument of the ‘propolize’ method,

in which case they do not need to appear in the source code.)

Detailed markup occurs within ‘text’ sections, these occur in the following contexts:

  • Propositions

  • Paragraphs

  • List items

  • Secondary headings

  • Text inside link definitions (see below)

The detailed markup includes the following:

  • ‘*’ to delineate italic text

  • ‘**’ to delineate bold text

  • ‘[]’ for anchor targets for the form ‘[name:]’ for normal anchors, and ‘[name::]’ for numbered footnote anchors

  • ‘[]()’ for links as in ‘[example.com/](An example website)’. Three types of URL definition exist -

    • name:

      for normal anchors

    • name::

      for numbered footnote anchors

    • url

      for all other URL’s

There is also a post-processing step where ‘–’ is converted into ‘–’

Two other special items parsed are:

  • ‘' followed by a character will output the HTML-escaped version of that character

  • HTML entities (e.g. ‘–’) are output as is

All other text is output as HTML-escaped text.

There are also special qualifier prefixes:

  1. The special tag qualifier may occur at the beginning of a paragraph, in the form ‘#:<tag> ’,

where <tag> is a special tag (currently the only option is “bq” for “blockquote”).

  1. The ‘critique’ qualifier ‘?? ’ can occur at the beginning of a paragraph or a list, and it qualifies

the list or paragraph as being part of the ‘critique’ where a propositional document is being written as a critique of some other propositional document.

Instance Method Summary collapse

Instance Method Details

#html_escape(s) ⇒ Object Also known as: h 



82
83
84
 
# File 'lib/propolize.rb', line 82

def html_escape(s)
  s.to_s.gsub(/&/, "&amp;").gsub(/>/, "&gt;").gsub(/</, "&lt;")
end