Ref: Your note of Mon, 25 Sep 2017 01:12:55 +0100 Melvyn Maltz wrote: > And while I'm on the subject, does anyone remember that a few > months ago I wanted the PoOPS ripped apart and reconstructed so > that every single instruction had a page to itself with links ?
It's not for want of trying. The problem is the sheer size of the document and the fact that it is conditionally generated from a repository containing a much larger set of documents, the primary purpose of which is for the IBM architects and engineers to design and implement the architecture, and which have for many years been written only to be formatted in the existing way as two-column printed or PDF documents. Back in December 2012, I discussed improvement possibilities with Dan Greiner and he sent me an "HTML" exported version of PoO from which I constructed an IBM internal "proof of concept" static web version of the whole book (at the zEC12 level) with a separate page for each topic (except if there were multiple instructions followed by a common description, it included all of the instruction-only topics on the same page as the common description). One could go straight to a given instruction either via hyperlinks from tables in Appendix B, or using a front-end menu system which used a JavaScript program generated from Appendix B. As a collection of static web pages, it didn't have any built-in search, but it had the same index as the PDF version, hyperlinked to the referenced topics. I had many problems with the generated "HTML", many of which were not the fault of FrameMaker. For example, markup that appears identical on the page can be defined in many different ways in the source, using combinations of named styles, or direct formatting instructions such as underscore. Also, the "HTML" did not include any indication of which borders were present or absent on a table cell, and in some cases the source used complex patterns of table cells with selected borders present to draw diagrams. It was therefore necessary to use "intelligent" logic to try to deduce which borders should be present from the context, which was exceedingly messy in places, and provably impossible in others. It took me several weeks to get to what I considered an acceptable quality for usability, at least for a "proof of concept". And much of the work consisted of writing a program (in REXX and CMS Pipelines) that made many hundreds of specific adjustments to the source, where many of those adjustments would have to be reworked for any updated version. The "proof of concept" was totally successful as a demonstration of the level of usability that could be achieved, and even now, five years later, it is still a useful IBM internal resource. However, it also demonstrated that the amount of work that would be needed to convert the book to a professional-quality web format was enormous, and would probably require migrating much of the architecture documentation repository to a new format (and retraining all the users of it). It would certainly not be at all feasible at present to provide an officially supported web version (correcting formatting errors and building new versions promptly for each new release of the PDF version). However, I personally felt that the "proof of concept" web version was a very useful resource, even if far from perfect, so I am continuing to investigate possibilities for making something similar available "as is", for example via a Tools and Toys site. Management might be uneasy that doing this would create pressure on the Architecture group to provide an official version, but I think that the clear value of making an unofficial version available to our customers (with appropriate disclaimers) would be well worth some unease. Back in 2013, I also created a related document, the "HLASM Instruction Set Overview", which provides summary tables of all instructions (again as of zEC12) grouped by category showing which combinations of operands and functions are supported, using different colours to show which instructions were available for each machine type. There is a somewhat better chance that I might be able to make that available externally in some way, especially as I am now the HLASM team leader (following the retirement of Sharuff Morsa back in June). Remember that it's always much easier for us to make things happen for customers if customers are on record as actually asking for them. Jonathan Scott HLASM team IBM Hursley, UK
