Helpfile system for FPC IDE (and with Lazarus in mind) ---------------------- Why CHM ? - Main reasons: - library/tool availability. Not only Drewski's lib, but also chmlib, kchmviewer,xchm,gnorpm, and various helpware and keywords tools - Single file help model. This is way easier crossplatform than a loose collection of one file-per-topic with all little filesystem details to handle platform dependently. - Basically a custom HTML archive. Can even be extracted. (Microsoft supports this with the "enhanced decompilation support" pragma in projects even) - Currently all active helpformats of MS are in maintenance mode or not available to 3rd party developers - hlp legacy not even shipped anymore Vista+ - chm (=htmlhelp1) supported on all clients, tools (MS) available but old - htmlhelp2 targeted at IDEs, but tools not open afaik. - htmlhelp3 part of VS2010 (12?). - Vista assitance Little known, on Vista+, but not open (restricted) - htmlhelp2/3 only supported by VS, and not generically loaded onto client windowses. Delphi after 2005/6 also used htmlhelp2. special licenses, no open tools. - CHM has good indexing suitable for IDE Help (help combined from multiple CHM sources with the F1 key) - Linux helpsystems are fragmented over desktopsuites, relatively slow and moving targets. (every major version, redone), and typically not single file. - OS X help system status unknown - it is only a backend of current documentation systems. CHM extinction is painful since it will void the investments in the CHM generation and loading, but since html seems to remain the base rendered format of nearly any help system, parts can probably be reused. More importantly, the core documentation systems (fpdoc, latex, latex->html conversions) are not that dependant on the choice for chm. - Conceptually not too weird/alien, and legacy formats like tph can be probably converted. Cache ----- Microsoft seems to cache the index for multiple merged CHMs in a CHW file too: Index file automatically generated when multiple Compiled HTML Help (.CHM) files are merged together; creates the Help table of contents and contains references to each CHM file. The CHW file must be rebuilt each time any of the merged CHM files are updated; otherwise, the indexes will not merge correctly and the table of contents will not be valid; CHW files can be compressed using the KeyCHW program. I pried apart the binary index of the virtualstringtree chm files, and found that you can resolve topic titles very quickly (an directly) from them. This is great for diambiguation dialogues. (do you want keyword VAR in "var parameters" or VAR in "variable declarations" ?) I still have to compare this to the text index. Maybe it is also as hidden attribute in the text unit. URLS * http://www.nongnu.org/chmspec/latest/Internal.html#WWKeywordLinks * http://www.russotto.net/chm/chmformat.html * http://www.helpware.net/htmlhelp/ * http://www.helpware.net/htmlhelp/how_to_merge_ctx2.htm * http://www.helpware.net/htmlhelp/how_to_merge.htm * http://www.helpware.net/htmlhelp/how_to_context.htm * http://www.helpware.net/htmlhelp/how_to_whatsthis.htm * http://helpware.net/delphi/index.html * http://helpware.net/htmlhelp/hh_info.htm (mostly about versioning but * has something on .col collections) * http://helpware.net/htmlhelp/hh_kbase.htm list of KB articles on chm, with several howtos * http://freenet-homepage.de/mawin/ (hlp,dead) * http://msdn.microsoft.com/en-us/library/ms644670%28VS.85%29.aspx * http://msdn.microsoft.com/en-us/library/2bk8zwb3(VS.80).aspx * http://msdn.microsoft.com/en-us/library/ms670091%28VS.85%29.aspx * http://www.hypertexas.com/RHTutor/merger.htm * http://www.codeproject.com/KB/cs/htmlhelp.aspx about help formats: * http://www.helpmvp.com/docs-1/helpbasics * http://www.mshelpwiki.com/wiki/tiki-index.php?page=HTMLHelpArticles examples: * http://www.help-info.de/en/Visual_Basic/vb.htm * http://www.help-info.de/en/Help_Info_HTMLHelp/hh_context-id.htm * http://www.911cd.net/forums/lofiversion/index.php/t22749.html (javascript in toc?) * A tutorial: (PDF, examples) http://frogleg.mvps.org/helptechnologies/htmlhelp/hhtutorials.html#char_hhw mshelp2: From http://helpware.net/FAR/help/msh2_primer.htm it looks like mshelp2 was a reasonably nice system too, but without client existance it is hard. The url above has a comparison list of winhelp..htmlhelp2 kchmviewer code: -------------- // Check whether the search tables are present if ( ResolveObject("/#TOPICS", &m_chmTOPICS) && ResolveObject("/#STRINGS", &m_chmSTRINGS) && ResolveObject("/#URLTBL", &m_chmURLTBL) && ResolveObject("/#URLSTR", &m_chmURLSTR) ) { m_lookupTablesValid = true; fillTopicsUrlMap(); } else m_lookupTablesValid = false; if ( m_lookupTablesValid && ResolveObject ("/$FIftiMain", &m_chmFIftiMain) ) m_searchAvailable = true; else m_searchAvailable = false; // Some CHM files have toc and index files, but do not set the name // properly. // Some heuristics here. if ( m_topicsFile.isEmpty() && hasFile( "/toc.hhc" ) ) m_topicsFile = "/toc.hhc"; if ( m_indexFile.isEmpty() && hasFile( "/index.hhk" ) ) m_indexFile = "/index.hhk"; if ( !m_topicsFile.isEmpty() || ( m_lookupTablesValid && hasFile( "/#TOCIDX" ) ) ) m_tocAvailable = true; else m_tocAvailable = false; if ( !m_indexFile.isEmpty() || ( m_lookupTablesValid && hasFile( "/$WWKeywordLinks/BTree" ) ) ) m_indexAvailable = true; else m_indexAvailable = false; return true; From http://www.flipcode.com/archives/Integrating_DirectX_8_Into_MSDN.shtml The CHM files are compiled HTML files (called "chums") and the CHI files are the index files for each associated CHM file. In your language-specific directory, you'll also see a msdnvs98.CHW file, a msdnvs98.CHQ file and a msdnvs98.COL file. The CHW file is the combined index file (i.e. when you open up the index pane under MSDN.) This is a binary file. The CHQ file is the index file used for word searches (i.e. when you open up the search pane under MSDN.) This is a binary file. The COL file describes what you'll find in the table of contents. This is an XML file. Windows decompiler/compiler (3rd party, free?) http://www.keyworks.net/keytools.htm --------------------------- The difference between .chi and .chw is not entirely clear to me. Both seem to be combined indexes. .CHW seems to miss #URTBL and #URLSTR files needed for binary operation. But if we use .chi, what do we need .chw for ? (.chw is older?) --------------------------- binary indexes binary indexes ought to be faster, more compact and are required for merged chms. keyword links are also only possible in binary files? (???) Also, the keywords are UCS-2 (unicode), and the topic title is accessable via the index without loading the topic file itself. The only disadvantage to my best current knowledge is that they must be ordered according to whatever comparing algorithm hh.exe help (or your own search algorithm if you forfeit windows merged CHM compatibility) uses. For now, I suggest to explore merged files, and see how they work in practice. --------------------------- ALinks Alinks are a kind of label. In the help text you make a link to an alink (how?) and you can specify elsewhere (/$WWAssociativeLinks/) to which topics the alink resolve. This is mainly usefull for usage over multiple CHM files, because the separate stores can easily be merged. Example of usage was mainly see also information with procedures. For instance if you have a list of a certain kind of string routines (e.g. routines/classes that split strings into part), you can define such label for them. If then later multiple chm files contain such string routines, when the see also label is clicked, it will pop up with a list of such items over all registered CHMs. The trick is that the external registration ($WWAssocia..) can be quickly merged runtime over multiple files. Like the binary index, the combined alinks index is btree indexed and cached in a .CHW. KLinks is the same thing, and essentially the binary representation of the index. How to create alink in workshop: http://www.fast-help.com/WebsiteHelp/index.html?ALinkSearch alink format (1.4 sdk) http://msdn.microsoft.com/en-us/library/ms644643%28VS.85%29.aspx - http://www.cabeweb.de/html/tddownload.htm#HHelp Hier geben Sie den Namen für den A-Link ein. Mehrere Namen werden jeweils durch Semikolon abgetrennt. Nach dem gleichen Schema werden in den anderen .htm Dateien A-Link Namen eingegeben. Folgender Quelltext wird dadurch der .htm-Datei hinzugefügt: Command value gibt an, dass es sich um einen A-Link handelt. Mit Komma wird "MENU" abgetrennt, wenn der Link als Popup-Fenster erscheinen soll. Button value gibt zwischen den Anführungszeichen den Buttontext an. Ohne Eintrag entsteht ein kleiner Button ohne Text. Item1 value gibt den Namen der Hilfedatei an, kann leer bleiben. Item2 value legt den A-Link Namen fest, nach dem gesucht werden soll. Dieser Name steht im Header unter den Stichworten für den Index, allerdings mit folgender Notation: ---------------------- aliases/contextids CHM has the ability to define (numeric?) context ID's that are then mapped to topic by the chm's indexes. This makes CHM file versioning easier, since there is then an abstraction layer between topic as known in the application and topic/topic-filename as known in the CHM. There is also a textual "alias" involved. I'm not sure if this is usable outside the chm file yet. (this is probably an alink, see above) (seeing the #IVB files where they are stored they are not) Already implement in package it seems, chmwriter.addcontext() -------------- whatsthis CHM also has a more rarely used function that allows to get specific help for a button by clicking a question mark first, and then the button. As said it is rarely used since a management challenge. Lazarus' support: http://www.lazarus.freepascal.org/index.php?topic=7710.0 http://www.lazarus.freepascal.org/index.php?topic=7614.0 Lazarus "IDE" help: The problem is that the IDE help is in some wiki format, which is not available as an archive. There is a tool wikihelp in lazarus-ccr http://wiki.ullihome.de/index.php/WikiHelp-Download/de sample projects ------------------ http://www.cabeweb.de/html/tddownload.htm#HHelp Detail points ------------------ The follow link: http://www.help-guide.de/hh_beachten.htm seems to indicate that the MS html compiler harvests and <ht> tags. For <title> it says it is only needed to take care when option "auto sync" is on. (auto index ?) popup comments --------------- see http://www.help-info.de/en/Help_Info_HTMLHelp/hh_context-id.htm http://helpware.net/FAR/help/dlg_hhpedit_sec.htm for .hhp syntax and extra tab ------------ http://www.help-info.de/en/Help_Info_HTMLHelp/hh_chm_add_glossary_tab.htm .js scripts to make (a)links easier? + chm links. ------------------ http://www.cabeweb.de/html/tddownload.htm samples --------- MSDN allows samples to be saved, and it seems to be possible 3rd party too (just less generally documented) see http://obones.free.fr/CHMSamples.htm #Windows options:4 The MSDN menu is added by adding 0x10000 to the Navigation Pane Style parameter. Remember, this is hexadecimal math, so if this is position is somehow 0x90000 to begin with and you add 0x10000, it becomes 0xA0000. Of course, all the other characters remain the same. button field: Use the following values to add or delete any of the buttons by hand. These values are from htmlhelp.h: 0x 2 Hide/Show 0x 4 Back 0x 8 Forward 0x 10 Stop 0x 20 Refresh 0x 40 Home 0x 80 Forward 0x 100 Back 0x 200 Notes 0x 400 Contents 0x 800 Sync 0x 1000 Options 0x 2000 Print 0x 4000 Index 0x 8000 Search 0x 10000 History 0x 20000 Favorites 0x 40000 Jump 1 0x 80000 Jump 2 0x100000 Zoom 0x200000 TOC Next 0x400000 TOC Prev Note: If you implement the TOC Next and TOC Prev buttons, make sure you also flag the HHP file to create a binary TOC. If you don't, the TOC Next and TOC Prev buttons will appear as disabled. http://msdn.microsoft.com/en-us/library/ms644660%28v=VS.85%29.aspx http://msdn.microsoft.com/en-us/library/ms644661%28v=VS.85%29.aspx explanation about how to autogenerate toc: http://www.help-info.de/download/chm_example_files/HH_HTML-Headlines/01_Einleitung.htm http://www.help-info.de/download/chm_example_files/HH_HTML-Headlines/01_Einleitung.htm#top autogenerate index? http://www.sagehill.net/docbookxsl/HtmlHelp.html glossary: http://www.help-info.de/en/Help_Info_HTMLHelp/hh_chm_add_glossary_tab.htm fpc discussions: - http://www.lazarus.freepascal.org/index.php/topic,19394.0/topicseen.html modifying HH_WINTYPE structure via api http://stackoverflow.com/questions/15887213/disable-print-button-in-htmlhelp