Menu
▾
▴
Re: [Scrollkeeper-devel] ScrollKeeper-0.1 Proposal #3
|
From: Dan M. <d-...@uc...> - 2000-11-13 17:45:36
|
On Mon, 13 Nov 2000, Nik Clayton wrote:
> On Sun, Nov 12, 2000 at 10:22:33PM -0600, Dan Mueth wrote:
> > Hi everybody,
>
> Ditto. A brief intro -- I'm the FreeBSD Documentation Project cat herder.
> I was at the O'Reilly conference earlier this year, and I subscribed to this
> list a few days ago. I've been working my way through the archives :-)
>
> > Feedback is welcome :)
>
> OK :-)
>
> > --------------------------------------
> > | ScrollKeeper 0.1 - Proposal #3 |
> > --------------------------------------
> >
> > II. Building, Installing, and Uninstalling
> >
> > i. Building
> >
> > The OMF documents are manipulated during the application
> > build process, generally as part of 'make all'. The purpose of this
> > is to (1) substitute the correct URL of the document where it will
> > actually be installed, which is not generally known until build time,
> > and to (2) extract the OMF from DocBook documents into a seperate file.
> > (NOTE: #2 may not be supported in ScrollKeeper 0.1)
>
> You probably don't know where the application is going to be installed until
> install time, not build time. Using the FreeBSD ports tree, it's trivial
> to do
>
> cd /usr/ports/foo/bar
> make
> make PREFIX=/somewhere/else install
>
> Similarly, if you're building packages on BSD (or RPMs, or whatever) the
> end user can change the install path after the package has been built, but
> before it has been installed.
This would pose a significant problem. The original design installed each
document with something like:
scrollkeeper-install <omffile> <doc>
so that the path of the doc was given to ScrollKeeper at install
time. This would solve the problem of paths changing between build and
install time. However we decided to change the process to simplify things
for developers and packagers. (see the mailing list archives...)
I will have to consider this some more.
Anybody have an idea for a solution which is easy on the packagers but
solves the problem of people changing the default installation directory
of a package?
I would expect that changing the install path of a package after it is
built would often wreak havoc on it. Do people really do this very often,
and are most packages robust against this? (ie. Do we really have to
worry about this?)
> I know that FreeBSD packages and RPMs both support running commands after
> the install -- I assume the .deb format does as well.
>
> > Note that the OMF file is named <application>-<document_title>-<locale>.omf.
> > This is important to avoid collisions between OMF files when they are
> > installed.
>
> Your examples don't use a sufficiently long <locale>. For example, the user
> might install docs in Chinese, using both EUC and Big 5 encoding. For that,
> you really need to be able to specify zh_CN.EUC and zh_TW.Big5.
>
> Note that trying to rely on just zh_CN or zh_TW isn't sufficient for other
> languages, like Japanese, where the various encodings hang off a ja_JP
> prefix.
I don't think long locales pose any problems.
> > Installation is done by first copying the document and OMF file into
> > place and then having ScrollKeeper update its database by calling
> > 'scrollkeeper-update'.
>
> Seems reasonable.
>
> > install:
> > install foo-manual.sgml $(DOCDIR)
> > install omf-install/foo-manual-fr.omf $(OMFDIR)
> > scrollkeeper-update -p $(SCROLLKEEPER_DB_DIR)
>
> An option to specify exactly where you installed the documentation is
> probably a good idea, so that scrollkeeper-update doesn't have to rescan
> a (potentially) huge directory tree of documentation.
We originally had the location of the document passed, but this became
redundant when we had the build scripts update the OMF file to contain the
real path.
The only directory we scan is OMFDIR. These files tell us where all the
documentation is, so we never scan documentation trees.
> > -- For use by help browsers --
> > scrollkeeper-get-contents-list <language>:
> > 1) Returns the path:
> > ${pkglocalstatedir}/<language>/scrollkeeper-contents-list.xml
>
> Should a lot of this stuff be implemented only as separate programs? What
> about a scrollkeeper library that applications can link with that provides
> functions that return this information from a config file somewhere. Having
> to run several applications every time someone starts their help browser may
> not be very efficient.
Sure. We just thought we'd keep things simple for the first version.
> > scrollkeeper-contents-list.xml:
> > This is a simple XML file which reveals what the Contents List
> > looks like and where the OMF files and doc are at. This is used
> > by the help browser to display the Contents List.
> > [We will need to write up a simple DTD.]
> >
> > <sect>
> > <title>Applications</title>
> > <sect>
> > <title>Games</title>
> > <doc docid="000050">
> > <doctitle>FreeCell</doctitle>
> > <docomf>/usr/local/games/freecell/freecell-omf.xml</docomf>
> > <docsource>/usr/local/games/freecell/freecell.sgml</docsource>
> > <docformat>SGML</docformat>
> > </doc>
> > </sect>
> > </sect>
>
> <snip>
>
> > scrollkeeper-extended-contents-list.xml:
> > Similar to scrollkeeper-contents-list.xml, except has TOC info in
> > it too. This is used by the help browser to display the
> > "extended Contents List".
>
> What's the rationale for keeping these separate? Any program iterating
> over their contents should know whether it needs the extended information or
> not, and ignore it, or process it, as necessary.
Right. We could opt to dump the non-extended list, and always pass the
extended contents list. Until we get a feeling for how the performance
is, it may be nice to keep the non-extended list since it will be much
shorter.
> The choice of element or attribute in your sample is inconsistent. Either
> something like
>
> ...
> <doc id="00050" omf="..." source="..." format="sgml">
> <title>Freecell</title>
> </doc>
>
> or
>
> <doc>
> <docid>00050</docid>
> <title>...</title>
> ...
> </doc>
>
> might be better. When I first started writing DTDs, I was advised on
> several mailing lists that if you expect to show content to the end user
> (such as the title) then make it an element. Anything that is designed to
> help the application (such as the format, or the source) is an attribute.
>
> Of course, there's a case for saying that "Well, the application will be
> able to show the user an icon for the source format, or the path to the
> underlying document" so it's not a cut and dried decision. It's probably
> best to consider what the default view would be.
Don't they give any value to aesthetics? Mine is clearly the prettiest ;)
Actually I was following the convention you mention. Everything the help
browser is supposed to use is an element, and things which the help
browser isn't supposed to use (the docid) is an attribute. The docid is
only used by ScrollKeeper to make it easy to uninstall a document's
metadata.
Dan
|