oslc-domains message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [oslc-domains] Re: [oslc-core] Re: Fw: Guidance on using relative links in OASIS specifications
- From: "Jim Amsden" <jamsden@us.ibm.com>
- To: Chet Ensign <chet.ensign@oasis-open.org>
- Date: Mon, 22 Oct 2018 14:44:33 -0400
I would suggest removing the parts directories,
and renaming the files to be part1-overview.html, part2-discovery.html,
etc. This removes more redundancy from the path names, the part appears
twice, in the folder and in the file name. The part folders currently only
contain the .html and .pdf files. Since those file names don't clash, then
they can all be in the same oslc-core/cs03/folder.
Note that the PDF files will link to
the related HTML document unless they are processed to rename *.html to
*.pdf, and we'd have to be sure PDF support relative links with fragment
identifiers.
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
From:
Chet Ensign <chet.ensign@oasis-open.org>
To:
Jim Amsden <jamsden@us.ibm.com>
Cc:
"OSLC Core TC
(oslc-core@lists.oasis-open.org)" <oslc-core@lists.oasis-open.org>,
OASIS OSLC Domains TC Discussion List <oslc-domains@lists.oasis-open.org>,
Paul Knight <paul.knight@oasis-open.org>
Date:
10/22/2018 02:24 PM
Subject:
[oslc-domains]
Re: [oslc-core] Re: Fw: Guidance on using relative links in OASIS specifications
Sent by:
<oslc-domains@lists.oasis-open.org>
But how does that work with the parts directories? dialogs.html,
discovery.html, etc. are all in separate directories.
On Mon, Oct 22, 2018 at 2:17 PM Jim Amsden <jamsden@us.ibm.com>
wrote:
Chet,
Its pretty simple. Consider OSLC Core multi-part specifications. There's
lots of cross links between the specifications as they are all related
capabilities of a whole. If the repo and published file names are just
the files: attachments.html, core-vocab.html, dialogs.html, discovery.html,
oslc-core.html, etc. then all the relative links are things lik <a href=""
Discovering Dialogs</a>. These links would work as long as the files
are all published in the same parent directory, and retain their file name.
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
From: Chet
Ensign <chet.ensign@oasis-open.org>
To: Jim
Amsden <jamsden@us.ibm.com>,
Paul Knight <paul.knight@oasis-open.org>
Cc: "OSLC
Core TC (oslc-core@lists.oasis-open.org)"
<oslc-core@lists.oasis-open.org>,
OASIS OSLC Domains TC Discussion List <oslc-domains@lists.oasis-open.org>
Date: 10/22/2018
02:09 PM
Subject: [oslc-core]
Re: Fw: Guidance on using relative links in OASIS specifications
Sent by: <oslc-core@lists.oasis-open.org>
Hi Jim - would you mind sending us some examples of the relative links
you want to maintain? It isn't clear to us how you'd construct the relative
links given that the variable information is built into the URL path.
Thanks - also taking this forward to the TAB and the Board Process Committee
for discussion.
/chet
On Thu, Oct 18, 2018 at 11:37 AM Jim Amsden <jamsden@us.ibm.com>
wrote:
Chet, any update on this? We're looking to finish up changes to the 7 part
OSLC Core specs and they have quite a few relative links that will either
be broken, or will require manual updates when published to the OASIS document
repository.
I think the primary issue is that we can't use relative links because the
file names get changed when the documents are published. For example,
OSLC Core Vesion 3.0. Part 1: Overview Committee Specification revision
03 has published URL:
http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part1-overview/oslc-core-v3.0-csprd03-part1-overview.html
However, the actual file name in the GitHub repo is simply oslc-core.html.
Perhaps OASIS could consider changing the naming guidelines to not put
variable information like version, revision number and document status
in the published file name. This should be unnecessary because it is also
included in the path and results in variable but redundant information.
In the URL above, oslc-core-v3.0-csprd03-part1-overview.html
is redundant with oslc-core/v3.0/csprd03/part1-overviewin
the path. If this redundancy could be eliminated, then the file name would
be unchanged when published, and all relative links would work fine.
If you would like to consider this, we could certainly change the names
of the files to better reflect their title and part.
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
----- Forwarded by Jim Amsden/Raleigh/IBM on 10/18/2018 11:28 AM -----
From: Jim
Amsden/Raleigh/IBM
To: "Chet
Ensign" <chet.ensign@oasis-open.org>
Cc: "OSLC
Core TC (oslc-core@lists.oasis-open.org)"
<oslc-core@lists.oasis-open.org>,
oslc-domains@lists.oasis-open.org
Date: 10/04/2018
11:44 AM
Subject: Guidance
on using relative links in OASIS specifications
Chet,
The OASIS OSLC Specifications contain numerous URL references across the
multi-part specifications. For example, the OSLC Core Specification has
links to its vocabulary document. Many of these links include fragment
identifiers to link to specific document sections.
<p class='conformance'>OSLC Servers MUST implement the OSLC
Core vocabulary as defined in <a href="">http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part7-core-vocabulary/oslc-core-v3.0-csprd03-part7-core-vocabulary.html">OSLC
Core Version 3.0. Part 7: Vocabulary</a>.</p>
The issue is what to use for stable URIs for these references. We cannot
use the file names in the git repository because these do not correspond
to the published files. As can be seen from the example above, the actual
OASIS published file names correspond to OASIS file naming guidelines,
and include document status and revision numbers in the file and path names.
So these file names do not provide stable URIs. Each document does have
a stable URI that references the latest published version. For example,
http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/oslc-core-v3.0-part7-core-vocabulary.htmlis
the URI for the latest version of the OSLC Core Vocabulary specification.
If we use these to construct the relative URIs, then we have two problems.
First, when developing the specifications, the relative links would not
work between resources in the git repository. Second, when browsing a particular
revision of an OSLC specification, a reader clicking on one of these links
may be viewing a different version of the related specification, the latest
version.
We could avoid direct href references in the HTML and always link indirectly
through a bibliography entry. However, this would provide a poor user experience
when viewing the HTML documents, and doesnât support fragment identifiers.
What is the OASIS recommended approach for dealing with relative links
between documents?
Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575
--
/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org
Primary: +1 973-996-2298
Mobile: +1 201-341-1393
--
/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org
Primary: +1 973-996-2298
Mobile: +1 201-341-1393
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]