Archetype documentation using XML + XSLT

[system]

Dear All

After discussions with users and in consideration of the range of platforms now being implemented, it would seem appropriate to move to a multiplatform documentation process for openEHR artefacts. The important specific documentation to consider are for archetypes and templates. It seems prudent to start with the former. An outline is on the wiki below:

http://www.openehr.org/wiki/display/dev/Archetype+to+HTML

What we need is an XSL Script that consumes XML archetypes and produces high quality documents based on a stylesheet that can be altered for different purposes. I would propose that the same HTML be used in all environments and the look and feel is changed only in the stylesheet.

We need somewhere to lodge the proposed and updated XSL scripts and style sheet and a way to make sure we do not have too many people repeating the same work.

Cheers, Sam

(attachments)

[Peter_Gummer1 (Peter Gummer)]

sam.heard signatureSam Heard wrote:

What we need is an XSL Script that consumes XML archetypes ...

Hi Sam,

XSLT is ok in small doses, but it becomes unmaintainable for anything
complex. Other approaches share the advantages claimed at
http://www.openehr.org/wiki/display/dev/Archetype+to+HTML: "It can be used
anywhere and on any platform and should easily allow localisation. Many
people know how to tweak and maintain XSL."

Just about any language these days has XML parsing libraries. Almost any
language would be more maintainable than XSLT (even something as grotty as
Perl). The transforms for XML archetypes would become quite complex, I
imagine, especially with the localisation requirement.

My own experience with XSLT is summarised by the second-last paragraph of
http://lists.xml.org/archives/xml-dev/200103/msg00647.html: '... developers
whom I know are going over the same path with XSLT : "It is cool and
simple - It is cool and complex - It is complex and it does not look cool
for me".'

But why generate the HTML from XML archetypes rather than ADL? There's
already a solid, cross-platform ADL parser. Why not use that?

- Peter

[system]

Hi Peter

I have discussed this at some depth with quite a few people and we do need something that works easily in Java, C#, Eiffel, Python, Ruby. The benefit is that a script that is relatively short and a css will provide a lot of power and local adaptability and be an asset we can share in all these environments. Accessing a component written in another language is always difficult (Eiffel from Java, C# from Eiffel etc) so it makes sense to go down this road. So far we have gone down the coding route and find we have lots of people doing the same thing and keeping it all synchronised and upto date is difficult.

Anyway - lets hear what others say but I think you will find the implementers are pretty keen to work in this way.

Cheers, Sam

Peter Gummer wrote:

(attachments)

[Heath_Frankel3 (Heath Frankel)]

Peter,
The key is that by using XSLT we don't need to use one particular software
component and as you say, everyone can execute an XSLT script in their
chosen environment where the output should be almost the same.

We have done many XSL transformations from AOM XML and they are not as
complex as you might expect. In fact XSLT is designed exactly for this
purpose and does make it relatively simple to do such things. The only
people that think XSLT is complex and unmaintainable are those that are not
use to using XSLT, just like those that are not use to using Effiel, Perl,
etc, everyone has their preferred language. Luckily, there is quite a large
and growing number of developers that are XSLT literate, whether they like
the language or not.

Heath

From: openehr-technical-bounces@openehr.org [mailto:openehr-technical-
bounces@openehr.org] On Behalf Of Peter Gummer
Sent: Wednesday, 16 April 2008 10:18 AM
To: For openEHR technical discussions
Subject: Re: Archetype documentation using XML + XSLT

sam.heard signatureSam Heard wrote:

> What we need is an XSL Script that consumes XML archetypes ...

Hi Sam,

XSLT is ok in small doses, but it becomes unmaintainable for anything
complex. Other approaches share the advantages claimed at
http://www.openehr.org/wiki/display/dev/Archetype+to+HTML: "It can be used
anywhere and on any platform and should easily allow localisation. Many
people know how to tweak and maintain XSL."

