Re: EMC documentation

[Paul <paul.corner-at-tesco.net>]

Hi Ray

On Tuesday 08 January 2002 12:34 am, Ray wrote:

> Great.  I'll get this going soon.  I am almost convinced that Lyx is the
> way to go for the base files.  The editor is trivial and can be included
> with every BDI.  Lyx to DocBook is a good one way intermediary for stuff
> like pdf, ps, rtf and html.

Looks like we have some more packages to add to the BDI CD - I'll trawl 
through my master CDs for the latest versions. Should Lyx and docbook be 
included as part of the developers install or left as optional extras. 
Personally, I favour the latter.

> Openssh is available and I think that we could even create a shell script
> or icon that runs the ssh setup so that the public file is ready for
> sourceforge.

Just some clear and simple to follow instructions should be enough for most 
people. 

> I suppose that we could put a directory under doc and call it doxygen.  It
> would be parallel to the handbook.  I would think that when we freeze the
> sourceforge stuff long enough to make an official release, you could simply
> run doxygen there and generate the same set of files that are generated
> here.

A better idea might be to leave out the doxygen generated files alltogether 
and just have the config file. With the EMC sources changing and being 
expanded, any documents tied in to the code so tightly would need to 
regenerated after even a modest commit. Most users of the handbook would be 
"end users" as opposed to programmers (who would probably have doxygen 
allready installed).
Please do not mistake my intentions, I would be the first to agree that the 
sources need a coherent programmer's reference to the inner workings. Doxygen 
just appears to produce an overwhelming amount of info that is difficult to 
understand.


> The next thing I would like to do is set up a copy of kfm or konquorer to
> popin to the help window of tkemcex with at least a bit of context
> sensitive help.  It can get that info directly from the handbook index
> which we can create with Lyx.

This is easy - If the relevant help is in say, emc_wots_this.html, issue a 
linux command from inside tkemc for:
kfm emc_wots_this.html
And the same for Konqueror. This will tie your GUI to a KDE envionment which 
may not be a good thing for a general release. An html viewer widget in tk 
would be more universal (I've seen one somewhere....).

Regards, Paul.