Make built-in documentation independent from wiki

[flo@…]

I noticed that there are various links to the built-in documentation pages in the wiki. We use the wiki for internal documentation and development matters and therefore anonymous users don't have rights to access it. So it would be nice if the online documentation pages would be independant from the wiki, because anonymous users can't view them if they have no right to access the wiki and it is annoying if you have those links to is everywhere, which lead you (as an anonymous user) to pages which say "Access denied". A quick workaround would be to only display the links if you have rights to access the wiki.

Best regards

Florian Lahr

[Felix Collins]

I propose that the Trac guide and associated "default" wiki pages are converted at release time (of Trac) to static HTML that is shipped with a trac install and served out alongside the other static Trac content (ie the templates). The conversion should be an automatic part of the build process and the converter should be built into the Trac code itself, perhaps as part of trac-admin. A manual conversion would of course also be possible from the web interface too with a ui allowing the selection of a subset of pages to convert.

A side effect of this of course would be to add a feature to Trac to allow HTML documentation generation from the wiki! What a great feature.

[simon-code@…]

For me, the built-in Help problem is actually two issues:

1. The wiki pages that "clutter" project documentation (as descibed above)
2. The TracGuide help link in metanavigation that is hard-coded into the WikiModule (see trunk/trac/wiki/web_ui.py@2976#L46​).

It should be possible to remove/disable this help link without changing Trac source.

Proper handling of Help should be a priority for planned multi-project support.

[trac@…]

I like the above comments, but I have another (maybe easier to implement) idea. Create a configuration parameter or inter-trac parameter such that when the Wiki web_ui is disabled or you don't want to have Trac documentation in the project itself, that help references are replaced with an external URL. By external URL, I mean the URL of a different Trac project (sort of an implied inter-Trac link).

Of course, using this capability to link to trac.edgewall.org would be a poor use, but you could set up a separate/dummy documentation project with only the Trac documentation in read-only mode (and turn off everything except the wiki in that project).

[Matthew Good]

Replying to trac@digidescorp.com:

I like the above comments, but I have another (maybe easier to implement) idea. Create a configuration parameter or inter-trac parameter such that when the Wiki web_ui is disabled or you don't want to have Trac documentation in the project itself, that help references are replaced with an external URL. By external URL, I mean the URL of a different Trac project (sort of an implied inter-Trac link).

The problem with linking to another project for the docs is that every time someone clicks one of the help links they'll now be browsing another project, which would lead to a lot of confusion.

[trac@…]

Replying to mgood:

The problem with linking to another project for the docs is that every time someone clicks one of the help links they'll now be browsing another project, which would lead to a lot of confusion.

Yes, that's why I thought it should be configured as read-only and wiki-only.

Looks like I may want something like this soon. Upper management here feels that having both the corporate wiki and Trac's wiki is too confusing, so we're probably going to turn off Trac's wiki. The problem is, if we actually turn it off, then we will end up with about 90 Trac environments without help pages.

[Christian Boos]

[OT] Reply to trac@digidescorp.com:

… we will end up with about 90 Trac environments …

Wow, that must be a world record ;)

[Matthew Good]

Replying to trac@digidescorp.com:

Looks like I may want something like this soon. Upper management here feels that having both the corporate wiki and Trac's wiki is too confusing, so we're probably going to turn off Trac's wiki. The problem is, if we actually turn it off, then we will end up with about 90 Trac environments without help pages.

Well, I wouldn't think you'd need to completely disable the Trac Wiki. Just turn off editing and make something else the default page. That way it's still on for browsing the Trac docs, but you don't need to use it for your own documentation.

[trac@…]

Yes, I suppose disabling editing would be fine. I'll have to change the permissions scheme, though (right now, everyone's an administrator, just for simplicity).

[Christian Boos]

href.wiki links in the templates could be replace with href.help ones, and that specific handler could belong to a "mini" wiki module, which only gives view access to the help related pages. Therefore, the TracGuide would remain available even in environments having the wiki module disabled or for users not having the WIKI_VIEW permission.

