scrollkeeper-devel — Developer discussion list for ScrollKeeper

[Scrollkeeper-devel] Basics of relocatable packages

[Dan M. <d-...@uc...>]

Hi everybody,

I don't know much about relocatable packages and I'm hoping people on this
list can help fill me in on things.

First, could people tell me which Unix, Linux, and BSD distributions do or
don't use relocatable packages.  I know Red Hat has few relocatable
packages, and SuSe seems to be the same.  It sounds like Solaris uses sysv
and ships most, but not all, packages relocatable. What about everything
else?

Second, is relocating RPMs *extremely* lame, or is my information out of
date?  I was just reading about it here:
 http://www.rpmdp.org/rpmbook/node80.html#12292

It looks like relocating packages with RPM only really works if all of
your files are under $prefix.  If you put things under /etc or /var or
anywhere else, there seems to be no nice way of doing it.  This seems like
a really dumb limitation in RPM, so I'm hoping this document is just
obsolete and that RPM has been improved since the time this document was
written (1997-8).

Does relocating a package normally happen in the same trivial way that it
does for RPM?  ie. It just takes all the file paths which match a certain
pattern for $prefix and substitute a new $prefix in place of it when it
installs.  Are there other common features?

My general impression is that at least with RPM, people would often not be
able to make their applications relocatable without doing some odd
monkeying around to get it to work.  I'm guessing that other packaging
systems are much better.  I guess for the sake of ScrollKeeper we will
support relocatable packages and then let the packagers decide for
themselves whether they use this feature.

Given all this, I think the old proposal to the list which Laszlo just
linked to should more or less be the right approach.  The spec file (or
whatever it is called in a particular packaging system) just needs to call
a post-install script and provide it with the information:
  (1) where the OMF files are
  (2) where the docs are

Does anybody know offhand whether the prefix the user passes to RPM on the
command line to relocate a package is available as a variable inside the
spec file to be passed to the post-install script?  The link above does
not seem to say, but I think that it indirectly implies it is possible to
access this variable.

I'd really like to hear feedback on all this from people who ship
relocatable packages.  This is all more of an exercise for me since I use
Red Hat and thus never use relocatable packages.  I would like to get this
all right on the first try though ;)

Dan

RE: [Scrollkeeper-devel] Scrollkeeper file format improvements?

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

> -----Original Message-----
> From: Dan Mueth [mailto:d-...@uc...]
>=20
> On Tue, 26 Jun 2001, L=E1szl=F3 Kov=E1cs wrote:
>=20
> > Second the TOC:
> >
> > Functionally JavaHelp and Scrollkeeper files are the same=20
> so there is
> > only a little room for changes with obvious benefit.
> >
> > Scrollkeeper format is:
> >
> > <tocsect1 linkid=3D"intro">Introduction
> >     <tocsect2 linkid=3D"whatisscrollkeeper">What is ScrollKeeper?
> >     </tocsect2>
> >     <tocsect2 linkid=3D"aboutthisdoc">About This Document
> >     </tocsect2>
> >     <tocsect2 linkid=3D"authors">Authors
> >     </tocsect2>
> >     <tocsect2 linkid=3D"scrollkeeperlicense">ScrollKeeper License
> >     </tocsect2>
> > </tocsect1>
> >
> > The numbering of the tocsects caused me tremendous problems while
> > writing the TOC extractor stylesheet (although that was my=20
> first ever
> > stylesheet, it is not that difficult actually). I think we=20
> should get
> > rid of those numbers regardless of other changes. The only=20
> help browser
> > using Scrollkeeper currently that I know of is Nautilus and=20
> it doesn't
> > use those numbers at all. No code change would be needed=20
> there if the
> > numbers go.
>=20
> Sounds reasonable.  I think the reason they are there are=20
> because DocBook
> uses <sect1>, <sect2>, etc.  It would be interesting to know=20
> the reason
> why DocBook numbers their sections.  I suspect it is (a) for=20

DocBook doesn't number it's sections, authors number their sections.  =
Some
authors find it easier to follow the logic when they can clearly see =
that
they're in a <sect3>.  Other authors use <section> everywhere, because =
that
means they can pick up and move sections around more easily.  I'm able =
to
keep track of where I am through the features of my SGML/XML editor, =
rather
than needing to use the tags to tell me where I am.  <section> can also =
be
infinitely recursed, so if you're writing large documents, <section> =
offers
a lot more flexibility.  Ugh, that sounds harsh.  Maybe it's because =
I'm
stuck using Outlook...

> the author,
> since they read and write the markup and having numbers helps=20
> keep them
> from getting confused, and (b) <books>, <articles>, etc. have=20
> strict rules
> on how they can be sectioned.  Neither of these really apply=20
> here, so I
> think we can do away with the numbers if there is any=20
> incentive to do so,
> such as making things simpler.

I'm all for getting rid of numbering of things, and setting up the toc =
stuff
to be infinitely recursable.  Later,
	Greg

Re: [Scrollkeeper-devel] Scrollkeeper file format improvements?

[Dan M. <d-...@uc...>]

On Tue, 26 Jun 2001, L=E1szl=F3 Kov=E1cs wrote:

