dedoc/paragraph_dataset huggingface dataset:
project can reach more than 10.000 different documents.
A not negligible part of such documents are written di-
rectly using a standard word processor, starting from scratch
or from the most similar document written for a different
project. Copy&paste errors, typo and layout mismatch are
frequent causes of low quality document delivery.
Alstom Bologna therefore considered to move to new tools
for writing such documentation aiming at:
• improving the documents quality and timeliness
• giving the possibility to write and verify documents
• sharing different templates and standard chapters through
out specific libraries of content
• having limited impact on final users (authors) way of
These desiderata were fullfilled by implementing a Web-
based environment, called SSE (Smart Structured Editor),
that allows users to easily (i) produce structured content
enriched with some metadata to easy the document tracking
and exploring, and (ii) share content fragments via templat-
ing. SSE authors do not have to deal with with typographic
and presentational aspects but just to focus on content, while
all formatting, quality check and generation of tables and
indexes is demanded to the system.
In the next section, we will introduce the core HTML-
based format developed for the project, called ADF and
strongly based on patterns. In the following one we will
provide more details on the SSE templating mechanisms and
their application to the case-study.
4 ADF: EXPLOITING HTML PATTERNS AND
The main goal of this research was to study the definition
and application of a pattern-based subset of HTML to the
production of technical documents, with particular attention
to templating mechanisms. Actually, the vocabulary is inde-
pendent of specific markup expectations. It can be expressed
in many different markup languages, such as XML, HTML
and even RDF. The HTML serialization was used throughout
the project and will be used here for all the examples.
The vocabulary is built on three key pillars:
• Pattern-based structural and semantic specifica-
tion: each element of the language addresses and de-
scribes precisely one aspect of the document according
to the pattern theory of documents developed by the
authors of this document, and an analysis of the struc-
tural and semantic characteristics of the documents
most frequently used in Alstom.
• Structure reuse: small and big text fragments can be
identified in good documents of the past, extracted
and reused in newer ones so as to generate a complete
library of templates ready to use and reuse. Templates
may be composed of a few words, a few lines, long
portions of documents, and even structures and scaf-
foldings (more details in the following subsection)
• Provenance: each part of the document, from meta-
data to individual fragments, is clearly and unambigu-
ously associated to the moment in time and the actor
that generated it, with a full history of its modifica-
tions in time. This allows to maintain a full tracking
mechanism of the content of the document and who
created it.
The research is rooted in our past research on structural
patterns. We have been investigating how the structure of
digital documents can be segmented into recurring atomic
components, which can be addressed independently and ma-
nipulated for different purposes. Instead of defining a large
number of complex and diversified structures, we identified
a small number of structural patterns that are sufficient to
express what most users need. The two main characterizing
aspects of our patterns are: (i) orthogonality (each pattern
needs to have a specific goal and to fit a specific context) and
(ii) assemblability (each pattern can be used only in some
locations, within other patterns). Patterns allow authors to
create unambiguous, manageable and well-structured docu-
ments and the regularity of pattern-based documents makes
it possible to perform easily complex operations, conversions
and manipulations.
The patterns were used to define RASH, a markup lan-
guage that restricts the use of HTML elements to only 32
elements, and enables one to include also RDF statements.
In addition, it uses the new Digital Publishing WAI-ARIA
Module 1.0 [5] for specifying accessible structural semantics
to the various document parts. It is designed for encoding
scientific articles and already adopted by several conferences
in computer science field. While the framework that has
been developed for RASH includes a native editor for facili-
tating the creation of Web-first articles [15], there are some
peculiarities of the (ALSTOM) technical documentation that
suggested us to fork RASH in a new language called ADF
and to build a native ADF editor.
Basically, an ADF document is a HTML page composed
of three parts:
• metadata providing non-content information about
the document, its context, and the default parameters
used. These metadata are expressed in JSON-LD and
RDF-a and stored within the document itself
• front matter including the front page, and the initial
• the body of the document with the actual content; this
content is fully compliant to RASH, and thus to both
the pattern-theory and HTML
Most details of ADF, especially those related to the AL-
STOM needs, are not relevant for the purposes of this paper.
What is most interesting here is the support for templating
mechanisms provided by ADF.
Expressing and using templates in a ADF
A template in ADF is a fragment of content placed inside
a document but originating elsewhere, and possibly shared
by more than one document. The origin of the template is
called the source, and each document that uses the template
is called a client of the template. The template is composed of
fixed content (received as is from the source and not designed
to be modified) and variable content (parts that are empty
or filled in with default text, and meant to be modified and
customized differently by each client document). Some tem-
plates may have no variable content, and be composed only
of predetermined fixed content not meant for modification
by clients. These can be called formulaic templates.
There is no restriction on the content of templates. This
means that templates can contain anything from whole doc-
uments down to individual words, as well as hierarchies,
tables, lists, figures, etc. Templates can even nest, e.g., when
a variable of a template contains another template. Further-
more, the vocabulary does not prevent fixed content from
modification by the document’s author, unless specifically
prevented from changes through the use of a specific class
(docreadonly)
The HTML representation of a template sees the template
as an instance of a special RDF-a class called, appropriately
enough, “Template”. A template must always be associated
to a subtree, i.e., a single HTML element must contain the
whole template. A very small text fragment is shown below:
<span typeof="Template" property="tpl:source"
content="templateEngine.php?tpl=AlstomName">
Alstom Ferroviaria S.p.A. </span>
The only required property for templates is "tpl:source",
whose value must point to the URI of the source of the tem-
plate, be it a file somewhere, a network service or even a
fragment of the document itself.
Additional attributes associated to a template and not
meant to be displayed, such as the version used, or the author
of the template, can be specified via empty <span> elements,
as shown in the following snippet:
<span property="tpl:version" content="1.0"/>
Figure 1: Overall interface of SSE
Variables are properties of the template. Properties whose
value is inside the content of the element can be directly
modified by the author. Properties whose value is specified
via the content attribute of the element may or may not be
modified depending on the purpose of the variable. Since
each client of the template as its own private copies of the
variables, we need to introduce an identity to the template.
Furthermore, most probably the content of the variable is not
a plain string, but an HTML fragment. This requires explicit
specification of the datatype of the property.
content="templateEngine.php?tpl=AlstomName"
resource="#AlstomName">
Alstom Ferroviaria S.p.A. -
<span property="premise" datatype="rdf:HTML">
Sede di Bologna
Nested templates can be used, but it may become diffi-
cult to associate a property to the correct template. For this
reason, if a template contains another template, both use a
resource attribute and all SPAN elements defining properties
use an about value to point to the correct template.
<p typeof="Template" property="tpl:source"
content="templateEngine.php?tpl=SignatureBlock"
resource="#SignatureBlock">
<span property="tpl:version" content="3.0"
about="#SignatureBlock"></span>
This document is signed in <span
property="location"
about="#SignatureBlock">Bologna</span> on
<span property="date" about="#SignatureBlock">
21 January 2017</span> by
<span property="signee" about="#SignatureBlock">
P. Alberti</span> on behalf of
<span property="onBehalfOf" datatype="rdf:HTML"
about="#SignatureBlock">
<span property="tpl:version" content="1.0"
about="#AlstomName"></span>
<span property="premise" datatype="rdf:HTML"
about="#AlstomName"> Sede di Bologna </span>
The previous code, for instance, shows a template with
identified (id attribute) SignatureBlock that has some prop-
erties (location, date, etc.) and contains another template
called AlstomName. The content attribute contains the URL
where the template content is. In this example the content
is delivered by a php script with a given tpl parameter that
holds the template identifier.
5 WRITING AND SHARING ADF TEMPLATES IN
SSE was built to to help authors create high-quality and
consistent ADF documents and to reduce their effort. Fig. 1
shows the main SSE interface. Note that SSE is a fully Web
application that can be accessed directly via browser, no
further installation is needed.
Figure 2: Template update notification and nested templates
The interface is organized in four areas:
(1) Header: contains information about the user profile
and log on buttons
(2) Project area (left column): allows users to explore
projects, as well as the structure and the history of
the current document.
(3) Template area (right column): allows users to include
templates and fragments in the current document
(4) Document area (editor): the main component of SSE
in which users can write documents
The template area is the most relevant for our purposes.
It contains a list of fragments and templates that can be
included inside the document that is open. The authors of
templates can associate one or more categories to each tem-
plate when creating it (or later on). The user can filter tem-
plates/fragments according to their category. Each project is
configured to use a predefined taxonomy of categories. The
user can also search templates by name. These basic filtering
and search mechanisms, as we will discuss later, still have
some limitations when the number of templates increases;
in fact we are doing some refactoring so as to make it more
scalable.
The icons on the right of each item shows provenance
information about the template (author, modification date
and so on) and a preview of the template content.
To include a template/fragment users can drag & drop the
template in the desired position of the target document. Note
that the section numbering is automatically managed by SSE
after including a template.
Templates can be created or modified directly in SSE and
can be edited like documents. Authorized users can access a
template area that is similar to document one but with pecu-
liar controls to manage content. The left sidebar is different
as users can navigate templates. For convenience, templates
re grouped into two macro-categories that are document