search

SDL-Hercules-390 / hyperion

The SDL Hercules 4.x Hyperion version of the System/370, ESA/390, and z/Architecture Emulator
Other
240 stars 90 forks source link

Hyperion auxiliary applications could use a short description what they're made for #563

Closed PoC-dev closed 1 year ago

PoC-dev commented 1 year ago

I'm writing about Hyperion 4.4.1 on Linux, but this might apply to newer versions, and other OS.

I have been searching for a way to handle DASD tasks offline, so I typed dasd<tab><tab> and started each application being listed.

Sometimes, it's just not possible to guess what a given application is made for. Example: dasdisup.

HHC02499I Hercules utility dasdisup - IEHIOSUP - version 4.4.1.0-SDL
HHC01414I (C) Copyright 1999-2022 by Roger Bowler, Jan Jaeger, and others
HHC01417I ** The SoftDevLabs version of Hercules **
HHC01415I Build date: Mar  3 2022 at 17:38:30
HHC02463I Usage: dasdisup [-option [-option ... ]] ckdfile [sf=sfile]  [...]
HHC02463I   ckdfile:      input dasd image file
HHC02463I   sfile:        optional dasd image shadow file
HHC02463I options:
HHC02463I   -hdr          show column headers
HHC02463I   -dsnl[=n]     restrict dsname width
HHC02463I   -info         show F1 info
HHC02463I   -caldt        calendar date format
HHC02463I   -refdt        show last-reference date
HHC02463I   -expdt        show expiry date
HHC02463I   -yroffs[=n]   year offset
HHC02463I Note:
HHC02463I   Multiple images can be processed in the same run,
HHC02463I   but options must be specified ahead of each image.

I know the version and who made it. I know the usage and valid options. But I don't know what it is supposed to do.

Now, I could try to locate the online HTML documentation and find the section about dasdisup. Cumbersome.

I suggest to add one or more lines like:

HHC0xxxxI This utility performs OS/360 IEHIOSUP function: Adjusting XCTL tables' TTR pointers.
HHC0xxxxI See <insert link to online documentation here>.

Another (additional) possibility would be the creation of man pages. Useless for Windows as target platform, but useful for Linux and other Unix-like platforms, to ease finding documentation and possible helpful applications. Unix commands supporting man documentation:

I offer to work on creating man pages with low pwriority if this is is seen beneficial to the project. I probably could use some help to expand the build system so manpages get installed properly, though. Opinions, please?

Fish-Git commented 1 year ago

Now, I could try to locate the online HTML documentation and find the section about dasdisup. Cumbersome.

Doing a grep of our .html files is "cumbersome"?

What about downloading, opening, navigating to page 60 of our existing "Operations and Utilities Guide" PDF documentation? Is that also "cumbersome"?   ;-)

Please don't misunderstand! I think your suggestion has merit. Providing the URL of where a utility's documentation can be found is a good idea and certainly has merit.

As far as providing yet another slightly more descriptive description of the utility's purpose however, not so much IMO. We already identify the "purpose/description" of each utility in the form of a "long name" of the utility. Now granted, I'll admit some of them aren't very descriptive (such as the one you mentioned, dasdisup), but most of the others are descriptive enough IMO. e.g.:

HHC02499I Hercules utility dasdinit - DASD image file creation program - version 4.6.0.10919-SDL-DEV-gb7f3bf2e
HHC02499I Hercules utility dasdload - Build DASD from TSO XMIT files - version 4.6.0.10919-SDL-DEV-gb7f3bf2e
HHC02499I Hercules utility dasdls - List DASD image file contents - version 4.6.0.10919-SDL-DEV-gb7f3bf2e
HHC02499I Hercules utility hetget - Extract Files from AWS, HET or FAKETAPE - version 4.6.0.10919-SDL-DEV-gb7f3bf2e
...etc...

Changing (expanding) the description provided in message HHC02499I would certainly not be hard to do, but I'm not sure what a more descriptive value would be! So I'm a little reluctant to change that.

But adding a new message with a URL pointing to the documentation for the utility certainly sounds like it might be a useful, worthwhile enhancement IMO.

I'll add it to the list.

As far as providing man pages for each of them goes, I personally don't feel that's necessary either, given that each of them should already be documented somewhere in our existing .html files and/or the PDF manuals.

Others may of course feel differently.

PoC-dev commented 1 year ago

Doing a grep of our .html files is "cumbersome"?

Yes. The HTML documentation I must first locate, then grep, then use some browser to be able to read it in a meaningful way.

A link to the documentation relieves me from searching the correct directory but needs an active internet connection.

A local man page doesn't need all of that and is partly indexed to make apropos work.

What about downloading, opening, navigating to page 60 of our existing "Operations and Utilities Guide" PDF documentation? Is that also "cumbersome"? ;-)

Compared to a local man page, yes.

Please don't misunderstand!

Same here. I don't want to troll or do nitpicking, and I recognize that you aren't a "Linux guy", as you often put it. My personal issue is that if I take too long to finish a secondary task ("locate documentation, read documentation") it might happen that I meanwhile forget what I wanted to look up in said documentation. The less effort is needed to view documentation, the more it is actually used. At least my me. :-)

As far as providing yet another slightly more descriptive description of the utility's purpose however, not so much IMO. We already identify the "purpose/descriotion" of each utility in the form of a "long name" of the utility. Now granted, I'll admit some of them aren't very descriptive (such as the one you mentioned, dasdisup), but most of the others are descriptive enough IMO. e.g.:

I admit, I inadvertently picked the worst example (dasdisup). :-)

Providing the URL of where a utility's documentation can be found is a good idea and certainly has merit.

Thanks! One drawback of URLs is that they can be volatile. IBM is a very good example, having provided URLs in their programs or documentation being invalid after a web presence redesign.

Changing (expanding) the description provided in message HHC02499I would certainly not be hard to do, but I'm not sure what a more descriptive value would be!

I can have a look and provide examples, if you wish.

As far as providing man pages for each of them goes, I personally don't feel that's necessary either, given that each of them should already be documented somewhere in our existing .html files and/or the PDF manuals.

Yes, but man pages are readily available, right from the command line, effortless to view and (ideally) provide some usage examples for the uninitiated. No need to leave the terminal emulator one is currently using to fiddle around with Hercules'ish tasks anyway. It's effortless. Even though the effort to copy-paste an URL in your browser is already not much absolute effort, it's relatively more, compared to man pages. My point is not that there is no documentation at all. My point is that viewing the full documentation should be effortless.

Also, there are existing solutions about having one input file, and being able to generate HTML and roff-man output, amongst others. So there would be no need to take care of the same information in different formats.

Fish-Git commented 1 year ago

Changing (expanding) the description provided in message HHC02499I would certainly not be hard to do, but I'm not sure what a more descriptive value would be!

I can have a look and provide examples, if you wish.

Thanks. I'd appreciate that. That would help a lot.

Fish-Git commented 1 year ago

@PoC-dev

(Ping!)  How's it going?

Fish-Git commented 1 year ago

Closing due to lack of response.