Menu
▾
▴
omnihelp-devs — OmniHelp development discussion list
You can subscribe to this list here.
| 2003 |
Jan
(3) |
Feb
|
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|---|
|
From: Glenn M. <gle...@vo...> - 2003-01-20 15:14:03
|
Hi Jeremy, With your permission, I would like to help enhance and extend OmniHelp. = The first task that I would like to tackle is the "doxyenation" of the = javascript code. I'll add doxygen comment blocks to the functions. Then = I'll use open-source doxygen to extract the prototypes and comments into = a mini-HTML system. When I'm finished (by the end of next weekend), how should I progress in = making this source (and even the generated mini-HTML system) available = as the basis? I'm a bit ignorant has to the checkout, check-in hand-off = procedure so that this open-source effort can grow. I feel that this effort is worthwhile to me to help me understand the = code. Once I'm done, the mini-HTML system will be provide useful = overviews and information on what the javascript does, so that when = others want to modify the code, they can know where to localize their = efforts. I'm not going to be able to complete this doxygenation effort. I can put = in the templates and describe things that I know. You know the code = better. The mechanism will be in place for you and others to document = what the code does and have it be exposed. Yes, this will initially make two separate mini-HTML systems: the one = generated from Mif2Go and your FM document, and the one generated from = Doxygen. However, it will provide me with a working target to tailor and enhance = my other open-source tools which will eventually allow OmniHelp to grow = and support modular components. After all, OmniHelp needs to be in a = position where people can use it in real-world documentation projects, = whereby the documentation suite is composed of multiple manuals and/or = mini-HTML systems. In preparation, last weekend I downloaded a perl environment and doxygen = executable for my Windows XP box at home. Is this proposed involvement acceptable? Glenn Maxey Technical Writer Voyant Technologies, Inc. 1765 West 121st Avenue Westminster, CO 80234-2301 Tel. +1 303.223.5164 Fax. +1 303.223.5275 gle...@vo... |
|
From: Glenn M. <gle...@vo...> - 2003-01-16 17:57:01
|
Hi Jeremy, You've seen the Perl tools that I developed which wrap around the = standard HTML output generated by Mif2Go (WWP) and Doxygen. At some point in the 3 month future, I could easily make some = enhancements to those tools to support the .ohc and .ohk formats. At the = same time, I'll look into the .ohk format to see how it could be = enhanced to be more flexible. I realize that such Perl tools requires a perl development environment, = but such environments are free and easy to come by. The code is = transparent and doesn't need to be compiled. These tools would only be = run in preparation for getting the input files ready for OmniHelp; they = wouldn't be called by OmniHelp. Unfortunately, I've got several projects on my plate at the moment with = deadlines looming. Later, Glenn |
|
From: Glenn M. <gle...@vo...> - 2003-01-16 17:29:31
|
Hi Jeremy, I've been looking over OmniHelp. Great job. I haven't finished my = evaluation, but the one thing that stuck out to me was the format of the = .ohk file. The documentations mentions that there are two formats. One format has a = level followed by text that is exposed to the reader. The other format has a level followed by a URL, followed by "the index = of the Contents entry in tocItems, whose title is used for the link = text." Elsewhere you present the example from an .ohk: [1,"title, HTML attribute"], [2,"for images, assigning via marker"], >>[3,"ae999029.htm#Xae1003420",3], --[2,"ae999029.htm#Xae1003420",1], The related .ohc: [2,"9 Using markers for HTML markup","htmlmark.htm#Xae1015982"], [3,"9.1 Working with FrameMaker markers","ae999397.htm#Xae1015686"], >>[3,"9.2 Adding custom marker types","ae999029.htm#Xae999029"], Hence, what you'll see in the index for the >> item will be "9.2 Adding = custom marker types". What you'll see for the -- item will be "9 Using = markers for HTML markup".=20 Unfortunately, this points out two limitations the way I see it. [1] You are tieing the .ohk too tightly with the .ohc. The index number = is going to be very hard to maintain. How does it know what should be = referenced in modular systems? What if I have tools to build a master = .ohc from several .ohc files? [2] What if I don't want the text from the .ohc displayed in my index? = This example is actually a really good one, because I probably would not = want that title "9.2 Adding custom marker types" in my index without = editing.=20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= An extension to this format that would be easier to generate and = maintain is that the third item in the .ohk entry is the plain text that = I want displayed in the index. [2,"ae999029.htm#Xae1003420","adding customer markers"] [2,"ae999029.htm#Xae1003420","customer markers"] [2,"ae999029.htm#Xae1003420","markers"] [1,"ae999029.htm#Xae1003420","Dude, so you want some customer makers"] I mean, in the case of FM index tokens, they can be placed into the = output as mid-topic <a name=3D..> targets. For that matter, they can = even have a value attribute that contains the contents of the FM index = token (just to keep the source reference complete), such as <a = name=3D"Xae1003420" value=3D"customer markers"></a>. Thanks to your = help, I already have mif2go doing this. If the source reference is complete within each owning HTML file, the = .ohk could be generated at any point in time for whatever set of HTML = files exists.=20 [*] It would NOT have to rely on titles from the TOC, but could have the = entries come directly from the author as intended as index tokens. [*] It would NOT have to be re-exported from the source (FM), but could = actually recombine and re-use existing HTML (like from two manuals.) Which leads me to another question. Who does the ordering and = alphebetization of the index? Is the .ohk supposed to be in order from = the onset, or does the OmniHelp do that later? =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D I'll be looking into this more, as well as the underlying HTML and = javascript. If I find ways to contribute and improve the deliverables, = I'll do the work and submit the work. Thanks for doing getting this project more than off the ground. Glenn |
