[ros-dev] Implementing a help system

[Karim Liman-Tinguiri]

I'm not yet sure of the license I'll choose for my work (which will of
course be open-sourced), but I think I'll make it GPL since it is not
linked, neither statically nor dynamically, to Microsoft copyrighted
libraries (at least a React-OS version exists).

I also think I'd better start off from scratch the winhelp rather than
"recycling" Wine's one since, on the one hand, the .hlp format isn't
very complicated, and on the other hand, the Wine's version must be
written and optimized for Unix-based system; therefore starting from
scratch (I could have a look at Wine's version and take some code
snippets though) would allow us to have a winhelp fully optimized and
designed for ReactOS.

But, once again, a help system without help files isn't of much use.
The library on reactos.com is very incomplete and has a long way to
go. Furthermore, lot of documentation will have to be written from
scratch. Therefore I recommend we coordinate efforts along with
documentalists in order to have a set of .hlp files ready to use as
soon as the help system is ready. Documentation should be written from
the most common, general components such as the ReactOS explorer to
the obscure command-line tools considering the user has no experience
on windows OS (we want ReactOS to be independent); in that order since
most people who use the latter (command-line tools in general) are
more experienced. As I stated earlier, the .hlp format is relatively
simple so we can expect a running alpha .hlp file viewer in less than
2 ~ 3 weeks.

Also, please note Casper that I deliberately chose not to invest into
the new .chm help format (Microsoft HTML Help) since it is specific to
the newer windows versions and doesn't fit in ReactOS's focus of
having an OpenSource Windows NT 4-compatible OS.

Lastly, ReactOS lacks the binaries compress.exe, expand.exe, and
lzexpand.dll. Since the .hlp files are partially packed with the LZW
algorithm, these binaries are necessary to allow opening of these
file. Now that this algorithm has legally reached the end of its
copyright, it can be freely implemented in ReactOS. Its source file is
available at (amongst other places)
http://www.moon-soft.com/program/FORMAT/windows/Hlp.htm. There only
remains to code a very thin wrapper (file open, feed buffer to
algorithm, file close, console output) that mimics the compress.exe,
expand.exe and lzexpand.dll executables' behaviour. Note that I could
implement them directly in the help client but it'd be cleaner to have
it dynamically linked to these files.

I've already began the coding of the .hlp file viewer. It's in very
early stage. Soon enough I hope, depending on my free time, a
pre-alpha release should come. I've also had a look at
http://svn.reactos.com/viewcvs/trunk/rosdocs/ and I was happy to find
out that DocBook format was already set up... but not used. A tool
chain still has to be set up to automatically convert docbooks to
.hlp.

As a summary, we basically need in the very near future:
- LZW algorithm implementation (compress.exe, expand.exe and
lzexpand.dll) : this should be very easy to get done since 95 % of the
source is freely available.
- Lots of documentation to be written and compiled as .hlp. We could
(should) set up a mailing list for documentalists.

PS: I would also like, if possible, to have an access to the #ros-dev
channel on FreeNode to take part in developper talk.


On Mon, 21 Feb 2005 21:26:10 +0100, Casper Hornstrup <ch at csh-consult.dk> wrote:
> 
> 
> > -----Original Message-----
> > From: ros-dev-bounces at reactos.com
> > [mailto:ros-dev-bounces at reactos.com] On Behalf Of Karim Liman-Tinguiri
> > Sent: 21. februar 2005 16:09
> > To: ros-dev at reactos.com
> > Subject: [ros-dev] Implementing a help system
> >
> > Hello,
> >
> > Therefore I am wondering if there is a current project started to code
> > one. If not, I plan to code an open-source version of the winhlp32.exe
> > file located in the system folder able to open and show windows .hlp
> > files. The goal is to have a winhlp32.exe that runs and behaves
> > exactly like (or very close to) that of the Microsoft copyrighted
> > winhlp32.exe. It should therefore be able to serve existing windows
> > apps with a help server without any modification to the program. I've
> > verified the dependencies of winhlp32.exe; all of them have already
> > been implemented in ReactOS, so it should not be a big deal to code it
> > from scratch. Despite the fact that the .hlp file format isn't
> > officially documented, it has already been reverse engineered and its
> > documentation can be found on the web (2). However, if there already
> > is a help support project up and running, I intend to join it.
> 
> Winhelp is obviously needed for compatibility, but a MS Help clone would
> be better to use for ReactOS online documentation due to its flexibility.
> There is a GPL CHM library at: http://freshmeat.net/projects/chmlib/.
> 
> > Besides, as soon as this is ready (why not before ?), I advise we
> > convert all documentation on the reactos.com's library (and all
> > further documentation) to the DocBook (SGML)
> > format: it has the advantage of being easily converted on-the-fly to
> > pdf, html, post-script and many others. A tool chain to convert it to
> > .hlp will however have to be created (meanwhile we can use the
> > standard tools for compiling .hlp files).
> 
> See http://svn.reactos.com/viewcvs/trunk/rosdocs/
> 
> Casper
> 
>