> First the index, the Scrollkeeper format is this:
>
>   <primary>
>     <title>Front</title>
>     <secondary>
>       <title>Panel</title>
>       <tertiary>
>         <title>applets</title>
>         <see indexid=3D"id2597162">Panel, Testing, Zone</see>
>       </tertiary>
>     </secondary>
>   </primary>
>
> The JavaHelp format is like this:
>
> <indexitem text=3D"adding an existing portfolio" target=3D"proj.import"=
 />
> <indexitem text=3D"adding an existing project">
>     <indexitem text=3D"naming the project" target=3D"proj.importdirecto=
ry"
> />
> </indexitem>
> <indexitem text=3D"analyzing program performance, see  profiler " />
>
> I think replacing our primary, secondary, tertiary tags with indexitem
> would be a good move. This would allow infinite amount of index levels,
> the processing of the file would be easier in the help browser and the
> DTD would be simpler (I think, I am not a DTD expert). The rest should
> stay as their are technical reasons for them to be as they are.

So we would have:
   <indexitem>
     <title>Front</title>
     <indexitem>
       <title>Panel</title>
       <indexitem>
         <title>applets</title>
         <see indexid=3D"id2597162">Panel, Testing, Zone</see>
       </indexitem>
     </indexitem>
   </indexitem>

Right?

I think either way is fine.

> Second the TOC:
>
> Functionally JavaHelp and Scrollkeeper files are the same so there is
> only a little room for changes with obvious benefit.
>
> Scrollkeeper format is:
>
> <tocsect1 linkid=3D"intro">Introduction
>     <tocsect2 linkid=3D"whatisscrollkeeper">What is ScrollKeeper?
>     </tocsect2>
>     <tocsect2 linkid=3D"aboutthisdoc">About This Document
>     </tocsect2>
>     <tocsect2 linkid=3D"authors">Authors
>     </tocsect2>
>     <tocsect2 linkid=3D"scrollkeeperlicense">ScrollKeeper License
>     </tocsect2>
> </tocsect1>
>
> The numbering of the tocsects caused me tremendous problems while
> writing the TOC extractor stylesheet (although that was my first ever
> stylesheet, it is not that difficult actually). I think we should get
> rid of those numbers regardless of other changes. The only help browser
> using Scrollkeeper currently that I know of is Nautilus and it doesn't
> use those numbers at all. No code change would be needed there if the
> numbers go.

Sounds reasonable.  I think the reason they are there are because DocBook
uses <sect1>, <sect2>, etc.  It would be interesting to know the reason
why DocBook numbers their sections.  I suspect it is (a) for the author,
since they read and write the markup and having numbers helps keep them
from getting confused, and (b) <books>, <articles>, etc. have strict rule=
s
on how they can be sectioned.  Neither of these really apply here, so I
think we can do away with the numbers if there is any incentive to do so,
such as making things simpler.

> The JavaHelp TOC file is:
>
> <tocitem image=3D"toplevelfolder" text=3D"Java Development Environment"=
>
>     <tocitem target=3D"jde.intro">Introduction to JDE Online Help />
>     <tocitem text=3D"IDE Tutorial" target=3D"tut.starttoc">
>         <tocitem text=3D"Introducing JDE" target=3D"tut.intro" />
>         <tocitem text=3D"Tutorial One" target=3D"tut.quickstart" / >
>         <tocitem text=3D"Tutorial Two" target=3D"tut.edit" />
>         <tocitem text=3D"Tutorial Three" target=3D"tut.errors" />
>     </tocitem>
> </tocitem>
>
> It holds the same info as Scrollkeeper's, if there is no technical
> reason against it, I would support switching to it.

Somebody mentioned on this list a little while back that one should not
have "running text" as an attribute.

Dan

[Scrollkeeper-devel] relocatable package support

[Laszlo K. <las...@su...>]

Hi All,

I am looking into implementing the relocatable package support according
to this algorithm:

http://www.geocrawler.com/archives/3/6429/2000/11/50/4678568/

First, I think we should rename the scrollkeeper-update-identifier
script to scrollkeeper-update-url.

Summarizing it we have the following features:

1. Update the url in one OMF file if an absolute url path is specified.
2. Update the url in one OMF file if only a base filename in the OMF
file and a directory name (where the doc resides) is specified
(recursive search down the dir for the doc).
3. Update the url in one OMF file if a relative filename in the OMF file
and a directory name (where the doc resides) is specified (append the
relative path to the dir).

There would be one more needed:

4. Update the url in a set of OMF files in the same subdirectory
structure with urls from docs specified by a directory only. Both the
base filename (2) and the relative filename (3) should work in this
case.

The user should be able to do something like this:

scrollkeeper-update-url $prefix/share/omf/scrollkeeper
$prefix/doc/scrollkeeper

and this should do everything they need.

This can become quite complicated to be used together with
scrollkeeper-preinstall, it will need a good documentation.

Thoughts?

Laszlo

[Scrollkeeper-devel] Scrollkeeper file format improvements?

[<las...@Su...>]

Hi,

Scrollkeeper recently went through a review here in Sun (everything
deployed with the Gnome desktop has to). The reviewers advised me to
look at JavaHelp that tries to achieve similar goals (including a
browser provided) as Scrollkeeper. I looked primarily to the metadata
files of the docs and their might be some improvements we could make to
the Scrollkeeper files based on that. Another angle is that 

