Re: Task list of WebHelp for GSoC 2012

The mentors for webhelp has come up with the following priority feature list to be expected from the possible students for webhelp [1]. If you are eligible to participate, and like to contribute to DocBook, and WebHelp, then join with us. The list provided might look overwhelming at first. For a new user, it always will be. :-) But by the time, it'll be OK. Unless otherwise specified, almost all the tasks expected are moderate. I would classify only one to have a bit of more research involved. The possible students can of course discuss about these and come to an agreement on what needs to be implemented which will match with our objectives, and students current skills plus skills that s/he like to develop.

During the proposal period, only keep your focus on first 5 tasks here and (6) a. Please don't hesitate to ask questions you may have regarding the provided tasks, and DocBook in general. There's still time to discuss and submit a proposal. The proposal deadline is April 6th, 19:00 UTC.

[1] http://docbook.xmlpress.net/tiki-index.php?page=Ideas2012#Webhelp

Provide an example Makefile as an alternative to the ant script

Removal of the dependency on Ant. Make WebHelp build with make, so that people using make and xsltproc can build WebHelp.

This would be a good starter task for the student to get a feel for how thing work.

There might be a sample Makefile to get the implementor of this going, or to give the student some ideas.

Parameterize list of files to exclude from indexing. Currently it's hard coded that we don't index index.html and ix01.html (the legal notice and index topics). It should be smarter and automatically not index the index file even if it's not named ix01.html. Add to the indexer the ability to specify a list of files or file patterns not to index. Currently it does not index index.html or ix01.html, which is generally appropriate, but it should be up to the user to decide.

Search functionality improvements

Add other search options:

Add an option to create webhelp as a webapp using Lucene as the search engine.

Strip quotes from search queries (if a user searches for "foo bar" with quotes, strip the quotes). Currently a quoted search shows no results.

That would be a relatively easy and quick fix, and would add a lot of benefit.

Improve image copying functionality to deal with xincluded content. - This could be blocker for some projects, and it doesn't WYSIWYG IDE friendly. Current image copying feature is very primitive.

This will be a bit of a mindbender for the student, but a good exercise. We'll provide a good demo doc that shows what is needed.

Why issue are we trying to address here? This is more of an issue if you make extensive use of xinclude. Imagine you xinclude some file from some random place on your system and the DocBook content includes a fileref with a relative path to an image. The build system has to copy the image into the webhelp output dir AND adjust the path to the image to it's new home. Ideally this should be robust enough to handle whatever weird and random thing a writer might do. I've implemented a solution for this that could be adapted.

Enhanced configurability, together with improved readability of the code (webhelp.xsl). These issues are somewhat interwoven; being able to make WebHelp more configurable is hard when the code is hard to parse.

Moving the params and gentext strings into the normal place in the xsls. Seems a docbook developer already started doing this.

We'll provide some specific instructions for this stuff on what needs to be done.

EASY Tasks

Remove the "content" folder in WebHelp output (and thus in the template). - Easy

This is fairly easy work. Further, this could be a sub-task under (parameterize list of files to exclude from indexing.)

This could be implemented after (2).

Make it possible to include the document title in the html page's <head><title> without also having the document title appear in the search results summary.

Adding this task here is arguable. Would this be configurable? If not, would everyone regard this an improvement?

Make sure we give an informative message if they come to the page using NoScript or with cookies disabled.

NoScript is all over the place these days, so the informative message could even be "please configure NoScript to allow _javascript_ for this page".

Low Priority

Add autocompletion to the search box (This was suggested by one of the students and is an interesting idea).

This could of lower priority. Shall we keep this to the end? `

If someone dies to implement this, why not, but otherwise it's a "nice to have" item to the largest possible extent. :-)

Make the toc width adjustable (is this even possible?)

It's possible, generally. But should look whether this can be integrated into webhelp design. low prioriy!

Fix some bugs:

Sidebar does not remain collapsed when clicking next/previous

Improve performance in IE 8/9 (remove need for "treat as IE 7 directive")

Adjust titlepage templates so abstract is not shown by default.

=============================

docbook-apps message