Re: [oslc-domains] Re: [oslc-core] Re: Fw: Guidance on using relative links in OASIS specifications

["Jim Amsden" <jamsden@us.ibm.com>]

Chet,
I'm happy to join
a call and demonstrate ReSpec. I have also developed some notes on ReSpec
changes needed to follow OASIS naming guidelines when generating HTML snapshots
for publishable documents.

The issue isn't
to bad with single-part specifications. The problem here is that the file
name in GitHub does not correspond to the [doc-id] file name when published.
But most relative links in a single-part specification can use <a href=""
references which do work fine since they are document relative. for example,
for OSLC Query, the GitHub URI is https://github.com/oasis-tcs/oslc-core/blob/master/specs/oslc-query.htmlwhile the CSPRD01 document is http://docs.oasis-open.org/oslc-core/oslc-query/v3.0/csprd01/oslc-query-v3.0-csprd01.html.
The published file name is not the same as the GitHub source file name
so any links that refer to ./oslc-query.html will be broken. The issues
is that the file name (redundantly) contains the version, state and revision
information which changes every time the document is published. This seems
unnecessary since the same information is also in the path.

However the issues
is much worse for multi-part specifications since its a lot more likely
to have cross document relative links. The multi-part links are also replicated
in the additional artifacts section of each document. OSLC Core is 7 parts.
That's a lot of broken links.

Three are three
solutions that could be explored:

1. change OASIS
naming guidelines so that doc-id.ext does not redundantly include version,
status and revision information

2. update ReSpec
to generate the proper URIs for document references and fix all relative
document links to include version, status and revision information 

3. add additional
resources to redirect relative links to the published version. For example,
link http://docs.oasis-open.org/oslc-core/oslc-query/v3.0/csprd01/oslc-query.htmlto http://docs.oasis-open.org/oslc-core/oslc-query/v3.0/csprd01/oslc-query-v3.0-csprd01.html
This would require
no change to OASIS naming conventions, or ReSpec, but would require an
additional publish step.


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:
       Ashok
Malhotra <malhotrasahib@gmail.com>, "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>,
OASIS TAB <tab@lists.oasis-open.org>
Date:
       11/28/2018
11:58 AM
Subject:
       [oslc-domains]
Re: [oslc-core] Re: Fw: Guidance on using relative links in OASIS specifications
Sent
by:        <oslc-domains@lists.oasis-open.org>

---

Jim, would you have a half hour next
week to join a Zoom call with Patrick Durusau and me so you can show us
how this is all working in ReSpec? 

I'd love it if we could produce a way
that you can keep all the filename and URL settings in a master file and
then translate the names when you produce the finished HTML. That would
be a step towards making ReSpec work for any other TCs who'd like to use
it. 

Alternatively, if we get html files from
you with simple <a href="" in it (or whatever),
we should be able to script the work needed to organize and expand links
on our side. 

We can make that decision once we know
what each approach will take. 

In any case, would you have some time? 

Thanks, 

/chet


On Wed, Nov 28, 2018 at 9:43 AM Jim Amsden
<jamsden@us.ibm.com>
wrote:
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 




-- 

/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