[IVOA /TCG Question] access to VODML documentation of IVOA data models

[Markus Demleitner]

Dear Mireille,

On Tue, Aug 25, 2020 at 07:47:35PM +0200, Mireille LOUYS wrote:
> templated format designed following the VODML specification.
> Currently each RFC wiki page for a recent DM specification inserts in the
> page the link to the volute repository to either the xml VODML description,
> ( xml file) and/or  to the HTML doc (html file) or the repository containing
> both and all the output of the VODML design for this datamodel.
> 
> 
> How can we stabilise the access to these documentation files for the VO
> developers, the VO users, and the community at large ?
> 
> Here is an example for the VODML documentation file for the Provenance DM
> specification that we are currently proposing for uptake to some projects.
> 
> https://volute.g-vo.org/svn/trunk/projects/dm/provenance/ProvDM/vo-dml/Provenance.html

[For later readers: This file was displayed as HTML source]

> My browsers Safari and Chrome cannot recognise the mime-type properly and
> show the plain text instead.

No, they are working fine (at least for this particular problem):
volute was giving them a text/plain content-type.

And that is easily fixed:

$ svn propset svn:mime-type "text/html" Provenance.html
$ svn commit

-- this tells subversion that it should not assume that people want
to see the source (which is its IMHO reasonable default) but that
sufficiently capable clients should try to render the material.

There is still a broken image in there, but that's because the file
is really missing in Volute.

> To summarize:
> - how can we fix this on volute ?
> - how can we define a richer repository where all documents necessary for a
> Data model specification can be accessed when the specification is published
> and recommended ?

First: We shouldn't worry too much about volute or subversion
technicalities; I think it's still the general feeling that we should
migrate to github, and even if the sentiment wrt large,
commercial, arguably adversarial platform changed, I think it's
pretty clear that we would migrate to something git-based on a
relatively short timescale.

Then: I do not think standards should refer to artefacts in version
control systems, and, even more importantly, I would much rather keep
formatted stuff out of VCSes.  In particular with git, having lots of
rendered PNGs in there is going to be really painful all around
(wasting space and bandwidth, having lots of hard-to-reconcile
conflicts, etc).  Please (and that's a general plea) only commit
build results into VCSes if there really is no reasonable alternative
(like, currently, with role_diagram.pdf in ivoatex).

So, if you want the VODML-generated HTML documentation as a constant
artefact (and I'm still not sure that's a clear yes; I wonder if the
documentation pointer shouldn't simply go into the HTML rendering of
the standard itself), I'd say there are two possibilities:

(a) Keep them with the standard.  Ivoatex lets you pack additional
files into the submission archive (AUX_FILES in the Makefile), and
you can link to them from the document, too (the auxiliaryurl macro).
Together with some Makefile rules, I think one could build something
rather unobstructive that would just bake the formatted VO-DML HTML
into the submission to the docrepo, and the files would then sit at
preditable URLs next to the spec.

One seemingly trivial detail I see here: presumably both the spec and
the formatted doc would want to be called Provenance.html (in your
example).  A good solution for this probably also depends on how you
have created your documentation links so far.

(b) Have them somewhere else in the resource hierarchy at ivoa.net.
I've always argued that resolving a DM URI should do content
negotiation and return the HTML by default and the VO-DML if the
right accept header is being passed.  If people think that's a good
idea I'd be happy help out building that.

         -- Markus