[simon-code@…]

Replying to cboos:

href.wiki links in the templates could be replace with href.help ones, and that specific handler could belong to a "mini" wiki module, which only gives view access to the help related pages. Therefore, the TracGuide would remain available even in environments having the wiki module disabled or for users not having the WIKI_VIEW permission.

This is sort of what I have done for my hosting setup. However, I have taken it a bit further with my [help:...] links in that I source in pages for Help both from a local and remote project. The advantage is that each individual project does not need to be cluttered with various Trac and other Help pages in all shapes and sizes.

I needed to resort to various trickery to get this to work well. However, on my mod_python setup it is snappy and performing well, and all Help navigation stays local within the project (Help module) regardless of where the page originally came from.

I use some custom options for the module in my global trac.ini - kind of like:

[help]
help_pages_project = /path/to/other/project/or/empty/if/only/local
global_help_pages = HelpUser, HelpAdmin, HowTo, FAQ
local_help_pages = HelpProject

However, since I wrote this 1,5 years ago I have learned much more about Trac, and would certainly do it slightly different now. My idea now would be to have a Help module that is extensible through an interface - a HelpPageProvider kind of thing. Using your idea the local wiki would then be one (default) provider to a general Help module providing main matching, navigation and so on (kind of like Admin).

A provider would need to do a number of things:

• Provide page list, headings and extra information for building menus and navigation
• Provide match logic for links
• Do actual render and return output

I render remote help pages in the remote project (a trade-off on issues that arise as no ideal way to do this today) such as all links rendered as missing locally - the cost is that I have to "massage" the content a little by redoing any URL pointing to a Help page.

However, a Help module might remedy that - and certainly if I had used [help:...] links instead of wiki links in my remote wiki. Then it would just be a matter of checking the help index to verify if it exists or not, and even remote pages could be rendered locally.

Using this extensible idea, one could also imagine a Help provider that fetches pages from t.e.o and caches locally in a separate table - weekly updates, Admin interface or whatever. Anything would be possible using the excellent plugin architecture you have.

I'll gladly help if I can if/when the time comes to look at these issues.

I'll attach a screenshot of my Help module next - mostly to illustrate real-life usage, and hopefully provide some inspiration :-)

[simon-code@…]

Traceback trying to upload screenshot? Anything wrong at t.e.o.?

Forgot to mention one more problem I have had: Lots of hardcoded links in templates to help pages that I have had to replace with my own. This should also be a bit more generalised as it assumes local wiki page with the same name exists. Link to a help module with matching would also fix that in code.

[Christian Boos]

Replying to simon-code@bvnetwork.no:

Traceback trying to upload screenshot? Anything wrong at t.e.o.?

Yes, #4087, please send the picture to me and I'll attach it.

