Menu
▾
▴
Re: [Scrollkeeper-devel] Handling relocatable packages
|
From: Nik C. <ni...@no...> - 2000-12-04 20:10:17
|
On Mon, Nov 27, 2000 at 03:42:38AM -0200, Ali Abdin wrote:
> * Nik Clayton (ni...@no...) wrote at 03:22 on 26/11/00:
> > Just because the original implementors didn't provide a hook to make it
> > non-relocatable, don't assume that other's won't have done.
>
> This is not scrollkeeper's problem though. We should support both instead of
> imposing relocatable packages on people.
>
> Actually, I think if we supposed relocatable packages, we will (by definition)
> have supported non-relocatable packages, so this is a moot point.
Ah ha. Someone gets it :-) That's right exactly.
> > > Aside from rebuilding the database in cases where it becomes corrupt, I'd
> > > like this to be a zero maintenance system that works out of the box. I
> > > don't think we should focus on unusual things a SA may want to
> > > do.
> >
> > "Tools, not policy" (see, I said I'd be coming back to it). The things
> > that you are I think are unusual might be standard practice for someone
> > who wants to use sk.
>
> I think the goal is to make scrollkeeper "automated" enough so that Desktop
> users can use it (remember - Help Documents are (usually) for new users).
>
> Now if a sysadmin wanted to play around and mess with ScrollKeeper, I think
> this also should be possible. Now, what kind of things would a sysadmin want
> to do that should be supported?
It's not a "What would they want to do" thing. It's a philosophy of not
building in restrictions (like "There will only ever be one contents
list") in to the system. We might not be able to immediately see why
multiple contents lists would be useful. But the extra effort in
supporting them is useful.
<snip>
> > but we should make it possible for the SA to change this behaviour if
> > necessary.
>
> I really don't think this is a major issue (to specify which directory a file
> goes into).
It's not a major issue, no. What I'm trying to do is highlight where
people are (or could be) inadvertently hardcoding in design decisions
that haven't been thought through.
If we have a feature list that we agree with, and one of those features
is "sk will support multiple contents lists" then it's unlikely that
we'll forget that as we implement sk.
I haven't seen this sort of design document yet, and the "DD:" points in
my original message were supposed to seed that, so that we can agree on
some common functionality, irrespective of the specific implementation
details.
[ Quote kept for context ]
> > > > > Why do we specify the format on the command line? The FORMAT is specified
> > > > > in the OMF already. The packager should just install and register the
> > > > > metadata instead of putting it on the command line.
> > > >
> > > > Because at this point, all we've done is install a document with no OMF.
> > > > SK has to synthesise some OMF, based on any additional information we
> > > > give it.
> > > >
> > > > This separation is necessary to support documents that have no separate
> > > > OMF. Adding "-format" to the command line is probably going to be
> > > > easier for an end user than having to create a separate file to return
> > > > to.
> > >
> > > Perhaps we agree on this after all and are just talking past each
> > > other. So for docs with OMF we have two steps:
> > > 1) update the IDENTIFIER to point to the right URL
> > > 2) register the OMF file with sk
> > >
> > > Really, #1 is only necessary for local docs (as opposed to remote
> > > ones) and for relocatable packages.
> >
> > I think that's right. In my example, "sk-install-doc" is probably the
> > wrong name.
> >
> > Ah ha, I think I've got a work around.
> >
> > We've been going back and forth about what to do if a document doesn't
> > have OMF, or if the doc does have OMF, but the URL in the INDENTIFIER is
> > wrong, or whatever.
> >
> > So, what if we have two command, sk-generate-omf and sk-install-omf? The
> > usage for this would look something like;
> >
> > sk-generate-omf [--omf:creator ...]
> > [--omf:maintainer ...]
> > [--omf:contributor ...]
> > [--omf:title ...]
> > [--omf:date ...]
> > [<other --omf:... options]
> > file.omf
> >
> > sk-install-omf [--omf-dir ...] /path/to/omf/file
> >
> > sk-generate-omf is used to generate OMF for installation into sk. It can be
> > told about an existing OMF file (for example, if the document has been
> > distributed with an OMF file). However, it also has a series of --omf:<foo>
> > options, which are used to override the OMF in the .omf file, and replace
> > it with something else (I haven't listed them all in the synopsis above).
>
> Umm - okay, lets say I have a well-formed OMF file and then I do
> 'sk-generate-omf file.omf' - umm, what exactly has been "done" to this file?
Nothing. But if you do
sk-generate-omf --omf:creator 'Foo Bar <fo...@ex...>' file.omf
then sk-generate-omf has just rewritten the content of the CREATOR
element in file.omf.
sk-generate-omf < file.omf > file2.omf
is probably the more natural way of running it though.
> Hmm, you seem to be implying that people will not write OMF files and that
> they should be "extracted" from the docs. From my understanding, they are a
> part of the doc (there was discussion on wether to include necessary tags in
> the docs themselves, or to have separate OMF files).
Not quite. I think we need to cater for a few sets of eventualities.
1. No OMF provided, but document is in an OMF'able format, or where
some of the OMF can be extracted.
2. No OMF provided, and document is not in an OMF'able format (such
as plain text)
3. OMF provided, but it's incorrect in some way.
4. OMF provided, and it's correct.
In the case of (1) I think we need some tools that can extract OMF from
common formats (DocBook, man, LinuxDoc, ...). Whilst these tools are
not strictly part of sk itself (anyone want to start an omf-tools
project?) I think they'll be important to aid the take up of sk.
In 1, we'll also need the sk-generate-omf command to update the OMF
after it's been extracted from the source document.
In the case of (2) we'll need an sk-generate-omf command to make it easy
for the end user to generate valid OMF files.
[ To anticipate your question -- "Why not get the end user to create the
OMF files using a text editor?", I think the reason is three-fold.
First, the user doesn't need to learn a new text format.
Second, this makes it impossible for the user to create an invalid OMF
file.
Third, it insulates the end user from possible changes in the OMF file
format (i.e., the XML DTD). ]
In the case of (3), we'll need sk-generate-omf to fixup the incorrect
OMF data.
In the case of (4), we don't need to do anything.
> I think perhaps we should just allow the '--omf:' overrides in the
> sk-install-omf binary
I disagree. Don't have one tool that does multiple things, have
multiple tools that do one thing each. It's useful to be able to
generate OMF without forcing the end user to install the documentation
as part of the process.
<snip>
> > For documents that have no OMF (i.e., the author didn't provide one),
> > sk-generate-omf can be used to generate one that SK can use.
>
> I think at first, ScrollKeeper will only support DocBook SGML/XML (which I
> think is a decent goal for '1.0' (then from the experience with that we can
> possible tackle other (more difficult) file formats)).
>
> If a document does not have an OMF file, we should not attempt to "guess"
> anything in any way.
Agreed. But tools that make it easier for the end user to have a stab
at generating OMF would be useful. For example, it would greatly ease
the end user's job if they can do something like
cd /usr/share/man/man1
foreach i (*.1)
man2omf $i > /usr/local/share/omf/man/$i.omf
end
This doesn't mean that the generated OMF files are 100% correct (note:
not 'valid', as man2omf should always generate valid XML) -- for
example, the author information might say "Automatically generated by
man2omf", or some such.
As I say earlier though, this is not strictly sk's responsibility.
However, I suggest that development of small helper apps like these will
increase the speed with which people can usefully use sk on their
system.
> > The Contents List is in XML, right. XML already has a mechanism for
> > saying that a file includes other files.
> >
> > <?xml version="1.0">
> > <!DOCTYPE contents PUBLIC "-//Scrollkeeper Contents List//EN" [
> >
> > <!ENTITY contents.bio SYSTEM "/path/to/biology/contents/list">
> > <!ENTITY contents.chem SYSTEM "/path/to/chemistry/contents/list">
> >
> > ]>
> >
> > <contents>
> > &contents.bio;
> >
> > &contents.chem;
> > </contents>
> >
> > Why reinvent the wheel? All we need to do is ensure (as reasonably as
> > possible) that the identifiers in the different contents lists are
> > unique.
>
> Actually - this is a VERY good idea.
Woo hoo
[ Sorry, too much Simpsons ]
> In fact, DV just suggested this idea on
> IRC which I didn't quite understand (then I read this example and I get it)...
>
> Basically, you can have a /etc/scrollkeeper.conf file that lists all the
> directories which Scrollkeeper will scan and include as entities.
Not quite. XML can do all this for you.
Suppose, for example, that the sysadmin wants to make it easy for end
users to create their own contents lists that include the system's
installed documentation.
They might create a default Contents List that looks like this:
<?xml version="1.0">
<!DOCTYPE contents PUBLIC "-//Scrollkeeper Contents List//EN" [
<!ENTITY contents.system SYSTEM "/path/to/system/contents/list">
<!ENTITY contents.user SYSTEM "&HOME;/.sk/contents/list">
]>
<contents>
&contents.system;
&contents.user;
</contents>
There's only one peice of 'magic' in here, "&HOME;".
Basically, what I'm trying to show here is that this master contents
list would pull in the contents of /path/to/system/contents/list, and
would then pull in /home/$USER/.sk/contents/list.
So if the user goes and creates their own contents list in
~/.sk/contents/list and runs sk then they're changes are automatically
picked up.
Unfortunately, XML (and SGML) has no concept of using environment
variables inside paths like this.
What you could do is hardcode sk to recognise $HOME inside a Contents
List and automatically expand it to the appropriate environment
variable. However, that's a bit of a kludge, and also takes us outside
of XML functionality.
However, it's not too much of a stretch to say (and document) that when
SK parses a Contents List it pre-initialises a few entities for use in
the Contents List. One of those might be &HOME;, which corresponds with
$HOME, another might be &LC_LANG;, which corresponds with $LC_LANG, and
so on.
Actually, that's a pretty cool idea. You could imagine a master
Contents List that looks like
<?xml version="1.0">
<!DOCTYPE contents PUBLIC "-//Scrollkeeper Contents List//EN" [
<!ENTITY contents SYSTEM "/var/db/sk/&LC_LANG;/contents">
]>
<contents>
&contents;
</contents>
which would pick up the contents list from /var/db/sk/$LC_LANG/contents
depending on the setting of the $LC_LANG environment variable of the
person running sk.
> I have a question though. How will this work for user's directories? Does
> Scrollkeeper need to support this "indepenendently (and track it with a
> ~/.scrollkeeperrc)
See above. This approach actually lets the SA create a global config
file that automatically pulls in $HOME/.sk/, without the user needing to
do anything special. The name of the file it pulls in is completely at
the discretion of the SA.
Of course, sk would ship with defaults that show how all this works.
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
|