Just about any language these days has XML parsing libraries. Almost any
language would be more maintainable than XSLT (even something as grotty as
Perl). The transforms for XML archetypes would become quite complex, I
imagine, especially with the localisation requirement.

My own experience with XSLT is summarised by the second-last paragraph of
http://lists.xml.org/archives/xml-dev/200103/msg00647.html: '...

developers

[Andrew_Patterson]

I agree with Peter that there are times where using XSLT has
made me want to top myself, but I agree with the general
consensus that it is really the only neutral (language, environment)
way of expressing such a transform.

I'm certainly happy to use such an XSLT transform in my software
(as long as I don't have to write it!)

Andrew

[system]

Hi Sam,

I would also like to try out these XSLT scripts.

Besides HTML, we could also transform archetypes (XML) to other formats, e.g. MindMap and PDF using XSLT. HTML and MindMap are good for on-line browsing. PDF is good for print-out and off-line use. Both are needed for a knowledge repository environment.

Cheers,
Rong

[thomas.beale]

Sam Heard wrote:

[Adam_Flinton]

Sam Heard wrote:

Dear All

After discussions with users and in consideration of the range of
platforms now being implemented, it would seem appropriate to move to
a multiplatform documentation process for openEHR artefacts. The
important specific documentation to consider are for archetypes and
templates. It seems prudent to start with the former. An outline is on
the wiki below:

http://www.openehr.org/wiki/display/dev/Archetype+to+HTML

What we need is an XSL Script that consumes XML archetypes and
produces high quality documents based on a stylesheet that can be
altered for different purposes. I would propose that the same HTML be
used in all environments and the look and feel is changed only in the
stylesheet.

We need somewhere to lodge the proposed and updated XSL scripts and
style sheet and a way to make sure we do not have too many people
repeating the same work.

A) I have done a complete publishing mechanism based on XSLT & ANT & was
wondering how come I could not create the HTML as part of this process.

B) Hurrah.

C) I could help as I have a fairly good grasp on XML Archetypes now
despite my differences wrt their structuring/design.

Adam

[Adam_Flinton]

Peter Gummer wrote:

sam.heard signatureSam Heard wrote:

What we need is an XSL Script that consumes XML archetypes ...
    
Hi Sam,

XSLT is ok in small doses, but it becomes unmaintainable for anything
complex. Other approaches share the advantages claimed at
http://www.openehr.org/wiki/display/dev/Archetype+to+HTML: "It can be used
anywhere and on any platform and should easily allow localisation. Many
people know how to tweak and maintain XSL."

Just about any language these days has XML parsing libraries. Almost any
language would be more maintainable than XSLT (even something as grotty as
Perl). The transforms for XML archetypes would become quite complex, I
imagine, especially with the localisation requirement.

My own experience with XSLT is summarised by the second-last paragraph of
http://lists.xml.org/archives/xml-dev/200103/msg00647.html: '... developers
whom I know are going over the same path with XSLT : "It is cool and
simple - It is cool and complex - It is complex and it does not look cool
for me".'

But why generate the HTML from XML archetypes rather than ADL? There's
already a solid, cross-platform ADL parser. Why not use that?

What happens if/when XML archetypes become the norm? Are you seriously
considering going XML > ADL > HTML?

Adam

[Adam_Flinton]

Heath Frankel wrote:

Peter,
The key is that by using XSLT we don't need to use one particular software
component and as you say, everyone can execute an XSLT script in their
chosen environment where the output should be almost the same.

We have done many XSL transformations from AOM XML and they are not as
complex as you might expect. In fact XSLT is designed exactly for this
purpose and does make it relatively simple to do such things. The only
people that think XSLT is complex and unmaintainable are those that are not
use to using XSLT, just like those that are not use to using Effiel, Perl,
etc, everyone has their preferred language. Luckily, there is quite a large
and growing number of developers that are XSLT literate, whether they like
the language or not.

This is why I built the publishing system in Ant + XSLT. You could
change it to NANT is a dotnetty type or you could rewrite the ant
scripts in perl etc all the while w/o changing the real analysis code
which is in XSLT.

