scrollkeeper-devel — Developer discussion list for ScrollKeeper

Re: [Scrollkeeper-devel] structure of extracted index page

[Mary D. <Mar...@Su...>]

Hi Dan

yes, it appears ids are optional for indexterms (and not used for "see" and "see 
also").
From what I understand the convertor at run time generates ids where required 
(using generate-id() ).  However, as you point out, I don't believe scrollkeeper 
can predict what these ids will be because:
1) scrollkeeper may use a different convertor to the 'run-time' convertor.
2) even if the same convertor is used the w3.org description indicates that 
  "An implementation is under no obligation to generate the
   same identifiers each time a document is transformed."
   see http://www.w3.org/TR/xslt#function-generate-id

Am I correct in these assumptions?


Your point about generating ids for use within the index doc (for "see" and "see 
also") makes sense and I will incorporate this


cheers
Mary


> 
> My understanding is that id's are optional on all the indexing tags of
> interest here: indexterm, see, seealso (and maybe others...)
> 
> Do you know what collateindex.pl does with indexterms which do not have
> id's?  I tried to make a small test document which generates a nice index
> but wasn't successful within just a few minutes.  Do you have a test
> document handy we can play with?  I am guessing that it can generate an
> index independent of whether the indexterms have id's.
> 
> It is certainly convenient if all the indexterms have id's, as it is
> easier to link to them from the index.  This is very similar to how the
> TOC links to section id's though.  Jade deals with sections without id's
> by assigning id's to them.  It can do this because it is generating both
> the anchors and the links in the same output.
> 
> Suppose we continued to use on-the-fly conversion from SGML to HTML:
> 
> The difficulty with ScrollKeeper creating an index off of an SGML
> document, or even a TOC off an SGML document, which doesn't have id's is
> that the generated index or TOC has to predict the id's (ie. anchors)
> which will be assigned to those sections or indexterms by the converter at
> run time.  If we know how this assignment will be done, we are ok.  
> Otherwise, we must require that all sections and indexterms (and <see> and
> <seealso>) have id's.  This is what we are doing now in the GDP, but is
> not really a great solution since we are making further restrictions on
> top of DocBook.  Thus SK would not work with just any DocBook doc, but a
> certain subset of all DocBook docs.  So the better solution is to come up
> with a scheme which will assign id's in a predictable way.  This method
> would be used by ScrollKeeper during the index creation and during
> gnome-db2html2/gnome-db2html3 during display.  The downside to this is
> that ScrollKeeper would need to know in advance which display system will
> be used.  So long as GNOME and KDE follows the system used by
> collateindex.pl, we should not have any problems.
> 
> Laszlo - Does this all sound correct based on your experience?  How do you
> handle sections without id's in ScrollKeeper's TOC extraction?  Do you
> ignore those sections or id them in the same way as db2html?
> 
> The other possibility is that instead of trying to refer to an anchor in
> the generated HTML, we try to refer to the position in the XML document.  
> I really don't know how this would work exactly, since I am not very
> familiar with libxml, but it may be possible.  (DV?)
> 
> Dan
> 
> 
> 
> On Wed, 25 Apr 2001, Mary Dwyer wrote:
> 
> > hi
> > 
> > I'd appreciate some feedback/suggestions on the structure of the index 
> > scrollkeeper will create from a document.
> > 
> > To aid explanation, consider a document including the following index 
markups:
> > 
> > <indexterm id="idx-a1">
> >   <primary>Apple</primary><secondary>Big 
</secondary><tertiary>Green</tertiary>
> > </indexterm>
> > 
> > <indexterm zone="a1"><primary>Orange</primary><secondary>Medium></secondary>
> > </indexterm>
> > 
> > <indexterm id="idx-a2" class=startofrange>
> >   <primary>Banana</primary><secondary>Small</secondary>
> > </indexterm>
> > <indexterm startref="idx-a2" class=endofrange>
> > 
> > 
> > 
> > 
> > The Example below is an excerpt from the extracted index .
> >  
> > 1. The tags <indexdoc> </indexdoc> indicate beginning and end of document
> > 2. The index entry is indicated by the tags <indexentry linkid="id"> 
> > </indexentry>
> > 
> > I do not know how to handle See and See Also references (as they are not 
> > associatied with an id) - any suggestions?
> > 
> > 
> > Example:
> > 
> > <indexdoc>
> >    <indexentry linkid="idx-a1">Apple, Big, Green
> >    </indexentry>
> >    <indexentry linkid="idx-a2">Banana, Small
> >    </indexentry>
> >    <indexentry linkid="a1">Orange, Medium
> >    </indexentry
> >       
> >    etc. .......
> >    
> > </indexdoc>   
> > 
> > 
> > 
> > TIA
> > Mary
> > 
> > 
> > 
> > 
> > ~ I speak for myself, not for my employer ~
> > =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> > Mary Dwyer
> > Desktop Applications & Middleware Grp
> > Sun Microsystems Ireland
> > Tel: +353-1-8199222 (xt 19222)
> > Fax: +353-1-8199078
> > email: mar...@ir...
> > =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> > 
> > 
> > _______________________________________________
> > Scrollkeeper-devel mailing list
> > Scr...@li...
> > http://lists.sourceforge.net/lists/listinfo/scrollkeeper-devel
> > 
> 
> 

~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Re: [Scrollkeeper-devel] structure of extracted index page

[Daniel V. <vei...@re...>]

On Wed, Apr 25, 2001 at 10:44:30PM -0500, Dan Mueth wrote:
> The other possibility is that instead of trying to refer to an anchor in
> the generated HTML, we try to refer to the position in the XML document.  
> I really don't know how this would work exactly, since I am not very
> familiar with libxml, but it may be possible.  (DV?)

  I'm afraid I didn't follow the discussion here (sorry !), the best
way to get a technical  answer from me is to give me a practical example
(what's your input, how it's processed, what's the result, why it fails),
and then I can use what I know both from the specs and the code to get
this answer precisely and quickly,

Daniel

-- 
Daniel Veillard      | Red Hat Network http://redhat.com/products/network/
vei...@re...  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/

Re: [Scrollkeeper-devel] structure of extracted index page

[Dan M. <da...@ea...>]

[removing gnome-doc-list from cc list since this email is getting into the
internal guts of SK]

On Wed, 25 Apr 2001, Mary Dwyer wrote:

> Example:
> 
> <indexdoc>
>    <indexentry linkid="idx-a1">Apple, Big, Green
>    </indexentry>
>    <indexentry linkid="idx-a2">Banana, Small
>    </indexentry>
>    <indexentry linkid="a1">Orange, Medium
>    </indexentry
>       
>    etc. .......
>    
> </indexdoc>   

There is nesting information which is left out.  For example, if you also
have "Apple, Big, Blue", the markup above does not reveal that your index
looks like:
  Apple
      Big
          Green  *
          Blue   *
  Banana
      Small      *
  Orange
      Medium     *

I think it makes sense to put this into the XML file, since this is the
way the data will typically be displayed and processed.  If SK does the
work of sorting this out then things will be faster and easier for the
help browsers.

Note that for <see> and <seealso>, they are actually creating links
*within* the index, pointing to other parts of the index.  For these we
can either describe their position by creating an id for them or by
specifying the full index term they link to.  I'm not sure which is
better, but introducing id's seems reasonable.

For example, one might use:

<indexdoc>
  <primary>
     <title>Apple</title>
     <secondary>
       <title>Big</title>
       <tertiary>
          <title linkid="idx-a1">Green</title>
          <title linkid="idx-a3">Blue</title>
          <seealso seeid="sa-1">New York City</seealso>
       </tertiary>
     </secondary>
   </primary>
   <primary>
     <title>Banana</title>
     <secondary>
       <title linkid="idx-a2">Small</title>
     </secondary>
   </primary>
   <primary>
     <title id="sa-1" linkid="idx-a5">New York City</title>
   </primary>
</indexdoc>

or

<indexdoc>
  <primary title="Apple">
    <secondary title="Big">
      <tertiary title="Green" linkid="idx-a1"/>
      <tertiary title="Blue" linkid="idx-a3"/>
      <seealso title="New York City" seeid="sa-1"/>
    </secondary>
  </primary>
  <primary title="Banana">
    <secondary title="Small" linkid="idx-a2"/>
  </primary>
  <primary title="New York City" id="sa-1" linkid="idx-a5">
  </primary>
</indexdoc>

So, here SK generated the id "sa-1" which is used to link to "New York
City" in the index, while "idx-a5" is the id assigned to the index term by
the author for linking from the index into the body of the document.

Does this seem reasonable?

Dan

Re: [Scrollkeeper-devel] structure of extracted index page

[Dan M. <da...@ea...>]

Hi Mary,

I suspect you know more about indexing with DocBook than almost anybody
else on these lists.  I'll give a shot at an answer, and you can correct
me where I go wrong ;)

My understanding is that id's are optional on all the indexing tags of
interest here: indexterm, see, seealso (and maybe others...)

Do you know what collateindex.pl does with indexterms which do not have
id's?  I tried to make a small test document which generates a nice index
but wasn't successful within just a few minutes.  Do you have a test
document handy we can play with?  I am guessing that it can generate an
index independent of whether the indexterms have id's.

It is certainly convenient if all the indexterms have id's, as it is
easier to link to them from the index.  This is very similar to how the
TOC links to section id's though.  Jade deals with sections without id's
by assigning id's to them.  It can do this because it is generating both
the anchors and the links in the same output.

Suppose we continued to use on-the-fly conversion from SGML to HTML:

The difficulty with ScrollKeeper creating an index off of an SGML
document, or even a TOC off an SGML document, which doesn't have id's is
that the generated index or TOC has to predict the id's (ie. anchors)
which will be assigned to those sections or indexterms by the converter at
run time.  If we know how this assignment will be done, we are ok.  
Otherwise, we must require that all sections and indexterms (and <see> and
<seealso>) have id's.  This is what we are doing now in the GDP, but is
not really a great solution since we are making further restrictions on
top of DocBook.  Thus SK would not work with just any DocBook doc, but a
certain subset of all DocBook docs.  So the better solution is to come up
with a scheme which will assign id's in a predictable way.  This method
would be used by ScrollKeeper during the index creation and during
gnome-db2html2/gnome-db2html3 during display.  The downside to this is
that ScrollKeeper would need to know in advance which display system will
be used.  So long as GNOME and KDE follows the system used by
collateindex.pl, we should not have any problems.

Laszlo - Does this all sound correct based on your experience?  How do you
handle sections without id's in ScrollKeeper's TOC extraction?  Do you
ignore those sections or id them in the same way as db2html?

The other possibility is that instead of trying to refer to an anchor in
the generated HTML, we try to refer to the position in the XML document.  
I really don't know how this would work exactly, since I am not very
familiar with libxml, but it may be possible.  (DV?)

Dan



On Wed, 25 Apr 2001, Mary Dwyer wrote:

> hi
> 
> I'd appreciate some feedback/suggestions on the structure of the index 
> scrollkeeper will create from a document.
> 
> To aid explanation, consider a document including the following index markups:
> 
> <indexterm id="idx-a1">
>   <primary>Apple</primary><secondary>Big </secondary><tertiary>Green</tertiary>
> </indexterm>
> 
> <indexterm zone="a1"><primary>Orange</primary><secondary>Medium></secondary>
> </indexterm>
> 
> <indexterm id="idx-a2" class=startofrange>
>   <primary>Banana</primary><secondary>Small</secondary>
> </indexterm>
> <indexterm startref="idx-a2" class=endofrange>
> 
> 
> 
> 
> The Example below is an excerpt from the extracted index .
>  
> 1. The tags <indexdoc> </indexdoc> indicate beginning and end of document
> 2. The index entry is indicated by the tags <indexentry linkid="id"> 
> </indexentry>
> 
> I do not know how to handle See and See Also references (as they are not 
> associatied with an id) - any suggestions?
> 
> 
> Example:
> 
> <indexdoc>
>    <indexentry linkid="idx-a1">Apple, Big, Green
>    </indexentry>
>    <indexentry linkid="idx-a2">Banana, Small
>    </indexentry>
>    <indexentry linkid="a1">Orange, Medium
>    </indexentry
>       
>    etc. .......
>    
> </indexdoc>   
> 
> 
> 
> TIA
> Mary
> 
> 
> 
> 
> ~ I speak for myself, not for my employer ~
> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> Mary Dwyer
> Desktop Applications & Middleware Grp
> Sun Microsystems Ireland
> Tel: +353-1-8199222 (xt 19222)
> Fax: +353-1-8199078
> email: mar...@ir...
> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> 
> 
> _______________________________________________
> Scrollkeeper-devel mailing list
> Scr...@li...
> http://lists.sourceforge.net/lists/listinfo/scrollkeeper-devel
> 

Re: [Scrollkeeper-devel] URN as identifier

[Bob S. <bo...@sc...>]

> From: Kendall Clark <ke...@mo...>

Hi Kendall,
It was very helpful to hear from you. Are you still the
maintainer of the OMF DTD?
 
> I worked on OMF so let me see if I can remember some good answers to
> these better questions.
> 
> As for "more general URI": yes, exactly. I wasn't being careful to
> distinguish URN from URI and URL in the DTD, as I should have been. I
> suspect that attribute should be renamed "URI" -- at least, that's
> what I'd name it today if I were working on the DTD now.
> 
> [stuff deleted]
> 
> The ambiguity of OMF's RELATION pretty faithfully mirrors the
> ambiguity, at the time, of Dublin Core's use of RELATION. That is,
> it's vague on purpose, in a kind of librarian, infosci, you just never
> know sense. :>
> 
> What we need, and maybe Dublin Core has made some progress on this, is
> a way to specify the *type* of RELATION; that is, a controlled
> vocabulary that gives us a way to specify kinds of RELATION between
> resources.

Actually, Dublin Core has done just that with the element
qualifiers they published 2000-07-11.  They are described
in <http://dublincore.org/documents/dcmes-qualifiers/>.
For the <relation> element, they have:

  Is Version Of
  Has Version
  Is Replaced By
  Replaces
  Is Required By
  Requires
  Is Part Of
  Has Part
  Is Referenced By
  References
  Is Format Of
  Has Format

The one that caught my eye was "Is Version Of", since
that seems to capture the relation between a given
document and the seriesID.

The question is then: How is this encoded in an OMF
metadata? I notice that the OMF <relation> element already
has a "status" attribute by virtue of the core attribute
set in the DTD.  It would seem we could just assign a
specific value for the status attribute.  For example:

<relation  status="IsVersionOf"  url="seriesID-expressed-as-uri"/>

This means the document connected to this OMF <resource>
is a version of the seriesID.

> SK doesn't necessarily need to rely on a controlled
> vocabulary from another organization in this regard; if Dublin Core
> has released one by now, there's no reason to think that it will
> necessarily be useful in the SK effort. The SK team is perfectly able
> to define it's own controlled vocabulary for kinds of RELATION, given
> its problem domain; make it public, maintain it in a clear and open
> fashion, and, perhaps most importantly, make sure that who or whatever
> is generating SK content is amenable to using it.

Right.  To quote from the Dublin Core qualifiers document:

"It is expected that implementors will develop additional
qualifiers for use within local applications or specific
domains. Such qualifiers may not be understood by other
applications."

We could make it more SK or OMF specific by saying:

<relation  status="omf-series-id"  url="seriesID-expressed-as-uri"/>

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bo...@sc...

[Scrollkeeper-devel] structure of extracted index page

[Mary D. <Mar...@Su...>]

hi

I'd appreciate some feedback/suggestions on the structure of the index 
scrollkeeper will create from a document.

To aid explanation, consider a document including the following index markups:

<indexterm id="idx-a1">
  <primary>Apple</primary><secondary>Big </secondary><tertiary>Green</tertiary>
</indexterm>

<indexterm zone="a1"><primary>Orange</primary><secondary>Medium></secondary>
</indexterm>

<indexterm id="idx-a2" class=startofrange>
  <primary>Banana</primary><secondary>Small</secondary>
</indexterm>
<indexterm startref="idx-a2" class=endofrange>




The Example below is an excerpt from the extracted index .
 
1. The tags <indexdoc> </indexdoc> indicate beginning and end of document
2. The index entry is indicated by the tags <indexentry linkid="id"> 
</indexentry>

I do not know how to handle See and See Also references (as they are not 
associatied with an id) - any suggestions?


Example:

<indexdoc>
   <indexentry linkid="idx-a1">Apple, Big, Green
   </indexentry>
   <indexentry linkid="idx-a2">Banana, Small
   </indexentry>
   <indexentry linkid="a1">Orange, Medium
   </indexentry
      
   etc. .......
   
</indexdoc>   



TIA
Mary




~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Re: [Scrollkeeper-devel] URN as identifier

[Kendall C. <ke...@mo...>]

>>>>> "bob" == Bob Stayton <bo...@sc...> writes:

  >> Right.  So I guess the URN would go in identifier.  This can be
  >> done without any modification to the OMF I believe.  (Is a URN
  >> considered a URL?  If not, I guess we should explicitly state
  >> that an identifier may be a URN.)

  bob> Well, if you look at the OMF template at
  bob> http://www.ibiblio.org/osrt/omf/cgi-bin/template.pl the
  bob> <identifier> element says "(e.g. a URL or URN)".  The DTD uses
  bob> "url" as the attribute name, but I believe that should be
  bob> interpeted as a more general URI.

I worked on OMF so let me see if I can remember some good answers to
these better questions.

As for "more general URI": yes, exactly. I wasn't being careful to
distinguish URN from URI and URL in the DTD, as I should have been. I
suspect that attribute should be renamed "URI" -- at least, that's
what I'd name it today if I were working on the DTD now.

  bob> This sounds fine, but I'm trying to understand the OMF syntax
  bob> for these.  As I read the existing OMF specification for
  bob> VERSION, it has modifiers VERSION.identifier, VERSION.date, and
  bob> VERSION.description.  The description calls these attributes.

I haven't followed very closely the Scrollkeeper discussion recently,
so if this is wide of the mark, someone please correct me. But the OMF
VERSION.(identifier, date, description) was meant to be used to store
versioning, as in RCS/CVS, metadata about resources. So the three
parts -- id, desc, date -- were intended to be used thus (in
pseudo-markup):

<version id="1.0" desc="The initial public release" date="20010101" />

Again, I haven't followed the SK conversation, so I don't know if you
all are talking about using VERSION for revision metadata or for
something else.

  bob> But the OMF DTD defines them as child elements of <version>.  I
  bob> guess the spec uses the word "attribute" in the general
  bob> meaning, not in the XML DTD meaning.

Yes, in general the spec is *not* using words in their XML or SGML DTD
sense, since the spec was written before any DTD was begun, and by
people who did not have DTD jargon primarily in mind. This is
appropriate since the OMF spec could be used equally well as the basis
of an XML Schemas, TREX, RELAX, or Schematron formalization effort.

Again, if I recall correctly, I made id-desc-date child elements of
VERSION primarily out an urge to avoid tying the hands of users of
OMF. Description, for example, may well be anything from a short
sentence to paragraphs of information, a la CHANGELOG.

  bob> If seriesid and identifier are children elements of <relation>,
  bob> I'm not clear on how the <relation> XML attributes are used.
  bob> Perhaps we should contact someone at OMF to get clarification
  bob> on the expected usage of <relation>?

The ambiguity of OMF's RELATION pretty faithfully mirrors the
ambiguity, at the time, of Dublin Core's use of RELATION. That is,
it's vague on purpose, in a kind of librarian, infosci, you just never
know sense. :>

What we need, and maybe Dublin Core has made some progress on this, is
a way to specify the *type* of RELATION; that is, a controlled
vocabulary that gives us a way to specify kinds of RELATION between
resources. SK doesn't necessarily need to rely on a controlled
vocabulary from another organization in this regard; if Dublin Core
has released one by now, there's no reason to think that it will
necessarily be useful in the SK effort. The SK team is perfectly able
to define it's own controlled vocabulary for kinds of RELATION, given
its problem domain; make it public, maintain it in a clear and open
fashion, and, perhaps most importantly, make sure that who or whatever
is generating SK content is amenable to using it.

I hope some of this helps. (FWIW, I've been mulling a rewrite of the
OMF DTD using James Clark's new TREX schema specification language,
which is now Linuxly-viable given that it has an initial Python
implementation. But I need to catch up to the SK status quo to see if
that makes less sense than any of a number of alternatives.)

Best,
Kendall Clark
-- 
I am a finite state machine.

Re: [Scrollkeeper-devel] Re: group part of URN

[Bob S. <bo...@sc...>]

> From: <las...@su...>
> 
> > Well, since the URN string as discussed so far is a
> > fixed-field string, then all URNs would have to have
> > a group (or a blank group field).  Given the already
> > large number of fields, I wonder if it is necessary.
> > Couldn't Sun (the obvious big organization example 8^)
> > coordinate assigning the documument name part?  Make
> > the project string part of the name?
> 
> :-) As far as Sun is concerned Scrollkeeper's primary purpose is to
> support the Gnome Desktop Help. So we would be able to manage the
> document names for some time without the "group" field. How about no
> "group" field, but we still use "x-omf1" to track the version of the urn
> to handle later changes easily?

