Hi Luke, Il giorno Thu, 22 Dec 2011 13:18:30 -0500 Luke Campagnola <lcamp...@email.unc.edu> ha scritto:
> On Sun, Dec 18, 2011 at 13:52, Antonio Valentino > <antonio.valent...@tiscali.it> wrote: > >> My patch creates keyword tags from reference labels instead of > >> index entries. It sets the id attribute to the reference label > >> name and does not include a name attribute (so the keyword does > >> not show up in the index). This enables the program to display > >> locations in the document without requiring that they have a > >> corresponding index entry. > >> > > > > Ok. > > My concern regards the fact that almost all the keyword entries > > added in this way are in some manner duplicates of existing ones. > > Just they have a different id. > > I just tried this out with the Sphinx documentation and I see your > point. It seems that there are some directives that create both a > reference label and an index entry. In this case, we would end up with > a duplicate entry. In some circumstances, we might even get > conflicting IDs and unpredictable results. > > In the circumstances where the documentation has an explicit reference > label, this will only show up when using my patch. I think the > cleanest solution would be to only use reference labels to generate ID > attributes and only use index entries to generate name attributes. > However, this isn't really an option since some projects may already > depend on the IDs as they are currently generated. > > Perhaps the best option, then, is to generate the new set of IDs but > ensure that they can not conflict with any previously-generated IDs. > OK, it seems a reasonable approach > I'm attaching a patch against the code at > bitbucket.org/avalentino/sphinx with the following changes (maybe I > should use hg export? I'm not familiar with hg): The standard way to go is to have a local "hg clone" the repository. Please let me know if you have a bitbucket account, I can give you commit access to my fork. > 1. The keyword_item method now returns a tuple (name, id, ref) rather > than a complete "<keyword ...>" tag > 2. build_qhp() keeps a dictionary of all existing IDs so we can be > sure that there are not overwritten by any of the reference-label IDs > (this has the added benefit of removing most of the duplicate > reference entries you mentioned) > 3. build_qhp() compiles all keyword items from index entries and > reference labels in one location. > OK I will give a deeper look to the code in next days > There is also a block of commented code that displays the IDs that > would have conflicted with previous IDs. Interestingly, it seems there > are a lot of places in the sphinx code that generate non-unique > reference labels. I'm not sure if this was an oversight or if I'm not > quite grasping the full picture (the latter is more likely). > > > Luke > You are right. I'm going to study a little better builders similar to the qthelp one (htmlhelp end epub) to see if they have a better handling of index and cross referencing. best regards -- Antonio Valentino -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