Adam

[system]

Adam

Heath Frankel has developed a proposal for a new version of the XML (the first was a straight serialisation of the AOM) which makes it a lot tidier. The ARB will be reviewing this at some point. It would be good to get a few opinions sooner rather than later.

Sistine Barretto will contribute as well. I think it would be good to have this as an openEHR project - documentation of artefacts.

Cheers, Sam

Adam Flinton wrote:

(attachments)

[Adam_Flinton]

Thomas Beale wrote:

Sam Heard wrote:

Hi Peter

I have discussed this at some depth with quite a few people and we do
need something that works easily in Java, C#, Eiffel, Python, Ruby.
The benefit is that a script that is relatively short and a css will
provide a lot of power and local adaptability and be an asset we can
share in all these environments. Accessing a component written in
another language is always difficult (Eiffel from Java, C# from
Eiffel etc) so it makes sense to go down this road. So far we have
gone down the coding route and find we have lots of people doing the
same thing and keeping it all synchronised and upto date is difficult.

well, to be fair, C-based languages talk to each other;

Java doesn't talk to any other compiled language easily,

??? Ummm...that's a surprise seeing how things like our schema checker
calls out to a variety of engines including the MS one. Gee I must be
like a bumblebee.

& then there's SWT etc.etc.etc.

Usually the problem with apps like that is that the designers never
intended for them to be called on by outside processes & that's the case
whether you're writing the outside app in C, Java or Bash.

but nearly everything can call a script, because it is an operating
system call. My take on this from experience would be:*
*

    * everything, no matter how trivial you think it will be to start
      with, will get much more complex due to people wanting it to do more

    * complexity = pain, in a language with weak semantics
    * complexity = maintenance

I have in the past written various PERL scripts that quickly became
larger than I originally expected. PERL is powerful, but almost
unreadable (without total discipline and an amazing memory, and
possibly a background in deciphering egyptian hieroglyphics)....in the
end it has always become a maintenance problem, and every time I have
chosen what seems to be an easy option, I have regretted it.

Others will be more involved in this than me, so I won't comment
further, other than to say: think very carefully about maintainability!

XSLT requires design not different from anything else.

Use the unix app mentality i.e. that a given script does one job well &
then have a number of scripts & alles will be in ordnung.

e.g. wrt the publishing mech you have:

D:\Data\Java\workspaces\3.3\PublishArchetypes\PublishOpenEHR\xslt>ls
BranchReport.xslt ProduceReport1.xslt
processADLFileList.xslt
CombineBranchFileLists.xslt Release.xslt processFileList.xslt
CommonReportTemplates.xslt ValidateAndFileList.xslt setTextAsVal.xslt
ProcessArchetypes.xslt Xhtml-reports test
ProcessTemplates.xslt identity.xslt
ProduceReport.xslt

Where each script has a specific job.

e.g. in the above Xhtml-reports folder you then have:

D:\Data\Java\workspaces\3.3\PublishArchetypes\PublishOpenEHR\xslt\Xhtml-reports>
ls
ArtefactList.xslt Dependencies.xslt Errors.xslt TypesFolders.xslt
ChangeHistory.xslt Doc.css Orphans.xslt UsedBy.xslt
CommonTemplates.xslt DraftInRelease.xslt Template.xslt filterErrors.xslt

etc.

Equally my XSLT which turn HL7V3 mif into SVG are organized :

D:\Data\Java\workspaces\3.3\xmlprocess\Applications\MifTVJSF\xslt\svg>ls
ClassElements.xsl MIF2SVGGenerator.xsl TextElements.xsl
CommonTemplates.xsl MIF2SVGProcessor.xsl lineintersect.xslt
CreateSortedMifAttributes.xsl MIFV1Processor.xsl sortedMifClassAtts.xml
MIF2SVG.css MiscElements.xsl

As I have built it in the expectation of Mif version 2 & indeed v2.1
v2.2 etc.