Yes, I agree that identifying the schema version is
important for long-term maintainability.

bobs

Re: [Scrollkeeper-devel] Re: group part of URN

[<las...@Su...>]

> Well, since the URN string as discussed so far is a
> fixed-field string, then all URNs would have to have
> a group (or a blank group field).  Given the already
> large number of fields, I wonder if it is necessary.
> Couldn't Sun (the obvious big organization example 8^)
> coordinate assigning the documument name part?  Make
> the project string part of the name?

:-) As far as Sun is concerned Scrollkeeper's primary purpose is to
support the Gnome Desktop Help. So we would be able to manage the
document names for some time without the "group" field. How about no
"group" field, but we still use "x-omf1" to track the version of the urn
to handle later changes easily?

Laszlo

Re: [Scrollkeeper-devel] URN as identifier

[Dan M. <da...@ea...>]

On Mon, 23 Apr 2001, Bob Stayton wrote:

> > From: Dan Mueth <da...@ea...>
> > 
> > > But I'm not clear where a series ID fits into the OMF
> > > metadata DTD.  If I understand you correctly, the same
> > > series ID would be applied to every version/language/format
> > > of a document in its history, including when it changes
> > > hands.  But the OMF <identifier> element is supposed to be
> > > unique to each document.
> > 
> > Right.  So I guess the URN would go in identifier.  This can be done
> > without any modification to the OMF I believe.  (Is a URN considered a
> > URL?  If not, I guess we should explicitly state that an identifier may be
> > a URN.)
> 
> Well, if you look at the OMF template at
> http://www.ibiblio.org/osrt/omf/cgi-bin/template.pl
> the <identifier> element says "(e.g. a URL or URN)".
> The DTD uses "url" as the attribute name, but I believe
> that should be interpeted as a more general URI.

