Re: [Scrollkeeper-devel] Handling relocatable packages

[Gregory L. <gle...@cu...>]

> 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:
> 
> 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.


Didn't somebody have these?  I could have sworn I'd seen them, but I
can't seem to figure out where.


> > > 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.


I've borrowed a perl hack from Greg Ferguson, and I've made (and had
made) a few changes to it.  However, there are a few things that don't
quite work just yet, I'll let people know when I've got tools working.


> In 1, we'll also need the sk-generate-omf command to update the OMF
> after it's been extracted from the source document.


Why does it need to be updated immediately after it's been
extracted?  Or did I miss something?


> 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). ]


I don't think this is something that should be part of sk, per say, but
some "extra" module.  


> In the case of (3), we'll need sk-generate-omf to fixup the incorrect
> OMF data.


That sounds like fun, I'm very familiar with "automagically" fixing XML
documents, based on the errors that a parser spits out.  I'd guess that
the w3c's Tidy application would contain some of the concepts needed for
this.


> > 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.


Yes,  one tool that does one thing is "The Unix Way", and I think it's
probably a good way to go.  Would someone want to have this available at
the time that they install the package?  If so, it needs to be part of
sk.

    Greg