No OneTemporary
Actions

Subscribers

None

File Metadata

Created: Sat, Dec 21, 5:35 AM

View Options

	diff --git a/documentation-tools/doc-converter/DocBook.hs b/documentation-tools/doc-converter/DocBook.hs
	new file mode 100644
	index 0000000..151ae0c
	--- /dev/null
	+++ b/documentation-tools/doc-converter/DocBook.hs
	@@ -0,0 +1,1127 @@
	+{-# LANGUAGE NoImplicitPrelude #-}
	+{-
	+Copyright (C) 2006-2018 John MacFarlane <jgm@berkeley.edu>
	+
	+This program is free software; you can redistribute it and/or modify
	+it under the terms of the GNU General Public License as published by
	+the Free Software Foundation; either version 2 of the License, or
	+(at your option) any later version.
	+
	+This program is distributed in the hope that it will be useful,
	+but WITHOUT ANY WARRANTY; without even the implied warranty of
	+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	+GNU General Public License for more details.
	+
	+You should have received a copy of the GNU General Public License
	+along with this program; if not, write to the Free Software
	+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
	+-}
	+
	+{- \|
	+ Module : Text.Pandoc.Readers.DocBook
	+ Copyright : Copyright (C) 2006-2018 John MacFarlane
	+ License : GNU GPL, version 2 or above
	+
	+ Maintainer : John MacFarlane <jgm@berkeley.edu>
	+ Stability : alpha
	+ Portability : portable
	+
	+Conversion of DocBook XML to 'Pandoc' document.
	+-}
	+module Text.Pandoc.Readers.DocBook ( readDocBook ) where
	+import Prelude
	+import Control.Monad.State.Strict
	+import Data.Char (isSpace, toUpper)
	+import Data.Default
	+import Data.Either (rights)
	+import Data.Foldable (asum)
	+import Data.Generics
	+import Data.List (intersperse)
	+import Data.Maybe (fromMaybe)
	+import Data.Text (Text)
	+import qualified Data.Text as T
	+import Text.HTML.TagSoup.Entity (lookupEntity)
	+import Text.Pandoc.Builder
	+import Text.Pandoc.Class (PandocMonad)
	+import Text.Pandoc.Options
	+import Text.Pandoc.Shared (crFilter, safeRead)
	+import Text.TeXMath (readMathML, writeTeX)
	+import Text.XML.Light
	+
	+{-
	+
	+List of all DocBook tags, with [x] indicating implemented,
	+[o] meaning intentionally left unimplemented (pass through):
	+
	+[o] abbrev - An abbreviation, especially one followed by a period
	+[x] abstract - A summary
	+[o] accel - A graphical user interface (GUI) keyboard shortcut
	+[x] ackno - Acknowledgements in an Article
	+[o] acronym - An often pronounceable word made from the initial
	+[o] action - A response to a user event
	+[o] address - A real-world address, generally a postal address
	+[ ] affiliation - The institutional affiliation of an individual
	+[ ] alt - Text representation for a graphical element
	+[o] anchor - A spot in the document
	+[x] answer - An answer to a question posed in a QandASet
	+[x] appendix - An appendix in a Book or Article
	+[x] appendixinfo - Meta-information for an Appendix
	+[o] application - The name of a software program
	+[x] area - A region defined for a Callout in a graphic or code example
	+[x] areaset - A set of related areas in a graphic or code example
	+[x] areaspec - A collection of regions in a graphic or code example
	+[ ] arg - An argument in a CmdSynopsis
	+[x] article - An article
	+[x] articleinfo - Meta-information for an Article
	+[ ] artpagenums - The page numbers of an article as published
	+[x] attribution - The source of a block quote or epigraph
	+[ ] audiodata - Pointer to external audio data
	+[ ] audioobject - A wrapper for audio data and its associated meta-information
	+[x] author - The name of an individual author
	+[ ] authorblurb - A short description or note about an author
	+[x] authorgroup - Wrapper for author information when a document has
	+ multiple authors or collaborators
	+[x] authorinitials - The initials or other short identifier for an author
	+[o] beginpage - The location of a page break in a print version of the document
	+[ ] bibliocoverage - The spatial or temporal coverage of a document
	+[x] bibliodiv - A section of a Bibliography
	+[x] biblioentry - An entry in a Bibliography
	+[x] bibliography - A bibliography
	+[ ] bibliographyinfo - Meta-information for a Bibliography
	+[ ] biblioid - An identifier for a document
	+[o] bibliolist - A wrapper for a set of bibliography entries
	+[ ] bibliomisc - Untyped bibliographic information
	+[x] bibliomixed - An entry in a Bibliography
	+[ ] bibliomset - A cooked container for related bibliographic information
	+[ ] biblioref - A cross reference to a bibliographic entry
	+[ ] bibliorelation - The relationship of a document to another
	+[ ] biblioset - A raw container for related bibliographic information
	+[ ] bibliosource - The source of a document
	+[ ] blockinfo - Meta-information for a block element
	+[x] blockquote - A quotation set off from the main text
	+[x] book - A book
	+[x] bookinfo - Meta-information for a Book
	+[x] bridgehead - A free-floating heading
	+[x] callout - A “called out” description of a marked Area
	+[x] calloutlist - A list of Callouts
	+[x] caption - A caption
	+[x] caution - A note of caution
	+[x] chapter - A chapter, as of a book
	+[x] chapterinfo - Meta-information for a Chapter
	+[ ] citation - An inline bibliographic reference to another published work
	+[ ] citebiblioid - A citation of a bibliographic identifier
	+[ ] citerefentry - A citation to a reference page
	+[ ] citetitle - The title of a cited work
	+[ ] city - The name of a city in an address
	+[x] classname - The name of a class, in the object-oriented programming sense
	+[ ] classsynopsis - The syntax summary for a class definition
	+[ ] classsynopsisinfo - Information supplementing the contents of
	+ a ClassSynopsis
	+[ ] cmdsynopsis - A syntax summary for a software command
	+[ ] co - The location of a callout embedded in text
	+[x] code - An inline code fragment
	+[x] col - Specifications for a column in an HTML table
	+[x] colgroup - A group of columns in an HTML table
	+[ ] collab - Identifies a collaborator
	+[ ] collabname - The name of a collaborator
	+[ ] colophon - Text at the back of a book describing facts about its production
	+[x] colspec - Specifications for a column in a table
	+[x] command - The name of an executable program or other software command
	+[x] computeroutput - Data, generally text, displayed or presented by a computer
	+[ ] confdates - The dates of a conference for which a document was written
	+[ ] confgroup - A wrapper for document meta-information about a conference
	+[ ] confnum - An identifier, frequently numerical, associated with a conference for which a document was written
	+[ ] confsponsor - The sponsor of a conference for which a document was written
	+[ ] conftitle - The title of a conference for which a document was written
	+[x] constant - A programming or system constant
	+[ ] constraint - A constraint in an EBNF production
	+[ ] constraintdef - The definition of a constraint in an EBNF production
	+[ ] constructorsynopsis - A syntax summary for a constructor
	+[ ] contractnum - The contract number of a document
	+[ ] contractsponsor - The sponsor of a contract
	+[ ] contrib - A summary of the contributions made to a document by a
	+ credited source
	+[ ] copyright - Copyright information about a document
	+[ ] coref - A cross reference to a co
	+[ ] corpauthor - A corporate author, as opposed to an individual
	+[ ] corpcredit - A corporation or organization credited in a document
	+[ ] corpname - The name of a corporation
	+[ ] country - The name of a country
	+[ ] database - The name of a database, or part of a database
	+[x] date - The date of publication or revision of a document
	+[ ] dedication - A wrapper for the dedication section of a book
	+[ ] destructorsynopsis - A syntax summary for a destructor
	+[ ] edition - The name or number of an edition of a document
	+[ ] editor - The name of the editor of a document
	+[x] email - An email address
	+[x] emphasis - Emphasized text
	+[x] entry - A cell in a table
	+[ ] entrytbl - A subtable appearing in place of an Entry in a table
	+[ ] envar - A software environment variable
	+[x] epigraph - A short inscription at the beginning of a document or component
	+ note: also handle embedded attribution tag
	+[x] equation - A displayed mathematical equation
	+[ ] errorcode - An error code
	+[ ] errorname - An error name
	+[ ] errortext - An error message.
	+[ ] errortype - The classification of an error message
	+[ ] example - A formal example, with a title
	+[ ] exceptionname - The name of an exception
	+[ ] fax - A fax number
	+[ ] fieldsynopsis - The name of a field in a class definition
	+[x] figure - A formal figure, generally an illustration, with a title
	+[x] filename - The name of a file
	+[ ] firstname - The first name of a person
	+[ ] firstterm - The first occurrence of a term
	+[x] footnote - A footnote
	+[ ] footnoteref - A cross reference to a footnote (a footnote mark)
	+[x] foreignphrase - A word or phrase in a language other than the primary
	+ language of the document
	+[x] formalpara - A paragraph with a title
	+[ ] funcdef - A function (subroutine) name and its return type
	+[ ] funcparams - Parameters for a function referenced through a function
	+ pointer in a synopsis
	+[ ] funcprototype - The prototype of a function
	+[ ] funcsynopsis - The syntax summary for a function definition
	+[ ] funcsynopsisinfo - Information supplementing the FuncDefs of a FuncSynopsis
	+[x] function - The name of a function or subroutine, as in a
	+ programming language
	+[x] glossary - A glossary
	+[x] glossaryinfo - Meta-information for a Glossary
	+[x] glossdef - A definition in a GlossEntry
	+[x] glossdiv - A division in a Glossary
	+[x] glossentry - An entry in a Glossary or GlossList
	+[x] glosslist - A wrapper for a set of GlossEntrys
	+[x] glosssee - A cross-reference from one GlossEntry to another
	+[x] glossseealso - A cross-reference from one GlossEntry to another
	+[x] glossterm - A glossary term
	+[ ] graphic - A displayed graphical object (not an inline)
	+ Note: in DocBook v5 `graphic` is discarded
	+[ ] graphicco - A graphic that contains callout areas
	+ Note: in DocBook v5 `graphicco` is discarded
	+[ ] group - A group of elements in a CmdSynopsis
	+[ ] guibutton - The text on a button in a GUI
	+[ ] guiicon - Graphic and/or text appearing as a icon in a GUI
	+[ ] guilabel - The text of a label in a GUI
	+[x] guimenu - The name of a menu in a GUI
	+[x] guimenuitem - The name of a terminal menu item in a GUI
	+[x] guisubmenu - The name of a submenu in a GUI
	+[ ] hardware - A physical part of a computer system
	+[ ] highlights - A summary of the main points of the discussed component
	+[ ] holder - The name of the individual or organization that holds a copyright
	+[o] honorific - The title of a person
	+[ ] html:form - An HTML form
	+[x] imagedata - Pointer to external image data (only `fileref` attribute
	+ implemented but not `entityref` which would require parsing of the DTD)
	+[x] imageobject - A wrapper for image data and its associated meta-information
	+[ ] imageobjectco - A wrapper for an image object with callouts
	+[x] important - An admonition set off from the text
	+[x] index - An index
	+[x] indexdiv - A division in an index
	+[x] indexentry - An entry in an index
	+[x] indexinfo - Meta-information for an Index
	+[x] indexterm - A wrapper for terms to be indexed
	+[x] info - A wrapper for information about a component or other block. (DocBook v5)
	+[x] informalequation - A displayed mathematical equation without a title
	+[x] informalexample - A displayed example without a title
	+[ ] informalfigure - A untitled figure
	+[ ] informaltable - A table without a title
	+[ ] initializer - The initializer for a FieldSynopsis
	+[x] inlineequation - A mathematical equation or expression occurring inline
	+[ ] inlinegraphic - An object containing or pointing to graphical data
	+ that will be rendered inline
	+[x] inlinemediaobject - An inline media object (video, audio, image, and so on)
	+[ ] interface - An element of a GUI
	+[ ] interfacename - The name of an interface
	+[ ] invpartnumber - An inventory part number
	+[ ] isbn - The International Standard Book Number of a document
	+[ ] issn - The International Standard Serial Number of a periodical
	+[ ] issuenum - The number of an issue of a journal
	+[x] itemizedlist - A list in which each entry is marked with a bullet or
	+ other dingbat
	+[ ] itermset - A set of index terms in the meta-information of a document
	+[ ] jobtitle - The title of an individual in an organization
	+[x] keycap - The text printed on a key on a keyboard
	+[ ] keycode - The internal, frequently numeric, identifier for a key
	+ on a keyboard
	+[x] keycombo - A combination of input actions
	+[ ] keysym - The symbolic name of a key on a keyboard
	+[ ] keyword - One of a set of keywords describing the content of a document
	+[ ] keywordset - A set of keywords describing the content of a document
	+[ ] label - A label on a Question or Answer
	+[ ] legalnotice - A statement of legal obligations or requirements
	+[ ] lhs - The left-hand side of an EBNF production
	+[ ] lineage - The portion of a person's name indicating a relationship to
	+ ancestors
	+[ ] lineannotation - A comment on a line in a verbatim listing
	+[x] link - A hypertext link
	+[x] listitem - A wrapper for the elements of a list item
	+[x] literal - Inline text that is some literal value
	+[x] literallayout - A block of text in which line breaks and white space are
	+ to be reproduced faithfully
	+[ ] lot - A list of the titles of formal objects (as tables or figures) in
	+ a document
	+[ ] lotentry - An entry in a list of titles
	+[ ] manvolnum - A reference volume number
	+[x] markup - A string of formatting markup in text that is to be
	+ represented literally
	+[x] mathphrase - A mathematical phrase, an expression that can be represented
	+ with ordinary text and a small amount of markup
	+[ ] medialabel - A name that identifies the physical medium on which some
	+ information resides
	+[x] mediaobject - A displayed media object (video, audio, image, etc.)
	+[ ] mediaobjectco - A media object that contains callouts
	+[x] member - An element of a simple list
	+[x] menuchoice - A selection or series of selections from a menu
	+[ ] methodname - The name of a method
	+[ ] methodparam - Parameters to a method
	+[ ] methodsynopsis - A syntax summary for a method
	+[x] mml:math - A MathML equation
	+[ ] modespec - Application-specific information necessary for the
	+ completion of an OLink
	+[ ] modifier - Modifiers in a synopsis
	+[ ] mousebutton - The conventional name of a mouse button
	+[ ] msg - A message in a message set
	+[ ] msgaud - The audience to which a message in a message set is relevant
	+[ ] msgentry - A wrapper for an entry in a message set
	+[ ] msgexplan - Explanatory material relating to a message in a message set
	+[ ] msginfo - Information about a message in a message set
	+[ ] msglevel - The level of importance or severity of a message in a message set
	+[ ] msgmain - The primary component of a message in a message set
	+[ ] msgorig - The origin of a message in a message set
	+[ ] msgrel - A related component of a message in a message set
	+[ ] msgset - A detailed set of messages, usually error messages
	+[ ] msgsub - A subcomponent of a message in a message set
	+[ ] msgtext - The actual text of a message component in a message set
	+[ ] nonterminal - A non-terminal in an EBNF production
	+[x] note - A message set off from the text
	+[ ] objectinfo - Meta-information for an object
	+[ ] olink - A link that addresses its target indirectly, through an entity
	+[ ] ooclass - A class in an object-oriented programming language
	+[ ] ooexception - An exception in an object-oriented programming language
	+[ ] oointerface - An interface in an object-oriented programming language
	+[x] option - An option for a software command
	+[x] optional - Optional information
	+[x] orderedlist - A list in which each entry is marked with a sequentially
	+ incremented label
	+[ ] orgdiv - A division of an organization
	+[ ] orgname - The name of an organization other than a corporation
	+[ ] otheraddr - Uncategorized information in address
	+[ ] othercredit - A person or entity, other than an author or editor,
	+ credited in a document
	+[ ] othername - A component of a persons name that is not a first name,
	+ surname, or lineage
	+[ ] package - A package
	+[ ] pagenums - The numbers of the pages in a book, for use in a bibliographic
	+ entry
	+[x] para - A paragraph
	+[ ] paramdef - Information about a function parameter in a programming language
	+[x] parameter - A value or a symbolic reference to a value
	+[ ] part - A division in a book
	+[ ] partinfo - Meta-information for a Part
	+[ ] partintro - An introduction to the contents of a part
	+[ ] personblurb - A short description or note about a person
	+[ ] personname - The personal name of an individual
	+[ ] phone - A telephone number
	+[ ] phrase - A span of text
	+[ ] pob - A post office box in an address
	+[ ] postcode - A postal code in an address
	+[x] preface - Introductory matter preceding the first chapter of a book
	+[ ] prefaceinfo - Meta-information for a Preface
	+[ ] primary - The primary word or phrase under which an index term should be
	+ sorted
	+[ ] primaryie - A primary term in an index entry, not in the text
	+[ ] printhistory - The printing history of a document
	+[ ] procedure - A list of operations to be performed in a well-defined sequence
	+[ ] production - A production in a set of EBNF productions
	+[ ] productionrecap - A cross-reference to an EBNF production
	+[ ] productionset - A set of EBNF productions
	+[ ] productname - The formal name of a product
	+[ ] productnumber - A number assigned to a product
	+[x] programlisting - A literal listing of all or part of a program
	+[ ] programlistingco - A program listing with associated areas used in callouts
	+[x] prompt - A character or string indicating the start of an input field in
	+ a computer display
	+[ ] property - A unit of data associated with some part of a computer system
	+[ ] pubdate - The date of publication of a document
	+[ ] publisher - The publisher of a document
	+[ ] publishername - The name of the publisher of a document
	+[ ] pubsnumber - A number assigned to a publication other than an ISBN or ISSN
	+ or inventory part number
	+[x] qandadiv - A titled division in a QandASet
	+[o] qandaentry - A question/answer set within a QandASet
	+[o] qandaset - A question-and-answer set
	+[x] question - A question in a QandASet
	+[x] quote - An inline quotation
	+[ ] refclass - The scope or other indication of applicability of a
	+ reference entry
	+[ ] refdescriptor - A description of the topic of a reference page
	+[ ] refentry - A reference page (originally a UNIX man-style reference page)
	+[ ] refentryinfo - Meta-information for a Refentry
	+[ ] refentrytitle - The title of a reference page
	+[ ] reference - A collection of reference entries
	+[ ] referenceinfo - Meta-information for a Reference
	+[ ] refmeta - Meta-information for a reference entry
	+[ ] refmiscinfo - Meta-information for a reference entry other than the title
	+ and volume number
	+[ ] refname - The name of (one of) the subject(s) of a reference page
	+[ ] refnamediv - The name, purpose, and classification of a reference page
	+[ ] refpurpose - A short (one sentence) synopsis of the topic of a reference
	+ page
	+[x] refsect1 - A major subsection of a reference entry
	+[x] refsect1info - Meta-information for a RefSect1
	+[x] refsect2 - A subsection of a RefSect1
	+[x] refsect2info - Meta-information for a RefSect2
	+[x] refsect3 - A subsection of a RefSect2
	+[x] refsect3info - Meta-information for a RefSect3
	+[x] refsection - A recursive section in a refentry
	+[x] refsectioninfo - Meta-information for a refsection
	+[ ] refsynopsisdiv - A syntactic synopsis of the subject of the reference page
	+[ ] refsynopsisdivinfo - Meta-information for a RefSynopsisDiv
	+[x] releaseinfo - Information about a particular release of a document
	+[ ] remark - A remark (or comment) intended for presentation in a draft
	+ manuscript
	+[ ] replaceable - Content that may or must be replaced by the user
	+[ ] returnvalue - The value returned by a function
	+[ ] revdescription - A extended description of a revision to a document
	+[ ] revhistory - A history of the revisions to a document
	+[ ] revision - An entry describing a single revision in the history of the
	+ revisions to a document
	+[ ] revnumber - A document revision number
	+[ ] revremark - A description of a revision to a document
	+[ ] rhs - The right-hand side of an EBNF production
	+[x] row - A row in a table
	+[ ] sbr - An explicit line break in a command synopsis
	+[x] screen - Text that a user sees or might see on a computer screen
	+[o] screenco - A screen with associated areas used in callouts
	+[o] screeninfo - Information about how a screen shot was produced
	+[ ] screenshot - A representation of what the user sees or might see on a
	+ computer screen
	+[ ] secondary - A secondary word or phrase in an index term
	+[ ] secondaryie - A secondary term in an index entry, rather than in the text
	+[x] sect1 - A top-level section of document
	+[x] sect1info - Meta-information for a Sect1
	+[x] sect2 - A subsection within a Sect1
	+[x] sect2info - Meta-information for a Sect2
	+[x] sect3 - A subsection within a Sect2
	+[x] sect3info - Meta-information for a Sect3
	+[x] sect4 - A subsection within a Sect3
	+[x] sect4info - Meta-information for a Sect4
	+[x] sect5 - A subsection within a Sect4
	+[x] sect5info - Meta-information for a Sect5
	+[x] section - A recursive section
	+[x] sectioninfo - Meta-information for a recursive section
	+[x] see - Part of an index term directing the reader instead to another entry
	+ in the index
	+[x] seealso - Part of an index term directing the reader also to another entry
	+ in the index
	+[ ] seealsoie - A See also entry in an index, rather than in the text
	+[ ] seeie - A See entry in an index, rather than in the text
	+[x] seg - An element of a list item in a segmented list
	+[x] seglistitem - A list item in a segmented list
	+[x] segmentedlist - A segmented list, a list of sets of elements
	+[x] segtitle - The title of an element of a list item in a segmented list
	+[ ] seriesvolnums - Numbers of the volumes in a series of books
	+[ ] set - A collection of books
	+[ ] setindex - An index to a set of books
	+[ ] setindexinfo - Meta-information for a SetIndex
	+[ ] setinfo - Meta-information for a Set
	+[ ] sgmltag - A component of SGML markup
	+[ ] shortaffil - A brief description of an affiliation
	+[ ] shortcut - A key combination for an action that is also accessible through
	+ a menu
	+[ ] sidebar - A portion of a document that is isolated from the main
	+ narrative flow
	+[ ] sidebarinfo - Meta-information for a Sidebar
	+[x] simpara - A paragraph that contains only text and inline markup, no block
	+ elements
	+[x] simplelist - An undecorated list of single words or short phrases
	+[ ] simplemsgentry - A wrapper for a simpler entry in a message set
	+[ ] simplesect - A section of a document with no subdivisions
	+[ ] spanspec - Formatting information for a spanned column in a table
	+[ ] state - A state or province in an address
	+[ ] step - A unit of action in a procedure
	+[ ] stepalternatives - Alternative steps in a procedure
	+[ ] street - A street address in an address
	+[ ] structfield - A field in a structure (in the programming language sense)
	+[ ] structname - The name of a structure (in the programming language sense)
	+[ ] subject - One of a group of terms describing the subject matter of a
	+ document
	+[ ] subjectset - A set of terms describing the subject matter of a document
	+[ ] subjectterm - A term in a group of terms describing the subject matter of
	+ a document
	+[x] subscript - A subscript (as in H2O, the molecular formula for water)
	+[ ] substeps - A wrapper for steps that occur within steps in a procedure
	+[x] subtitle - The subtitle of a document
	+[x] superscript - A superscript (as in x2, the mathematical notation for x
	+ multiplied by itself)
	+[ ] surname - A family name; in western cultures the last name
	+[ ] svg:svg - An SVG graphic
	+[x] symbol - A name that is replaced by a value before processing
	+[ ] synopfragment - A portion of a CmdSynopsis broken out from the main body
	+ of the synopsis
	+[ ] synopfragmentref - A reference to a fragment of a command synopsis
	+[ ] synopsis - A general-purpose element for representing the syntax of
	+ commands or functions
	+[ ] systemitem - A system-related item or term
	+[ ] table - A formal table in a document
	+[ ] task - A task to be completed
	+[ ] taskprerequisites - The prerequisites for a task
	+[ ] taskrelated - Information related to a task
	+[ ] tasksummary - A summary of a task
	+[x] tbody - A wrapper for the rows of a table or informal table
	+[x] td - A table entry in an HTML table
	+[x] term - The word or phrase being defined or described in a variable list
	+[ ] termdef - An inline term definition
	+[ ] tertiary - A tertiary word or phrase in an index term
	+[ ] tertiaryie - A tertiary term in an index entry, rather than in the text
	+[ ] textdata - Pointer to external text data
	+[ ] textobject - A wrapper for a text description of an object and its
	+ associated meta-information
	+[ ] tfoot - A table footer consisting of one or more rows
	+[x] tgroup - A wrapper for the main content of a table, or part of a table
	+[x] th - A table header entry in an HTML table
	+[x] thead - A table header consisting of one or more rows
	+[x] tip - A suggestion to the user, set off from the text
	+[x] title - The text of the title of a section of a document or of a formal
	+ block-level element
	+[x] titleabbrev - The abbreviation of a Title
	+[x] toc - A table of contents
	+[x] tocback - An entry in a table of contents for a back matter component
	+[x] tocchap - An entry in a table of contents for a component in the body of
	+ a document
	+[x] tocentry - A component title in a table of contents
	+[x] tocfront - An entry in a table of contents for a front matter component
	+[x] toclevel1 - A top-level entry within a table of contents entry for a
	+ chapter-like component
	+[x] toclevel2 - A second-level entry within a table of contents entry for a
	+ chapter-like component
	+[x] toclevel3 - A third-level entry within a table of contents entry for a
	+ chapter-like component
	+[x] toclevel4 - A fourth-level entry within a table of contents entry for a
	+ chapter-like component
	+[x] toclevel5 - A fifth-level entry within a table of contents entry for a
	+ chapter-like component
	+[x] tocpart - An entry in a table of contents for a part of a book
	+[ ] token - A unit of information
	+[x] tr - A row in an HTML table
	+[ ] trademark - A trademark
	+[x] type - The classification of a value
	+[x] ulink - A link that addresses its target by means of a URL
	+ (Uniform Resource Locator)
	+[x] uri - A Uniform Resource Identifier
	+[x] userinput - Data entered by the user
	+[x] varargs - An empty element in a function synopsis indicating a variable
	+ number of arguments
	+[x] variablelist - A list in which each entry is composed of a set of one or
	+ more terms and an associated description
	+[x] varlistentry - A wrapper for a set of terms and the associated description
	+ in a variable list
	+[x] varname - The name of a variable
	+[ ] videodata - Pointer to external video data
	+[ ] videoobject - A wrapper for video data and its associated meta-information
	+[ ] void - An empty element in a function synopsis indicating that the
	+ function in question takes no arguments
	+[ ] volumenum - The volume number of a document in a set (as of books in a set
	+ or articles in a journal)
	+[x] warning - An admonition set off from the text
	+[x] wordasword - A word meant specifically as a word and not representing
	+ anything else
	+[x] xref - A cross reference to another part of the document
	+[ ] year - The year of publication of a document
	+[x] ?asciidoc-br? - line break from asciidoc docbook output
	+-}
	+
	+type DB m = StateT DBState m
	+
	+data DBState = DBState{ dbSectionLevel :: Int
	+ , dbQuoteType :: QuoteType
	+ , dbMeta :: Meta
	+ , dbBook :: Bool
	+ , dbFigureTitle :: Inlines
	+ , dbContent :: [Content]
	+ } deriving Show
	+
	+instance Default DBState where
	+ def = DBState{ dbSectionLevel = 0
	+ , dbQuoteType = DoubleQuote
	+ , dbMeta = mempty
	+ , dbBook = False
	+ , dbFigureTitle = mempty
	+ , dbContent = [] }
	+
	+
	+readDocBook :: PandocMonad m => ReaderOptions -> Text -> m Pandoc
	+readDocBook _ inp = do
	+ let tree = normalizeTree . parseXML . handleInstructions
	+ $ T.unpack $ crFilter inp
	+ (bs, st') <- flip runStateT (def{ dbContent = tree }) $ mapM parseBlock tree
	+ return $ Pandoc (dbMeta st') (toList . mconcat $ bs)
	+
	+-- We treat <?asciidoc-br?> specially (issue #1236), converting it
	+-- to <br/>, since xml-light doesn't parse the instruction correctly.
	+-- Other xml instructions are simply removed from the input stream.
	+handleInstructions :: String -> String
	+handleInstructions ('<':'?':'a':'s':'c':'i':'i':'d':'o':'c':'-':'b':'r':'?':'>':xs) = '<':'b':'r':'/':'>': handleInstructions xs
	+handleInstructions xs = case break (=='<') xs of
	+ (ys, []) -> ys
	+ ([], '<':zs) -> '<' : handleInstructions zs
	+ (ys, zs) -> ys ++ handleInstructions zs
	+
	+getFigure :: PandocMonad m => Element -> DB m Blocks
	+getFigure e = do
	+ tit <- case filterChild (named "title") e of
	+ Just t -> getInlines t
	+ Nothing -> return mempty
	+ modify $ \st -> st{ dbFigureTitle = tit }
	+ res <- getBlocks e
	+ modify $ \st -> st{ dbFigureTitle = mempty }
	+ return res
	+
	+-- normalize input, consolidating adjacent Text and CRef elements
	+normalizeTree :: [Content] -> [Content]
	+normalizeTree = everywhere (mkT go)
	+ where go :: [Content] -> [Content]
	+ go (Text (CData CDataRaw _ _):xs) = xs
	+ go (Text (CData CDataText s1 z):Text (CData CDataText s2 _):xs) =
	+ Text (CData CDataText (s1 ++ s2) z):xs
	+ go (Text (CData CDataText s1 z):CRef r:xs) =
	+ Text (CData CDataText (s1 ++ convertEntity r) z):xs
	+ go (CRef r:Text (CData CDataText s1 z):xs) =
	+ Text (CData CDataText (convertEntity r ++ s1) z):xs
	+ go (CRef r1:CRef r2:xs) =
	+ Text (CData CDataText (convertEntity r1 ++ convertEntity r2) Nothing):xs
	+ go xs = xs
	+
	+convertEntity :: String -> String
	+convertEntity e = Data.Maybe.fromMaybe (map toUpper e) (lookupEntity e)
	+
	+-- convenience function to get an attribute value, defaulting to ""
	+attrValue :: String -> Element -> String
	+attrValue attr elt =
	+ fromMaybe "" (lookupAttrBy (\x -> qName x == attr) (elAttribs elt))
	+
	+-- convenience function
	+named :: String -> Element -> Bool
	+named s e = qName (elName e) == s
	+
	+--
	+
	+addMetadataFromElement :: PandocMonad m => Element -> DB m Blocks
	+addMetadataFromElement e = do
	+ case filterChild (named "title") e of
	+ Nothing -> return ()
	+ Just z -> do
	+ getInlines z >>= addMeta "title"
	+ addMetaField "subtitle" z
	+ case filterChild (named "authorgroup") e of
	+ Nothing -> return ()
	+ Just z -> addMetaField "author" z
	+ addMetaField "subtitle" e
	+ addMetaField "author" e
	+ addMetaField "date" e
	+ addMetaField "release" e
	+ return mempty
	+ where addMetaField fieldname elt =
	+ case filterChildren (named fieldname) elt of
	+ [] -> return ()
	+ [z] -> getInlines z >>= addMeta fieldname
	+ zs -> mapM getInlines zs >>= addMeta fieldname
	+
	+addMeta :: PandocMonad m => ToMetaValue a => String -> a -> DB m ()
	+addMeta field val = modify (setMeta field val)
	+
	+instance HasMeta DBState where
	+ setMeta field v s = s {dbMeta = setMeta field v (dbMeta s)}
	+ deleteMeta field s = s {dbMeta = deleteMeta field (dbMeta s)}
	+
	+isBlockElement :: Content -> Bool
	+isBlockElement (Elem e) = qName (elName e) `elem` blocktags
	+ where blocktags = ["toc","index","para","formalpara","simpara",
	+ "ackno","epigraph","blockquote","bibliography","bibliodiv",
	+ "biblioentry","glossee","glosseealso","glossary",
	+ "glossdiv","glosslist","chapter","appendix","preface",
	+ "bridgehead","sect1","sect2","sect3","sect4","sect5","section",
	+ "refsect1","refsect2","refsect3","refsection",
	+ "important","caution","note","tip","warning","qandadiv",
	+ "question","answer","abstract","itemizedlist","orderedlist",
	+ "variablelist","article","book","table","informaltable",
	+ "informalexample", "linegroup",
	+ "screen","programlisting","example","calloutlist"]
	+isBlockElement _ = False
	+
	+-- Trim leading and trailing newline characters
	+trimNl :: String -> String
	+trimNl = reverse . go . reverse . go
	+ where go ('\n':xs) = xs
	+ go xs = xs
	+
	+-- meld text into beginning of first paragraph of Blocks.
	+-- assumes Blocks start with a Para; if not, does nothing.
	+addToStart :: Inlines -> Blocks -> Blocks
	+addToStart toadd bs =
	+ case toList bs of
	+ (Para xs : rest) -> para (toadd <> fromList xs) <> fromList rest
	+ _ -> bs
	+
	+-- function that is used by both mediaobject (in parseBlock)
	+-- and inlinemediaobject (in parseInline)
	+-- A DocBook mediaobject is a wrapper around a set of alternative presentations
	+getMediaobject :: PandocMonad m => Element -> DB m Inlines
	+getMediaobject e = do
	+ (imageUrl, attr) <-
	+ case filterChild (named "imageobject") e of
	+ Nothing -> return (mempty, nullAttr)
	+ Just z -> case filterChild (named "imagedata") z of
	+ Nothing -> return (mempty, nullAttr)
	+ Just i -> let atVal a = attrValue a i
	+ w = case atVal "width" of
	+ "" -> []
	+ d -> [("width", d)]
	+ h = case atVal "depth" of
	+ "" -> []
	+ d -> [("height", d)]
	+ atr = (atVal "id", words $ atVal "role", w ++ h)
	+ in return (atVal "fileref", atr)
	+ let getCaption el = case filterChild (\x -> named "caption" x
	+ \|\| named "textobject" x
	+ \|\| named "alt" x) el of
	+ Nothing -> return mempty
	+ Just z -> mconcat <$>
	+ mapM parseInline (elContent z)
	+ figTitle <- gets dbFigureTitle
	+ let (caption, title) = if isNull figTitle
	+ then (getCaption e, "")
	+ else (return figTitle, "fig:")
	+ fmap (imageWith attr imageUrl title) caption
	+
	+getBlocks :: PandocMonad m => Element -> DB m Blocks
	+getBlocks e = mconcat <$>
	+ mapM parseBlock (elContent e)
	+
	+
	+parseBlock :: PandocMonad m => Content -> DB m Blocks
	+parseBlock (Text (CData CDataRaw _ _)) = return mempty -- DOCTYPE
	+parseBlock (Text (CData _ s _)) = if all isSpace s
	+ then return mempty
	+ else return $ plain $ trimInlines $ text s
	+parseBlock (CRef x) = return $ plain $ str $ map toUpper x
	+parseBlock (Elem e) =
	+ case qName (elName e) of
	+ "remark"-> return mempty
	+ "toc" -> return mempty -- skip TOC, since in pandoc it's autogenerated
	+ "index" -> return mempty -- skip index, since page numbers meaningless
	+ "para" -> parseMixed para (elContent e)
	+ "formalpara" -> do
	+ tit <- case filterChild (named "title") e of
	+ Just t -> (para . strong . (<> str ".")) <$>
	+ getInlines t
	+ Nothing -> return mempty
	+ (tit <>) <$> parseMixed para (elContent e)
	+ "simpara" -> parseMixed para (elContent e)
	+ "ackno" -> parseMixed para (elContent e)
	+ "epigraph" -> parseBlockquote
	+ "blockquote" -> parseBlockquote
	+ "attribution" -> return mempty
	+ "titleabbrev" -> return mempty
	+ "authorinitials" -> return mempty
	+ "bibliography" -> sect 0
	+ "bibliodiv" -> sect 1
	+ "biblioentry" -> parseMixed para (elContent e)
	+ "bibliomixed" -> parseMixed para (elContent e)
	+ "equation" -> para <$> equation e displayMath
	+ "informalequation" -> para <$> equation e displayMath
	+ "glosssee" -> para . (\ils -> text "See " <> ils <> str ".")
	+ <$> getInlines e
	+ "glossseealso" -> para . (\ils -> text "See also " <> ils <> str ".")
	+ <$> getInlines e
	+ "glossary" -> sect 0
	+ "glossdiv" -> definitionList <$>
	+ mapM parseGlossEntry (filterChildren (named "glossentry") e)
	+ "glosslist" -> definitionList <$>
	+ mapM parseGlossEntry (filterChildren (named "glossentry") e)
	+ "chapter" -> sect 0
	+ "appendix" -> sect 0
	+ "preface" -> sect 0
	+ "bridgehead" -> para . strong <$> getInlines e
	+ "sect1" -> sect 1
	+ "sect2" -> sect 2
	+ "sect3" -> sect 3
	+ "sect4" -> sect 4
	+ "sect5" -> sect 5
	+ "section" -> gets dbSectionLevel >>= sect . (+1)
	+ "refsect1" -> sect 1
	+ "refsect2" -> sect 2
	+ "refsect3" -> sect 3
	+ "refsection" -> gets dbSectionLevel >>= sect . (+1)
	+ "important" -> divWith ("", ["important"], []) <$>
	+ getBlocks e
	+ "caution" -> blockQuote . (para (strong $ str "Caution") <>)
	+ <$> getBlocks e
	+ "note" -> divWith ("", ["note"], []) <$>
	+ getBlocks e
	+ "tip" -> blockQuote . (para (strong $ str "Tip") <>)
	+ <$> getBlocks e
	+ "warning" -> divWith ("", ["warning"], []) <$>
	+ getBlocks e
	+ "area" -> return mempty
	+ "areaset" -> return mempty
	+ "areaspec" -> return mempty
	+ "qandadiv" -> gets dbSectionLevel >>= sect . (+1)
	+ "question" -> addToStart (strong (str "Q:") <> str " ") <$> getBlocks e
	+ "answer" -> addToStart (strong (str "A:") <> str " ") <$> getBlocks e
	+ "abstract" -> blockQuote <$> getBlocks e
	+ "calloutlist" -> bulletList <$> callouts
	+ "itemizedlist" -> bulletList <$> listitems
	+ "orderedlist" -> do
	+ let listStyle = case attrValue "numeration" e of
	+ "arabic" -> Decimal
	+ "loweralpha" -> LowerAlpha
	+ "upperalpha" -> UpperAlpha
	+ "lowerroman" -> LowerRoman
	+ "upperroman" -> UpperRoman
	+ _ -> Decimal
	+ let start = fromMaybe 1 $
	+ (attrValue "override" <$> filterElement (named "listitem") e)
	+ >>= safeRead
	+ orderedListWith (start,listStyle,DefaultDelim)
	+ <$> listitems
	+ "variablelist" -> definitionList <$> deflistitems
	+ "figure" -> getFigure e
	+ "mediaobject" -> para <$> getMediaobject e
	+ "caption" -> return mempty
	+ "info" -> addMetadataFromElement e
	+ "articleinfo" -> addMetadataFromElement e
	+ "sectioninfo" -> return mempty -- keywords & other metadata
	+ "refsectioninfo" -> return mempty -- keywords & other metadata
	+ "refsect1info" -> return mempty -- keywords & other metadata
	+ "refsect2info" -> return mempty -- keywords & other metadata
	+ "refsect3info" -> return mempty -- keywords & other metadata
	+ "sect1info" -> return mempty -- keywords & other metadata
	+ "sect2info" -> return mempty -- keywords & other metadata
	+ "sect3info" -> return mempty -- keywords & other metadata
	+ "sect4info" -> return mempty -- keywords & other metadata
	+ "sect5info" -> return mempty -- keywords & other metadata
	+ "chapterinfo" -> return mempty -- keywords & other metadata
	+ "glossaryinfo" -> return mempty -- keywords & other metadata
	+ "appendixinfo" -> return mempty -- keywords & other metadata
	+ "bookinfo" -> addMetadataFromElement e
	+ "article" -> modify (\st -> st{ dbBook = False }) >>
	+ addMetadataFromElement e >> getBlocks e
	+ "book" -> modify (\st -> st{ dbBook = True }) >>
	+ addMetadataFromElement e >> getBlocks e
	+ "table" -> parseTable
	+ "informaltable" -> parseTable
	+ "informalexample" -> divWith ("", ["informalexample"], []) <$>
	+ getBlocks e
	+ "linegroup" -> lineBlock <$> lineItems
	+ "literallayout" -> codeBlockWithLang
	+ "screen" -> codeBlockWithLang
	+ "programlisting" -> codeBlockWithLang
	+ "synopsis" -> synopsis
	+ "?xml" -> return mempty
	+ "title" -> return mempty -- handled in parent element
	+ "subtitle" -> return mempty -- handled in parent element
	+ _ -> getBlocks e
	+ where parseMixed container conts = do
	+ let (ils,rest) = break isBlockElement conts
	+ ils' <- (trimInlines . mconcat) <$> mapM parseInline ils
	+ let p = if ils' == mempty then mempty else container ils'
	+ case rest of
	+ [] -> return p
	+ (r:rs) -> do
	+ b <- parseBlock r
	+ x <- parseMixed container rs
	+ return $ p <> b <> x
	+ codeBlockWithLang = do
	+ let classes' = case attrValue "language" e of
	+ "" -> []
	+ x -> [x]
	+ return $ codeBlockWith (attrValue "id" e, classes', [])
	+ $ trimNl $ strContentRecursive e
	+
	+ synopsis = do
	+ return $ codeBlockWith (attrValue "id" e, ["synopsis"], [])
	+ $ trimNl $ strContentRecursive e
	+
	+ parseBlockquote = do
	+ attrib <- case filterChild (named "attribution") e of
	+ Nothing -> return mempty
	+ Just z -> (para . (str "— " <>) . mconcat)
	+ <$>
	+ mapM parseInline (elContent z)
	+ contents <- getBlocks e
	+ return $ blockQuote (contents <> attrib)
	+ listitems = mapM getBlocks $ filterChildren (named "listitem") e
	+ callouts = mapM getBlocks $ filterChildren (named "callout") e
	+ deflistitems = mapM parseVarListEntry $ filterChildren
	+ (named "varlistentry") e
	+ parseVarListEntry e' = do
	+ let terms = filterChildren (named "term") e'
	+ let items = filterChildren (named "listitem") e'
	+ terms' <- mapM getInlines terms
	+ items' <- mapM getBlocks items
	+ return (mconcat $ intersperse (str "; ") terms', items')
	+ parseGlossEntry e' = do
	+ let terms = filterChildren (named "glossterm") e'
	+ let items = filterChildren (named "glossdef") e'
	+ terms' <- mapM getInlines terms
	+ items' <- mapM getBlocks items
	+ return (mconcat $ intersperse (str "; ") terms', items')
	+ parseTable = do
	+ let isCaption x = named "title" x \|\| named "caption" x
	+ caption <- case filterChild isCaption e of
	+ Just t -> getInlines t
	+ Nothing -> return mempty
	+ let e' = fromMaybe e $ filterChild (named "tgroup") e
	+ let isColspec x = named "colspec" x \|\| named "col" x
	+ let colspecs = case filterChild (named "colgroup") e' of
	+ Just c -> filterChildren isColspec c
	+ _ -> filterChildren isColspec e'
	+ let isRow x = named "row" x \|\| named "tr" x
	+ headrows <- case filterChild (named "thead") e' of
	+ Just h -> case filterChild isRow h of
	+ Just x -> parseRow x
	+ Nothing -> return []
	+ Nothing -> return []
	+ bodyrows <- case filterChild (named "tbody") e' of
	+ Just b -> mapM parseRow
	+ $ filterChildren isRow b
	+ Nothing -> mapM parseRow
	+ $ filterChildren isRow e'
	+ let toAlignment c = case findAttr (unqual "align") c of
	+ Just "left" -> AlignLeft
	+ Just "right" -> AlignRight
	+ Just "center" -> AlignCenter
	+ _ -> AlignDefault
	+ let toWidth c = case findAttr (unqual "colwidth") c of
	+ Just w -> fromMaybe 0
	+ $ safeRead $ '0': filter (\x ->
	+ (x >= '0' && x <= '9')
	+ \|\| x == '.') w
	+ Nothing -> 0 :: Double
	+ let numrows = case bodyrows of
	+ [] -> 0
	+ xs -> maximum $ map length xs
	+ let aligns = case colspecs of
	+ [] -> replicate numrows AlignDefault
	+ cs -> map toAlignment cs
	+ let widths = case colspecs of
	+ [] -> replicate numrows 0
	+ cs -> let ws = map toWidth cs
	+ tot = sum ws
	+ in if all (> 0) ws
	+ then map (/ tot) ws
	+ else replicate numrows 0
	+ let headrows' = if null headrows
	+ then replicate numrows mempty
	+ else headrows
	+ return $ table caption (zip aligns widths)
	+ headrows' bodyrows
	+ isEntry x = named "entry" x \|\| named "td" x \|\| named "th" x
	+ parseRow = mapM (parseMixed plain . elContent) . filterChildren isEntry
	+ sect n = do isbook <- gets dbBook
	+ let n' = if isbook \|\| n == 0 then n + 1 else n
	+ headerText <- case filterChild (named "title") e `mplus`
	+ (filterChild (named "info") e >>=
	+ filterChild (named "title")) of
	+ Just t -> getInlines t
	+ Nothing -> return mempty
	+ modify $ \st -> st{ dbSectionLevel = n }
	+ b <- getBlocks e
	+ let ident = attrValue "id" e
	+ modify $ \st -> st{ dbSectionLevel = n - 1 }
	+ return $ headerWith (ident,[],[]) n' headerText <> b
	+ lineItems = mapM getInlines $ filterChildren (named "line") e
	+
	+getInlines :: PandocMonad m => Element -> DB m Inlines
	+getInlines e' = (trimInlines . mconcat) <$>
	+ mapM parseInline (elContent e')
	+
	+strContentRecursive :: Element -> String
	+strContentRecursive = strContent .
	+ (\e' -> e'{ elContent = map elementToStr $ elContent e' })
	+
	+elementToStr :: Content -> Content
	+elementToStr (Elem e') = Text $ CData CDataText (strContentRecursive e') Nothing
	+elementToStr x = x
	+
	+parseInline :: PandocMonad m => Content -> DB m Inlines
	+parseInline (Text (CData _ s _)) = return $ text s
	+parseInline (CRef ref) =
	+ return $ maybe (text $ map toUpper ref) text $ lookupEntity ref
	+parseInline (Elem e) =
	+ case qName (elName e) of
	+ "equation" -> equation e displayMath
	+ "informalequation" -> equation e displayMath
	+ "inlineequation" -> equation e math
	+ "subscript" -> subscript <$> innerInlines
	+ "superscript" -> superscript <$> innerInlines
	+ "inlinemediaobject" -> getMediaobject e
	+ "quote" -> do
	+ qt <- gets dbQuoteType
	+ let qt' = if qt == SingleQuote then DoubleQuote else SingleQuote
	+ modify $ \st -> st{ dbQuoteType = qt' }
	+ contents <- innerInlines
	+ modify $ \st -> st{ dbQuoteType = qt }
	+ return $ if qt == SingleQuote
	+ then singleQuoted contents
	+ else doubleQuoted contents
	+ "simplelist" -> simpleList
	+ "segmentedlist" -> segmentedList
	+ "classname" -> codeWithLang
	+ "code" -> codeWithLang
	+ "filename" -> codeWithLang
	+ "literal" -> codeWithLang
	+ "computeroutput" -> codeWithLang
	+ "prompt" -> codeWithLang
	+ "parameter" -> codeWithLang
	+ "option" -> codeWithLang
	+ "optional" -> do x <- getInlines e
	+ return $ str "[" <> x <> str "]"
	+ "markup" -> codeWithLang
	+ "wordasword" -> emph <$> innerInlines
	+ "command" -> codeWithLang
	+ "varname" -> codeWithLang
	+ "function" -> codeWithLang
	+ "type" -> codeWithLang
	+ "symbol" -> codeWithLang
	+ "constant" -> codeWithLang
	+ "userinput" -> codeWithLang
	+ "varargs" -> return $ code "(...)"
	+ "keycap" -> return (str $ strContent e)
	+ "keycombo" -> keycombo <$>
	+ mapM parseInline (elContent e)
	+ "menuchoice" -> menuchoice <$>
	+ mapM parseInline (
	+ filter isGuiMenu $ elContent e)
	+ "xref" -> do
	+ content <- dbContent <$> get
	+ let linkend = attrValue "linkend" e
	+ let title = case attrValue "endterm" e of
	+ "" -> maybe "???" xrefTitleByElem
	+ (findElementById linkend content)
	+ endterm -> maybe "???" strContent
	+ (findElementById endterm content)
	+ return $ link ('#' : linkend) "" (text title)
	+ "email" -> return $ link ("mailto:" ++ strContent e) ""
	+ $ str $ strContent e
	+ "uri" -> return $ link (strContent e) "" $ str $ strContent e
	+ "ulink" -> link (attrValue "url" e) "" <$> innerInlines
	+ "link" -> do
	+ ils <- innerInlines
	+ let href = case findAttr (QName "href" (Just "http://www.w3.org/1999/xlink") Nothing) e of
	+ Just h -> h
	+ _ -> '#' : attrValue "linkend" e
	+ let ils' = if ils == mempty then str href else ils
	+ let attr = (attrValue "id" e, words $ attrValue "role" e, [])
	+ return $ linkWith attr href "" ils'
	+ "foreignphrase" -> emph <$> innerInlines
	+ "emphasis" -> case attrValue "role" e of
	+ "bold" -> strong <$> innerInlines
	+ "strong" -> strong <$> innerInlines
	+ "strikethrough" -> strikeout <$> innerInlines
	+ _ -> emph <$> innerInlines
	+ "footnote" -> (note . mconcat) <$>
	+ mapM parseBlock (elContent e)
	+ "title" -> return mempty
	+ "affiliation" -> return mempty
	+ -- Note: this isn't a real docbook tag; it's what we convert
	+ -- <?asciidor-br?> to in handleInstructions, above. A kludge to
	+ -- work around xml-light's inability to parse an instruction.
	+ "br" -> return linebreak
	+ _ -> innerInlines
	+ where innerInlines = (trimInlines . mconcat) <$>
	+ mapM parseInline (elContent e)
	+ codeWithLang = do
	+ let classes' = case attrValue "language" e of
	+ "" -> []
	+ l -> [l]
	+ return $ codeWith (attrValue "id" e,classes',[]) $ strContentRecursive e
	+ simpleList = (mconcat . intersperse (str "," <> space)) <$> mapM getInlines
	+ (filterChildren (named "member") e)
	+ segmentedList = do
	+ tit <- maybe (return mempty) getInlines $ filterChild (named "title") e
	+ segtits <- mapM getInlines $ filterChildren (named "segtitle") e
	+ segitems <- mapM (mapM getInlines . filterChildren (named "seg"))
	+ $ filterChildren (named "seglistitem") e
	+ let toSeg = mconcat . zipWith (\x y -> strong (x <> str ":") <> space <>
	+ y <> linebreak) segtits
	+ let segs = mconcat $ map toSeg segitems
	+ let tit' = if tit == mempty
	+ then mempty
	+ else strong tit <> linebreak
	+ return $ linebreak <> tit' <> segs
	+ keycombo = spanWith ("",["keycombo"],[]) .
	+ mconcat . intersperse (str "+")
	+ menuchoice = spanWith ("",["menuchoice"],[]) .
	+ mconcat . intersperse (text " > ")
	+ isGuiMenu (Elem x) = named "guimenu" x \|\| named "guisubmenu" x \|\|
	+ named "guimenuitem" x
	+ isGuiMenu _ = False
	+
	+ findElementById idString content
	+ = asum [filterElement (\x -> attrValue "id" x == idString) el \| Elem el <- content]
	+
	+ -- Use the 'xreflabel' attribute for getting the title of a xref link;
	+ -- if there's no such attribute, employ some heuristics based on what
	+ -- docbook-xsl does.
	+ xrefTitleByElem el
	+ \| not (null xrefLabel) = xrefLabel
	+ \| otherwise = case qName (elName el) of
	+ "chapter" -> descendantContent "title" el
	+ "section" -> descendantContent "title" el
	+ "sect1" -> descendantContent "title" el
	+ "sect2" -> descendantContent "title" el
	+ "sect3" -> descendantContent "title" el
	+ "sect4" -> descendantContent "title" el
	+ "sect5" -> descendantContent "title" el
	+ "cmdsynopsis" -> descendantContent "command" el
	+ "funcsynopsis" -> descendantContent "function" el
	+ _ -> qName (elName el) ++ "_title"
	+ where
	+ xrefLabel = attrValue "xreflabel" el
	+ descendantContent name = maybe "???" strContent
	+ . filterElementName (\n -> qName n == name)
	+
	+-- \| Extract a math equation from an element
	+--
	+-- asciidoc can generate Latex math in CDATA sections.
	+--
	+-- Note that if some MathML can't be parsed it is silently ignored!
	+equation
	+ :: Monad m
	+ => Element
	+ -- ^ The element from which to extract a mathematical equation
	+ -> (String -> Inlines)
	+ -- ^ A constructor for some Inlines, taking the TeX code as input
	+ -> m Inlines
	+equation e constructor =
	+ return $ mconcat $ map constructor $ mathMLEquations ++ latexEquations
	+ where
	+ mathMLEquations :: [String]
	+ mathMLEquations = map writeTeX $ rights $ readMath
	+ (\x -> qName (elName x) == "math" && qPrefix (elName x) == Just "mml")
	+ (readMathML . showElement)
	+
	+ latexEquations :: [String]
	+ latexEquations = readMath (\x -> qName (elName x) == "mathphrase")
	+ (concat . fmap showVerbatimCData . elContent)
	+
	+ readMath :: (Element -> Bool) -> (Element -> b) -> [b]
	+ readMath childPredicate fromElement =
	+ ( map (fromElement . everywhere (mkT removePrefix))
	+ $ filterChildren childPredicate e
	+ )
	+
	+-- \| Get the actual text stored in a verbatim CData block. 'showContent'
	+-- returns the text still surrounded by the [[CDATA]] tags.
	+--
	+-- Returns 'showContent' if this is not a verbatim CData
	+showVerbatimCData :: Content -> String
	+showVerbatimCData (Text (CData CDataVerbatim d _)) = d
	+showVerbatimCData c = showContent c
	+
	+-- \| Set the prefix of a name to 'Nothing'
	+removePrefix :: QName -> QName
	+removePrefix elname = elname { qPrefix = Nothing }
	diff --git a/documentation-tools/doc-converter/remarkup.lua b/documentation-tools/doc-converter/remarkup.lua
	new file mode 100644
	index 0000000..c907592
	--- /dev/null
	+++ b/documentation-tools/doc-converter/remarkup.lua
	@@ -0,0 +1,323 @@
	+-- (WIP) Pandoc Remarkup Writer
	+--
	+-- Invoke with: pandoc -t remarkup.lua
	+--
	+-- Note: you need not have lua installed on your system to use this
	+-- custom writer. However, if you do have lua installed, you can
	+-- use it to test changes to the script. 'lua remarkup.lua' will
	+-- produce informative error messages if your code contains
	+-- syntax errors.
	+
	+local function hasArg (attrs, a)
	+ for _, i in pairs(attrs) do
	+ if i == a then
	+ return true
	+ end
	+ end
	+ return false
	+end
	+
	+local hex_to_char = function(x)
	+ return string.char(tonumber(x, 16))
	+end
	+
	+local url_unescape = function(url)
	+ return url:gsub("%%(%x%x)", hex_to_char)
	+end
	+
	+local function escape(s, in_attribute)
	+ return s
	+end
	+
	+-- Helper function to convert an attributes table into
	+-- a string that can be put into HTML tags.
	+local function attributes(attr)
	+ local attr_table = {}
	+ for x,y in pairs(attr) do
	+ if y and y ~= "" then
	+ table.insert(attr_table, ' ' .. x .. '="' .. escape(y,true) .. '"')
	+ end
	+ end
	+ return table.concat(attr_table)
	+end
	+
	+-- Run cmd on a temporary file containing inp and return result.
	+local function pipe(cmd, inp)
	+ local tmp = os.tmpname()
	+ local tmph = io.open(tmp, "w")
	+ tmph:write(inp)
	+ tmph:close()
	+ local outh = io.popen(cmd .. " " .. tmp,"r")
	+ local result = outh:read("*all")
	+ outh:close()
	+ os.remove(tmp)
	+ return result
	+end
	+
	+-- Table to store footnotes, so they can be included at the end.
	+local notes = {}
	+
	+-- Blocksep is used to separate block elements.
	+function Blocksep()
	+ return "\n\n"
	+end
	+
	+-- This function is called once for the whole document. Parameters:
	+-- body is a string, metadata is a table, variables is a table.
	+-- This gives you a fragment. You could use the metadata table to
	+-- fill variables in a custom lua template. Or, pass `--template=...`
	+-- to pandoc, and pandoc will add do the template processing as
	+-- usual.
	+function Doc(body, metadata, variables)
	+ return body
	+ -- local buffer = {}
	+ -- local function add(s)
	+ -- table.insert(buffer, s)
	+ -- end
	+ -- add(body)
	+ -- if #notes > 0 then
	+ -- add('\n')
	+ -- for _,note in pairs(notes) do
	+ -- add(note)
	+ -- end
	+ -- end
	+ -- return table.concat(buffer,'\n')
	+end
	+
	+-- The functions that follow render corresponding pandoc elements.
	+-- s is always a string, attr is always a table of attributes, and
	+-- items is always an array of strings (the items in a list).
	+-- Comments indicate the types of other variables.
	+
	+function Str(s)
	+ return escape(s)
	+end
	+
	+function Space()
	+ return " "
	+end
	+
	+function LineBreak()
	+ return "\n"
	+end
	+
	+function SoftBreak()
	+ return " "
	+end
	+
	+function Emph(s)
	+ return "//" .. s .. "//"
	+end
	+
	+function Strong(s)
	+ return "" .. s .. ""
	+end
	+
	+function Subscript(s)
	+ return "_" .. s .. ""
	+end
	+
	+function Superscript(s)
	+ return "^" .. s .. ""
	+end
	+
	+function SmallCaps(s)
	+ return s
	+end
	+
	+function Strikeout(s)
	+ return '~~' .. s .. '~~'
	+end
	+
	+function Link(s, src, tit)
	+ if s == nil or s == '' then
	+ return "[[" .. url_unescape(src) .. "]]"
	+ else
	+ return "[[" .. url_unescape(src) .. "\|" .. s .. "]]"
	+ end
	+end
	+
	+function Image(s, src, tit)
	+ return "IMAGE: " .. Link(s, src, tit)
	+end
	+
	+function RawInline(lang, s, attr)
	+ return "`" .. s .. "`"
	+end
	+
	+function Code(s, attr)
	+ return "`" .. s .. "`"
	+end
	+
	+function InlineMath(s)
	+ return "`" .. s .. "`"
	+end
	+
	+function DisplayMath(s)
	+ return "`" .. s .. "`"
	+end
	+
	+function Note(s)
	+ local num = #notes + 1
	+ -- insert the back reference right before the final closing tag.
	+ s = string.gsub(s,
	+ '(.*)</', '%1 <a href="#fnref' .. num .. '">↩</a></')
	+ -- add a list item with the note to the note table.
	+ table.insert(notes, '<li id="fn' .. num .. '">' .. s .. '</li>')
	+ -- return the footnote reference, linked to the note.
	+ return '<a id="fnref' .. num .. '" href="#fn' .. num ..
	+ '"><sup>' .. num .. '</sup></a>'
	+end
	+
	+function Span(s, attr)
	+ return s
	+end
	+
	+function Cite(s, cs)
	+ return s
	+end
	+
	+function Plain(s)
	+ return s
	+end
	+
	+function Para(s)
	+ return s
	+end
	+
	+-- lev is an integer, the header level.
	+function Header(lev, s, attr)
	+ local marker = string.rep("=", lev)
	+ return "" .. marker .. " " .. s .. " " .. marker
	+end
	+
	+function BlockQuote(s)
	+ local new_s = string.gsub(s, "\n", "\n> ")
	+ return "> " .. new_s
	+end
	+
	+function HorizontalRule()
	+ return string.rep("-", 5)
	+end
	+
	+function RawBlock(lang, s, attr)
	+ return "```lang=" .. lang .. "\n" .. s .. "\n```"
	+end
	+
	+function CodeBlock(s, attr)
	+ if (hasArg(attr, "synopsis")) then
	+ return "(SYNOPSIS)\n" .. s .. "\n"
	+ end
	+
	+ return "```\n" .. s .. "\n```"
	+end
	+
	+function BulletList(items)
	+ local buffer = {}
	+ for _, item in pairs(items) do
	+ table.insert(buffer, "* " .. item)
	+ end
	+ return table.concat(buffer, "\n")
	+end
	+
	+function OrderedList(items)
	+ local buffer = {}
	+ for _, item in pairs(items) do
	+ table.insert(buffer, "# " .. item)
	+ end
	+ return table.concat(buffer, "\n")
	+end
	+
	+-- Revisit association list STackValue instance.
	+function DefinitionList(items)
	+ local buffer = {}
	+ for _,item in pairs(items) do
	+ for k, v in pairs(item) do
	+ table.insert(buffer,"<dt>" .. k .. "</dt>\n<dd>" ..
	+ table.concat(v,"</dd>\n<dd>") .. "</dd>")
	+ end
	+ end
	+ return "<dl>\n" .. table.concat(buffer, "\n") .. "\n</dl>"
	+end
	+
	+-- Convert pandoc alignment to something HTML can use.
	+-- align is AlignLeft, AlignRight, AlignCenter, or AlignDefault.
	+function html_align(align)
	+ if align == 'AlignLeft' then
	+ return 'left'
	+ elseif align == 'AlignRight' then
	+ return 'right'
	+ elseif align == 'AlignCenter' then
	+ return 'center'
	+ else
	+ return 'left'
	+ end
	+end
	+
	+-- Caption is a string, aligns is an array of strings,
	+-- widths is an array of floats, headers is an array of
	+-- strings, rows is an array of arrays of strings.
	+function Table(caption, aligns, widths, headers, rows)
	+ local buffer = {}
	+ local function add(s)
	+ table.insert(buffer, s)
	+ end
	+ add("<table>")
	+ if caption ~= "" then
	+ add("<caption>" .. caption .. "</caption>")
	+ end
	+ local header_row = {}
	+ local empty_header = true
	+ for i, h in pairs(headers) do
	+ table.insert(header_row,'<th>' .. h .. '</th>')
	+ empty_header = empty_header and h == ""
	+ end
	+ if empty_header then
	+ head = ""
	+ else
	+ add('<tr>')
	+ for _,h in pairs(header_row) do
	+ add(h)
	+ end
	+ add('</tr>')
	+ end
	+ for _, row in pairs(rows) do
	+ add('<tr>')
	+ for i,c in pairs(row) do
	+ add('<td>' .. c .. '</td>')
	+ end
	+ add('</tr>')
	+ end
	+ add('</table>')
	+ if caption ~= "" then
	+ add("//" .. caption .. "//")
	+ end
	+ return table.concat(buffer,'\n')
	+end
	+
	+function Div(s, attr)
	+ if(hasArg(attr, "note")) then
	+ return "NOTE:".. s .. "\n"
	+ end
	+
	+ if(hasArg(attr, "warning")) then
	+ return "WARNING:".. s .. "\n"
	+ end
	+
	+ if(hasArg(attr, "important")) then
	+ return "IMPORTANT:".. s .. "\n"
	+ end
	+
	+ return "<div" .. attributes(attr) .. ">\n" .. s .. "</div>"
	+end
	+
	+-- The following code will produce runtime warnings when you haven't defined
	+-- all of the functions you need for the custom writer, so it's useful
	+-- to include when you're working on a writer.
	+local meta = {}
	+meta.__index =
	+ function(_, key)
	+ io.stderr:write(string.format("WARNING: Undefined function '%s'\n",key))
	+ return function() return "" end
	+ end
	+setmetatable(_G, meta)
	diff --git a/documentation/Concepts/containers.xml b/documentation/Concepts/containers.xml
	index c6e8384..eea9377 100644
	--- a/documentation/Concepts/containers.xml
	+++ b/documentation/Concepts/containers.xml
	@@ -1,336 +1,339 @@
	<?xml version="1.0" encoding="UTF-8"?>
	<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:trans="http://docbook.org/ns/transclusion"
	xmlns:svg="http://www.w3.org/2000/svg"
	xmlns:m="http://www.w3.org/1998/Math/MathML"
	xmlns:html="http://www.w3.org/1999/xhtml"
	xmlns:db="http://docbook.org/ns/docbook">
	<?xxe-sn 2ahi4rjnvuo 2h?>

	<title><?xxe-sn 2ahi4rjnvuo 2i?>Containers</title>

	<section>
	<?xxe-sn 2alsjvonojk 1g?>

	<title><?xxe-sn 2alsjvonojk 1h?>Syntax</title>

	<para><?xxe-sn 2alsjvonojk 1z?>Container operations:</para>

	<itemizedlist>
	<?xxe-sn 2alsjvonojk 20?>

	<listitem>
	<?xxe-sn 2alsjvonojk 21?>

	<para><?xxe-sn 2alsjvonojk 22?><code><?xxe-sn 2alsjvonojk 23?>access(serial)</code>
	Denotes operation's type as a sequential access. <link
	xlink:href="#operation-access-serial"><?xxe-sn 2alsjvonojk 41?>More</link>...</para>
	</listitem>

	<listitem>
	<?xxe-sn 2alsjvonojk 24?>

	<para><?xxe-sn 2alsjvonojk 25?><code><?xxe-sn 2alsjvonojk 26?>access(rand)</code>
	Denotes operation's type as a random access. <link
	xlink:href="#operation-access-rand"><?xxe-sn 2alsjvonojk 42?>More</link>...</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 2alsjvonojk 1i?>Container implementations:</para>

	<itemizedlist>
	<?xxe-sn 2alsjvonojk 1j?>

	<listitem>
	<?xxe-sn 2alsjvonojk 1k?>

	<para><?xxe-sn 2alsjvonojk 1l?><code><?xxe-sn 2alsjvonojk 1y?>container(onthefly)</code>
	Lazy data structure that generates elements on the fly when needed.
	<link xlink:href="#implementation-container"><?xxe-sn 2alsjvonojk 27?>More</link>...</para>
	</listitem>

	<listitem>
	<?xxe-sn 2alsjvonojk 1n?>

	<para><?xxe-sn 2alsjvonojk 1o?><code><?xxe-sn 2alsjvonojk 28?>container(solid)</code>
	Array or data structure that occupies contiguous memory region <link
	xlink:href="#implementation-container-1"><?xxe-sn 2alsjvonojk 29?>More</link>...</para>
	</listitem>
	</itemizedlist>
	</section>

	<section>
	<?xxe-sn 2ahi4rjnvuo 2j?>

	<title><?xxe-sn 2ahi4rjnvuo 2k?>Introduction</title>

	<para><?xxe-sn 2ahi4rjnvuo 2m?><emphasis><?xxe-sn 2ahi4rjnvuo 4g?>Containers</emphasis>
	is a general term referring to the data structures that contain a group of
	elements of certain type.</para>

	<para><?xxe-sn 2ahi4rjnvuo 2n?>Considering that virtually every program
	use containers to store, retrieve, search or otherwise process aggregate
	data, obviously efficiency of containers implementation is a priority for
	Xreate design.</para>

	<para><?xxe-sn 2ahi4rjnvuo 2p?>There are many different data structures
	invented to serve as a containers, each of them having different
	characteristics and peculiarities with no obvious winner but rather each
	one suits the best in appropriate situations. Usually it is software
	developer's knowledge and responsibility to be able to select the most
	appropriate container's implementation for a particular use case. That
	said, Xreate goes further and gathers information on <emphasis><?xxe-sn 2ahi4rjnvuo 4h?>how
	containers are used</emphasis>, by analysing the program sources. On this
	ground it's possible to choose semi-automatically the most appropriate
	data structure for container implementation to efficiently fulfil
	particular needs in a particular situation.</para>

	<para><?xxe-sn 2ahi4rjnvuo 2q?>In order to do this, the following approach
	is used. The way a container is defined is associated with one or more
	possible implementations it supports. On the other side, operations over
	container demand certain "good" implementations to efficiently process
	container data. Viewing it as <emphasis><?xxe-sn 2ahi4rjnvuo 53?>supply
	and demand</emphasis> setting, with a list of several acceptable
	implementations from either side, the most appropriate tradeoff is chosen
	as implementation for a given container to fulfill both sides with regard
	to defaults, preferences, constraints and other ways to guide inference
	process.</para>

	<para><?xxe-sn 2ahi4rjnvuo 2r?>In short example below</para>

	<programlisting xml:id="Intr_1"><?xxe-sn 2ahi4rjnvuo 2s?>name = "tests/containers.cpp: Containers.Doc_Intr_1"
	//container definition:
	a= {1, 2, 3, 4, 5}:: [num]; container(solid).


	//container's operation
	x= a[0]:: num; access(rand). </programlisting>

	<para><?xxe-sn 2ahi4rjnvuo 2t?>container's <emphasis><?xxe-sn 2ahi4rjnvuo 4i?>offer</emphasis>
	<code><?xxe-sn 2apiasqubk0 c?>container(solid)</code> and operation's
	<emphasis><?xxe-sn 2ahi4rjnvuo 4j?>demand</emphasis> <code><?xxe-sn 2apiasqubk0 d?>access(rand)</code>
	are explicitly expressed by annotations for clarity purposes.</para>

	<para><?xxe-sn 2ahi4rjnvuo 2u?>Annotation <code><?xxe-sn 2alsjvonojk 2p?>container(solid)</code>
	depicts that container <code><?xxe-sn 2ahi4rjnvuo 4l?>a</code> supports
	implementation <code><?xxe-sn 2ahi4rjnvuo 4m?>solid</code>, that is plain
	contiguous memory region or array. On the other side, annotation
	<code><?xxe-sn 2ahi4rjnvuo 4n?>access(rand)</code> expresses nature of
	<emphasis><?xxe-sn 2ahi4rjnvuo 54?>retrieving by index</emphasis>
	operation (variable <code><?xxe-sn 2ahi4rjnvuo 4p?>x</code>) and it
	requires selected data structure to support <emphasis><?xxe-sn 2ahi4rjnvuo 55?>random
	access</emphasis> to be efficiently executed.</para>

	<para><?xxe-sn 2ahi4rjnvuo 2v?>Obviously, implementation <code><?xxe-sn 2ahi4rjnvuo 4r?>solid</code>
	allows efficient random access and so it's assumed as a container
	<code><?xxe-sn 2ahi4rjnvuo 4s?>a</code>'s implementation by inference
	process.</para>

	<para><?xxe-sn 2ahi4rjnvuo 4t?>Semi-automatic, guided container's
	implementation selection has some advantages, such as:</para>

	<itemizedlist>
	<?xxe-sn 2ahi4rjnvuo 4u?>

	<listitem>
	<?xxe-sn 2ahi4rjnvuo 4v?>

	<para><?xxe-sn 2ahi4rjnvuo 4w?><emphasis><?xxe-sn 2ahi4rjnvuo 4x?>Less
	manual work</emphasis>. Inferring adequate implementations with little
	to no additional input from developer saves time to concentrate on
	more important aspects. Other approach to achieve the same, namely to
	assign default one-size-fits-all implementation with an average
	performance, is simpler but can not compete with more careful
	strategy.</para>
	</listitem>

	<listitem>
	<?xxe-sn 2ahi4rjnvuo 4y?>

	<para><?xxe-sn 2ahi4rjnvuo 4z?><emphasis><?xxe-sn 2ahi4rjnvuo 50?>Rapid
	development and optimization antagonism</emphasis>. It is important to
	keep in mind, that rapid development and frequent code changes
	somewhat contradict optimization efforts. Each round of optimization
	is leveraged by relying on concrete and particular program properties,
	overt or hidden connections and other observations. Once program
	undergo further development most of the previously sound optimization
	techniques became obsolete, irrelevant or plainly wrong. Selecting(as
	often as needed) the most efficient data structures keeps reasonable
	efficiency level automatically and does not impede possibly fast
	development pace.</para>
	</listitem>

	<listitem>
	<?xxe-sn 2ahi4rjnvuo 56?>

	<para><?xxe-sn 2ahi4rjnvuo 57?><emphasis><?xxe-sn 2ahi4rjnvuo 58?>Regression
	resistance</emphasis>. Xreate encourages frequent changes, adjusting
	and recombination in software components, libraries and modules by
	automatically reevaluating and reassigning most appropriate data
	structures in the new conditions or signalling error if it's
	impossible. This somewhat alleviates problem of <emphasis><?xxe-sn 2apiasqubk0 g?>fragile
	software</emphasis> and gives more confidence for refactoring.</para>
	</listitem>
	</itemizedlist>
	</section>

	<section>
	<?xxe-sn 2ahi4rjnvuo 32?>

	<title><?xxe-sn 2ahi4rjnvuo 33?>Container Implementations</title>

	<para><?xxe-sn 2ahi4rjnvuo 35?>Xreate supports container implementations
	presented below:</para>

	<section>
	<?xxe-sn 2ahi4rjnvuo 5g?>

	<title><?xxe-sn 2ahi4rjnvuo 5h?>Implementation
	'container(onthefly)'</title>

	<para><?xxe-sn 2alsjvonojk 2f?>Source: range list operator
	<code><?xxe-sn 2alsjvonojk 2i?>[from .. to]</code>.</para>

	<para><?xxe-sn 2alsjvonojk 2g?>Supported operations: <code><?xxe-sn 2alsjvonojk 2h?>access(serial)</code>.</para>

	<para><?xxe-sn 2ahi4rjnvuo 5j?>This is elementary implementation that
	represents <emphasis><?xxe-sn 2ahi4rjnvuo 5k?>lazy</emphasis> data
	structure — sequence of elements is generated by recurrence equation
	applied to a current element to compute next element of the sequence. It
	does not keep actual data in the memory, but instead computes necessary
	elements when accessed. This kind of implementation is rather memory
	- efficient since occupied memory does not depend on count of
	- elements.</para>
	+ efficient since occupied memory does not depend on container's
	+ size.</para>

	<para><?xxe-sn 2ahi4rjnvuo 5l?>For example, range list <code><?xxe-sn 2alsjvonojk 2a?>[1..10]</code>
	supports <code><?xxe-sn 2alsjvonojk 2b?>onthefly</code> implementation
	by using internally recurrent function <code><?xxe-sn 2alsjvonojk 2c?>x[i+1] = x[i] + 1, 1<= x <= 10</code>,
	that generates successive element <code><?xxe-sn 2alsjvonojk 2d?>x[i+1]</code>
	given <code><?xxe-sn 2alsjvonojk 2e?>x[i]</code>.</para>

	<para><?xxe-sn 2ahi4rjnvuo 5p?>Recurrent elements generation is suited
	for sequential access and can't serve random access operations.</para>
	</section>

	<section>
	<?xxe-sn 2ahi4rjnvuo 5q?>

	<title><?xxe-sn 2ahi4rjnvuo 5r?>Implementation
	'container(solid)'</title>

	<para><?xxe-sn 2alsjvonojk 2l?>Source: list operator.</para>

	<para><?xxe-sn 2alsjvonojk 2m?>Supported operations: <code><?xxe-sn 2alsjvonojk 2n?>access(serial)</code>,
	<code><?xxe-sn 2alsjvonojk 2o?>access(rand)</code>.</para>

	<para><?xxe-sn 2ahi4rjnvuo 5t?>This is implementation from the opposite
	side of the memory/computation space. It stores all the container's data
	in memory occupying contiguous region, known as <emphasis><?xxe-sn 2alsjvonojk 2j?>array</emphasis>.
	As opposed to the implementation <code><?xxe-sn 2alsjvonojk 2k?>onthefly</code>,
	it's computationally efficient for there is no need for any additional
	computations apart from simple offset calculation to get an element
	requested by an index.</para>

	<para><?xxe-sn 2ahi4rjnvuo 5u?>Due to the fact that all elements are
	present in the memory, the implementation supports sequential access as
	well as random access operations.</para>
	</section>
	</section>

	<section>
	<?xxe-sn 2ahi4rjnvuo 3f?>

	<title><?xxe-sn 2ahi4rjnvuo 3g?>Container Operations</title>

	<para><?xxe-sn 2ahi4rjnvuo 3i?>In order to describe requirements for a
	container all the operations are broken down into several categories as
	presented below.</para>

	<section>
	<?xxe-sn 2alsjvonojk 2q?>

	<title><?xxe-sn 2alsjvonojk 2r?>Operation 'access(serial)'</title>

	<para><?xxe-sn 2alsjvonojk 2s?>Operators: <code><?xxe-sn 2alsjvonojk 3e?>loop map</code>,
	<code><?xxe-sn 2alsjvonojk 3f?>loop fold</code>.</para>

	<para><?xxe-sn 2alsjvonojk 3s?>Annotation denotes sequential access
	operation, such as <code><?xxe-sn 2alsjvonojk 3t?>map loop</code> or
	<code><?xxe-sn 2alsjvonojk 3u?>map fold</code>.</para>

	<para><?xxe-sn 2alsjvonojk 43?>Example:</para>

	<programlisting xml:id="OpAccessSeq_1"><?xxe-sn 2alsjvonojk 44?>name = "tests/containers.cpp: Containers.Doc_OpAccessSeq_1"
	import raw("scripts/containers/containers.lp").

	test = function :: int; entry
	{
	range = [1..5] :: [int]; container(onthefly).
	sum = loop fold(range->el:: int, 0->acc):: [int]; access(serial)
	{
	acc + el
	}.

	sum
	}</programlisting>
	</section>

	<section>
	<?xxe-sn 2alsjvonojk 2t?>

	<title><?xxe-sn 2alsjvonojk 2u?>Operation 'access(rand)'</title>

	<para><?xxe-sn 2alsjvonojk 2v?>Operators: index</para>

	<para><?xxe-sn 2alsjvonojk 3v?>Annotation denotes random access
	operation.</para>

	<para><?xxe-sn 2apiasqubk0 1?>Example:</para>

	<programlisting xml:id="OpAccessRand_1"><?xxe-sn 2apiasqubk0 2?>name = "tests/containers.cpp: Containers.Doc_OpAccessRand_1"
	import raw("scripts/containers/containers.lp").

	test = function:: num; entry
	{
	a = {1, 2, 3, 4, 5}:: [num]; container(solid).
	a[1]:: num; access(rand)
	}</programlisting>
	</section>
	</section>

	<section>
	<?xxe-sn 2apiasqubk0 5?>

	<title><?xxe-sn 2apiasqubk0 6?>AST Attachments</title>

	<para><?xxe-sn 2apiasqubk0 7?>In order to bypass tedious writing of
	necessary annotations for each line of code that works with containers
	there are appropriate annotations already defined for common operations.
	All it takes for a client's code is to include transcend script
	<code><?xxe-sn 2apiasqubk0 8?>scripts/dfa/ast-attachments.lp</code> that
	allows to assign predefined annotations for syntactic constructs and
	operators.</para>

	<para><?xxe-sn 2apiasqubk0 9?>Example below includes <code><?xxe-sn 2apiasqubk0 e?>ast-attachments.lp</code>
	that feeds compiler with default annotations sparing developer of
	- specifying them manually. </para>
	+ specifying them manually.</para>

	<programlisting xml:id="ASTAttach_1"><?xxe-sn 2apiasqubk0 a?>name = "tests/containers.cpp: Containers.Doc_ASTAttach_1"
	import raw("scripts/containers/containers.lp").
	import raw("scripts/dfa/ast-attachments.lp").

	test = function :: int; entry
	{
	range = [1..5] :: [int].
	sum = loop fold(range->el:: int, 0->acc):: [int]
	{
	acc + el
	}.

	sum
	}</programlisting>
	</section>
	</chapter>
	+<?xxe-revisions
	+#1 2019-03-07T18:26:00Z pgess
	+?>
	\ No newline at end of file
	diff --git a/documentation/communication.xml b/documentation/communication.xml
	index f4293f6..1547364 100644
	--- a/documentation/communication.xml
	+++ b/documentation/communication.xml
	@@ -1,440 +1,443 @@
	<?xml version="1.0" encoding="UTF-8"?>
	<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:trans="http://docbook.org/ns/transclusion"
	xmlns:svg="http://www.w3.org/2000/svg"
	xmlns:m="http://www.w3.org/1998/Math/MathML"
	xmlns:html="http://www.w3.org/1999/xhtml"
	xmlns:db="http://docbook.org/ns/docbook">
	<?xxe-sn 29tvny21340 1?>

	<title><?xxe-sn 29tvny21340 2?>Communication</title>

	<para><?xxe-sn 2abbls7nbb4 2?>The chapter discusses safe usage of non-local
	variables, that is variables accessible by different components or threads
	with global variables as a particular case.</para>

	<section>
	<?xxe-sn 29xq7jt0wzk 1?>

	<title><?xxe-sn 29xq7jt0wzk 2?>Syntax</title>

	<para><?xxe-sn 29xq7jt0wzk 3?>Annotations:</para>

	<synopsis><?xxe-sn 2afyauuaxvk d?>SYNTAX:
	commop(send) (1)
	commop(receive) (2)</synopsis>

	<itemizedlist>
	<?xxe-sn 2afyauuaxvk e?>

	<listitem>
	<?xxe-sn 2afyauuaxvk f?>

	<para><?xxe-sn 2afyauuaxvk g?>annotation <code><?xxe-sn 2afyauuaxvk h?>(1)</code>
	marks <code><?xxe-sn 2afyauuaxvk i?>SEND</code> communication
	event.</para>
	</listitem>

	<listitem>
	<?xxe-sn 2afyauuaxvk j?>

	<para><?xxe-sn 2afyauuaxvk k?>annotation <code><?xxe-sn 2afyauuaxvk l?>(2)</code>
	marks <code><?xxe-sn 2afyauuaxvk m?>RECEIVE</code> communication
	event.</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 2afyauuaxvk n?>Specializations:</para>

	<synopsis><?xxe-sn 2afyauuaxvk o?>SYNTAX:
	commDirect
	commGuarded</synopsis>

	<para><?xxe-sn 2afyauuaxvk p?>Communication reasoning able to assign
	following specializations:</para>

	<itemizedlist>
	<?xxe-sn 2afyauuaxvk q?>

	<listitem>
	<?xxe-sn 2afyauuaxvk r?>

	<para><?xxe-sn 2afyauuaxvk s?><code><?xxe-sn 2afyauuaxvk t?>commDirect</code>
	— specialization is expected to provide direct access to raw
	variable's content.</para>
	</listitem>

	<listitem>
	<?xxe-sn 2afyauuaxvk u?>

	<para><?xxe-sn 2afyauuaxvk v?><code><?xxe-sn 2afyauuaxvk w?>commGaurded</code>
	— specialization is expected to do internal consistency checks at run
	time.</para>
	</listitem>
	</itemizedlist>
	</section>

	<section>
	<?xxe-sn 29tvny21340 3?>

	<title><?xxe-sn 29tvny21340 4?>Background</title>

	<para><?xxe-sn 29tvny21340 5?>One of the major concepts that support
	writing of safe programs is a notion of <emphasis><?xxe-sn 2abbls7nbb4 1?>immutability</emphasis>.
	Immutability tremendously simplifies many kinds of analyses; using
	immutable structures is a practical way to write multithreaded
	applications and has many other benefits beyond that. However in its most
	basic form it comes with a price of disastrous, in many cases, memory
	overhead, since property of immutability stipulates for each change of
	variable to make an independent copy of it occupying different memory
	region. Unwise using of immutable structures lead to the situation such
	that CPU is mostly occupied with unnecessary variables copying to and fro
	as well as with extensive garbage collection, irrelevant of actual
	algorithm's complexity at hand. Thus it is one of the central highlights
	of proper programming language design to provide techniques to overcome
	the shortcomings by relaxing immutability requirements keeping
	nevertheless safety benefits. There are many ways to approach the problem,
	and one such technique, namely <emphasis><?xxe-sn 2abbls7nbb4 3?>communication
	model</emphasis> is discussed next.</para>
	</section>

	<section>
	<?xxe-sn 29xq7jt0wzk 5?>

	<title><?xxe-sn 29xq7jt0wzk 6?>Communication Model</title>

	<para><?xxe-sn 29xq7jt0wzk 7?><emphasis><?xxe-sn 2abizkj6e4g 1?>Communication
	model</emphasis> is a way to capture and express what's going on with
	variables in a program as well as to define rules that describe valid
	operations over variables. Within the framework writing value to a
	variable is viewed as <emphasis><?xxe-sn 29xq7jt0wzk 8?>sending</emphasis>,
	and conversely reading variable's value is viewed as <emphasis><?xxe-sn 29xq7jt0wzk 9?>receiving</emphasis>.</para>

	<para><?xxe-sn 2abizkj6e4g 2?>Variables that are accessed from different
	components or threads are referred to as non-local variables. This chapter
	is focused on a on-local variables, global variables particularly, since
	exactly for them it's hard to manually check exhaustively where and how
	they are used in order to catch any errors. It is natural to view them as
	the means of interaction between different parts of a program, in other
	words, interaction between sender and receiver, where sender and receiver
	are different components. The same terms comprise rules that express valid
	ways of interacting. The abstraction is named <emphasis><?xxe-sn 29xq7jt0wzk a?>communication
	model</emphasis> due to similarity with the network communication.</para>

	<para><?xxe-sn 29xq7jt0wzk b?>Reasoning based on working with a
	<emphasis><?xxe-sn 2abizkj6e4g 3?>communication path</emphasis>, i.e chain
	of <emphasis><?xxe-sn 29xq7jt0wzk c?>communication events</emphasis>(e.g.
	sending/receiving) occurred during program execution.</para>

	<para><?xxe-sn 2abizkj6e4g 4?>Let's consider small example:</para>

	<programlisting><?xxe-sn 2abizkj6e4g 5?>a = init():: int; commop(send). //(1)
	b = a + 1 :: int; commop(receive). //(2)</programlisting>

	<para><?xxe-sn 2abizkj6e4g 6?>It shows computing of variable
	<code><?xxe-sn 2abizkj6e4g 7?>b</code>. Variable <code><?xxe-sn 2abizkj6e4g 8?>b</code>
	depends on <code><?xxe-sn 2abizkj6e4g 9?>a</code> so <code><?xxe-sn 2abizkj6e4g a?>a</code>
	is calculated first. Variables <code><?xxe-sn 2abizkj6e4g b?>a</code>,
	<code><?xxe-sn 2abizkj6e4g c?>b</code> are annotated with <code><?xxe-sn 2abizkj6e4g d?>comm(send)</code>
	and <code><?xxe-sn 2abizkj6e4g e?>comm(receive)</code>, denoting
	<emphasis><?xxe-sn 2abizkj6e4g f?>sending</emphasis> and
	<emphasis><?xxe-sn 2abizkj6e4g g?>receiving</emphasis> events,
	respectively. Communication path in this case is an ordered list
	<code><?xxe-sn 2abizkj6e4g h?>{<begin>, SEND, RECEIVE,
	<end>}</code> where <code><?xxe-sn 2abizkj6e4g i?><begin>,
	<end></code> — are special events that denote first and last events
	in the path, respectively.</para>

	<para><?xxe-sn 2abizkj6e4g k?>The gist of using communication model is to
	ensure that <emphasis><?xxe-sn 2abizkj6e4g l?>every sent value is properly
	received</emphasis>. It relies on the compiler to gather all possible
	communication paths in the program as an input for processing. There are
	two supported modes of reasoning:</para>

	<itemizedlist>
	<?xxe-sn 29xq7jt0wzk d?>

	<listitem>
	<?xxe-sn 29xq7jt0wzk e?>

	<para><?xxe-sn 29xq7jt0wzk f?>Validation. In this mode all
	communication paths are checked against communication rules to confirm
	that the program is valid. Otherwise compilation error is
	raised.</para>
	</listitem>

	<listitem>
	<?xxe-sn 29xq7jt0wzk g?>

	<para><?xxe-sn 29xq7jt0wzk h?>Planning. In this mode reasoning assigns
	proper implementation for variables in efforts to ensure
	validity.</para>
	</listitem>
	</itemizedlist>
	</section>

	<section>
	<?xxe-sn 29xq7jt0wzk j?>

	<title><?xxe-sn 29xq7jt0wzk k?>Validation</title>

	<para><?xxe-sn 29xq7jt0wzk l?>To perform validation, every communication
	path is checked against number of communication rules that express which
	communication path are valid. Default behaviour expressed by "every sent
	value being properly received" produce next possible cases:</para>

	<itemizedlist>
	<?xxe-sn 29xq7jt0wzk 1w?>

	<listitem>
	<?xxe-sn 29xq7jt0wzk 1x?>

	<para><?xxe-sn 29xq7jt0wzk 1y?>Valid. Path that consists of pairs of
	events <code><?xxe-sn 29xq7jt0wzk 1z?>{SEND, RECEIVE}</code> are
	<emphasis><?xxe-sn 29xq7jt0wzk 20?>valid</emphasis> meaning that each
	sent value is properly received.</para>
	</listitem>

	<listitem>
	<?xxe-sn 29xq7jt0wzk 21?>

	<para><?xxe-sn 29xq7jt0wzk 22?>Undefined and expired value. Paths that
	have parts <code><?xxe-sn 2abizkj6e4g m?>{<begin>,
	RECEIVE}</code> or <code><?xxe-sn 2abizkj6e4g n?>{RECEIVE,
	RECEIVE}</code> are invalid meaning possibly undefined value is
	received in the first case or duplication i.e. expired value is used
	in the second's one.</para>
	</listitem>

	<listitem>
	<?xxe-sn 2a3uy8rr2f4 5?>

	<para><?xxe-sn 2a3uy8rr2f4 6?>Lost value. Paths that have parts
	<code><?xxe-sn 2abizkj6e4g o?>{SEND, SEND}</code> or <code><?xxe-sn 2abizkj6e4g p?>{SEND,
	<end>}</code> indicate possibly lost change since consequent
	sender replaces value in the former case and sent value is not used at
	all in the latter case.</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 29xq7jt0wzk 28?>Traditional immutability validation is
	based on the idea that once valid value is valid as long it is unmodified.
	In this regards communication model can be viewed as an extension and more
	expressive tool since it also captures <emphasis><?xxe-sn 2afyauuaxvk 3?>value
	expiration</emphasis> after it was used as well as <emphasis><?xxe-sn 2afyauuaxvk 4?>value</emphasis>
	<emphasis><?xxe-sn 2afyauuaxvk 5?>loss</emphasis>, if it was not used at
	all.</para>
	</section>

	<section>
	<?xxe-sn 29xq7jt0wzk 29?>

	<title><?xxe-sn 29xq7jt0wzk 2a?>Planning</title>

	<para><?xxe-sn 2abizkj6e4g s?>Reasoning in the communication model aside
	of performing validation, also assigns appropriate specialization for
	sending and receiving operations, as appropriate. At the moment there are
	two specializations the operations are expected to support:</para>

	<itemizedlist>
	<?xxe-sn 2abizkj6e4g t?>

	<listitem>
	<?xxe-sn 2abizkj6e4g u?>

	<para><?xxe-sn 2abizkj6e4g v?>Direct. Direct specialization
	<code><?xxe-sn 2abizkj6e4g w?>commDirect</code> is expected to provide
	direct access to variable's value. This specialization is assigned in
	case of fully statically validated communication path.</para>
	</listitem>

	<listitem>
	<?xxe-sn 2abizkj6e4g x?>

	<para><?xxe-sn 2abizkj6e4g y?>Guarded. In case if there are possible
	communication path inconsistencies that can not be completely ruled
	out at compile time, checking logic should be embedded into compiled
	code. Specialization <code><?xxe-sn 2abizkj6e4g z?>commGaurded</code>
	is expected to hold variable state and check usage consistency.</para>
	</listitem>
	</itemizedlist>
	</section>

	<section>
	<?xxe-sn 2a3uy8rr2f4 8?>

	<title><?xxe-sn 2a3uy8rr2f4 9?>Planning Horizon</title>

	<para><?xxe-sn 2a3uy8rr2f4 a?>Reasoning implements algorithm that is
	bounded by the maximal path length it can process. The parameter is called
	<emphasis><?xxe-sn 2a3uy8rr2f4 b?>planning horizon</emphasis>. Any
	variable that it can not check due to exceedingly large path's length is
	assigned default implementation <code><?xxe-sn 2abizkj6e4g 10?>commGaurded</code>
	that performs necessary checks during runtime. Thus the parameter
	regulates trade off between static analysis extensiveness and runtime
	checks overhead.</para>
	</section>

	<section>
	<?xxe-sn 2a7t1hxqqyo 1?>

	<title><?xxe-sn 2a7t1hxqqyo 2?>Example: Direct Implementation</title>

	<programlisting xml:id="DirImpl_1"><?xxe-sn 2a7t1hxqqyo 3?>name="tests/effects-communication.cpp: Doc_DirImpl", lines=15
	import raw("scripts/dfa/propagation.lp").
	import raw("scripts/dfa/polymorphism.lp").
	import raw("scripts/effects-communication/communication.lp").
	import raw("scripts/effects-communication/config.lp").

	CommDirect = type {
	value:: int
	}.

	guard:: commDirect {
	init = function::CommDirect
	{
	{value = 0}
	}

	read = function(vault1:: CommDirect):: int
	{
	(vault1:: *;commop(receive))["value"]
	}

	write = function(vault2:: CommDirect, valueNew:: int)::CommDirect
	{
	(vault2:: *; dfa_pseudo(vault2)) + {value = valueNew}:: int; commop(send); dfa_uppy(vault2)
	}
	}

	main = function::int; entry {
	x1 = init()::*; dfa_polym(ret).
	x2 = write(x1, 1)::*; dfa_polym(arg).
	val = read(x2)::int; dfa_polym(arg).
	val
	}</programlisting>

	<para><?xxe-sn 2a7t1hxqqyo 4?>In this example, basic workflow is presented
	in <code><?xxe-sn 2afyauuaxvk 1?>main</code> — the function
	<code><?xxe-sn 2a7t1hxqqyo 5?>write(x1, 1)</code> is invoked following by
	invocation of <code><?xxe-sn 2a7t1hxqqyo 6?>read(x2)</code>. Functions
	<code><?xxe-sn 2afyauuaxvk 9?>write()</code> and <code><?xxe-sn 2afyauuaxvk a?>read()</code>
	are annotated with <code><?xxe-sn 2afyauuaxvk b?>commop(send)</code> and
	<code><?xxe-sn 2afyauuaxvk c?>commop(receive)</code> respectively in order
	to enable communication reasoning. Analyzer gathers and validates observed
	communication path and since there is no ambiguity, it's possible to
	assign specialization <code><?xxe-sn 2a7t1hxqqyo 7?>CommDirect</code>
	allowing direct access to the variables avoiding any additional overhead.
	Note, there are no any other specializations defined and if reasoning was
	not enable to conclude that it is the case the compilation error would be
	raised.</para>
	</section>

	<section>
	<?xxe-sn 2a7t1hxqqyo 9?>

	<title><?xxe-sn 2a7t1hxqqyo a?>Example: Guarded Implementation</title>

	<programlisting xml:id="GuardedImpl_1"><?xxe-sn 2a7t1hxqqyo b?>name="tests/effects-communication.cpp: Doc_GuardedImpl", lines=15
	import raw ("scripts/effects-communication/communication.lp").
	import raw ("scripts/dfa/propagation.lp").
	import raw ("scripts/dfa/polymorphism.lp").
	import raw ("scripts/effects-communication/config.lp").

	CommState = type variant{Invalid, Valid, Outdated}.

	CommDirect = type {
	value:: int
	}.

	CommGuarded = type {
	value:: int,
	state:: CommState
	}.

	guard:: commDirect {
	init=function::CommDirect{
	{value = 0}
	}

	read= function(vault1:: CommDirect):: int{
	(vault1::CommDirect; commop(receive))["value"]
	}

	write= function(vault2:: CommDirect, valueNew1:: int)::CommDirect{
	(vault2::CommDirect;dfa_pseudo(vault2)) + {value = valueNew1}:: int; commop(send); dfa_uppy(vault2)
	}
	}

	errorRead = function:: int { -1 }

	errorWrite = function:: CommGuarded{
	{
	value = -1,
	state = Invalid()
	}
	}

	guard:: commGuarded{
	init=function::CommGuarded{
	{
	value = 0,
	state = Invalid()
	}
	}

	read=function(vault3:: CommGuarded):: int {
	switch variant (vault3["state"]->whatever::CommState;commop(receive)):: int
	case (Invalid) { errorRead() }
	case (Outdated) { errorRead() }
	case (Valid) { vault3["value"] }
	}

	write=function(vault4:: CommGuarded, valueNew2:: int)::CommGuarded{
	switch variant (vault4["state"]->whatever::CommState;commop(send); dfa_pseudo(vault4))::int
	case (Invalid) {
	{value = valueNew2, state = Valid()}:: CommGuarded; dfa_uppy(vault4)
	}

	case (Outdated) {
	{value = valueNew2, state = Valid()}:: CommGuarded; dfa_uppy(vault4)
	}

	case (Valid) { errorWrite():: CommGuarded; dfa_uppy(vault4) }
	}
	}

	main=function(cmd:: num)::int; entry {
	x1 = init():: *; dfa_polym(ret).
	x2 = write(x1, 1)::*; dfa_polym(arg).

	x3 = if (cmd > 0)::int {
	y = read(x2):: int; dfa_polym(arg).
	y

	} else {
	z = write(x2, 2)::*; dfa_polym(arg).
	a = read(z):: int; dfa_polym(arg).
	a
	}.

	x3
	}</programlisting>

	<para><?xxe-sn 2a7t1hxqqyo d?>Here example of slightly more complicated
	workflow. Function <code><?xxe-sn 2afyauuaxvk 2?>main</code> contains
	branching that depends on argument known at run time only. Analyzer is
	presented with two possible communication paths and one of them(false
	branch) leads to a possibly lost value for it contains two consequent
	<code><?xxe-sn 2afyauuaxvk 6?>SEND</code> events. In this situation the
	analyzer unable to statically validate correctness and assigns
	specialization <code><?xxe-sn 2afyauuaxvk 7?>commGuarded</code> to embed
	checking logic into compiled code as an intermediary layer between
	variable's content and client's code. Implementation <code><?xxe-sn 2afyauuaxvk 8?>commGuarded</code>
	along with a variable access also tracks the variable status and returns
	error if the value is inconsistent.</para>
	</section>
	</chapter>
	+<?xxe-revisions
	+#1 2019-03-07T18:27:57Z pgess
	+?>
	\ No newline at end of file
	diff --git a/documentation/exploitation.xml b/documentation/exploitation.xml
	index 984d077..39bd002 100644
	--- a/documentation/exploitation.xml
	+++ b/documentation/exploitation.xml
	@@ -1,488 +1,490 @@
	<?xml version="1.0" encoding="UTF-8"?>
	<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:trans="http://docbook.org/ns/transclusion"
	xmlns:svg="http://www.w3.org/2000/svg"
	xmlns:m="http://www.w3.org/1998/Math/MathML"
	xmlns:html="http://www.w3.org/1999/xhtml"
	xmlns:db="http://docbook.org/ns/docbook">
	<?xxe-sn 26yv439af40 1?>

	<title><?xxe-sn 26yv439af40 2?>Exploitation</title>

	<para><?xxe-sn 26yv439af40 6?>This chapter discusses <emphasis><?xxe-sn 26yv439af40 7?>exploiting</emphasis>
	external resources, such as files, as a particular instance of a
	<emphasis><?xxe-sn 26yv439af40 8?>side effects</emphasis> problem that
	inevitably stems from an interaction with the outside world. Unlike <link
	xlink:href="/w/virtualization"><?xxe-sn 295bzzou9kw 2?>virtualization</link>,
	an another documentation's topic that tackles I/O, exploitation approaches
	subject from a different angle — it is concerned with an <emphasis><?xxe-sn 26yv439af40 x?>order
	of operations</emphasis>, sequence in which different clients jointly use
	the same resource and it deals with corresponding difficulties, e.g. ensures
	proper resource initialization before actual usage.</para>

	<section>
	<?xxe-sn 29je46abuev -wunr7fl0rw8v?>

	<title><?xxe-sn 29je46abuev -wunr7fl0rw8u?>Syntax</title>

	<section>
	<?xxe-sn 29je46abuev -wunr7fl0rw8s?>

	<title><?xxe-sn 29je46abuev -wunr7fl0rw8r?>Annotations</title>

	<synopsis><?xxe-sn 29je46abuev -wunr7fl0rw8q?>SYNTAX:
	use(//resource-id//)
	init(//resource-id//)</synopsis>

	<itemizedlist>
	<?xxe-sn 29je46abuev -wunr7fl0rw8p?>

	<listitem>
	<?xxe-sn 29je46abuev -wunr7fl0rw8o?>

	<para><?xxe-sn 29je46abuev -wunr7fl0rw8n?><emphasis><?xxe-sn 29je46abuev -wunr7fl0rw8m?>resource-id</emphasis>
	— user-defined resource identifier</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 29je46abuev -wunr7fl0rw8l?>Annotates function or code
	block as such that exploits resource <emphasis><?xxe-sn 29je46abuev -wunr7fl0rw8k?>resource-id</emphasis>.</para>
	</section>

	<section>
	<?xxe-sn 29je46abuev -wunr7fl0rw8j?>

	<title><?xxe-sn 29je46abuev -wunr7fl0rw8i?>Guards</title>

	<synopsis><?xxe-sn 29je46abuev -wunr7fl0rw8h?>SYNTAX:
	exploitation(init)
	exploitation(none)</synopsis>

	<para><?xxe-sn 29je46abuev -wunr7fl0rw8g?>Specializations that are
	recognized by exploitation reasoning. Each specialization corresponds to
	an initialization strategy:</para>

	<itemizedlist>
	<?xxe-sn 29je46abuev -wunr7fl0rw8f?>

	<listitem>
	<?xxe-sn 29je46abuev -wunr7fl0rw8e?>

	<para><?xxe-sn 29je46abuev -wunr7fl0rw8d?><code><?xxe-sn 29je46abuev -wunr7fl0rw8a?>exploitation(init)</code>
	is expected to perform actual resource initialization.</para>
	</listitem>

	<listitem>
	<?xxe-sn 29je46abuev -wunr7fl0rw8c?>

	<para><?xxe-sn 29je46abuev -wunr7fl0rw8b?><code><?xxe-sn 29je46abuev -wunr7fl0rw89?>exploitation(none)</code>
	is expected to do nothing as initialization isn't necessary or done
	elsewhere.</para>
	</listitem>
	</itemizedlist>
	</section>
	</section>

	<section>
	<?xxe-sn 26yv439af40 3?>

	<title><?xxe-sn 26yv439af40 4?>Background</title>

	<para><?xxe-sn 26yv439af40 b?>In software engineering, the idea to avoid
	side effects have received considerable traction. Indeed, side effects is
	something that is hard to take into account and thus programs that have
	side effects are inherently unsafe, thus best coding practices are
	rightfully suggest to isolate side effects producing code as much as
	possible. It's so called pure functional languages whose philosophy goes
	even further and frames side effects as something opposite of "pure", and
	everything is built around effectless computations to the point that some
	languages' design itself includes side effects producing constructs, such
	as I/O, as an afterthought, as something almost unnecessary.</para>

	<para><?xxe-sn 26yv439af40 c?>However, in reality the opposite is true,
	most applications' sole responsibility is to communicate with "outside
	world", reacting to the external events and change "world state"
	accordingly. As a consequence, side effects usually are the
	<emphasis><?xxe-sn 26yv439af40 d?>only</emphasis> important effects the
	program produce and surely deserve first class support from a programming
	language and justify efforts to develop approach to alleviate related
	safety and performance concerns.</para>
	</section>

	<section>
	<?xxe-sn 26yv439af40 z?>

	<title><?xxe-sn 26yv439af40 10?>Exploitation Plan</title>

	<para><?xxe-sn 26yv439af40 12?>One complexity of taking side effects into
	account is the fact that final result depends on an <emphasis><?xxe-sn 28ivhnywem8 1?>exact
	operations order</emphasis>. This harshly impacts both performance and
	safety, for many techniques, e.g. caching, parallelization can neither be
	automatically performed nor validated since they are based on various
	degrees of reordering or deal with possibly undetermined beforehand order
	of execution.</para>

	<para><?xxe-sn 28ivhnywem8 2?>In this chapter, it is assumed, that final
	effects of execution fully defined by <emphasis><?xxe-sn 28ivhnywem8 3?>exploitation
	path</emphasis> — for a particular code path that can occur during
	execution, it is its part consisting of only relevant code blocks., i.e.
	those that deal with an exploited resource. Other code blocks do not
	influence exploitation effects and so are excluded from consideration.
	Thus reasoning about effects is reduced to considering all possible
	exploitation paths, checking do they meet certain requirements that define
	valid exploitation and making corrections if needed and possible.</para>

	<para><?xxe-sn 26yv439af40 13?>Result of the reasoning is called
	<emphasis><?xxe-sn 26yv439af40 14?>exploitation plan</emphasis> —
	specification that defines exact order and strategy of using a given
	resource in order to comply with imposed requirements.</para>

	<para><?xxe-sn 26yv439af40 15?>With all above said, the discussed approach
	can be presented as follows:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 16?>

	<listitem>
	<?xxe-sn 26yv439af40 17?>

	<para><?xxe-sn 26yv439af40 18?>Annotations are used to express some
	aspects of side effects to enable further reasoning. They indicate
	code blocks that deal with resource as well as provide additional
	information about how exactly it is exploited, e.g. use, initialize or
	deinitialize resource.</para>
	</listitem>

	<listitem>
	<?xxe-sn 28ivhnywem8 4?>

	<para><?xxe-sn 28ivhnywem8 5?>Existing code paths, extracted during
	source code processing, coupled with relevant annotations is enough to
	construct all possible exploitation paths and analyze them. Analysis
	determines possible(<emphasis><?xxe-sn 295bzzou9kw 3?>weak</emphasis>)
	paths that can occur or not during particular execution as well as
	certain paths(<emphasis><?xxe-sn 295bzzou9kw 4?>strong</emphasis>)
	that occur always no matter what. Also it checks are exploitation
	paths valid against certain rules, e.g. initialization occurs always
	before actual usage and is it possible to correct invalid
	paths.</para>
	</listitem>

	<listitem>
	<?xxe-sn 28ivhnywem8 6?>

	<para><?xxe-sn 28ivhnywem8 7?>Reasoning's result is an exploitation
	plan that dictates order and strategy of exploitation is presented in
	form of appropriate specialization for polymorphic functions that deal
	with resources in order to ensure safe exploitation to the extent
	based on provided annotations.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 19?>

	<para><?xxe-sn 26yv439af40 1a?>Exploitation related side effects are
	viewed as a set of additional restrictions over operations order. Only
	subset of possible reorders is still valid w.r.t. side effects.
	Transcend's task is to find out refined set of valid orders. Thus
	techniques that rely on reordering enjoy additional information to
	make safe optimizations.</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 26yv439af40 1b?>... and it serves three major goals:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 1c?>

	<listitem>
	<?xxe-sn 26yv439af40 1d?>

	<para><?xxe-sn 26yv439af40 1e?>Safety. Validates existing exploitation
	plan or is it possible to safely exploit given resource at all.
	Compiler signals error if a given exploitation plan is invalid, i.e.
	does not satisfy requirements w.r.t. side effects as expressed by
	annotations.</para>
	</listitem>

	<listitem>
	<?xxe-sn 28j5661y0mv -wunr7fl0rw8v?>

	<para><?xxe-sn 28j5661y0mv -wunr7fl0rw8u?>Regression Resilience. When
	it comes to using external resources, some spurious dependencies
	usually occur between otherwise isolated, independent components of a
	program. Sometimes refactoring and other code changes break those
	dependencies inevitably introducing regressions. Exploitation catches
	this sort of regressions and automatically regenerates exploitation
	plan suited for a changed conditions.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 1f?>

	<para><?xxe-sn 26yv439af40 1g?>Performance. Generated exploitation
	plans are optimal in a sense that they cut off superfluous operations,
	for example, removing resource initialization in several places if it
	can be done safely in a single one, thus reducing overall
	overhead.</para>
	</listitem>
	</itemizedlist>
	</section>

	<section>
	<?xxe-sn 27ay8x1a5mo 1?>

	<title><?xxe-sn 27ay8x1a5mo 2?>Domination Analysis</title>

	<para><?xxe-sn 27ay8x1a5mo 3?>When it comes to a reasoning about order of
	execution flow and possible code paths, crucial vehicle for that is
	<emphasis><?xxe-sn 27ay8x1a5mo 4?>domination analysis</emphasis> producing
	<emphasis><?xxe-sn 27ay8x1a5mo 5?>dominator tree</emphasis> as an
	output.</para>

	<para><?xxe-sn 27ay8x1a5mo 6?>Unlike the usual function-bounded domination
	analysis, when separate domination tree is produced for each function
	defined in a program, Exploitation requires program bound analysis, that
	is to take into account control flow across all functions in a program. It
	is computationally intensive task to perform analysis over a whole
	program, however it is compensated by the fact that Exploitation only
	takes into account code blocks that deal with, or in other words, exploit
	external resources. Thus there is no necessity to build full dominator
	tree, only the relevant parts are constructed, just enough to make sound
	exploitation plan decisions.</para>
	</section>

	<section>
	<?xxe-sn 28h47d43thc i?>

	<title><?xxe-sn 28h47d43thc j?>Empty Exploitation Plan. Effect Free
	Computations</title>

	<para><?xxe-sn 28h47d43thc k?>Validation of exploitation path is done
	against some predefined constraints. Depending on complexity of a
	constraints, i.e. number of different exploitation events that are seeking
	for in each path, reasoning goals categorized into several groups:</para>

	<itemizedlist>
	<?xxe-sn 28j5661y0mv -wunr7fl0rw8t?>

	<listitem>
	<?xxe-sn 28j5661y0mv -wunr7fl0rw8s?>

	<para><?xxe-sn 28j5661y0mv -wunr7fl0rw8r?>Zero Order Exploitation.
	Meaning that all paths are checked in terms is there exploitation at
	all or no, is there at least a single exploitation event along the
	path.</para>
	</listitem>

	<listitem>
	<?xxe-sn 28j5661y0mv -wunr7fl0rw8q?>

	<para><?xxe-sn 28j5661y0mv -wunr7fl0rw8p?>First Order Exploitation.
	Deals with a situations when it's enough to check only two different
	exploitation event occur in a required order. It can be useful for
	example, to check whether all resource uses occur after it is
	initialized.</para>
	</listitem>

	<listitem>
	<?xxe-sn 28j5661y0mv -wunr7fl0rw8o?>

	<para><?xxe-sn 28j5661y0mv -wunr7fl0rw8n?>Higher Order Exploitation.
	Expresses constraints involving several(more than two) exploitation
	events and relations between them.</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 28j5661y0mv -wunr7fl0rw8m?><emphasis><?xxe-sn 28j5661y0mv -wunr7fl0rw8l?>Empty
	Exploitation</emphasis> is an important instance of zero order constraint.
	It useful mechanism for developer to annotate function or part of a
	program as effect free in terms of exploitation. Thus, efectless, clean or
	- pure code can be clearly separated from effectfull part and compiler
	- raises compilation error in case of accidental mixing or using "wrong"
	- type of code in non appropriate environment.</para>
	+ pure code can be clearly separated from effectful part and compiler raises
	+ compilation error in case of accidental mixing or using "wrong" type of
	+ code in non appropriate environment.</para>
	</section>

	<section>
	<?xxe-sn 26yv439af40 u?>

	<title><?xxe-sn 26yv439af40 v?>Resource Initialization</title>

	<para><?xxe-sn 26yv439af40 w?>One important problem related to an
	exploitation order is to ensure that a given resource is properly
	initialized before its first usage and additionally it is not initialized
	more then once during exploitation session. This is instance of first
	order exploitation since in a validation mode it is enough to check
	exploitation plan to ensure that every resource usage preceded by resource
	initialization at some point in the <emphasis><?xxe-sn 28jw0wb6fpc 1?>past</emphasis>,
	i.e. previously in the exploitation path.</para>

	<para><?xxe-sn 28jw0wb6fpc 2?>For planning mode, the problem is addressed
	as follows:</para>

	<itemizedlist>
	<?xxe-sn 28jw0wb6fpc 3?>

	<listitem>
	<?xxe-sn 28jw0wb6fpc 4?>

	<para><?xxe-sn 28jw0wb6fpc 5?>Central idea of the algorithm is to
	consider candidates for initialization only among code blocks that
	<emphasis><?xxe-sn 295bzzou9kw 5?>dominate</emphasis> given usage
	site. Obviously, initialization in dominating block precedes usage for
	any possible code path.</para>
	</listitem>

	<listitem>
	<?xxe-sn 295bzzou9kw 6?>

	<para><?xxe-sn 295bzzou9kw 7?>One or more dominator blocks are chosen
	for actual initialization in such way that they are cover all found
	usage sites.</para>
	</listitem>

	<listitem>
	<?xxe-sn 295bzzou9kw 8?>

	<para><?xxe-sn 295bzzou9kw 9?>For code blocks chosen for
	initialization specialization <code><?xxe-sn 295bzzou9kw a?>exploitation(init)</code>
	is set, for the rest specialization <code><?xxe-sn 295bzzou9kw b?>exploitation(none)</code>
	is used.</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 28h47d43thc 1?>Look at the example below:</para>

	<programlisting xml:id="ResourceInit_1"><?xxe-sn 28h47d43thc 2?>name="tests/exploitation.cpp: Doc_ResourceInit_1", lines=15
	import raw("scripts/cfa/payload.lp").
	import raw("scripts/exploitation/exploitation.lp"). //exploitation reasoning
	import raw("scripts/exploitation/test1.assembly.lp").

	guard:: exploitation(init)
	{
	openFile = function(filePrev:: FILE_P):: FILE_P; init(file)
	{
	fopen("/tmp/test", "w")::FILE_P
	}
	}

	guard:: exploitation(none)
	{
	openFile = function(filePrev:: FILE_P):: FILE_P
	{
	filePrev::int
	}
	}

	test = function:: int; entry
	{
	seq
	{ f0 = undef:: FILE_P. f0 }
	{
	//Scope #1:
	f1 = openFile(f0):: FILE_P.
	f1
	}

	{ //Scope #2:
	f2 = openFile(f1):: FILE_P.
	f2
	}
	{
	//Scope #3:
	sizeWritten = fwrite("Attempt to write..", 12, 1, f2):: int; use(file).
	sizeWritten
	}
	{
	//Scope #4:
	fclose(f2):: int; use(file)
	}
	{ sizeWritten :: int}
	}</programlisting>

	<para><?xxe-sn 28h47d43thc 3?>There is the function <code><?xxe-sn 28h47d43thc 4?>test</code>
	that executes sequentially next commands: open a file(scopes #1, #2),
	write some text(scope #3) and finally, close the file(scope #4). It
	represents simple work flow with an external resource.</para>

	<para><?xxe-sn 28h47d43thc 7?>In order to connect the code to the
	exploitation the functions <code><?xxe-sn 28h47d43thc 5?>fwrite</code> and
	<code><?xxe-sn 28h47d43thc 6?>fclose</code> in scopes #3 and #4
	respectively are annotated with annotation <code><?xxe-sn 295bzzou9kw c?>use(file)</code>.
	This information is used by reasoning to look whether it is possible to
	initialize given resource before actual usage as well as where and when
	exactly to initialize it. Function <code><?xxe-sn 28h47d43thc 9?>openFile</code>
	is annotated as <code><?xxe-sn 28h47d43thc a?>init(file)</code> meaning it
	<emphasis><?xxe-sn 28h47d43thc b?>can</emphasis> initialize depending on
	chosen strategy. The function is invoked both in scope #1 and scope #2.
	Both scopes are executed <emphasis><?xxe-sn 28h47d43thc d?>strictly
	before</emphasis> scopes #3, #4. Thus it is indeed possible to initialize
	resource before usage. Next task for exploitation is to choose correct
	exploitation plan, i.e. to assign strategies for all possible
	initialization places in the effort to initialize resource only once.
	Here, it means that only one invocation of <code><?xxe-sn 28h47d43thc e?>openFile</code>
	is assigned with <code><?xxe-sn 28h47d43thc f?>exploitation(init)</code>
	to actually initialize the file. Other one is automatically marked with
	<code><?xxe-sn 28h47d43thc g?>exploitation(none)</code> to invoke
	different specialization of <code><?xxe-sn 28h47d43thc h?>openFile</code>
	- that does nothing since the files is already initialized.</para>
	+ that does nothing since the file is already initialized.</para>
	</section>
	</chapter>
	<?xxe-revisions
	+#13 2019-03-07T18:19:21Z pgess
	#12 2019-02-09T15:16:04Z pgess
	+1sPEAAABgYUGABiBhQgAAAoHc91tE6ZjQwVTMwDdbIN6om0=
	+
	#11 2019-02-02T13:07:26Z pgess
	1sPEAAABgYUIAAyBhQgAAAQBc4GFCAA=
	-
	#10 2019-02-01T17:38:23Z pgess
	1sPEAAABgYUKAIFE9icACGZQc28yPz5sZWFziRsTC0MIQ2oTC2OCNgECQ4MkU4s0IwcTC2PCVFMF
	MyRTFgEDM4kVEwVDCmMJU4I8EwxThHozgVuDDEOBGoMIMwljVVMMQwVTPBMEAQMTBxMGYw5TbUMP
	Yx9TLHMQEwcTChMJUxYAiR6YbxmDNI5ygjqDMb5tjjuLSbZOimemdYERpyObYagAiSKDYoJMhH3i
	gWejny2BIIFcqCZl6Q6TG4l51AGZa4N5lkeBJZzSBZdFigWdWA==
	#9 2019-01-26T14:30:18Z pgess
	1sPEAAAB9icAUfYlAAEqIGRz0wATB0OBHVMEQxszCBMFQzRTBTMEYwdjgRgTCAEBY4I9MwpDgVxj
	m00Ap2mrJoRxiR2ZGo5OijKLeq8mnUlJhCOBG54rgkGBYw==
	#8 2019-01-15T20:23:54Z pgess
	1sPEAAAB9ioAhCvvEAAlgiWBWTphc3NvY+KAlENzVW5ld2Jyb2tld2lmb3JzIDh0cmlnZ2MzZWRz
	hjUTDkNNEwgjBVMPAQFDQVNUAQVjBCMHMwQTBjMIY4wxUwdDgw5jfwEDUwQzihsBAVMiIwVjgRFD
	BFNTYwYzgnoTByMGAQFDix3UEwxDCjMGMwxjBVM2YxozBc0TBkMWEyBjbFMJUyVjDhMIMzdji11T
	CEMHMxVTBwEFYwSkY4I8kxZTK2OLHFMYM1EBAjOBEhMRUw0TEEOBPUMdMwSTCDMFUwlDBwEEYxET
	CUMMUyAzim8zEUMcYwVTIRMSQxozgV1TEZMLAQFjE2MKEwcBBTMEgwxjC1MGYwQzBjMOQ4EbM4FY
	UwkTBGMXAQFTD0MIUw5jTSMEEwtTBwEBUwczGpMIQwgzBVMGAQJjgQYTBTMFkwhjBmMHcwVTCYME
	UwQzCUODSwCGSj+FZK15XBNPiyyLPJR1hWWUNYNkpX6MOIMfiRmBCIolnGArgTQQdhKbF60ngxKE
	KINihiyoLp1okBUHN4hQjnyjB404oSOUH4lodqw8hHBFO4ZOqxeLbIIllBGGCCpGrHyDDC6HLFip
	eZ4Bg3iBQYFqhwi+jEQfpVuYPIl8mXqLN4dsin4bj20rhGeZD0++OQWCBYFdllSWf+JYhH8Oymig
	CB+BHoFDok6fa5MkgieFGRKBGqJyzHaLRL41cCiqf69yhAWEe4FAcM5PhGACnnsZgT6gNho=
	#7 2019-01-15T13:53:13Z pgess
	1sPEAAAB7xAAIuoxAAAQDHPREhMKQwRTQBMJExBjmDgAog2uVjCJF4N4hUU=
	#6 2019-01-15T11:27:29Z pgess
	1sPEAAAB6jIAF+dpAAAKB3PMJBMJQylTmxMAiReKLbtb
	#5 2019-01-15T08:04:19Z pgess
	1sPEAAAB520AglrYYQAogTF6RGF0aXNvZmluIGxpbVN0bDo6IEMxakRlLCwsaGxsIEluIHNoYWJ1
	dHOjSwEDEwYBAiMEAQJDCmMEYwtDTGMFUyIzBzMGEw9TgyxDDxMFYwYTCSMFIwoTBTMKEwkzJgEG
	MwQzC1OCV+ETBQEBQ1pjCVMMM0djBgEBY4EBAQFDJVMxEwZjdxMMQy4BA1MJYxJjFjMgYwQTGwEC
	YxkBAUMGAQFjBFMGAQODCZMMgywBATMIMwQBBkMEExL5EwdDC0MHYxJDBQECUwSDCVOGCQEDQ4Na
	gwkzKVObEwCRFaoCiCekAopDFIULT3MjmUcbgweMEYRHhjqtBLRjhWyRCoRwkXWCKoEaPYFqh32C
	W4EahyZxhydMgQJfnjBHgzSFHYs5rTyVBJE+oEODeJFFjn6SK50Al37CmTiVDYJ8kR9Wi06ZMoMu
	EoEUnUCXizOGEJeKLY5K
	#4 2019-01-14T13:48:02Z pgess
	1sPEAAAB2GUAgSjKVwAOVz0zPz5UdHRlc2hvdWxTcnOVKhMWQ4IsEwzdUwUBAWMEUwdjCGMJIwYB
	ATMFAQFjBFMIEx9TNVMEMwRjC1MMUxEBBRMEMwkzgl5TCmMLgyBDIwEBY4FMMw0zBFMXM4pXEwUB
	AWOgfQCVTSKDNKlVixtjgU2UA4k+mUicDoljFoQumTyORYVtRoN7HZdigjEdkjOBQiyJVjmVRIRC
	gQeCUZlRh2Q=
	#3 2018-12-24T11:55:39Z pgess
	1sPEAAAByiAAglmxQABBgSBxZmxmbWZucmVzdWxpbmRpdmlkZG8gc28sIGJvZ3VzIGdsb2JpcyBs
	bCBsQ0ZHNz8+QS04Pz5mb3J3bzk/PnAvPgpzpUkTCwECQx8BAlMZUyUBAmMpM4EjU4IUYwgBBRMF
	Mw4TBhMJQwcBB2MMMwQTC0MgMwYzByMPQyVDCwERYwRDBRMFYwUzBEMJUwQTBAEDEwQzB+LWUw4B
	A0MKExBzCwEEUwUzBiMMAQEzCFMKYwQTF3MLAQczBFMHAQFDDTMGExRzCwEEQwSDByMPUwRDBRMF
	Qw1TKWOCS3MLAQETCAECAIM0DKp5LlmhW4E7gxWgXIJenROObIhji1uHGoNjOIxDiwt0S5NdhiSN
	F4xGlnaRBothlSWICkSYHIYbimyXV4I3g3jJhQKEEIIQi1uDJJ8LhCvJjEOBfINCl0GELsmHL8VC
	hTySPYYHhl2NPYcQxAE=
	#2 2018-12-24T11:20:18Z pgess
	1sPEAAABsUAAErE4AAAHBXOwUxMGQ18AqheGSg==
	#1 2018-12-18T16:02:30Z pgess
	1sPEAAABsT0AMqdsAAIYEm9sc6JqAQITDEMLQwuDIDODMhMLQ2JDFGMLAJhklUuCMJSIGoM0izSB
	dIJQ
	?>
	\ No newline at end of file
	diff --git a/documentation/virtualization.xml b/documentation/virtualization.xml
	index 8876674..fea27c3 100644
	--- a/documentation/virtualization.xml
	+++ b/documentation/virtualization.xml
	@@ -1,497 +1,541 @@
	<?xml version="1.0" encoding="UTF-8"?>
	<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:trans="http://docbook.org/ns/transclusion"
	xmlns:svg="http://www.w3.org/2000/svg"
	xmlns:m="http://www.w3.org/1998/Math/MathML"
	xmlns:html="http://www.w3.org/1999/xhtml"
	xmlns:db="http://docbook.org/ns/docbook">
	<?xxe-sn 26yv439af40 1k?>

	<title><?xxe-sn 26yv439af40 1l?>Virtualization</title>

	- <para><?xxe-sn 26yv439af40 1m?>The chapter expands on a usage of context
	+ <para><?xxe-sn 26yv439af40 1m?>The chapter expands on the usage of context
	based polymorphism, in other words, reasoning over CFG, as a ground to
	implement <emphasis><?xxe-sn 26yv439af40 1n?>application level
	virtualization</emphasis>.</para>

	- <para><?xxe-sn 26yv439af40 1o?>One way to approach virtualization problem is
	- to model it in terms of satisfying constraints imposed by environment over
	- agents that operate within it, as presented below:</para>
	+ <remark><?xxe-sn 2c3rmc3fvnj 1td6aqezxvj7l?>Желательно расшифровать
	+ аббревиатуру CFG, до этого она нигде не встречалась, и мне не ясно что она
	+ означает</remark>
	+
	+ <para><?xxe-sn 26yv439af40 1o?>One way to approach the virtualization
	+ problem is to model it in terms of satisfying constraints imposed by
	+ environment over agents that operate within it, as presented below:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 1p?>

	<listitem>
	<?xxe-sn 26yv439af40 1q?>

	<para><?xxe-sn 26yv439af40 1r?><emphasis><?xxe-sn 26yv439af40 1s?>sizo</emphasis>
	- (distorted abbreviation of SEcurity ZOne) — logical entity introduced to
	- represent environment and describe desired virtualization
	+ (distorted abbreviation for SEcurity ZOne): logical entity introduced to
	+ represent an environment and describe the desired virtualization
	outcome.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 1t?>

	<para><?xxe-sn 26yv439af40 1u?><emphasis><?xxe-sn 26yv439af40 1v?>zek</emphasis>
	- (distorted abbreviation of SEcurity aGent) — represents behaviour of the
	+ (distorted abbreviation for SEcurity aGent): represents behaviour of the
	code in terms of virtualized resources access.</para>
	+
	+ <remark><?xxe-sn 2c3rmc3fvnj 1td6aqezxvj7m?>По поводу длинных тире:
	+ насколько я знаю, они практически не используются в английском языке
	+ (как и наши «типографские» кавычки). Только короткие. Но эту информацию
	+ нужно проверить (PS: сегодня читал книгу на английском, и таки увидел
	+ там длинные тире).</remark>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 26yv439af40 1w?>Basic idea is to automatically reason over
	information defined by sizos and zeks and produce <emphasis><?xxe-sn 26yv439af40 1x?>virtualization
	plan</emphasis> as a solution that dictates which parts of code should be
	virtualized and how exactly. Such reasoning enables two features:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 1y?>

	<listitem>
	<?xxe-sn 26yv439af40 1z?>

	<para><?xxe-sn 26yv439af40 20?>Optimization. Allows choosing
	- virtualization technique with a least performance penalty nevertheless
	- satisfying necessary requirements.</para>
	+ virtualization technique with the smallest performance penalty
	+ nevertheless satisfying necessary requirements.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 21?>

	<para><?xxe-sn 26yv439af40 22?>Safety. Validates manually chosen
	- virtualization plan to be safe and sound by checking that it indeed
	- satisfies requirements.</para>
	+ virtualization plan to ensure it is solid and operable by checking that
	+ it indeed satisfies requirements.</para>
	+
	+ <remark><?xxe-sn 2c3rmc3fvnj 1td6aqezxvj7n?>Я бы вообще сократил: "to
	+ ensure it is solid, operable and satisfying the necessary
	+ requirements"</remark>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 26yv439af40 23?>In other words, context based reasoning
	- provides improvements by virtualizing only necessary sections of code, only
	- for necessary type of resources and by employing as lightweight as possible
	- virtualization strategy just enough to comply with safety and security
	- requirements expressed by annotations in the code.</para>
	+ provides improvements by virtualizing only necessary sections of code and
	+ only for necessary type of resources by employing as lightweight
	+ virtualization strategy as possible – just enough to comply with the safety
	+ and security requirements expressed by annotations in the code.</para>

	<section>
	<?xxe-sn 26yv439af40 24?>

	<title><?xxe-sn 26yv439af40 25?>Background</title>

	<para><?xxe-sn 26yv439af40 26?><emphasis><?xxe-sn 26yv439af40 27?>Virtualization</emphasis>
	- refers to an abstracting code from underlying <emphasis><?xxe-sn 26yv439af40 28?>resources</emphasis>
	- used by it. Here term resource depicts any external entity such as
	- devices, files, network connections, etc, for which it is desirable to
	+ refers to abstracting code from the underlying <emphasis><?xxe-sn 26yv439af40 28?>resources</emphasis>
	+ used by it. Here the term 'resource' depicts any external entity such as a
	+ device, file, network connection etc, for which it is desirable to
	regulate access.</para>

	<para><?xxe-sn 26yv439af40 29?>Virtualization is a vast area and broad
	term that includes number of techniques on different levels to achieve
	several important goals such as:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 2a?>

	<listitem>
	<?xxe-sn 26yv439af40 2b?>

	- <para><?xxe-sn 26yv439af40 2c?>Shared access — to allow several
	- clients use the same resource while behaving as if each client is the
	- sole resource user simplifying development and testing.</para>
	+ <para><?xxe-sn 26yv439af40 2c?>Shared access — allowing several
	+ clients to use the same resource while behaving as if each client were
	+ sole resource user, to simplify development and testing.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 2d?>

	<para><?xxe-sn 26yv439af40 2e?>Isolation — cornerstone of safety and
	behaviour repeatability achieved by minimizing influence of isolated
	clients between each other and external environment.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 2f?>

	- <para><?xxe-sn 26yv439af40 2g?>Adaptation — to allow client
	- application work within an unexpected environment it was not developed
	+ <para><?xxe-sn 26yv439af40 2g?>Adaptation — allowing client
	+ application work in an unexpected environment it was not developed
	for, by emulating "native" familiar environment thus reducing
	adaptation and support costs.</para>
	</listitem>
	</itemizedlist>

	- <para><?xxe-sn 26yv439af40 2h?>Due to importance of goals achievable with
	- virtualization, it is unavoidable in a long run. That being said, basic
	- virtualization techniques have performance penalties arising from indirect
	- and regulated access to underlying resources.</para>
	+ <para><?xxe-sn 26yv439af40 2h?>Due to the importance of goals achievable
	+ with virtualization, it is unavoidable in a long run. That being said,
	+ basic virtualization techniques have performance penalties arising from
	+ indirect and regulated access to underlying resources.</para>

	<para><?xxe-sn 26yv439af40 2i?>Further discussion is concerned with what
	can be done to alleviate major virtualization inefficiencies by
	- fine-grained control over what, when, and how should be
	- virtualized.</para>
	+ fine-grained control over what should be virtualized, when, and
	+ how.</para>
	</section>

	<section>
	<?xxe-sn 26yv439af40 2j?>

	<title><?xxe-sn 26yv439af40 2k?>Access Control</title>

	- <para><?xxe-sn 26yv439af40 2l?>Whole program can be broken down into one
	+ <para><?xxe-sn 26yv439af40 2l?>A whole program can be broken down into one
	or more virtualization zones, each having different appropriate type of
	virtualization strategy. Such approach allows to model <emphasis><?xxe-sn 26yv439af40 2m?>hybrid
	- virtualization</emphasis>, i.e. different parts of program are virtualized
	- differently depending on some conditions. To capture this concept, term
	- <emphasis><?xxe-sn 26yv439af40 2n?>sizo</emphasis> is introduced and
	- refers to a logical entity that holds information about particular zone
	- necessary to find best suited virtualization strategy.</para>
	+ virtualization</emphasis>, i.e. different parts of a program are
	+ virtualized differently depending on certain conditions. To capture this
	+ concept, the term <emphasis><?xxe-sn 26yv439af40 2n?>sizo</emphasis> is
	+ introduced, that refers to a logical entity that holds information about a
	+ particular zone necessary to find best suited virtualization
	+ strategy.</para>

	<important>
	<?xxe-sn 26yv439af40 2o?>

	<para><?xxe-sn 26yv439af40 2p?>Sizo is associated with <link
	xlink:href="/w/concepts/context"><?xxe-sn 26yv439af40 2q?>context</link>,
	i.e. each zone spans over one or more code blocks.</para>
	</important>

	- <para><?xxe-sn 26yv439af40 2r?>There is a annotation <code><?xxe-sn 26yv439af40 2s?>assign_sizo</code>
	+ <para><?xxe-sn 26yv439af40 2r?>There is an annotation <code><?xxe-sn 26yv439af40 2s?>assign_sizo</code>
	to specify sizo a code block is assigned to:</para>

	<synopsis><?xxe-sn 26yv439af40 2t?>SYNTAX:
	assign_sizo(//sizo-ref//).</synopsis>

	<itemizedlist>
	<?xxe-sn 26yv439af40 2u?>

	<listitem>
	<?xxe-sn 26yv439af40 2v?>

	<para><?xxe-sn 26yv439af40 2w?><emphasis><?xxe-sn 26yv439af40 2x?>sizo-ref</emphasis>
	unique sizo's identifier</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 26yv439af40 2y?>Next thing is to specify which resources a
	- particular sizo controls access to, as below:</para>
	+ particular sizo controls access to, as demonstrated below:</para>

	<synopsis><?xxe-sn 26yv439af40 2z?>SYNTAX:
	assign_sizo_control(//resource-type//).</synopsis>

	- <para><?xxe-sn 26yv439af40 30?>It indicates that current sizo(sizo that
	- spans over code block the annotation located within) regulates all access
	- to a resources of a given type <emphasis><?xxe-sn 26yv439af40 31?>resource-type</emphasis>.
	- Conversely, If for a particular environment there is no need to control,
	- for example, file system access, no virtualization for file operations is
	+ <para><?xxe-sn 26yv439af40 30?>It indicates that the current sizo (sizo
	+ that spans over the code block wherein the annotation is located)
	+ regulates all access to resources of a given type, <emphasis><?xxe-sn 26yv439af40 31?>resource-type</emphasis>.
	+ Conversely, if for a particular environment there is no need to control
	+ e.g. file system access, no virtualization for file operations is
	applied.</para>

	<para><?xxe-sn 26yv439af40 32?>On the other hand, there is an annotation
	- to mark function that accesses one or another resource:</para>
	+ to mark a function that accesses one or another resource:</para>

	<synopsis><?xxe-sn 26yv439af40 33?>SYNTAX:
	assign_zek_access(//resource-type//).</synopsis>

	<para><?xxe-sn 26yv439af40 34?>Let's consider an example to demonstrate
	- all above:</para>
	+ all the above:</para>

	<programlisting xml:id="AccControl_1"><?xxe-sn 26yv439af40 35?>name="tests/virtualization.cpp: Virtualization.Doc_AccControl_1", lines=15
	import raw ("scripts/cfa/context.lp"). //enable context reasoning
	import raw ("scripts/virtualization/virtualization.lp"). //enable virtualization reasoning

	guard:: strategy(direct)
	{
	openFile = function(filename::string):: int
	{
	printf("direct file access")
	}
	}

	guard:: strategy(common)
	{
	openFile = function(filename::string):: int;
	assign_zek_access(files)
	{
	printf("virtualized file access")
	}
	}

	main = function:: int; entry
	{
	context:: assign_sizo(zoneA);
	assign_sizo_control(files).
	openFile("/some/file")
	}</programlisting>

	- <para><?xxe-sn 26yv439af40 36?>Example outlines dummy function
	+ <para><?xxe-sn 26yv439af40 36?>The example outlines a dummy function
	<code><?xxe-sn 26yv439af40 37?>openFile</code> to model file system
	- access. The function has two specializations with guards <code><?xxe-sn 26yv439af40 38?>strategy(direct)</code>
	- to model direct access, and <code><?xxe-sn 26yv439af40 39?>strategy(common)</code>
	- to be invoked if virtualization is enabled. It also annotated with
	+ access. The function includes two specializations with the <code><?xxe-sn 26yv439af40 38?>strategy(direct)</code>
	+ guard to model direct access, and the <code><?xxe-sn 26yv439af40 39?>strategy(common)</code>guard
	+ to be invoked if virtualization is enabled. It is also annotated with
	<code><?xxe-sn 26yv439af40 3a?>assign_zek_access(files)</code> to indicate
	- that it accesses file system. On the other hand, context of function
	- <code><?xxe-sn 26yv439af40 3b?>main</code> defines sizo <code><?xxe-sn 26yv439af40 3c?>zoneA</code>
	- and enables control over file operations.</para>
	-
	- <para><?xxe-sn 26yv439af40 3d?>Reasoning works with provided information
	- and decides whether it is necessary to enable virtualization. In this
	- case, the answer is yes for <code><?xxe-sn 26yv439af40 3e?>zoneA</code>,
	- because of the fact that sizo controls file operations and there is
	- actually function within the sizo that requires files access.
	- Consequently, example outputs:<screen xml:id="Output_AccControl_1"><?xxe-sn 26yv439af40 3f?>virtualized file access</screen>confirming
	+ that it accesses the file system. On the other hand, the context of the
	+ function <code><?xxe-sn 26yv439af40 3b?>main</code> defines the
	+ <code><?xxe-sn 26yv439af40 3c?>zoneA</code> sizo and enables control over
	+ file operations.</para>
	+
	+ <para><?xxe-sn 26yv439af40 3d?>Reasoning works with the provided
	+ information and decides whether it is necessary to enable virtualization.
	+ In this case, the answer is yes for <code><?xxe-sn 26yv439af40 3e?>zoneA</code>,
	+ because of the fact that the sizo controls file operations and that there
	+ is actually a function within the sizo that requires file access.
	+ Consequently, the example outputs the following:<screen
	+ xml:id="Output_AccControl_1"><?xxe-sn 26yv439af40 3f?>virtualized file access</screen>confirming
	that specifically virtualized specialization of <code><?xxe-sn 26yv439af40 3g?>openFile</code>
	was invoked.</para>
	</section>

	<section>
	<?xxe-sn 26yv439af40 3h?>

	<title><?xxe-sn 26yv439af40 3i?>Isolation</title>

	<para><?xxe-sn 26yv439af40 3j?>As shown in the previous section, it is
	- possible to enable(or disable) virtualization on per resource basis.
	- However such functionality is limited in a sense that if several sizos
	+ possible to enable (or disable) virtualization on a per resource basis.
	+ However, such functionality is limited in a sense that if several sizos
	allow access to the same resource they can interfere with each other.
	Thus, next step to consider is <emphasis><?xxe-sn 26yv439af40 3k?>isolation</emphasis>,
	- i.e. zeks in different sizos should not have ability to access the same
	- resource, but rather work with their own set of resources associated with
	- particular sizo. As previously, following examples are focused on file
	- operations as most ubiquitous type of resources.</para>
	+ i.e. zeks in different sizos should not have the ability to access the
	+ same resource, but rather work with their own set of resources associated
	+ with a particular sizo. The following examples, just as the previous one,
	+ are focused on file operations as the most ubiquitous type of
	+ resources.</para>

	<para><?xxe-sn 26yv439af40 3l?>One way to isolate file access is to
	- associate unique file prefix with each sizo. If virtualization enabled,
	- all filenames in the sizo are silently transformed on the fly by adding
	- assigned prefix. This way, all the file operations from one sizo are
	- confined within specific directory allocated solely for that particular
	- sizo or simply have unique prefix if the same directory contains files
	- belonging to a different sizos.</para>
	+ associate a unique file prefix with each sizo. If virtualization is
	+ enabled, all filenames in the sizo are silently transformed on the fly by
	+ adding an assigned prefix. This way, all the file operations from one sizo
	+ are confined within a specific directory allocated solely for that
	+ particular sizo, or simply have a unique prefix if the same directory
	+ contains files belonging to a different sizo(s).</para>

	<programlisting xml:id="Isolation_1"><?xxe-sn 26yv439af40 3m?>name="tests/virtualization.cpp: Doc_Isolation_1", lines=15
	main = function:: int; entry
	{
	seq
	{
	context:: assign_sizo(domainA);
	assign_sizo_control(files).
	openFile("test")
	}
	{
	context:: assign_sizo(domainA).

	openFile("test")
	}
	{
	context:: assign_sizo(domainB);
	assign_sizo_control(files).
	openFile("test")
	}
	}</programlisting>

	- <para><?xxe-sn 26yv439af40 3n?>In this example file <code><?xxe-sn 26yv439af40 3o?>test</code>
	+ <para><?xxe-sn 26yv439af40 3n?>In this example, the file <code><?xxe-sn 26yv439af40 3o?>test</code>
	is accessed from different sizos <code><?xxe-sn 26yv439af40 3p?>domainA</code>
	- and <code><?xxe-sn 26yv439af40 3q?>domanB</code>. As there are several
	- "competing" sizos are declared, they are isolated and <code><?xxe-sn 26yv439af40 3r?>openFile</code>
	+ and <code><?xxe-sn 26yv439af40 3q?>domanB</code>. As several "competing"
	+ sizos are declared, they are isolated, and <code><?xxe-sn 26yv439af40 3r?>openFile</code>
	resolves <code><?xxe-sn 26yv439af40 3s?>test</code> to a different
	- filename depending on from which sizo it is called. One possible way to
	- implement discussed strategy shown below:</para>
	+ filename depending on which sizo it was called from. One possible way to
	+ implement the discussed strategy is shown below:</para>

	<programlisting xml:id="Isolation_2"><?xxe-sn 26yv439af40 3t?>name="tests/virtualization.cpp: Doc_Isolation_1", lines=15
	import raw ("scripts/cfa/context.lp"). //enable context reasoning
	import raw ("scripts/virtualization/virtualization.lp"). //enable virtualization reasoning
	import raw ("scripts/virtualization/test-Isolation_1.assembly.lp"). //additional configuration

	DictSizo = type slave dict_sizo.
	Sizo = type slave virt_sizo.

	guard:: strategy(direct)
	{
	resolveFilename = function(filename:: string):: string;
	assign_zek_access(files)
	{
	filename
	}
	}

	guard:: strategy(prefix)
	{
	resolveFilename = function(filename:: string):: string;
	assign_zek_access(files)
	{
	dictSizo = intrinsic query("dict_sizo")::[DictSizo].
	sizoId = intrinsic query late("sizo_current"->sizoCurrent:: Sizo):: int;
	demand(sizo)
	{
	loop fold(dictSizo->entry::DictSizo, 0->id):: int
	{
	if(entry[0] == sizoCurrent):: int { entry[1] } else { id }
	}
	}.

	buf = "00"::string.
	seq
	{ sprintf(buf, "%d/%s", sizoId, filename) }
	{ buf }
	}
	}

	openFile = function(filename:: string):: int
	{
	filenameReal = resolveFilename(filename):: string.
	printf("File opened: '%s'%c", filenameReal, 10)
	}</programlisting>

	<para><?xxe-sn 26yv439af40 3u?>Example outputs:</para>

	<screen xml:id="Output_Isolation_1"><?xxe-sn 26yv439af40 3v?>File opened: '0/test'
	File opened: '0/test'
	File opened: '1/test'
	</screen>

	- <para><?xxe-sn 26yv439af40 3w?>In this example function <code><?xxe-sn 26yv439af40 3x?>openFile</code>
	- calls <code><?xxe-sn 26yv439af40 3y?>resolveFilename</code> to find out
	- real filename. It can be said, that <code><?xxe-sn 26yv439af40 3z?>resolveFilername</code>
	+ <para><?xxe-sn 26yv439af40 3w?>In this example, the function
	+ <code><?xxe-sn 26yv439af40 3x?>openFile</code> calls <code><?xxe-sn 26yv439af40 3y?>resolveFilename</code>
	+ to find out the real filename. It can be said that <code><?xxe-sn 26yv439af40 3z?>resolveFilename</code>
	serves as <emphasis><?xxe-sn 26yv439af40 40?>hypervisor</emphasis>
	- dereferencing file pseudonym into real filename. In order to do that,
	- <code><?xxe-sn 26yv439af40 41?>resolveFilername</code> consists of two
	+ dereferencing file pseudonym into a real filename. For this purpose,
	+ <code><?xxe-sn 26yv439af40 41?>resolveFilename</code> consists of two
	specializations: specialization <code><?xxe-sn 26yv439af40 42?>strategy(direct)</code>
	- serves non virtualized environmentб leaving filename without any
	- processing, and the other specialization <code><?xxe-sn 26yv439af40 43?>strategy(prefix)</code>
	- implements resolving strategy by adding sizo-associated prefix to each
	- file. More specifically, unique index is assigned to each sizo and
	- <code><?xxe-sn 26yv439af40 44?>resolveFilename</code> uses the index as
	+ serves the non-virtualized environment leaving the filename without any
	+ processing, while the other specialization <code><?xxe-sn 26yv439af40 43?>strategy(prefix)</code>
	+ implements the resolving strategy by adding a sizo-associated prefix to
	+ each file. More specifically, a unique index is assigned to each sizo, and
	+ <code><?xxe-sn 26yv439af40 44?>resolveFilename</code> uses the index as a
	file name prefix.</para>

	<para><?xxe-sn 26yv439af40 45?>Resolution function <code><?xxe-sn 26yv439af40 46?>resolveFilename</code>
	has only one parameter <code><?xxe-sn 26yv439af40 47?>filename</code>,
	- deriving required prefix from <emphasis><?xxe-sn 26yv439af40 48?>late
	- context</emphasis> associated with particular sizo.</para>
	+ deriving the required prefix from <emphasis><?xxe-sn 26yv439af40 48?>late
	+ context</emphasis> associated with a particular sizo.</para>

	<important>
	<?xxe-sn 26yv439af40 49?>

	<para><?xxe-sn 26yv439af40 4a?>Client code has no way to influence
	- resolving process and force to use unapproved prefix, thus accessing and
	- interfering with files that belong to other sizos.</para>
	+ resolving process and force it to use an unapproved prefix, thus
	+ accessing and interfering with files that belong to other sizos.</para>
	</important>
	</section>

	<section>
	<?xxe-sn 26yv439af40 4b?>

	<title><?xxe-sn 26yv439af40 4c?>Isolation Categories</title>

	- <para><?xxe-sn 26yv439af40 4d?>Every optimization technique applicable
	- only if some specific preconditions are met. Indeed, only general approach
	- can handle general task. However, for practical instances there are always
	- some improvements possible by tailoring to the particular use case
	- specifics and subtle details. In other words, the more information
	- available the more space for improvements is there. And first step on this
	- road is the very ability to express and reason about such additional
	+ <para><?xxe-sn 26yv439af40 4d?>Every optimization technique is applicable
	+ only if certain preconditions are met. Indeed, only a general approach can
	+ handle a general task. However, for practical instances some improvements
	+ are always possible by tailoring to a particular use case specifics and
	+ subtle details. In other words, the more information available, the more
	+ space there is for improvements. And the first step along this road is the
	+ very ability to express and reason about such additional
	information.</para>

	<para><?xxe-sn 26yv439af40 4e?>As a demonstration, in order to improve
	- reasoning to find out optimal virtualization strategy for particular use
	- case, different <emphasis><?xxe-sn 26yv439af40 4f?>sizo
	+ reasoning to find out the optimal virtualization strategy for a particular
	+ use case, different <emphasis><?xxe-sn 26yv439af40 4f?>sizo
	categories</emphasis> can be introduced, as below:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 4g?>

	<listitem>
	<?xxe-sn 26yv439af40 4h?>

	<para><?xxe-sn 26yv439af40 4i?><emphasis><?xxe-sn 26yv439af40 4j?>Inward
	Isolation</emphasis>. The category describes sizo that prohibits
	- access from other sizos to its internal resources, but able to access
	+ access of other sizos to its internal resources, but is able to access
	external resources freely. For example, monitoring and supervision
	- software may have been assigned this type of isolation — freely
	- accesses subordinate zones but can't be influenced from the
	+ software may have been assigned this type of isolation, where it
	+ freely accesses subordinate zones but cannot be influenced from the
	outside.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 4k?>

	<para><?xxe-sn 26yv439af40 4l?><emphasis><?xxe-sn 26yv439af40 4m?>Outward
	isolation</emphasis>. The exact opposite of inward isolation. Allows
	- access from external sizos but is only allowed to use its own internal
	- resources, so no influence to the outside world is possible.
	- Appropriate for various sandboxes and testing environments to run
	- possibly insecure code.</para>
	+ access from external sizos, but is only allowed to use its own
	+ internal resources, so no influence over the outside world is
	+ possible. Appropriate for various sandboxes and testing environments
	+ to run a potentially insecure code.</para>
	</listitem>
	</itemizedlist>

	- <para><?xxe-sn 26yv439af40 4n?>For file operations inward isolation may be
	- implemented as virtualization strategy that requires from
	+ <para><?xxe-sn 26yv439af40 4n?>For file operations, inward isolation may
	+ be implemented as a virtualization strategy that requires from
	<emphasis><?xxe-sn 26yv439af40 4o?>other</emphasis> sizos compulsory usage
	- of file prefixes so no other sizo can access internal data of inwardly
	- isolated sizo. Conversely, outward isolation is compatible with strategy
	- that assigns prefix for this very sizo, so it can in no way access any
	- external data, being at the same time exposed to the outside world for any
	- sizo that have permission to know unique assigned prefix able to access
	- internal data of sizo in question. To put it simply, strategy for these
	- types can be described with following points:</para>
	+ of file prefixes so that no other sizo could access internal data of
	+ inwardly isolated sizo. Conversely, outward isolation is compatible with
	+ the strategy that involves assigning a prefix for this very sizo, so it
	+ can in no way access any external data, being at the same time exposed to
	+ the outside world and any sizo that has a permission to know a unique
	+ assigned prefix able to access the internal data of the sizo in question.
	+ To put it simply, strategy for these types can be described with following
	+ points:</para>

	<itemizedlist>
	<?xxe-sn 26yv439af40 4p?>

	<listitem>
	<?xxe-sn 26yv439af40 4q?>

	<para><?xxe-sn 26yv439af40 4r?>Inward isolation — requires prefixes
	for other sizos.</para>
	</listitem>

	<listitem>
	<?xxe-sn 26yv439af40 4s?>

	- <para><?xxe-sn 26yv439af40 4t?>Outward isolation — requires prefix for
	- itself.</para>
	+ <para><?xxe-sn 26yv439af40 4t?>Outward isolation — requires a prefix
	+ for itself.</para>
	</listitem>
	</itemizedlist>

	<para><?xxe-sn 26yv439af40 4u?>There is an annotation introduced to
	- declare category for the current sizo:</para>
	+ declare a category for a current sizo:</para>

	<synopsis><?xxe-sn 26yv439af40 4v?>SYNTAX:
	assign_sizo_category(inward).
	assign_sizo_category(outward).</synopsis>

	<para><?xxe-sn 26yv439af40 4w?>Consider the example below:</para>

	<programlisting xml:id="IsolationCat_1"><?xxe-sn 26yv439af40 4x?>name="tests/virtualization.cpp: Doc_IsolationCat_1", lines=15
	test = function:: int; entry
	{
	seq
	{
	context:: assign_sizo(zoneA);
	assign_sizo_control(files);
	assign_sizo_category(inward).
	openFile("test1")
	}
	{
	context:: assign_sizo(zoneB);
	assign_sizo_control(files);
	assign_sizo_category(outward).
	openFile("test1")
	}
	}
	</programlisting>

	<para><?xxe-sn 26yv439af40 4y?>There are two sizos declared in the code
	- above. Using reasoning apparatus developed in previous sections, both
	- sizos activate virtualization, for both of them control file resources and
	- both contain <code><?xxe-sn 26yv439af40 4z?>openFile</code> that actually
	- requires file access. However, this time additional bits of information
	- are available, namely <code><?xxe-sn 26yv439af40 50?>zoneA</code> and
	- <code><?xxe-sn 26yv439af40 51?>zoneB</code> declared as inward and
	- outward, respectively. By strategy outlines above, <code><?xxe-sn 26yv439af40 52?>zoneA</code>
	- enables prefix based isolation strategy for <code><?xxe-sn 26yv439af40 53?>zoneB</code>,
	- and <code><?xxe-sn 26yv439af40 54?>zoneB</code> enables isolation for
	- itself as well. As a result, it's enough to virtualize only one
	- zone(<code><?xxe-sn 26yv439af40 55?>zoneB</code>) leaving <code><?xxe-sn 26yv439af40 56?>zoneA</code>
	- to enjoy direct access to file resources. Example output's is shown below,
	- confirming that direct file access is granted for <code><?xxe-sn 26yv439af40 57?>zoneA</code>:</para>
	+ above. Using the reasoning apparatus developed in the previous sections,
	+ both sizos activate virtualization, for both of them control some file
	+ resources and both contain <code><?xxe-sn 26yv439af40 4z?>openFile</code>
	+ that actually requires file access. However, this time additional bits of
	+ information are available, namely <code><?xxe-sn 26yv439af40 50?>zoneA</code>
	+ and <code><?xxe-sn 26yv439af40 51?>zoneB</code> are declared as inward and
	+ outward, respectively. According to the strategy outlined above,
	+ <code><?xxe-sn 26yv439af40 52?>zoneA</code> enables prefix based isolation
	+ strategy for <code><?xxe-sn 26yv439af40 53?>zoneB</code>, and
	+ <code><?xxe-sn 26yv439af40 54?>zoneB</code> enables isolation for itself
	+ as well. As a result, it is enough to virtualize only one zone
	+ (<code><?xxe-sn 26yv439af40 55?>zoneB</code>) leaving <code><?xxe-sn 26yv439af40 56?>zoneA</code>
	+ to enjoy a direct access to file resources. Example outputs are shown
	+ below, confirming that the direct file access is granted to
	+ <code><?xxe-sn 26yv439af40 57?>zoneA</code>:</para>

	<screen xml:id="Output_IsolationCat_1"><?xxe-sn 26yv439af40 58?>File opened: 'test1'
	File opened: '1/test1'
	</screen>
	</section>
	</chapter>
	<?xxe-revisions
	+#2 2019-03-22T19:27:23Z Администратор
	#1 2018-12-18T13:45:06Z pgess
	+1sPEAAABgaQOAIh1gZoaABWFD4NIYW9mYWZzV0lBcmRub9CxaWMnQnknc4QyAQETgT1DM1OCWAEC
	+Yw8zBTMnUxljgUMjDDMGcwVTUyMMM4N7AQEjBFOBVyMFAQEzBxMFMztzDFOBHCMHEwRTCkMSIwVT
	+GzMMIxhDG2OCDyMEMxRTV2MEMwhjJVMG4UMEMxFTBFOCbkMEYwVDCDMIMzdjBFMEQxEzCUMFQ4J3
	+gwSTBWMYEwdTgVUzgxRDD0MWUwpTgQUBAUOCB1MIYykjBTMmc0YjBRMLYy1Tgm5jhB0TDzMgU3Rj
	+DDMWEwVTBUMGUwljCCMHUxozBDMXQyFTKwEBMzpDBkMHcwZDgRtDgWVjhnJjC2MFQ2szBFMZQwUz
	+HzMcQwljE0MdQxtjMDNyUyATCFMEYwhzHVMYYwVzHWMRMwRTYhMHM4E4kwVDB1MYQxAjCVMiEwkz
	+D1MPY4McMx9DG1MGU4IHM2VzC2MGAQFjBVMFYwQTCSMIUwZjHlN5YzUzUkNUEwZTNjMQYwdTB0NC
	+UwxTFhMJUxtDhCBDgTsjBlMEczlTIkNvYwVjDjMEQwUTBGMcQxNTjVdjgQUzHUMEQy6jEwljZ5MQ
	+Uwu9Uy0jDhMFU2sBAhMLUw4BAoMJMyFDBUNcYx1TBDM0UyVDIWMuQ4FXEwdTWzOBHUMHQ4IWYxNz
	+BZMGAQIzJWMcMy+TBnMFQwZzEjMZIwRTYDMKQwYTBGMNgwQjBDMGYwsTBTOBOkMFUx9zEzOCUHMF
	+UyszgQgTBUMGYyMBATOCBVMFQ0MjB2NdEwdDZ2MoM4EMQw9TBBMGU1pDDiMGgwlTdpMEQxBTBmMQ
	+cweDDyMQgxFDgwZTgQNjDRMFEwsTKTOGPTMhQ1BTgh1jLgECMxETBEOBdQEBYyQzbxMIQydTBDMN
	+YwUzDUMekwRzHDOBKACENYM1N4JbmVwRKh2CGYFQWAieLoRev0CEBcQxgySFBoF33kO5cYp5gQIy
	+nCoTM60HEB+6IYIQGJFEijRpJwaBOAmNfROacaR5iTmCfwulc5gbPRWKGQtoXIMAiRobgVmDKoMU
	+zgkZgQgFggzNUDELlQCeI1gvgm+JMnWDZHgNjUilcppIjwaGY5J9CLhFHJhwOSzDCYMr3USBHR+v
	+WYEQhXiJdXSBPZhMOoR8K4EbNCAzYoQ/wlq4SWyBO44YbDnDIhqaTW0/oQyBSB2DShuNbSoTHYMd
	+Ia5gIoILkowgkgCgJIJnzjiHAZIchyIiezhVtERcN4IsoBMgnyyIEKRPj2OEJYQlkhK+EyGBA1yq
	+WW+BTRPJWQ4gFo1cgQmrJiC/PrQ4O6iPNo0sgQiBRNM0P5dNjzlUDZURKGCQOiM2gxBHMM18gWJd
	+jwGBKoIZSUQaJx6xeUZJBollG0EqinnzVRSxWoE9CtdrE6U2gUOBNNaCUy6kWCJ3Ja94gguKG0yb
	+c2loKoERrjeBhSkbXrRxfyp5ep5jF3CxiVFcgmqDCIEFyW65U7RsRIZBJVWCIT6BhR4VgXclqgR5
	+jHerRsQRmCq/aHlsPQ==
	+
	?>
	\ No newline at end of file
	diff --git a/pandoctl b/pandoctl
	index 61a06bf..005ceed 100755
	--- a/pandoctl
	+++ b/pandoctl
	@@ -1,13 +1,13 @@
	#!/bin/bash

	case $1 in
	convert)
	Name=$(basename $2)
	sed -e '/<?xxe-revisions/, /?>/ d' -e 's/<?xxe[^?]*?>//g' $2 \| \
	/opt/pandoc/dist/build/pandoc/pandoc \
	-f docbook \
	-t ./documentation-tools/doc-converter/remarkup.lua \
	- -o /tmp/docs/$Name.remarkup
	+ -o $3/$Name.remarkup
	;;
	- *) echo "usage: $0 convert <SOURCE-FILE>";;
	+ *) echo "usage: $0 convert <SOURCE-FILE> <DEST-FOLDER>";;
	esac
	diff --git a/vendors/coco/generator/Copyright.frame b/vendors/coco/generator/Copyright.frame
	new file mode 120000
	index 0000000..708b5d5
	--- /dev/null
	+++ b/vendors/coco/generator/Copyright.frame
	@@ -0,0 +1 @@
	+/usr/share/coco-cpp/Copyright.frame
	\ No newline at end of file
	diff --git a/vendors/coco/generator/Scanner.frame b/vendors/coco/generator/Scanner.frame
	new file mode 120000
	index 0000000..d1ee132
	--- /dev/null
	+++ b/vendors/coco/generator/Scanner.frame
	@@ -0,0 +1 @@
	+/usr/share/coco-cpp/Scanner.frame
	\ No newline at end of file

No OneTemporaryActions

File Metadata

View Options

Event Timeline

No OneTemporary
Actions