We should use the specification as the authoritative definition of the
OMF, as the DTD still needs some work until it is fully consistent with
the spec.  The spec is at: 
http://www.ibiblio.org/osrt/omf/omf_elements

As you say, it specifies "URL".  We can request this be changed to "URI"
for the next version of the specification.

> > eg:
> > <identifier>http://www.ldp.org/docs/howto/nfs</identifier>
> > <identifier>urn:blahblahblah</identifier>
> > 
> > If anybody replies to this, let's please start a new thread with a title
> > about URN's ;)
> > 
> > > I would propose instead using the OMF <relation> element,
> > > with its url attribute pointing to a series ID.  By that I
> > > mean define a seriesID using uuidgen as Dan suggests.  Then
> > > the OMF metadata for each document includes
> > > 
> > > <relation url="thisseriesUUID" status="omf-series-id"/>
> > > 
> > > This defines a relationship between this document and the
> > > series of which it is a part.  Then you could query an OMF
> > > metadata collection to select all documents that share the
> > > same relation element.  From that you could select specific
> > > alternate version/language/format documents.
> > > 
> > > Would this be a correct usage of the <relation> element?
> > > Would it meet the needs of a seriesID?
> > 
> > I think using a uuidgen code and putting it in RELATION is the way to
> > go.  (I was completely overlooking this element.)  I would propose
> > breaking RELATION into two attributes:  RELATION.identifier and
> > RELATION.seriesid.  The identifier attribute should follow the guidelines
> > of the IDENTIFIER element - it can point to any valid URL/URN.  The
> > seriesid is the document series id code, obtained from uuidgen.
> > 
> > It would look something like this:
> > 
> > -----
> > 14.     Relation
> >         Label: RELATION
> >         Obligation: Optional
> >                 RELATION.IDENTIFIER (Optional)
> >                 RELATION.SERIESID (Optional)
> >         Maximum Occurrence: Repeatable
> > 
> > Description of the resource's relationship with other similar resources.  
> > RELATION.IDENTIFIER is a URL that points to the IDENTIFIER element of
> > another resource.  Each instance of RELATION with the RELATION.IDENTIFIER
> > attribute links the resource to other resources of similar domain or
> > style. RELATION.SERIESID is a string code which specifies various
> > instances of a document, such as various versions, formats, or
> > translations.  All documents which are related in these ways should have
> > the same RELATION.SERIESID.  No documents which do not belong to this
> > set should share the RELATION.SERIESID.
> > -----
> 
> This sounds fine, but I'm trying to understand the
> OMF syntax for these.  As I read the existing
> OMF specification for VERSION, it has modifiers
> VERSION.identifier, VERSION.date, and VERSION.description.
> The description calls these attributes.  But the OMF
> DTD defines them as child elements of <version>.  I guess the
> spec uses the word "attribute" in the general meaning,
> not in the XML DTD meaning.  