I've been advised to write a paper about conversion possibilities of
Scrollkeeper files to JavaHelp format in case we would ever like to add
JavaHelp support to Scrollkeeper. Considering this changes that don't
improve, but don't limit either could make my work easier.

Considering all these I can see improvements being made to our TOC and
index format.

First the index, the Scrollkeeper format is this:

  <primary>
    <title>Front</title>
    <secondary>
      <title>Panel</title>
      <tertiary>
        <title>applets</title>
        <see indexid="id2597162">Panel, Testing, Zone</see>
      </tertiary>
    </secondary>
  </primary>

The JavaHelp format is like this:

<indexitem text="adding an existing portfolio" target="proj.import" /> 
<indexitem text="adding an existing project"> 
    <indexitem text="naming the project" target="proj.importdirectory"
/> 
</indexitem> 
<indexitem text="analyzing program performance, see  profiler " />

I think replacing our primary, secondary, tertiary tags with indexitem
would be a good move. This would allow infinite amount of index levels,
the processing of the file would be easier in the help browser and the
DTD would be simpler (I think, I am not a DTD expert). The rest should
stay as their are technical reasons for them to be as they are.

Second the TOC:

Functionally JavaHelp and Scrollkeeper files are the same so there is
only a little room for changes with obvious benefit. 

Scrollkeeper format is:

<tocsect1 linkid="intro">Introduction
    <tocsect2 linkid="whatisscrollkeeper">What is ScrollKeeper?
    </tocsect2>
    <tocsect2 linkid="aboutthisdoc">About This Document
    </tocsect2>
    <tocsect2 linkid="authors">Authors
    </tocsect2>
    <tocsect2 linkid="scrollkeeperlicense">ScrollKeeper License
    </tocsect2>
</tocsect1>

The numbering of the tocsects caused me tremendous problems while
writing the TOC extractor stylesheet (although that was my first ever
stylesheet, it is not that difficult actually). I think we should get
rid of those numbers regardless of other changes. The only help browser
using Scrollkeeper currently that I know of is Nautilus and it doesn't
use those numbers at all. No code change would be needed there if the
numbers go.

The JavaHelp TOC file is:

<tocitem image="toplevelfolder" text="Java Development Environment"> 
    <tocitem target="jde.intro">Introduction to JDE Online Help /> 
    <tocitem text="IDE Tutorial" target="tut.starttoc"> 
        <tocitem text="Introducing JDE" target="tut.intro" /> 
        <tocitem text="Tutorial One" target="tut.quickstart" / > 
        <tocitem text="Tutorial Two" target="tut.edit" /> 
        <tocitem text="Tutorial Three" target="tut.errors" /> 
    </tocitem>  
</tocitem>

It holds the same info as Scrollkeeper's, if there is no technical
reason against it, I would support switching to it.

Thoughts?

Laszlo

[Scrollkeeper-devel] Packaging tests

[<las...@Su...>]

Hi,

We are close to release 0.3 that contains the largest number of new
dependencies and new features ever in Scrollkeeper. Here are most of
these:

* Support for DocBook/XML documents using libxml2
* DocBook/SGML support is now with OpenSP instead of libxml1
* Uses xml-i18n-tools for category translations
* Fall back to other translations of a document if the one in 
  the current locale is not available
* Initial support for index extraction (incomplete)

It would be nice if we could test these dependencies to see how they
work on various platforms. This needs at least one person per platform
trying to package the CVS version of Scrollkeeper and send the results
to the mailing list (then I'll try to fix the problems). Redhat Linux
and Solaris have been covered already.

Thanks,

Laszlo

Re: [Scrollkeeper-devel] extracted index

[Mary D. <Mar...@Su...>]

hi

sounds good to me -I'll implement it

thanks
Mary

<Dan Meuth wrote>
> 
> I'm not certain what the rational behind this recommendation is, or
> whether it would apply to our situation.  At any rate, I think we can
> easily follow the recommendation and make this into an attribute:
> 
> <indexdoc>
>   <primary title="Apple">
>      <secondary title="Big">
>        <tertiary title="Green">
>          <link linkid="idx-a1"/>
>          <link linkid="idx-a2"/>
>        </tertiary>
> ...
> 
> instead of the previously suggested:
> 
> <indexdoc>
>   <primary title="Apple">
>      <secondary title="Big">
>        <tertiary title="Green">
>          <linkid>idx-a1</linkid>
>          <linkid>idx-a2</linkid>
>        </tertiary>
> 
> Dan
> 
> 
> 

~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

------------- End Forwarded Message -------------


~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Re: [Scrollkeeper-devel] extracted index

[Dan M. <d-...@uc...>]

On Mon, 28 May 2001, Mary Dwyer wrote:

> < Dan Meuth wrote>
>
> > Right.  I hadn't thought of this until you pointed it out.  This does not
> > describe what the index really looks like - it has one Panel item with
> > three links, not three items named "Panel" each with one link.  For this
> > reason, the id's should be children instead of attributes.
> >
> > > - the following solution appealed, but unfortunately ID and IDREFs as
> element
> > > content is illegal :-)
> >
> > Why is it illegal?
>
> Norm Walsh pointed out, from the following example, that
> |   <primary>
> |     <title>Main Menu</title>
> |     <secondary>
> |       <title>Example</title>
> |       <linkid>idx-a3</linkid>
> |       <id>id10533</id>
>
> ".... putting ID or IDREF values in element content is discouraged
> by the W3C XML Schemas Recommendation and simply won't work for DTDs."
>
> Given what Laszlo pointed out earlier about my incorrect use of <id>, I'm not
> sure whether the above applies just to a misuse of the <id> tag in my example or
> whether it also applies to an entry such as <linkid>idx-a3</linkid> ?

