oslc-domains message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: 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: Wed, 28 Nov 2018 09:43:11 -0500
Chet,
This is fine.
But my experience is that trying to update ReSpec generated HTML files
to relative link references from internal SCM files to OASIS document published
files that change with every revision leads to significant extra work and
the potential for errors. I had been doing this for all of the OASIS OSLC
documents (currently 19 different documents that will need to be published
multiple times) and this is difficult for me to sustain. If we can develop
a consistent algorithm that translates SCM file names to published file
names based on domain short name, stage, version and revision, then perhaps
we can update ReSpec to automate this transformation.
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>,
OASIS TAB <tab@lists.oasis-open.org>, Paul Knight <paul.knight@oasis-open.org>,
Ashok Malhotra <malhotrasahib@gmail.com>
Date:
11/27/2018
04:03 PM
Subject:
[oslc-core]
Re: Fw: Guidance on using relative links in OASIS specifications
Sent
by: <oslc-core@lists.oasis-open.org>
Hi Jim,
On this topic, Paul and I talked about
it and I also discussed it with the TAB.
Our consensus is that you should do your
authoring and editing however you find workable; we will do what's needed
to add our structure and metadata as part of our publishing process. Since
you all are working in an easily manipulated, clear text format (Hallelujah),
we should be able to put together a script or two to process the content
expeditiously. Patrick Durusau of the TAB has offered to help with that.
Patrick and Jacques Durand of the TAB
pointed out that the current scheme has been in use going back to 2010,
and that it was the result of several years of debate. The majority of
the content published on docs.oasis-open.orgnow conforms to the directives. We just didn't see a compelling reason
dramatically change existing, established practice, especially where there
are simpler solutions to be had.
So my goal is to make it easy for you
all to work in a way that makes sense while not disrupting current practice.
Let me know if you have any questions
on it.
Best,
/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
----------------
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]