Yes.  The specification doesn't distinguish between attributes and
children.  In most, if not all, cases we can treat these as children
instead of XML attributes. It looks like the current version of the DTD
treats some as children and others as attributes in self-closing
tags.

> If seriesid and identifier are children elements
> of <relation>, I'm not clear on how the <relation>
> XML attributes are used.  Perhaps we should contact
> someone at OMF to get clarification on the
> expected usage of <relation>?

I don't think it matters if what the specification calls "attributes" are
children or attributes in self-closing tags in the XML representation.

We could have:
<relation>
  <identifier>
     http:foo
  </identifier>
</relation>
<relation>
  <seriesid>
     1234567890
  </seriesid>
</relation>

Or:
<relation identifier="http:foo"/>
<relation seriesid="1234567890"/>

One thing which is not clear for this element or some of the other ones
is:

(1) Can you have both the identifier and the seriesid attributes set for a
given <relation>? I would expect this to be "no", since the identifier is
not describing the same object as the seriesid.

(2) Can you have multiple children of the same type (eg. two
<identifier>'s) for a given <relation>?  I would expect this to also be
"no", although the specification doesn't explicitly state it.

I would expect that the specification should explicitly address these
issues.

Dan

Re: [Scrollkeeper-devel] URN as identifier

[Bob S. <bo...@sc...>]

> From: Dan Mueth <da...@ea...>
> 
> > But I'm not clear where a series ID fits into the OMF
> > metadata DTD.  If I understand you correctly, the same
> > series ID would be applied to every version/language/format
> > of a document in its history, including when it changes
> > hands.  But the OMF <identifier> element is supposed to be
> > unique to each document.
> 
> Right.  So I guess the URN would go in identifier.  This can be done
> without any modification to the OMF I believe.  (Is a URN considered a
> URL?  If not, I guess we should explicitly state that an identifier may be
> a URN.)

Well, if you look at the OMF template at
http://www.ibiblio.org/osrt/omf/cgi-bin/template.pl
the <identifier> element says "(e.g. a URL or URN)".
The DTD uses "url" as the attribute name, but I believe
that should be interpeted as a more general URI.

> eg:
> <identifier>http://www.ldp.org/docs/howto/nfs</identifier>
> <identifier>urn:blahblahblah</identifier>
> 
> If anybody replies to this, let's please start a new thread with a title
> about URN's ;)
> 
> > I would propose instead using the OMF <relation> element,
> > with its url attribute pointing to a series ID.  By that I
> > mean define a seriesID using uuidgen as Dan suggests.  Then
> > the OMF metadata for each document includes
> > 
> > <relation url="thisseriesUUID" status="omf-series-id"/>
> > 
> > This defines a relationship between this document and the
> > series of which it is a part.  Then you could query an OMF
> > metadata collection to select all documents that share the
> > same relation element.  From that you could select specific
> > alternate version/language/format documents.
> > 
> > Would this be a correct usage of the <relation> element?
> > Would it meet the needs of a seriesID?
> 
> I think using a uuidgen code and putting it in RELATION is the way to
> go.  (I was completely overlooking this element.)  I would propose
> breaking RELATION into two attributes:  RELATION.identifier and
> RELATION.seriesid.  The identifier attribute should follow the guidelines
> of the IDENTIFIER element - it can point to any valid URL/URN.  The
> seriesid is the document series id code, obtained from uuidgen.
> 
> It would look something like this:
> 
> -----
> 14.     Relation
>         Label: RELATION
>         Obligation: Optional
>                 RELATION.IDENTIFIER (Optional)
>                 RELATION.SERIESID (Optional)
>         Maximum Occurrence: Repeatable
> 
> Description of the resource's relationship with other similar resources.  
> RELATION.IDENTIFIER is a URL that points to the IDENTIFIER element of
> another resource.  Each instance of RELATION with the RELATION.IDENTIFIER
> attribute links the resource to other resources of similar domain or
> style. RELATION.SERIESID is a string code which specifies various
> instances of a document, such as various versions, formats, or
> translations.  All documents which are related in these ways should have
> the same RELATION.SERIESID.  No documents which do not belong to this
> set should share the RELATION.SERIESID.
> -----

This sounds fine, but I'm trying to understand the
OMF syntax for these.  As I read the existing
OMF specification for VERSION, it has modifiers
VERSION.identifier, VERSION.date, and VERSION.description.
The description calls these attributes.  But the OMF
DTD defines them as child elements of <version>.  I guess the
spec uses the word "attribute" in the general meaning,
not in the XML DTD meaning.  

If seriesid and identifier are children elements
of <relation>, I'm not clear on how the <relation>
XML attributes are used.  Perhaps we should contact
someone at OMF to get clarification on the
expected usage of <relation>?

bobs

Re: [Scrollkeeper-devel] Re: group part of URN

[Bob S. <bo...@sc...>]

> From: <las...@su...>
> Organization: Sun Microsystems
> 
> > I seem to have missed the introduction of :group: in
> > the URN.  Is that necessary to establishing a document
> > "name" part?  Or is it part of the metadata (in which case
> > shouldn't it be in the OMF metadata elements)?
> 
> Oh, this was me. I just thought that for a large organization we might
> want to have another level between organization and document. Obvious
> values for this are project or package name.

Well, since the URN string as discussed so far is a
fixed-field string, then all URNs would have to have
a group (or a blank group field).  Given the already
large number of fields, I wonder if it is necessary.
Couldn't Sun (the obvious big organization example 8^)
coordinate assigning the documument name part?  Make
the project string part of the name?

I'm not objecting strongly, I just want the URN usage
to be perfectly clear.

bobs

Re: [Scrollkeeper-devel] Better internationalization support

[Dan M. <da...@ea...>]

> But I'm not clear where a series ID fits into the OMF
> metadata DTD.  If I understand you correctly, the same
> series ID would be applied to every version/language/format
> of a document in its history, including when it changes
> hands.  But the OMF <identifier> element is supposed to be
> unique to each document.

Right.  So I guess the URN would go in identifier.  This can be done
without any modification to the OMF I believe.  (Is a URN considered a
URL?  If not, I guess we should explicitly state that an identifier may be
a URN.)

eg:
<identifier>http://www.ldp.org/docs/howto/nfs</identifier>
<identifier>urn:blahblahblah</identifier>

If anybody replies to this, let's please start a new thread with a title
about URN's ;)

> I would propose instead using the OMF <relation> element,
> with its url attribute pointing to a series ID.  By that I
> mean define a seriesID using uuidgen as Dan suggests.  Then
> the OMF metadata for each document includes
> 
> <relation url="thisseriesUUID" status="omf-series-id"/>
> 
> This defines a relationship between this document and the
> series of which it is a part.  Then you could query an OMF
> metadata collection to select all documents that share the
> same relation element.  From that you could select specific
> alternate version/language/format documents.
> 
> Would this be a correct usage of the <relation> element?
> Would it meet the needs of a seriesID?

I think using a uuidgen code and putting it in RELATION is the way to
go.  (I was completely overlooking this element.)  I would propose
breaking RELATION into two attributes:  RELATION.identifier and
RELATION.seriesid.  The identifier attribute should follow the guidelines
of the IDENTIFIER element - it can point to any valid URL/URN.  The
seriesid is the document series id code, obtained from uuidgen.

It would look something like this:

-----
14.     Relation
        Label: RELATION
        Obligation: Optional
                RELATION.IDENTIFIER (Optional)
                RELATION.SERIESID (Optional)
        Maximum Occurrence: Repeatable

Description of the resource's relationship with other similar resources.  
RELATION.IDENTIFIER is a URL that points to the IDENTIFIER element of
another resource.  Each instance of RELATION with the RELATION.IDENTIFIER
attribute links the resource to other resources of similar domain or
style. RELATION.SERIESID is a string code which specifies various
instances of a document, such as various versions, formats, or
translations.  All documents which are related in these ways should have
the same RELATION.SERIESID.  No documents which do not belong to this
set should share the RELATION.SERIESID.
-----

I imagine somebody else on the list can write this more clearly.

BTW: Are any of the OMF maintainers on this list following this
thread?  It would be nice to hear your opinions.

Dan

Re: [Scrollkeeper-devel] Better internationalization support

[<las...@Su...>]

Bob Stayton wrote:
> 
> > From: Dan Mueth <da...@ea...>
> >
> > So, we would have:
> >
> > urn:x-omf1:organization:group:name:version:language:format
> >
> > where organization will normally be a domain and group is whatever the
> > coordinators for that domain choose (package, project, etc.)
> 
> I seem to have missed the introduction of :group: in
> the URN.  Is that necessary to establishing a document
> "name" part?  Or is it part of the metadata (in which case
> shouldn't it be in the OMF metadata elements)?

Oh, this was me. I just thought that for a large organization we might
want to have another level between organization and document. Obvious
values for this are project or package name.

[snip]

> I would propose instead using the OMF <relation> element,
> with its url attribute pointing to a series ID.  By that I
> mean define a seriesID using uuidgen as Dan suggests.  Then
> the OMF metadata for each document includes
> 
> <relation url="thisseriesUUID" status="omf-series-id"/>
> 
> This defines a relationship between this document and the
> series of which it is a part.  Then you could query an OMF
> metadata collection to select all documents that share the
> same relation element.  From that you could select specific
> alternate version/language/format documents.
> 
> Would this be a correct usage of the <relation> element?
> Would it meet the needs of a seriesID?

I looked at the definition of the <relation> element and it didnt seem
very obvious if it is ok, but I think we could use it like the above.

Laszlo

Re: [Scrollkeeper-devel] Better internationalization support

[<las...@Su...>]

Dan Mueth wrote:
> 
> On Fri, 20 Apr 2001, Laszlo Kovacs wrote:
> 
> > So I thought maybe an OMF URN version field should be added, like:
> >
> > urn:x-omf:omf-urn-version:organization:group:name:version:language:format
> >
> > where omf-urn-version is for internal purpose to track changes in our
> > URN structure. Although we could also use x-omf1, x-omf2 etc instead of
> > x-omf. Do people think this would be useful?
> 
> So, we would have:
> 
> urn:x-omf1:organization:group:name:version:language:format
> 
> where organization will normally be a domain and group is whatever the
> coordinators for that domain choose (package, project, etc.)
> 
> The part of this which will be used to identify a series of a document
> (different versions, formats, and languages) is:
> 
> urn:x-omf1:organization:group:name
> 
> Note that this means that a document cannot be moved between organizations
> or groups or it will lose its "identity". (eg. an organization changes its
> name, a document changes groups such as by being moved into a different
> package, etc. ) The versions before the move will belong to a different
> series from those versions after the move.  Fundamentally, the part of the
> URN which describes the series should never change, even if the old labels
> no longer accurately describe the document, because this part of the URN
> is being used to identify the document series.
> 
> So, we have a few choices here:
> 
> 1) Use the URN's as if they are metadata and change the URN if the
> organization, doc name, or doc group changes.  This undermines the purpose
> of having a document series identifier.  We could do it anyway and just
> live with a certain level of breakage in the system, but this does not
> seem like The Right Way.
> 
> 2) Try to enforce that once the document series portion of the URN is set,
> it should not be changed.  This is the behavior one expects from a
> document series identifier.  However, it seems odd since the URN looks
> like metadata and people would not want "incorrect" metadata.  Plus, most
> people will probably not realize they should not change this part and
> change it anyway.
> 
> 3) Go back to using the uuidgen system (or some other system) for series
> id's.  Note that we may still use URN's for unique document identifiers.
> We would be going back to the original plan of having two identifiers: one
> for the doc series and one as a unique resource identifier.  If we do
> this, we would have to seperately evaluate whether URN's or uuidgen are
> better for the unique document identifiers.
> 
> 4) ???
> 
> Although I had really warmed up to the URN idea, I see this as a serious
> problem. I don't see #1 or #2 as proper solutions.  My inclination at this
> point it to use #3.
> 
> Thoughts?