About the help module, the idea of using help: TracLinks within help pages certainly makes sense. The ability to fetch pages from "somewhere else" is also interesting, but I think this should probably be limited to "importing" them from a specific project, in case of multiple project support (see #130 and Global or Shared Resources?).

[Christian Boos]

The screenshot simon was talking about, uploaded by me because of #4087…

[Christian Boos]

See also #3386 for an alternative idea regarding the help links.

[anonymous]

Replying to cboos:

See also #3386 for an alternative idea regarding the help links.

That works. Could it be used to introduce project-specific namespaces to the wiki as well (as part of multi-project support?)

[Christian Boos]

Also, we need to figure out what to do with the default set of wiki pages at install time (#1626):

• copy them anyway, even if they're not used
• [inherit] wiki_default_dir = ...?

[osimons]

This is the essence of TracDev/Proposals/NewHelp, so I'll grab ownership of this one.

[osimons]

#8097 closed as duplicate - or at least very closely related as it mentions that help links won't work if wiki is disabled.

[Ryan J Ollos]

Replying to flo@…:

A quick workaround would be to only display the links if you have rights to access the wiki.

I have similar requirements to yours. Another quick workaround that would satisfy my needs would be to move the /wiki/Trac* and /wiki/Wiki* documentation pages to /wiki/Help/*. I'd then use the TracFineGrainedPermissions scheme to allow anonymous users to access /wiki/Help/*, but no other part of the wiki.

[Remy Blank]

Will this be done in time for 0.12? If not, please move out to (probably) next-major-0.1X.

[Remy Blank]

#7430 was closed as a duplicate, and requested that changes to the documentation should not pollute the timeline.

[Christian Boos]

The newhelp stuff wasn't worked on since quite some time, so I think it's a bit too late for 0.12.

However, the suggestion from comment:22 is simple enough, and would already be quite useful. Another very simple complementary idea would be to have the help link going to href.help() have a WikiHelp component handle the /help URLs and delegate the processing to the WikiModule (adding the Help/ prefix).

That could be a good transition to a new system and in the meantime would make it possible to write simple plugins doing other kind of help system delegation.

[Christian Boos]

simon, would you be OK with the suggestion in above? (comment:26)

[osimons]

As a transitional step, I think that would work. However, I'd like for us to provide a help: link resolver as a separate component (that can be replaced by those needing different resolving) and consistently use href.help() for links in templates, and help:WikiFormatting-style link syntax for all help linking. Then it matters less where the content is actually found.

Too bad we won't make a feature for providing localized documentation to go along with the rest of the localization for 0.12 release, but hey… It does not seem too realistic.

[osimons]

Sorry, cboos - seems I just read comment:22 before commenting, and forgot to read the rest of your comment:26. I see that we agree on the transitional details though :-)

[Ryan Ollos <ryano@…>]

Potentially related issue would be moving InterMapTxt#PrefixDefinitions out of the help section since it is really a configuration section. I'm not sure what the best place to relocate it would be. However, one might like to control whether one can edit the prefix definitions independent of editing the help pages. This might be deserving of a ticket itself, as a follow on issue to this ticket.

[Ryan Ollos <ryano@…>]

Replying to Ryan Ollos <ryano@…>:

Potentially related issue would be moving InterMapTxt#PrefixDefinitions …

On further inspection, it looks like this might not necessarily be considered part of the help section, so perhaps just leave it at its current location and not move to help.

[Christian Boos]

Postponing again.

[Ryan Ollos <ryano@…>]

Replying to cboos:

That could be a good transition to a new system and in the meantime would make it possible to write simple plugins doing other kind of help system delegation.

I'm not sure exactly what you mean here, but I quoted because it could be related to the following comment.

Something I've been thinking about is, it would be really nice if there was a way that plug-ins could add to the Trac documentation in a standard way so that the documentation appears in the User Guide section of TracGuide. Perhaps there would be a heading below the The Ticket Subsystem section titled Extensions and a plugin could provide a page that is automatically inserted into that index on installation.

Perhaps that is something to consider within the scope of this ticket?

[Christian Boos]

Replying to Ryan Ollos <ryano@…>:

… Perhaps that is something to consider within the scope of this ticket?

It is already, see osimons' proposal TracDev/Proposals/NewHelp#Implementation.

[Christian Boos]

Replying to anonymous:

Replying to cboos:

See also #3386 for an alternative idea regarding the help links.

That works. Could it be used to introduce project-specific namespaces to the wiki as well (as part of multi-project support?)

Exactly ;-) But that's OT here (see #3021).

Still #3386 will be a first step for making built-in documentation independent from wiki.

[Eduard <alexandrul.ct@…>]

Please take a look at #10595

I have removed the hardcoded references for the Help/Guide, Index, and Start Page links and put the existing values as the defaults for help_page, index_page, and start_page options in the [wiki] section.

Next step would be to split the Help/Guide link, and maybe add a guide_href option that would accept an intertrac formatted value that could point either to an internal page or to a clean Trac environment (or even ​http://trac.edgewall.org).