dedoc/paragraph_dataset huggingface dataset:
alessandro.caponi@unibo.it
Angelo Di Iorio
angelo.diiorio@unibo.it
Fabio Vitali
fabio.vitali@unibo.it
Paolo Alberti
paolo.alberti@alstomgroup.com
Marcello Scatá
marcello.scata@alstomgroup.com
There are several domains in which the documents are made
of reusable pieces. Template languages have been widely
studied by the document engineering community to deal
with common structures and textual fragments. Though, tem-
plating mechanisms are often hidden in mainstream word-
precessors and even unknown by common users.
This paper presents a pattern-based language for tem-
plates, serialized in HTML and exploited in a user-friendly
WYSIWYG editor for writing technical documentation. We
discuss the deployment of the editor by an engineering com-
pany in the railway domain, as well as some generalized
lessons learned about templates.
• Information systems→ Collaborative and social comput-
ing systems and tools; Digital libraries and archives;
Collaborative editing, HTML, Technical documentation, Tem-
Alessandro Caponi, Angelo Di Iorio, Fabio Vitali, Paolo Alberti,
and Marcello Scatá. 2018. Exploiting patterns and templates for
Permission to make digital or hard copies of all or part of this work for
personal or classroom use is granted without fee provided that copies
are not made or distributed for profit or commercial advantage and that
copies bear this notice and the full citation on the first page. Copyrights
for components of this work owned by others than the author(s) must
be honored. Abstracting with credit is permitted. To copy otherwise, or
republish, to post on servers or to redistribute to lists, requires prior specific
permission and/or a fee. Request permissions from permissions@acm.org.
© 2018 Copyright held by the owner/author(s). Publication rights licensed
to ACM.
https://doi.org/10.1145/3209280.3209537
technical documentation. In DocEng ’18: ACM Symposium on Doc-
ument Engineering 2018, August 28–31, 2018, Halifax, NS, Canada.
ACM, New York, NY, USA, 9 pages. https://doi.org/10.1145/3209280.
3209537
1 INTRODUCTION
HTML has become the beginning and end of markup needs.
With CSS, microformats, microdata and structural classes it
handles all the things for which XML was designed at the
beginning.
What is not yet completed in HTML is the support for
a fourth dimension of markup, that of the authoring and
processing control (that we call APC): for instance informa-
tion about change tracking, reuse of fragments from other
documents, authorship attribution are not yet expressed in a
straightforward and widely shared way.
In this paper we focus on fragments’ reuse and templates,
and we investigate a pattern-based approach for handling
and embedding such information in HTML. The context in
which we experimented our approach is the production of
industrial design documents. In that domain, the structure of
the documents is pretty much established at the beginning of
a project and repeated, typographical autonomy is disdained,
and semantics identification is of limited usefulness. On the
other hand, the control of authoring and processing events
is very important as well as the control of reusable content.
This work follows our previous research on patterns [6]
and HTML as language for writing specialized documents
[11]: we started focusing on scientific articles and now we
also work on technical documentation. We propose a HTML-
based format, called ADF, able to express APC information
and an editor, called SSE, that includes modules for automatic
generation of content, numbering and document structures,
and sophisticated mechanisms for templating and prove-
nance characterization. We also introduce the PDX library
DocEng ’18, August 28–31, 2018, Halifax, NS, Canada Caponi et al.
of DOM extensions for handling automatic behaviors, on top
of which SSE was built.
We applied this approach successfully in an engineering
domain with the help of an important multi-national com-
pany in the railway domain. The paper also describes this
case-study, starting from its specific needs and moving to
possible generalizations of the overall approach.
It is then structured as follows. Section 2 discusses how
HTML has been used in practice for expressing authoring
information and, in particular, templating data. Section 3
describes our case-study, while our approach, format and
tools are presented in Section 4. Discussions and conclusions
are drawn in Section 6.
2 RELATED WORK
HTML has been increasingly gaining centrality in markup
languages, up to take over XML in several cases. Related tech-
nologies and standards make it possible to do a lot of things
directly in HTML: CSS let designers create high-quality doc-
uments even for printing (instead of using XSL-FO), RDFa
and Microformats embed data for automatic processing and
reasoning by software agents, structural classes for DIV and
SPAN associate presentation and dynamic behavior to single
elements, that are finally delivered though JS frameworks.
Particular relevant to our work are some efforts in using
HTML for expressing data about the authoring and process-
ing of content (APC, Authoring and Processing Control). In
particular, we focus on solutions to handle change-tracking
and templating. The same specifications of HTML include
the elements INS and DEL to respectively indicate the inser-
tion and the deletion of a piece of content. These elements
are very generic and are meant to be applied to modifications
of entire subtrees, text fragments or mixed structures. Their
usage is not totally precise: for instance, the deletion of an
item in a list (LI element) has to be expressed as the deletion
of the content of the item instead of the item itself.
The controlled inclusion of content is a further example of
APC. Very basic mechanisms are provided in HTML with the
element OBJECT: the content is included dynamically in the
rendered page but very little information is available about
provenance and the connection with the included content is
rather weak.
Muchmore sophisticated inclusionmechanisms have been
studied by hypertext and document engineering experts.
For instance, researchers proposed to allow for permanent
connections between the included content and its original
source. A very common scenario, implemented by hot-links
and warm-links in the early days of hypermedia [17] and
re-proposed by the W3C standard XLink [14] in the@show
and @actuate attributes, shows that changes in the source
fragment are automatically propagated to all those including
it. That is very useful to include real-time information such
as news and can be adapted to HTML content too. Similarly,
XInclude [9] provides a general and standard solution for
inclusions in XML settings that can be applied to HTML.
These mechanisms are actually rooted in the early days of
the hypertext research. The pioneer Xanadu [12] was meant
to be a shared workspace where users could freely link, edit
and reuse text fragments.
The key concept of Xanadu were the transclusions, i.e.
permanent and live inclusions of content. The original idea
of transclusions has been implemented in different forms
over the years and is still an active topic for the community.
For instance, Wikipedia supports basic transclusion mecha-
1 nisms : entire articles or sections can be included from one
wiki page to another. Differently from the original idea, the
link is not locked to a particular version of the transcluded
content. The most recent version is always included. The
adoption of these mechanisms, however, is still limited as
confirmed by [1]. The authors studied the writing habits of
Wikipedia editors in order to identify which transclusions
are used and to which degree, digging into a collection of 20
million articles. They concluded that the editors still have dif-
ficulties in understanding and exploiting transclusions, due
to the fragmented and incomplete documentation, as well as
the cognitive overhead of complex and nested transclusions.
The system presented in [3] allows users to build com-
posite e-books and is based on an interesting classification
of transclusions in three different types as proposed by [2],
which made a distinction between Trans-quotations, Trans-
references and Trans-annotations depending on the rights of
reproducing and distributing the transcluded content. The
e-books are composed of chunks of content permanently
linked to the original source: if there is an updated version,
the system downloads it and updates the document appro-
priately. The overall system relies on a customized metadata
schema that describes the relations between the transcluded
fragments and their provenance.
Some forms of transclusions were also proposed to allow
users to collect any content from theWeb. In [10] the authors
introduced the idea of partial bookmarking and extended a
Web browser so as to let users collect portions of any web
page and to combine them into new documents shown in
a different tab. The environment can be used for reading
multi-source content but does not allow users to re-publish
It is also worth mentioning here a totally different use of
transclusions: in [8] the authors proposed an open-source
and cross-platform technology, called Auckland Interface
Model (AIM), that allows designers to build GUIs decompos-
ing them by using the transclusion metaphor. AIM separates
GUI layout, GUI content and GUI data, and enables end-users
1https://en.wikipedia.org/wiki/Wikipedia:Transclusion
Exploiting patterns and templates for technical documentation DocEng ’18, August 28–31, 2018, Halifax, NS, Canada
to treat GUIs as documents. Such an approach proved to be
beneficial for GUI developers and users, facilitating reuse
and consistency.
The annotation of text fragments, not only for transclu-
sions but for any automatic processing, has become reality
for HTML with the diffusion of Microformats and Micro-
data. Microformats are small patterns of HTML to represent
common things like people, events, reviews, tags and so on.
Microdata extends HTML, by introducing some new general-
purpose properties, and can be used together with several
vocabularies like Schema.org.
Alternative proposals have also been studied by the aca-
demic community. To overcome some limitations of micro-
formats in terms of flexibility and editing difficulties, [13],
[4] presented a language for semantic embedding in HTML,
called XTiger, and an editing tool working on that language
that makes the authoring process easier and safer. In fact,
the tool uses descriptions expressed XTiger to help authors
to produce valid semantically-annotated content. Several
other editors for semantic content have been proposed by
researchers and professionals, see [7] for more details.
3 REUSING CONTENT FOR TECHNICAL
DOCUMENTS: A CASE-STUDY
The production of semantically-annotated content in HTML,
in particular that of authoring and processing control, has
been widely studied in the literature but is still deployed in
a limited manner in mainstream applications.
This research, in fact, started from an analysis we did on
methods and tools for writing documentation for engineer-
ing projects. These projects often require stakeholders to
produce a of documents. Some of these are rigidly structured
and composed of well-defined items that can be assembled
and delivered into the final document: this is the case, for
instance, of manuals associated to products and machines.
These are handled by specialized tools that are very effective,
and characterized by peculiar difficulties, editing patterns
and approaches [16].
These are many other documents which are equally im-
portant but difficult to be written by following the same ap-
proach and using the same tools. Some examples are: notes,
documentation for tenders, business plans, quality plans,
legal notices and so on. These are often made of common
pieces that are simply copied&pasted across documents, due
to the lack of mainstream effective tools supporting such a
reuse.
This also happened in our case-study. Alstom is a multina-
tional company operating worldwide in rail transport mar-
kets, active in the fields of passenger transportation, sig-
nalling and locomotives. The Alstom site at Bologna (Italy),
center of excellence for the signalling technology, is involved
in a lot of projects (national and international) producting a
huge number of documents for each project. A medium size
project has a documentation master list of around 1.000 doc-
uments, while the documentation master list of a complex