Seems like a valid point, we should probably go with the uuidgen then. 

Laszlo

Re: [Scrollkeeper-devel] Better internationalization support

[Bob S. <bo...@sc...>]

> From: Dan Mueth <da...@ea...>
>
> So, we would have:
> 
> urn:x-omf1:organization:group:name:version:language:format
> 
> where organization will normally be a domain and group is whatever the
> coordinators for that domain choose (package, project, etc.)

I seem to have missed the introduction of :group: in
the URN.  Is that necessary to establishing a document
"name" part?  Or is it part of the metadata (in which case
shouldn't it be in the OMF metadata elements)?
 
> The part of this which will be used to identify a series of a document
> (different versions, formats, and languages) is:
> 
> urn:x-omf1:organization:group:name
> 
> Note that this means that a document cannot be moved between organizations
> or groups or it will lose its "identity". (eg. an organization changes its
> name, a document changes groups such as by being moved into a different
> package, etc. ) The versions before the move will belong to a different
> series from those versions after the move.  Fundamentally, the part of the
> URN which describes the series should never change, even if the old labels
> no longer accurately describe the document, because this part of the URN
> is being used to identify the document series.
> 
> So, we have a few choices here:
> 
> 1) Use the URN's as if they are metadata and change the URN if the
> organization, doc name, or doc group changes.  This undermines the purpose
> of having a document series identifier.  We could do it anyway and just
> live with a certain level of breakage in the system, but this does not
> seem like The Right Way.  

I agree, changing the URN of a specific version of a
document is The Wrong Way.  The purpose of URNs is to
be a permanent name for a specific document.  If you start
changing them, we couldn't call them URNs.
 
> 2) Try to enforce that once the document series portion of the URN is set,
> it should not be changed.  This is the behavior one expects from a
> document series identifier.  However, it seems odd since the URN looks
> like metadata and people would not want "incorrect" metadata.  Plus, most
> people will probably not realize they should not change this part and
> change it anyway.

You are probably right.  The URN isn't metadata, it is a
pointer to a document and its associated metadata.
According the URN RFCs, the OMF would be the ultimate
authority of how this namespace is to be interpreted.  But
I could see how someone who doesn't refer to the namespace
definition could be confused when they don't match.
 
> 3) Go back to using the uuidgen system (or some other system) for series
> id's.  Note that we may still use URN's for unique document identifiers.
> We would be going back to the original plan of having two identifiers: one
> for the doc series and one as a unique resource identifier.  If we do
> this, we would have to seperately evaluate whether URN's or uuidgen are
> better for the unique document identifiers.

I agree.  I don't think the document ID should try to
carry a series ID.  The principle purpose of a document ID
is to uniquely and permanently identify a particular
document.  Trying to force it to also function as a series ID
leads to the contradictions that Dan points out.

Dan's option #3 would make a series ID into another piece of
information that is associated with a document. 
That frees the URN name to track the current
organization for each version.

But I'm not clear where a series ID fits into the OMF
metadata DTD.  If I understand you correctly, the same
series ID would be applied to every version/language/format
of a document in its history, including when it changes
hands.  But the OMF <identifier> element is supposed to be
unique to each document.