I'm not certain what the rational behind this recommendation is, or
whether it would apply to our situation.  At any rate, I think we can
easily follow the recommendation and make this into an attribute:

<indexdoc>
  <primary title="Apple">
     <secondary title="Big">
       <tertiary title="Green">
         <link linkid="idx-a1"/>
         <link linkid="idx-a2"/>
       </tertiary>
...

instead of the previously suggested:

<indexdoc>
  <primary title="Apple">
     <secondary title="Big">
       <tertiary title="Green">
         <linkid>idx-a1</linkid>
         <linkid>idx-a2</linkid>
       </tertiary>

Dan

[Scrollkeeper-devel] Re: Migration to libxml2

[Karl E. <ke...@gm...>]

L=E1szl=F3 Kov=E1cs <las...@su...> writes:

> I am not very good with DOCTYPE declarations. How does it have to look
> in order to use the 4.0 or upper DTD I installed somewhere. How does
> this fit into the rest of the XML file? Before the head xml declaration
> or after?

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "/usr/share/sgml/db41xml/docbookx.dtd">
<book>
...
</book>

Instead of the filename you can use:

    "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"

Cf. docbookx.dtd from Norm's DTD package.

> The DOCTYPE declaration seems to contain the type of the doc (book,
> article etc). Does this mean I need to detect the type of the doc and
> put it in there?

Yes.

--=20
work : ke...@su...                          |                   ,__o
     : http://www.suse.de/~ke/             |                 _-\_<,
home : ke...@gm...                     |                (*)/'(*)

[Scrollkeeper-devel] Re: Migration to libxml2

[<las...@Su...>]

> At this stage these are warnings only.  Once you've the derived XML file
> make sure it starts with the DOCTYPE declaration.  Than it will make use
> of the XML entity files coming with Norm's DocBook XML package.  On SuSE
> you'll find the entities files here:
> 
>     /usr/share/sgml/db41xml/ent/iso-*

I am not very good with DOCTYPE declarations. How does it have to look
in order to use the 4.0 or upper DTD I installed somewhere. How does
this fit into the rest of the XML file? Before the head xml declaration
or after?

The DOCTYPE declaration seems to contain the type of the doc (book,
article etc). Does this mean I need to detect the type of the doc and
put it in there?

Laszlo

[Scrollkeeper-devel] Re: Migration to libxml2

[Karl E. <ke...@gm...>]

L=E1szl=F3 Kov=E1cs <las...@su...> writes:

> Is there any way to turn them
> off? I could use the -f option to redirect them to a file, but is there
> any other way?

According to /usr/share/doc/packages/sp/doc/nsgmls.htm -wno-xml should
do -- but it fails for me.  This Unix trick works for me:

    s2x -b iso-8859-1 ggv.sgml 2>/dev/null > ggv.xml

--=20
work : ke...@su...                          |                   ,__o
     : http://www.suse.de/~ke/             |                 _-\_<,
home : ke...@gm...                     |                (*)/'(*)

[Scrollkeeper-devel] Re: Migration to libxml2

[<las...@Su...>]

> At this stage these are warnings only. 
Yes, I figured it out in the meantime. Is there any way to turn them
off? I could use the -f option to redirect them to a file, but is there
any other way?

Laszlo

[Scrollkeeper-devel] Re: Migration to libxml2

[Karl E. <ke...@gm...>]

L=E1szl=F3 Kov=E1cs <las...@su...> writes:

> I tried sgml2xml with mixed results. I initially tried it on RH 6.2
> and RH 7.0 and had loads of DTD related messages, every SGML tag was
> printed as not known. I tried to installed the DTDs with the help of
> Dan and Greg, but I couldnt get it right.

Right approach.  Every SGML application wants and have to read the DTD
before processing the document instance (the ordinary .sgml file); sx
(resp. sgml2xml) is a SGML application.

> Then I installed RH 7.1 and gnome-doc-tools 2.0 and most of the
> messages disappeared.

Good.  I've my db2xml script (available from
http://www.suse.de/~ke/docbook-toys/) which hides all the nitty
gritties; warning: lately the script was only tested on SuSE Linux 7.1
and 7.2beta.

> Now I have a couple of "reference to internal SDATA entity"hellip" is
> not allowed in XML" coming out from sgml2xml. Same for mdash. I
> obviously do something wrong, but I dont know what. Any ideas?

At this stage these are warnings only.  Once you've the derived XML file
make sure it starts with the DOCTYPE declaration.  Than it will make use
of the XML entity files coming with Norm's DocBook XML package.  On SuSE
you'll find the entities files here:

    /usr/share/sgml/db41xml/ent/iso-*

> Considering that I didnt manage to get this working on on RH 6.2 and
> RH 7.0 it might not be trivial, or I might just dig in the wrong
> direction.  Anyway we have to make it trivial for the user.

Sure, but it isn't actually difficult if a db2xml script is in place;
distributor should take care about this issue.

