ITS Standards

[DC Kelley]

There has been debate recently on how we can go about posting the message set standard on a web page type media and how we can add hyper-links to the issued standard so that the reader can easily go from one page to another, Attached is a sample page using a new style of report based on what I have heard in this regard. Let hear come comments pro and con on this and see if people think it will serve before building it.

A few comments on the major sections follow. The basic report style here is the one used by SAE and IEEE for standards, but with limited style changes it fits all the other SDOs as well. This is basically the report you get when you run the “First Word” product.

Forward linking
This uses the “used by” section of the current report generation make multiple calls to the database and then extracts and lists other places where the current entry is used in a short table. This is an “upward” link and in the current document sis simply printed out by name (no hyper-link).

Downward linking
The actual ASN (and the XML) has the formal name of other elements which make up a data frame or a message. In this example these have all been turned into hyper links (while keeping the code style formatting) This provides a "downward" link. In the current document you have the turn back to the table of contents, find the entry by name, then use the hyper-link there to reach it.

Multiple links points
Each entry would be linked to at the head (where the descriptive name is) and also at the ASN name and at the XML name. All three of these links would be woven together to allow transferring the document within the same view point (i..e you could link from one XML entry to another XML entry and in a similar fashion for ASN entries).

Note that all of these hyper-links could be removed and the document would still have the same basic information, you would simply have the turn the pages yourself. This is an important issue for the standards organizations that still need to produce a final products in printed paper. I envision having a simple on/off switch to render out documents without such links as needed and another switch that will render them to sets of single webs pages for posting and exchanging.

There are some additional features which I would like to add to the document production process mentioned in the examples as well, but I will leave these for another day.

Again, comments are solicited on this style and how to make it serve better.

[DC Kelley]

At 11:52 AM 9/18/2004, Rob Ayers wrote:
Dave-

When I clicked on the one you commented try this, it did what I was looking for--that is link me to the place where the item is defined. Clicking on other items spawned a browser & took me to search.com??? Perhaps those were not working in the example.

Would prefer not to include the 'used by' table in the base document if we don't have to, would prefer that to be output to a separate informative file.
Thanks
Rob

[DC Kelley]

I made the other links (which would go to almost all pages and parts of a 700 page report I was not going to connect by hand) just go to www.search.com to demonstrate the concept. Only the links back and forth to those two entires work "inside" the document. I wanted to get a feel for what a typical entry would look like with all those blue lines .

I think SAE and IEEE would want to keep the "used by" entry in the document as they do now because it makes for a complete set of cross references. To turn this off, simply un-check the button "include cross links" in First Word. When you say print it "to a separate informative file" that can be done but what would you want to link to? Just the name of the other entry? Perhaps you can edit the sample pages to show me what you want.

[Site Admin]

The followng comes from the ISO WG 9 TCIP committee working group who have been trying to establish a "wish list" of key features they feel is needed in their standard to address deployment needs.

[This document was produced at about the same time, and they did not see the above thread, so the thought are all a bit dis-joint from each other at this point]

TWG 9 and TWG Chairs:

Paul Slonaker put together a list of baseline requirements for the cross
reference table(s). Please review these, edit and comment on the
document.

The purpose of the table are two-fold,

(1) to support review of the content requirements of the TCIP standard
during this review period
(2) aid developers in navigating through the document to identify
-- content requirements supported by messages and embedded data frames
-- relationships among messages and data frames to help map data
repositories and data maps to TCIP messages to ensure referential
integrity of the messages.

Thanks for your review.

I believe that Rob needs these requirements soon, so please send me your comments by the COB Friday. I'll compile them, send them to Rob and distribute them to this mailing list. If you think there are others
(in your company or TWG) who may want to contribute to these requirements, please feel free to forward the materials to them. I will
put them on the mailing list when I distribute the final version.

Thanks for your help. Polly

[DC Kelley]

Here is a more flushed-out document after the group meet last reflecting more of what is wanted. My own feelings (Kelley) is that this is quite doable and should not be hard to implement in the next quarters improvements.

[DC Kelley]

