Issue 1737: Compiler-readable code (java-rtf) Source: (, ) Nature: Uncategorized Issue Severity: Summary: Summary: PLEASE PLEASE PLEASE resist the temptation to include consolidated Java source code in .PDF files. At least 3 reasons exist: - EVERY publication of the consolidated org.omg.* hierachy so far has contained code that, even before inclusion in the PDF, simply could not have compiled (void functions returning values, non-void functions failing to do so, etc.). Errors of this nature arise through having an editor have to maintain two seperate copies of the code. The need to apply changes twice (to compiler readable and to .PDF) all but guarantees that errors will creep in, particularly given that only the non-.PDF version can be machine checked. Resolution: closed issue Revised Text: Actions taken: July 27, 1998: received issue June 4, 1999: closed issue Discussion: End of Annotations:===== Return-Path: Sender: raz@arrakis.com.au Date: Mon, 27 Jul 1998 09:42:37 -0300 From: Roland Turner Organization: - To: java-rtf@omg.org Subject: IDL-Java issues I'm a little embarrassed to be posting these so late. I've been meaning to clean these up and check their status first for some time, but the opportunity doesn't appear to have presented itself. Now it's probably too late to make use of them this time around, but here they are for future consideration. However, the first item should be considered this time around if at all possible. Thanks. - Raz --- Compiler-readable code my favourite hobby horse :-) PLEASE PLEASE PLEASE resist the temptation to include consolidated Java source code in .PDF files. At least 3 reasons exist: - EVERY publication of the consolidated org.omg.* hierachy so far has contained code that, even before inclusion in the PDF, simply could not have compiled (void functions returning values, non-void functions failing to do so, etc.). Errors of this nature arise through having an editor have to maintain two seperate copies of the code. The need to apply changes twice (to compiler readable and to .PDF) all but guarantees that errors will creep in, particularly given that only the non-.PDF version can be machine checked. - At least one .PDF version to date has been hyphenated! This does wonders for Java compilers. These two situations mean that the authoritative copy of the code (that in the .PDF) contains errors which make it unimplementable and require that each ORB implementor "correct" the standard, hopefully in the right way, in order to create a product. This seems undesirable. The third problem is this: - PDF is becoming widespread, but tools to cleanly extract source code are not. Getting the source back out of the PDF is hard work and yields source with almost no useful formatting. This is particularly frustrating when it is then neccesary to debug the broken code that was in the PDF in the first place. The solution that I propose is that the mapping be published in two seperate files. The RTF shares a compiler-readable form of the source for checking anyway, why not use the compiler-checked form of the code as the authoritative code for the standard? If you absolutely must include the source in the .PDF, then a note to the effect that this version is not authoritative and that the authoritative, compiler-readable form can be found at a specified URL is perhaps in order.