Menu
▾
▴
scrollkeeper-devel
|
From: Dan M. <d-...@uc...> - 2000-11-28 07:47:32
|
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. 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). 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. Thoughts? Dan |
|
From: Laszlo K. <las...@su...> - 2000-11-29 14:04:21
|
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. > > 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). > > 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. > > Thoughts? > > Dan > I think it is a good idea. The Gnome scheme definitely look simple, something similar would be useful. We just need to figure out how feasible it is to implement this with Scrollkeeper. Laszlo |
|
From: Nik C. <ni...@no...> - 2000-12-04 13:18:04
|
[ Sorry for the delay in some of these, free time tends to come in
discrete bursts for me ]
On Tue, Nov 28, 2000 at 01:47:29AM -0600, 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
Big problem.
> 2) presumably other desktops will introduce more URI schemes
Wouldn't suprise me. Probably without thinking about what others have
been doing in this space as well.
> 3) many docs won't be addressable at all this way unless scrollkeeper
> provides a mechanism.
True.
You missed
4) The inevitable clash between two documents that want to have the
same simple name.
> 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.
Let the users use bookmarks. On a network with multiple architectures,
does "modem-HOWTO" refer to the Linux, FreeBSD, or Solaris document?
If an individual user wants to create their own aliases for
documentation, they should probably be able to do so. The user can then
have the burden of deciding which short name maps to which document, and
is in a much better position to know that they want "modem-HOWTO" to
point to the Solaris document.
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
|
|
From: Laszlo K. <las...@su...> - 2000-12-04 13:27:53
|
> Let the users use bookmarks. On a network with multiple architectures, > does "modem-HOWTO" refer to the Linux, FreeBSD, or Solaris document? > > If an individual user wants to create their own aliases for > documentation, they should probably be able to do so. The user can then > have the burden of deciding which short name maps to which document, and > is in a much better position to know that they want "modem-HOWTO" to > point to the Solaris document. > Or the sysadmin decides where these URI's point to depending on machine type. Laszlo |
|
From: Dan M. <d-...@uc...> - 2000-12-04 16:10:30
|
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 do they help a user find a document they've never seen before. Bookmarks are great, but they serve a different purpose. > > If an individual user wants to create their own aliases for > > documentation, they should probably be able to do so. The user can then > > have the burden of deciding which short name maps to which document, and > > is in a much better position to know that they want "modem-HOWTO" to > > point to the Solaris document. > > > > Or the sysadmin decides where these URI's point to depending on machine > type. We need to have a reasonable "default" document chosen. For any given document (ie a set of documents with different versions, languages, and formats but usually the same author and title) we will need to default to a reasonable choice. (We probably also want a way to return them all to choose from.) This was in the original post. The sysadmin will indirectly be determining where these URI's point to by specifying the default COVERAGE.OS in /etc/sk.conf. So sk will know to return documents that apply to that OS (and in the right language, and for the right distribution, ...). That is why we have all this great metadata - so the sys admin and user don't have the burden of doing everything by hand. Dan |
|
From: Nik C. <ni...@no...> - 2000-12-04 20:09:58
|
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. N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery |
|
From: Dan M. <d-...@uc...> - 2000-12-06 06:50:53
|
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? ] The name scheme will make things nice enough that people can cross-reference and that users can type in simple-to-remember URI's. It will not be a perfect system. I could always create a document which tries to cross-reference obscure documents and thus will have broken links. I don't think the possibility of broken links should scare us away from a very useful and powerful tool though. We can always work around this in various ways. A smart help browser could check links before displaying them (ie. throw out broken links). Or, a help browser connected to the Net would not generally have broken links if we have a large document database (MetaLab). At least in the short term, we could just recommend that people link to documents that they can confidently say will be there. For example any GNOME application can link to docs shipped with gnome-core or gnome-libs or any other document shipped in the given package. Even if we discourage cross-referencing documents that are not provided in the package dependencies we would still have a very useful tool. I know that with GNOME, 99% of the links we want to make between documents are guaranteed to be functional due to package dependencies. If we have broken links, then it is our fault, just like if we have broken images, broken translations, or broken applications. If we *really* need to make a link from foo to bar, then we can always list it in the dependencies. > > 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. Yes. But people still type in URL's even though they have search engines, web portals, bookmarks, etc. It is just another way to find a document which in many cases is a lot faster and easier than the other methods. No, people won't die without it. But yes, it would be a very useful tool. Dan |
|
From: Ali A. <ali...@au...> - 2000-12-04 19:05:39
|
* Laszlo Kovacs (las...@su...) wrote at 16:36 on 04/12/00: > > Let the users use bookmarks. On a network with multiple architectures, > > does "modem-HOWTO" refer to the Linux, FreeBSD, or Solaris document? > > > > If an individual user wants to create their own aliases for > > documentation, they should probably be able to do so. The user can then > > have the burden of deciding which short name maps to which document, and > > is in a much better position to know that they want "modem-HOWTO" to > > point to the Solaris document. > > > > Or the sysadmin decides where these URI's point to depending on machine > type. The "short name" should be settable by the sysadmin (for Desktop users, they are the sysadmins). Each doc should have by default its own shortname. But what should scrollkeeper do if it finds a conflict? Regards, Ali |
|
From: Ali A. <ali...@au...> - 2000-12-05 20:23:08
|
* Ali Abdin (ali...@au...) wrote at 22:26 on 04/12/00: > * Laszlo Kovacs (las...@su...) wrote at 16:36 on 04/12/00: > > > Let the users use bookmarks. On a network with multiple architectures, > > > does "modem-HOWTO" refer to the Linux, FreeBSD, or Solaris document? > > > > > > If an individual user wants to create their own aliases for > > > documentation, they should probably be able to do so. The user can then > > > have the burden of deciding which short name maps to which document, and > > > is in a much better position to know that they want "modem-HOWTO" to > > > point to the Solaris document. > > > > > > > Or the sysadmin decides where these URI's point to depending on machine > > type. > > The "short name" should be settable by the sysadmin (for Desktop users, they > are the sysadmins). Each doc should have by default its own shortname. Oh, doh - if they change the short name, there goes all your cross-references. The proper solution is to cross-reference by UUID, but that won't work...no authors would do it then... Regards, Ali |
|
From: Dan M. <d-...@uc...> - 2000-12-06 06:42:04
|
On Mon, 4 Dec 2000, Ali Abdin wrote:
> * Ali Abdin (ali...@au...) wrote at 22:26 on 04/12/00:
> > * Laszlo Kovacs (las...@su...) wrote at 16:36 on 04/12/00:
> > > > Let the users use bookmarks. On a network with multiple architectures,
> > > > does "modem-HOWTO" refer to the Linux, FreeBSD, or Solaris document?
> > > >
> > > > If an individual user wants to create their own aliases for
> > > > documentation, they should probably be able to do so. The user can then
> > > > have the burden of deciding which short name maps to which document, and
> > > > is in a much better position to know that they want "modem-HOWTO" to
> > > > point to the Solaris document.
> > > >
> > >
> > > Or the sysadmin decides where these URI's point to depending on machine
> > > type.
> >
> > The "short name" should be settable by the sysadmin (for Desktop users, they
> > are the sysadmins). Each doc should have by default its own shortname.
>
> Oh, doh - if they change the short name, there goes all your cross-references.
>
> The proper solution is to cross-reference by UUID, but that won't work...no
> authors would do it then...
You don't typically want the completely unique identification (UUID is for
{document, language, version, format}, but the document identifier (NUID
is what I called it) {document but not language, version, or format}.
This would be mapped onto names to make things "nice" like IP addresses
are mapped onto names. Of course we won't use a DNS server - we'd put the
name into the metadata and use a database on the web for reference use
only. It would still be a "first come, first serve" basis for giving out
names (like domain names), although inappropriate use would be frowned
upon of course.
Dan
|