> And the good news, as far as the encoding is concerned it works ok.

Good :)

> If I manage to actually build it on both Solaris and Linux, this might
> be the way out as far as encoding is concerned.

You'll work it out.  IIRC, patches were also posted on the openjade
list to work wround compilation issues.

--=20
work : ke...@su...                          |                   ,__o
     : http://www.suse.de/~ke/             |                 _-\_<,
home : ke...@gm...                     |                (*)/'(*)

Re: [Scrollkeeper-devel] Re: Migration to libxml2

[<las...@Su...>]

> Maybe, this help:
> 
>     http://www.jclark.com/sp/sx.htm
> 
> sgml2xml is renamed from 'sx' to avoid a namespace clash with 'sx' (part
> of the rzsz package, modem related tools).
> 

I tried sgml2xml with mixed results. I initially tried it on RH 6.2 and
RH 7.0 and had loads of DTD related messages, every SGML tag was printed
as not known. I tried to installed the DTDs with the help of Dan and
Greg, but I couldnt get it right. Then I installed RH 7.1 and
gnome-doc-tools 2.0 and most of the messages disappeared. Now I have a
couple of "reference to internal SDATA entity"hellip" is not allowed in
XML" coming out from sgml2xml. Same for mdash. I obviously do something
wrong, but I dont know what. Any ideas?

Considering that I didnt manage to get this working on on RH 6.2 and RH
7.0 it might not be trivial, or I might just dig in the wrong direction.
Anyway we have to make it trivial for the user.

And the good news, as far as the encoding is concerned it works ok.

If I manage to actually build it on both Solaris and Linux, this might
be the way out as far as encoding is concerned.

Laszlo

Re: [Scrollkeeper-devel] extracted index

[Mary D. <Mar...@su...>]

> > Mary Dwyer wrote:
> >
> > > 3.  ids are generated within the index to provide internal links for see 
and
> > >     seealso references. For example, where "Main Menu, Example" is an 
index
> > > entry, and there is a see reference from "Chapter, Example" to "Main Menu,
> > > Example" the output will be as follows:
> > >
> > > <primary>
> > >     <title>Chapter</title>
> > >     <secondary>
> > >       <title>Example</title>
> > >       <see id="id10791">Main Menu, Example</see>
> > >     </secondary>
> > >   </primary>
> > >   <primary>
> > >     <title>Main Menu</title>
> > >     <secondary>
> > >       <title linkid="idx-a3" id="id10791">Example</title>
> > >     </secondary>
> > >   </primary>
> >

> > >  In order to be able to match the <see>/<seealso> content to the correct 
index
> > > term I need to be able to assume the <see>/<seealso> content will be 
structured
> > > in a set way, ie primary, secondary, tertiary (each term seperated by a 
comma
> > > and a space - or whatever, once it is consistent).
> > This might be a problem considering the variety of sources documents are
> > coming from. Why is this needed?

Dan

it's more a problem of how to generate the id.
ie, when outputing the 'main' term need a way of generating an id which can be 
generated again when outputing the see/seealso term. The only way I have figured 
to match a see/seealso value to the appropriate index entry is via a key.  But 
in order to construct the "use" element of the key I need to know how the 
see/seealso value is constructed (ie spaces, commas between terms etc). 
This will be clearer when I commit the stylesheet to SK CVS - in the meantime if 
anyone has any ideas/suggestions .....


cheers
mary

> 
> I think we have three options here:
> 
> (1) Use the title as one expects all browsers to display them, such as
> Mary did: "Main Menu, Example"
>      <secondary>
>        <title>Example</title>
>        <see id="id10791">Main Menu, Example</see>
>      </secondary>
> 
> (2) Provide the information about where it is linking to as metadata so
> that the help browser can construct the string however it wants to:
> 
>      <secondary>
>        <title>Example</title>
>        <see id="id10791" ptitle="Main Menu" stitle="Example"/>
>      </secondary>
> 
> (3) Don't bother giving the title of the section you are linking to,
> because the help browser can always go in and extract it since it has the
> id:
> 
>      <secondary>
>        <title>Example</title>
>        <see id="id10791">
>      </secondary>
> 
> I tend to prefer #2 I think, since it gives the help browser the
> flexibility to present the information in different ways without doing
> much work.
> 
> Dan
> 

~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Re: [Scrollkeeper-devel] extracted index

[Mary D. <Mar...@Su...>]

< Dan Meuth wrote>

> Right.  I hadn't thought of this until you pointed it out.  This does not
> describe what the index really looks like - it has one Panel item with
> three links, not three items named "Panel" each with one link.  For this
> reason, the id's should be children instead of attributes.
> 
> > - the following solution appealed, but unfortunately ID and IDREFs as 
element
> > content is illegal :-)
> 
> Why is it illegal?

Norm Walsh pointed out, from the following example, that
|   <primary>
|     <title>Main Menu</title>
|     <secondary>
|       <title>Example</title>
|       <linkid>idx-a3</linkid>
|       <id>id10533</id>

".... putting ID or IDREF values in element content is discouraged
by the W3C XML Schemas Recommendation and simply won't work for DTDs."

Given what Laszlo pointed out earlier about my incorrect use of <id>, I'm not 
sure whether the above applies just to a misuse of the <id> tag in my example or 
whether it also applies to an entry such as <linkid>idx-a3</linkid> ?
Mary

