Menu
▾
▴
Re: [Scrollkeeper-devel] Handling relocatable packages
|
From: Nik C. <ni...@no...> - 2000-11-21 16:17:52
|
On Tue, Nov 21, 2000 at 01:34:42PM +0000, Laszlo Kovacs wrote:
> > 1. Maintaining one or more lists of documentation that the user wants
> > a TOC for (the "Contents List" from the most recent proposal)
>
> Yes, but we didn't aim for more than one.
I think we need more than one. I explain why in a bit.
> > 4. Maintaining a Categories list
>
> What is the difference between this and (1)?
Depends on whether or not sk enforces the list of categories that
documentation can be in or not. If it doesn't, then no list.
Pro: Everything's very easy.
Con: If the end user makes a typo when choosing a category for the
document, sk can't warn them about it.
> Multiple content lists would probably be a lower priority.
>
> >
> > What sort of documentation can the Contents List going to point to?
> >
> > 1. Locally installed standard documentation that comes with the system,
> > such as man pages, or Info documents.
> >
> > QUESTION: Is sk going to deal with non-SGML/XML documents, such as
> > these?
>
> It will be able to categorize them if OMF files are created for them. I
> think sk wants to categorize docs based on OMF files while the ones
> without OMF files would not be considered by it. They can be considered
> by the help browser though as it happens now with Nautilus in Gnome.
I think this is a bad idea. If you go this route then sk becomes another
format, like info, or man, or html, and the help browsers have to deal with
this, and still need to go and handle the rest of the documentation in the
system.
I think sk has a much better chance of being adopted if it is very easy for
legacy documentation to be 'adopted' by sk, so that, at the very least, the
documentation makes it in to the Contents List. Producing detailed OMF for
legacy documentation can be done after the document has been adopted.
DD: Legacy documentation (with, in the worst case, just a filename) can
be adopted by SK so that it appears in the Contents List. The end user
won't be able to do very much with it until there's meaningful OMF for
the legacy docs, but it's a start, and should assist users who want to
write OMF for legacy docs.
<snip>
> > I think it is fair to say that, when run, sk will need to construct it's
> > global Contents List by parsing multiple, smaller, contents lists. In much
> > the same way that SGML catalog files can include one another at the moment.
>
> As I said before sk works with one Content List at moment and we did not
> think about more than one. You might want to detail how you imagine
> this.
The SA generates a contents list for the host, call it /var/db/sk/contents.xml
or something (I was calling it master.xml in the previous examples).
A regular user has also installed some documentation under $HOME, and have
created $HOME/.sk/db/contents.xml
The user wants to create TOC and Index files, personal to them, that contain
both these lists.
Either of the following approaches should work (to generate a personal TOC);
1. Use multiple '-d' parameters (or -c, or whatever)
sk-generate-toc -d /var/db/sk/contents.xml -d ~/.sk/db/contents.xml
2. Use an environment variable, which contains a ':' delimited list of
files to search.
SK_CONTENTS=/var/db/contents.xml:~/.sk/db/contents.xml sk-generate-toc
3. Create a meta-contents file, that uses entity inclusions to pull in the
files. Something like this;
<!DOCTYPE contents PUBLIC "-//ScrollKeeper Contents List 1.0//EN" [
<!ENTITY systemwide SYSTEM "/var/db/sk/contents.xml">
<!ENTITY personal SYSTEM "/home/nik/.sk/db/contents.xml">
]>
<contents>
&systemwide;
&personal;
</content>
[ I've assumed here that XML can do this in the same way that you can
with SGML. I know more SGML than I do XML, so this might not be
the case. ]
And then point sk-generate-toc at this meta-contents file;
sk-generate-toc -d meta-contents.xml
> > DD: Contents Lists must be able to refer to other Contents Lists, and sk
> > must have an option to chase the link to read the referred to Contents
> > List.
> >
> > DD: sk must have a run time option to allow the end user to select which
> > Contents Lists the user wants sk to process.
> >
> > DD: sk must have a run time option to allow the end user to select which
> > TOC to update.
>
> Waht do you mean about TOC update? At the moment this is extracted at
> install time (from sgml only) and stored in a file. As long as the doc
> does not change, the TOC does not need to be updated.
Joe Sysadmin runs sk-generate-toc to generate a TOC suitable for the entire
host, and puts it in /usr/local/share/doc/TOC
Joe User runs sk-generate-toc to generate a TOC that includes documentation
that they've installed documentation under $HOME.
Just so I'm clear here -- I'm not talking about the TOC that gets stored in
the Contents List. I am assuming that the TOC will need to be extracted
from the Contents List in other formats (such as HTML) to support environments
where KDE or GNOME are not the norm.
It would be nice to assume that everybody who is going to run sk is going
to be running a desktop environment that supports these things, but not
everybody is. I also suspect that a lot of people are going to need little
more than a mechanism which generates an HTML ToC and Index for their
installed documentation.
> > DD: sk must have a run time option to allow the end user to select which
> > Index to update.
>
> Saem as for TOC above,
As above.
> > DD: One of the sk commands must be to generate a usable Contents List
> > (which really means {X}HTML version, to start with) given a Contents
> > List which is in sk internal format.
>
> The sk Content List is XML, why would we want to generate HTML? I guess
> it depends on the browser what kind of files are needed. Anyway I am
> sure our XML Content List can be easily converted to HTML.
As above.
> > Each piece of documentation (which might really consist of tens or even
> > hundreds of files) can be considered to consist of two parts.
> >
> > 1. The documentation itself (*.html, *.png, foo.pdf, whatever).
> >
> > 2. The OMF, containing the 17 (?) key pieces of meta information that
> > sk likes to keep about the documentation. Not all 17 pieces of
> > information may necessarily be present.
> >
> > Not all documentation the user wants to point to is going to have the OMF
> > information associated with it. This is unavoidable.
> >
> > DD: sk must work tolerably well with minimum OMF information. At the
> > worst case, sk must do something useful when the only OMF information
> > available is the document title, and a URL pointing to the document's
> > 'index' page.
> >
> > Actually, I take that back. The only piece of information sk needs
> > is the URL. In the worst case (with 0 OMF information) the URL
> > becomes the title, until the end user provides some OMF, or points
> > sk at pre-existing OMF.
>
> This has to be discussed. OMF is the heart of Scrollkeeper, I am not
> sure we intend to make Scrollkeeper to deal with docs that don't have
> OMFs. But as I said before, the browser can deal with them separately.
I know. All I'm saying is that in the worst case (when a document has been
'adopted' by SK, but with no OMF, SK should synthesise an OMF that contains
1 piece of information, the document's title, which is based on the filename.
> > DD: sk should probably include some support applications which can parse
> > common documentation formats (*roff man and mdoc, GNU info, HTML,
> > LinuxDoc, LaTeX, DocBook) and extract as much OMF information from
> > them as possible.
>
> Yes, that is a good idea.
We can call them plugins. That's a nice, sexy, buzzwordy term :-)
> > In some cases this is necessary to produce bare bones OMF files that
> > will not be processed further. In other cases, this will be to produce
> > OMF files that will be further customised and improved by the end user.
> >
> > DD: sk should include some support applications that can generate TOC and
> > Index information from a variety of source formats.
>
> This is planned for SGML, it can be done for other formats too.
More plugins :-)
> > DD: sk should not assume that the OMF information is in the same directory
> > as the document, nor should it assume that the location of the OMF
> > information can be inferred based on the document's location. The
> > location of the OMF information must always be explicitly listed in
> > the Contents List.
>
> Yes, this is how it works.
Thought so.
> > The OMF information may not even be on the same host as the target
> > document.
>
> At the moment the OMF information is local, the document might not be.
> However the current implementation supports only local docs.
That's fine. I just want to make sure that these design decisions are
written down somewhere. Ideally, we then have a list of things to implement,
which can be checked off one by one.
> > DD: It is possible for a document to change, but for the OMF information
> > to be neglected. sk should maintain a modification time stamp for
> > each document and its corresponding OMF, to allow the end user to
> > determine when that might have happened, and to correct for it.
>
> Currently we take for granted that the OMF is changed at any doc change.
> If the doc has an OMF then when the whole package is re-installed then
> the OMF changes (the timestamp, this is what we monitor).
A document won't always be installed with new OMF. For example, if SK is
maintaining information about a remote document, but with the OMF locally.
The remote document might change, and SK needs to be able to tell when the
OMF is out of date (timestamps) with respect to the document.
> > DD: An application may have multiple pieces of documentation associated
> > with it. Applications are also not the only things that have
> > documentation, the system does (think: man page sections). Simply
> > storing information about a document isn't enough, you need to be
> > able to group documents into chunks (and probably group chunks into
> > chunks, or allow the same document to appear in multiple categories).
> > I'm not going to discuss this in too much detail in this document, this
> > is the reason for "4. Maintaining a Categories list" earlier.
>
> I think this is working. You can certainly install a doc in multiple
> places in the Content List.
I don't think we want to install the same document in multiple places.
Apart from ballooning the size of the Contents List, it means that there
is greater chance that one or more of those copies will be neglected during
an up date.
Each document should only appear once in the Contents List, but SK should be
able to handle multiple categories assigned to the same document.
> > DD: One document, multiple output formats. The user might have installed
> > the same document three times, once as HTML, once as PDF, and once as
> > plain text. The three installations are the same document, and have
> > the same OMF associated with them.
> >
> > sk should treat this as one document with three formats, rather than
> > three separate documents.
> >
> > [ This is probably going to be the most contentious piece of this
> > writeup, and it might change. In particular, it also suggests that
> > translations of a document should be treated as the same document,
> > just in a different language, and I'm not sure that's a good idea.
> > Then again, it might be. ]
>
> It doesn't work like this right now, every doc needs a separate OMF
> file. However one OMF file with several doc entries each describing a
> different doc is supported. So it would be possible to use one OMF file
> for the same doc in multiple formats.
This is a pretty crucial decision to make, and I haven't seen it discussed
on the list.
Gut instinct tells me that it's a cleaner design to consider that is 1:M
mapping between documents, and instances, instead of a 1:1 mapping.
I'll try and come up with some convincing reasons for this.
> > SK Tasks
> > --------
> >
> > There are a number of tasks that the sk end user is going to want to tell
> > sk to do. They are;
> >
> > Install new documentation that comes bundled with OMF
<snip>
> > 'sk-install-doc' registers the document. The two (optional) arguments
> > here are
<snip>
> > This command does not physically copy the file in to place.
>
> I guess here you mean that most or all of the OMF metadata should be
> able to be passed in as a parameter in the installation script/binary.
> Good idea.
No. At this point, no OMF information has been installed.
Installing the OMF for this document is a separate task.
[ Re MD5 ]
> md5 was ruled out before because it is too slow on Solaris. But we have
> a mechanism of assigning unique IDs by storing the assigned ones and
> then just not reassigning them again.
This is implementation specific, and not really important.
<snip>
> The current implementation assigns different IDs for the same doc in
> different formats.
This comes back to the earlier point, about a 1:M or 1:1 mapping. This
needs to be decided.
<snip>
> All of this can be implemented, but I don't see it too important for the
> moment.
I do, which is why I'm bringing it up. I hadn't seen anything talking about
SK from a user's point of view, or the sort of tasks a user is going to
want to carry out. I'd like to hammer out some sort of specification that
we can try and agree on, and codeto.
> > Install new documentation that doesn't come with OMF
> >
> > This is very similar to the previous example. However, instead of
> > running sk-install-omf, the user has two choices.
<snip>
> I guess we can support this later on.
We should be able to support this out of the box. Remember that if the
document has no OMF supplied by the end user then (IMHO) SK should synthesise
some OMF.
> > Removing documentation
> >
> > If the user wants to remove a single document format, but keep the
> > information about the document, they might do
> >
> > sk-remove-doc -format pdf -id MD5
> >
> > which would remove the <docinstance> information for the PDF version of
> > the document with id == MD5.
> >
> > If they want to remove a complete document, they do
> >
> > sk-remove-doc -id MD5
> >
> > which removes the whole thing. This does not touch the document's files
> > (such as /usr/local/share/doc/app-name/*), but it does update the Contents
> > List, and if the OMF has been stored in a separate file then it removes
> > that as well.
> >
> > Normally, this behaviour would be carried out by pkg_delete, or whatever
> > packaging system the user is using.
>
> This is fully automatic, if you delete the OMF file, all the related
> docs will be uninstalled.
I might not want to do that though. I might be deleting the OMF file because
it's out of date, and I haven't got time to update it.
As I say, in the absence of OMF, SK should fake some reasonable OMF, and
keep going.
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
|