All of that would have been so much easier had IBM stuck with using an extendable markup language such as DCF/BookMaster/BookManager or LaTeX.
-- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 עַם יִשְׂרָאֵל חַי נֵ֣צַח יִשְׂרָאֵ֔ל לֹ֥א יְשַׁקֵּ֖ר ________________________________________ From: IBM Mainframe Assembler List <ASSEMBLER-LIST@LISTSERV.UGA.EDU> on behalf of Jonathan Scott <00001b5498fc732f-dmarc-requ...@listserv.uga.edu> Sent: Friday, June 20, 2025 4:58 AM To: ASSEMBLER-LIST@LISTSERV.UGA.EDU <ASSEMBLER-LIST@LISTSERV.UGA.EDU> Subject: Re: z17 PoO External Message: Use Caution 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