> 
> > <primary>
> >     <title>Panel</title>
> >     <linkid>idx-a2</linkid>
> >     <linkid>idx-a5</linkid>
> >     <linkid>idx-a9</linkid>
> >     <indexid>id10715</indexid>
> >
> > Does anyone have any suggestions on the best way of presenting multiple
> > occurences of an indexterm??
> 
> I think you are headed in exactly the right direction here.  Because an
> index item may occur in multiple places, it probably makes more sense to
> use child elements instead of attributes as we originally discussed.
> 
> This makes the file a little longer, but we can always make the titles
> attributes if we care about XML bloat.
> 
> The long version is:
> 
> <indexdoc>
>   <primary>
>      <title>Apple</title>
>      <secondary>
>        <title>Big</title>
>        <tertiary>
>          <title>Green</title>
>          <linkid>idx-a1</linkid>
>          <linkid>idx-a2</linkid>
>        </tertiary>
>        <tertiary>
>          <title>Blue</title>
>          <linkid>idx-a3</linkid>
>        </tertiary>
>        <tertiary>
>          <title>New York City</title>
>          <seealso>sa-a1</seealso>
>        </tertiary>
>      </secondary>
>    </primary>
>    <primary>
>      <title>Banana</title>
>      <secondary>
>        <title>Small</title>
>        <linkid>idx-a2</linkid>
>      </secondary>
>    </primary>
>    <primary>
>      <title>New York City</title>
>      <linkid>idx-a5</linkid>
>      <id>sa-1</id>
>    </primary>
> </indexdoc>
> 
> If we shorten it with attributes, it is easier to read and distinguish
> which parts are repeatable and which are not:
> 
> <indexdoc>
>   <primary title="Apple">
>      <secondary title="Big">
>        <tertiary title="Green">
>          <linkid>idx-a1</linkid>
>          <linkid>idx-a2</linkid>
>        </tertiary>
>        <tertiary title="Blue">
>          <linkid>idx-a3</linkid>
>        </tertiary>
>        <tertiary title="New York City">
>          <seealso>sa-a1</seealso>
>        </tertiary>
>      </secondary>
>    </primary>
>    <primary title="Banana">
>      <secondary title="Small">
>        <linkid>idx-a2</linkid>
>      </secondary>
>    </primary>
>    <primary title="New York City" id="sa-1">
>      <linkid>idx-a5</linkid>
>    </primary>
> </indexdoc>
> 
> Dan
> 

~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

------------- End Forwarded Message -------------


~ I speak for myself, not for my employer ~
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Mary Dwyer
Desktop Applications & Middleware Grp
Sun Microsystems Ireland
Tel: +353-1-8199222 (xt 19222)
Fax: +353-1-8199078
email: mar...@ir...
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

Re: [Scrollkeeper-devel] extracted index

[<las...@su...>]

Dan Mueth wrote:
> 
> On Fri, 25 May 2001, Mary Dwyer wrote:
> 
> > Hi
> >
> > >From the stylesheet point of view, if we get the main entry for duplicate index
> > terms correct, the see/seealso references will follow.
> >
> > So, to recap, here's an example of the problem:
> > - there are multiple sections in the document indexed by the term "Panel". These
> > sections have the identifiers idx-a2, idx-a5, idx-a9. There are also a number of
> > see/seealso references to "Panel"
> > - under the current stylesheet structure this would result in the index entry
> >   <primary>
> >     <title linkid="idx-a2" indexid="id10715">Panel</title>
> >     <title linkid="idx-a5" indexid="id10715">Panel</title>
> >     <title linkid="idx-a9" indexid="id10715">Panel</title>
> 
> Right.  I hadn't thought of this until you pointed it out.  This does not
> describe what the index really looks like - it has one Panel item with
> three links, not three items named "Panel" each with one link.  For this
> reason, the id's should be children instead of attributes.
> 
> > - the following solution appealed, but unfortunately ID and IDREFs as element
> > content is illegal :-)
> 
> Why is it illegal?

I think Norman Walsh said to Mary we shouldnt do it like this. Norm, is
this what happened?

Laszlo

[Scrollkeeper-devel] Re: extracted index

[Karl E. <ke...@gm...>]

Dan Mueth <d-...@uc...> writes:

> I'm curious where the rule against having running text in attributes
> comes from.  Is it technical, conventional, or aesthetic?

All three.  But you're sure you will never have to a further markup to
the text exeptions are possible.

> In the end, I don't think it will matter very much whether we use
> attributes or children since index files will never be written or
> edited by hand.

Okay.

> I think it does make things a little more clear in at least my
> email client, which does not put element names in grey ;)

Mine applies nice colors; Gnus treats SGML "tags" like quotation markers
;)  From the Gnus manual:


Article Highlighting
--------------------
   Not only do you want your article buffer to look like fruit salad,
but you want it to look like technicolor fruit salad.

Nice weekend,
Karl

-- 
work : ke...@su...                          |                   ,__o
     : http://www.suse.de/~ke/             |                 _-\_<,
home : ke...@gm...                     |                (*)/'(*)

[Scrollkeeper-devel] New scrollkeeper-announce mailing list

[Dan M. <d-...@uc...>]

Hi,