I have a horror of being handed vast XSLT scripts which have been
created in the same way as the earth i.e. through steady accretion.

Adam

[Adam_Flinton]

Sam Heard wrote:

Adam

Heath Frankel has developed a proposal for a new version of the XML
(the first was a straight serialisation of the AOM) which makes it a
lot tidier. The ARB will be reviewing this at some point. It would be
good to get a few opinions sooner rather than later.

Sistine Barretto will contribute as well. I think it would be good to
have this as an openEHR project - documentation of artefacts.

Cheers, Sam

I am trying to get my publishing mechanism out into OSS-land probably
via the OHT.

I have got my XML/XSLT/XForms engine out & I would like to get the
publishing mech & the (JSF+EJB3) vocab server out too.

Adam

[Adam_Flinton]

Sam Heard wrote:

Dear All

After discussions with users and in consideration of the range of
platforms now being implemented, it would seem appropriate to move to
a multiplatform documentation process for openEHR artefacts. The
important specific documentation to consider are for archetypes and
templates. It seems prudent to start with the former. An outline is on
the wiki below:

http://www.openehr.org/wiki/display/dev/Archetype+to+HTML

What we need is an XSL Script that consumes XML archetypes and
produces high quality documents based on a stylesheet that can be
altered for different purposes. I would propose that the same HTML be
used in all environments and the look and feel is changed only in the
stylesheet.

We need somewhere to lodge the proposed and updated XSL scripts and
style sheet and a way to make sure we do not have too many people
repeating the same work.

Oh & one quick ancillary question ....

Does this/ Would this include Template (.oet) > XHTML via XSLT?

Adam

[thomas.beale]

Adam Flinton wrote:

[thomas.beale]

Adam Flinton wrote:

XSLT requires design not different from anything else.

Use the unix app mentality i.e. that a given script does one job well &
then have a number of scripts & alles will be in ordnung.
  

this is certainly the way to go alright. It does mean you need decent
shell and/or other glue languages like make or Ant or whatever, but unix
is good at that.

- thomas beale

[thomas.beale]

Adam Flinton wrote:

Oh & one quick ancillary question ....

Does this/ Would this include Template (.oet) > XHTML via XSLT?

*Adam,

The current (simple) .oet XML format for templates will soon be replaced
with a proper openEHR XSD (also simple) which is more based on the AOM,
and hence the AOM XSD, plus a converter. Turning this into HTML can be
done however suits - better re-use of code from various archetype ->
HTML conversions should be possible.

- thomas

[erik.sundvall]

Hi!

ADL and XML

[...removed a load of XML-bashing from the man with a brain-integrated
ADL-parser ...]

ADL can be guaranteed as 100% correct all the time, and are the mathematical
reference form of archetypes

Actually I would prefer more emphasis on the view that the AM is the
main reference and that ADL is a serialization of it. But a "reference
form" of individual _archetypes_ needs a serialization not just an
object model of course...

No matter how nice and pure ADL might be, I have seen people getting
suspicious of "this OpenEHR-thing" when ADL has been focused too
strongly. (Or people getting upset by having to learn yet another
language, alternatively having been put of by the idea of having to
write an ADL parser in a new environment.) It's wonderful that there
are now two "official" ways (ADL and XML) to serialize AM constructs,
having even more would probably not hurt.

Thomas Beale wrote:

Interesting links:
http://www.json.org/xml.html

For some months I have been wanting to experiment with making a simple
JSON implementation of the AM (and eventually also the RM) as a
compact javascript- and Flash/Flex-friendly alternative to ADL/dADL
and then submit it as an ITS for openEHR. I realize I won't have the
time for it though so I drop the idea here hoping that someone else
gets inspired.

Links
http://www.json.org/
http://groups.google.com/group/json-schema (You'd probably want a
schema in the ITS)
http://www.jspon.org/ (Not sure if you need the power of JSPON. The
built in name/path mechanisms of the AM/RM might be enough.)

Anybody interested?

