Daniel Egger <degger@xxxxxxx> writes: > Am Die, 2003-08-19 um 02.31 schrieb Sven Neumann: > > (...) > >> Actually it was Mitch's idea. Perhaps he should continue to explain it >> then. > > Exactly, why are you bothering me with an example? Here we go (ignoring the rest of the thread)... It all starts with the uglyness of the current implementation. Whenever we specify a help page in the current codebase, we have to write something like: gimp_dialog_new (..., "dialogs/file_new.html", ...); This is absolutely unmaintainable since it spreads the knowledge about where to find help pages across the whole source code. Apart from that, it's simply ugly. Even worse, it's my own fault from pre 1.2 days and I feel like I have to fix that ;) To keep it simple and straightforward, I'd like to replace that with: gimp_dialog_new (..., GIMP_HELP_FILE_NEW, ...); and have these constants defined in one header file. The advantage of this approach is that we keep all available help topics in one place and that the compiler will not like unavailable help topics, so we can't suffer from typos like in the current implementation. The header would look like: #define GIMP_HELP_FILE_NEW "gimp-file-new" #define GIMP_HELP_FILE_OPEN "gimp-file-open" #define GIMP_HELP_IMAGE_FLATTEN "gimp-image-flatten" etc... <implementation-detail> For a smooth transition the first step would be to have: #define GIMP_HELP_FILE_NEW "dialogs/file_new.html" so we can collect needed help items without breaking the current system (which is already broken but still kindof works if you badly symlink aroung) </implementation-detail> That's basically everything that needs to be changed in the core. The help browser however still needs to find the actual help pages so there needs to be a mapping from these string IDs to links of some sort for finding the content (like relative paths or uris to html pages). That mapping would preferably be a XML file like: <gimp-help> <help-item id="gimp-file-new" uri="file/file-new.html" /> <help-item id="gimp-file-open" uri="file/file-open.html" /> <help-item id="gimp-image-flatten" uri="image/image.html#flatten" /> </gimp-help> I don't care about the element names and stuff, it should just be simple enough to keep a GMarkup based parser simple too. How should this XML file be generated? I suggest to simply use the same IDs as section IDs in the XML source so the mapping file can be generated automatically. I also thought about generating the header which defines the help items, but gimp would depend on gimp-help or vice versa then, which is probably a bad idea. Also, manually syncing the gimp's and gimp-help's ID space will make us look at it more often, which can't be bad ;) The generated mapping file would be installed under a defined name (like gimp-help.xml) and the help browser would parse it when it first opens a given help tree. This approach also covers 3rd party plug-ins since they can tell the gimp where their help tree is. The help browser has access to this path and can simply open the gimp-help.xml file from that given help path. All that needs to be done from the help system's side is generating this mapping file and installing it in the top help dir. I will add the header mentioned above tomorrow and start adding items to it, so we can see all needed help items in one place (using the <implementation deatil> approach above). Is this a solution everybody can live with or did I miss something obvious? If it sounds reasonable, we should go ahead, it's not even an awful lot of work (the coding part, not writing the help pages :) ciao, --mitch
