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

[Mireille LOUYS]

Dear Markus, dear tcg members,
to follow up on this I have inserted my comments below.

many thanks, Mireille.

Le 26/08/2020 à 10:48, Markus Demleitner a écrit :
> 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.
ok thanks a lot .
>
> There is still a broken image in there, but that's because the file
> is really missing in Volute.
I will fix this. just have to change the image file name in the html.
>
>> 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
yes , we came to the same conclusion here at CDS , I think.
We would favor solution (b).
Our preference would be to have all standards documents and their 
complementary side documents on ivoa.net, with anchors pointing from the 
spec landing page to all relevant documents together with the ivoa 
specification.

see my example in the next mail .

-- 
--
Mireille Louys,  MCF (Associate Professor)
CDS				IPSEO, Images, Laboratoire Icube
Observatoire de Strasbourg	Telecom Physique Strasbourg
11 rue de l'Université		300, Bd Sebastien Brandt CS 10413
F- 67000-STRASBOURG		F-67412 ILLKIRCH Cedex
Tel: +33 3 68 85 24 34