I would propose instead using the OMF <relation> element,
with its url attribute pointing to a series ID.  By that I
mean define a seriesID using uuidgen as Dan suggests.  Then
the OMF metadata for each document includes

<relation url="thisseriesUUID" status="omf-series-id"/>

This defines a relationship between this document and the
series of which it is a part.  Then you could query an OMF
metadata collection to select all documents that share the
same relation element.  From that you could select specific
alternate version/language/format documents.

Would this be a correct usage of the <relation> element?
Would it meet the needs of a seriesID?

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bo...@sc...

Re: [Scrollkeeper-devel] Better internationalization support

[Dan M. <da...@ea...>]

On Fri, 20 Apr 2001, Laszlo Kovacs wrote:

> So I thought maybe an OMF URN version field should be added, like:
> 
> urn:x-omf:omf-urn-version:organization:group:name:version:language:format 
> 
> where omf-urn-version is for internal purpose to track changes in our
> URN structure. Although we could also use x-omf1, x-omf2 etc instead of
> x-omf. Do people think this would be useful?

So, we would have:

urn:x-omf1:organization:group:name:version:language:format

where organization will normally be a domain and group is whatever the
coordinators for that domain choose (package, project, etc.)

The part of this which will be used to identify a series of a document
(different versions, formats, and languages) is:

urn:x-omf1:organization:group:name

Note that this means that a document cannot be moved between organizations
or groups or it will lose its "identity". (eg. an organization changes its
name, a document changes groups such as by being moved into a different
package, etc. ) The versions before the move will belong to a different
series from those versions after the move.  Fundamentally, the part of the
URN which describes the series should never change, even if the old labels
no longer accurately describe the document, because this part of the URN
is being used to identify the document series.

So, we have a few choices here:

1) Use the URN's as if they are metadata and change the URN if the
organization, doc name, or doc group changes.  This undermines the purpose
of having a document series identifier.  We could do it anyway and just
live with a certain level of breakage in the system, but this does not
seem like The Right Way.  

2) Try to enforce that once the document series portion of the URN is set,
it should not be changed.  This is the behavior one expects from a
document series identifier.  However, it seems odd since the URN looks
like metadata and people would not want "incorrect" metadata.  Plus, most
people will probably not realize they should not change this part and
change it anyway.

3) Go back to using the uuidgen system (or some other system) for series
id's.  Note that we may still use URN's for unique document identifiers.
We would be going back to the original plan of having two identifiers: one
for the doc series and one as a unique resource identifier.  If we do
this, we would have to seperately evaluate whether URN's or uuidgen are
better for the unique document identifiers.

4) ???

Although I had really warmed up to the URN idea, I see this as a serious
problem. I don't see #1 or #2 as proper solutions.  My inclination at this
point it to use #3.

Thoughts?

Dan

Re: [Scrollkeeper-devel] Better internationalization support

[Laszlo K. <las...@Su...>]

> I did some more research on URNs.  The first thing I learned
> is that there is no universal system in place for resolving
> URNs over the Internet.  The DNS resolution protocol described
> in RFC2168 (June 1997) appears to have never gotten past the
> Experimental stage.
> 
> I wasn't really thinking in terms of Internet resolution
> of URNs, just using the URN syntax to define unique OMF
> identifiers.  I found RFC 2611 "URN Namespace
> Definition Mechanisms" (June 1999) that provides guidance
> for doing that.  Section 4.0 defines three categories
> of URN namespaces:
> 
> I. Experimental: which are not registered with IANA.
> They take the form "X-anyname". There is no provision
> for avoiding collisions. They are intended for use within
> internal or limited experiemental contexts.
> 
> II.  Informal: which are registered with IANA, and
> take the form "urn-number", where the number is assigned
> by IANA.
> 
> III. Formal: which are registered with IANA, and where
> you get to pick the name.  The catch is that it is
> processed through an RFC review process, although not
> "standards-track".  There seem to be very few RFCs
> requesting formal URNs.
> 
> The first category (X-name) would permit us to
> use URNs in a valid fashion, yet avoid the need
> to register a namespace.  Registration doesn't gain us much if
> there is no global resolution mechanism.  Experimental
> namespaces define their own mechanism for resolving
> items in their name space.  OMF URNs would only
> be resolvable in the OMF scope, but that would work
> for ScrollKeeper.  So a valid NID could be "x-omf".
> 
> I also found examples of namespaces that use ":" to
> separate fields in their NSSs (the part after the
> namespace in the URN).  So rather than proliferate
> organization NIDs, we could make it part of
> the NSS in a single x-omf namespace:
> 
> urn:x-omf:organization:name:version:language:format
>     <-->  <--------------------------------------->
>     NID                   NSS
> 
> So this would be a valid URN that uniquely identifies
> a document for a given version, language, and format:
> 
>   urn:x-omf:kde.org:GetStart:1.2:en:html
> 
> You could use a fragment of this to reference what you
> call a document group:
> 
>   urn:x-omf:kde.org:GetStart
> 
> refers to all versions, languages, and formats of the
> KDE Getting Started guide.
> 
> This syntax could also be useful for queries:
> 
>   urn:x-omf:kde.org:GetStart:*:fr:*
> 
> which requests any french version of the document,
> perhaps defaulting to the latest HTML version in
> the context of ScrollKeeper.
> 
> Managing this single namespace would be up to OMF.
> They would assign organization subspaces, without
> a need for IANA or RFCs.  Those organizations would
> assign their document names in a unique fashion.
> 
> In the future, if this experimental namespace
> proves valuable and some global resolution
> mechanism becomes available, OMF could apply for
> a formal namespace identifier.
> 
> Coments?
> 

Bob,

We discussed this on IRC yesterday and we decided to go this way (per
your suggestion):
 
urn:x-omf:organization:name:version:language:format
    <-->  <--------------------------------------->
    NID                   NSS

This will give us a unique ID and a non-unique ID also. At the moment it
will be the docwriters, developers task to manage their namespaces. I
think we will write up a recomendation of how to do it so that the URNs
will be as unique as possible. I raised during the discussion that we
could have another field between "organization" and "name" like
"package" or "project" or a more generic one like "group". I also
thought this morning that we might end up with having to modify the
structure of the NSS which would be a problem with maintaining
compatibility at the same time. So I thought maybe an OMF URN version
field should be added, like:

urn:x-omf:omf-urn-version:organization:group:name:version:language:format 

where omf-urn-version is for internal purpose to track changes in our
URN structure. Although we could also use x-omf1, x-omf2 etc instead of
x-omf. Do people think this would be useful?

Laszlo

Re: [Scrollkeeper-devel] Better internationalization support

[Bob S. <bo...@sc...>]

