Extend SED-ML beyond XML-based model languages

specification/level-1-version-4/sed-ml-L1V4.tex

@@ -89,7 +89,7 @@ \chapter{Examples}
 \label{app:examples}
 This appendix presents selected SED-ML examples. These examples are only illustrative and do not intend to demonstrate the full capabilities of SED-ML. For a more comprehensive view of the SED-ML features refer to the specification (Chapter~\ref{chp:specification}). 
 
-The presented examples use models encoded in SBML and CellML. SED-ML is not restricted to those formats, but can be used with models encoded in formats serialized in XML (see Section~\ref{sec:languageURI} for more information).
+The presented examples use models encoded in SBML and CellML\changed{, though SED-ML is not restricted to those formats. See} Section~\ref{sec:languageURI} for more information.
 
 All specification examples listed below are available as \hyperref[sec:archive]{Combine Archives} from \url{http://sed-ml.org/} under the \code{*.omex} file name for the respective example. 
 

specification/level-1-version-4/sources/concepts.tex

@@ -210,7 +210,7 @@ \subsection{Language references}
 To help  software decide whether or not it supports a SED-ML description file, the information on the \hyperref[class:model]{model} encoding for each referenced \hyperref[class:model]{model} can be provided through the \hyperref[sec:language]{\element{language}} attribute, as the description of a language name and version through an unrestricted \code{String} is error-prone. 
 A prerequisite for a language to be fully supported by SED-ML is that a formalised language definition, e.g., an XML Schema, is provided online. SED-ML also defines a set of standard URIs to refer to particular language definitions. 
 
-To specify the language a model is encoded in, a set of pre-defined SED-ML URNs can be used (\tab{languageURI}). The structure of SED-ML language URNs is \element{urn:sedml:language:}\emph{\element{name.version}}. SED-ML allows to specify a model representation format very generally as being \code{XML}, if no standardised representation format has been used to encode the model. On the other hand, one can be as specific as defining a model being in a particular version of a language, e.g., SBML Level 3 Version 1 as \code{urn:sedml:language:sbml.level-3.version-1}.
+To specify the language a model is encoded in, a set of pre-defined SED-ML URNs can be used (\tab{languageURI}). The structure of SED-ML language URNs is \element{urn:sedml:language:}\emph{\element{name.version}}. \changed{One} can be as specific as defining a model being in a particular version of a language, e.g., SBML Level 3 Version 1 as \code{urn:sedml:language:sbml.level-3.version-1}.
 
 For additional information see the \hyperref[sec:language]{\element{language}} attribute on \Model.
 
@@ -220,6 +220,7 @@ \subsection{Language references}
 \toprule
 \textbf{Language} & \textbf{URN}\\
 \midrule
+\changed{BNGL (generic) & \code{urn:sedml:language:bgnl}} \\
 CellML (generic) & \code{urn:sedml:language:cellml} \\
 CellML 1.0 & \code{urn:sedml:language:cellml.1\_0} \\
 CellML 1.1 & \code{urn:sedml:language:cellml.1\_1} \\
@@ -379,7 +380,7 @@ \subsection{Annotation Scheme}
 % ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 \section{XPath}  
 \label{sec:xpath}
-\concept{XPath} is a language for finding and referencing information in an XML document \citep{xpath:1999}. Within SED-ML \currentLV, XPath version 1 expressions are used to identify nodes and attributes within an XML representation in the following ways:
+\concept{XPath} is a language for finding and referencing information in an XML document \citep{xpath:1999}. Within SED-ML \currentLV, XPath version 1 expressions \changed{can be used to identify nodes and attributes within an XML representation of an XML-encoded model} in the following ways:
 
 \begin{itemize}
 	\item {Within a \Variable definition, where \concept{XPath} identifies the model variable required for manipulation in SED-ML.}
@@ -397,7 +398,8 @@ \section{XPath}
 
 which will only be interpretable by standard XML software tools if the SBML file declares no namespaces (and hence is invalid SBML).
 
-Following the convention of other \concept{XPath} host languages such as XPointer and XSLT, the prefixes used within \concept{XPath} expressions must be declared using namespace declarations within the SED-ML document, and be in-scope for the relevant expression. Thus for the correct example above, there must also be an ancestor element of the node containing the XPath expression that has an attribute like:
+Following the convention of other \concept{XPath} host languages such as XPointer and XSLT, the prefixes used within \concept{XPath} expressions must be declared using namespace declarations within the SED-ML document, and be in-scope for the relevant expression. Thus for the correct example above, there must also be an ancestor element of the node containing the 
+ssion that has an attribute like:
 \begin{alltt}
 xmlns:sbml=`http://www.sbml.org/sbml/level3/version1/core'
 \end{alltt}

specification/level-1-version-4/sources/data.tex

@@ -106,7 +106,7 @@ \subsubsection{\element{DataSource}}
 
 This represents a change from \LoneVone and \LoneVtwo, in which a \token{taskReference} was always present for a \token{variable} in a \DataGenerator.
 
-To indicate that the \hyperref[sec:target]{\element{target}} of the \Variable is an entity defined within the current SED-ML description (and not an \hyperref[sec:xpath]{Xpath} expression) the hashtag (\#) with the reference to an \hyperref[type:id]{\element{id}} is used. 
+To indicate that the \hyperref[sec:target]{\element{target}} of the \Variable is an entity defined within the current SED-ML description (and not an \changed{entity in an external document, such as referenced by a} \hyperref[sec:xpath]{Xpath} expression) the hashtag (\#) with the reference to an \hyperref[type:id]{\element{id}} is used. 
 
 In addition, this example uses the \hyperref[sec:modelReference]{\element{modelReference}}, in order to facilitate a mapping of the data with a given model. 
 

specification/level-1-version-4/sources/generalElements.tex

@@ -338,7 +338,7 @@ \subsection{\element{Variable}}
 			<listOfChanges>
 				<computeChange target="TARGET ELEMENT OR ATTRIBUTE">
 				<listOfVariables>
-				   <variable id="v1" name="maximum velocity" target="XPath TO MODEL ELEMENT/ATTRIBUTE" />
+				   <variable id="v1" name="maximum velocity" target="\changed{Path} TO MODEL ELEMENT/ATTRIBUTE" />
 				   [FURTHER VARIABLE DEFINITIONS]
 				</listOfVariables>
 				[..]
@@ -364,11 +364,11 @@ \subsection{\element{Variable}}
 % ~~~ TARGET ~~~
 \paragraph*{\element{target}}
 \label{sec:target}
-An instance of \Variable can refer to a model constituent inside a particular \hyperref[class:model]{model} through an \code{\hyperref[type:xpath]{XPath}} expression stored in the \concept{\element{target}} attribute. 
+An instance of \Variable can refer to a model constituent inside a particular \hyperref[class:model]{model} through \changed{the address stored in the \concept{\element{target}} attribute, such as an \code{\hyperref[type:xpath]{XPath}} expression}. 
 
 The \concept{\element{target}} attribute may also be used to reference an entity within the SED-ML file itself, by containing a fragment identifier consisting of a hash character (\code{\#}) followed by the \SId of the targeted element. As of SED-ML \currentLV this is used to refer to a \hyperref[class:dataSource]{DataSource} in a \Variable or to refer to \hyperref[class:listOfRanges]{ranges} within a \hyperref[class:repeatedTask]{repeatedTask} (see Listing~\ref{lst:repeatedTask}).
 
-Note that while it is possible to write \code{\hyperref[type:xpath]{XPath}} expressions that select multiple nodes within a referenced model, when used within a \concept{\element{target}} attribute a single element or attribute \emph{must} be selected by the expression.
+Note that while it is possible to write \changed{addresses} that select multiple nodes within a referenced model, when used within a \concept{\element{target}} attribute a single element or attribute \emph{must} be selected by the expression.
 
 \lsttexta{target}{target}
 In the example the \concept{\element{target}} is used to reference a species with \element{id='PY'} in an SBML model.
@@ -459,7 +459,7 @@ \subsection{\element{RemainingDimension}}
 \subsection{\element{DependentVariable}}
 \label{class:dependentVariable}
 
-The \DependentVariable object is a child of the \Variable class, extending it to include three new attributes:  \element{term} (of type \element{URN}), \element{target2} (of type XPath), and \element{symbol2} (of type URN).  A dependent variable is necessary when the desired variable is a composite of two other variables, such as 'the rate of change of S1 with respect to time'.
+The \DependentVariable object is a child of the \Variable class, extending it to include three new attributes:  \element{term} (of type \element{URN}), \element{target2} (of type Target), and \element{symbol2} (of type URN).  A dependent variable is necessary when the desired variable is a composite of two other variables, such as 'the rate of change of S1 with respect to time'.
 
 In a \DependentVariable, the \element{term} is used to define the relationship of the two variables (i.e. 'rate of change'), the \element{target} or \element{symbol} attributes are used to define the first such variable, and the new \element{target2} and \element{symbol2} is used to define the second variable.  
 

specification/level-1-version-4/sources/introduction.tex

@@ -36,7 +36,7 @@ \section{SED-ML overview}
 \paragraph*{\Model}
 The \Model class allows to reference the models used in a simulation experiment.
 
-The \hyperref[class:change]{Change} class allows to modify models (pre-processing), i.e., changing the value of an observable, computing the change of a value using mathematics, or general changes on any XML element of the model representation that is addressable by \hyperref[sec:xpath]{XPath} expressions, e.g., substituting a piece of XML by an updated one.
+The \hyperref[class:change]{Change} class allows to modify models (pre-processing), i.e., changing the value of an observable, computing the change of a value using mathematics, or general changes on \changed{any element of the model representation that is addressable by an unambiguous target, such as an \hyperref[sec:xpath]{XPath} expression for an entity in an XML-encoded model}, e.g., substituting a piece of XML by an updated one.
 
 \paragraph*{\Simulation}
 The \Simulation class defines the simulation settings and the steps taken during simulation. These include the particular type of simulation, the algorithm, and the algorithm parameters used for the execution of the simulation.