Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>  
>  >
>  > Yes, I thought of something like simply parsing over the html output from
> epydoc, bringing the htmls into adequate form (removing frames
> ....).
>
> The .chm writer would omit to write frames-related stuff, as the html writer
>
> does with the --no-frames option (as should have done, actually... fixed in 
> r1550). I wouldn't perform a post-processing of epydoc pages: instead i'd 
> subclass the current HTMLWriter to directly let it create the required
> files.
> What other difference should be taken into account to create html files to be
> chm-compiled? Remember that much customization can be performed using an 
> appropriate css stylesheet.
>   

That's a clean option, if if not too difficult to implement. Difference 
sould be only to get
rid of the browse frames 'cos all browsing is handled by the chm window.


>  > I already have a some modules at hand. One to generate all the required
> files for micros html workshop compiler (needs rework, ugly code!) and
> one for
>  > parsing and bringing into shape html files. All not heavily tested,
> though working.
>
> Can i have a sample of how the hhc, hhk, hhp file should appear? You may use
> the tracker item above to post the files, to keep all the chm stuff together
> (i marked the item as to be done for 3.1 release; now i'm mostly focused on 
> functional testing for the 3.0 release).
>   

I'll prepair some samle files and post them as soon as I find the time.

> A question: can the index and table of content contain actually different 
> indexes? We can generate the class index and the modules indexes, and we can
> generate an identifiers and a term definitions tables of contents: it would be
> nice if all could fit into the compiled help without having to mix classes 
> with modules and terms with identifiers. It's not a great issue anyway,
> mostly   curious...
>   

No, I don't think this possible. HelpWorkshop supports plugging together
multiple chms but the index is generated as one from all chms.
But one can freely name keywords as they appear in the index or if it
comes to that, provide some meta keywords.


>  > Think I could throw this together in a few weeks to a working alpha. But
> the thing I can not do is test it on linux. AFAIK, Wine supports micros
> compiler
>  > and it would be nice to support this.
>
> I've never run it on Wine (actually, i've never run it at all :) but it 
> doesn't seem an issue to run the compiler once you have the project [1]. We 
> should add a --chm-compiler option to tell epydoc the command line to run;
> the
> files generation could be performed even if the compiler were not available or
> couldn't run on the current platform anyway.
>
>   

No problem to generate the required files without actually compiling.
Commandline ....you actually feed the compiler  an *.ini file like 
project file with
all required data. Things like:

- where is the index file
- where is the contents file
- title of the window
- buttons to show
- a dozen more.....

so a single chm option might be a bit uncomfortable. But I have to take 
a closer look at it.



> [1]
> http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcmp7.asp
>
>  > And ....of course, I'd welcome any help or advice on implementation
> details.
>
> Just for a pointer, the indexes are created in the epydoc.docwriters.html.py
>
> module, in the HTMLWriter.write() method. I think the informations required to
> create chm indexes are the same gathered here: i guess it's a matter of 
> creating pages with different format and names for the indexes to be passed
> to
> the compiler. The class should be refactored so that a ChmWriter could be 
> easily subclassed from it, but apart from changing the implementation of the
> indexes pages writing, i think there not much stuff to be done.
>
> Probably the list of files to be included in the project should be created 
> reading back from the disk every file which has been written in the output 
> directory: this way also images (which may be more difficult to track: think
> about images generated by docutils directives such as the math formulas we are
> everybody expecting...) may be included in the chm project.
>   

Images (and css and javascripts) are handled by micros compiler. As long as
they are linked correctly they are automatically included in the 
project. So that's
easier aswell to handle on an already dumped tree ++ you have to know 
wheter
a folder contains subitems or not. So there is a some lookahead necessary.


It all boils down to two methods

def has_intersting_subitems(item):
    # yes, give it a folder icon
    # no, give it a file icon

def get_index_page(items):
    # locate the item to be displayed when clicking on a folder in the tree


to get a contents tree like this:

<chm>
    <item name="root" local='root.html' icon="folder">
        <item name="page1" local="root/page1.html"/>
        <item name="page2" local="root/page2.html"/>
    </item>
</chm>

other names in the contents file ...Html not Xml, but it should give the 
idea.

But I don't know what epydoc offers to handle this. Or if it there is need
to process intime rather than processing an already dumped tree.



> Finally, adding a --chm action to the command line and the hook for the chm 
> compiler should be done in the cli.py module.
>
> Regards,
>
>   

Jürgen