> From: Dan Mueth <da...@ea...>
> 
> On Wed, 18 Apr 2001, Bob Stayton wrote:
> 
> > I read the OMF element descriptions again and I think
> > we need to be careful how we use the <identifier> element.
> > According to the description, <identifier> is a URI
> > that points to a unique document.  Since <identifier> is part
> > of an OMF record, and since an OMF record also has
> > elements for the document's language, version, and
> > format, I interpret the <identifier> element to be
> > a reference to one combination of
> > document+language+version+format.  Each such combination
> > would have its own OMF record.
> > 
> > But you would like to be able to use a fallback mechanism
> > that permits providing access to alternate versions,
> > languages, or formats, depending on the needs of the user,
> > right?
> > 
> > A simple URN like <urn:kde:GetStart> is really an abstract
> > reference to the collection of all combinations of
> > language+version+format for the KDE getting started guide.
> > If the identifier is in a parsible format, such as
> > name+language+version+format, then it is unique and yet it
> > can be picked apart as needed for fallback along
> > any of the dimensions.  
> > 
> > Using a fixed field format:
> > 
> > <urn:kde:GetStart+en+3.1+pdf>
> > 
> > or maybe a more flexible URL syntax which identifies
> > each field:
> > 
> > <urn:kde:GetStart?lang=en&version=3.1&format=pdf>
> 
> Everything you say seems right, and this approach should work. (Although I
> think a couple small details of the syntax would have to be
> changed: http://www.ietf.org/rfc/rfc2141.txt .)
> 
> This would solve a few problems at once - the unique id, the document set
> id, and it would allow us to integrate with the URN resource location
> system.
> 
> It seems somewhat complicated though and would be a substantial amount of
> work to achieve.  We would have to go through the application and review
> procedure to get our NID, which I'm guessing is enough trouble that few
> people would want to get their own NID.  Then, we would have to actively
> manage a pretty large set of NSS's.  This would probably only be tractable
> if we had an automatic system to handle requests.
> 
> If we just wanted to solve the document set id problem, then using uuidgen
> would be a much simpler solution, both as an organization and for
> individuals.  So, whether we would use something like this largely comes
> down to how important it is that we adopt the URN system for its own
> value.  I don't know enough about the URN system to know how widely
> adopted it is or what tools exist to take advantage of it.  Could you fill
> us in here?  
>
> Do DNS servers currently support URN's?
> 
> Note we could still use the URN system with uuidgen:
> 
> "urn:gnome.org:`uuidgen`"
> 
> which would remove most of the admin headache.  We would need a seperate
> id using uuidgen for the document groups (all formats, locales, and
> versions of a document).

I did some more research on URNs.  The first thing I learned
is that there is no universal system in place for resolving
URNs over the Internet.  The DNS resolution protocol described
in RFC2168 (June 1997) appears to have never gotten past the
Experimental stage.  

I wasn't really thinking in terms of Internet resolution
of URNs, just using the URN syntax to define unique OMF
identifiers.  I found RFC 2611 "URN Namespace
Definition Mechanisms" (June 1999) that provides guidance
for doing that.  Section 4.0 defines three categories
of URN namespaces:

I. Experimental: which are not registered with IANA.
They take the form "X-anyname". There is no provision
for avoiding collisions. They are intended for use within
internal or limited experiemental contexts.

II.  Informal: which are registered with IANA, and
take the form "urn-number", where the number is assigned
by IANA.

III. Formal: which are registered with IANA, and where 
you get to pick the name.  The catch is that it is
processed through an RFC review process, although not
"standards-track".  There seem to be very few RFCs 
requesting formal URNs.

The first category (X-name) would permit us to
use URNs in a valid fashion, yet avoid the need
to register a namespace.  Registration doesn't gain us much if
there is no global resolution mechanism.  Experimental
namespaces define their own mechanism for resolving
items in their name space.  OMF URNs would only
be resolvable in the OMF scope, but that would work
for ScrollKeeper.  So a valid NID could be "x-omf".

I also found examples of namespaces that use ":" to
separate fields in their NSSs (the part after the
namespace in the URN).  So rather than proliferate
organization NIDs, we could make it part of
the NSS in a single x-omf namespace:

urn:x-omf:organization:name:version:language:format
    <-->  <--------------------------------------->
    NID                   NSS

So this would be a valid URN that uniquely identifies
a document for a given version, language, and format:

  urn:x-omf:kde.org:GetStart:1.2:en:html

You could use a fragment of this to reference what you
call a document group:

  urn:x-omf:kde.org:GetStart 

refers to all versions, languages, and formats of the
KDE Getting Started guide.    

This syntax could also be useful for queries:

  urn:x-omf:kde.org:GetStart:*:fr:*

which requests any french version of the document,
perhaps defaulting to the latest HTML version in 
the context of ScrollKeeper.

Managing this single namespace would be up to OMF.
They would assign organization subspaces, without
a need for IANA or RFCs.  Those organizations would
assign their document names in a unique fashion.  

In the future, if this experimental namespace
proves valuable and some global resolution
mechanism becomes available, OMF could apply for
a formal namespace identifier.

Coments?

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bo...@sc...

Re: [Scrollkeeper-devel] Better internationalization support

[Dan M. <da...@ea...>]

On Wed, 18 Apr 2001, Bob Stayton wrote:

> I read the OMF element descriptions again and I think
> we need to be careful how we use the <identifier> element.
> According to the description, <identifier> is a URI
> that points to a unique document.  Since <identifier> is part
> of an OMF record, and since an OMF record also has
> elements for the document's language, version, and
> format, I interpret the <identifier> element to be
> a reference to one combination of
> document+language+version+format.  Each such combination
> would have its own OMF record.
> 
> But you would like to be able to use a fallback mechanism
> that permits providing access to alternate versions,
> languages, or formats, depending on the needs of the user,
> right?
> 
> A simple URN like <urn:kde:GetStart> is really an abstract
> reference to the collection of all combinations of
> language+version+format for the KDE getting started guide.
> If the identifier is in a parsible format, such as
> name+language+version+format, then it is unique and yet it
> can be picked apart as needed for fallback along
> any of the dimensions.  
> 
> Using a fixed field format:
> 
> <urn:kde:GetStart+en+3.1+pdf>
> 
> or maybe a more flexible URL syntax which identifies
> each field:
> 
> <urn:kde:GetStart?lang=en&version=3.1&format=pdf>

Everything you say seems right, and this approach should work. (Although I
think a couple small details of the syntax would have to be
changed: http://www.ietf.org/rfc/rfc2141.txt .)

This would solve a few problems at once - the unique id, the document set
id, and it would allow us to integrate with the URN resource location
system.

It seems somewhat complicated though and would be a substantial amount of
work to achieve.  We would have to go through the application and review
procedure to get our NID, which I'm guessing is enough trouble that few
people would want to get their own NID.  Then, we would have to actively
manage a pretty large set of NSS's.  This would probably only be tractable
if we had an automatic system to handle requests.

If we just wanted to solve the document set id problem, then using uuidgen
would be a much simpler solution, both as an organization and for
individuals.  So, whether we would use something like this largely comes
down to how important it is that we adopt the URN system for its own
value.  I don't know enough about the URN system to know how widely
adopted it is or what tools exist to take advantage of it.  Could you fill
us in here?  

Do DNS servers currently support URN's?

Note we could still use the URN system with uuidgen:

"urn:gnome.org:`uuidgen`"

which would remove most of the admin headache.  We would need a seperate
id using uuidgen for the document groups (all formats, locales, and
versions of a document).

Dan

Re: [Scrollkeeper-devel] Better internationalization support

[Bob S. <bo...@sc...>]

> From: Laszlo Kovacs <las...@su...>
> 
> > In December, I posted an alternative approach
> > using URNs.  
> > [stuff deleted]
> 
> I read that email back in December, but this explanation above seems to
> clarify loads of things. I think I like this idea. At the bottom of your
> previous email you suggested that omf should be the namespace for every
> document handled by Scrollkeeper. I think it would be better if this
> would be named after the organization or project who produces the ID.
> Like urn:gnome:... or urn:kde:... . If we use omf for namespace then I
> think we will need to validate the URNs used by developers of various
> projects, while otherwise this would be done by them. We just need to
> publish a description about how the URNs should be created.

Yes, I agree.  
 
> If we do it like this then we just have to publish this recommendation
> and we are done. And I can start development:-)
> 
> Note that I still see this mainly as support for identifying a doc and
> all its translations uniquely. So these documents should all hold the
> same id. Therefore using the <identifier> tag from OMF might not be the
> best for this as the only way I can figure out that this is the ID that
> is the same for the doc and all its translations is that it begins with
> the word "urn". If we want to use URNs later for something else then we
> would be in trouble, I think. It could be something like
> urn:translation:... so we know that this URN is for translation
> identification. In which case only the last part of the URN is available
> to identify the doc and that might not be enough to keep the uniqueness
> of the ID. 
> 
> But I really think generally this is the way to go.
> 
> Thoughts?

I read the OMF element descriptions again and I think
we need to be careful how we use the <identifier> element.
According to the description, <identifier> is a URI
that points to a unique document.  Since <identifier> is part
of an OMF record, and since an OMF record also has
elements for the document's language, version, and
format, I interpret the <identifier> element to be
a reference to one combination of
document+language+version+format.  Each such combination
would have its own OMF record.

But you would like to be able to use a fallback mechanism
that permits providing access to alternate versions,
languages, or formats, depending on the needs of the user,
right?

A simple URN like <urn:kde:GetStart> is really an abstract
reference to the collection of all combinations of
language+version+format for the KDE getting started guide.
If the identifier is in a parsible format, such as
name+language+version+format, then it is unique and yet it
can be picked apart as needed for fallback along
any of the dimensions.  

Using a fixed field format:

<urn:kde:GetStart+en+3.1+pdf>

or maybe a more flexible URL syntax which identifies
each field:

<urn:kde:GetStart?lang=en&version=3.1&format=pdf>

You want the French version?  Then find the OMF record
whose urn substitutes lang=fr, possibly with some
flexibility in version (in case the latest english
version hasn't been translated) and format.

Special characters would be escaped with %XX.
Kind of ugly, but I guess not any uglier than a UUID. 8^)

I also note that <identifier> is a repeatable element in
the OMF DTD.  That means an OMF record could have one
<identifier> whose attribute is an http: address and
another using the urn: prefix to provide this other
information.

So now I've turned a simple scheme into a more complicated
one, but it is more rigorous and I think meets the
needs for a fallback mechanism.

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bo...@sc...

Re: [Scrollkeeper-devel] Re: ScrollKeeper

[Greg F. <gf...@ho...>]

On Apr 17, 10:27am, Eric Bischoff wrote:
> Subject: [Scrollkeeper-devel] Re: ScrollKeeper
>
> > ...
> > BTW, I found this rather astonishing line in the LDP
> > Author Guide Chapter 4 (thanks to an htdig search for XSL
> > on the latest Sybil):
> >
> > $JADE -t sgml -i xml -d
/home/ldp/SGML/style/xsl/docbook/html/docbook.xsl $DOCUMENT.sgml
> >
> > This sure looks to me like jade is processing an SGML file
> > with an xsl stylesheet, but that would be a pretty good
> > trick, don't you think?   8^)
>
> Hey, if someone can do that, I'm more than happy ;-).
>
> No, seriously, this must be a bug. Jade is a DSSS=B5=B5L engine, not
> an XSL engine.

Not a bug; it's a typo in the doc which has since been corrected.

Latest - http://www.linuxdoc.org/LDP/LDP-Author-Guide/jade.html
("3.3.1.2. Jade in XML mode")

I believe the line you are referring to now reads:

  jade -t sgml -i html -d <style> $_jade_path/pubtext/xml.dcl foo.xml

r,
Ferg

Re: [Scrollkeeper-devel] Better internationalization support

[Laszlo K. <las...@Su...>]

> In December, I posted an alternative approach
> using URNs.  I didn't get any response at the time,
> perhaps because my mail was so long.  8^)
> A URN is human comprehensible, can be generated
> locally without tools, and, by following a simple
> namespace convention, can be globally unique.
> 
> The syntax of a URN is:
> 
>    urn:namespaceID:documentID
> 
> The "urn:" part is fixed, and the other two parts
> are assigned by the document originator.
> Each organization can define its own namespaceID,
> and then they just need to keep their own documentIDs
> unique within that namespace.
> 
> The key to global uniqueness is ensuring that
> each namespaceID is unique.  This can generally
> be achieved today by following the convention
> of using their own IP name, such as apache.org
> or ldp.org.  If an individual lacks an IP name, they can apply
> to OMF to register their documents under the omf.org
> namespace.
> 
> So the LDP could use URNs such as:
> 
> urn:ldp.org:SysAdminG
> urn:ldp.org:ls.man.1
> etc.
> 
> I've attached my original mail which provides further
> background information and references on URNs.