Best regards,
Erik Sundvall
erisu@imt.liu.se http://www.imt.liu.se/~erisu/ Tel: +46-13-227579

[thomas.beale]

Erik Sundvall wrote:

Hi!

Actually I would prefer more emphasis on the view that the AM is the
main reference and that ADL is a serialization of it. But a "reference
form" of individual _archetypes_ needs a serialization not just an
object model of course...
  

The AOM is indeed intended as the definitive model of an archetype.
However it is currently lacking in a few small areas - the
ARCHETYPE_ONTOLOGY class needs some additional items for example. But in
terms of explanatory power, object models are often not the best
representation; they show a parser-output view. Syntax shows a
parser-input view, and we humans are parsers (i.e. we read things
serially). This is why we represent mathematics, java code, OWL, EBNF
and many other things in the form of syntax.

By definition, an syntax is a 'serialisation' of its object model. But I
don't think we can see all syntaxes as being the same. There is an
OWL-RDF syntax for OWL, but it is unreadable gibberish, so humans
usually read OWL-abstract. Similarly, Java programmers use the Java
language rather than some XMI-like syntax. Syntaxes designed primarily
for data serilialisation are not necessarily any good for human use,
including comprehension, explanation of principles and therefore
education. Most XML is of the latter kind - a direct serialisation of
some object model. But you can't read it and understand it in the way
that you can an abstract syntax (if anyone doubts this, just try reading
OWL-RDF or XMI sometime).

No matter how nice and pure ADL might be, I have seen people getting
suspicious of "this OpenEHR-thing" when ADL has been focused too
strongly. (Or people getting upset by having to learn yet another
language, alternatively having been put of by the idea of having to
write an ADL parser in a new environment.) It's wonderful that there
are now two "official" ways (ADL and XML) to serialize AM constructs,
having even more would probably not hurt.
  

there are also at least 2 open source parsers available. In an ideal
world we would have just used an existing language, but none of the
candidates proved up to the job. OWL probabaly comes closest., but still
lacks some basic constructs that prevent it being easily usable for
archetypes.

The power of ADL is important to me now as I am in the midst of defining
extensions and semantics for specialisation. I originally thought I
would do it directly as an object model, but found I had to go back to
ADL to understand the semantics properly; changing / enhacing object
models will come as a largely derivative step.

Thomas Beale wrote:
  

Interesting links:
http://www.json.org/xml.html
    
For some months I have been wanting to experiment with making a simple
JSON implementation of the AM (and eventually also the RM) as a
compact javascript- and Flash/Flex-friendly alternative to ADL/dADL
and then submit it as an ITS for openEHR. I realize I won't have the
time for it though so I drop the idea here hoping that someone else
gets inspired.

I think this is an excellent idea, and it would make a very useful ITS.

- thomas beale

[Adam_Flinton]

Other limitations on using XML - it's a no-show for enterprise scale databases
or information processing. All that wasted space starts to count when you have
to buy two £20,000 high availability RAID disk arrays instead of one....and plus
the bandwidth wastage when there are millions of messages rather than just a
few. Yes, binary compression helps, but it just shifts disk and bandwidth loss
to the CPU. There are many better ways to represent data for large-scale
deployments than XML (even the dADL syntax from ADL does 100% better in space,
and represents all object-oriented constructs unambiguously).
  

You have got to be kidding me on this one.

Having done XML messaging in very large retail systems (major
supermarket chains in the EU & US), mobile phone systems, home
office/criminal justice system & now the CFH....you simply have got to
be kidding.

ummmmmm.......where to even start....oh yes how about...

"XML is a very commonly used standard with thousands of tools in
existence from routing engines, to processing engines to parsers to
database layers ...."

or maybe

"XML is THE standard in enterprise level messaging systems with
standards such as SOAP, EbXML, OAGI BODS etc.etc."

or maybe :

"XML integrates easily with existing web infrastructures by use of such
mechanisms as AJAX, Rest JSON etc".

Now wrt ADL.....

Adam