Jonathan,
it is nice to see that others did fight the same windmills as I did. In
2014 or so I worked on REXXes to get at least the two chapters with
general instructions to HTML
with
-- one column only (who prints the 2240 pages anyway?)
-- each instruction separate and not a single part for a group of
instructions. Look for example at the ADD (with AR, AGR, AGFR, ARK,
AGRK, A, AY, AG, AGF, plus AFI, AGFI, AHIK, AGHIK, ASI, AGSI in one part
of the text and this text tries to describe each and all of these 15
different flavors)
- I failed -
The column stuff was easy (albeit tricky) but the generation of text for
each of the instructions from the "made for all" text failed and brought
the project to a grinding halt- to many different ways to describe the
variations for each of the "sub-instruction".PoP text is good for humans
but tricky for programs to interpret and create good results. What was
good for ADD already failed at the AND - To me it felt like to many
different humans (as opposed to a machine doing it) created the text.
Martin
Am 20.06.25 um 10:58 schrieb Jonathan Scott:
If the editor of Principles of Operation (presumably Bruce) doesn't follow this
mailing list, I'm sure Dan Greiner can let him know about any errors.
There is however a complication that any corrections normally only go in the
next edition, which will be for the next hardware level in a few years.
As previously mentioned on this list, back in 2013, while working on HLASM for IBM, I
tried to create a static HTML web version of PoO which could be accessed and updated more
easily. However, the existing source was only designed to be used for the PDF and the
(non-IBM) proprietary tools used to maintain it were unfortunately incapable of
extracting enough HTML information to create a web version systematically (for example,
the extracted output contains no information about which borders are present around a
table cell, and fails to distinguish superscripts and subscripts from normal text). I
wrote an experimental tool containing a lot of REXX and CMS Pipelines code to try to
recognize patterns and create equivalent HTML, and I made a prototype web version
available internally within IBM. It gave excellent results for some areas which mostly
used very systematic markup, such as reference topics describing general instructions,
but the amount of work needed to get it anywhere near 100% right was clearly infeasible.
The architects already had more than enough work to do, so they did not want to feel
under pressure to produce an official version, and management at the time therefore did
not want the prototype to be made available externally. Some IBMers found it very
useful, and before I retired, there were signs that the architects might be persuaded to
let the HLASM team make the web PoO available externally "as is" with all its
glitches. However, it also required quite a bit of work to recreate it for each new
hardware level, which I used to do myself, so I don't know whether that will happen.
I also wrote a REXX and CMS Pipelines tool to extract the instruction set
information from HLASM itself, combine it with instruction names extracted from
the text of the z/Architecture Reference Summary and create a systematic table
of all supported instructions showing the range of OPTABLE levels for each one.
I later had the instruction table added as an appendix to the HLASM
Programmer's Guide. It hasn't yet been updated for z17 but I hope the team
will fix that soon. I also used that table (in combination with information
extracted from the text of appendix B of PoO) as the basis of a Javascript tool
to look up any instruction by mnemonic, jumping to the relevant topic in the
prototype web PoO (or in the HLASM Language Reference for assembler
instructions, and I also supported common z/OS macros which were redirected to
the z/OS IBM Docs).
And back in 2013 I also created an HLASM instruction set overview HTML
document, which contains tables of all instruction mnemonics supported by HLASM
grouped hierarchically by category. It shows what combinations of operands and
functions are supported, with tooltips showing the instruction name, syntax and
OPTABLE ranges, where the mnemonic background is also colour-coded on a rainbow
as a quick indicator of how recently it was added. The IBM internal version of
that document had links from each mnemonic to the relevant topic in the
prototype web PoO but the document could also be generated without external
links. Again, it required a bit of work to update it for each new hardware
level but it was very useful for looking up what instructions were available at
a given level, and I had been hoping to make it available externally, but I
never had the time to find a way past the administrative complications.
Perhaps my successors may find a way. The table of all supported instructions
which is now available in the HLASM Programmer's Guide was originally generated
for that document.
Jonathan Scott
-----Original Message-----
From: IBM Mainframe Assembler List<ASSEMBLER-LIST@LISTSERV.UGA.EDU> On Behalf
Of Paul Gilmartin
Sent: 19 June 2025 22:29
To:ASSEMBLER-LIST@LISTSERV.UGA.EDU
Subject: Re: z17 PoO
On 6/19/25 12:28, Abe Kornelis wrote:
I agree with Shmuel - the procedure for submitting comments seems so easy.
But you have to find the page on the IBM site which is not that easy
when working from a downloaded PDF.
...
The Abstracts are all N/A in order to prevent readers' submitting Feedbacks.
--
gil