I read that email back in December, but this explanation above seems to
clarify loads of things. I think I like this idea. At the bottom of your
previous email you suggested that omf should be the namespace for every
document handled by Scrollkeeper. I think it would be better if this
would be named after the organization or project who produces the ID.
Like urn:gnome:... or urn:kde:... . If we use omf for namespace then I
think we will need to validate the URNs used by developers of various
projects, while otherwise this would be done by them. We just need to
publish a description about how the URNs should be created.

If we do it like this then we just have to publish this recommendation
and we are done. And I can start development:-)

Note that I still see this mainly as support for identifying a doc and
all its translations uniquely. So these documents should all hold the
same id. Therefore using the <identifier> tag from OMF might not be the
best for this as the only way I can figure out that this is the ID that
is the same for the doc and all its translations is that it begins with
the word "urn". If we want to use URNs later for something else then we
would be in trouble, I think. It could be something like
urn:translation:... so we know that this URN is for translation
identification. In which case only the last part of the URN is available
to identify the doc and that might not be enough to keep the uniqueness
of the ID. 

But I really think generally this is the way to go.

Thoughts?

Laszlo

Re: [Scrollkeeper-devel] SK mini-roadmap

[Laszlo K. <las...@su...>]

----- Original Message -----
From: "Dan Mueth" <da...@ea...>
To: "ScrollKeeper Devel" <scr...@li...>
Sent: Tuesday, April 17, 2001 5:11 PM
Subject: [Scrollkeeper-devel] SK mini-roadmap


>
> Laszlo,
>
> I'm trying to assemble our plans just a bit.  It looks like we have 4
> developments in the near future:
>
> A) Move SK to libxml2
> B) i18n improvements
> C) Support relocatable packages
> D) indexing/searching
>
> Am I missing anything we need to do in the short term?
No probably not.

> Is this the order we plan to implement things?
The TOC extractor can not be moved to libxml2 as long as the SGML->XML
parser does not work. We might still want to create another XSL based TOC
extractor for DocBook XML docs. That way we would support both DocBook SGML
and DocBook XML (if we want to do this). Another option is to move all of
Scrollkeeper to libxml2 apart from the TOC extractor, this would be really
quick to do. Probably up to one day. And it is possible technically. Then
we'll see what to do with the TOC extractor.

> What is the status on (A).  Is (A) pretty hard or going to take a lot of
> time?
The TOC extractor is the real problem as I said above, the rest can be moved
quickly.

>
> I don't see much point in making a new stable release for (A) since it
> doesn't have user-visible changes.  I'm tempted to make a new release for
> each of the other points unless (C) is easy/fast enough to lump in with
> (B) without delaying it much.  So, I have:
>
>    Release Number         Changes            Est. Release Date
>    --------------         -------            -----------------
>     0.3.x / 0.4         (A) and (B)             late May
>     0.5.x / 0.6             (C)                 late June
>     0.7.x / 0.8             (D)                 mid July

I dont know how much C would take, I think we can decide about a separate
release for it later.

> If we think (A) will take a long time, we may want to do (B) first since
> we get important functionality from (B).  However, if Mary needs (A) to do
> (D), we may have to do (A) before (B).
That develops on the approach, if she develops a new binary then that can be
linked to libxml2 regardless of what the rest of Scrollkeeper is linked to.

Laszlo

[Scrollkeeper-devel] Better internationalization support

[Bob S. <bo...@sc...>]

> 2. This is the long discussed document ID and this is what I would like
> to address. We want an ID that is the same a document and all of its
> translations and it allows to find the English doc if the translated one
> is not there or fall back to other translations of the doc (like first
> to German then to English if the French is not there. I think the main
> problem is not how to implement the fallback mechanism, but how to
> assign these IDs, how to make the docwriters, translators to request the
> ID and how to send it to them. It should be very easy for anybody to
> generate an ID like this. Then I think it should be down to the
> docwriters, translators to make sure to use the same ID for a doc and
> all of its translations. Uidgen was mentioned to be used to generate the
> IDs. As this is not available on every platform a web based request
> mechanism with a Linux server could be a good approach (like ask the
> Linux server for a number). This should probably all be hidden inside a
> Scrollkeeper script or binary that just retrieves an ID whenever run. 

> Any thoughts?

> Laszlo

In December, I posted an alternative approach
using URNs.  I didn't get any response at the time,
perhaps because my mail was so long.  8^)
A URN is human comprehensible, can be generated
locally without tools, and, by following a simple
namespace convention, can be globally unique.

The syntax of a URN is:

   urn:namespaceID:documentID

The "urn:" part is fixed, and the other two parts
are assigned by the document originator.
Each organization can define its own namespaceID,
and then they just need to keep their own documentIDs
unique within that namespace.

The key to global uniqueness is ensuring that
each namespaceID is unique.  This can generally
be achieved today by following the convention
of using their own IP name, such as apache.org
or ldp.org.  If an individual lacks an IP name, they can apply
to OMF to register their documents under the omf.org
namespace.

So the LDP could use URNs such as:

urn:ldp.org:SysAdminG
urn:ldp.org:ls.man.1
etc.

I've attached my original mail which provides further
background information and references on URNs.

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bo...@sc...