I am looking at the requirements expressed in this document and think most of them are easy to understand and fairly direct to build. The document has gotten much more mature since I saw it last. However the last item (#6) dealing with "closure" still confuses me and I can not quite visualize what is really wanted. Is there a well formed fragment somewhere that illustrates this?

Quoting that part of the document which confuses me:

[Site Admin]

The following reprises continued discussion by email among several people regarding how this should all work. Thanks to Paul Slonaker for reformatting things into a readable linear form.

From: Paul Slonaker <p_slonaker@yahoo.com>

I'd like to weigh in with some comments on what
Jon and Dave have said. I'll preface Jon's
comments with JL> and Dave's by DK>. I have
rearranged their quotes somewhat to make it
easier for me to reply to them; please accept
my apologies if by doing so I've misrepresented
anyone. (I've also changed everything back into
plain text - without, I hope, losing too much
readability.)
---------------------------------------------

DK> One of the things that struck me as strange
DK> about the WG9 comments set was
DK> that the table like the one you propose is
DK> a stand alone document. This
DK> seems to be a history thing with TCIP but I
DK> feel I need to ask while
DK> people want to do it that way. You are
DK> going to end up with two sets of
DK> long tables for each entry (one for what is
DK> in an item and another for
DK> where that item is used)

My understanding, and I hope that someone will
correct me if I'm wrong, is that the main desire
is that the user not have to buy or even just
download and install a special tool to view
the cross-reference. At first blush, putting
all of the cross-reference info into an HTML
document yields that freedom while providing
the necessary navigation ability. If this is
not practical given the size of the standard
(and the cross-reference provided by ARINC was
large enough to be cumbersome), then we will
have to reconsider this.

A clarification: Let me be very clear that the purpose of Mini-Edit is as a tool for the standards producers, not to trap anyone into needing a custom tool of any sort. [ Although a growing number of deployment use it manage data as well] The output of the Mini-Edit work is a Word Document (or PDF or HTML), or XML or ASN files - all things you can then read and play with without having to purchase any anything. Everything it does you can do yourself by hand, it is just much fast at it and automates the drudgery involved. The tool is free to all, as part of the FHWA support program. If we can come to agreement on what this linking feature is that different SDOs want, then I will have our programmers add it to the tool suite and all the standards not just TCIP) will end up using the result.


DK> The reason I ask this is because in the
DK> SAE and IEEE work, we build one long (some
DK> would say huge) document with all the links
DK> forward and back in one place. We do that
DK> now, we simply have the add the hyperlinks
DK> in the right places. It seems to me this
DK> is clearer than having a separate document.
DK> Having gotten that off my chest, it would
DK> be no be a big deal to build it both ways
DK> and let the end user render it either way
DK> as they prefer.

I agree; I think that it would be optimal if
this kind of navigation was built into the
standard "document" itself.

DK> I also expect in the next go round that we
DK> will start rendering entries as single web
DK> pages to support better web access to the
DK> work, and the link design need to support
DK> this as well.

Yes. The standard would not necessarily
consist of a single document, but would be more
of a database with multiple views (one of which
would be separate web pages as you suggest).

------------------------------------------------

JL> Your revised example uses a frame (F1) in
JL> an element (E1) and (E3), which
JL> is not possible.

DK> I do not see why you say which is not
DK> possible here, could you help to me
DK> understand the violation you see.

I think that the problem was that the ASN.1
and the used-by examples seemed to bear an
inverse relationship to each other.
The ASN.1 example was:

[Site Admin]

Also re-posted to follow the thread:

As soon as I had sent my previous message, I realized that I had not talked about "closure". I'll try to explain what I mean by this, and the rest of you can decide if it's useful enough to require.

Remembering the previous example,

[DC Kelley]

FYI: Some related information on the general subject of automated publishing methods and converting between Word and XML and a database can also be found at this thread:
http://serv4.itsware.net/bb/viewtopic.php?t=636

[DC Kelley]

This thread topic produced a lot of debate and a lot of thinking (700+ views when I posted this). Now, over three months latter, we have a pretty damn good looking set of links being produced and can see the end game in sight for the first official release of the 1st Word tool with hyper-linking. Take a look at http://serv4.itsware.net/bb/viewtopic.php?t=593 for a screen shot. People are saying they can not believe how they ever lived without this tool, obviously that is a good sign!

I wish to thank the members of various committee and working groups, especially those in the TCIP community that added to this debate and moved the whole ITS community forward in understanding what a suitable set of links needed to entail. I believe we have largely achieved this goal with what we have now, and thought I would take the morning and draft out my thoughts on where I see the current technical issues and and problems in the tool we now have created. Its not perfect, but it is moving towards it.

The attached memo outlines the current problems left to solve, mostly dealing with issues of name-spaces and linking to the entries of other standards. I expect we will have this completed in another few weeks, after which the improved tool will be used to process drafts for the various committees. My understanding is that TCIP 2.7 plans to use it in the next revision and will likely be the first.

[DC Kelley]

I just came across this thread while reviewing the most read topics (this was in the top ten). It has been a year, so a short update may be in order.

At this point this function (adding hyper links to listings) is universally loved and many people have come to depend on it. The tool can go document over 30,000 links or more (even thought Microsoft claims this should not be possible, and frankly no one wants to read docs that long). It still takes time (5 minutes to render a ~250 page std, 50 minutes to link it).

I can not imagine reading a standard without it anymore. Committee document reviewers have learned that if they DON'T see a link on a bit code, it likely means that the element in question has a problem, so it is helping people do better reviews, besides making the page turning process go away. The only real problem to report is that those SDOs that want render final standards to PDFs are still having issues with the Adobe tool not handling hyper links well. Some of the 3rd party tools do it fine, but Adobe seems to have made it harder in recent releases.

This is so damn useful that I have taken to rendering deployment projects the same way. I take the schema set they want to use, hack it down from the issued standard and add local content (the same process any deployment must deal with) but then I run the resulting product past the First Word tool and issue a nice composite document they can use in procurement and in actual vendor/code validation work. Take a look at the AzTech project in the schema repository for some examples of this. Perhaps in time we can make this available by way of a web service to others.