Now that ScrollKeeper has a fairly large audience (over 5000 downloads
from SourceForge and many more through Linux distros which have started
shipping it), I figure there are people who want to track the main
announcements without hearing all the technical discussions.

So, I just created a new mailing list for ScrollKeeper announcements
called "scrollkeeper-announce".  All posts are moderated, so it should be
very low traffic.  We will announce new releases and other general
announcements such as roadmaps, significant errata descriptions, and
anything else which we feel is of interest to those using or
redistributing ScrollKeeper.

To join the list, visit:
http://lists.sourceforge.net/lists/listinfo/scrollkeeper-announce

If you want to unsubscribe to scrollkeeper-devel, you can do so here:
http://lists.sourceforge.net/lists/listinfo/scrollkeeper-devel

Dan

Re: [Scrollkeeper-devel] Re: extracted index

[Dan M. <d-...@uc...>]

On 25 May 2001, Karl Eichwalder wrote:

> Dan Mueth <d-...@uc...> writes:
>
> > If we shorten it with attributes, it is easier to read and distinguish
> > which parts are repeatable and which are not:
>
> Don't do this.  As a general rule: Don't hide "running" text inside of
> attributes.  If you use a proper Editor the element contents are visible
> (eg., use a light grey for the element names).

I'm curious where the rule against having running text in attributes comes
from.  Is it technical, conventional, or aesthetic?

In the end, I don't think it will matter very much whether we use
attributes or children since index files will never be written or edited
by hand.  I think it does make things a little more clear in at least my
email client, which does not put element names in grey ;)

Dan

[Scrollkeeper-devel] Re: extracted index

[Karl E. <ke...@gm...>]

Dan Mueth <d-...@uc...> writes:

> If we shorten it with attributes, it is easier to read and distinguish
> which parts are repeatable and which are not:

Don't do this.  As a general rule: Don't hide "running" text inside of
attributes.  If you use a proper Editor the element contents are visible
(eg., use a light grey for the element names).

-- 
work : ke...@su...                          |                   ,__o
     : http://www.suse.de/~ke/             |                 _-\_<,
home : ke...@gm...                     |                (*)/'(*)

[Scrollkeeper-devel] Re: Migration to libxml2

[Karl E. <ke...@gm...>]

Laszlo Kovacs <las...@su...> writes:

> Same problem, although I can build sx or osx, but not the entire SP or
> OpenSP. Nsgmls seems to cause problems. Here are the error messages:

Sorry, I'm not a hacker.  If I remember correctly, one of my collegues
applied a patch or two.  Similar patches should come with every Linux
distro.  Feel free to try one of source RPMs; on SuSE Linux it has
astrange name:

    jade_dsl.spm (or jade_dsl-VERSION.src.rpm)

Somewhere below

    ftp://ftp.suse.com/pub/suse/

here we go:

    ftp://ftp.suse.com/pub/suse/i386/7.1/suse/zq1/jade_dsl.spm


-- 
work : ke...@su...                          |                   ,__o
     : http://www.suse.de/~ke/             |                 _-\_<,
home : ke...@gm...                     |                (*)/'(*)

[Scrollkeeper-devel] Linking to Indexterms Without ID's [was: Re: [Scrollkeeper-devel] extracted index]

[Dan M. <d-...@uc...>]

On Thu, 24 May 2001, Mary Dwyer wrote:

> A few issues to note:
> 1. only dealing with indexterms from the original document that include an "id"
> or "zone" attribute (in order to provide anchors back to the original document)

There are two general approaches to how we solve this problem which come
to my mind:

The first is using XPointers.  I don't understand how one proceeds from
having an XPointer to the right location to actually having XSLT produce
the HTML output of the right page and anchor it to the right location.
If we can do this without much trouble, then this may be a good solution.
Does anybody understand how this works once we have the XPointer?

The other is to create a black box id generator which you feed your docs
through.  For the sake of discussion, I will call it "sk_idattgen" and it
will ship as part of ScrollKeeper.  It is an executable that you input
your SGML or XML doc and it outputs the same docs but it inserts id's
anywhere they are missing in a deterministic and reproducable way.  It
would be simple to do - it could just number all the id's and check to
make sure none of the numbers collide with pre-existing id's, for example.
ScrollKeeper would run sk_idattgen on any SGML or XML docs it works with
before it does any other processing.  Any help browser which wants to work
properly with ScrollKeeper will have to run sk_idattgen on any doc it
works with before it does other processing.  (Note this solves the problem
not only for indexing, but also for the TOC and potentially other problems
that will surely pop up in the future.)

I like the later solution because it is so simple to implement and to use,
and should be very robust.  The main downside to it is the time penalty of
having to parse the file an extra time.  I don't think it should be
noticable on the help browser side.

For ScrollKeeper itself, if we really care about performance we can just
create a function which does the sk_idattgen work which we call inside the
other SK functions so we don't parse the document twice.  This will help
in cases where we are processing dozens of files and care about
performance.

Dan

Re: [Scrollkeeper-devel] extracted index

[Dan M. <d-...@uc...>]

On Thu, 24 May 2001, L=E1szl=F3 Kov=E1cs wrote:

> Mary Dwyer wrote:
>
> > 3.  ids are generated within the index to provide internal links for =
see and
> >     seealso references. For example, where "Main Menu, Example" is an=
 index
