Edgewall Software

Opened 14 years ago

Closed 14 years ago

#9061 closed enhancement (cantfix)

New Help System

Reported by: carsten.klein@… Owned by:
Priority: normal Milestone:
Component: general Version:
Severity: normal Keywords: newhelp
Cc: carsten.klein@… Branch:
Release Notes:
API Changes:
Internal Changes:


I noticed the effort currently under way to externalize the help pages and guides from the wiki into a separate, non versioned storage. While I think that this would be rather nice, I would like to comment on the proposed solution that can be found under TracDev/Proposals/NewHelp.

The extension point interface is quite ok, but I would like it to be so that the user must not reimplement the wheel twice in respect to the get_help_page_content method:

So I would rather like to the see interface similar to the below

class IHelpProvider(Interface):
    """Extension point interface for components that provide pages
    to the Help system and its related features.

    def get_help_pages_locator():
        """Either returns the resource location and the mimetype of 
        the help pages provided by this, or a generator function 
        that will be called for accessing the page content, which 
        in turn will provide both the content and the mimetype 
        associated with that content."""

    def get_help_pages(locale_id):
        """Returns help pages provided by the plugin as a generator
        of tuples of the form: `(section, title, page_id)` """

That way, the most common implementation, i.e. help pages located in the filesystem (or an egg-archive thereof), can directly be implemented into trac, no need for the user to reimplement it for every extension out there.

The more special cases then would return a callable locator that then in turn would resolve and locate the content and the mimetype of the content. In fact the locator function will behave like the already defined get_help_page_content(page_id, locale_id) method.

Of course, in the future, trac could be adjusted so that it would support multiple different resource locations instead of just the relative-to-the-component-folder location. For example external databases, or, again, pages in the wiki.

This could also make room for yet another extension point, e.g. IHelpLocator or something similar.

Attachments (0)

Change History (2)

comment:1 by anonymous, 14 years ago

Cc: carsten.klein@… added

comment:2 by osimons, 14 years ago

Milestone: 1.0
Resolution: cantfix
Status: newclosed

Hi Carsten, and thanks for your interest in the branch. It is somewhat behind schedule…

Anyway, the proposal is an open proposal, with lots of room for adding comments and feedback and suggestions directly on the wiki page. Add a section with your comments, or inline questions and suggestions as you see fit. Tracking wiki feedback through tickets will not be manageable over time.

The only real restriction for editing proposals is that you should not directly change the details of it or change the APIs and/or decisions made so far by Trac developers. Other than that, feel free to clarify, suggest or approve/disapprove ideas. Your feedback will be merged into some future revised proposal.

Modify Ticket

Change Properties
Set your email in Preferences
as closed The ticket will remain with no owner.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from (none) to the specified user.

Add Comment

E-mail address and name can be saved in the Preferences .
Note: See TracTickets for help on using tickets.