Building Gnumeric docs on Win32

[Adrian Custer <acuster nature berkeley edu>]

Hey All,

Here's an explanation for how to build the gnumeric docs on win32
platforms, posted here for posterity. This strategy requires:

        -- a working 'nix build platform
        -- xsltproc and xmllint tools (substitutes should work fine)
        -- the stylesheets from norm's distro
                (these are assumed to be in the path listed in the
                gnumeric-driver.xsl file in the CVS repository:
                /usr/share/sgml/docbook/xsl-stylesheets-1.65.1/htmlhelp/htmlhelp.xsl)
        -- the icons from yelp
        -- 'nix zip
        -- windows 
        -- unzip on windows
        -- the Microsoft HTML builder

For the last of these, several projects are aiming to be replacements.
Check in on these to see if they have progressed.

        chmlib
        libmspack
        HTMLHelpMaker
        chmtools

For useful info, see:

        Deploying HTML Help by Robert Chandler
        http://www.workwrite.com/helpthink/zip/deploy-chandler.html
        (or .zip)
        
        msdn.microsoft.com/library/tools/htmlhelp/chm/hhlstart.htm
        The help compiler and files are in Hcwsetup.exe
        
        www.helpmaster.com/ links to tools like mkindex.exe
        
        mups.org/htmlhelpcenter/
        
        helpware.net/htmlhelp/hh_info.htm
        helpware.net/htmlhelp/basics.htm
        helpware.net/FAR/far-faq.htm
        

Overview of the process:
-----------------------
        Docbook --> ....chm

Docbook must become:
        A project file .hhp
        The Topic files .html (the major content)
        The Content files .hhc (the table of contents)
        The Index files .hhk (for the index search)
        [TODO: use mkindex]
        The Images and others .png

Then this slew must be compiled into a .chm file.
on windows: hhc file.hhp (requires hh.exe & hha.dll in path) 

(Somehow the windows gnumeric.exe must call the help system, but that's
for the developers to figure out.)



How To Build Gnumeric Docs on Win32:
-----------------------------------

Prep:

        cd some_working_dir
        cvs -z3 co gnumeric
        cd gnumeric/doc/C/
        mkdir htmlhelpdocs
        mkdir htmlhelpdocs-cleaned

Validate:

        xmllint --valid --no-out gnumeric.xml

Make html files:

        cd htmlhelpdocs
        xsltproc -o . ../gnumeric-driver.xsl ../gnumeric.xml
        xmllint --valid --noout --html *.html
        bash
          for f in *.html; \
            do xmllint --format --html $f \ 
              > ../htmlhelpdocs-cleaned/$f; \
          done
        exit

Place all files together and bundle:

        cd ../htmlhelpdocs-cleaned/
        (for the paranoid) xmllint --valid --noout --html *.html
        cp ../htmlhelpdocs/*.hh* .
        cp -R ../figures .
        cp -R /usr/share/yelp/icons figures/.
        zip -r gnmHHdoc.zip *

Transfer zip file to windows:

Unzip file:
        (ususally can right click on the file)

Open in HTML Workshop
        Double click on .hhp --> launches the workshop

Compile
        one of the buttons causes the project to be compiled
        and generates the .chm file

Test
        double click on gnumeric.chm


Hope that helps you all,

ciao,
adrian



-- 
Adrian Custer <acuster nature berkeley edu>