> > entry, and there is a see reference from "Chapter, Example" to "Main =
Menu,
> > Example" the output will be as follows:
> >
> > <primary>
> >     <title>Chapter</title>
> >     <secondary>
> >       <title>Example</title>
> >       <see id=3D"id10791">Main Menu, Example</see>
> >     </secondary>
> >   </primary>
> >   <primary>
> >     <title>Main Menu</title>
> >     <secondary>
> >       <title linkid=3D"idx-a3" id=3D"id10791">Example</title>
> >     </secondary>
> >   </primary>
>
> Isnt there a restriction that id attributes have to be unique throughou=
t
> the document? If it is then we will need to name the "id" attribute
> something else.

It looks like the <see> tag above does not want an 'id' attribute, but
instead it needs something like a 'linkid' - perhaps called 'seeid':
      <see seeid=3D"id10791">Main Menu, Example</see>

> >  In order to be able to match the <see>/<seealso> content to the corr=
ect index
> > term I need to be able to assume the <see>/<seealso> content will be =
structured
> > in a set way, ie primary, secondary, tertiary (each term seperated by=
 a comma
> > and a space - or whatever, once it is consistent).
> This might be a problem considering the variety of sources documents ar=
e
> coming from. Why is this needed?

I think we have three options here:

(1) Use the title as one expects all browsers to display them, such as
Mary did: "Main Menu, Example"
     <secondary>
       <title>Example</title>
       <see id=3D"id10791">Main Menu, Example</see>
     </secondary>

(2) Provide the information about where it is linking to as metadata so
that the help browser can construct the string however it wants to:

     <secondary>
       <title>Example</title>
       <see id=3D"id10791" ptitle=3D"Main Menu" stitle=3D"Example"/>
     </secondary>

(3) Don't bother giving the title of the section you are linking to,
because the help browser can always go in and extract it since it has the
id:

     <secondary>
       <title>Example</title>
       <see id=3D"id10791">
     </secondary>

I tend to prefer #2 I think, since it gives the help browser the
flexibility to present the information in different ways without doing
much work.

Dan

Re: [Scrollkeeper-devel] extracted index

[Dan M. <d-...@uc...>]

On Fri, 25 May 2001, Mary Dwyer wrote:

> Hi
>
> >From the stylesheet point of view, if we get the main entry for duplicate index
> terms correct, the see/seealso references will follow.
>
> So, to recap, here's an example of the problem:
> - there are multiple sections in the document indexed by the term "Panel". These
> sections have the identifiers idx-a2, idx-a5, idx-a9. There are also a number of
> see/seealso references to "Panel"
> - under the current stylesheet structure this would result in the index entry
>   <primary>
>     <title linkid="idx-a2" indexid="id10715">Panel</title>
>     <title linkid="idx-a5" indexid="id10715">Panel</title>
>     <title linkid="idx-a9" indexid="id10715">Panel</title>

Right.  I hadn't thought of this until you pointed it out.  This does not
describe what the index really looks like - it has one Panel item with
three links, not three items named "Panel" each with one link.  For this
reason, the id's should be children instead of attributes.

> - the following solution appealed, but unfortunately ID and IDREFs as element
> content is illegal :-)

Why is it illegal?

> <primary>
>     <title>Panel</title>
>     <linkid>idx-a2</linkid>
>     <linkid>idx-a5</linkid>
>     <linkid>idx-a9</linkid>
>     <indexid>id10715</indexid>
>
> Does anyone have any suggestions on the best way of presenting multiple
> occurences of an indexterm??

I think you are headed in exactly the right direction here.  Because an
index item may occur in multiple places, it probably makes more sense to
use child elements instead of attributes as we originally discussed.

This makes the file a little longer, but we can always make the titles
attributes if we care about XML bloat.

The long version is:

<indexdoc>
  <primary>
     <title>Apple</title>
     <secondary>
       <title>Big</title>
       <tertiary>
         <title>Green</title>
         <linkid>idx-a1</linkid>
         <linkid>idx-a2</linkid>
       </tertiary>
       <tertiary>
         <title>Blue</title>
         <linkid>idx-a3</linkid>
       </tertiary>
       <tertiary>
         <title>New York City</title>
         <seealso>sa-a1</seealso>
       </tertiary>
     </secondary>
   </primary>
   <primary>
     <title>Banana</title>
     <secondary>
       <title>Small</title>
       <linkid>idx-a2</linkid>
     </secondary>
   </primary>
   <primary>
     <title>New York City</title>
     <linkid>idx-a5</linkid>
     <id>sa-1</id>
   </primary>
</indexdoc>

If we shorten it with attributes, it is easier to read and distinguish
which parts are repeatable and which are not:

<indexdoc>
  <primary title="Apple">
     <secondary title="Big">
       <tertiary title="Green">
         <linkid>idx-a1</linkid>
         <linkid>idx-a2</linkid>
       </tertiary>
       <tertiary title="Blue">
         <linkid>idx-a3</linkid>
       </tertiary>
       <tertiary title="New York City">
         <seealso>sa-a1</seealso>
       </tertiary>
     </secondary>
   </primary>
   <primary title="Banana">
     <secondary title="Small">
       <linkid>idx-a2</linkid>
     </secondary>
   </primary>
   <primary title="New York City" id="sa-1">
     <linkid>idx-a5</linkid>
   </primary>
</indexdoc>

Dan