|
|
Post by Stefan on Jul 3, 2020 12:36:27 GMT -5
Hi Guys,
Don't get me wrong, I think the SPFLite documentation is VERY comprehensive. That said, here are some minor things that caught my eye over time...
(Please bear in mind that these comments are based on documentation shipped with v20151)
Main SPFLite HELP document
(1) Is the Index Tab needed, given it refers to just 4, rather random, entries: New keyword (File Manager)
New keyword 1 (Excluded lines) SPFLite (Instances & Configs)
Unexclude (Excluded lines)
(2) There's no support for the 'HELP LINE' primary command. i.e. While 'HELP FIND' primary command jumps into the documentation at the FIND syntax page, HELP LINE is less accommodating.
(3) The various 'KEYMAP' sections mention the 'implied (Enter)' after {line command} and non-[]-bracketed Primary commands, often accompanied by ways of how to suppress them.
While the "suppression technique" is a clue, it isn't until you reach the paragraph about (RestoreCursor) that you learn that 'implied (Enter)' applies ONLY IF the line/primary command is the last element in the key definition. (4a) The main document's Contents Tab - Primary Command access is excellent! It provides direct access to any given command description AND it lists the available commands to help users find which command they may need.
Macro HELP document
(4b) In contrast, the Macros doc doesn't provide direct access to any available functions. Neither the Contents Tab nor the Search Tab provide easy access to specific functions.
I found the most effective way is to start with either 'Function Overview' or 'Function Details' and then page down, or use CTRL+F to search that section. I think a Contents Tab - Functions facility, like the primary command facility referred to in (4a), leading directly to an individual function, would be really useful. I think it would also be helpful if that entry also repeated the FM=YES/NO, EDIT=YES/NO information.
|
|
|
|
Post by George on Jul 4, 2020 16:05:50 GMT -5
Stefan: Yes, the HELP indexing is poor. One problem, for example, in supporting HELP xxxxxx commands, is that the xxxxxx operand has to be translated into the name used in the HELP document. While HelpnDoc does assist in creating an INCLUDE file of equates to be used by the actual HELP command, it's a PITA to try and keep things working.
Like, what abbreviation should be used for "Working with DIFF". Can't be DIFF, that would be used to point at the DIFF primary command. WDIFF? Who would ever think of that?
I looked once at actually creating a real true Index for the HELP file, but it's an enormous effort. You have to first define the structure of the Index, and then slowly go through almost 1000 pages of documentation, highlight the desired keywords, and then specify where, in the Index structure, you'd like it to appear.
It is simply such a labour intensive task to try and make improvements.
George
|
|
|
|
Post by Stefan on Jul 5, 2020 5:08:10 GMT -5
Hi guys,
I wonder if the HELP facility is still the "tool of choice" for this these days. As Robert says, it wasn't really intended for documents of this scale.
I've written various bits of documentation in the dim and distant past (funnily enough including a customised User Guide for TSO & ISPF/PDF when my employer changed everyone from ROSCOE to TSO/ISPF). It was a SCRIPT document (remember General Markup Language GML)? Can't even recall how I got the screenshots into it.
From personal experience, the documentation issued with ooRexx is PDF-based and it works pretty well in terms of finding what you want. I don't know if or how one might allow direct access via the HELP XXXX primary command, but often that isn't necessary. And for new users of the product, a PDF is perhaps more 'sequentially readable' than the structured separation imposed by the current files.
As I said, the main HELP info is pretty good. The Macro document is a little tedious. I wouldn't want you guys taking time to index the doc when you could be fixing or enhancing the product. Maybe I'll have a look at what could be achieved with a PDF. I don't have a PDF Authoring package... yet! :-)
|
|
|
|
Post by George on Jul 5, 2020 10:43:20 GMT -5
HnD does have a global Find/Replace function, but it is painfully slow. I believe HnD basically stores every topic as some kind of compressed (ZIP type) individual file within the main file, which is a sort-of database structure.
So to view a page, it has to fetch and 'un-zip' each page's contents. A global find simply walks through the document, un-zipping a page at a time to perform the find/replace. Painful to watch, and a single search through the main SPFLite document take over 3 minutes on my system. So we don't do THAT very often.
Yes I remember GML, I even remember basic Script before GML (We used to use Waterloo Script). I was very good at it since we had nothing else 'way back', no PDF, no Help files (no PCs). I remember writing an App that displayed formatted (print files) documents on a standard TSO screen (online Help!) It handled all the stuff like Bold, underlined, etc.
Mind you, I also remember writing out documentation and giving it to the typists to enter. I used to hate going back to them with corrections and changes. Gad I'm old!
|
|
|
|
Post by George on Jul 5, 2020 14:02:45 GMT -5
Yes, Hnd has some very annoying problems, I use it because a) it's free (even if it does 'watermark' the output) but b) I've tried several other Help authoring systems via trial downloads and frankly I was not impressed with any of them.
The fact that I can use the same tool to create CHM, PDF and HTML versions is great. And I can even create the SPFLite Web site in Hnd. Again I explored a bunch ow 'Website Builders' to replace HnD for the web site. ICK!!!! I never found one as simple to use.
George
|
|
|
|
Post by Stefan on Jul 6, 2020 8:41:38 GMT -5
Fair enough. I'm not volunteering to rock your boat. And if you need output in various formats, maybe HnD is well suited to author the information.
|
|
