scrollkeeper-devel

Re: [Scrollkeeper-devel] Simple URI's

[Ali A. <ALI...@au...>]

On Tue, 28 Nov 2000, Dan Mueth wrote:

> 
> GNOME uses a "gnome-help" URI scheme.  So if you type
> "gnome-help:gnumeric", it looks in
> $prefix/share/gnome/help/gnumeric/<locale>/ and looks for the doc under
> the name gnumeric.sgml or else index.html.  It is a very convenient way to
> find a manual.  It also allows for cross-referencing of documents very
> simply since any document you write knows that "gnome-help:gnumeric" will
> point to the Gnumeric manual regardless of where things are installed (eg.
> under /usr or /opt or ...).
> 
> The problem with this is:
> 1) other help browsers have to understand how to handle the
> "gnome-help" URI scheme
> 2) presumably other desktops will introduce more URI schemes
> 3) many docs won't be addressable at all this way unless scrollkeeper
> provides a mechanism.
> 
> So probably what we want is to introduce a scheme which passes the
> identifier (what is the right term here?) to scrollkeeper which can return
> the path.  So for example, one would use: "sk-help:modem-HOWTO".  It
> would have to find the doc (and select from any available versions,
> languages, formats) and then display it.  This would be *very* useful IMO,
> both for users as well as for cross-referencing between documents.

This is a good idea
 
> A couple issues which pop up:
> 
> 1) Selecting the right doc.  We could have a default setting for language
> (just use the current locale), formats (perhaps in /etc/sk.conf we list in
> order of preference), and versions (show the biggest version number).

Use the current locale for "default", then fallback to the 'C' locale.

I think you also need to do some i18n handling (i.e. LANG can be a 
delimited list of locales (or is that LC_ALL?) (e.g. export 
LANG=fr_BR:fr_FR:en_GB:en_US)

> 2) Mapping the names.  The OMF file should specify the name by which the
> document should be referred.  This seems to require yet another OMF
> attribute to be created, perhaps IDENTIFIER.URINAME?  We will not have
> complete uniqueness here.  However ideally we will have a 1-1
> correspondence between NUID's and URINAME's.  We could keep a database on
> the web so people can register names and find out if a name is taken.  
> This creates even more administrative overhead, but I think it is well
> worth the trouble it would take to set up a simple php/mysql site on
> SourceForge.

Not sure this is a good idea...you will have to have a 'URINAME' if you 
are typing the URI manually.

BUT:

I think that applications should give scrollkeeper a "title", locale 
(optional), and version # (optional), format (default would be Docbook). 
Scrollkeeper would then search its database and return the unique IDs 
(possible there will be more than one doc matching the criteria, so the 
client would either pick the first one, or try to do some other 
processing (e.g: See Also)).

You could also have another function that would return the "first found 
match" of the document directly (so you don't have to search for UUID, 
and then tell scrollkeeper to return this document - you just tell it 
"return the first document that matches this criteria").

Anyway, this approach would only work if you have a list of documents to 
choose from. 

So, maybe URINAME's are the way to go.

Re: [Scrollkeeper-devel] Simple URI's

[Ali A. <ALI...@au...>]

On Mon, 4 Dec 2000, Nik Clayton wrote:

> On Mon, Dec 04, 2000 at 10:10:25AM -0600, Dan Mueth wrote:
> > On Mon, 4 Dec 2000, Laszlo Kovacs wrote:
> > > > Let the users use bookmarks.  On a network with multiple architectures,
> > > > does "modem-HOWTO" refer to the Linux, FreeBSD, or Solaris document?
> > 
> > Bookmarks won't help here.  Bookmarks do not provide a mechanism for one
> > document to cross-reference another, 
> 
> Nor should they.  Document cross references are going to be a pain in
> the backside, which ever way you cut it.  I don't think is really within
> sk's purview.
> 
> [ For example, suppose I have a document that references modem-HOWTO in
>   a link.  What happens to the link if modem-HOWTO hasn't been
>   installed?  Is it active (and generates an error if it's clicked), or
>   is it inactive, or what? ]
> 
> > nor do they help a user find a document they've never seen before.  
> 
> That's what the index, table of contents, and free text search are for.


I agree - it will be a pain to support cross references properly (I wrote 
this in a previous mail but its stuck in the mail spool at home! DOH)

I think if people want "cross-links" they should use a 'See Also' at the 
end of the document

Regards,
Ali

Re: [Scrollkeeper-devel] Simple URI's

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

> > 2) Mapping the names.  The OMF file should specify the name by which the
> > document should be referred.  This seems to require yet another OMF
> > attribute to be created, perhaps IDENTIFIER.URINAME?  We will not have
> > complete uniqueness here.  However ideally we will have a 1-1
> > correspondence between NUID's and URINAME's.  We could keep a database on
> > the web so people can register names and find out if a name is taken.
> > This creates even more administrative overhead, but I think it is well
> > worth the trouble it would take to set up a simple php/mysql site on
> > SourceForge.
> 
> Not sure this is a good idea...you will have to have a 'URINAME' if you
> are typing the URI manually.
> 
> BUT:
> 
> I think that applications should give scrollkeeper a "title", locale
> (optional), and version # (optional), format (default would be Docbook).
> Scrollkeeper would then search its database and return the unique IDs
> (possible there will be more than one doc matching the criteria, so the
> client would either pick the first one, or try to do some other
> processing (e.g: See Also)).
> 
> You could also have another function that would return the "first found
> match" of the document directly (so you don't have to search for UUID,
> and then tell scrollkeeper to return this document - you just tell it
> "return the first document that matches this criteria").
> 
> Anyway, this approach would only work if you have a list of documents to
> choose from.
> 
> So, maybe URINAME's are the way to go.

Are you suggesting to try to partially match the string from the
Scrollkeeper URI with the "title" that you described above? 

Laszlo

Re: [Scrollkeeper-devel] Simple URI's

[Ali A. <ali...@au...>]

* Laszlo Kovacs (las...@su...) wrote at 21:43 on 29/11/00:
> > > 2) Mapping the names.  The OMF file should specify the name by which the
> > > document should be referred.  This seems to require yet another OMF
> > > attribute to be created, perhaps IDENTIFIER.URINAME?  We will not have
> > > complete uniqueness here.  However ideally we will have a 1-1
> > > correspondence between NUID's and URINAME's.  We could keep a database on
> > > the web so people can register names and find out if a name is taken.
> > > This creates even more administrative overhead, but I think it is well
> > > worth the trouble it would take to set up a simple php/mysql site on
> > > SourceForge.
> > 
> > Not sure this is a good idea...you will have to have a 'URINAME' if you
> > are typing the URI manually.
> > 
> > BUT:
> > 
> > I think that applications should give scrollkeeper a "title", locale
> > (optional), and version # (optional), format (default would be Docbook).
> > Scrollkeeper would then search its database and return the unique IDs
> > (possible there will be more than one doc matching the criteria, so the
> > client would either pick the first one, or try to do some other
> > processing (e.g: See Also)).
> > 
> > You could also have another function that would return the "first found
> > match" of the document directly (so you don't have to search for UUID,
> > and then tell scrollkeeper to return this document - you just tell it
> > "return the first document that matches this criteria").
> > 
> > Anyway, this approach would only work if you have a list of documents to
> > choose from.
> > 
> > So, maybe URINAME's are the way to go.
> 
> Are you suggesting to try to partially match the string from the
> Scrollkeeper URI with the "title" that you described above? 

Well, you could use the title - but you would have to implement proper URI
escaping/handling (i.e. use %20 instead of a space, etc.)

This would suck though, because people are not going to make links to
sk-help:PPP%20HowTo (note: it would be case sensitive so HowTo may not work
(it might be HOWTO, or Howto - or it even could be 'How-to' or 'HOW-TO', etc.)
The title could be 'Gnumeric Manual' and people will not want to type all of
that out (and they may forget its name, was it 'Gnumeric manual?' or 'Gnumeric
Help', or 'Gnumeric Tutorial', etc.)

So I don't think title is a good idea.

We have the option of a new field called 'URINAME'. This means that there
needs to be a 'unique' URINAME for each help file, so the line between UUIDs
and URINAMEs become blurred (the only diff. is a doc in another locale has a
diff. UUID, but the same URINAME)...

I suggest you just go ahead and add an extra URINAME field (note you will
still need to handle propery escaping, but I doubt people will make the
URINAME "complex" (otherwise doc. authors just wont' link to it because they
can't remember the proper URINAME to use).

Regards,
Ali