Sunday, May 01, 2005

Good Web Help for PHP?

I have been searching a lot for a decent help system for PHP applications. The idea is something similar to the Microsoft HTML Help (CHM) or Web help generated by Macromedia Robohelp. I'd be interested to hear more from people about what their thoughts are regarding this topic.

In general, such a system should be a set of XSLT stylesheets to compile DocBook help into HTML and PHP, so it is easily deployable over the web. It should be able to compile any existing DocBook documentation without modifying it (for example the PHP manual).

The following is a detailed list of requirements for such a system:

1. It should be server-based, so it can contain PHP scripts.
This is necessary primarily, to implement fully-functional search capabilities, and in addition, to reduce the number of files generated for keyword index entries (because it'd be possible to generate keyword index as a PHP array rather then generating a separate HTML document for every index keyword)

2. It should look a lot like Microsoft's HTML help, for example MSDN docs.
It should have the same basic layout (text in the right frame; context/index/search/favorites tabs in the left frame). Also it should open in a new window, so the user can browse it independently from the main application.

3. It should be able to group more than one DocBook document, each one containing its own ... tags, into one documentation tree exposing each book as a subroot.

4. It should separate a whole document into a number of pages, analogously to the chunked HTML output of the standard DocBook XSLT stylesheet.

5. It should have five navigation buttons (next page, previous page, forward, back, root). The next/previous buttons should work analogously to chunked HTML created by XSLT of the DocBook XSLT distribution; forward and back buttons should simply implement browser's forward and back functions applied only to the main text frame.

6. The left frame's contents tab should contain a navigation tree like in HTML Help preferably in DHTML.

7. The Index tab of the left frame should consist of two subframes: the first (upper) one containing a list of index keywords, by clicking on a keyword a request would be sent to the server; the server would look up a number of links using a mapping file, probably best implemented as a PHP array, and would display all links in the lower frame. Clicking on these links would open the appropriate page in the main text frame.

8. The search tab should have a search textbox together with standard search options: search whole words/phrase/any word. It also should contain a combobox for selecting a section, when the help consists of more than one DocBook. Search would be done server-side using an index, generated by the transformation (and probably some post-transformation processing).

9. The possiblity to store bookmarks (in a permanent cookie) would be nice.

10. It should be possible to create context-sensitive help by linking to specific places inside the document from the application. For this, the id attribute of DocBook tags should be used.
When the help is then called, it should accept as a parameter suchan id and open at the according place.

11. Also it would be nice to have a back linking mechanism: when the user clicks on a link in the help, a specific page opens in the calling application. This can be implemented for example using JavaScript callbacks with a specific link ID. Probably more of a nice-to-have than a critical features :)

12. Differently from the standard XSLT stylesheet the generated help should heavily use CSS stylesheets. This would allow users to customize the appearance of the help without modifying XSLT styles.

OK that's quite a long and thorough feature request list. I'd be happy to hear feedback from people of what their thoughts are. It probably wouldn't take more than 3 weeks or so for something like this to be implemented.