DESCRIPTION

Change LTTng help plugin generation 

The generation of the LTTng help plugin used to be done from 
a wiki stored at Eclipse.org. This wiki matches the latest 
delivered source code. However, when developing new features 
or updating existing features it is required to document the 
new or updated feature. But this cannot be done on the wiki
web page. This causes that the writing of documentation 
is often postponed before the next official release.

This commit changes the way the help plugin is build. The source
wiki text file along with the relevant images as part of are 
stored as part of the git repository. The build-helper.xml was 
updated to build the help from the local wiki file. This allows 
the designer to update the documentation along with the feature
implementation. Note, that the local wiki can be edited with the 
MyLyn wiki text editor.

When a release to open source is done and these new or updated 
feature are part of it, then the open source wiki at Eclipse.org
needs to be aligned to the wiki which is stored in the git 
repository.

How to know if someone updated the open source wiki independent to
the one in the git repository? For that, the build-helper.xml file
also builds the help plugin files as it used to be done. After a 
Ant build with the build-helper.xml file the changes will show 
as changes in the git repository. Knowing what changed, it can be 
easily transfered to the local wiki stored in git.

Note that the legacy help files were removed from the repository.

Change-Id: Iba1b140a78a5e4aaa2b2a7ffbdb0cf852f9b6030


COMMENTS

author: Brenden Conley
date: 2012-11-21 20:57:05.000000000

Patch Set 1:

Build Started https://hudson.eclipse.org/sandbox/job/linuxtools/628/ 

-------------------------------------
author: Brenden Conley
date: 2012-11-21 21:14:16.000000000

Patch Set 1: Verified

Build Successful 

https://hudson.eclipse.org/sandbox/job/linuxtools/628/ : SUCCESS

-------------------------------------
author: Braxton Mccarthy
date: 2012-11-23 20:26:12.000000000

Patch Set 1: I would prefer that you didn't submit this

The .html files in doc/ should not be committed, they are all generated from User-Guide.mediawiki (except notice.html, but we could fold it into the .mediawiki too).

The whole Linux_Tools_Project/ directory should not be committed either, it all gets pulled from the website (from what I understand). However it seems the top-level directory itself needs to exist, or Ant complains.

There is a problem with the User-Guide.html that gets pulled from the website, one <div> in the middle of <p> tags that confuses the parser, but that's a problem with the wiki's file, not with this patch.

Finally, would it be possible to have the pictures in doc/ to be in the images/ sub-directory, like is the case with the website files?

I can give a hand working on this, just lemme know!

-------------------------------------
author: Ricky Reeves
date: 2012-11-23 20:57:29.000000000

Patch Set 1:

Thanks for your comments. Here are my answers:
>The .html files in doc/ should not be committed, they are >all generated from User-Guide.mediawiki (except >notice.html, but we could fold it into the .mediawiki too).
The HTML files need to be committed because they need to be created prior the build of the plugin/features. The generation of the help plug-in cannot be integrated in maven since you need a Eclipse instance with MyLyn installed to run the buildhelper.xml. Besides the HTML files are not big. 

>The whole Linux_Tools_Project/ directory should not be >committed either, it all gets pulled from the website >(from what I understand). However it seems the top-level >directory itself needs to exist, or Ant complains.
I kept that to be able to spot any changes that someone did on the web page. If the files are not under version control, we cannot find out if and what was changed.

>There is a problem with the User-Guide.html that gets >pulled from the website, one <div> in the middle of <p> >tags that confuses the parser, but that's a problem with >the wiki's file, not with this patch.
This is shortcoming of the the generation process.There is no way to fix that. We always have had to fix that manually after each help generation.

> Finally, would it be possible to have the pictures in 
> doc/ to be in the images/ sub-directory, like is the case > with the website files?
Unfortunately, the generation from local file is not flexible enough to do that. I have tried.

-------------------------------------
author: Braxton Mccarthy
date: 2012-11-23 21:39:30.000000000

Patch Set 1:

> doc/*.html files
It seems to be possible to build wikitext stuff in maven, at least according to:
http://www.eclipse.org/forums/index.php/m/797823/
But it also seem to be a lot of work, perhaps for now it'd be fine to just commit the generated files... although that's not a super-clean solution, just like the CTF grammar files. ;)

> committing Linux_Tools_Project/
Ok, that makes sense. Although I would only commit the .html files and not the images.

IMO in an ideal world we would only build the user guide from git, and tell people to send patches to fix typos. It seems a bit redundant to have the two methods.

> pictures in doc/images/
If I add the directory path in the wiki links (ie, [[Image:images/filename.png]] ) it seems to work fine. Both in the MediaWiki preview and in the generated HTML files. It would also keep the same structure as the files on the website. Am I missing someting? If not, I can do this change in a separate patch after this one is pushed.

-------------------------------------
